didericis/bot-bottle
1
0
Fork 0
Code Issues 33 Pull Requests 9 Actions Packages Releases Wiki Activity

docs: clarify forge alias identity

Browse Source
This commit is contained in:
didericis (codex)
2026-07-26 20:51:34 +00:00
committed by didericis
parent bb4075558f
commit 5cb1c190f4
1 changed files with 29 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/prds/prd-new-trusted-agent-forge-identity.md
+29 -25
View File
@@ -7,12 +7,13 @@
## Summary ## 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 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 agent non-secret, provider-specific system guidance for that repository and
routes authenticated forge API calls through the egress proxy without exposing 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 Repository-local agent and bottle definitions are no longer discovered. Once
agent definitions can select a host forge credential, allowing checked-out 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 ### Identity is owned by the wrong layer
`git-gate.user` puts an agent property on a repository transport component. An `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 author identity and set of forge credentials should follow the agent across
repositories. Git-gate should own Git transport policy, not decide who the bottles and repositories. Git-gate should own Git transport policy, not decide
agent is. who the agent is.
### Repository-local agents become a credential-selection path ### Repository-local agents become a credential-selection path
@@ -63,16 +64,16 @@ agents need the same host-only boundary.
## Goals / Success Criteria ## Goals / Success Criteria
- **Agent-owned identity.** Author name/email and named forge accounts live on - **Agent-owned identity.** Author name/email and named forge configurations
the agent definition, not under `git-gate`. live on the agent definition, not under `git-gate`.
- **Trusted definitions only.** Agent and bottle files are discovered only - **Trusted definitions only.** Agent and bottle files are discovered only
under `~/.bot-bottle/{agents,bottles}`. Repository-local definitions never under `~/.bot-bottle/{agents,bottles}`. Repository-local definitions never
contribute names, defaults, or overrides. contribute names, defaults, or overrides.
- **Optional repository association.** A bottle repository may name one forge - **Optional repository association.** A bottle repository may name one forge
account from the selected agent. Repositories without `forge` retain current alias from the selected agent. Repositories without `forge` retain current
behavior and generate no forge guidance or actor credential route. behavior and generate no forge guidance or credential route.
- **Proxy-held forge credential.** The host resolves the selected forge - **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. bottle receives neither the token nor a credential file containing it.
- **Forge-aware system guidance.** For associated repositories, bot-bottle - **Forge-aware system guidance.** For associated repositories, bot-bottle
generates provider-specific instructions describing the API base URL, 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 | | Part | Source | Role |
|------|--------|------| |------|--------|------|
| Author identity | agent `author` | configures Git name/email and identifies the agent's claimed author | | 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 | | 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 This boundary keeps identity on the agent, capability/policy on the bottle, and
transport enforcement in git-gate. 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 selected home agent's `author` block. There is no compatibility period where a
bottle identity silently overrides the agent identity. bottle identity silently overrides the agent identity.
`forge-accounts` is a map whose keys follow the manifest's existing kebab-case `forge-accounts` is a map whose keys are **forge aliases** and follow the
identifier grammar (`[a-z][a-z0-9-]*`). Each account contains: manifest's existing kebab-case identifier grammar
(`[a-z][a-z0-9-]*`). Each forge entry contains:
- `url`: a canonical HTTPS Gitea API base URL; - `url`: a canonical HTTPS Gitea API base URL;
- `auth.type`: `token` in this slice; - `auth.type`: `token` in this slice;
- `auth.token_secret`: the name of a host environment variable containing the - `auth.token_secret`: the name of a host environment variable containing the
operator-provided, agent-specific API token. operator-provided, agent-specific API token.
The token secret name is host configuration, not bottle configuration. The The token's owner determines the authenticated forge account; there is no
token value is resolved only if a selected bottle repository references the separate account-name field. The token secret name is host configuration, not
account. bottle configuration. The token value is resolved only if a selected bottle
repository references the forge alias.
### Bottle manifest ### Bottle manifest
@@ -187,7 +190,8 @@ git-gate:
- When absent, the repository behaves exactly as it does today. Bot-bottle does - 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 not resolve a forge actor token and does not add forge-specific instructions
for that repository. 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 The resolved association enables a scoped proxy credential route and adds the
repository/forge relationship to generated system guidance. repository/forge relationship to generated system guidance.
@@ -230,7 +234,7 @@ composition; they are not a filesystem discovery path.
### Forge URL validation ### 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: creating any runtime resources:
- scheme must be `https`; - scheme must be `https`;
@@ -248,7 +252,7 @@ and guidance renderer.
### Proxy credential provisioning ### 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: repository, the host:
1. Resolves `auth.token_secret` from the host environment and rejects a missing 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, The token is not copied into the bottle, `.gitconfig`, generated prompt,
workspace, or process environment visible to the agent. workspace, or process environment visible to the agent.
If several repositories reference the same forge account, they share one If several repositories reference the same forge alias, they share one
credential route. Unreferenced forge accounts resolve no secret and create no credential route. Unreferenced forge aliases resolve no secret and create no
route. route.
### Generated system guidance ### Generated system guidance
@@ -274,7 +278,7 @@ a repository.
For each associated repository, Gitea guidance includes: 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`); - API base URL (for example `https://gitea.dideric.is/api/v1`);
- the git-gate repository name tied to that forge; - the git-gate repository name tied to that forge;
- the instruction to call the configured HTTPS API through the proxy without - 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 teardown, stopping the egress proxy discards the activation's in-memory/runtime
copy. Later activations resolve the current host secret again. 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 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. configuration field and host environment variable, but do not print any value.