payment-invariants

Category: Testing & Security | Uploader: Riklr | Downloads: 0 | Version: v1.0（Latest）

The 5 security invariants that protect Key0's payment flow. Load this to know what must never be broken — and therefore what must always be tested and reviewed.

Changelog: Source: GitHub https://github.com/Riklr/key0

Directory Structure

Current level: .claude/skills/payment-invariants/

📄 SKILL.md 4.4 KB

SKILL.md

---
name: payment-invariants
description: The 5 security invariants that protect Key0's payment flow. Load this to know what must never be broken — and therefore what must always be tested and reviewed.
---

# Key0 Payment Security Invariants

These are the 5 rules that must hold at all times. Violating any one of them means someone can get paid access without paying, pay once and receive multiple tokens, or corrupt the payment state.

---

## Invariant 1 — All State Changes Go Through `transition()`

All challenge state changes MUST use `IChallengeStore.transition(id, fromState, toState, updates)`. Direct writes that bypass the compare-and-swap guard are forbidden.

**Why**: Without CAS, two concurrent `submitProof` calls both read `PENDING`, both pass verification, and both issue a token — one payment, two tokens.

**The rule**: `transition()` only writes if the current state matches `fromState`. If another caller already changed the state, this call returns `false` and must abort.

The full happy-path state machine is: `PENDING → PAID → DELIVERED`. DELIVERED is the terminal success state — it is set after `fetchResourceCredentials` succeeds and the `accessGrant` is stored on the record. EXPIRED and CANCELLED are terminal failure states. All transitions go through `transition()`.

Forbidden patterns:
- Calling `store.set()`, `store.update()`, or direct Map/Redis writes to change `state`
- Reading state and writing it back without going through `transition()`

---

## Invariant 2 — `markUsed()` Return Value Is Checked, with Rollback Guard

`ISeenTxStore.markUsed(txHash, challengeId)` is an atomic SET NX. It returns `false` if that txHash was already used — abort immediately.

**Why**: Without this, the same on-chain transaction can be submitted as proof for two different challenges. One real payment → two different resources unlocked.

Three things must all be present:
1. `transition(PENDING → PAID)` succeeds before `markUsed()` is called
2. `markUsed()` is called before issuing the token; a `false` return aborts the flow
3. **Rollback guard**: if `markUsed()` returns `false`, the state MUST be rolled back via `transition(PAID → PENDING)` — otherwise the challenge is stuck in PAID with no token issued and the honest client can never retry with the same tx

---

## Invariant 3 — On-Chain Verification Runs All Six Checks

`verifyTransfer()` must verify ALL of the following. Skipping any one opens a specific attack:

| # | Check | Attack if skipped |
|---|---|---|
| 1 | `receipt.status === "success"` | Reverted tx accepted — no USDC moved |
| 2 | ERC-20 Transfer event in logs | Any contract interaction accepted, not just transfers |
| 3 | `Transfer.to === challenge.destination` | Payment to attacker's own address accepted |
| 4 | `Transfer.value >= challenge.amountRaw` | Underpayment accepted |
| 5 | `chainId` matches `challenge.chainId` | Free testnet USDC satisfies a mainnet challenge |
| 6 | `block.timestamp <= challenge.expiresAt` | Post-expiry payment accepted |

All six checks are required. Partial verification is not sufficient.

---

## Invariant 4 — JWT Claims and Secret Strength

JWTs issued after payment must:
- Set `jti` = `challengeId` — links the token to the specific challenge for replay detection
- Set `exp` — tokens without expiry are valid forever, even after access should be revoked
- Use HS256 with secret ≥ 32 characters, OR RS256 with a proper key pair

Forbidden:
- Missing `jti` claim
- Missing `exp` claim
- Secrets shorter than 32 characters (brute-forceable)
- `alg: "none"` or algorithm confusion (e.g. switching HS256 to RS256 using a public key as the secret)

---

## Invariant 5 — Callback Boundary Safety

`onPaymentReceived` and `fetchResourceCredentials` are user-supplied callbacks that run after the critical payment path.

**`onPaymentReceived`** — MUST be fire-and-forget:
- Called with `.catch(noop)` and not awaited in the main flow
- If awaited and the webhook is slow/down: client times out, retries, risks double-processing

**`fetchResourceCredentials`** — errors leave the challenge stuck in PAID:
- Its return value (the token) is required, so it is awaited — this is correct
- If it throws, the challenge stays in PAID (never reaches DELIVERED), no token is issued, client paid for nothing
- This is a known recoverable failure state — a refund/recovery cron can detect PAID records with no `accessGrant` and act on them

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

payment-invariants

Directory Structure

SKILL.md

Report

Notice