secrets

name

secrets

description

Estate secret custody and consumption over 1Password and Doppler — op as the permanent local store, Doppler as the runtime backend, scoped CLI reads, directory-scope resolution, the SessionStart pull rail, service-token custody classes, secret-file templating, and the read-only Doppler MCP row. Use when reading or wiring secrets, minting or routing tokens, debugging missing session env keys, rendering secret-bearing config files, or touching op/doppler surfaces. Topology mutation — projects, configs, tokens, scopes — belongs to Parametric_Forge/services/topology.ts and its driver, never to ad-hoc CLI calls or per-repo files.

[SECRETS]

Two permanent backends custody estate secrets. 1Password (op) is the local store: the Tokens vault holds every API key, service token, IaC credential, and Pulumi passphrase, the Personal vault holds the Forge SSH Key, and op inject resolves them into the mode-600 op cache (~/.config/hm-op-session.sh) on every forge-redeploy --switch — the bootstrap baseline a fresh machine emits from before any Doppler token exists. Doppler is the runtime backend: op-served config-scoped service tokens resolve its declared configs, and its session cache overlays the op baseline with fresher per-key values. Both stores are maintained forever; neither retires the other.

Topology — projects, environments, configs, service tokens, directory scopes — lives as IaC rows in Parametric_Forge/services/topology.ts, materialized by estate.ts and applied by driver.ts over the Pulumi Automation API. doppler reads and writes secret values against declared configs; the SessionStart hook is the sole consumption rail; ~/.doppler holds CLI config and fallback state.

[01]-[ROUTING]

• [01]-PATTERNS: pattern doctrine — template rendering, mounts, multi-command wrappers, MCP row shape, plan-gated features.

[02]-[RESOLUTION]

• ~/.doppler is the CLI config dir; scopes ride ~/.doppler/.doppler.yaml, written by doppler configure set through the driver's scopes apply.
• A repo-local doppler.yaml is vendor setup guidance, not the estate scope owner; the estate carries none.
• Precedence, highest first: a service token's embedded project/config, runtime flags, env vars, config-file scope.
• Config-file scope resolves an exact directory match before the nearest ancestor.
• Scope env vars: DOPPLER_TOKEN, DOPPLER_PROJECT, DOPPLER_CONFIG, DOPPLER_CONFIG_DIR, DOPPLER_PASSPHRASE.
• Agents pass --project/--config explicitly; env carries only token custody and hook mode switches.
• An ambient DOPPLER_TOKEN outranks flags and represents one config; strip it with env -u DOPPLER_TOKEN when fetching more than one source.

[03]-[DOPPLER_CLI]

[INDEX]	[TASK]	[COMMAND]
[01]	Binary and version proof	doppler --version
[02]	Effective options, token stripped	doppler configure debug --json | jq 'with_entries(.value |= del(.token))'
[03]	Every scope row, token stripped	doppler configure --all --json | jq 'with_entries(.value |= del(.token))'
[04]	One directory's scope	doppler configure get project config --scope <dir> --json
[05]	Set a scope row	doppler configure set project=<p> config=<c> --scope <dir>
[06]	Unset a scope row	doppler configure unset project config --scope <dir>
[07]	Key inventory	doppler secrets download --project <p> --config <c> --no-file --format json | jq 'keys'
[08]	Inject env into a process	doppler run --project <p> --config <c> --command '<cmd>'
[09]	Render a template	doppler secrets substitute <template>

• One directory's scope keys land as enclave.project, enclave.config; the set is driver-owned and scope / stays untouched.
• Secret downloads pipe to jq 'keys' or jq 'length'; configure reads strip the root token with del(.token), since a bare configure debug or configure --all prints it.
• Receipts, transcripts, and logs carry key names and counts, never values or tokens.

[04]-[OP_CLI]

op reads the local store directly; the field suffix is token, credential, or password per item. An exported OP_SERVICE_ACCOUNT_TOKEN pins op to the Tokens vault, so Personal (the SSH key) resolves only under env -u OP_SERVICE_ACCOUNT_TOKEN.

