ADR-0004 — Credential-store-first token resolution

Status: Accepted

Context

LisaOS touches many external systems — issue tracking, messaging, workspace, backups, the gateway itself — and most need a credential. The system also runs a great deal of unattended automation: headless sessions and scheduled jobs that authenticate with no human present. A credential written into source, a configuration file, or a committed script is a leak waiting to happen — and a fail-closed publication pipeline is far harder to keep honest if secrets are scattered through the codebase in the first place.

Decision

Standardise a single credential-resolution order for every integration and every job:

1. A protected credential store — the first and preferred source.
2. The environment — a fallback when the store is unavailable.
3. Never a literal in source — no token, key, host, or account identifier is committed.

Resolution is best-effort and non-blocking: a job that cannot find a credential logs the fact and degrades rather than hanging, and an unattended session that comes up without a credential says so plainly instead of failing opaquely.

Consequences

• Positive: There is one place a credential lives and one order in which it is sought, so both interactive and unattended callers resolve identically. Rotating a secret is a store operation, not a code change.
• Positive: Because no credential is ever a literal, the sanitisation gate's job is narrower and more trustworthy — it is enforcing an invariant the codebase already upholds, not compensating for scattered secrets.
• Positive: The file-first-then-environment order means a locked-down deployment and a looser local one can share the same code without either leaking into the other.
• Negative / accepted: Every integration must implement the resolution order rather than reading an environment variable directly — a small, repeated discipline. It is accepted as the price of never having a secret in a diff.