Tier C key wiring

@@ -22,21 +22,21 @@ The universal principle is that API keys live at the gateway only — never in a

## Where keys live

Provider API keys are held together in a single operator-managed environment file on the workspace virtual machine, loaded via one `EnvironmentFile=` override applied to the whole Doorman unit — Anthropic, Gemini, and OpenAI keys all live in that one file, not in separate per-provider drop-ins. Rotating one provider's key means editing that shared file and reloading the service; it isn't isolated from the other providers' configuration the way a true per-provider drop-in would be.
Provider API keys are held together in a single operator-managed environment file on the gateway host, loaded via one environment-file override applied to the whole Doorman unit — the supported providers' keys all live in that one file, not in separate per-provider drop-ins. Rotating one provider's key means editing that shared file and reloading the service; it isn't isolated from the other providers' configuration the way a true per-provider drop-in would be.

The environment file is owned by root and readable by the service user running the Doorman. It is not tracked in any version-control repository, not included in any backup that publishes outside the virtual machine, and not present anywhere in the Git history. The `.gitignore` at the workspace root does not need to mention it because it lives outside the repository entirely.
The environment file is owned by root and readable only by the service user running the Doorman. It is not tracked in any version-control repository, not included in any backup that publishes outside the host, and not present anywhere in Git history.

The Doorman binary reads keys from its environment at startup and holds them in process memory. Keys are never written to disk by the Doorman, never echoed in response bodies, and never included in log output at any log level. Audit-ledger entries record the provider name, not any portion of the key.

A future strengthening of this posture, planned for a later milestone, will replace the plaintext environment file with a sops-encrypted file that the Doorman decrypts into its runtime environment using an operator-held decryption key that is never present on the virtual machine in plaintext. The current systemd-tier approach is the operational baseline until that milestone lands.
A future strengthening of this posture, planned for a later milestone, will replace the plaintext environment file with an encrypted file that the Doorman decrypts into its runtime environment using an operator-held decryption key that is never present on the host in plaintext. The current approach is the operational baseline until that milestone lands.

## Provisioning a key

Activating a new provider key requires operator presence for the steps that touch the key value, and proceeds through an eight-step sequence. The operator obtains the key from the provider's console and copies it to a temporary file on the virtual machine. The temporary file is created with restricted permissions before the key value is written to it. The new key is then added to the shared environment file using the value from the temporary file, the service is reloaded, and the health endpoint is queried to confirm the service has picked up the new configuration. A low-cost test call verifies that the key routes correctly and that an audit-ledger entry is produced with the expected fields. The operator then removes the temporary file using a secure deletion tool. The final step is a workspace changelog entry recording the activation event: provider name, date, and the reference to the first audit-ledger entry. The key value does not appear in the changelog entry or in any commit message.
Activating a new provider key requires operator presence for every step that touches the key value itself, following a documented internal runbook rather than an ad hoc process. In outline: the key is obtained from the provider's console, staged only through restricted-permission temporary handling, written into the shared environment file, and the service is reloaded and health-checked to confirm the new configuration took effect. A low-cost test call confirms the key routes correctly and produces the expected audit-ledger entry before the temporary handling artifacts are securely removed. The activation itself is recorded in an internal operational log — provider name, date, and a pointer to the corresponding audit-ledger entry — but the key value never appears in that record or in any commit message.

## Rotation

Quarterly rotation per provider is the default cadence, aligned with calendar quarters. The procedure generates a new key at the provider console while the old key remains active, replaces that provider's key line in the shared environment file, reloads the service, verifies operation, and retains the old key at the provider side for a forty-eight-hour window in case rollback is needed. A rotation event marker in the audit ledger delineates pre-rotation and post-rotation usage, supporting post-incident investigation.
Quarterly rotation per provider is the default cadence, aligned with calendar quarters. The procedure generates a new key at the provider console while the old key remains active, replaces that provider's key line in the shared environment file, reloads the service, verifies operation, and retains the old key at the provider side for a short overlap window in case rollback is needed. A rotation event marker in the audit ledger delineates pre-rotation and post-rotation usage, supporting post-incident investigation.

Accelerated rotation is appropriate when a compromise is suspected (see the breach response section), when the provider mandates rotation on its own schedule, or when the operator chooses a more frequent cadence for a high-volume deployment.

@@ -48,15 +48,15 @@ When a provider returns a server error, the Doorman falls back to Tier A local i

## Audit posture

Every Tier C call produces an audit-ledger entry recording: provider name, model name, input and output token counts, computed USD cost, end-to-end latency, tenant identifier, call purpose, and success status. The four permitted call purposes are editorial refinement, citation grounding, entity disambiguation, and initial knowledge graph construction. Calls for purposes outside this allowlist are rejected at the Doorman.
Every Tier C call produces an audit-ledger entry recording the provider, the model, token counts, computed cost, latency, tenant identifier, call purpose, and success status. Calls are restricted to a fixed allowlist of permitted purposes — editorial and knowledge-graph work, not open-ended use — and any call outside that allowlist is rejected at the Doorman.

Monthly review by the workspace Master-layer session aggregates prior-month usage by provider, flags cost spikes and success-rate anomalies, and verifies that provider-side billing agrees with ledger-side USD totals within a reasonable margin. Persistent divergence between provider billing and the ledger is an investigation trigger, not a tolerance.
A recurring operator review aggregates prior-period usage by provider, flags cost spikes and success-rate anomalies, and verifies that provider-side billing agrees with ledger-side cost totals within a reasonable margin. Persistent divergence between provider billing and the ledger is an investigation trigger, not a tolerance.

## Breach response

A breach is any event that exposes a key value beyond the Doorman boundary: accidental logging, accidental commit to a repository, a panic stack trace that echoes environment variables, inclusion in an inbox or outbox message, or appearance in a chat transcript used as a reproduction step. The response sequence is fixed and the first step is non-negotiable: revoke the key at the provider console immediately, before cleaning up the source of the leak. Revocation makes the leaked key worthless and bounds any potential misuse window. The remaining steps — removing the compromised key from the shared environment file, provisioning a fresh key through the standard eight-step runbook, sweeping the audit ledger for anomalous activity between the leak timestamp and revocation timestamp, and logging the incident — follow in order.
A breach is any event that exposes a key value beyond the Doorman boundary: accidental logging, accidental commit to a repository, a panic stack trace that echoes environment variables, inclusion in a message record, or appearance in a transcript used as a reproduction step. The response sequence is fixed and the first step is non-negotiable: revoke the key at the provider console immediately, before cleaning up the source of the leak. Revocation makes the leaked key worthless and bounds any potential misuse window. The remaining steps — removing the compromised key from the shared environment file, provisioning a fresh key through the standard runbook, sweeping the audit ledger for anomalous activity between the leak timestamp and revocation timestamp, and logging the incident — follow in order.

The incident log entry in the workspace cleanup log carries the leak source, the revocation timestamp, audit-ledger sweep findings, and the root cause and corrective action. This entry is part of the continuous-disclosure substrate: material operational events are recorded in signed, date-stamped commits that are suitable for review.
The incident is recorded in an internal operational log, carrying the leak source, the revocation timestamp, audit-ledger sweep findings, and the root cause and corrective action. This recording discipline is part of the continuous-disclosure substrate: material operational events are recorded in signed, date-stamped commits that are suitable for review.

## See also