Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,11 @@ 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.
- **Approval policies** (E1.5). Per tenant and per project (Settings › Autopilot › Approvals): a person with the
new **Approver** role (or an admin) approves the plan, opening the pull request, the change and/or the merge on
**Board › Tasks › Approvals** — Approve, or Reject with a reason; who and when are recorded and audited
Expand All @@ -90,6 +95,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)).
Expand Down Expand Up @@ -128,5 +139,7 @@ Everything on `main` before the first tagged release. AgentOS.NET has not shippe
[docs/CONFIG.md](docs/CONFIG.md#set-at-deploy-bootstrap).
- The `approver` realm role (E1.5) is created by the azd post-deploy hook and the Helm realm job; a local realm
imported before it needs the role added through the Keycloak admin API, or its volume dropped.
- Existing API tokens keep working — the `AddApiTokenScopesAndSalt` migration gives them scopes from their old
role and they stay service accounts; scripts calling the unversioned Api routes should move to `/v1`.

[Unreleased]: https://github.com/hoangsnowy/AgentOS.NET/commits/main
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|
Expand Down
19 changes: 12 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -459,19 +459,24 @@ tenant. Settings and keys are stored per `(tenant, key)` and always read for an

## API

Every route requires an authenticated principal unless it is explicitly public (fallback policy): on the
Api that is `/`, `/version`, `/health`, `/alive`, `POST /tenants/register`, `GET /tenants/invitations/preview`,
the runner hub (it authenticates the runner itself) and, outside Production, `/openapi` + `/scalar`. The Api
validates a Keycloak bearer token (RS256 only); the Web uses a cookie session (`/account/login` → OIDC). Both hosts
rate-limit per tenant, per user and per anonymous client (Settings → Platform → Request limits). The complete, always-current list is the **Scalar UI** at `/scalar/v1`.
The most used routes:
Versioned REST under **`/v1`** — the unversioned paths still work but are deprecated (`Deprecation` / `Sunset`
headers, sunset 2027-05-03). Every route requires an authenticated principal unless it is explicitly public
(fallback policy): on the Api that is `/`, `/version`, `/health`, `/alive`, `POST /tenants/register`,
`GET /tenants/invitations/preview` (and their `/v1` twins), the runner hub (it authenticates the runner itself) and,
outside Production, `/openapi` + `/scalar`. The Api takes `Authorization: Bearer` with a Keycloak access token
(people, RS256 only) **or** an AgentOS.NET API token `aos_…` (personal tokens and service accounts, scoped read / run /
admin — Settings → API tokens); the Web uses a cookie session (`/account/login` → OIDC). Both hosts rate-limit per
tenant, per user and per anonymous client (Settings → Platform → Request limits) — a token counts as its tenant and
principal exactly like a JWT. Contract, auth, CI example and deprecation policy: **[docs/API.md](docs/API.md)**;
OpenAPI: [docs/api/openapi-v1.json](docs/api/openapi-v1.json) (live in the **Scalar UI** at `/scalar/v1` outside
Production). The most used routes (all under `/v1`):

| Method | Path | Auth | Description |
|---|---|---|---|
| `POST` | `/pipeline` · `/pipeline/stream` | signed in | Run the full flow (SSE progress on `/stream`) |
| `POST` | `/requirement` · `/code` · `/test` · `/qa` | signed in | Run one agent on its own |
| `GET` | `/runs`, `/runs/{id}` | signed in | Persisted runs |
| `GET` | `/tenants/me` | signed in | Resolved tenant, user, roles |
| `GET` | `/tenants/me` | signed in | Resolved tenant, user, roles (and an API token's scopes) |
| `GET` `POST` | `/tenants`, `/tenants/{id}/members` | Admin | Tenants and members |
| `GET` `POST` `DELETE` | `/settings*` | Admin | Legacy runtime-config endpoint (see CONFIG.md) |
| `POST` | `/llm/test` | signed in | Probe the configured provider with a minimal call |
Expand Down
10 changes: 10 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ When reporting, include: affected component, reproduction steps, and impact.
[docs/SETUP.md](docs/SETUP.md).
- **API auth** is Keycloak OIDC JWT bearer (RS256); tokens are signed by the Keycloak realm key
and validated against its JWKS — rotate the signing key in Keycloak, not in AgentOS.NET.
- **API tokens** (`aos_…`, personal tokens and service accounts) are the machine credential for CI, scripts and the
VS Code extension. Treat one like a password: store it in a CI secret store or VS Code secret storage, never in a
repository; give it the lowest scope that works (`read` < `run` < `admin`) and the shortest expiry; revoke it in
**Settings → API tokens** the moment it may have leaked (effective on the next request). See [docs/API.md](docs/API.md#api-tokens).
- The **remote dev-agent runtime** executes work on a developer machine — treat the pairing
credential as a secret. Remote execution is gated by the `RemoteAgent:AutoApprove` platform setting, which
Production locks off (a gate, not yet a per-run human approval — see the
Expand Down Expand Up @@ -55,6 +59,12 @@ When reporting, include: affected component, reproduction steps, and impact.
- **QA gate before every PR** — a pipeline result becomes a pull request only when QA passed on real model
output (`PrGate`, enforced inside the PR service itself): failed runs, the iteration cap with QA still
failing, and offline canned text are blocked with the reason on the session.
- **API tokens** — shown once, stored only as a salted HMAC-SHA256 (per-token random salt) and compared in constant
time; scoped (`read` = safe methods, `run` = writes, `admin` = the workspace-admin role, never `platform-admin`),
always expiring (capped by the `Tenants:ApiTokens:MaxLifetimeDays` platform setting), revocable, with last use
shown. Create, revoke, use and refusal are audited (use / refusal at most once per token per 5 minutes, with IP and
user agent). Service accounts need a workspace admin; a removed member's personal tokens are revoked before their
account is deleted.
- **Approval policies + repo safety** — per tenant / project, an approver (or admin) approves the plan, the pull
request, the change and/or the merge on Board › Tasks (audited); a gate fails closed — rejected or nobody who can
approve stops the task. AgentOS.NET never opens a pull request from, or merges, the default branch, and refuses a
Expand Down
146 changes: 146 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# AgentOS.NET REST API

The Api host (`src/AgentOs.Api`) serves a versioned REST API, an MCP endpoint at `/mcp`, and the paired-runner
SignalR hub. This page is the contract: how versions work, how to authenticate (people and machines), and what
happens when something is deprecated.

- **Current version:** `v1` — every route is under `/v1/…`.
- **OpenAPI:** [`docs/api/openapi-v1.json`](api/openapi-v1.json) (committed, reviewed with each change) and live at
`/openapi/v1.json` + the Scalar UI at `/scalar/v1` outside Production.

## Versions

| Path | Status | Notes |
|---|---|---|
| `/v1/<route>` | **current** | The contract. Named operations, documented in `openapi-v1.json`. |
| `/<route>` (no version) | **deprecated** since 2026-11-03, sunset **2027-05-03** | The same handlers. Still work; answer with deprecation headers (below). Not in the OpenAPI document. |
| `/`, `/version`, `/health`, `/alive`, `/health/llm` | unversioned | Operational probes — never versioned, never deprecated. |
| `/mcp` | unversioned | MCP (Streamable HTTP) — versioned by the MCP protocol itself. |
| `/hubs/remote-agent` | unversioned | Paired-runner SignalR hub — versioned by its own wire contract. |

Every module's REST routes are mapped through `ModuleLoader.MapVersionedModuleEndpoints`
(`src/AgentOs.SharedKernel/Modularity/ModuleLoader.cs`): once under `/v1` and once at the old path with
`ApiDeprecationMetadata`. A module whose endpoints are a protocol (a SignalR hub) implements
`IProtocolEndpointModule` and is mapped once, at its own path.

### Deprecation headers

A response from a deprecated route carries:

```http
Deprecation: @1793664000
Sunset: Mon, 03 May 2027 00:00:00 GMT
Link: </v1/tenants/me>; rel="successor-version", <https://github.com/hoangsnowy/AgentOS.NET/blob/main/docs/API.md#deprecation-policy>; rel="deprecation"; type="text/html"
```

- `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) — when the route was deprecated (an RFC 9651
date: `@` + Unix seconds).
- `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) — the earliest date it may stop working.
- `Link rel="successor-version"` — the route to call instead; `rel="deprecation"` — this policy.

The headers are added before authentication, so a `401`, `403` or `429` from a deprecated route says so too.
Clients should log or alert on any response that carries `Deprecation`.

## Deprecation policy

1. **Within a version, changes are additive only.** New routes, new optional request fields and new response fields
may appear in `v1` at any time; clients must ignore unknown response fields. Removing or renaming a route, a
required field or a response field, or changing a field's type or meaning, is a breaking change.
2. **A breaking change ships as a new version** (`/v2/…`) next to the old one. The old version's routes are then
marked deprecated and keep working.
3. **Minimum notice: six months** from the first release that announces the deprecation to the `Sunset` date, and
never removed in a patch release. The `Deprecation` and `Sunset` headers, this page and the
[CHANGELOG](../CHANGELOG.md) (**Deprecated** section, with a migration note) announce it together.
4. **After the sunset date** the route may be removed in the next minor or major release; removals are listed under
**Removed** in the CHANGELOG with the successor route.
5. **Security exception.** A route that cannot be made safe may be withdrawn sooner; the CHANGELOG **Security**
section says why and what to use instead.
6. **The committed OpenAPI document is the review gate.** `docs/api/openapi-v1.json` is regenerated by a test
(`ApiV1IntegrationTests`, `AGENTOS_UPDATE_OPENAPI=1`) and the test fails when the running Api no longer matches
it — so every contract change shows up as a diff in the pull request and is reviewed against rule 1.

The unversioned routes that existed before `v1` are the first deprecation under this policy: deprecated
2026-11-03, sunset 2027-05-03.

## Authentication

Every route except the operational probes and the public sign-up / invitation-preview routes needs
`Authorization: Bearer <token>`. The Api accepts two kinds of bearer token on the same header:

| Token | Who | How it is checked |
|---|---|---|
| Keycloak access token (JWT, RS256) | people (the desktop, Scalar) | signature against the realm JWKS, issuer, audience, lifetime |
| AgentOS.NET API token `aos_<prefix>_<secret>` | scripts, CI, the VS Code extension, MCP clients | prefix lookup → salted-HMAC compare in constant time → not revoked, not expired |

`Bearer aos_…` is forwarded from the JWT scheme to the API-token scheme
(`ApiTokenAuthentication.AddApiTokenAuthentication`), so nothing else changes for callers: the principal carries the
same `tenant`, `sub`, name and role claims a JWT would.

### API tokens

Created in the desktop, **Settings → People & data → API tokens**:

- **Personal token** — any member. Acts as that member (`sub` = their user id; runs are attributed to them). Revoked
automatically when the member is removed from the workspace.
- **Service account** — workspace admins only. A workspace identity for CI (`sub` = `apitoken:<id>`, name
`service:<name>`), not tied to a person.

Each token has a **scope** (closed upwards — admin includes run includes read):

| Scope | Allows |
|---|---|
| `read` | `GET` / `HEAD` / `OPTIONS` — runs, results, settings views, `/v1/tenants/me` |
| `run` | also `POST` / `PUT` / `PATCH` / `DELETE` — start pipeline runs, upload ticket files, call `/mcp` |
| `admin` | also the workspace-admin routes (the principal gets the `admin` role). Admins only. Never `platform-admin`. |

A request whose method needs a scope the token lacks gets `403` (`application/problem+json`, *Insufficient token
scope*). An invalid, revoked or expired token gets `401` with `WWW-Authenticate: Bearer error="invalid_token"`.

The plaintext is shown **once** at creation; only a salted HMAC-SHA256 is stored. Every token expires — at most
`Tenants:ApiTokens:MaxLifetimeDays` (platform setting, default 366 days; see [CONFIG.md](CONFIG.md)). Creation,
revocation and use are audited (**Settings → Audit log**: `apitoken.created`, `apitoken.revoked`, `apitoken.used`,
`apitoken.refused`; use and refusal rows are written at most once per token per 5 minutes, with the caller's IP and
user agent). The token list shows when each token was last used.

Check what a token resolves to:

```bash
curl -s -H "Authorization: Bearer $AGENTOS_TOKEN" https://agentos.example.com/v1/tenants/me
# {"tenantId":"acme","userId":"apitoken:…","userName":"service:ci-deploy","roles":["member"],
# "isAuthenticated":true,"isAdmin":false,"authMethod":"api_token","scopes":["read","run"]}
```

### CI: start a run with a service account

Create a service account with the `run` scope, store it as a CI secret, and call the Api:

```yaml
# .github/workflows/agentos.yml
jobs:
agentos:
runs-on: ubuntu-latest
steps:
- name: Run the AgentOS.NET pipeline
env:
AGENTOS_URL: https://agentos.example.com
AGENTOS_TOKEN: ${{ secrets.AGENTOS_TOKEN }}
run: |
curl --fail-with-body -sS -X POST "$AGENTOS_URL/v1/pipeline" \
-H "Authorization: Bearer $AGENTOS_TOKEN" -H "Content-Type: application/json" \
-d '{"description":"As a user I can reset my password by email"}'
```

`/v1/pipeline/stream` returns the same run as Server-Sent Events (`progress`, `result`, `error`).

### VS Code extension

The **AgentOS.NET Runner** extension (`tools/agentos-vscode`) uses a personal token for API calls:
**AgentOS.NET: Set API token** stores it in VS Code secret storage (checked against `/v1/tenants/me`),
**Run the pipeline on a user story** calls `POST /v1/pipeline`, **Check API token** / **Clear API token** manage it.
Set `agentos.apiUrl` to the Api's base URL.

## Errors

Errors are RFC 7807 `application/problem+json` (`status`, `title`, `detail`, `traceId`); validation failures are
`400` with an `errors` map. `402` means the workspace's monthly budget cap is reached; `429` is the per-tenant rate
limit (120 requests/minute on the Api).
1 change: 1 addition & 0 deletions docs/CONFIG.md
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,7 @@ as one fixed dev user, so production-sized per-user buckets would throttle a UI
| Key | Default | Notes |
|---|---|---|
| `RemoteAgent:AutoApprove` | `false` (Production locked) | Unattended remote execution. |
| `Tenants:ApiTokens:MaxLifetimeDays` | `366` (platform, 1–1825) | Longest expiry a new personal token or service-account token may get (Settings → Platform → Safety). Existing tokens keep their expiry. See [API.md](API.md#api-tokens). |
| `Tenants:OpenSignup` | `true` in Development, else `false` | Lets anyone create a new workspace (and become its admin) from `/signup` / `POST /tenants/register`. Invitations always work. Pin it with `Settings:Locks:Tenants:OpenSignup`. |
| `Tools:EnforceByDefault` | `true` in Production, else `false` | Fail-closed tool policy. |
| `Workspaces:AllowedHosts` | empty | Self-hosted GitHub Enterprise / Azure DevOps Server hosts, comma-separated (atop `SsrfGuard`; public provider hosts always allowed). |
Expand Down
Loading
Loading