Credential vault: secure storage and origin-bound account aliases

[SarthakWade]

Problem

Headless cannot save or reuse credentials without passing plaintext through the agent-facing command surface. Users need customizable aliases such as personal, work, and client-acme, while password values remain inside an OS-protected vault.

Proposed surface

headless credentials list [--origin URL]
headless credentials add --origin URL --alias NAME --interactive
headless credentials rename --origin URL --alias OLD --to NEW
headless credentials remove --origin URL --alias NAME

The interactive command reads passwords only from /dev/tty with echo disabled and restores terminal state on every exit path. Listing returns aliases and optional user-approved username metadata, never passwords.

Use macOS Keychain and Linux Secret Service/KWallet. If secure storage is unavailable, return a specific error and do not fall back to plaintext.

Storage and identity model

• Bind each record to a canonical exact HTTPS authentication origin, account identity, and customizable alias.
• Keep the broker as the sole component that can read password values.
• Do not share Keychain items among executables unless Credential security design: threat model and broker contract #154 approves a signed access-group design.
• Store only nonsecret indexing metadata outside the OS vault.
• Define duplicate, rename, deletion, migration, backup, recovery, and unavailable-vault behavior.
• Never import an existing browser vault or accept an unrestricted profile or vault path.

macOS without Developer ID

The local/community build remains supported:

• Keychain storage and retrieval work without paid Apple membership.
• Each credential use requires Touch ID, macOS password authorization, or explicit trusted native confirmation.
• Silent credential use remains off by default.
• Use without repeated confirmation is permitted only through the native, Touch ID-gated policy defined in Unsigned macOS credentials: user-authorized use without repeated confirmation #166.
• CLI, MCP, environment variables, defaults manipulation, and page content cannot enable or modify that policy.
• Rebuilds or signing-identity changes may require reauthorization or migration.
• Capability output must identify the local security tier without claiming notarization or stable public signer identity.

A self-signed certificate is not a public trust mechanism and must not be generated or trusted automatically.

macOS with Developer ID

The same vault format and protocol must continue to work after a signed release becomes available. The implementation must support stable broker identity, notarized distribution, update migration, and provisioned access groups only if the accepted architecture requires them.

Signing certificates, passwords, team identifiers, and notarization credentials are release secrets and must never enter source control or runtime diagnostics.

Linux

Use an approved Secret Service or KWallet backend. Reject Chromium's basic plaintext fallback. Missing, locked, unsupported, or unavailable stores return explicit errors and do not silently disable protection.

Security requirements

Reject cross-origin use, insecure origins except explicit localhost development policy, unsafe aliases, duplicate ambiguity, piped secrets, password arguments, environment variables, and secret-bearing MCP parameters. Vault operations must not leak through logs, flows, diagnostics, crash text, command output, or temporary files.

Normal-vault aliases and credentials must be inaccessible from private contexts. Private contexts may use only in-memory credentials enrolled inside that context as specified by #35.

Testing

• Portable tests use a deterministic fake vault and verify all validation and redaction behavior.
• macOS integration tests exercise real Keychain add, query, authorization denial, deletion, identity-change handling, and cleanup.
• Linux integration tests exercise each supported secure backend plus locked and unavailable states.
• Tests verify terminal echo restoration after success, failure, interruption, and signals.
• Secret fixtures use synthetic credentials and never write values to CI logs or artifacts.

Acceptance criteria

• Both engines implement the same validated alias contract.
• Local/ad-hoc macOS builds enforce mandatory user presence unless the user enables the narrowly scoped native exception in Unsigned macOS credentials: user-authorized use without repeated confirmation #166.
• Developer ID support can be added without changing command or stored-record semantics.
• Store permissions, duplicates, deletion, backend failure, and identity changes fail closed.
• Secret-bearing buffers have bounded lifetime and are cleared where the platform permits.
• Capabilities and documentation state the active security tier and its limitations.
• Protocol, runtime, build, and relevant E2E suites pass.

Blocked by #154.

[yashranaway]

Implement this on the unsigned tier. Don't wait for paid Apple credentials.

Mandatory user presence on every saved-credential use. Capabilities should report a local/unnotarized vault, not a notarized password manager. Rebuilds may re-prompt. That's acceptable.

#166 is skipped. Same alias/origin records should still work if we later ship a Developer ID build. Blocked only on the #154 decision text, which is now this policy.

[yashranaway]

Unblocked for implementation after #171. Do #155 first if you have to pick one.

Mandatory user presence. No access groups. No #166. Capabilities report local/unnotarized, not a signed password manager.