docs: edit guides, PRDs and security notes, regenerate release news

This commit is contained in:
sam committed 2026-10-19 10:04:36 +11:00
1 parent 1f11ee0fea
commit 9cd1495838
7 files changed
+458 -457

No files matched your search

+20 -9
View File
@@ -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!
---
+33 -36
View File
@@ -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 `<source>` 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.
+5 -5
View File
@@ -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-<timestamp>.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
+1 -1
View File
@@ -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/"
}
}
+1 -1
View File
@@ -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"
}
]
]
+229 -243
View File
@@ -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.
+169 -162
View File
@@ -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