Signet Guardian , Payment Guard Middleware

intent

Signet Guardian is a policy firewall for any skill that handles money. it enforces a master switch (payments on/off), per-transaction limits, monthly spend caps, and optional confirmation thresholds. use this skill before initiating any payment and after recording a successful payment. the skill does not block payments at runtime by itself; other payment-capable skills must call signet-preflight (before) and signet-record (after) by contract. this gives you one place to enforce policy across all payment flows in your agent.

inputs

Policy configuration (source of truth, in order of precedence):

1. OpenClaw config: signet.policy in the main control config (if the extension is installed).
2. File fallback: {baseDir}/references/policy.json (where {baseDir} is set by OPENCLAW_SKILL_DIR or OPENCLAW_BASE_DIR).

Policy schema:

Field	Type	Meaning
paymentsEnabled	boolean	Master switch. if false, all payments denied.
maxPerTransaction	number	Max amount per single transaction (e.g. 20).
maxPerMonth	number	Max total spend in current calendar month (e.g. 500).
currency	string	ISO code (e.g. GBP, USD). request currency must match or preflight denies.
requireConfirmationAbove	number	If amount exceeds this, return CONFIRM_REQUIRED (e.g. 5).
blockedMerchants	array (optional)	List of substrings; payee matching any is denied.
allowedMerchants	array (optional)	If non-empty, only payees matching one are allowed.
version	number (optional)	For future policy migrations.

Ledger file: {baseDir}/references/ledger.jsonl (strict JSONL, one object per line, newline-separated). no extra setup needed; created on first write.

External dependencies: none (file-based). all policy and ledger data lives in {baseDir}/references/.

Edge cases to know:

• if policy file missing or invalid JSON, preflight returns DENY (default-deny).
• if ledger file does not exist, signet-record creates it.
• idempotency keys prevent double-counting on retries; same key used in preflight and record is idempotent on record.
• concurrent record calls lock on {baseDir}/references/.ledger.lock to enforce monthly cap safely.
• currency mismatch between request and policy results in DENY; no FX conversion happens.
• amount must be > 0; zero or negative amounts are denied.

procedure

Step 1: Call signet-preflight before any payment

Input: amount (number > 0), currency (ISO code), payee (string), purpose (string), optional idempotency-key (string for dedup), optional caller-skill (string for audit).

Command:

signet-preflight --amount 15 --currency GBP --payee "shop.example.com" --purpose "Subscription" [--idempotency-key "sub-123"] [--caller-skill "my-payment-skill"]

Output (JSON):

• { "result": "ALLOW", "reason": "Within policy" } , safe to proceed.
• { "result": "CONFIRM_REQUIRED", "reason": "Above confirmation threshold of £5" } , ask user to confirm.
• { "result": "DENY", "reason": "Payments disabled by policy" } , do not proceed; tell user.

Exit code: 0 for ALLOW or CONFIRM_REQUIRED, 1 for DENY.

Output location: stdout (JSON). denials are also logged to ledger with status: "denied".

Step 2: Handle preflight result

See decision points section below. if ALLOW, proceed to payment. if CONFIRM_REQUIRED, ask user and only proceed if confirmed. if DENY, stop and inform user of the reason.

