diff --git a/docs/prds/prd-new-trusted-agent-forge-identity.md b/docs/prds/prd-new-trusted-agent-forge-identity.md index 4201438c..60ce086b 100644 --- a/docs/prds/prd-new-trusted-agent-forge-identity.md +++ b/docs/prds/prd-new-trusted-agent-forge-identity.md @@ -7,12 +7,13 @@ ## Summary -Move author identity and named forge accounts into host-trusted agent +Move author identity and named forge configurations into host-trusted agent definitions. A bottle may optionally associate a git-gate repository with one -of the selected agent's forge accounts. When associated, bot-bottle gives the +of the selected agent's forge aliases. When associated, bot-bottle gives the agent non-secret, provider-specific system guidance for that repository and routes authenticated forge API calls through the egress proxy without exposing -the account token to the bottle. +the forge token to the bottle. The authenticated account is inferred from the +identity that owns that token; it is not separately declared in the manifest. Repository-local agent and bottle definitions are no longer discovered. Once agent definitions can select a host forge credential, allowing checked-out @@ -49,9 +50,9 @@ review refs instead of a normal branch-backed pull request. ### Identity is owned by the wrong layer `git-gate.user` puts an agent property on a repository transport component. An -author identity and forge actor should follow the agent across bottles and -repositories. Git-gate should own Git transport policy, not decide who the -agent is. +author identity and set of forge credentials should follow the agent across +bottles and repositories. Git-gate should own Git transport policy, not decide +who the agent is. ### Repository-local agents become a credential-selection path @@ -63,16 +64,16 @@ agents need the same host-only boundary. ## Goals / Success Criteria -- **Agent-owned identity.** Author name/email and named forge accounts live on - the agent definition, not under `git-gate`. +- **Agent-owned identity.** Author name/email and named forge configurations + live on the agent definition, not under `git-gate`. - **Trusted definitions only.** Agent and bottle files are discovered only under `~/.bot-bottle/{agents,bottles}`. Repository-local definitions never contribute names, defaults, or overrides. - **Optional repository association.** A bottle repository may name one forge - account from the selected agent. Repositories without `forge` retain current - behavior and generate no forge guidance or actor credential route. + alias from the selected agent. Repositories without `forge` retain current + behavior and generate no forge guidance or credential route. - **Proxy-held forge credential.** The host resolves the selected forge - account's token reference and gives the value only to the egress proxy. The + alias's token reference and gives the value only to the egress proxy. The bottle receives neither the token nor a credential file containing it. - **Forge-aware system guidance.** For associated repositories, bot-bottle generates provider-specific instructions describing the API base URL, @@ -116,9 +117,9 @@ The resolved bottled agent is an agent definition composed with a bottle: | Part | Source | Role | |------|--------|------| | Author identity | agent `author` | configures Git name/email and identifies the agent's claimed author | -| Forge accounts | agent `forge-accounts` | names API origins and host token references available to this agent | +| Forge configurations | agent `forge-accounts` | maps forge aliases to API origins and host token references available to this agent; token ownership determines account identity | | Git repository | bottle `git-gate.repos` | configures Git transport, host verification, and push capability | -| Repository/forge association | bottle repo `forge` | optionally selects an agent forge account for guidance and API access | +| Repository/forge association | bottle repo `forge` | optionally selects an agent forge alias for guidance and API access | This boundary keeps identity on the agent, capability/policy on the bottle, and transport enforcement in git-gate. @@ -152,17 +153,19 @@ The resolved values populate `user.name` and `user.email`. Existing selected home agent's `author` block. There is no compatibility period where a bottle identity silently overrides the agent identity. -`forge-accounts` is a map whose keys follow the manifest's existing kebab-case -identifier grammar (`[a-z][a-z0-9-]*`). Each account contains: +`forge-accounts` is a map whose keys are **forge aliases** and follow the +manifest's existing kebab-case identifier grammar +(`[a-z][a-z0-9-]*`). Each forge entry contains: - `url`: a canonical HTTPS Gitea API base URL; - `auth.type`: `token` in this slice; - `auth.token_secret`: the name of a host environment variable containing the operator-provided, agent-specific API token. -The token secret name is host configuration, not bottle configuration. The -token value is resolved only if a selected bottle repository references the -account. +The token's owner determines the authenticated forge account; there is no +separate account-name field. The token secret name is host configuration, not +bottle configuration. The token value is resolved only if a selected bottle +repository references the forge alias. ### Bottle manifest @@ -187,7 +190,8 @@ git-gate: - When absent, the repository behaves exactly as it does today. Bot-bottle does not resolve a forge actor token and does not add forge-specific instructions for that repository. -- When present, it must match a `forge-accounts` entry on the selected agent. +- When present, it must match a forge alias in `forge-accounts` on the selected + agent. The resolved association enables a scoped proxy credential route and adds the repository/forge relationship to generated system guidance. @@ -230,7 +234,7 @@ composition; they are not a filesystem discovery path. ### Forge URL validation -The host parses and canonicalizes each referenced forge account URL before +The host parses and canonicalizes each referenced forge alias's URL before creating any runtime resources: - scheme must be `https`; @@ -248,7 +252,7 @@ and guidance renderer. ### Proxy credential provisioning -For each distinct forge account referenced by at least one selected bottle +For each distinct forge alias referenced by at least one selected bottle repository, the host: 1. Resolves `auth.token_secret` from the host environment and rejects a missing @@ -262,8 +266,8 @@ The bottle makes an unauthenticated request to the configured HTTPS API URL. The token is not copied into the bottle, `.gitconfig`, generated prompt, workspace, or process environment visible to the agent. -If several repositories reference the same forge account, they share one -credential route. Unreferenced forge accounts resolve no secret and create no +If several repositories reference the same forge alias, they share one +credential route. Unreferenced forge aliases resolve no secret and create no route. ### Generated system guidance @@ -274,7 +278,7 @@ a repository. For each associated repository, Gitea guidance includes: -- account alias (for example `didericis-gitea`); +- forge alias (for example `didericis-gitea`); - API base URL (for example `https://gitea.dideric.is/api/v1`); - the git-gate repository name tied to that forge; - the instruction to call the configured HTTPS API through the proxy without @@ -300,7 +304,7 @@ The operator-owned token is not minted, rotated, or revoked by bot-bottle. On teardown, stopping the egress proxy discards the activation's in-memory/runtime copy. Later activations resolve the current host secret again. -Logs may include the account alias, canonical API origin, and repository name. +Logs may include the forge alias, canonical API origin, and repository name. They must never contain the token value. Errors for missing secrets name the configuration field and host environment variable, but do not print any value.