a7d6f71d5a2c9da170a46bfc4471f9979189de87
3
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
2cb2275eb6
|
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. |
||
|
|
85e27e3778
|
docs(prds): cement A2A as the agent-to-agent protocol
Sam's decision, recorded as requirements rather than options. A2A carries agent-to-agent work: discovery of what a remote agent offers, delegation of a unit of work, progress on it, and the artifacts it produces. MCP stays the tool layer -- the two are complementary, and internal/tools/provider already registers MCP providers as optional capabilities. A2A rides archie's existing transports, which the protocol permits: its canonical data model is Protocol Buffer messages and it defines a gRPC binding, so archie speaks it over the gRPC and NATS it already runs. The boundaries are requirements. internal/domain/messaging stays the human and channel layer, because a Conversation is a ChannelID and a ThreadID and its participants are people. internal/agentexec stays the daemon-to-worker execution protocol, whose Request, Result, gate and budget policy A2A never carries. A2A is an edge protocol that composes with both. The load-bearing decision, and the one that constrains everything downstream: archie's work lifecycle is MAPPED to A2A's, not expressed in it. An A2A task is a view over archie's own task, and archie's status stays the record of truth. Three gaps make the mapping partial, and each is a fact A2A's states cannot hold: A2A's terminal states describe what the agent did, while archie's merged and rejected describe what a forge did afterwards; pr_open hands work to a human reviewer, while A2A's input-required means the CLIENT must send more input; and declined, parked and dead are outcomes of archie's own policy. Adopting A2A's state names as the persisted task status is rejected outright -- it would migrate the task store and drop the forge outcomes that tell a caller whether the work was accepted. An A2A agent is an Identity: the actor archie persists, versions and scopes credentials to. A persona is prompt text with no endpoint; an agent container is task-scoped and ephemeral; the daemon is the process that serves the identity. The Gateway serves the card for the identity it is configured as, over the gRPC binding's Get Agent Card operation, and the card is derived -- skills from the catalog, identity from configuration, capabilities from what the process already advertises -- never hand-written, and carries no secret. archie is a server first, because the work a peer would delegate exists only inside archie. An inbound call is authenticated at the transport by the bearer-token interceptor the Gateway already applies: A2A carries no identity in its payload, so the transport credential is the identity. Authorization is per skill, which is A2A's own model. Task-scoped grants are not A2A credentials -- reusing one would let a peer act with a worker's authority -- and the dashboard's authentication gates an operator interface, not an agent endpoint. The new PRD is a development-audience page, so it regenerates the development artifact rather than the public one: dev-docs.json goes to 68 pages and docs.json is unchanged. Verified: task check exit 0, including docs:prds, and both docsite checks. |
||
|
|
a75df5eb0c
|
feat(docs): split the published set by audience, public and development
The site's sidebar held the landing page and one guide next to seventeen architecture records, the migration register, the review procedure and five PRDs. Nothing there is secret -- every development page may be read by anyone -- but a reader who wants to know what Archie is and how to point an event at it was meeting contributor material with no signal that it was not for them. One source tree now yields two sets: public (index, guides/) under /docs/, and development (architecture/, prds/) under /dev/, each with its own artifact and its own derived sidebar. archive/, inspiration/, news/ and the credential notes stay out of both, unchanged. Selective PRD publication is gone rather than carried over. It existed only because settled architecture cites PRDs and a link to a held-back target fails the generator, so five PRDs published to keep those citations alive; with both halves of every such citation in the development set, the exception has no work left to do. Both sets are generated in one pass over one url map, so a citation that crosses between them resolves to the base its target is served under, and the refusal now fires only for a target genuinely in neither set. Widening the set exposed a scanner bug worth its own note: the link regex matched `Resolve[T](i, src, exportPath)` inside a code span and refused the page for a link to `i,`. Code spans and fenced blocks are now skipped, because what a renderer draws as a link is the only thing this tool may rewrite or refuse a page for. docs/prds/public-and-dev-docs.md records the decision. Draft: the three choices in it are the maintainer's, the write-up is not yet reviewed. |