From e33d7a5eed5db6de4fb24ea1d67fe51f7bcd9474 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 13:57:54 +0000 Subject: [PATCH 1/2] feat(api): API tokens v2 (personal + service accounts, scopes) and the /v1 versioned API (E1.3) API tokens - Personal tokens for every member (act as their owner) and service accounts for admins; scopes read / run / admin, closed upwards, enforced per HTTP method by ApiTokenScopeMiddleware and by the role claim (admin scope => admin role, never platform-admin). - Stored as HMAC-SHA256 with a per-token random salt, compared in constant time; legacy unsalted rows still validate. Migration AddApiTokenScopesAndSalt backfills scopes from the old role. - Expiry capped by the platform setting Tenants:ApiTokens:MaxLifetimeDays (default 366). Create / revoke / use / refusal audited (use + refusal at most once per token per 5 minutes, with IP + user agent). Member removal revokes the member's personal tokens before deleting the account. - Self-contained registration: AddApiTokenAuthentication() chains the JWT forward selector; UseApiTokenScopes(). No default-scheme or policy changes. - Settings > API tokens opens to every member (personal tokens); admins also create service accounts and see / revoke every token. /tenants/me reports the auth method and scopes. /v1 - Every module REST route is served under /v1 and at its unversioned path, which is deprecated (Deprecation / Sunset / Link successor-version headers, sunset 2027-05-03) and left out of OpenAPI. SignalR hubs (IProtocolEndpointModule), /mcp and the probes stay unversioned. - OpenAPI document v1 with title, bearer scheme and policy; committed as docs/api/openapi-v1.json and kept in sync by a test. - docs/API.md: versions, auth, scopes, CI example, deprecation policy. VS Code extension: Set / Check / Clear API token (SecretStorage) and Run the pipeline via POST /v1/pipeline. Tests: token lifecycle, scopes, salting, max lifetime, audit, claims; integration on the real Api host (WebApplicationFactory): token auth next to JWT, scope per method, admin route, revoked / expired -> 401, /v1 + deprecated twins with headers, unique endpoint names, hub unversioned, OpenAPI = committed copy. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Twi9jFk8LiG81JBRi6Ddh --- CHANGELOG.md | 16 +- CLAUDE.md | 2 +- Directory.Packages.props | 2 + README.md | 13 +- SECURITY.md | 10 + docs/API.md | 146 + docs/CONFIG.md | 1 + docs/api/openapi-v1.json | 2788 +++++++++++++++++ docs/plans/enterprise-readiness.md | 7 +- docs/security/hardening.md | 10 +- src/AgentOs.Api/ApiDocument.cs | 48 + src/AgentOs.Api/Program.cs | 44 +- .../RemoteAgentModule.cs | 2 +- .../ApiTokenAuthenticationHandler.cs | 143 +- .../ApiTokens/ApiTokenEntity.cs | 18 +- .../ApiTokens/ApiTokenScopes.cs | 97 + .../ApiTokens/ApiTokenService.cs | 309 +- .../Endpoints/TenantEndpoints.cs | 23 +- src/AgentOs.Modules.Tenants/IAuditLog.cs | 6 + src/AgentOs.Modules.Tenants/MemberRemoval.cs | 26 +- ...33906_AddApiTokenScopesAndSalt.Designer.cs | 177 ++ ...20261103133906_AddApiTokenScopesAndSalt.cs | 87 + .../TenantsDbContextModelSnapshot.cs | 29 +- .../Persistence/TenantsDbContext.cs | 7 +- .../Settings/TenantsSettings.cs | 10 + src/AgentOs.Modules.Tenants/TenantsModule.cs | 4 +- .../Http/ApiVersioning.cs | 116 + .../Modularity/IProtocolEndpointModule.cs | 8 + .../Modularity/ModuleLoader.cs | 25 + .../Components/Pages/ApiTokensApp.razor | 98 +- .../Components/Pages/SettingsHub.razor | 2 +- .../Components/Pages/UsersApp.razor | 3 +- src/AgentOs.Web/Services/AppCatalog.cs | 2 +- src/AgentOs.Web/Services/SettingsSearch.cs | 2 +- src/AgentOs.Web/Services/ShellActions.cs | 2 +- .../AgentOsUi/ApiTokensRealAuthTests.cs | 20 +- tests/AgentOs.Tests/AgentOs.Tests.csproj | 3 + .../Api/ApiV1IntegrationTests.cs | 331 ++ tests/AgentOs.Tests/Tenants/ApiTokenTests.cs | 357 ++- .../Tenants/MemberRemovalTests.cs | 35 + .../OpenSignupAndAzureEndpointTests.cs | 2 +- tools/agentos-vscode/README.md | 13 + tools/agentos-vscode/package.json | 11 +- tools/agentos-vscode/src/extension.ts | 105 +- 44 files changed, 4951 insertions(+), 209 deletions(-) create mode 100644 docs/API.md create mode 100644 docs/api/openapi-v1.json create mode 100644 src/AgentOs.Api/ApiDocument.cs create mode 100644 src/AgentOs.Modules.Tenants/ApiTokens/ApiTokenScopes.cs create mode 100644 src/AgentOs.Modules.Tenants/Persistence/Migrations/20261103133906_AddApiTokenScopesAndSalt.Designer.cs create mode 100644 src/AgentOs.Modules.Tenants/Persistence/Migrations/20261103133906_AddApiTokenScopesAndSalt.cs create mode 100644 src/AgentOs.SharedKernel/Http/ApiVersioning.cs create mode 100644 src/AgentOs.SharedKernel/Modularity/IProtocolEndpointModule.cs create mode 100644 tests/AgentOs.Tests/Api/ApiV1IntegrationTests.cs diff --git a/CHANGELOG.md b/CHANGELOG.md index 83ac0dd7..1b48b06b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,12 @@ Everything on `main` before the first tagged release. AgentOS.NET has not shippe and theme, Api, Web and optional Ollama, with the key ring certificate-wrapped and row-level security on by default. CI lints and templates the chart and runs a cold install plus an upgrade on kind. +- **API tokens v2 + `/v1` (E1.3).** Personal API tokens for every member and service accounts for admins, scoped + `read` / `run` / `admin`, salted-HMAC storage, a platform max-lifetime setting + (`Tenants:ApiTokens:MaxLifetimeDays`), use + refusal auditing. The Api serves every route under `/v1` with a + published OpenAPI document ([docs/api/openapi-v1.json](docs/api/openapi-v1.json)) and a + [deprecation policy](docs/API.md#deprecation-policy). The VS Code extension can store a token and start a run. + ### Changed - The dock is the MVP: Home · Board · Insights · Settings; Terminal and Files are Board tabs, and one @@ -79,6 +85,12 @@ Everything on `main` before the first tagged release. AgentOS.NET has not shippe - Sign-in cookies are isolated per instance and a failed OIDC callback restarts sign-in instead of erroring. - Code-scanning (CodeQL) alerts are cleared as they land, with compiler-enforced twins for their classes. +### Deprecated + +- The unversioned Api routes (`/pipeline`, `/runs`, `/tenants/…`, …) — use the same path under `/v1`. They keep + working until at least **2027-05-03** and answer with `Deprecation`, `Sunset` and `Link: rel="successor-version"` + headers ([docs/API.md](docs/API.md#deprecation-policy)). + ### Security - Postgres row-level security on every tenant table ([ADR-0012](docs/adr/0012-postgres-row-level-security.md)). @@ -96,6 +108,8 @@ Everything on `main` before the first tagged release. AgentOS.NET has not shippe ### Migration notes -- None — there is no earlier tagged release to upgrade from. +- None — there is no earlier tagged release to upgrade from. (Pre-release installs: existing API tokens keep working — + the `AddApiTokenScopesAndSalt` migration gives them scopes from their old role and they stay service accounts; + scripts calling the unversioned routes should move to `/v1`.) [Unreleased]: https://github.com/hoangsnowy/AgentOS.NET/commits/main diff --git a/CLAUDE.md b/CLAUDE.md index fb0a92c4..793e9a1a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,7 +65,7 @@ CI: `.github/workflows/ci.yml` runs `restore → build Release → test` on Ubun ## Architecture -Modular monolith. Solution file is **`AgentOs.slnx`** (the .NET 10 XML format). Each module is an `AgentOs.Modules.*` class library that **references `AgentOs.Domain` + `AgentOs.SharedKernel` only**; cross-module references are explicit and minimal (e.g. `Llm → AppConfig`, `Integration → Tools`). Hosts (`Api`, `Web`) reference every module and wire them with one `services.AddModulesFromAssemblies(cfg, …)` call + `await app.Services.InitializeModulesAsync()` + `app.MapModuleEndpoints()` — no per-module wiring in `Program.cs`. +Modular monolith. Solution file is **`AgentOs.slnx`** (the .NET 10 XML format). Each module is an `AgentOs.Modules.*` class library that **references `AgentOs.Domain` + `AgentOs.SharedKernel` only**; cross-module references are explicit and minimal (e.g. `Llm → AppConfig`, `Integration → Tools`). Hosts (`Api`, `Web`) reference every module and wire them with one `services.AddModulesFromAssemblies(cfg, …)` call + `await app.Services.InitializeModulesAsync()` + `app.MapVersionedModuleEndpoints()` (the Api: every module REST route under `/v1` plus its deprecated unversioned twin; SignalR hubs implement `IProtocolEndpointModule` and stay at their own path — see [docs/API.md](docs/API.md)) — no per-module wiring in `Program.cs`. | Project | Role | |---|---| diff --git a/Directory.Packages.props b/Directory.Packages.props index 49b775a8..34c3d751 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -66,6 +66,8 @@ + + + @@ -46,6 +48,7 @@ +