Otc Confirmation

One-Time Confirmation code security mechanism for sensitive agent operations. Generates a cryptographically secure single-use code, delivers it via a private...

Security Scan

The skill's code, scripts, and required environment variables are coherent with a one-time-code (OTC) email confirmation mechanism; nothing in the package appears to be trying to perform unrelated actions, but you should inspect how SMTP credentials are used and be mindful of the prompt-injection examples in the docs.

Purpose & Capability

The skill is an OTC/email confirmation system and it requires SMTP credentials and curl to send email — these requirements are expected and proportionate. The bundle contains both production-ready shell scripts (generate/send/verify) and Python reference implementations, which matches the README claim of two implementation paths. Declared primaryEnv (OTC_EMAIL_RECIPIENT) and required env vars align with the stated purpose.

Instruction Scope

The SKILL.md instructs the agent to call the included scripts and to keep the code in a permission-restricted state file; that is within scope. However, the document also contains examples and discussion of prompt-injection and 'system prompt override' patterns (pre-scan flagged these). Those appear to be explanatory examples in the threat model rather than instructions to override guards, but you should review the SKILL.md and scripts to confirm no lines attempt to change agent system prompts or perform out-of-band data collection. The skill asks that the agent 'not read the state file' — this is a policy constraint in docs and not an enforced OS-level guarantee; a compromised agent running as the same OS user could still access the file.

Install Mechanism

No remote install or arbitrary downloads — this is an instruction-only skill with bundled scripts and docs. That reduces supply-chain risk compared with fetching executables from unknown URLs. The only external binary dependency declared is curl, which is reasonable for SMTP-over-curl email sending.

Credentials

The skill requires SMTP credentials (OTC_SMTP_USER and OTC_SMTP_PASS) and an email recipient. Those are necessary for its stated function. However, SMTP credentials are sensitive; inspect scripts to ensure credentials are not exposed (for example, passed as literal args visible in process listings or written to logs). SKILL.md references additional optional env vars (SMTP_HOST/PORT, OTC_EMAIL_BACKEND, OTC_CUSTOM_EMAIL_SCRIPT) which are reasonable but should be audited when enabling backends or custom scripts.

Persistence & Privilege

The skill does not request always:true and is user-invocable. It does not claim to modify other skills or system-wide agent configuration. Its stated behavior (create per-user state dir and state file) is standard for this type of guard and scoped to the skill.

Scan Findings in Context

[ignore-previous-instructions] expected: Detected phrase(s) commonly associated with prompt-injection. In this package they appear in the threat-modeling/docs and examples (explaining prompt-injection attacks) rather than as an instruction for the skill to override system prompts. Still, review SKILL.md and examples to ensure none of the shipped scripts or templates instruct agents to ignore prior system prompts.

[system-prompt-override] expected: Detected 'system-prompt-override' pattern. This is expected in documentation that teaches about prompt-injection threats. Verify there are no embedded instructions in SKILL.md or templates that attempt to change/overwrite agent system prompts or perform silent prompt changes at runtime.

Assessment

Before installing or enabling this skill: 1) Manually inspect the three shell scripts (generate_code.sh, send_otc_email.sh/send_email_smtp.sh, verify_code.sh) to confirm they do not echo the code, do not log secrets, and that credentials are not passed on the command line in a way visible via ps. 2) Run the skill in a non-production sandbox first and test the state-file lifecycle and permission bits (state dir mode 700, state file mode 600). 3) Use a dedicated SMTP account with limited privileges and rotate its password if compromised. 4) If you enable a custom backend script, verify it is trusted and executable only by your user. 5) Be aware the 'agent must not read the state file' is a procedural control — a compromised agent running as the same OS user could read it; consider isolating the guard (different user, container, or stricter sandbox). 6) Note the SKILL.md includes prompt-injection discussion — review the docs and templates so you are comfortable there are no instructions that would weaken your agent's system prompt or security posture. If you want extra assurance, have a security-savvy reviewer audit the scripts for credential handling (curl usage, logging, process args) prior to production use.

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 $RANDOM
• 🛡️ 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

