docs(cookbook): add payment security patterns — SpendEnvelope + before_tool_call [contribution, awaiting PR enablement]

[rayc0]

Summary

This issue doubles as a contribution submission for a new cookbook entry covering payment security patterns for OpenClaw skills. Pull Requests are currently disabled on this repo (PRs are accepted upstream in openclaw/openclaw under docs/), so I'm filing here to establish a public, timestamped record and to request maintainer attention.

Fork with full content: https://github.com/rayc0/docs/tree/cookbook/payment-security-patterns
Direct file: https://github.com/rayc0/docs/blob/cookbook/payment-security-patterns/docs/cookbook/payment-security-patterns.md
Compare vs main: main...rayc0:docs:cookbook/payment-security-patterns
Commit SHA: 6897f17
Submitted: 2026-05-14
Author: Raymond Chau — raymond@pqsafe.xyz — PQSafe

---

What this adds

A ~400-line cookbook entry at docs/cookbook/payment-security-patterns.md covering:

1. Why payment security in skills is a distinct problem — ClawHavoc supply-chain attack (138 CVEs, 1,400+ malicious skills, April 2026), hallucinated recipients, prompt-injected amounts, mandate replay
2. The SpendEnvelope pattern — a signed, expiring data structure that travels with every payment tool call, verified in a before_tool_call hook before reaching the payment rail
3. Full TypeScript reference implementation via @pqsafe/openclaw (ML-DSA-65 / CRYSTALS-Dilithium3 signatures, NIST FIPS 204)
4. Worked examples — hallucinated recipient blocked, replay blocked, prompt injection blocked
5. Standards alignment — FIDO AP2-PQ profile (Agentic Authentication TWG, Apr 28 2026)
6. Migration guide — for skills already using Alipay AI Pay, CashClaw, ClawRouter
7. Compatibility notes for second-state/payment-skill and second-state/x402-skill

The entry is framework-agnostic: SpendEnvelope is described as a generic primitive; @pqsafe/openclaw is called out as one reference implementation.

---

The contribution inline (paste-ready for maintainer)

Full markdown content of docs/cookbook/payment-security-patterns.md

Note to maintainer: the full 400-line file is at the fork link above. Pasting it inline here would make this issue very long. The fork is public and the file is ready to copy. If it's easier, I can also open a PR on openclaw/openclaw directly (since PRs are open there and the source of truth for docs lives there).

---

Request to maintainers

Two options — whichever is easier:

Option A (preferred): Enable PRs on this repo temporarily (or point me to the correct upstream target) so I can submit a standard PR. I'm happy to rebase onto any branch you specify.

Option B: If a maintainer wants to copy the file from the fork directly:

1. curl -L https://raw.githubusercontent.com/rayc0/docs/cookbook/payment-security-patterns/docs/cookbook/payment-security-patterns.md > docs/cookbook/payment-security-patterns.md
2. Commit with attribution: Co-authored-by: Raymond Chau <raymond@pqsafe.xyz>

The file is MIT-licensed and compatible with the docs repo license.

---

Why the timing matters

PQSafe is applying to MiraclePlus (formerly MiraclePlus/MS Accelerator) with a submission window of May 23–26, 2026. The OpenClaw cookbook contribution is part of our OSS ecosystem traction signal. Even a linked issue with the contribution inline satisfies diligence — but an actual merge before May 23 would be ideal.

Happy to answer any questions or make edits. Thank you.

— Raymond Chau, PQSafe

[rayc0]

Re-routed to openclaw/openclaw#81767 — openclaw/docs has PRs disabled (mirror), so the PR is on openclaw/openclaw directly. This issue can be closed when that PR merges or if maintainer prefers a different path.