OAuth token storage: should the default become keyring or encrypted file?

[PierrunoYT]

Problem to decide

Zero's unified OAuth store currently documents/selects the plaintext file backend when storage is unspecified. The implementation publishes state atomically under a mode-0700 directory using mode-0600 files and a cross-process lock. Optional AES-GCM and keyring backends already exist.

This is not a claim that the file is world-readable: the existing permissions and atomicity controls are strong. The remaining tradeoff is at-rest confidentiality from same-account malware, backup/snapshot exposure, and accidental disclosure. The API-key credential store uses a stronger automatic default—keyring where supported or encrypted file—without silently selecting plaintext.

Audit context: finding SEC-07 at main revision 1b5db1765672820caac1684b168c9898b5ba3593.

Related issue #937 / PR #1007 address oversized multi-login keyring blobs; they do not decide the default OAuth storage policy.

Proposed direction

Consider an auto OAuth storage policy aligned with the credential store:

1. a reliable OS keyring where supported;
2. encrypted file with an explicit key source when keyring is unavailable; and
3. plaintext only after an explicit user choice.

Existing plaintext stores must not be silently deleted, overwritten, or made inaccessible.

Design questions

1. Is plaintext file storage the deliberate default for portability/headless operation?
2. What should auto do in CI, SSH/headless sessions, containers, and systems with a locked or size-limited keyring?
3. Where should encrypted-file key material come from without creating a circular secret-storage problem?
4. Should migration be opt-in, prompted, or automatic after a successful read/write verification?
5. How long must old config values and plaintext read compatibility remain?
6. What recovery path should be shown when the selected keyring becomes unavailable?

Required migration properties

• mode-0600/0700 and atomic publication remain intact;
• migration writes and verifies the destination before removing or retiring the source;
• interruption leaves at least one readable copy;
• rollback is documented and tested;
• no token bytes enter argv, logs, diagnostics, or migration errors;
• headless operation has an explicit supported path; and
• users may deliberately retain plaintext storage when they accept the tradeoff.

Full audit proposal: https://github.com/PierrunoYT/zero/blob/audit/codebase-audit-2026-09-08/docs/audit/SECURITY_AUDIT.md#sec-07--oauth-file-storage-defaults-to-plaintext