User request (sensitive op)
  → Agent runs generate_code.sh (code stored in state file, never printed)
  → Agent runs send_otc_email.sh (reads code from state file, sends email)
  → Agent replies in chat: "需要确认，请查看邮箱"
  → User reads email, replies with code in ORIGINAL chat session
  → Agent runs verify_code.sh (reads state file, compares, deletes on match)
  → Agent executes operation

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

clawhub install otc-confirmation

2. Configure

Option A: OpenClaw Config (Recommended)

Add to openclaw.json:

{
  "skills": {
    "entries": {
      "otc-confirmation": {
        "enabled": true,
        "env": {
          "OTC_EMAIL_RECIPIENT": "[e-mail]",
          "OTC_EMAIL_BACKEND": "smtp",
          "OTC_SMTP_HOST": "smtp.gmail.com",
          "OTC_SMTP_PORT": "587",
          "OTC_SMTP_USER": "[e-mail]",
          "OTC_SMTP_PASS": "your-app-password"
        }
      }
    }
  }
}

Option B: Environment Variables

export OTC_EMAIL_RECIPIENT=[e-mail]
export OTC_EMAIL_BACKEND=smtp
export OTC_SMTP_HOST=smtp.gmail.com
export OTC_SMTP_PORT=587
export OTC_SMTP_USER=[e-mail]
export OTC_SMTP_PASS=your-app-password

3. Use in Your Agent

SKILL_DIR="{baseDir}"

# Step 1: Generate code (stored in secure state file, nothing printed to stdout)
bash "$SKILL_DIR/scripts/generate_code.sh"

# Step 2: Send email (reads code from state file internally)
bash "$SKILL_DIR/scripts/send_otc_email.sh" "Send email to [e-mail]" "Discord #work"

# Step 3: Reply in chat (do NOT mention the code)
echo "需要确认，请查看你的注册邮箱"

# Step 4: Wait for user input, then verify (reads expected code from state file)
bash "$SKILL_DIR/scripts/verify_code.sh" "$USER_INPUT"

if [ $? -eq 0 ]; then
  echo "OTC通过，执行操作..."
  # Execute the operation
else
  echo "确认码不匹配，操作取消"
fi

Email Backends

SMTP (Default, Zero Dependencies)

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

export OTC_EMAIL_BACKEND=smtp
export OTC_SMTP_HOST=smtp.gmail.com
export OTC_SMTP_PORT=587
export OTC_SMTP_USER=[e-mail]
export OTC_SMTP_PASS=your-app-password

send-email Skill

If you have the send-email skill installed:

export OTC_EMAIL_BACKEND=send-email

himalaya CLI

If you have himalaya installed:

export OTC_EMAIL_BACKEND=himalaya

Custom Script

Use your own email sending script:

export OTC_EMAIL_BACKEND=custom
export OTC_CUSTOM_EMAIL_SCRIPT=/path/to/your/send_email.sh

Your script must accept three arguments: <to> <subject> <body>

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. 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. 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: examples/soul_md_integration.md
• AGENTS.md integration: examples/agents_md_integration.md

Security Rules

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.

bash scripts/generate_code.sh [prefix] [length]
# Default: cf-XXXX (prefix="cf", length=4)
# Code is stored in a secure state file (mode 600)
# Nothing is printed to stdout

send_otc_email.sh

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

bash scripts/send_otc_email.sh <operation> [session] [lang]
# Example:
bash scripts/send_otc_email.sh "Send email to [e-mail]" "Discord #work"
# If email fails → exits with error (never falls through)

verify_code.sh

Verify user input against the stored code.

bash scripts/verify_code.sh <user_input>
# Exit code 0: verified (state file deleted — single-use)
# Exit code 1: mismatch or no pending code

send_email_smtp.sh

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

bash scripts/send_email_smtp.sh <to> <subject> <body>
# Requires OTC_SMTP_* environment variables

Troubleshooting

Email not sending

1. Verify SMTP credentials are configured: test -n "$OTC_SMTP_USER" && echo "set" || echo "not set"
2. Test SMTP connection: curl -v smtp://$OTC_SMTP_HOST:$OTC_SMTP_PORT
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. 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:

# Check if command exists
command -v send-email
command -v himalaya

# Install if missing
clawhub install send-email  # or install himalaya

License

MIT

Author

Lewis-404