Credential security design: threat model and broker contract

[SarthakWade]

Problem

Agents currently submit passwords through normal fill values. Password fields are omitted from semantic snapshots and flows do not record fill values, but secrets can still appear in model context, process arguments, tool transcripts, or shell history. There is no credential vault, authorization policy, trusted autofill path, or documented relationship between credential security and macOS code signing.

Apple Developer Program membership is not required to implement Keychain storage, local authentication prompts, secure terminal input, aliases, private IPC, persistent sessions, or local tests. It is required for Developer ID certificates and notarized public distribution. That distinction must be settled before implementation because it changes which authorization modes can be offered safely.

Security goals

• Password values never appear in snapshots, command output, MCP responses, logs, flows, recordings, diagnostics, errors, environment variables, or process arguments.
• Websites and page JavaScript cannot enumerate aliases or query the vault.
• Credentials are bound to a canonical authentication origin and account identity.
• The vault fails closed when a supported OS secret store is unavailable.
• Login cookies and profile data are included in the authentication threat model.
• Direct agent-provided credentials remain available as an explicit user choice, with clear disclosure that the model or tool provider may retain them.

Threat model

Document protection against:

• Another OS account or offline copy of the profile.
• An untrusted webpage, cross-origin frame, or prompt-injection attempt.
• An ordinary process that can reach the per-user socket.
• A malicious process running as the logged-in user.
• Browser-process injection or compromise.
• Root, administrator, or kernel compromise.
• Theft of authenticated session cookies without theft of a password.
• Replacement of the distributed application or credential broker.

No design should claim to protect against every same-user or privileged compromise. The intended guarantees and residual risks must be stated precisely.

Required broker architecture

Specify a credential broker that:

• Is the only component allowed to read password values from macOS Keychain or Linux Secret Service/KWallet.
• Exposes aliases and opaque challenge references, never password values.
• Authenticates IPC callers and validates the active session and top-level origin.
• Keeps plaintext only for the shortest practical lifetime and clears temporary buffers where the platform permits.
• Rejects insecure storage backends, including Chromium's Linux plaintext fallback.
• Defines iframe, OAuth redirect, passkey, MFA, CAPTCHA, audit, crash, and recovery behavior.
• Keeps normal and private-context credentials, approvals, cookies, and storage separate.
• Never treats same-user socket ownership alone as authorization to release a credential.

macOS deployment tiers

Community or local build without paid Apple membership

The application can be compiled, ad-hoc signed, and tested locally. It can use Keychain Services and request Touch ID or macOS password authorization.

Required restrictions:

• The broker owns its Keychain items directly; do not depend on shared Keychain access groups.
• Every saved-credential use requires current user presence or an explicit trusted native confirmation.
• Saved-credential use requires current user presence by default.
• A native-only, Touch ID-gated exception for use without repeated confirmation may be offered through Unsigned macOS credentials: user-authorized use without repeated confirmation #166.
• That exception must remain off by default, inaccessible to agent-facing settings, explicit about its authorization-provenance risk, and invalidated after defined application-identity changes.
• Users may need to approve the application manually through Gatekeeper.
• Rebuilt or relocated binaries may trigger new Keychain prompts or be treated as a different identity.
• Public automatic updates must not claim a stable Apple-verified signer.
• Source builds and locally trusted installations are supported, but must not be described as notarized or enterprise-ready.

A locally generated or self-signed certificate may stabilize one installation, but it does not create public trust, requires per-user certificate management, and must not be the default distribution strategy.

Developer ID build with paid Apple membership

Developer ID distribution remains outside the Mac App Store and does not require App Store review. It enables:

• A stable Apple-verifiable application and broker identity.
• Notarization and normal Gatekeeper installation behavior.
• Reliable identity across public updates.
• Provisioned Keychain access groups if multiple signed components genuinely require them.
• Consideration of session-level or trusted-origin approvals after security review.

Certificates, certificate passwords, team identifiers, and notarization credentials must live in protected local storage or CI secrets, never in the repository, artifacts, logs, or issue text.

Linux behavior

Linux implementation has no Apple dependency. Use Secret Service or KWallet through a documented backend. If neither approved backend is available or unlocked, credential storage and retrieval fail explicitly. Never fall back to a basic plaintext Chromium store.

The same alias, origin, challenge, redaction, private-context, and authorization contracts apply. Platform-specific limitations must be represented through capabilities rather than silent partial behavior.

Decision options

1. Support both deployment tiers. This is the recommended option. Development and community builds default to mandatory user presence and may offer the explicit native-only exception in Unsigned macOS credentials: user-authorized use without repeated confirmation #166; signed builds can later enable reviewed convenience policies.
2. Require Developer ID for all macOS credential features. This provides a simpler guarantee but blocks community and local users unnecessarily.
3. Defer the macOS credential manager until signing is available. This minimizes near-term risk but delays useful functionality and Linux parity.

The architecture should not require redesign when moving from option 1's local tier to a Developer ID release.

Required decisions

Record:

• Chosen deployment tier policy.
• Broker process and IPC identity checks.
• Keychain item access-control flags and behavior after application updates.
• Whether any component sharing requires a provisioned access group.
• User-presence rules for each tier, including the scope, persistence, and invalidation contract for Unsigned macOS credentials: user-authorized use without repeated confirmation #166.
• How the runtime reports its credential security level.
• Login-cookie and profile protections.
• Migration and recovery when signing identity changes.
• Which tests use mocks and which require a real macOS Keychain and biometric-capable host.
• Release secrets, notarization responsibilities, and failure behavior.

Acceptance criteria

• An architecture-decision entry defines the complete threat model, deployment tiers, guarantees, and residual risks.
• Local/ad-hoc and Developer ID behavior are distinguishable in capabilities and documentation.
• Security review covers password theft, alias enumeration, prompt injection, phishing origins, replayed approvals, socket callers, binary replacement, and stolen session cookies.
• No plaintext database or insecure Linux fallback is permitted.
• Follow-up issues have testable contracts and explicit dependencies.
• Release implications are cross-linked with E7 — Cut a release — everything since v1.0.2 is unreleased #45.
• The optional unsigned-build authorization exception is specified and tested separately in Unsigned macOS credentials: user-authorized use without repeated confirmation #166.

Apple references

• Keychain Services
• Sharing Keychain items between apps
• Developer ID certificates
• Gatekeeper and runtime protection

[yashranaway]

We're not buying an Apple Developer membership for this.

Build the local/community tier only. macOS Keychain and Linux Secret Service or KWallet. Touch ID or the macOS account password on every saved-credential use. No access groups. No silent fill. If the OS vault is missing or locked, fail closed. Never fall back to Chromium's plaintext store.

Keep the record format compatible with a later Developer ID build so we don't redesign this when we eventually sign releases. That later build is #45, not a prerequisite here.

#166 is out of the unsigned product. Per-use confirmation is the security model until we have a stable Apple-signed identity.

Write this as the architecture-decision entry, then start at #155. Vault commands are #156. Login/save flow is #157.

[yashranaway]

Architecture decision 24 is in #171. That is this ticket.

Unsigned local tier, per-use Touch ID, durable profiles, no #166, no Apple membership required. After #171 merges this issue closes. Implementation starts at #155.