Agent Secret Access Policy

Status: Implemented for MCP/CLI discovery and security-proxy substitution.

Calciforge currently keeps secret values out of agent context, but it also gates secret-name discovery and placeholder substitution when a Calciforge identity is known.

What exists today:

• mcp-server list_secrets and calciforge-secrets list expose fnox secret names visible to that process, filtered by the active secret access policy when CALCIFORGE_AGENT_ID, CALCIFORGE_USER_ID, or CALCIFORGE_CHANNEL[_ID] is set.
• secret_reference / calciforge-secrets ref NAME build `` placeholders and never return values; known identities may only build references for allowed names.
• security-proxy substitutes values at the network boundary, and refuses substitution for known request identities unless a policy rule allows the secret.
• per-secret destination allowlists can block substitution to disallowed hosts.

Policy shape:

[security.secret_access]
[[security.secret_access.rules]]
agents = ["research-*"]
users = ["brian"]
channels = ["signal"]
secrets = ["BRAVE_*", "SEARCH_*"]

Selectors are conjunctive: if a rule sets agents, users, and channels, all configured selectors must match. Empty selector lists are wildcards for that selector type. Secret patterns support *.

Identity sources:

• MCP and calciforge-secrets read CALCIFORGE_AGENT_ID, CALCIFORGE_USER_ID, and CALCIFORGE_CHANNEL_ID / CALCIFORGE_CHANNEL.
• API-backed calciforge-secrets wrappers forward those identities to the central secret-control API; managed installs set CALCIFORGE_AGENT_ID to the claw name in the generated wrapper.
• security-proxy reads x-calciforge-agent-id, legacy x-agent-id, x-calciforge-user-id, and x-calciforge-channel-id / x-calciforge-channel, then strips these identity headers before forwarding upstream.

Compatibility rule: unknown identity preserves process-scoped behavior only while no secret access rules are configured. Once an operator configures identity ACLs, missing or unknown identity fails closed: no matching rule means no discovery, no reference, and no substitution. Destination allowlists remain a second, independent gate.

Scope boundary: this policy controls secret discovery, reference creation, and network-boundary substitution. The central read-only /control/secrets/list and /control/secrets/ref/* helper endpoints are guarded by secret_discovery_api_key. The central /control/secrets/set helper is a privileged operator write path guarded by secret_control_api_key; it is not a per-agent write ACL. Add identity-scoped write permissions separately before exposing write-capable helpers to broad agent surfaces.

Remaining hardening work:

• ensure all managed agent launchers set stable identity env vars or headers by default.
• define identity-scoped secret write permissions if agents or channels are ever allowed to create or update fnox secrets through the central helper.
• add operator examples to generated install output once the managed launcher path is finalized.