claude-code - 💡(How to fix) Fix [FEATURE] Local session authentication (PIN / TOTP / SMS OTP / passkey) before Claude Code accepts prompts

Observation

Claude Code has broader access to a developer's machine than almost any other tool in routine use — shell execution, arbitrary file read/write, git history, environment variables, SSH keys, and credential stores. The existing authentication mechanism (OAuth / API key) authenticates the Anthropic account for billing purposes. It proves who owns the subscription; it does not verify who is operating the machine at a given moment. These credentials are stored persistently in OS credential stores and are available to any process that can invoke the claude binary.

There is currently no mechanism to require the local user to re-authenticate before Claude Code accepts prompts in a new terminal session.

Risk

A bad actor who gains access to a running machine inherits Claude Code's full permissions automatically. No additional barrier exists. Specific scenarios:

• Physical access — an unlocked workstation in an office, café, or shared space
• Lateral movement — stolen SSH credentials providing remote shell access
• Remote access malware — a RAT or screen-sharing tool operating in the background
• Compromised CI runner — a build agent with Claude Code installed and persistent credentials

In each case the attacker can invoke claude immediately, with full tool permissions, and begin reading source code, exfiltrating credentials, modifying files, or executing shell commands — with all actions appearing to originate from the legitimate account owner.

Requirement

Many organisations operating under access control frameworks cannot formally adopt a privileged agentic tool that has no local authentication requirement:

• ISO 27001:2022 — A.5.15 (Access control) and A.8.2 (Privileged access rights) require that access to privileged tooling is controlled and that only authorised users can operate it
• Cyber Essentials Plus — mandates MFA for cloud services, remote access, and administrative accounts; aligns with the principle that privileged developer tooling should require authentication
• SOC 2 — Common Criteria CC6.1 requires logical access controls on systems that can access or modify sensitive data
• UK government procurement — NCSC guidance and GovAssure expect authentication controls on tools with privileged system access; a practical requirement for any contractor working on public-sector engagements

Proposed Solution

An optional local session authentication gate, disabled by default, configurable per installation. The gate must be cleared once per terminal session before Claude Code will process any prompt. This is a cross-platform requirement — the implementation must work equivalently on macOS, Windows, and Linux.

Authentication methods:

Session token model:

• On successful authentication, Claude Code issues an in-memory session token scoped to the current process
• The token is not written to disk — it exists only in the process environment for the lifetime of the terminal session
• When the terminal closes, the token is gone; a new session requires re-authentication
• No persistent "remember for N days" option — session-scope is the design intent

Proposed CLI:

claude auth setup     # First-time enrolment — choose method, configure secret
claude auth status    # Display current auth configuration
claude auth disable   # Remove the auth requirement (requires passing current auth to confirm)

Proposed settings.json schema:

{
  "localAuth": {
    "enabled": true,
    "method": "totp",
    "sessionScope": "terminal"
  }
}

Enforcement behaviour:

• Auth gate fires once per terminal session, before the first prompt is processed
• All subsequent prompts in the same session pass without re-authentication
• On auth failure: Claude Code exits cleanly with a clear error — no fallback to unauthenticated access

Differentiation

No major AI coding assistant currently requires or offers local session authentication before accepting prompts. GitHub Copilot CLI, Cursor, Aider, Codeium/Windsurf, Gemini CLI, and Amazon Q Developer CLI all authenticate to their respective services but impose no barrier at the point of local invocation. A community feature request for 2FA on Cursor was raised in January 2026 and remains unimplemented — confirming the demand exists and that no vendor has acted on it.

Adding an opt-in local auth gate — particularly one supporting TOTP and passkeys — would be a meaningful and concrete security differentiator, and the first AI coding tool to address the physical and lateral access threat model directly.

For security-conscious teams, regulated industries, and public-sector contractors, this is a practical adoption requirement, not a preference.

Implementation Notes

The minimal viable path for the terminal CLI:

1. A pre-prompt lifecycle gate (analogous to a PreSessionStart hook) that fires before the first prompt is accepted in a new process
2. Auth state held as a process-scoped environment variable — never persisted to disk; process-scoped env vars behave consistently across macOS, Windows, and Linux and are automatically discarded when the terminal process exits
3. TOTP and PIN secrets stored in OS-native credential stores:
   • macOS — Keychain Services
   • Windows — Windows Credential Manager (DPAPI)
   • Linux — Secret Service API via libsecret (GNOME Keyring / KWallet)
4. Biometric authentication via platform APIs:
   • macOS — LocalAuthentication.framework (Touch ID, Face ID)
   • Windows — Windows Hello via WebAuthn API (fingerprint, face, PIN, security key)
   • Linux — PAM with fprintd for fingerprint sensors; libfido2 for FIDO2 / security keys; biometric support is hardware-dependent and less uniform than macOS/Windows — PIN or TOTP recommended as the primary method on Linux
5. SMS OTP via a configurable provider (Twilio, AWS SNS, or equivalent) or delegated to the user's existing MFA service; fully platform-agnostic

A community-level workaround exists today using a shell function wrapper and the UserPromptSubmit hook (exit code 2 to block), but it requires per-machine setup, is bypassable by invoking the binary directly, and is not discoverable to most users. A first-party implementation addresses all three gaps.

Prior Art / Related Issues

• #40271 — Active session termination does not invalidate remote browser sessions (related security theme; different surface — web sessions, not CLI)
• Cursor community feature request — "Cursor should have 2fa and other security features" (January 2026, unimplemented) — confirms cross-industry community demand; no vendor has shipped a solution
• No existing issue found for local CLI authentication on anthropics/claude-code as of 2026-05-12

Raised by UK developer with security-first policy.