docs(prds): settle identity for users, agents and external agents

One identity record covers users, agents, external agents, service accounts and the
system. Authentication is delegated to the estate's OIDC provider and attribution
stays archie's. Nothing that verifies a credential, issues a session, stores a
password or checks a permission is built here, per Sam's hard requirement that
authentication and authorisation are OSS archie integrates.

Authelia is the only provider, because the estate already runs it in front of the
dashboard and it issues credentials for both kinds of caller: authorization code
for humans and client_credentials for machines, whose subject is the client's own
identifier. Each agent is its own client, so two agents are distinguishable in the
audit trail and revocable separately. SPIFFE/SPIRE is rejected on operational fit
rather than quality: it is adopted and its attestation is strictly stronger, but it
adds a control plane archie does not have and answers a threat archie does not face
while its agents run in containers the operator launches.

internal/domain/identity survives and is not replaced by the provider's directory,
because it carries what the directory does not: lifecycle, bindings and
attribution. archie owns the subject binding that ties an identity to the provider
subject asserting it -- the same bridge identity_aliases already provides from a
legacy name -- plus the lifecycle, the attribution and the identity audit trail. It
owns no credential, password, session, token, signing key or permission rule.

How an agent proves who it is: it presents a token the provider issued to its own
client, archie validates it against the provider's published keys and takes the
subject as the acting identity, so an agent holds the secret and archie holds only
public keys. A WebMCP tool call cannot be a proof of agent identity and cannot be
made one -- a page can invoke its own tools, so an agent's call and a page script's
call arrive identically and the difference does not exist on the wire. It is
attributed to the identity the request presented with its source as a hint, and it
never records that an agent acted or that a human approved. Agent-initiated action
therefore arrives on a surface that carries a credential.

Task actions gain both attributions: the acting identity, derived from the
credential and never from a supplied string, and the authorising principal whose
authority the action used. The event kind describes the actor, so
KindHumanApproved is recorded only when a human acted; an agent acting under a
standing approval records itself as actor and the human as authorising principal.
An action with no authorising principal is unattributed rather than attributed to
the actor's own authority, and the review gate's approver is the approval's
authorising principal, not the surface they used.

External agents are first-class: the same record, kind service_account, bound to
its own provider client, at the cost of a client registration and a secret to
rotate per peer. Authorisation is deferred: no engine, no policy language, no
decision point, with the credential's scopes as the only input; the decision point
goes behind a single archie interface when per-skill limits are needed.

The PRD is a development-audience page, so it regenerates dev-docs.json to 69
pages. Verified: task check exit 0, including docs:prds.
This commit is contained in:
sam committed 2026-09-22 14:10:55 +10:00
1 parent 2b0439b181
commit 2cb2275eb6
2 files changed
+164

No files matched your search

+10
View File
@@ -240,6 +240,12 @@
"section": "PRDs",
"body": "# Extensions center\n\n**Status:** Draft\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions center\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disableable\" property\nenforced structurally rathLine truncated
},
{
"url": "/dev/prds/identity-decision/",
"title": "Identity for users, agents and external agents — decision",
"section": "PRDs",
"body": "# Identity for users, agents and external agents — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `docs/architecture/organisation.md` for placement;\n`docs/architecture/migration-decisions.md` §3 for the attribution semantics this\ndocument implements; `docs/prds/agent2agent-protocol.md` for the A2A surface that\nconsumes it.\n\n## Decision\n\nOne identity record covers every actor archie has: users, agents, external agents,\nservice accounts and the system. Authentication is delegated to the estate's OIDC\nprovider, and attribution stays archie's.\n\nAuthentication and authorisation are OSS archie integrates; a design that\nhand-rolls either fails this document.\n\n## The provider\n\n**Authelia is the only identity provider**, because the estate already runs it in\nfront of the dashboard and it issues credentials for both kinds of caller: humans\nuse the authorization code flow, and machines use the `client_credentials` grant,\nwhich yields a token whose subject is the client's own identifier.\n\n**Each agent is its own provider client.** A shared client would make two agents\nindistinguishable in the audit trail and revocable only together, which is the\nproperty attribution needs and the reason per-client registration is a\nrequirement.\n\n**SPIFFE/SPIRE is not adopted.** It is adopted and maintained, and its attestation\nis strictly stronger than a secret: a workload proves what it is rather than what\nit holds. It is rejected here on operational fit, not on quality: it adds a\ncontrol plane archie does not have, and the property it buys — identity attested\nfrom the platform rather than from a presented secret — answers a threat archie\ndoes not face, because archie's agents run as containers the operator launches and\nalready receive their credentials from the daemon that owns them. It is the right\nanswer when agents run on infrastructure the operator does not control.\n\n## What archie owns\n\n- **The identity record.** `internal/domain/identity` survives as archie's own\n record of an actor and is not replaced by the provider's directory, because the\n record carries what the directory does not: the lifecycle, the bindings and the\n attribution below.\n- **The lifecycle.** Active, suspended and retired, with rename, suspend,\n reactivate and retire, remain archie's. Suspending an identity must stop it\n acting whether or not the provider still authenticates it.\n- **The subject binding.** An identity that proves itself is bound to the provider\n subject that asserts it. This is the same bridge `identity_aliases` already\n provides from a legacy name to an identity, so the second binding is the same\n mechanism rather than a new one.\n- **Attribution.** Who acted, and under whose authority.\n- **The audit trail of identity changes**, which already records an actor, a source\n and a request identifier for every mutation.\n\n## What archie never owns\n\nA credential, a password, a session, a token, a signing key, a second-factor\nenrollment, or a permission rule.\n\n## How an agent proves who it is\n\n**An agent authenticates by presenting a token the provider issued to its own\nclient**, and archie validates it against the provider's published signing keys and\ntakes its subject as the acting identity. The agent holds a client secret; archie\nholds only the public keys, so a compromised archie cannot mint an identity.\n\n**A WebMCP tool call is not a proof of agent identity and cannot be made one.** A\npage can invoke its own tools, so an agent's call and a page script's call arrive\nat archie identically. No field, header or convention distinguishes them, because\nthe difference does not exist on the wire.\n\n**A WebMCP tool call is therefore attributed to the identity the request\npresented, with its source recorded as a hint.** It may record that the request\ncame from the dashboard; it never records that an agent acted, and it never\nrecords that a human approved. A tool call that a page script can forge must not\nbe the thing an audit trail rests on.\n\n**Agent-initiated action therefore arrives on a surface that carries a credential**\n— the A2A surface, or an authenticated agent call — because that is the only place\nan agent's identity is verifiable. An approval an agent makes is recorded as an\nagent's action.\n\n## The two attributions\n\nEvery task action records two identities, and `taskactions` gains both:\n\n- **The acting identity**: the identity that performed the action, derived from\n the credential the request presented and never from a string the request\n supplied.\n- **The authorising principal**: the identity whose authority the action used.\n\n**The event kind describes the actor.** An action performed by an agent is\nrecorded as an agent's action even when a human's standing approval permitted it,\nso `KindHumanApproved` is recorded only when the acting identity is a human. An\nagent acting under a standing approval rLine truncated
},
{
"url": "/dev/prds/image-capability-contract/",
"title": "Image capability contract and configuration",
@@ -575,6 +581,10 @@
"title": "Extensions center",
"url": "/dev/prds/extensions-center/"
},
{
"title": "Identity for users, agents and external agents — decision",
"url": "/dev/prds/identity-decision/"
},
{
"title": "Image capability contract and configuration",
"url": "/dev/prds/image-capability-contract/"