diff --git a/README.md b/README.md index c0187ab..c5cf2a0 100644 --- a/README.md +++ b/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 diff --git a/docs/handoff/membership-backend-checklist.md b/docs/handoff/membership-backend-checklist.md new file mode 100644 index 0000000..ba3f5d0 --- /dev/null +++ b/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`.