web/docs/handoff/membership-backend-checklist.md

Backend Handoff Checklist: Membership Activation Flow

This checklist maps current web behavior to required backend implementation.

Current implementation target in this repo:

• web/backend/secretapi

Required Endpoints

1. POST /secret/wallet/intent
2. POST /secret/wallet/verify
3. POST /secret/membership/quote
4. POST /secret/membership/confirm
5. GET /secret/membership/status

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 app download links.

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
7. ownership/payer context fields when applicable:
   • owner_wallet
   • payer_wallet
   • sponsorship_mode

Membership Confirm

Must return:

1. status = membership_active
2. designation_code
3. display_token
4. tx_hash

Membership Status

Must return:

1. status (active|none|suspended|revoked|unknown)
2. selector echo (wallet and/or designation_code)

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.
7. Distinct payer wallet requires deterministic ownership proof.
8. Ownership proof message contract:
   • EDUT-PAYER-AUTH:{designation_code}:{owner_wallet}:{payer_wallet}:{chain_id}
9. Company-first sponsor path allowed when:
   • sponsor_org_root_id is provided,
   • payer wallet is an org_root_owner principal for that org root,
   • payer entitlement status is active.

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. membership status resolution fields for wallet/designation lookups

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
   • membership status lookups 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.
5. Distinct payer requests fail closed without ownership proof.