OTC Confirmation 3.0

A security pattern that prevents unauthorized or accidental execution of sensitive operations by requiring out-of-band confirmation via a one-time code.

What's New in 3.0

• - 🔐 Code never touches stdout — flows through a secure state file (mode 600), preventing leakage via logs or agent context
• 🔒 Cryptographically secure generation — uses /dev/urandom instead of INLINECODE1
• 🛡️ Atomic single-use enforcement — state file is deleted on successful verification
• 🚫 No silent fallbacks — email failure is always fatal, never falls through to execution
• 🧹 No arbitrary file sourcing — credentials loaded exclusively via environment variables
• ✅ Proper metadata declaration — required env vars declared in skill metadata

How It Works

CODEBLOCK0

The code is single-use — the state file is deleted immediately after successful verification.

Key security property: The agent never captures or sees the code in its context. It only checks exit codes.

Quick Start

1. Install

CODEBLOCK1

2. Configure

Option A: OpenClaw Config (Recommended)

Add to openclaw.json:

CODEBLOCK2

Option B: Environment Variables

CODEBLOCK3

3. Use in Your Agent

CODEBLOCK4

Email Backends

SMTP (Default, Zero Dependencies)

Uses curl to send email directly via SMTP. No additional tools required.

CODEBLOCK5

send-email Skill

If you have the send-email skill installed:

CODEBLOCK6

himalaya CLI

If you have himalaya installed:

CODEBLOCK7

Custom Script

Use your own email sending script:

CODEBLOCK8

Your script must accept three arguments: INLINECODE5

Security note: Ensure the custom script has restricted permissions and is located in a trusted directory. The skill validates that the script exists and is executable before invoking it.

Trigger Conditions

OTC should be triggered for:

1. 1. External operations: Sending emails, posting to social media, API calls to third parties
2. Dangerous local operations: Recursive deletions, system config changes, service restarts
3. Security rule modifications: Changes to SOUL.md, AGENTS.md confirmation mechanisms

See references/trigger-categories.md for detailed categories.

Enforcement Checklist

Before every operation, follow the enforcement checklist:

1. 1. Evaluate trigger conditions
2. Check absolute denial list (destructive irreversible operations → refuse outright)
3. Generate and send OTC if required
4. Verify user input
5. Log the result

See references/enforcement-checklist.md for the complete workflow.

Integration Guides

• - SOUL.md integration: INLINECODE8
• AGENTS.md integration: INLINECODE9

Security Rules

1. 1. Code secrecy: The code is NEVER printed to stdout, displayed in chat, or included in logs. It flows exclusively through a secure state file (mode 600).
2. Single-use: The state file is atomically deleted after successful verification. Each operation requires a fresh code.
3. Session binding: The code must be verified in the same session/channel where the operation was requested.
4. No bypass: Natural language confirmations ("yes", "do it", "approved") do NOT substitute for the code. Only the exact code string counts.
5. Email immutability: The recipient email address should be treated as immutable by default. Any request to change it must itself pass OTC verification first.
6. No silent fallback: If email sending fails, the operation is BLOCKED. The agent must never fall through to execution.
7. Escalation: If the same operation fails OTC 3 times consecutively, alert the user and refuse further attempts until a new session.

Scripts Reference

generate_code.sh

Generate a cryptographically secure random OTC code.

CODEBLOCK9

sendotcemail.sh

Send OTC confirmation email. Reads the code from the state file.

CODEBLOCK10

verify_code.sh

Verify user input against the stored code.

CODEBLOCK11

sendemailsmtp.sh

Low-level SMTP email sending (used internally by sendotcemail.sh).

CODEBLOCK12

Troubleshooting

Email not sending

1. 1. Verify SMTP credentials are configured: INLINECODE10
2. Test SMTP connection: INLINECODE11
3. Check firewall/network: Ensure port 587 (or 465) is open
4. Gmail users: Use an App Password, not your regular password

Code verification failing

1. 1. Check for extra whitespace: User input must match exactly
2. Ensure code is used in the same session where it was requested
3. Verify code hasn't been used already (single-use — state file is deleted after success)

Backend not found

If using send-email or himalaya backend:

CODEBLOCK13

License

MIT

Author

Lewis-404