Add backend handoff checklist for membership activation flow

README.md

@@ -41,6 +41,8 @@ docs/
     contract-addresses.template.json
   api/
     secret-system.openapi.yaml
+  handoff/
+    membership-backend-checklist.md
   schemas/
     offer.v1.schema.json
     entitlement.v1.schema.json

docs/handoff/membership-backend-checklist.md

@@ -0,0 +1,118 @@
+# Backend Handoff Checklist: Membership Activation Flow
+
+This checklist maps current web behavior to required backend implementation.
+
+## Required Endpoints
+
+1. `POST /secret/wallet/intent`
+2. `POST /secret/wallet/verify`
+3. `POST /secret/membership/quote`
+4. `POST /secret/membership/confirm`
+5. `POST /secret/notify`
+
+## Web Behavior Dependency
+
+The landing page currently executes these actions in order:
+
+1. Connect wallet (`eth_requestAccounts`).
+2. Get signature intent.
+3. Sign typed data (`eth_signTypedData_v4`).
+4. Verify signature.
+5. Request membership quote.
+6. Send wallet transaction (`eth_sendTransaction`) using returned tx params.
+7. Confirm membership by tx hash.
+8. Show acknowledged state and optional notify form.
+
+If any endpoint is missing, flow fails closed and shows status error.
+
+## Response Requirements
+
+## Intent
+
+Must return:
+
+1. `intent_id`
+2. `designation_code`
+3. `display_token`
+4. `nonce`
+5. `issued_at`
+6. `expires_at`
+7. `chain_id`
+
+## Verify
+
+Must return:
+
+1. `status = signature_verified`
+2. `designation_code`
+3. `display_token`
+
+## Membership Quote
+
+Must return:
+
+1. `quote_id`
+2. `chain_id`
+3. `currency`
+4. `amount` or `amount_atomic + decimals`
+5. `deadline`
+6. tx execution fields:
+   - either `tx` object for wallet send
+   - or `contract_address` + `calldata` + `value`
+
+## Membership Confirm
+
+Must return:
+
+1. `status = membership_active`
+2. `designation_code`
+3. `display_token`
+4. `tx_hash`
+
+## Notify
+
+Must accept:
+
+1. `email`
+2. `designation_code`
+3. `designation_token`
+4. `wallet`
+5. `locale`
+
+## Security Requirements
+
+1. Replay-safe intent nonce and quote nonce.
+2. Intent and quote TTL enforcement.
+3. Chain allowlist checks.
+4. Origin allowlist checks.
+5. Tx amount/currency/recipient exact-match checks.
+6. Idempotent confirm path for repeated tx_hash submissions.
+
+## Data Persistence Requirements
+
+Persist at minimum:
+
+1. designation code and auth token
+2. wallet and chain id
+3. intent fields and verification time
+4. quote fields and expiry
+5. membership tx hash and activation timestamp
+6. notification email link metadata
+
+## Observability Requirements
+
+1. Correlation id per flow (`intent_id` preferred).
+2. Structured logs for each transition.
+3. Metrics counters for:
+   - intent requests
+   - verify success/fail
+   - quote success/fail
+   - confirm success/fail
+   - notify success/fail
+
+## Done Criteria
+
+1. Web flow reaches acknowledged state on successful membership tx.
+2. Membership inactive wallets cannot complete flow.
+3. Confirm endpoint is idempotent and deterministic.
+4. API matches `docs/api/secret-system.openapi.yaml`.