Step 3: Initiate payment (caller skill's responsibility)

the calling skill executes the actual payment (e.g. via Stripe, PayPal, bank API, etc.). signet-guardian does not do this; it only validates policy.

Input to payment handler: same amount, currency, payee, purpose as passed to preflight.

Step 4: Call signet-record after successful payment

only call this if the payment succeeded. use the same amount, currency, payee, purpose, and idempotency-key (if used in preflight).

Command:

signet-record --amount 15 --currency GBP --payee "shop.example.com" --purpose "Subscription" [--idempotency-key "sub-123"] [--caller-skill "my-payment-skill"]

Validation scope: signet-record re-checks currency and monthly cap (under file lock). it does not re-check paymentsEnabled or merchant rules (those are preflight's job). if the same idempotency-key was already recorded, this is a no-op (idempotent).

Output location: appended to {baseDir}/references/ledger.jsonl (strict JSONL format).

Exit code: 0 on success, 1 if currency mismatch or monthly cap exceeded (cap check happens under lock).

Step 5: Query spending and history (optional)

call signet-report to show user their transaction history or current month spend.

Command:

signet-report --period today
signet-report --period month

Output: human-readable summary plus optional JSON (caller skill determines format).

Step 6: Configure or view policy (optional, usually one-time)

run signet-policy to view, edit, or set up policy.

Commands:

signet-policy --show         # Print current policy (config, then file).
signet-policy --edit         # Open policy.json in $EDITOR.
signet-policy --wizard       # Interactive setup (no JSON editing).
signet-policy --migrate-file-to-config  # Copy file policy into OpenClaw config (one-time).

decision points

If preflight returns ALLOW:

• the calling skill may proceed with the payment immediately. no user confirmation needed.

If preflight returns CONFIRM_REQUIRED:

• the calling skill must ask the user explicitly: "allow this payment of £X to Y for [purpose]?"
• if user confirms, proceed with payment and call signet-record after.
• if user declines, do not call signet-record and do not attempt the payment. inform user the action was cancelled.

If preflight returns DENY:

• do not proceed. do not call signet-record. do not attempt the payment.
• show the user the reason from the preflight response (e.g. "payments disabled by policy", "amount exceeds per-transaction limit", "merchant blocked").
• optional: log the denied request in your own audit trail for support.

If currency in request does not match policy currency:

• preflight returns DENY with reason "currency mismatch: request is USD, policy is GBP".
• no FX conversion is attempted. the caller skill is responsible for converting or re-submitting with the correct currency.

If amount is zero or negative:

• preflight returns DENY with reason "amount must be > 0".

If policy file is missing or invalid JSON:

• preflight returns DENY with reason "policy not found or invalid".
• call signet-policy --show or signet-policy --wizard to set up policy.

If signet-record is called with same idempotency-key twice:

• second call is a no-op (idempotent). no duplicate ledger entry is created. exit code 0.
• use this for retries: same key ensures the monthly cap is not double-counted.

If signet-record detects currency mismatch at record time:

• record is rejected (exit code 1, reason "currency mismatch"). payment already happened.
• this should not occur if preflight and payment succeeded with matching currency. if it does, investigate policy changes mid-flow.

If signet-record detects monthly cap would be exceeded (under lock):

• record is rejected (exit code 1, reason "monthly cap exceeded: X + Y would exceed Z").
• payment already happened. do not retry. inform user that the transaction succeeded but ledger recording failed due to policy.
• optional: use future authorize/settle pattern to reserve budget before payment (not yet implemented in v1).

If concurrent calls race on the monthly cap:

• file lock ({baseDir}/references/.ledger.lock) ensures only one record call updates the ledger at a time.
• preflight is advisory (no lock); both may return ALLOW if called in parallel. record will enforce the cap; the second call to record (if it would exceed cap) is rejected.
• design your agent to handle this: if record fails with cap error, inform the user and do not retry without explicit re-confirmation.

output contract

signet-preflight output (stdout):

{
  "result": "ALLOW" | "CONFIRM_REQUIRED" | "DENY",
  "reason": "string describing the decision"
}

exit code 0 for ALLOW or CONFIRM_REQUIRED, 1 for DENY.

signet-record output (stdout):

{
  "status": "recorded" | "no-op (idempotent)" | "rejected",
  "reason": "string"
}

exit code 0 on success or idempotent no-op, 1 on rejection.

Ledger format (file: {baseDir}/references/ledger.jsonl): strict JSONL, one object per line, each containing:

{
  "ts": "2025-01-15T14:32:00Z",
  "status": "completed" | "denied",
  "amount": 15,
  "currency": "GBP",
  "payee": "shop.example.com",
  "purpose": "Subscription",
  "callerSkill": "my-payment-skill",
  "idempotencyKey": "sub-123",
  "reason": "Within policy" | "Payments disabled" | etc.
}

all fields present except callerSkill and idempotencyKey (only if provided).

signet-report output: human-readable summary (caller skill determines format). may include total spend this month, transaction list, last N transactions, etc.

signet-policy output: current policy in JSON (for --show) or confirmation message (for --edit, --wizard, --migrate).

outcome signal

• preflight ALLOW: the skill calling signet-guardian sees exit code 0 and result "ALLOW", and proceeds confidently with the payment.
• preflight CONFIRM_REQUIRED: the agent prompts the user (e.g. "confirm payment of £X?"), user clicks yes, and the skill proceeds.
• preflight DENY: the agent shows the user the denial reason (e.g. "payment limit exceeded this month") and stops.
• signet-record success: the skill sees exit code 0 and status "recorded", confirming the ledger entry is written and monthly cap is enforced.
• signet-record idempotent: the skill retries with the same idempotency-key and sees exit code 0, confirming no duplicate was created.
• signet-record cap exceeded: the skill sees exit code 1 and reason "monthly cap exceeded", confirming the ledger was protected but the payment already went through (alert user).
• signet-report: the user sees their current month spend, transaction history, and confidence in policy enforcement.
• signet-policy --wizard or --edit: the user completes setup, sees "policy saved" and subsequent preflight calls succeed with policy checks in effect.

overall: the user knows signet-guardian is working when:

1. every payment is gated by a preflight check that respects their policy.
2. large payments (above threshold) require explicit confirmation.
3. they can view their spending via signet-report.
4. monthly caps are enforced: if they hit the cap, signet-record rejects the entry and they are informed.
5. their policy is editable and takes effect immediately on the next preflight.