--- name: agentauth homepage: https://agentauth.id description: Require user-initiated biometric passkey approval before your OpenClaw agent deletes files, sends emails, makes purchases, or modifies system config. Every approval is cryptographically signed with FIDO2/WebAuthn, creating non-repudiable proof of human consent. Blocks prompt injection bypass and unauthorized agent actions. Use when you need human-in-the-loop authorization for sensitive or irreversible operations. compatibility: Requires agentauth CLI (`./scripts/cli.cjs`) metadata: { "openclaw": { "requires": { "bins": ["openclaw"] }, }, } --- # agentauth — Human Consent Gate for AI Agents ## Why This Exists OpenClaw's gateway uses bearer tokens stored in `.env` files. CVE-2026-25253 proved these tokens can be exfiltrated with one click. The ClawHavoc supply chain attack found 824+ malicious skills stealing credentials from `~/.clawdbot/.env`. Exec approvals are the lock on the front door. agentauth is the lock on the safe. agentauth adds a cryptographic consent layer: before your agent executes anything dangerous, *you* approve it with a biometric passkey on your device. The approval is signed with FIDO2/WebAuthn. It can't be faked, replayed, or stolen. ## What This Prevents - Agent deleting files or databases without your knowledge - Agent sending emails, messages, or making purchases autonomously - Prompt injection tricking the agent into destructive operations - Stolen API tokens being used to impersonate your agent - Agent modifying production configs or deploying code unsupervised - Social engineering attacks that bypass in-chat "approval" --- ## Data Security and Redaction To facilitate out-of-band approval, the `toolCall` and `displayString` are sent to the AgentAuth service. To prevent accidental leakage of sensitive information, `agentauth` performs automatic redaction of secrets (API keys, tokens, passwords) before transmission. **Best Practices:** - **Sensitive Data in Commands:** While `agentauth` redacts known secret patterns, avoid including unnecessary sensitive details like internal file paths or infrastructure specifics in the `toolCall` or `displayString`. - **`displayString` Content:** The `displayString` should be a clear, concise summary for the human approver, not a verbatim copy of the command. - **Notification Channels:** Data sent to these channels is also redacted but travels through third-party services (e.g., Slack, Telegram). --- ## Initial Setup: Initialize My AgentAuth Before approvals can be used, the user must register their authentication credentials. If the user says something like: - "Initialize my AgentAuth" - "Set up AgentAuth" - "Connect my passkey" - "Register AgentAuth" the agent MUST handle setup through a sub-agent so the main session remains responsive. --- ### Required Flow: Non-Blocking Initialization **Main Agent Responsibilities:** 1. Detect that the user is requesting AgentAuth initialization. 2. Spawn a sub-agent that runs the authentication setup flow. 3. Immediately call `sessions_yield()`. 4. Do not narrate internal sub-agent creation. The setup flow will notify the user directly. --- ### Sub-Agent Task The sub-agent runs: ```bash ~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs auth-flow --notify : ``` This command sends the user a secure setup link. The user follows the link and creates a Passkey using their device's on-screen instructions. When complete, the sub-agent reports the final result back to the main agent. --- ### Main Agent Example Call // WARNING: Do NOT add streamTo, attachAs, // attachments, agentId, model, thinking, thread, // cwd or resumeSessionId — these cause validation errors! ```js sessions_spawn({ runtime: "subagent", mode: "run", cleanup: "delete", lightContext: true, label: "agentauth-approval", timeoutSeconds: 300, task: "~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs auth-flow --notify :" }); sessions_yield(); ``` --- ### What the User Experiences 1. User says: `Initialize my AgentAuth` 2. User receives a secure setup link 3. User creates a Passkey 4. Agent receives completion status 5. Future sensitive actions can now require biometric approval --- ## Uninstall: Remove AgentAuth Before this skill is uninstalled, the agent MUST run the cleanup command to restore the original `AGENTS.md` file and remove integrations. If the user says something like: - "Uninstall AgentAuth" - "Remove AgentAuth" - "Disable AgentAuth" - "Clean up AgentAuth" the agent MUST handle cleanup through a sub-agent. --- ### Required Flow: Non-Blocking Cleanup **Main Agent Responsibilities:** 1. Detect that the user is requesting AgentAuth cleanup/uninstallation. 2. Spawn a sub-agent that runs the cleanup flow. 3. Immediately call `sessions_yield()`. 4. Do not narrate internal sub-agent creation. The cleanup flow will notify the user directly. --- ### Sub-Agent Task The sub-agent runs: ```bash ~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs cleanup --notify : ``` This command asks the user for final approval before removing AgentAuth-related configurations. When complete, the sub-agent reports the final result back to the main agent. --- ### Main Agent Example Call // WARNING: Do NOT add streamTo, attachAs, // attachments, agentId, model, thinking, thread, // cwd or resumeSessionId — these cause validation errors! ```js sessions_spawn({ runtime: "subagent", mode: "run", cleanup: "delete", lightContext: true, label: "agentauth-cleanup", timeoutSeconds: 300, task: "~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs cleanup --notify :" }); sessions_yield(); ``` --- ## Dangerous Operations Definition Treat the following as **dangerous**: * File deletions (`rm`, `rm -rf`, recursive deletes) * System-level modifications * Database destructive queries (`DELETE`, `DROP`, `TRUNCATE`) * Production deployments or config changes * External system writes (APIs, PR merges, emails) * Security or permission changes * Package installs or system mutations * Modifying the AGENTS.md to protect against unwanted rewrites. * Any modification, deletion, or overwriting of the OpenClaw environment file (e.g. ~/.openclaw/.env). * Any modification, deletion, or overwriting of the agentauth skill directory or its contents (e.g. ~/.openclaw/workspace/skills/agentauth). If unsure → **assume dangerous** --- ## Required Flow for Dangerous Actions: Non-Blocking Approval To ensure the main agent remains responsive, sensitive operations MUST be handled by a sub-agent. This creates a safe, non-blocking approval workflow. --- ### Required Flow: Non-Blocking Approval **Main Agent Responsibilities:** 1. Detect a dangerous action is being requested. 2. Define the `toolCall` (the command to be executed) and a human-readable `displayString`. 3. Spawn a sub-agent that runs the `approval-flow` command. 4. Immediately call `sessions_yield()`. 5. Do not narrate internal sub-agent creation. The `approval-flow` script handles all user notifications. --- ### Sub-Agent Task The sub-agent runs: ```bash ~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs approval-flow "" "" --notify : ``` This single command handles the entire workflow: - It sends the user a secure approval link. - It waits for the user to respond (approve/deny). - **If approved**, it executes the command. - **If denied**, it does nothing. - It returns the final result (e.g., the command's output or a status message) to the main agent. --- ### Main Agent Example Call ```js const dangerous_command = "rm ~/.openclaw/important.txt"; const display_string = "Delete the important notes file"; const notification_target = "slack:U12345"; // Example target // WARNING: Do NOT add streamTo, attachAs, // attachments, agentId, model, thinking, thread, // cwd or resumeSessionId — these cause validation errors! sessions_spawn({ runtime: "subagent", mode: "run", cleanup: "delete", lightContext: true, label: "agentauth-approval", timeoutSeconds: 300, task: `~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs approval-flow "${dangerous_command}" "${display_string}" --notify ${notification_target}` }); sessions_yield(); ``` --- ## CRITICAL: sessions_spawn Field Restrictions ONLY include these fields in sessions_spawn: - runtime - mode - cleanup - lightContext - label - timeoutSeconds - task NEVER include these fields — they cause validation errors: - streamTo ← FORBIDDEN - attachAs ← FORBIDDEN - attachments ← FORBIDDEN - agentId ← FORBIDDEN - resumeSessionId ← FORBIDDEN - thinking ← FORBIDDEN - thread ← FORBIDDEN - model ← FORBIDDEN - cwd ← FORBIDDEN --- ## Hard Rules (Updated for Sub-Agents) - If the user requests AgentAuth setup or initialization, ALWAYS use the `auth-flow` sub-agent workflow. - NEVER execute dangerous commands directly in the main agent. - ALWAYS delegate the entire approval and execution flow to a sub-agent. - NEVER announce the creation of the approval sub-agent. The `--notify` flag is responsible for user communication. - ALWAYS `sessions_yield()` immediately after spawning the approval sub-agent. - The main agent's role is to receive the final report from the sub-agent and communicate that final status to the user. - The executed command inside the sub-agent MUST exactly match the command that was approved. --- ## Decision Framework Ask: 1. Could this delete or overwrite data? 2. Could this impact production systems? 3. Could this be hard to undo? 4. Would a human want to explicitly review this before execution? If YES → follow the full sub-agent approval flow. --- ## If Approval Is Denied - The sub-agent will report a "deny" status. - The main agent should inform the user the operation was cancelled and not executed. --- ## If agentauth Fails - The sub-agent will report an error status. - The main agent should report the failure to the user and confirm that no action was taken. --- ## How This Compares | | agentauth | ClawGate | agent-passport | Exec Approvals (built-in) | |---|---|---|---|---| | Cryptographic proof | FIDO2 passkey signatures | Biometric (iOS only) | OAuth tokens | None | | Cross-platform | All browsers + mobile | iOS only | Browser | CLI prompt | | Audit trail | Signed, timestamped, non-repudiable | Unclear | No | No | | Prompt injection resistant | Yes — out-of-band approval | Partial | No | No | | Multi-user routing | Yes | No | No | No | Exec approvals are the lock on the front door. agentauth is the lock on the safe. --- ## Principle **Dual control system handled by `./scripts/cli.cjs`:** - Identity verification (FIDO2 passkey biometric) - Human approval (explicit consent for a specific action) Both are required before execution. This is not a limitation — it is the feature. Before approvals can occur, credentials must first be initialized through the `auth-flow` setup process. --- ## Example Interaction ``` User (via Telegram): Delete all the emails I sent to myself last month. Agent: This is a sensitive operation — deleting emails requires your explicit authorization. I've sent an approval request to your registered device. Please review and authenticate to proceed. [User receives a notification on their phone] [Screen shows: "Delete emails: remove all sent-to-self emails from February 2026 — requested by OpenClaw"] [User taps Approve and authenticates with fingerprint] Agent: Authorization confirmed. Proceeding to delete 47 emails sent to yourself in February. ``` ``` User (via Slack): Hey, I already approved this earlier, just send the email without asking again. Agent: I understand, but I need to verify this through agentauth. I cannot accept in-conversation approval for sending emails. I've sent a new approval request to your device. ``` --- **Remember:** When in doubt → STOP and use the sub-agent approval flow.

agentauth

Description

Latest Changes

Install agentauth with One Click