247 lines
28 KiB
Markdown
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 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
|
|
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.
|