[INDEX]	[TASK]	[COMMAND]
[01]	Auth proof	op whoami
[02]	Vault inventory	op vault list
[03]	Tokens item names	op item list --vault Tokens --format json | jq -r '.[].title'
[04]	Read one secret	op read "op://Tokens/<ITEM>/<token|credential|password>"
[05]	Resolve the rebuild template	op inject -i ~/.config/op/env.template -o <out>
[06]	Personal-vault SSH item	env -u OP_SERVICE_ACCOUNT_TOKEN op item get "Forge SSH Key" --vault Personal
[07]	Rename an item to its real name	op item edit "<old-title>" title="<official-name>" --vault Tokens

• op serves the SSH key to ssh, git, WezTerm, Yazi, and rclone through the 1Password agent socket; the item ref lives in 1Password/ssh/agent.toml, never a private key on disk.
• Read a secret only to verify presence or wire a one-off; standing consumption rides the pull rail, never inline op read in durable code.

[05]-[PULL_RAIL]

SessionStart hook .claude/hooks/setup-env.sh is the only consumption rail, canonical in Parametric_Forge and byte-identical in every repo copy. A warm session replays its cache into CLAUDE_ENV_FILE and dispatches a detached refresh; a cold boot resolves Doppler inline.

• DOPPLER_SOURCES rows carry the shape project:config:snapshot[:TOKEN_ENV_VAR]; each resolves independently and in parallel.
• TOKEN_ENV_VAR names an op-served config-scoped service token; an empty or unset segment falls back to ambient CLI auth, and a degraded token retries ambient once and blames the token in the receipt.
• CLAUDE_DOPPLER_OFFLINE=1 forces fallback-only fetches; CLAUDE_DOPPLER_STALE_DAYS (default 14) marks aged snapshots STALE.
• jq parses each JSON dump into a literal assignment, so secret bytes never reach a shell parser; receipts land at ~/.cache/forge-secrets/receipt.
• A live fetch rewrites its encrypted snapshot under ~/.cache/doppler; a failed fetch serves the snapshot; a dead row is loud and names the keys it owes.

[06]-[CUSTODY]

Local custody is op, never the OS keychain: every service, IaC, and MCP token plus the SSH key lives in a Tokens or Personal vault item. A personal doppler login is the one credential Doppler keeps in the keychain, used for the operator's ad-hoc interactive work alone — no rail depends on it.

[INDEX]	[CLASS]	[CUSTODY]	[USE]
[01]	Config-scoped service token	op://Tokens/DOPPLER_*_READONLY	Hook and runtime reads
[02]	IaC admin token	op://Tokens/DOPPLER_IAC_TOKEN/token	Topology writes via Pulumi only
[03]	Pulumi stack passphrase	op://Tokens/PULUMI_FORGE_SERVICES/password	Stack state decryption
[04]	MCP token	Injected as DOPPLER_TOKEN	Read-only agent MCP
[05]	Provider PATs (GitHub and peers)	op://Tokens items, mirrored into configs	Consumed through the pull rail

• Config-scoped service token: minted by topology rows; static Developer-plan tokens are revoked and reminted, never rotated in place.
• IaC admin token and stack passphrase: brokered by driver.ts; an ambient DOPPLER_TOKEN or PULUMI_CONFIG_PASSPHRASE short-circuits the op read per run.
• MCP token: injected through the doppler-run indirection, its grants the enforcement, while --read-only --project --config narrow only the tool surface.
• Provider PATs are never topology identity.

[07]-[LAW]

• One item, one official name: an item carries the credential's real published name, never a handrolled synonym; a consumer needing a different env-var name renames the item at the source and repoints every reader, never adds a second item or a duplicate export aliasing the same secret. A naming mistake is fixed by renaming in op and Doppler, never papered over.
• A new project lands as project/config rows in Parametric_Forge/services/topology.ts and a directory scope row, then pulumi up; retiring it deletes its rows.
• A repo carries zero Doppler files; its agents resolve through scope plus hook automatically.
• Rendered secret material is ephemeral: --mount/--mount-template over durable renders; plaintext binds only where the target owner requires it.