diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 5a1bbd6a2..b3d761184 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -244,7 +244,7 @@ "url": "/dev/prds/event-automation/", "title": "Event automation: identified events, typed parameters, purpose-built agents", "section": "PRDs", - "body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools,\n repo) profile) secrets, access)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required` gives the agent a worktree of the task's repository.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another workflow. The call passes the callee's\ninputs, and the callee runs as its own run with its own agent profile, so one\nevent can start an investigator that then calls a containment workflow:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n inputs: { src_ip: inputs.src_ip }\n wait: true # false starts the callee and continues\n```\n\n- With `wait: true` the caller receives the callee's outputs and fails if the\n callee fails. With `wait: false` the caller continues and the callee's\n outcome is reported on its own run.\n- A call's inputs are checked against the callee's declared inputs when the\n calling workflow is saved.\n- A workflow that calls itself, directly or through other workflows, is\n refused when it is saved. Calls are limited to a fixed depth at run time.\n- A callee must be enabled for the caller's org.\n\n### Bindings\n\nA binding connects an event type to one workflow:\n\n- an optional filter on mapped parameters (`severity in [\"high\", \"critical\"]`),\n written in the CEL the playbook engine already uses;\n- an assignment of workflow inputs from mapped parameters or constants,\n checked against the workflow's declared inputs when the binding is saved;\n- a repository, when the workflow's `repository` is not `none`: either fixed\n (`acme/api`) or taken from a parameter (the GitHub webhook's\n `repository.full_name`).\n\nAny number of bindings may use one event type. Approval and re-approval after\nan edit are unchanged. A binding whose workflow input types no longer match is\nrefused at dispatch and reported on the binding.\n\n### Agent profiles\n\nA profile is a named execution environment that a workflow selects:\n\n- the container image;\n- the tools the agent may call;\n- the secrets injected into it, by reference to the secret store, never\n inline;\n- its network access and forge access.\n\nThe global `[containers].image` becomes the default profile, so existing\nworkflows are unchanged. A secret or permission is granted to a profile, not\nto a binding, so an event can never widen what an agent can do.\n\n### Workflows belong to orgs\n\nArchie ships a default workflow catalogue that every org can use. An org can\nadd its own workflows, and can enable or disable any workflow, default or its\nown, for itself. A binding can target only a workflow enabled for its org, and\ndisabling a workflow stops its bindings dispatching and marks them on the\nbinding list.\n\n## Delivery order\n\n1. Event types: structural signatures, grouping, naming, match rules, and the\n inspector view of proposed and unidentified events.\n2. Mappings per event type, and multiple bindings per source.\n3. Workflow inputs, structured parameters in the task brief, and\n `repository: none | optional | required`.\n4. Agent profiles with image, tools, secret references and access.\n5. Signing as a source setting, with the unsigned option; UUIDv7 source paths\n with a custom-path override.\n6. Workflows calling workflows, with declared outputs.\n7. Org-scoped workflow catalogue, once orgs exist.\n\nEach step ships usable on its own. Step 3 is the first where an event that has\nnothing to do with a repository can run a workflow.\n\n## Out of scope\n\n- How forge-issue playbook triggers (`internal/domain/eda/playbook`) relate to\n event types. They stay as they are until event types exist.\n- Built-in catalogues of event types for known senders.\n- Orgs themselves: membership, access, and how sources and bindings belong to\n one. This design needs only an org to own workflows and their enabled state.\n- Running an agent outside a container.\n\n## Verification\n\n- Two GitHub webhooks with different `X-GitHub-Event` headers posted to one\n source are grouped into two proposed event types, and a firewall payload\n with a different shape is grouped separately.\n- A capture matching no named type is shown as unidentified and starts\n nothing.\n- A firewall event runs a `repository: none` workflow with its mapped inputs\n readable by the agent as structured data, and no clone is made.\n- A GitHub `pull_request.opened` event runs a PR review workflow against the\n repository named in the payload.\n- An event type created from a pasted payload has that payload's schema, and a\n later matching event is identified as it.\n- A new source gets a UUIDv7 path; a custom path that is already taken is\n refused.\n- A workflow that calls another with `wait: true` receives its outputs; one\n that calls itself through another workflow is refused when saved.\n- A mapping's matched-event count rises by one for each event it resolves.\n- A workflow disabled for an org cannot be targeted, and its existing bindings\n stop dispatching.\n- A binding whose filter excludes an event does not dispatch it.\n- An agent receives only the secrets its profile references.\n- An unsigned event on a signed source is captured and not dispatched. An\n event on an unsigned source is dispatched and marked unsigned.\n" + "body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools,\n repo) profile) secrets, access)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required` gives the agent a worktree of the task's repository.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another workflow. The call passes the callee's\ninputs, and the callee runs as its own run with its own agent profile, so one\nevent can start an investigator that then calls a containment workflow:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n inputs: { src_ip: inputs.src_ip }\n wait: true # false starts the callee and continues\n```\n\n- With `wait: true` the caller receives the callee's outputs and fails if the\n callee fails. With `wait: false` the caller continues and the callee's\n outcome is reported on its own run.\n- A call's inputs are checked against the callee's declared inputs when the\n calling workflow is saved.\n- A workflow that calls itself, directly or through other workflows, is\n refused when it is saved. Calls are limited to a fixed depth at run time.\n- A callee must be enabled for the caller's org.\n\n### Bindings\n\nA binding connects an event type to one workflow:\n\n- an optional filter on mapped parameters (`severity in [\"high\", \"critical\"]`),\n written in the CEL the playbook engine already uses;\n- an assignment of workflow inputs from mapped parameters or constants,\n checked against the workflow's declared inputs when the binding is saved;\n- a repository, when the workflow's `repository` is not `none`: either fixed\n (`acme/api`) or taken from a parameter (the GitHub webhook's\n `repository.full_name`).\n\nAny number of bindings may use one event type. Approval and re-approval after\nan edit are unchanged. A binding whose workflow input types no longer match is\nrefused at dispatch and reported on the binding.\n\n### Agent profiles\n\nA profile is a named execution environment that a workflow selects:\n\n- the container image;\n- the tools the agent may call;\n- the secrets injected into it, by reference to the secret store, never\n inline (superseded by `docs/prds/orgs-and-access.md`: secrets are granted to\n identities, and a profile holds no secrets);\n- its network access and forge access.\n\nThe global `[containers].image` becomes the default profile, so existing\nworkflows are unchanged. A secret or permission is granted to an identity, never to a binding, so an\nevent can never widen what an agent can do (`docs/prds/orgs-and-access.md`).\n\n### Workflows belong to orgs\n\nArchie ships a default workflow catalogue that every org can use. An org can\nadd its own workflows, and can enable or disable any workflow, default or its\nown, for itself. A binding can target only a workflow enabled for its org, and\ndisabling a workflow stops its bindings dispatching and marks them on the\nbinding list.\n\n## Delivery order\n\n1. Event types: structural signatures, grouping, naming, match rules, and the\n inspector view of proposed and unidentified events.\n2. Mappings per event type, and multiple bindings per source.\n3. Workflow inputs, structured parameters in the task brief, and\n `repository: none | optional | required`.\n4. Agent profiles with image, tools, secret references and access.\n5. Signing as a source setting, with the unsigned option; UUIDv7 source paths\n with a custom-path override.\n6. Workflows calling workflows, with declared outputs.\n7. Org-scoped workflow catalogue, once orgs exist.\n\nEach step ships usable on its own. Step 3 is the first where an event that has\nnothing to do with a repository can run a workflow.\n\n## Out of scope\n\n- How forge-issue playbook triggers (`internal/domain/eda/playbook`) relate to\n event types. They stay as they are until event types exist.\n- Built-in catalogues of event types for known senders.\n- Orgs themselves: membership, access, and how sources and bindings belong to\n one. This design needs only an org to own workflows and their enabled state.\n- Running an agent outside a container.\n\n## Verification\n\n- Two GitHub webhooks with different `X-GitHub-Event` headers posted to one\n source are grouped into two proposed event types, and a firewall payload\n with a different shape is grouped separately.\n- A capture matching no named type is shown as unidentified and starts\n nothing.\n- A firewall event runs a `repository: none` workflow with its mapped inputs\n readable by the agent as structured data, and no clone is made.\n- A GitHub `pull_request.opened` event runs a PR review workflow against the\n repository named in the payload.\n- An event type created from a pasted payload has that payload's schema, and a\n later matching event is identified as it.\n- A new source gets a UUIDv7 path; a custom path that is already taken is\n refused.\n- A workflow that calls another with `wait: true` receives its outputs; one\n that calls itself through another workflow is refused when saved.\n- A mapping's matched-event count rises by one for each event it resolves.\n- A workflow disabled for an org cannot be targeted, and its existing bindings\n stop dispatching.\n- A binding whose filter excludes an event does not dispatch it.\n- An agent receives only the secrets its identity is granted.\n- An unsigned event on a signed source is captured and not dispatched. An\n event on an unsigned source is dispatched and marked unsigned.\n" }, { "url": "/dev/prds/event-capture-storage/", diff --git a/docs/prds/event-automation.md b/docs/prds/event-automation.md index 71f9bb752..9cca0bc6c 100644 --- a/docs/prds/event-automation.md +++ b/docs/prds/event-automation.md @@ -155,12 +155,13 @@ A profile is a named execution environment that a workflow selects: - the container image; - the tools the agent may call; - the secrets injected into it, by reference to the secret store, never - inline; + inline (superseded by `docs/prds/orgs-and-access.md`: secrets are granted to + identities, and a profile holds no secrets); - its network access and forge access. The global `[containers].image` becomes the default profile, so existing -workflows are unchanged. A secret or permission is granted to a profile, not -to a binding, so an event can never widen what an agent can do. +workflows are unchanged. A secret or permission is granted to an identity, never to a binding, so an +event can never widen what an agent can do (`docs/prds/orgs-and-access.md`). ### Workflows belong to orgs @@ -216,6 +217,6 @@ nothing to do with a repository can run a workflow. - A workflow disabled for an org cannot be targeted, and its existing bindings stop dispatching. - A binding whose filter excludes an event does not dispatch it. -- An agent receives only the secrets its profile references. +- An agent receives only the secrets its identity is granted. - An unsigned event on a signed source is captured and not dispatched. An event on an unsigned source is dispatched and marked unsigned. diff --git a/docs/prds/orgs-and-access.md b/docs/prds/orgs-and-access.md new file mode 100644 index 000000000..2d197bb79 --- /dev/null +++ b/docs/prds/orgs-and-access.md @@ -0,0 +1,266 @@ +# Orgs, workspaces and access control + +**Status:** Approved +**Date:** 2026-09-24 +**Parent:** `docs/prds/event-automation.md`, epic `archie-core-t2db` + +## Why this exists + +Archie has no tenant boundary and no access control: one operator, one shared +token, and no org on any record. The event automation design needs orgs to own +sources, bindings, workflows and agents, and an agent's reach must be decided +by the policies over it, never by the event that started it. + +## Concepts + +- **Org.** The tenant boundary. An instance admin creates an org and adds its + first owner. An owner or admin adds further members by the sign-in + provider's subject or email. +- **Workspace.** A division of an org, named freely (`networking-prd`, + `service-desk-dev`), with an optional `environment` attribute (any string) + that policies can test. Sources, event types, mappings, bindings and runs + belong to a workspace. +- **Identity.** Every principal is an identity (`internal/domain/identity`): + - a person is an identity of kind `user`, bound to the sign-in provider + through the existing subject binding; + - an agent is an identity of kind `bot` or `service_account`, assigned to + one org and granted access, secrets and permissions the way a user is. + + Signing in and verifying credentials stay separate from identity; identity + is who acts. Memberships, roles, grants and audit records all reference the + identity ID. +- **Instance admin.** Operates the installation: orgs, the sign-in provider, + instance policies. Instance admins see an org's resources only as members + of it. + +## What belongs where + +| Level | Owns | +|---|---| +| Instance | the shipped workflow catalogue, instance policies | +| Org | members, identities and their grants, secrets, agent profiles, workspaces, org workflows and their enabled state | +| Workspace | sources, event types, mappings, bindings, runs, captures, run events and logs, chat sessions, memory | + +Every owned record carries its `org_id`, and workspace records also carry their +`workspace_id`. An identity, secret or profile is used in a workspace only +after the org grants it to that workspace. + +A secret is granted to an identity. An agent profile holds the container +image, tools and network access, and no secrets; this supersedes the secret +references in `event-automation.md`'s agent profiles. + +A workflow names the identity it runs as. A workflow called by another runs +as its own identity, and the caller's identity must be permitted `run` on it. + +## Access decisions + +### Where it lives + +- `internal/domain/access` owns the policy schema, the action list, how + principals and resources are turned into policy entities, and the + `Authorizer` contract. +- The Cedar implementation, using `github.com/cedar-policy/cedar-go`, lives in + `internal/infrastructure/access`; `internal/app` wires it. +- Exactly two places call the `Authorizer`: the dashboard and API request + path, and dispatch. Every other service verifies a credential and never + evaluates policy. + +### The model + +- **Principal:** an identity, with its memberships, roles and grants. +- **Resource:** the record acted on, with its workspace and org as parents, + its type, owner and state. +- **Action:** one of `read`, `create`, `update`, `delete`, `approve`, `run`, + `read_logs`, `read_secret`, `manage_members`, `manage_identities`, + `manage_policies`. +- **Context:** the event's signature result, the address it came from, the + time, and the run and step when the principal is an agent. + +### The policy chain + +``` +instance (+ network rules) ─▶ org ─▶ workspace ─▶ identity + workflow ─▶ object +``` + +- **Instance** policies hold across every org. They include network rules: + which addresses may deliver events to any source on the instance. +- **Object** policies attach to one object (an event source, a secret, an + identity, a binding, a workflow): "only `soc-responder` may read this + secret", "this source accepts events only from 10.20.0.0/16". +- A request is allowed only if every level with policies for it permits it. A + lower level narrows and never widens; a forbid at any level wins; with no + permit the request is denied. +- The shipped role policies mean the org level always has policies, so an + object or workspace policy alone can never grant access. +- Archie ships an instance policy, which no org can remove, forbidding any + principal to act on a resource outside the orgs it belongs to. + +### Storing and changing policies + +- Policies are stored in the State Store per level, versioned, and every + change is an audit event naming who made it. +- A policy is checked against the current schema when it is saved, and every + stored policy is checked again when archie starts. An invalid org, workspace + or object policy makes its level deny everything and is reported as a health + issue naming the policy and the error. An invalid instance policy stops + archie serving until it is fixed, with the same report. +- A policy change that would leave no owner able to `manage_policies` is + refused. + +### Roles + +Archie ships these org roles as policies. A member may hold a different role in +each workspace. + +| Role | Can | +|---|---| +| Owner | everything in the org, including members, identities, policies and deleting the org | +| Admin | everything except deleting the org and changing owners | +| Developer | create and edit workspace resources and org workflows; run workflows; read logs | +| Viewer | read everything except secret values | + +### Approvals + +What needs approval, and who may give it, is org and workspace policy. Archie +ships one default: arming a binding needs a member other than the one who made +the change, holding the admin or owner role. No policy can let a change approve +itself. + +### Denials + +- A lookup is filtered by org before any policy check, so a record in another + org is never loaded and is reported as not found, with the same error the + store returns for a record that does not exist. +- A request denied inside the caller's org is reported as forbidden, without + the reason. +- Every denial is recorded with the principal, action, resource, the level + that decided, and the deciding policies. Admins can see this record for + their org; instance admins for instance policies. + +### Recovering from a locked-out org + +`archied access reset --org ` restores the shipped role policies for one +org and removes its other org-level policies; `--instance` does the same for +instance policies. It runs only on the State Store host, never over the +network, and is recorded as an audit event. + +## Credentials + +### People and services + +- The State Store accepts two kinds of credential: the instance service + credential, held by the daemon and Gateway for dispatch and background work + across orgs, with every use attributed; and a principal credential issued to + one identity, from which the State Store derives the org and workspace scope + itself. No request field sets scope. +- A person signs in through the provider or uses a personal API token issued + to their identity. The shared token of a single-operator install + authenticates as the owner of the `default` org. +- If the sign-in provider is unreachable, sign-in fails with a health issue + distinct from a rejected credential, `archied access reset` still works, and + dispatch and running agents are unaffected. + +### Agents: decided once, carried as a run credential + +1. When a binding dispatches, the orchestrator evaluates the chain for the + workflow's identity: the identity may `run` this workflow in this + workspace, and the workflow and binding are enabled. +2. It issues one run credential holding the org, workspace, run, workflow, + identity, and the capabilities and secrets the identity is granted, + narrowed by the workflow's policy. This single credential replaces the + separate State Store and worktree grants. +3. The State Store, forge RPC, worktree RPC and secret retrieval each verify + every call against the credential and refuse anything outside it, recording + the refusal on the run. None of them evaluates policy. The State Store's + task-scoped calls stay limited to updating, transitioning and adding events + to the credential's own run. +4. The credential lives in the State Store, stored as a digest, so it survives + a restart. It expires at the workflow's timeout plus a margin, is revoked + when the run ends, and credentials of runs that are no longer running are + revoked when archie starts. A run whose credential is refused as unknown is + parked for retry, not failed. +5. Starting an identity is recorded as an audit event: identity, run, + workflow, the binding or member that started it, and the event behind it. + The State Store stamps the actor, principal, org and workspace on every + event from the credential and ignores those fields in the request. + +Forge RPC subjects are keyed by the identity's immutable ID, so identities with +the same name in two orgs never share a responder. + +## Events and task identity + +- The capture receiver is the only place network rules are evaluated. A + refused event is not stored; it is counted on its source with the address it + came from (the most recent addresses only). A source that refuses more + events than it accepts over an hour is reported as a health issue. +- The task idempotency key is `org/identity/owner/repo/number`, produced in one + place. The poller and the webhook receiver both resolve the org and identity + before publishing, so the same issue delivered both ways still gives one + key. The review-comment key follows the same rule. Task uniqueness in the + store uses the same fields. + +## Upgrading existing installs + +- An install with no sign-in provider has one org, `default`, with one + workspace, `default`, and the local operator as owner. +- The upgrade runs in the State Store first, then in the event store, each + resumable from a recorded version, after a backup of the database. Every + existing record gets the `default` org and workspace, and every existing + identity belongs to the `default` org. +- The State Store refuses scoped calls until its upgrade has finished, rather + than serving records with no org. +- People's identities and memberships live in the State Store, not the event + store. + +## Audit retention + +Audit and denial records are kept for a configured number of days. Repeated +identical denials within a minute are stored once with a count. Their size is +shown on the health surface. + +## Delivery order + +1. Orgs, workspaces, people as identities, memberships, identities assigned to + orgs; `org_id` and `workspace_id` on every owned record; the resumable + `default` upgrade; the new idempotency key. +2. `internal/domain/access` with the chain, shipped roles, the cross-org + forbid and the startup re-check; applied to the dashboard, API and + dispatch; denial records; `archied access reset`. +3. Instance and principal credentials with server-derived scope; personal API + tokens. +4. Identity grants; the run credential replacing both existing grants; audit + on every start. +5. Approval policy with the shipped default. +6. Instance network rules at the capture receiver, and object policies. +7. Org, workspace and object policy editing. + +## Out of scope + +- Self-service org sign-up, billing and quotas. +- Groups or teams as principals. +- Agents acting with the permissions of the person who triggered an event. + +## Verification + +- A member of org A reading an org B record by ID gets the store's ordinary + not-found error, and org B records never appear in org A's lists. +- A workspace policy permitting what its org forbids has no effect. +- A developer can create a binding and cannot approve it; an admin can. +- A policy naming an unknown attribute is refused when saved; a stored policy + that became invalid after an upgrade denies its level and shows as a health + issue. +- A policy change leaving no owner with `manage_policies` is refused, and + `archied access reset --org` restores access for a locked-out org. +- An identity not granted `secret:firewall-api` cannot retrieve it, and the + refusal is on its run. +- A run keeps working across a State Store restart, and a crashed run's + credential is revoked at the next start. +- Every run shows the identity it started and what started it. +- An instance network rule refuses an event from outside its range for every + org, and the refusal is counted on the source. +- An object policy on a secret narrows which identities can read it. +- A policy forbidding `run` where `environment` is `production` applies to + every such workspace. +- The same issue delivered by webhook and by poll produces one task. +- A single-operator install upgrades with every record in `default` and works + unchanged; an interrupted upgrade resumes.