Files
archie/docs/security/authorization.md
T
sam 4de8b67ba8 refactor(workflow): stop assuming a human decides
An approval, ask or park can be resolved by an operator, a rule, a
classifier or automatically, so the vocabulary stops naming a person:

- step type human.approve -> workflow.approve
- park class needs_human -> needs_decision (ParkNeedsDecision)
- event kinds human_* -> operator_*
- alert kind task.needs_human -> task.needs_decision
- status grouping "needs you" -> "needs attention"

0061 rewrites the stored values, including the approval step type in the
workflow-definitions resource and each task's pinned definition, with the
digest recomputed so resumed tasks still match.
2026-10-25 17:31:16 +11:00

247 lines
28 KiB
Markdown

# 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),
including its guidance on attributes and relationships. It describes concrete
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.
Instance service credentials are administrative authority. They are not user
sessions and must never reach a browser, model, or agent container. A service
forwarding a principal preserves attribution and tenant scope; forwarding alone
does not mean every internal RPC evaluates Cedar. Most internal RPCs trust the
authenticated service and enforce their own resource scope. The public HTTP
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.
## 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.
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.
Cedar permission is not ownership of another person's private data. Conversation
history, passkeys, recovery codes and personal tokens are bound to the person.
An organization or instance admin role does not override those relationships.
Account creation uses `manage_members` policy rather than a hard-coded admin
role. Authenticating through OIDC does not automatically grant membership, link
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 operator 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
handler stack. Separate tests exercise allowed requests and personal ownership;
a denied-request matrix alone is not proof that a workflow works end to end.
## Public and personal routes
Public protocol entry points are `GET /api/auth/status`, `POST /api/auth/setup`,
`POST /api/auth/login`, `POST /api/auth/logout`, `POST /api/auth/recover`,
`POST /api/auth/passkey/begin`, `POST /api/auth/passkey/finish`,
`GET /oauth2/login`, `GET /oauth2/callback`, health probes and signed webhook
intake. Each has its own protocol checks. Static embedded app assets are public;
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.
## HTTP route inventory
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` |
## Verification limits
A synthetic browser authenticator verifies protocol behavior, not a physical
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.
When changing a user-facing operation, update its inventory entry and its
allow/deny behavior cases. Include another user in the same organization, a
caller in another organization, a missing principal, unavailable policy storage,
and the applicable owner/workspace/instance restrictions.
Bootstrap is unauthenticated until the first administrator is created. Complete
setup before exposing a new installation to untrusted users. Last-active-owner
protection for identity suspension/retirement is tracked separately as
`archie-core-d7avc`; membership-policy guards are not that lifecycle guard.