totp-presence-plugin

Plug-and-play totp-presence for Claude Code and Codex CLI — a deterministic, channel-independent owner-presence gate against prompt injection.

STATUS: v0.1.1 — released via the agfpd-marketplace. SOFT live, HARD opt-in. Deferred: Codex HARD beyond best-effort; Windows (WSL only); Linux (experimental until live-tested). Architecture and phase history: CLAUDE.md.

Modes

• SOFT (default, zero-sudo, one command): MCP tools (totp_verify / totp_check_session) the agent calls itself, plus a tiny conditional SessionStart directive. Advisory — cannot DENY a tool call; tamper_resistant: false.
• HARD (opt-in, two honest actions — one sudo, one phone pairing): a root-anchored PreToolUse guard fail-closes every gated tool (read-only tools pass by design) until a fresh presence window is open. Claude: full .* coverage. Codex: best-effort (Bash/apply_patch/mcp__ only).

Install

# Claude Code (per-project scope; add the agfpd marketplace once if needed)
claude plugin marketplace add agfpd/agfpd-marketplace
claude plugin install totp-presence@agfpd --scope project
# Codex CLI (host-global)
codex plugin add totp-presence@agfpd

The source repo is private (agfpd org), so installing requires read access to the org (git/gh authenticated) — the same access model as every other agfpd plugin. The MCP server is published separately on npm as @agfpd/totp-presence-mcp and .mcp.json launches it via npx, so Node ≥18 must be on PATH (npx fetches and runs it on first session start).

Restart the session afterward — hooks.json / .mcp.json are not hot-reload. SOFT (advisory MCP) is live immediately. For HARD: /totp-presence:totp-setup (one guided sudo + pair the phone once), then restart. Confirm with /totp-presence:totp-status. (Codex has no slash commands — the same operations are the totp-setup / totp-status skills, which Claude also surfaces as those /names.)

Capability matrix

| | SOFT (default) | HARD (opt-in) | |---|---|---| | Install cost | one command, zero sudo | one guided sudo + one phone pairing | | What it does | MCP tools the agent calls itself + a tiny conditional SessionStart directive | root-anchored PreToolUse guard fail-closes every gated tool until a fresh presence window | | Can DENY a tool call? | no (advisory) | yes | | tamper_resistant | false | true | | Claude Code reach | this project (--scope project) | this project; full .* tool coverage | | Codex CLI reach | host-global | host-global; best-effort (Bash + apply_patch + mcp__ only; headless codex exec does not fire the hook) |

The trust core (/etc/totp-presence: seed, verifier, sudoers) is host-global — core_installed / tamper_resistant are host properties. But where HARD actually fires is asymmetric: on Claude it is per-project; on Codex it is host-global but partial. So tamper_resistant: true means "the host has a root anchor," not "every agent on this machine is gated." /totp-presence:totp-status reports the live matrix with no false assurance.

Honest ceiling

SOFT installs plug-and-play with zero sudo; the two human actions apply only to HARD. True zero-step HARD is impossible without gutting the guarantee — granting root once and pairing the phone once ARE the product. Windows native is unsupported (WSL only); Linux is experimental until live-tested.

Apache-2.0 © Artur Agafapudov. Trust core copied byte-for-byte from the audited upstream primitive.