secrets-handling

Secrets handling

Use the installed credential mechanism without bringing secret values into model context.

Sources of truth

• Read the credentials index for service names, credential identifiers, access commands, and non-secret operational notes. The index contains no values and is the only credential catalog the model may read.
• Values live in the protected store under ~/.config/credentials/. Never read, search, print, summarize, or copy that directory.
• The secret helper is the generic value-delivery interface. Native tools may use their own configured credential mechanism, such as ssh, gh, or curl --netrc, without exposing the backing files.

Consume a registered value

Follow the exact credential name and access pattern in the index. Prefer an environment-scoped child process when the consumer supports it:

secret run REGISTERED_NAME -- consumer-command

secret run removes other names from the managed store from the inherited environment and exposes only the requested names to that one child process. If a consumer requires the value in a specific argument or header, use the narrow inline form without printing it:

curl -H "x-api-key: $(secret get REGISTERED_NAME)" https://example.invalid/

The shell substitutes the helper output into that process without returning the value to the model. An already-exported environment variable may be passed directly when the index names it, but do not assume every stored credential is present in the current environment.

Never:

• run secret get as a standalone inspection command;
• echo, log, serialize, or interpolate a value into a response or file;
• assign a value to a shell variable that later diagnostic output could expose;
• place a value in a URL, command example, ticket, commit message, or process argument when a credential-aware file, environment, or stdin mechanism is available;
• weaken TLS, host-key, or certificate checks merely to make authentication succeed.