diff --git a/docs/github-token.md b/docs/github-token.md index b04df0947..f55082437 100644 --- a/docs/github-token.md +++ b/docs/github-token.md @@ -1,8 +1,12 @@ # Generating a GitHub Token for Archie Core -This guide walks you through creating a GitHub Personal Access Token (PAT) for Archie Core. +This guide walks you through creating a GitHub Personal Access Token (PAT) for +Archie Core. -> **Important**: Archie Core requires a **Classic Personal Access Token** (starts with `ghp_...`). Fine-grained PATs currently lack necessary scope permissions for Git HTTP push operations, repository invitation acceptance, and cross-repository operations needed by the orchestrator. +> **Important**: Archie Core requires a **Classic Personal Access Token** +> (starts with `ghp_...`). Fine-grained PATs currently lack necessary scope +> permissions for Git HTTP push operations, repository invitation acceptance, +> and cross-repository operations needed by the orchestrator. --- @@ -11,23 +15,30 @@ This guide walks you through creating a GitHub Personal Access Token (PAT) for A Archie Core uses the GitHub API to: 1. Poll assigned or labelled issues (`archie:queued`). -2. Update issue labels as tasks transition (`archie:working`, `archie:pr`, `archie:parked`). +2. Update issue labels as tasks transition (`archie:working`, `archie:pr`, + `archie:parked`). 3. Post status comments and emoji reactions. -4. Create branches, commit code changes, and open Pull Requests for human review. +4. Create branches, commit code changes, and open Pull Requests for human + review. --- ## Step-by-Step Instructions: Creating a Classic Token -1. Navigate to [GitHub Settings → Developer Settings → Tokens (classic)](https://github.com/settings/tokens). +1. Navigate to + [GitHub Settings → Developer Settings → Tokens (classic)](https://github.com/settings/tokens). 2. Click **Generate new token** → **Generate new token (classic)**. 3. Set the **Note**: `Archie Core` (or your bot's name). -4. Choose an **Expiration** (e.g. 90 days, 1 year, or No expiration for dedicated bot accounts). +4. Choose an **Expiration** (e.g. 90 days, 1 year, or No expiration for + dedicated bot accounts). 5. Select the required scope: - - **`repo`** (Full control of private repositories — required for polling, commenting, pushing branches, and opening PRs). - - **`workflow`** (Optional — required if Archie needs to update GitHub Actions workflows). + - **`repo`** (Full control of private repositories — required for polling, + commenting, pushing branches, and opening PRs). + - **`workflow`** (Optional — required if Archie needs to update GitHub + Actions workflows). 6. Scroll to the bottom and click **Generate token**. -7. **Copy your token immediately** (starts with `ghp_...`). You won't be able to see it again! +7. **Copy your token immediately** (starts with `ghp_...`). You won't be able to + see it again! --- diff --git a/docs/guides/first-playbook.md b/docs/guides/first-playbook.md index 37dde5416..0bbdaa49a 100644 --- a/docs/guides/first-playbook.md +++ b/docs/guides/first-playbook.md @@ -1,16 +1,15 @@ # Building your first playbook binding -This walks through the whole no-code path the event-capture epic promises: -point an external app's webhook at archie, see the real payload it sends, -map the fields you care about, bind them to a workflow, and watch the next -matching event turn into a task -- no code, no redeploy, no restart. +This walks through the whole no-code path the event-capture epic promises: point +an external app's webhook at archie, see the real payload it sends, map the +fields you care about, bind them to a workflow, and watch the next matching +event turn into a task -- no code, no redeploy, no restart. ## 1. Create a source and send a test event -Open **Events → Inspector** and click **New source**. Archie shows the -source's URL and signing secret once; copy both. Point the external app's -webhook at that URL. Send one real -event however is easiest for a first test, e.g.: +Open **Events → Inspector** and click **New source**. Archie shows the source's +URL and signing secret once; copy both. Point the external app's webhook at that +URL. Send one real event however is easiest for a first test, e.g.: ```bash curl -X POST http://localhost:8484/webhooks/capture/sentry \ @@ -18,25 +17,25 @@ curl -X POST http://localhost:8484/webhooks/capture/sentry \ -d '{"issue": {"title": "NullPointerException in checkout"}, "level": "error"}' ``` -This event isn't signed yet, so it's captured but marked **unauthenticated** --- visible for you to design against, but incapable of triggering anything: an unauthenticated event can never match a binding. +This event isn't signed yet, so it's captured but marked **unauthenticated** -- +visible for you to design against, but incapable of triggering anything: an +unauthenticated event can never match a binding. ## 2. Inspect the captured payload -Open the dashboard's **Event inspector** (`/captures`). Your test event -appears there with its real body -- this is schema-by-example: you're -looking at an actual payload from the actual sender, not guessing at a -schema in advance. +Open the dashboard's **Event inspector** (`/captures`). Your test event appears +there with its real body -- this is schema-by-example: you're looking at an +actual payload from the actual sender, not guessing at a schema in advance. ## 3. Map the fields you care about Open **Field mappings** (`/mappings`) → **New mapping**. Pick your captured event from the dropdown, then click through its payload tree on the right -- -every key and value is clickable. Clicking a value binds it as a field -(name, JSON path, and an inferred type you can change). Add whichever fields -your workflow needs (e.g. the issue title), mark the ones that must be -present as **Required**, hit **Preview** to confirm they resolve correctly -against the real payload, then **Save**. +every key and value is clickable. Clicking a value binds it as a field (name, +JSON path, and an inferred type you can change). Add whichever fields your +workflow needs (e.g. the issue title), mark the ones that must be present as +**Required**, hit **Preview** to confirm they resolve correctly against the real +payload, then **Save**. ## 4. Create the binding @@ -46,20 +45,20 @@ Open **Playbook bindings** (`/bindings`) → **New binding**: - **Source** -- the same `` segment from step 1 (e.g. `sentry`). - **Field mapping** -- the one you just saved. - **Workflow** -- which registered workflow should run on a match. -- **Repo pin** (optional) -- leave both blank to use the single configured - repo; set owner/repo explicitly if you run a multi-repo deployment. -- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The - sender signs every request body with this via HMAC-SHA256 so archie can - tell a genuine event from anyone who finds the URL. +- **Repo pin** (optional) -- leave both blank to use the single configured repo; + set owner/repo explicitly if you run a multi-repo deployment. +- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The sender + signs every request body with this via HMAC-SHA256 so archie can tell a + genuine event from anyone who finds the URL. Save. The binding starts in **draft** -- nothing fires yet. ## 5. Approve it A **draft** or freshly-**edited** binding needs an explicit human approval -before it can ever match a live event -- this is deliberate, not a missing -step: an operator authoring a binding is a considered act, an event arriving -is not, and nothing should self-arm. Click **Approve**. Status becomes **armed**. +before it can ever match a live event -- this is deliberate, not a missing step: +an operator authoring a binding is a considered act, an event arriving is not, +and nothing should self-arm. Click **Approve**. Status becomes **armed**. ## 6. Fire it for real @@ -77,16 +76,14 @@ curl -X POST http://localhost:8484/webhooks/capture/sentry \ -d "$BODY" ``` -This event is captured as **authenticated**, matched against your armed -binding, and dispatched into a new task through the exact same -gate/worktree/sandbox pipeline every other task goes through. Check -the **Tasks** page; a new task should appear, its body built from the fields -your mapping resolved. +This event is captured as **authenticated**, matched against your armed binding, +and dispatched into a new task through the exact same gate/worktree/sandbox +pipeline every other task goes through. Check the **Tasks** page; a new task +should appear, its body built from the fields your mapping resolved. ## Editing a live binding Any edit to an armed binding -- even a typo fix -- drops it back to -**pending_approval** automatically. This can't be bypassed by editing; it -has to be re-approved. When editing, leave the **Shared secret** field blank -to keep the existing secret; only fill it in if you're deliberately -rotating it. +**pending_approval** automatically. This can't be bypassed by editing; it has to +be re-approved. When editing, leave the **Shared secret** field blank to keep +the existing secret; only fill it in if you're deliberately rotating it. diff --git a/docs/guides/pr-review-benchmark.md b/docs/guides/pr-review-benchmark.md index 5d3aee20e..a28c01c1e 100644 --- a/docs/guides/pr-review-benchmark.md +++ b/docs/guides/pr-review-benchmark.md @@ -4,9 +4,9 @@ task bench:prreview ``` -Reviews the 38 runnable Martian pull requests once each at `deep` depth with -the production pipeline, judges the posted comments against the golden -comments in `internal/app/prbench/martian.json`, and writes +Reviews the 38 runnable Martian pull requests once each at `deep` depth with the +production pipeline, judges the posted comments against the golden comments in +`internal/app/prbench/martian.json`, and writes `docs/benchmarks/pr-review-.md` (recall per PR, overall recall, precision, models, archie version). Commit that file with the run. @@ -14,8 +14,8 @@ precision, models, archie version). Commit that file with the run. and judge both default to its `default` alias. Override with `task bench:prreview -- -model ALIAS_OR_PROVIDER/MODEL -judge-model ALIAS_OR_PROVIDER/MODEL`. Pick a judge other than the reviewer's model for an independent judgement. - Aliases set only in the dashboard are not in the file; pass a - `provider/model` ref instead. + Aliases set only in the dashboard are not in the file; pass a `provider/model` + ref instead. - Pull requests are public, so no credential is needed. `GH_TOKEN` or `GITHUB_TOKEN`, if set, only raises the GitHub API rate limit. - `-problems ID,ID` runs a partial smoke run; its report says it is not the diff --git a/docs/news/redirects.json b/docs/news/redirects.json index 4a397f3c8..5861b88f4 100644 --- a/docs/news/redirects.json +++ b/docs/news/redirects.json @@ -199,4 +199,4 @@ "/news/archied/1.9.7/": "/news/1.9.7/", "/news/archied/1.9.8/": "/news/1.9.8/", "/news/archied/1.9.9/": "/news/1.9.9/" -} +} \ No newline at end of file diff --git a/docs/news/releases.json b/docs/news/releases.json index d2949ff4b..da15650a4 100644 --- a/docs/news/releases.json +++ b/docs/news/releases.json @@ -499,4 +499,4 @@ "date": "2026-07-22", "body": "### archied\n\n- feat: ship the resident forge-polling daemon, deterministic workflow engine, isolated worktrees, quality gates, Gitea integration, Docker/NATS worker split, plugin loading, and skills support\n- feat: publish `archied` and `archie-agent` container images to the Gitea registry\n\n### archie-agent\n\n- feat: ship the isolated agent runtime, NATS RPC boundary, workflow execution, skills, and plugin support\n- feat: publish the `archie-agent` container image to the Gitea registry" } -] +] \ No newline at end of file diff --git a/docs/prds/external-agent-harness.md b/docs/prds/external-agent-harness.md index 12094e513..1027ac502 100644 --- a/docs/prds/external-agent-harness.md +++ b/docs/prds/external-agent-harness.md @@ -1,18 +1,17 @@ # External agent harnesses -**Status:** Approved -**Scope:** the harness model and, in "Session contract", the duplex session -that the setup terminal and the run-scoped live view both use. Code cites -this file for both (`ui/src/harness/SetupTerminal.vue`, +**Status:** Approved **Scope:** the harness model and, in "Session contract", +the duplex session that the setup terminal and the run-scoped live view both +use. Code cites this file for both (`ui/src/harness/SetupTerminal.vue`, `internal/infrastructure/postgres/queries/harness_secrets.sql`). ## Decision -A workflow stage can run on an external coding-agent CLI instead of the -built-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any -other CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API -key or the operator's subscription login, and can carry the operator's own -skills, plugins, subagents and instructions. +A workflow stage can run on an external coding-agent CLI instead of the built-in +agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any other CLI +packaged as a Docker Sandbox Kit v3. Each authenticates with an API key or the +operator's subscription login, and can carry the operator's own skills, plugins, +subagents and instructions. Two boundaries hold regardless of what the harness does: @@ -28,102 +27,99 @@ Two boundaries hold regardless of what the harness does: A harness is packaged as a Kit v3 image: an OCI image whose `vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the harness needs. Archie reads descriptors with the published -`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain -its own descriptor format. Published Kits run unmodified. +`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain its +own descriptor format. Published Kits run unmodified. Archie is a partial Kit runtime. It implements these capability types: -| Type | Archie behaviour | -| ------------------- | ----------------------------------------------------------------------------------------- | -| `credential@1` | Proxy-managed only, described below. | -| `network-policy@1` | Enforced by the egress proxy. | -| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. | -| `lifecycle@1` | Install and startup hooks run on container create. | -| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. | -| `agent-skills@1` | Discovery paths for bundled skills and optional shared skills; host access is always read-only. | -| `agent-skill@1` | Selected image-bundled skills copied into the declared discovery paths. | -| `agent-context@1` | The resolved discovery directory, defaulting beside the workspace; preserve instructions outside Archie-managed sections. | -| `resources@1` | Container CPU and memory limits. | +| Type | Archie behaviour | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `credential@1` | Proxy-managed only, described below. | +| `network-policy@1` | Enforced by the egress proxy. | +| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. | +| `lifecycle@1` | Install and startup hooks run on container create. | +| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. | +| `agent-skills@1` | Discovery paths for bundled skills and optional shared skills; host access is always read-only. | +| `agent-skill@1` | Selected image-bundled skills copied into the declared discovery paths. | +| `agent-context@1` | The resolved discovery directory, defaulting beside the workspace; preserve instructions outside Archie-managed sections. | +| `resources@1` | Container CPU and memory limits. | -Every other type fails closed: a required entry refuses the launch, an -optional one is skipped and recorded on the step. `credential@1` with -`passthrough: true` and any credential for a forge service are refused. +Every other type fails closed: a required entry refuses the launch, an optional +one is skipped and recorded on the step. `credential@1` with `passthrough: true` +and any credential for a forge service are refused. -The operator's own setup (plugins, subagents, instructions, settings) is a -mixin Kit, published with the harness Kit as a Kit set: the set merges their -layers into one image. It is versioned image content, rewritten on every -create, never state a run can modify. +The operator's own setup (plugins, subagents, instructions, settings) is a mixin +Kit, published with the harness Kit as a Kit set: the set merges their layers +into one image. It is versioned image content, rewritten on every create, never +state a run can modify. ## Contract A harness run is a second implementation of `agentexec.Runner`. It takes the -same `Request` and returns the same `Result`, so workflows, the daemon and -the State Store do not know which runner ran a stage. +same `Request` and returns the same `Result`, so workflows, the daemon and the +State Store do not know which runner ran a stage. -`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an -output adapter that translates the CLI's JSON output stream into -`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can -run stages with no capture tools, reporting no usage; its token budget falls -back to wall clock. +`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an output +adapter that translates the CLI's JSON output stream into `ToolCallReporter` +calls, `Usage` and a session ID. A CLI with no adapter can run stages with no +capture tools, reporting no usage; its token budget falls back to wall clock. Workflow definition validation rejects, at load time, a stage whose needs the -selected harness cannot meet: capture tools without an adapter, or a gate -retry without a `resume` verb. +selected harness cannot meet: capture tools without an adapter, or a gate retry +without a `resume` verb. ## Selection -A harness is an agent profile. `docs/prds/event-automation.md` defines a -profile as the execution environment a workflow selects; a harness profile -names one Kit pinned by digest, a workload Kit or a published Kit set, in -place of a container image. Archie runs that Kit's image and composes no Kits -itself; a bare mixin is refused. Everything else about profiles -holds: a workflow names its profile, a stage may name a different one, and a -profile holds no secrets. +A harness is an agent profile. `docs/prds/event-automation.md` defines a profile +as the execution environment a workflow selects; a harness profile names one Kit +pinned by digest, a workload Kit or a published Kit set, in place of a container +image. Archie runs that Kit's image and composes no Kits itself; a bare mixin is +refused. Everything else about profiles holds: a workflow names its profile, a +stage may name a different one, and a profile holds no secrets. -`archie-agent` builds the stage's runner from the stage's profile: the -ai-sdk agent loop for an image profile, the harness runner for a Kit -profile. Image profiles, and every workflow already written against them, -are unchanged. A Kit profile named by no workflow is a validation error. +`archie-agent` builds the stage's runner from the stage's profile: the ai-sdk +agent loop for an image profile, the harness runner for a Kit profile. Image +profiles, and every workflow already written against them, are unchanged. A Kit +profile named by no workflow is a validation error. -A stage naming a different profile than its workflow's is a separate run, -not a mid-container runner switch: a Kit task runs in one container -provisioned for one profile (Container layout), so a stage that needs a -different one is its own callee, started the way `workflow.call` already -starts one (`docs/prds/event-automation.md` "Workflows call workflows"), -with its own agent profile resolved off its own task row. This needs no -mechanism beyond `workflow.call` plus per-task profile resolution -(`daemon.pinTaskProfile`), both of which already treat every task's -profile independently of any caller's -- see +A stage naming a different profile than its workflow's is a separate run, not a +mid-container runner switch: a Kit task runs in one container provisioned for +one profile (Container layout), so a stage that needs a different one is its own +callee, started the way `workflow.call` already starts one +(`docs/prds/event-automation.md` "Workflows call workflows"), with its own agent +profile resolved off its own task row. This needs no mechanism beyond +`workflow.call` plus per-task profile resolution (`daemon.pinTaskProfile`), both +of which already treat every task's profile independently of any caller's -- see `TestWorkflowCallerConformance` (staterpc) for the callee's independent -`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon) -for the Kit-vs-image runner selection that independence produces. +`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon) for +the Kit-vs-image runner selection that independence produces. -Profiles are org resources in the State Store, so a Kit profile belongs to -one org, is granted to its workspaces like any profile, and applies without -a restart. +Profiles are org resources in the State Store, so a Kit profile belongs to one +org, is granted to its workspaces like any profile, and applies without a +restart. ## Organisations `docs/prds/orgs-and-access.md` is the boundary; a harness adds nothing that crosses it. -- A Kit profile, its credential bindings and its OAuth tokens belong to one - org. No record is shared between orgs. +- A Kit profile, its credential bindings and its OAuth tokens belong to one org. + No record is shared between orgs. - A harness run is a run like any other: it acts as the workflow's identity, under the run credential issued at dispatch. -- The egress proxy injects a credential only when the run credential carries - the secret the binding names. A Kit that declares a service the identity is - not granted gets no credential: a required one refuses the launch, an - optional one is skipped. -- A Kit's network policy is what the Kit asks for; the identity's network - grants are what the org allows. The proxy enforces the intersection. +- The egress proxy injects a credential only when the run credential carries the + secret the binding names. A Kit that declares a service the identity is not + granted gets no credential: a required one refuses the launch, an optional one + is skipped. +- A Kit's network policy is what the Kit asks for; the identity's network grants + are what the org allows. The proxy enforces the intersection. - Concurrency slots are counted per binding within its org. ## Credentials A credential binding maps a Kit's `credential@1` `service` name to an org -secret, which the org grants to identities like any secret. The secret holds -one of: +secret, which the org grants to identities like any secret. The secret holds one +of: - **API key:** a value in the org's secret store. - **OAuth:** tokens captured by the setup terminal, stored in the State Store @@ -132,26 +128,26 @@ one of: The egress proxy resolves the binding for each request against the run credential. The container gets the Kit's sentinel in the named variable or -credential file. OAuth refresh happens at the proxy, which intercepts the -Kit's `tokenEndpoint`, so a refreshed token is written to the State Store and -never returned to the container. +credential file. OAuth refresh happens at the proxy, which intercepts the Kit's +`tokenEndpoint`, so a refreshed token is written to the State Store and never +returned to the container. Runs sharing an OAuth binding share its subscription's rate limit. -`max_concurrent` on the binding (default 1) caps its simultaneous runs. A -stage waiting for a slot is `pending`, not `running`. +`max_concurrent` on the binding (default 1) caps its simultaneous runs. A stage +waiting for a slot is `pending`, not `running`. ## Session contract -A **session** is a duplex PTY into a Kit container the daemon owns. One -concept covers both targets; only the address, the lifetime and the -established egress phase differ. +A **session** is a duplex PTY into a Kit container the daemon owns. One concept +covers both targets; only the address, the lifetime and the established egress +phase differ. -| | Setup session | Run session (deferred) | -| --- | --- | --- | -| Address | `{org, profile}` | `{org, task, attempt}` | -| Container | ephemeral, from the profile's Kit | the task's running container | -| Purpose | run the CLI's own login so the proxy captures the tokens | watch and optionally take over | -| Lifetime | bounded by the session TTL; the container is removed on close | bounded by the task | +| | Setup session | Run session (deferred) | +| --------- | ------------------------------------------------------------- | ------------------------------ | +| Address | `{org, profile}` | `{org, task, attempt}` | +| Container | ephemeral, from the profile's Kit | the task's running container | +| Purpose | run the CLI's own login so the proxy captures the tokens | watch and optionally take over | +| Lifetime | bounded by the session TTL; the container is removed on close | bounded by the task | - **Transport.** The daemon serves `harness.v1.HarnessService`, a bidi gRPC stream, and the dashboard implements its `HarnessTerminal` interface @@ -161,39 +157,37 @@ established egress phase differ. `internal/app/archied` or `internal/agentexec`. - **Authorisation.** Opening a session is the `update` action on the secret, decided by the dashboard's authorizer before the route runs - (`internal/webui/authorize.go`). The dashboard then dials the daemon with - the harness service token. The daemon does not re-authorise a human; it - trusts the asserted `{org, profile}` exactly as the task-action RPC trusts - an asserted actor. Because that authority is a shell in a container holding - an org's credential, the harness listener requires `HARNESS_TOKEN` even on - loopback, unlike the State Store's loopback convention. -- **Egress phase.** Token interception is filtered by phase - (`oauth.go`'s `rule.runtime == atRun`), and `EnterRuntime` is one-way. A - setup session therefore follows a run's lifecycle exactly: install hooks at - the install phase, `EnterRuntime` before the shell. A credential whose - token endpoint must be captured declares `phase: runtime`; a credential - capturing at install phase is captured by the install hooks that run before - the switch. -- **Credentials.** Capture is gated: the proxy intercepts a token endpoint - only for a service the session is granted (`Proxy.granted`). A setup session - has no task, so the daemon registers a session grant: its proxy token - resolves to `{org, the Kit's declared credential services the org binds}`. - That is the intersection the `update`-on-secret authorisation covers. The - real token never enters the container: the response is sentinelized and - stored as the org's harness secret. -- **Container discipline.** The setup container runs a keepalive entrypoint - with an empty `Config.Env`; the PTY is an exec as the Kit's harness user - with the harness env and nothing inherited from any worker. No worktree is - mounted. It is acquired through the container pool, so it carries the - `archie-daemon` label, the concurrency cap and the max-uptime reaper; the - session TTL is the smaller bound. Closing revokes the egress session, - removes the sandbox network and the Kit volumes, then releases the - container. + (`internal/webui/authorize.go`). The dashboard then dials the daemon with the + harness service token. The daemon does not re-authorise a human; it trusts the + asserted `{org, profile}` exactly as the task-action RPC trusts an asserted + actor. Because that authority is a shell in a container holding an org's + credential, the harness listener requires `HARNESS_TOKEN` even on loopback, + unlike the State Store's loopback convention. +- **Egress phase.** Token interception is filtered by phase (`oauth.go`'s + `rule.runtime == atRun`), and `EnterRuntime` is one-way. A setup session + therefore follows a run's lifecycle exactly: install hooks at the install + phase, `EnterRuntime` before the shell. A credential whose token endpoint must + be captured declares `phase: runtime`; a credential capturing at install phase + is captured by the install hooks that run before the switch. +- **Credentials.** Capture is gated: the proxy intercepts a token endpoint only + for a service the session is granted (`Proxy.granted`). A setup session has no + task, so the daemon registers a session grant: its proxy token resolves to + `{org, the Kit's declared credential services the org binds}`. That is the + intersection the `update`-on-secret authorisation covers. The real token never + enters the container: the response is sentinelized and stored as the org's + harness secret. +- **Container discipline.** The setup container runs a keepalive entrypoint with + an empty `Config.Env`; the PTY is an exec as the Kit's harness user with the + harness env and nothing inherited from any worker. No worktree is mounted. It + is acquired through the container pool, so it carries the `archie-daemon` + label, the concurrency cap and the max-uptime reaper; the session TTL is the + smaller bound. Closing revokes the egress session, removes the sandbox network + and the Kit volumes, then releases the container. - **Kit unavailable.** The daemon serves the contract only when it has a container pool and a Kit launcher; otherwise there is no listener, and a - client's refused connection is gRPC's `Unavailable`. The dashboard's - existing failure surface is the honest degrade; `/api/harness`'s `terminal` - field means "a client is configured", not "the daemon can run a Kit". + client's refused connection is gRPC's `Unavailable`. The dashboard's existing + failure surface is the honest degrade; `/api/harness`'s `terminal` field means + "a client is configured", not "the daemon can run a Kit". - **Run target.** `RunTarget{task_id, attempt}` opens a read-only view of a running task's sandbox; it ships as the peek. The daemon resolves the pair itself, so the dashboard never learns a container name: the task store says @@ -201,140 +195,136 @@ established egress phase differ. launcher names the container `kitrun.TaskContainer(task_id, attempt)` (one container per attempt, removed when the run ends; volumes remain task-scoped for retries). A finished or unknown task, a task that is not running, an - attempt other than the running one, or a container that is gone is - `NotFound` with the reason in the message; an unreachable task store or - container engine is `Unavailable`. The view follows the container's stdout - and stderr, including the harness output forwarded by the worker, carries - no stdin and no exec, and - ends when the task's container ends or the client leaves, so it confers no - authority over the container. A read-only tail of the existing per-attempt - logs was rejected: those refresh only on task state changes and are the - daemon's account, not the sandbox's. - Mid-stream failures are shown as a reason in the terminal before it closes. + attempt other than the running one, or a container that is gone is `NotFound` + with the reason in the message; an unreachable task store or container engine + is `Unavailable`. The view follows the container's stdout and stderr, + including the harness output forwarded by the worker, carries no stdin and no + exec, and ends when the task's container ends or the client leaves, so it + confers no authority over the container. A read-only tail of the existing + per-attempt logs was rejected: those refresh only on task state changes and + are the daemon's account, not the sandbox's. Mid-stream failures are shown as + a reason in the terminal before it closes. - **Authorisation.** The dashboard route `GET /api/tasks/{id}/sandbox` is - decided as `read-logs` on the task before the handler runs, so a caller - sees a sandbox exactly when they may read that task's log. The daemon - checks that the task belongs to the asserted org before following output. + decided as `read-logs` on the task before the handler runs, so a caller sees + a sandbox exactly when they may read that task's log. The daemon checks that + the task belongs to the asserted org before following output. - **Grants.** The view takes no grant of its own. The run's egress session (its proxy token, install then `EnterRuntime`) already belongs to the run and is revoked by `Launcher.Release` when the task ends; the view reads after that phase switch and dies with the container. - - **Credentials.** The sandbox holds sentinels, never real credentials: - API keys are `egress.Sentinel` (`credentials.go`), and an OAuth token set - is sentinelised in the response and swapped back by the proxy only on a - granted service's resource host in the matching phase (`oauth.go`, - `injectOAuth`). The proxy runs in the daemon outside the container, so a - shell in the container sees only sentinels. + - **Credentials.** The sandbox holds sentinels, never real credentials: API + keys are `egress.Sentinel` (`credentials.go`), and an OAuth token set is + sentinelised in the response and swapped back by the proxy only on a granted + service's resource host in the matching phase (`oauth.go`, `injectOAuth`). + The proxy runs in the daemon outside the container, so a shell in the + container sees only sentinels. - **Takeover (interactive PTY into a running task) is out of scope for this bead.** It needs the dangerous-command authority (`archie-core-sod1`) to - gate it, and that authority is not wired for it: the harness listener has - no approval step; `ToolSetOptions.Approval` in `internal/agentexec/modelloop` + gate it, and that authority is not wired for it: the harness listener has no + approval step; `ToolSetOptions.Approval` in `internal/agentexec/modelloop` is never set by a caller, so task runs never build approval-required tools; approvals reach a human only on the chat paths (dashboard ask, Telegram, Gateway). Takeover would also need an audit record naming the actor, task, attempt and open/close times, and revocation tied to task end (the exec is closed with the container). Those follow the setup session's shape (`harnesssession.Session`, `container.ExecPTY`) once the authority exists. -- **Audit.** Opening and closing a session and a successful capture are - recorded with the asserted org and profile. A run view's open and close are - logged with the task and attempt; it reads output only, so it has no - takeover record. +- **Audit.** Opening and closing a session and a successful capture are recorded + with the asserted org and profile. A run view's open and close are logged with + the task and attempt; it reads output only, so it has no takeover record. Each session is the only interactive path into a harness container. ## Egress Only Kit profiles run on the egress path. An image profile keeps the network -access its identity is granted, because workflows such as a network -investigator need raw DNS, ICMP and arbitrary TCP that no HTTP proxy -carries. +access its identity is granted, because workflows such as a network investigator +need raw DNS, ICMP and arbitrary TCP that no HTTP proxy carries. -- **Sandbox network.** Each Kit run gets its own internal Docker bridge on - which the host holds no address. Host services, including those listening - on every interface, are unreachable from it by any address. +- **Sandbox network.** Each Kit run gets its own internal Docker bridge on which + the host holds no address. Host services, including those listening on every + interface, are unreachable from it by any address. - **Relay.** One relay container, `archie-agent relay`, sits on the sandbox - networks under a fixed alias and on the host-reachable network. It - forwards three fixed ports, to the proxy, NATS and the State Store, and can - reach nothing else. It holds no secrets. -- **Proxy.** The proxy runs inside `archied`, listening on the host gateway - of the host-reachable network. It terminates TLS with a per-daemon CA - installed into the container at create, identifies the container by a - per-run proxy password distinct from the worker's run grant, and applies - that run's network policy and credential inject rules. Upstream dials refuse loopback, and refuse internal addresses - unless the policy names the exact IP, so an allowed name cannot resolve - back into the host. + networks under a fixed alias and on the host-reachable network. It forwards + three fixed ports, to the proxy, NATS and the State Store, and can reach + nothing else. It holds no secrets. +- **Proxy.** The proxy runs inside `archied`, listening on the host gateway of + the host-reachable network. It terminates TLS with a per-daemon CA installed + into the container at create, identifies the container by a per-run proxy + password distinct from the worker's run grant, and applies that run's network + policy and credential inject rules. Upstream dials refuse loopback, and refuse + internal addresses unless the policy names the exact IP, so an allowed name + cannot resolve back into the host. ## Container layout A Kit task runs in one container, from the Kit composition's image, on the -task's sandbox network. The worker and every harness invocation share it; -they are separated by user, not by container, so a run's cost scales with -the run and not with how many agents it fans out to. +task's sandbox network. The worker and every harness invocation share it; they +are separated by user, not by container, so a run's cost scales with the run and +not with how many agents it fans out to. -- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs - it as the container's entrypoint, as root. It holds the task's NATS and - State Store credentials in its own environment and in root-only files, - runs the workflow, and serves `archie-agent mcp`. The Kit image's - entrypoint is not PID 1. +- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs it + as the container's entrypoint, as root. It holds the task's NATS and State + Store credentials in its own environment and in root-only files, runs the + workflow, and serves `archie-agent mcp`. The Kit image's entrypoint is not + PID 1. - **Harness.** Every invocation runs as the Kit's user (the image's `User`, - default uid 1000) with an explicit environment: the Kit's variables, the - proxy environment and the credential sentinels, and nothing inherited from - the worker. That user cannot read the worker's environment or files, or - trace it. Sibling invocations in one run share the user and the worktree. + default uid 1000) with an explicit environment: the Kit's variables, the proxy + environment and the credential sentinels, and nothing inherited from the + worker. That user cannot read the worker's environment or files, or trace it. + Sibling invocations in one run share the user and the worktree. - **Hooks.** `lifecycle@1` install and startup hooks run as the user each declares, before the worker accepts work. - **Mounts.** The task worktree at the Kit's workspace directory, owned by the Kit's user, and the read-only skills store. Nothing else from the host. -- **Network.** The relay forwards three fixed ports on the sandbox network: - the egress proxy, NATS and the State Store. The worker reaches NATS and the - State Store with its credentials; a harness can open those ports but holds - no credential either accepts. -- **Volumes.** `volume@1` paths persist for the life of the - WorkflowExecution, which covers session resume across gate iterations and - retries. They are not shared between executions. +- **Network.** The relay forwards three fixed ports on the sandbox network: the + egress proxy, NATS and the State Store. The worker reaches NATS and the State + Store with its credentials; a harness can open those ports but holds no + credential either accepts. +- **Volumes.** `volume@1` paths persist for the life of the WorkflowExecution, + which covers session resume across gate iterations and retries. They are not + shared between executions. ## Archie tools inside the harness -Capture tools return a stage's structured results through `archie-agent mcp`, -a stdio MCP server. The same command forwards central-tool discovery and -calls over Streamable HTTP to `http://archie.tools/mcp` through the egress -proxy. Claude Code, Codex, Pi, OMP and GitHub Copilot CLI register it using -their native MCP configuration. Registration files are per-stage and outside -the worktree; the Kit's bundled settings remain intact. A CLI that exits -without initializing the required MCP server fails the stage. +Capture tools return a stage's structured results through `archie-agent mcp`, a +stdio MCP server. The same command forwards central-tool discovery and calls +over Streamable HTTP to `http://archie.tools/mcp` through the egress proxy. +Claude Code, Codex, Pi, OMP and GitHub Copilot CLI register it using their +native MCP configuration. Registration files are per-stage and outside the +worktree; the Kit's bundled settings remain intact. A CLI that exits without +initializing the required MCP server fails the stage. -`archied` handles that exact endpoint inside the authenticated task proxy; -it is not a listener or an upstream network destination. It is available -only during task runtime, never during install or a setup session. The -harness supplies a sentinel, and the proxy injects a separate random gateway -token held only on the host. Ending the proxy session revokes that token and -cancels active calls. +`archied` handles that exact endpoint inside the authenticated task proxy; it is +not a listener or an upstream network destination. It is available only during +task runtime, never during install or a setup session. The harness supplies a +sentinel, and the proxy injects a separate random gateway token held only on the +host. Ending the proxy session revokes that token and cancels active calls. -The proxy reaches `archie-gateway` through its authenticated gRPC contract. -The Gateway derives the task, execution principal and org from a live run -grant on every request. Its tool list is bounded by the profile in that org -and the package's accepted tool authority, checked again at invocation. -Workspace tools, chat file delivery, conversation-only tools and tools that -require an unavailable approver are not served. Tool result limits apply -without exposing host spill paths; media is returned as MCP content. +The proxy reaches `archie-gateway` through its authenticated gRPC contract. The +Gateway derives the task, execution principal and org from a live run grant on +every request. Its tool list is bounded by the profile in that org and the +package's accepted tool authority, checked again at invocation. Workspace tools, +chat file delivery, conversation-only tools and tools that require an +unavailable approver are not served. Tool result limits apply without exposing +host spill paths; media is returned as MCP content. Task MCP providers run in the Gateway with task-bound sessions and sampling. Sampling uses the task's model and credentials, records task usage and refuses -revoked grants. It does not use the chat identity or chat model. The worker -does not start another copy of those providers for Kit tasks. The harness's -own built-in tools remain outside Archie's tool-result limits. +revoked grants. It does not use the chat identity or chat model. The worker does +not start another copy of those providers for Kit tasks. The harness's own +built-in tools remain outside Archie's tool-result limits. ## Enforcement around the harness -| Property | Enforcement | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Property | Enforcement | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Model never runs git | No forge credential can be bound. Archie records `HEAD` and every ref before the run; any change fails the step (`failed`, policy class). The workflow commits the stage's changes. | -| Protected paths | A diff touching a `Protection` path fails the step. | -| Read-only stage | Any worktree diff fails the step. | -| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. | -| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. | -| Cancellation | Cancelling the step kills the process group, then the container. | -| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. | +| Protected paths | A diff touching a `Protection` path fails the step. | +| Read-only stage | Any worktree diff fails the step. | +| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. | +| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. | +| Cancellation | Cancelling the step kills the process group, then the container. | +| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. | Harness settings that deny git or protected paths are added where the CLI supports them, to save wasted turns. They are never the enforcement. @@ -342,38 +332,34 @@ supports them, to save wasted turns. They are never the enforcement. ## Execution tree A harness run is one `agent` StepExecution. Subagents the harness spawns -internally are not recorded as children. Their usage is included in the -step's `tokens_used` when the adapter reports it. +internally are not recorded as children. Their usage is included in the step's +`tokens_used` when the adapter reports it. ## Agents never hold a harness -An Agent reaches a harness only by invoking a Workflow whose stage names it. -No Agent tool, chat tool or capability exposes a harness, its setup terminal -or its credential. The stage boundary is what carries the container, the git -and path checks, the gate and the budget; a harness outside a stage has none -of them. +An Agent reaches a harness only by invoking a Workflow whose stage names it. No +Agent tool, chat tool or capability exposes a harness, its setup terminal or its +credential. The stage boundary is what carries the container, the git and path +checks, the gate and the budget; a harness outside a stage has none of them. ## Out of scope -- Chat through a harness. The gateway chat loop stays on the built-in - runtime. -- `network-policy@2` HTTP method and path rules; a Kit requiring it is - refused. +- Chat through a harness. The gateway chat loop stays on the built-in runtime. +- `network-policy@2` HTTP method and path rules; a Kit requiring it is refused. - Recording the harness's internal subagents as StepExecutions. - Cost in currency. - Choosing a harness automatically per task. ## Plan -1. Descriptor resolution with the Kit spec package; capability support - table and fail-closed refusal. +1. Descriptor resolution with the Kit spec package; capability support table and + fail-closed refusal. 2. Egress proxy: internal network, per-daemon CA, per-container token, `network-policy@1`. 3. `credential@1`: API-key bindings, sentinel rendering, inject rules. -4. Harness `Runner`: container create with worktree, volumes, lifecycle - hooks and the mounted `archie-agent`; `agent-sessions@1` invocation; - worktree checks for git, protected paths and read-only; budget and - cancellation. +4. Harness `Runner`: container create with worktree, volumes, lifecycle hooks + and the mounted `archie-agent`; `agent-sessions@1` invocation; worktree + checks for git, protected paths and read-only; budget and cancellation. 5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop. 6. Kit profiles, runner selection from the stage's profile, and definition validation. @@ -383,19 +369,19 @@ of them. ## Verification -- Every named adapter discovers and calls a permitted central tool through - the proxy and records a local capture. A guessed tool outside the profile - or accepted package authority is refused. +- Every named adapter discovers and calls a permitted central tool through the + proxy and records a local capture. A guessed tool outside the profile or + accepted package authority is refused. - The gateway token never appears in the container, generated MCP files, worktree, logs or events. It is not the container's proxy password. -- A permission change after discovery takes effect at the next call; ending - the proxy session cancels active calls, and a revoked grant cannot execute - tools or sample a model. -- Bundled skills remain visible with shared skills missing or disabled; - shared mounts are per-skill and read-only. Explicit context directories - preserve non-managed instructions and refuse symlinked staging paths. -- The same workflow definition completes on `builtin` and on the Claude Code - Kit with the same `Result` shape and captures. +- A permission change after discovery takes effect at the next call; ending the + proxy session cancels active calls, and a revoked grant cannot execute tools + or sample a model. +- Bundled skills remain visible with shared skills missing or disabled; shared + mounts are per-skill and read-only. Explicit context directories preserve + non-managed instructions and refuse symlinked staging paths. +- The same workflow definition completes on `builtin` and on the Claude Code Kit + with the same `Result` shape and captures. - After `/login` in the setup terminal, the container's credential file holds only sentinels, the State Store holds the encrypted token, and a task run authenticates. @@ -407,8 +393,8 @@ of them. unchanged. - A harness edit to a protected test file fails the step in a TDD fix stage. - A read-only feasibility stage that writes a file fails. -- A file a run writes into a Kit-managed path such as the CLI's settings file - is gone on the next execution. +- A file a run writes into a Kit-managed path such as the CLI's settings file is + gone on the next execution. - A Kit requiring an unsupported capability is refused at launch with the capability named. - A stage with a failing gate resumes the same session with the gate output, @@ -416,11 +402,11 @@ of them. - Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a time; the second waits as `pending`. - Stopping a run kills the harness process and removes the container. -- A harness invocation cannot read the worker's NATS or State Store - credential from its environment, its files or `/proc`. +- A harness invocation cannot read the worker's NATS or State Store credential + from its environment, its files or `/proc`. - A run fanning out to many agent invocations uses one container. -- A Kit profile in org A cannot be selected, and its binding cannot be - resolved, by a workflow in org B. +- A Kit profile in org A cannot be selected, and its binding cannot be resolved, + by a workflow in org B. - A harness run whose identity is not granted a Kit's required credential is refused at launch; the proxy never injects a secret outside the run credential. diff --git a/docs/security/authorization.md b/docs/security/authorization.md index 1da04a452..9fa502e90 100644 --- a/docs/security/authorization.md +++ b/docs/security/authorization.md @@ -1,18 +1,20 @@ # User authorization boundaries Archie separates authentication (which person or service is calling) from -permission to act on a resource. This inventory follows the [OWASP -Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) -and [Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html), +permission to act on a resource. This inventory follows the +[OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) +and +[Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html), including its guidance on attributes and relationships. It describes concrete -enforcement points and their regression tests; it is not a compliance certification. +enforcement points and their regression tests; it is not a compliance +certification. ## Transport and authority -The browser uses HTTP/JSON and SSE to the UI service. The UI service calls -State Store, Gateway, Messaging and Harness through their gRPC contracts. -Only the State Store opens the task/control-plane/account database; Gateway -owns conversation storage. Browser HTTP handlers never open either database. +The browser uses HTTP/JSON and SSE to the UI service. The UI service calls State +Store, Gateway, Messaging and Harness through their gRPC contracts. Only the +State Store opens the task/control-plane/account database; Gateway owns +conversation storage. Browser HTTP handlers never open either database. Instance service credentials are administrative authority. They are not user sessions and must never reach a browser, model, or agent container. A service @@ -23,21 +25,25 @@ boundary evaluates Cedar before invoking them. Task credentials have a separate, explicit RPC allowlist and cannot call account or identity administration. Local service listeners are trusted process boundaries. Loopback is not a -substitute for authentication on a remotely reachable listener. OIDC credentials, -local browser sessions, personal API tokens, service credentials, and task grants -must remain distinct. +substitute for authentication on a remotely reachable listener. OIDC +credentials, local browser sessions, personal API tokens, service credentials, +and task grants must remain distinct. ## Policy and relationship model `internal/domain/access` defines actions, resources, principals and memberships. `internal/infrastructure/access` assembles Cedar entities and evaluates the -instance → organization → workspace → object chain. A forbid wins; each applicable -level must permit the operation. Missing or invalid policy chains fail closed. +instance → organization → workspace → object chain. A forbid wins; each +applicable level must permit the operation. Missing or invalid policy chains +fail closed. The default policies grant actions through scoped roles. Policies can also restrict a named identity, workspace environment, owner, state, source address, -signature, run or step. HTTP task decisions now include the stored initiating identity and task state; binding decisions include the stored binding state. The HTTP source address is the actual connection peer, not an unverified forwarded header. Membership and resource attributes must come from stored -records or authenticated context, never a request's assertion about itself. +signature, run or step. HTTP task decisions now include the stored initiating +identity and task state; binding decisions include the stored binding state. The +HTTP source address is the actual connection peer, not an unverified forwarded +header. Membership and resource attributes must come from stored records or +authenticated context, never a request's assertion about itself. Cedar permission is not ownership of another person's private data. Conversation history, passkeys, recovery codes and personal tokens are bound to the person. @@ -48,34 +54,34 @@ accounts by unverified email, or create an administrator. ## Enforcement inventory -| Location | Enforcement | Regression evidence | -| --- | --- | --- | -| Browser credential gate: `webui/auth.go`, `accounts.go` | Account session or verified provider identity; shared dashboard token is not a person when accounts are enabled. No API data before authentication. | `TestAccountBoundary`, `TestAccountSessionFailureIsClosed` | -| Browser policy gate: `webui/authorize.go` | Resolve principal from stored identity; evaluate action against stored org/workspace and resource kind before handler. Missing chain refuses. | `TestHTTPPolicyCannotBeBypassed`, `TestAuthorizeRefusesWithoutAChain`, `TestAuthorizeRecord`, `TestTaskAuthorizationUsesStoredAttributes`, `TestAuthorizeCreateIn` | -| Instance-only HTTP surfaces: `webui/instance_only.go`, server route registration | Hide instance-owned configuration and diagnostics from another org; policy still applies first. | `TestInstanceOnlyHidesTheInstanceFromOtherOrgs`, `TestInstanceAdminOrgs` | -| First setup: `webui/accounts.go`, `postgres/accounts.go` | Initial organization, workspace, instance URL, admin identity and password commit together. Transaction lock closes bootstrap after first account; later requests require `manage_members`. | Disposable PostgreSQL smoke verification for bootstrap race and rollback; account policy tests below | -| Account creation: `webui/accounts.go`, `staterpc/accounts.go`, `postgres/accounts.go` | Cedar `manage_members` at HTTP and RPC; target org is authenticated context. New local accounts cannot request owner role. | `TestAccountManagementUsesPolicy`, `TestAccountBoundary` | -| Local passwords and sessions: `identity/password.go`, `postgres/accounts.go` | Argon2id, independent salts, length/common-password checks, generic login refusal, account throttling, session hashes and expiry, revocation on logout/password change/suspension. | `TestPasswordVerification`, `TestAccountBoundary`; disposable PostgreSQL session verification | -| Transport and CSRF: `webui/accounts.go`, `api_tasks.go` | Password/account mutations require HTTPS or localhost development, JSON, custom CSRF header and same-origin requests. Forwarded headers require explicit trusted-proxy configuration. | `TestAuthenticationTransport`, existing mutation security tests | -| Personal account routes: `webui/accounts.go` | Active signed-in person; principal supplied by server. Password change verifies current password. Sensitive authenticator changes require recent sign-in. No caller-supplied target identity. | `TestAccountBoundary` | -| Recovery: `postgres/account_security.go`, `webui/accounts.go` | Fresh authenticated owner generates a hashed, one-use recovery secret. Redemption replaces password and revokes all sessions atomically. No email-existence disclosure. | Disposable PostgreSQL recovery verification | -| Passkeys: `postgres/passkeys.go`, `webui/passkeys.go` | Configured RP origin, browser-bound one-use expiring challenge, verified credential signature and user verification. Enrollment/management belong to caller. Credential counters persist under a row lock. | Disposable browser virtual-authenticator verification; task-grant denial tests | -| OIDC: `infrastructure/oidc`, `archieui/account_oidc.go`, `webui/auth.go` | Discovery and signed ID token with issuer/client audience/expiry, PKCE, state and nonce. Verified subject resolves to active identity. Browser-local session cannot outlive provider token, and provider credential remains checked. | `TestBrowserFlowVerifiesIDToken`, `TestProviderOutageIsUnavailableThenRecovers`, subject-claim tests; no external provider acceptance implied | -| OIDC settings: `webui/accounts.go`, `postgres/authentication.go` | Instance ownership plus policy; recent sign-in for changes. Public URL cannot change while enrolled passkeys would be orphaned. | `TestAccountBoundary`, `TestAuthenticationSettingsRejectUntrustedOrigins` | -| Org membership/workspaces/agent assignment: `webui/api_orgs.go`, `staterpc/orgs.go`, `postgres/orgs.go` | Own org or instance-owner relationship, allowed role vocabulary, membership escalation/last-owner guards, tenant-scoped SQL. | `TestOrgRPCsActInTheCallersOrg`, `TestSetMembershipRefusesUnknownRole`, org HTTP tests | -| Personal API tokens: `webui/api_personal_tokens.go`, `staterpc/personal_tokens.go`, `postgres/personal_tokens.go` | Token owner comes from principal; store only token hash; revoke only caller's binding. | `TestPersonalTokensWithoutPerson`, `TestPersonalTokenOwner` | -| gRPC caller attribution: `rpcidentity/identity.go` | Authenticated service may forward a principal; State Store resolves memberships/org itself. Task grant metadata is stripped. | `TestCallerAttribution` | -| Agent/task gRPC: `staterpc/task_grants.go` | Durable task-scoped grant, explicit allowed RPC and target task, no definition-pin replacement, no account RPCs. | `TestTaskCredentialsCannotManageAccounts`, `TestTaskCredentialCannotReplaceItsPin`, `TestRecordUsageAuthority`, `TestWorkerPresenceAuthority` | -| Chat HTTP: `webui/api_chat.go` | Server stamps sender and person thread; lists/read/turns/cancel/persona verify session ownership. Browser cannot submit another sender identity. | `TestWebChatOwnership`, `TestWebChatSenderCannotBeSuppliedByBrowser`; HTTP deny matrix | -| Chat history, slash commands and model session tools: `gateway/session_store_postgres.go` | Store filters `Get`, `List`, `GetByChannel`; shared read/write guards check person ownership as well as org. A saved session cannot change its conversation source to claim another person's history. Service curation runs without a person principal. | `TestSessionVisibility`; PostgreSQL smoke for history isolation | -| Chat questions/approvals: `webui/api_chat_ask.go` | Waiting question is bound to the initiating person, in addition to its unguessable ID. | `TestChatQuestionBelongsToInitiatingPerson` | -| Chat downloads: `webui/api_chat_files.go` | Offered file token expires and is bound to the initiating person; requests cannot supply a filesystem path. | `TestChatFileDownload` | -| Per-person memory: `archiegateway/chat_identity.go`, gateway memory tools, `sessioncurator` | Verified web sender identity scopes reads/writes. Curator refuses unidentified or mixed participants instead of guessing a person. | Gateway memory and session-curator tests | -| Workflow/task actions: `webui/api_tasks.go`, `domain/taskactions`, `staterpc` | Policy and stored workspace before action; domain transition, authority and durable dispatch guards remain in force. | HTTP deny matrix, task action/domain tests, task grant tests | -| Incoming webhooks: `forge/webhook`, `captureintake`, access delivery engine | Verify HMAC before parsing; derive source/org from stored source; evaluate source delivery policies and egress rules. No browser-user credential is inferred. | Webhook/capture tests, `TestAuthorizeDelivery` | -| Control-plane configuration, secrets, harness and extensions | Browser policy and instance-only restrictions where registered; service contracts carry principal/org; task grants cannot invoke administrative RPCs. | HTTP deny matrix, `TestAdministrationRoutes`, `TestChannelReloadRoute`, `TestConfineHarnessOrg` | -| Live HTTP/SSE and diagnostics | Authenticated policy gate applies before stream creation; org-scoped event reads; instance logs require administrative visibility. | HTTP deny matrix, instance-only tests, `TestServiceLogsRequireInstanceCredential` | -| Background schedules, dispatch, curation | Service/agent authority, not an implicit browser user. Task-scoped grants and org scopes remain distinct from initiating human attribution. | Existing dispatch, grant, memory and org-scope tests | +| Location | Enforcement | Regression evidence | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Browser credential gate: `webui/auth.go`, `accounts.go` | Account session or verified provider identity; shared dashboard token is not a person when accounts are enabled. No API data before authentication. | `TestAccountBoundary`, `TestAccountSessionFailureIsClosed` | +| Browser policy gate: `webui/authorize.go` | Resolve principal from stored identity; evaluate action against stored org/workspace and resource kind before handler. Missing chain refuses. | `TestHTTPPolicyCannotBeBypassed`, `TestAuthorizeRefusesWithoutAChain`, `TestAuthorizeRecord`, `TestTaskAuthorizationUsesStoredAttributes`, `TestAuthorizeCreateIn` | +| Instance-only HTTP surfaces: `webui/instance_only.go`, server route registration | Hide instance-owned configuration and diagnostics from another org; policy still applies first. | `TestInstanceOnlyHidesTheInstanceFromOtherOrgs`, `TestInstanceAdminOrgs` | +| First setup: `webui/accounts.go`, `postgres/accounts.go` | Initial organization, workspace, instance URL, admin identity and password commit together. Transaction lock closes bootstrap after first account; later requests require `manage_members`. | Disposable PostgreSQL smoke verification for bootstrap race and rollback; account policy tests below | +| Account creation: `webui/accounts.go`, `staterpc/accounts.go`, `postgres/accounts.go` | Cedar `manage_members` at HTTP and RPC; target org is authenticated context. New local accounts cannot request owner role. | `TestAccountManagementUsesPolicy`, `TestAccountBoundary` | +| Local passwords and sessions: `identity/password.go`, `postgres/accounts.go` | Argon2id, independent salts, length/common-password checks, generic login refusal, account throttling, session hashes and expiry, revocation on logout/password change/suspension. | `TestPasswordVerification`, `TestAccountBoundary`; disposable PostgreSQL session verification | +| Transport and CSRF: `webui/accounts.go`, `api_tasks.go` | Password/account mutations require HTTPS or localhost development, JSON, custom CSRF header and same-origin requests. Forwarded headers require explicit trusted-proxy configuration. | `TestAuthenticationTransport`, existing mutation security tests | +| Personal account routes: `webui/accounts.go` | Active signed-in person; principal supplied by server. Password change verifies current password. Sensitive authenticator changes require recent sign-in. No caller-supplied target identity. | `TestAccountBoundary` | +| Recovery: `postgres/account_security.go`, `webui/accounts.go` | Fresh authenticated owner generates a hashed, one-use recovery secret. Redemption replaces password and revokes all sessions atomically. No email-existence disclosure. | Disposable PostgreSQL recovery verification | +| Passkeys: `postgres/passkeys.go`, `webui/passkeys.go` | Configured RP origin, browser-bound one-use expiring challenge, verified credential signature and user verification. Enrollment/management belong to caller. Credential counters persist under a row lock. | Disposable browser virtual-authenticator verification; task-grant denial tests | +| OIDC: `infrastructure/oidc`, `archieui/account_oidc.go`, `webui/auth.go` | Discovery and signed ID token with issuer/client audience/expiry, PKCE, state and nonce. Verified subject resolves to active identity. Browser-local session cannot outlive provider token, and provider credential remains checked. | `TestBrowserFlowVerifiesIDToken`, `TestProviderOutageIsUnavailableThenRecovers`, subject-claim tests; no external provider acceptance implied | +| OIDC settings: `webui/accounts.go`, `postgres/authentication.go` | Instance ownership plus policy; recent sign-in for changes. Public URL cannot change while enrolled passkeys would be orphaned. | `TestAccountBoundary`, `TestAuthenticationSettingsRejectUntrustedOrigins` | +| Org membership/workspaces/agent assignment: `webui/api_orgs.go`, `staterpc/orgs.go`, `postgres/orgs.go` | Own org or instance-owner relationship, allowed role vocabulary, membership escalation/last-owner guards, tenant-scoped SQL. | `TestOrgRPCsActInTheCallersOrg`, `TestSetMembershipRefusesUnknownRole`, org HTTP tests | +| Personal API tokens: `webui/api_personal_tokens.go`, `staterpc/personal_tokens.go`, `postgres/personal_tokens.go` | Token owner comes from principal; store only token hash; revoke only caller's binding. | `TestPersonalTokensWithoutPerson`, `TestPersonalTokenOwner` | +| gRPC caller attribution: `rpcidentity/identity.go` | Authenticated service may forward a principal; State Store resolves memberships/org itself. Task grant metadata is stripped. | `TestCallerAttribution` | +| Agent/task gRPC: `staterpc/task_grants.go` | Durable task-scoped grant, explicit allowed RPC and target task, no definition-pin replacement, no account RPCs. | `TestTaskCredentialsCannotManageAccounts`, `TestTaskCredentialCannotReplaceItsPin`, `TestRecordUsageAuthority`, `TestWorkerPresenceAuthority` | +| Chat HTTP: `webui/api_chat.go` | Server stamps sender and person thread; lists/read/turns/cancel/persona verify session ownership. Browser cannot submit another sender identity. | `TestWebChatOwnership`, `TestWebChatSenderCannotBeSuppliedByBrowser`; HTTP deny matrix | +| Chat history, slash commands and model session tools: `gateway/session_store_postgres.go` | Store filters `Get`, `List`, `GetByChannel`; shared read/write guards check person ownership as well as org. A saved session cannot change its conversation source to claim another person's history. Service curation runs without a person principal. | `TestSessionVisibility`; PostgreSQL smoke for history isolation | +| Chat questions/approvals: `webui/api_chat_ask.go` | Waiting question is bound to the initiating person, in addition to its unguessable ID. | `TestChatQuestionBelongsToInitiatingPerson` | +| Chat downloads: `webui/api_chat_files.go` | Offered file token expires and is bound to the initiating person; requests cannot supply a filesystem path. | `TestChatFileDownload` | +| Per-person memory: `archiegateway/chat_identity.go`, gateway memory tools, `sessioncurator` | Verified web sender identity scopes reads/writes. Curator refuses unidentified or mixed participants instead of guessing a person. | Gateway memory and session-curator tests | +| Workflow/task actions: `webui/api_tasks.go`, `domain/taskactions`, `staterpc` | Policy and stored workspace before action; domain transition, authority and durable dispatch guards remain in force. | HTTP deny matrix, task action/domain tests, task grant tests | +| Incoming webhooks: `forge/webhook`, `captureintake`, access delivery engine | Verify HMAC before parsing; derive source/org from stored source; evaluate source delivery policies and egress rules. No browser-user credential is inferred. | Webhook/capture tests, `TestAuthorizeDelivery` | +| Control-plane configuration, secrets, harness and extensions | Browser policy and instance-only restrictions where registered; service contracts carry principal/org; task grants cannot invoke administrative RPCs. | HTTP deny matrix, `TestAdministrationRoutes`, `TestChannelReloadRoute`, `TestConfineHarnessOrg` | +| Live HTTP/SSE and diagnostics | Authenticated policy gate applies before stream creation; org-scoped event reads; instance logs require administrative visibility. | HTTP deny matrix, instance-only tests, `TestServiceLogsRequireInstanceCredential` | +| Background schedules, dispatch, curation | Service/agent authority, not an implicit browser user. Task-scoped grants and org scopes remain distinct from initiating human attribution. | Existing dispatch, grant, memory and org-scope tests | The policy HTTP matrix enumerates each registered protected route. It checks both anonymous refusal and refusal by an explicit Cedar forbid, using the real @@ -93,8 +99,9 @@ they do not contain user data. `/health/detailed` remains protected. Personal routes under `/api/account/` require an active signed-in person and server-derived ownership: password change, recovery-secret generation, passkey -begin/finish/list/delete. They do not require an organization administrator role. -`POST /api/accounts` and `/api/authentication` are administrative policy routes. +begin/finish/list/delete. They do not require an organization administrator +role. `POST /api/accounts` and `/api/authentication` are administrative policy +routes. ## HTTP route inventory @@ -102,120 +109,120 @@ The following routes are covered by `TestHTTPPolicyCannotBeBypassed` in `internal/webui/authorization_surfaces_test.go`. `authorize.go` maps each to its action/resource; the handler may impose a stricter record or instance boundary. -| Method | Route example | -| --- | --- | -| DELETE | `/api/access/policies` | -| DELETE | `/api/bindings/7` | -| DELETE | `/api/event-types/7` | -| DELETE | `/api/extensions/sample` | -| DELETE | `/api/mappings/7` | -| DELETE | `/api/orgs/7/members/sample` | -| DELETE | `/api/sources/sample` | -| DELETE | `/api/tokens/7` | -| GET | `/api/access/policies` | -| GET | `/api/alerts` | -| GET | `/api/authentication` | -| GET | `/api/bindings` | -| GET | `/api/bindings/7` | -| GET | `/api/bindings/7/dispatches` | -| GET | `/api/capabilities` | -| GET | `/api/captures` | -| GET | `/api/captures/7/dispatches` | -| GET | `/api/channels` | -| GET | `/api/chat/file/sample` | -| GET | `/api/chat/sessions` | -| GET | `/api/chat/sessions/7/messages` | -| GET | `/api/chat/sessions/7/turns` | -| GET | `/api/chat/update` | -| GET | `/api/config` | -| GET | `/api/control-plane/apply-status` | -| GET | `/api/control-plane/audit` | -| GET | `/api/control-plane/catalog` | -| GET | `/api/control-plane/resources/sample` | -| GET | `/api/control-plane/resources/sample/history` | -| GET | `/api/curators` | -| GET | `/api/event-types` | -| GET | `/api/extensions` | -| GET | `/api/extensions/catalogue` | -| GET | `/api/harness/bindings` | -| GET | `/api/harness/terminal` | -| GET | `/api/identities` | -| GET | `/api/logs` | -| GET | `/api/mappings` | -| GET | `/api/mappings/7` | -| GET | `/api/orgs` | -| GET | `/api/orgs/7` | -| GET | `/api/orgs/7/members` | -| GET | `/api/orgs/7/workspaces` | -| GET | `/api/secret-engines` | -| GET | `/api/services` | -| GET | `/api/setup` | -| GET | `/api/skills` | -| GET | `/api/sources` | -| GET | `/api/stream` | -| GET | `/api/summary` | -| GET | `/api/task-meta` | -| GET | `/api/tasks` | -| GET | `/api/tasks/7` | -| GET | `/api/tasks/7/attempts` | -| GET | `/api/tasks/7/changes` | -| GET | `/api/tasks/7/debug` | -| GET | `/api/tasks/7/dispatches` | -| GET | `/api/tasks/7/logs` | -| GET | `/api/tasks/7/logs/download` | -| GET | `/api/tasks/7/sandbox` | -| GET | `/api/tokens` | -| GET | `/api/version` | -| GET | `/api/workflows` | -| PATCH | `/api/bindings/7` | -| PATCH | `/api/mappings/7` | -| POST | `/api/accounts` | -| POST | `/api/alerts/7/dismiss` | -| POST | `/api/bindings` | -| POST | `/api/bindings/7/approve` | -| POST | `/api/bindings/7/pause` | -| POST | `/api/bindings/7/resume` | -| POST | `/api/channels/7/reload` | -| POST | `/api/chat/answer` | -| POST | `/api/chat/cancel` | -| POST | `/api/chat/message` | -| POST | `/api/chat/persona` | -| POST | `/api/chat/stream` | -| POST | `/api/chat/update/defer` | -| POST | `/api/chat/update/install` | -| POST | `/api/control-plane/resources/sample/commands/sample` | -| POST | `/api/event-types` | -| POST | `/api/extensions` | -| POST | `/api/extensions/catalogue/sample/install` | -| POST | `/api/extensions/sample/accept` | -| POST | `/api/extensions/sample/approve-update` | -| POST | `/api/extensions/sample/rollback` | -| POST | `/api/extensions/sample/update` | -| POST | `/api/identities` | -| POST | `/api/identities/7/sample` | -| POST | `/api/mappings` | -| POST | `/api/mappings/preview` | -| POST | `/api/orgs` | -| POST | `/api/orgs/7/members` | -| POST | `/api/orgs/7/workspaces` | -| POST | `/api/secret-references/check` | -| POST | `/api/sources` | -| POST | `/api/sources/sample/approve-unsigned` | -| POST | `/api/sources/sample/secret` | -| POST | `/api/sources/sample/signing` | -| POST | `/api/tasks/7/action` | -| POST | `/api/tokens` | -| POST | `/api/work-requests` | -| PUT | `/api/access/policies` | -| PUT | `/api/authentication` | -| PUT | `/api/event-types/7` | -| PUT | `/api/extensions/sample/enabled` | -| PUT | `/api/extensions/sample/update-policy` | -| PUT | `/api/orgs/7/agents/sample` | -| PUT | `/api/orgs/7/members/sample` | -| PUT | `/api/sources/sample/delivery-header` | -| PUT | `/api/sources/sample/name` | -| PUT | `/api/workflows/7/enabled` | +| Method | Route example | +| ------ | ----------------------------------------------------- | +| DELETE | `/api/access/policies` | +| DELETE | `/api/bindings/7` | +| DELETE | `/api/event-types/7` | +| DELETE | `/api/extensions/sample` | +| DELETE | `/api/mappings/7` | +| DELETE | `/api/orgs/7/members/sample` | +| DELETE | `/api/sources/sample` | +| DELETE | `/api/tokens/7` | +| GET | `/api/access/policies` | +| GET | `/api/alerts` | +| GET | `/api/authentication` | +| GET | `/api/bindings` | +| GET | `/api/bindings/7` | +| GET | `/api/bindings/7/dispatches` | +| GET | `/api/capabilities` | +| GET | `/api/captures` | +| GET | `/api/captures/7/dispatches` | +| GET | `/api/channels` | +| GET | `/api/chat/file/sample` | +| GET | `/api/chat/sessions` | +| GET | `/api/chat/sessions/7/messages` | +| GET | `/api/chat/sessions/7/turns` | +| GET | `/api/chat/update` | +| GET | `/api/config` | +| GET | `/api/control-plane/apply-status` | +| GET | `/api/control-plane/audit` | +| GET | `/api/control-plane/catalog` | +| GET | `/api/control-plane/resources/sample` | +| GET | `/api/control-plane/resources/sample/history` | +| GET | `/api/curators` | +| GET | `/api/event-types` | +| GET | `/api/extensions` | +| GET | `/api/extensions/catalogue` | +| GET | `/api/harness/bindings` | +| GET | `/api/harness/terminal` | +| GET | `/api/identities` | +| GET | `/api/logs` | +| GET | `/api/mappings` | +| GET | `/api/mappings/7` | +| GET | `/api/orgs` | +| GET | `/api/orgs/7` | +| GET | `/api/orgs/7/members` | +| GET | `/api/orgs/7/workspaces` | +| GET | `/api/secret-engines` | +| GET | `/api/services` | +| GET | `/api/setup` | +| GET | `/api/skills` | +| GET | `/api/sources` | +| GET | `/api/stream` | +| GET | `/api/summary` | +| GET | `/api/task-meta` | +| GET | `/api/tasks` | +| GET | `/api/tasks/7` | +| GET | `/api/tasks/7/attempts` | +| GET | `/api/tasks/7/changes` | +| GET | `/api/tasks/7/debug` | +| GET | `/api/tasks/7/dispatches` | +| GET | `/api/tasks/7/logs` | +| GET | `/api/tasks/7/logs/download` | +| GET | `/api/tasks/7/sandbox` | +| GET | `/api/tokens` | +| GET | `/api/version` | +| GET | `/api/workflows` | +| PATCH | `/api/bindings/7` | +| PATCH | `/api/mappings/7` | +| POST | `/api/accounts` | +| POST | `/api/alerts/7/dismiss` | +| POST | `/api/bindings` | +| POST | `/api/bindings/7/approve` | +| POST | `/api/bindings/7/pause` | +| POST | `/api/bindings/7/resume` | +| POST | `/api/channels/7/reload` | +| POST | `/api/chat/answer` | +| POST | `/api/chat/cancel` | +| POST | `/api/chat/message` | +| POST | `/api/chat/persona` | +| POST | `/api/chat/stream` | +| POST | `/api/chat/update/defer` | +| POST | `/api/chat/update/install` | +| POST | `/api/control-plane/resources/sample/commands/sample` | +| POST | `/api/event-types` | +| POST | `/api/extensions` | +| POST | `/api/extensions/catalogue/sample/install` | +| POST | `/api/extensions/sample/accept` | +| POST | `/api/extensions/sample/approve-update` | +| POST | `/api/extensions/sample/rollback` | +| POST | `/api/extensions/sample/update` | +| POST | `/api/identities` | +| POST | `/api/identities/7/sample` | +| POST | `/api/mappings` | +| POST | `/api/mappings/preview` | +| POST | `/api/orgs` | +| POST | `/api/orgs/7/members` | +| POST | `/api/orgs/7/workspaces` | +| POST | `/api/secret-references/check` | +| POST | `/api/sources` | +| POST | `/api/sources/sample/approve-unsigned` | +| POST | `/api/sources/sample/secret` | +| POST | `/api/sources/sample/signing` | +| POST | `/api/tasks/7/action` | +| POST | `/api/tokens` | +| POST | `/api/work-requests` | +| PUT | `/api/access/policies` | +| PUT | `/api/authentication` | +| PUT | `/api/event-types/7` | +| PUT | `/api/extensions/sample/enabled` | +| PUT | `/api/extensions/sample/update-policy` | +| PUT | `/api/orgs/7/agents/sample` | +| PUT | `/api/orgs/7/members/sample` | +| PUT | `/api/sources/sample/delivery-header` | +| PUT | `/api/sources/sample/name` | +| PUT | `/api/workflows/7/enabled` | ## Verification limits @@ -224,9 +231,9 @@ security key or every operating system. An OIDC unit test is not acceptance against a deployed provider. Disposable PostgreSQL smoke checks verify real SQL without putting database-dependent tests in the fast unit suite. -Existing anonymous conversations are retained but are not silently assigned to -a new person. Existing service credentials remain privileged; this inventory -does not claim that all internal gRPC methods have independent Cedar gates. +Existing anonymous conversations are retained but are not silently assigned to a +new person. Existing service credentials remain privileged; this inventory does +not claim that all internal gRPC methods have independent Cedar gates. When changing a user-facing operation, update its inventory entry and its allow/deny behavior cases. Include another user in the same organization, a