credentialFile: render the {{.Scopes}} and {{.PrimaryApiKey}} placeholders #224

Closed
opened 2026-10-27 13:35:27 +00:00 by sam · 0 comments
Owner

Follow-up from archie-core-egkf.13 (credentialFile rendering).

The renderer landed for {{.AccessToken}}, {{.RefreshToken}} and {{.ExpiresAt}}.
The published Claude Code Kit (the spec module's own claude.yaml) also declares
scopes: "{{.Scopes}}" and primaryApiKey: "{{.PrimaryApiKey}}" in its
oauth.credentialFile.structure, so that Kit currently refuses to launch with
"placeholder {{.Scopes}} is not rendered by archie". Devin's toml file uses
{{.PrimaryApiKey}} (devin is passthrough:true and refused for other reasons).

Spec semantics to implement:

  • {{.Scopes}} renders as an array. Nothing in harnesssecret.Secret carries
    scopes today, so this needs a source: parse the token response's scope
    field in the proxy capture, or store it alongside the token set.
  • {{.PrimaryApiKey}} is a string whose enclosing key is omitted entirely when
    no API key is captured (the declarative form of the v2 template's
    {{if .PrimaryApiKey}}).

Unblocking criterion: a Kit whose credentialFile references either placeholder
launches and the rendered file holds the sentinel/typed value, with no literal
placeholder left standing.

Notes

LANE RESULT (blocked, no code change): both placeholders have no source. Red-first could not be satisfied, so no failing test was left in the tree and nothing was committed.

{{.Scopes}} -- no source at all. Filed archie-core-egkf.15 with the full chain: egress capture
(oauth.go:239-256) never reads the token response scope, harnesssecret.Secret
(harnesssecret.go:17-25) and harnessSecretPayload (postgres/harness_secrets.go:22-27) have no
field, and message HarnessSecret (proto/state/v1/state.proto:634-642) has no field -- which is
load-bearing because the daemon reads the set over gRPC (bootstrap.go:424). Adding the field is
not glue: it is a capture change plus a domain/payload/proto/values change, and postgres,
staterpc and contracts/state are outside this lane non-goals.

{{.PrimaryApiKey}} -- no source either, for a stronger reason. archie has no API-key capture
into a credential file: a service API key lives in config.CredentialBinding.Secret
(config.go:916-919), is resolved to the REAL value only to populate the egress grant
(kitrun resolveCredentials), and the container gets only egress.Sentinel in the env var the Kit
names (credentials.go:107-117). The spec calls PrimaryApiKey a string whose enclosing key is
omitted when no key is captured (credential@1.md:59-61; claude.yaml:85-88), i.e. the real key
value in the v2 template. Writing it would breach the PRD rule that a real API key never
appears in the container filesystem. The omit case is deterministically true for an OAuth
credential here, but implementing omit-always is a policy decision (archie never renders a
primary API key), not a source -- so the fail-closed refusal is kept pending that call.
BLOCKED on archie-core-egkf.15 (filed by the lane with the full missing chain). Verified at 7d34b57f: egress capture parses only access_token/refresh_token/token_type/expires_in -- the token response's 'scope' (RFC 6749 5.1) is dropped; harnesssecret.Secret has no Scopes; harnessSecretPayload has no scopes (JSON in the encrypted envelope, so no migration); proto HarnessSecret has no scopes (load-bearing -- the daemon reads the token set over gRPC, so a local-only field is lost in production); staterpc/values.go has no mapping. No source exists for {{.Scopes}} anywhere, so red-first was unsatisfiable without inventing one and the lane correctly left no code.
RULING on {{.PrimaryApiKey}}: omit the enclosing key, always. credential@1.md defines it as a string whose enclosing key is omitted when no key is captured, and archie resolves a service key only to populate the egress grant while the container receives egress.Sentinel -- so the omit case is deterministically true for every OAuth credential rendered, and rendering a real key would breach the rule that a real API key never lands on the container filesystem. Implement the spec's omit case, do not substitute a value. This does not unblock the Kit while scopes still refuse; it settles what this bead does once egkf.15 lands.
LANE RESULT (done, committed 48ed7fe6 on peer/egkf14, not yet merged): {{.Scopes}} renders as an array from OAuthFacts.Scopes; a single-element set is a one-element array (never collapsed to a string). Empty scopes REFUSE by name with "re-run the setup terminal", because credential@1.md declares an omission case only for {{.PrimaryApiKey}} ("a string whose enclosing key is omitted when no key is captured") and none for {{.Scopes}} ("an array"), and an empty array can silently change the CLI capability decisions. {{.PrimaryApiKey}} now omits its enclosing key, never empties it. LaunchParams.OAuthExpiries became LaunchParams.OAuth map[string]OAuthFacts{Scopes, ExpiresAt}; kitrun reads both from the same stored token set. Residual for existing installs: a token set captured before egkf.15 has no scopes, so a Kit rendering {{.Scopes}} still refuses at launch, but now with an actionable message naming the setup terminal.
Merged and gated. Spec-driven: {{.Scopes}} renders as a typed array (credential@1.md says '(an array)', claude.yaml says 'scopes as a JSON array'); an empty scope set REFUSES by name, because credential@1.md declares an omission case only for {{.PrimaryApiKey}} and none for {{.Scopes}}; {{.PrimaryApiKey}} omits its enclosing key rather than emptying it. Operations note: a token set captured before egkf.15 has no scopes, so the published Claude Kit still refuses at launch -- the outcome is unchanged and the message is now actionable (re-run the setup terminal). A refresh only fills scopes when the provider repeats scope, which providers usually report only on the login exchange, so the remedy is a fresh /login rather than waiting for a refresh.

Close reason

Closed


Imported from beads archie-core-egkf.14 · GitHub #1423 · type task · priority P1 · created 2026-09-29 · closed 2026-09-29

Follow-up from archie-core-egkf.13 (credentialFile rendering). The renderer landed for {{.AccessToken}}, {{.RefreshToken}} and {{.ExpiresAt}}. The published Claude Code Kit (the spec module's own claude.yaml) also declares `scopes: "{{.Scopes}}"` and `primaryApiKey: "{{.PrimaryApiKey}}"` in its oauth.credentialFile.structure, so that Kit currently refuses to launch with "placeholder {{.Scopes}} is not rendered by archie". Devin's toml file uses {{.PrimaryApiKey}} (devin is passthrough:true and refused for other reasons). Spec semantics to implement: - {{.Scopes}} renders as an array. Nothing in harnesssecret.Secret carries scopes today, so this needs a source: parse the token response's scope field in the proxy capture, or store it alongside the token set. - {{.PrimaryApiKey}} is a string whose enclosing key is omitted entirely when no API key is captured (the declarative form of the v2 template's {{if .PrimaryApiKey}}). Unblocking criterion: a Kit whose credentialFile references either placeholder launches and the rendered file holds the sentinel/typed value, with no literal placeholder left standing. ### Notes LANE RESULT (blocked, no code change): both placeholders have no source. Red-first could not be satisfied, so no failing test was left in the tree and nothing was committed. {{.Scopes}} -- no source at all. Filed archie-core-egkf.15 with the full chain: egress capture (oauth.go:239-256) never reads the token response scope, harnesssecret.Secret (harnesssecret.go:17-25) and harnessSecretPayload (postgres/harness_secrets.go:22-27) have no field, and message HarnessSecret (proto/state/v1/state.proto:634-642) has no field -- which is load-bearing because the daemon reads the set over gRPC (bootstrap.go:424). Adding the field is not glue: it is a capture change plus a domain/payload/proto/values change, and postgres, staterpc and contracts/state are outside this lane non-goals. {{.PrimaryApiKey}} -- no source either, for a stronger reason. archie has no API-key capture into a credential file: a service API key lives in config.CredentialBinding.Secret (config.go:916-919), is resolved to the REAL value only to populate the egress grant (kitrun resolveCredentials), and the container gets only egress.Sentinel in the env var the Kit names (credentials.go:107-117). The spec calls PrimaryApiKey a string whose enclosing key is omitted when no key is captured (credential@1.md:59-61; claude.yaml:85-88), i.e. the real key value in the v2 template. Writing it would breach the PRD rule that a real API key never appears in the container filesystem. The omit case is deterministically true for an OAuth credential here, but implementing omit-always is a policy decision (archie never renders a primary API key), not a source -- so the fail-closed refusal is kept pending that call. BLOCKED on archie-core-egkf.15 (filed by the lane with the full missing chain). Verified at 7d34b57f: egress capture parses only access_token/refresh_token/token_type/expires_in -- the token response's 'scope' (RFC 6749 5.1) is dropped; harnesssecret.Secret has no Scopes; harnessSecretPayload has no scopes (JSON in the encrypted envelope, so no migration); proto HarnessSecret has no scopes (load-bearing -- the daemon reads the token set over gRPC, so a local-only field is lost in production); staterpc/values.go has no mapping. No source exists for {{.Scopes}} anywhere, so red-first was unsatisfiable without inventing one and the lane correctly left no code. RULING on {{.PrimaryApiKey}}: omit the enclosing key, always. credential@1.md defines it as a string whose enclosing key is omitted when no key is captured, and archie resolves a service key only to populate the egress grant while the container receives egress.Sentinel -- so the omit case is deterministically true for every OAuth credential rendered, and rendering a real key would breach the rule that a real API key never lands on the container filesystem. Implement the spec's omit case, do not substitute a value. This does not unblock the Kit while scopes still refuse; it settles what this bead does once egkf.15 lands. LANE RESULT (done, committed 48ed7fe6 on peer/egkf14, not yet merged): {{.Scopes}} renders as an array from OAuthFacts.Scopes; a single-element set is a one-element array (never collapsed to a string). Empty scopes REFUSE by name with "re-run the setup terminal", because credential@1.md declares an omission case only for {{.PrimaryApiKey}} ("a string whose enclosing key is omitted when no key is captured") and none for {{.Scopes}} ("an array"), and an empty array can silently change the CLI capability decisions. {{.PrimaryApiKey}} now omits its enclosing key, never empties it. LaunchParams.OAuthExpiries became LaunchParams.OAuth map[string]OAuthFacts{Scopes, ExpiresAt}; kitrun reads both from the same stored token set. Residual for existing installs: a token set captured before egkf.15 has no scopes, so a Kit rendering {{.Scopes}} still refuses at launch, but now with an actionable message naming the setup terminal. Merged and gated. Spec-driven: {{.Scopes}} renders as a typed array (credential@1.md says '(an array)', claude.yaml says 'scopes as a JSON array'); an empty scope set REFUSES by name, because credential@1.md declares an omission case only for {{.PrimaryApiKey}} and none for {{.Scopes}}; {{.PrimaryApiKey}} omits its enclosing key rather than emptying it. Operations note: a token set captured before egkf.15 has no scopes, so the published Claude Kit still refuses at launch -- the outcome is unchanged and the message is now actionable (re-run the setup terminal). A refresh only fills scopes when the provider repeats `scope`, which providers usually report only on the login exchange, so the remedy is a fresh /login rather than waiting for a refresh. ### Close reason Closed --- _Imported from beads `archie-core-egkf.14` · GitHub #1423 · type task · priority P1 · created 2026-09-29 · closed 2026-09-29_
sam added the hightask labels 2026-10-27 13:35:27 +00:00
sam self-assigned this 2026-10-27 13:35:27 +00:00
sam closed this issue 2026-10-27 13:35:27 +00:00
sam added a new dependency 2026-11-14 14:45:12 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#224