159 lines
4.0 KiB
Markdown
159 lines
4.0 KiB
Markdown
# 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/wallet/session/refresh`
|
|
4. `POST /secret/wallet/session/revoke`
|
|
5. `POST /secret/membership/quote`
|
|
6. `POST /secret/membership/confirm`
|
|
7. `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`
|
|
4. `session_token`
|
|
5. `session_expires_at`
|
|
|
|
## Wallet Session Refresh
|
|
|
|
Must return:
|
|
|
|
1. `status = session_refreshed`
|
|
2. `wallet`
|
|
3. `session_token`
|
|
4. `session_expires_at`
|
|
|
|
## Wallet Session Revoke
|
|
|
|
Must return:
|
|
|
|
1. `status = session_revoked`
|
|
2. `wallet`
|
|
3. `revoked_at`
|
|
|
|
## 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.
|
|
10. Optional strict chain verification mode:
|
|
- when `SECRET_API_REQUIRE_ONCHAIN_TX_VERIFICATION=true`,
|
|
- membership confirm must fail closed if chain RPC verification is unavailable.
|
|
11. Wallet-session fail-closed mode:
|
|
- when `SECRET_API_REQUIRE_WALLET_SESSION=true`,
|
|
- wallet-scoped APIs must reject missing/invalid/revoked/expired sessions.
|
|
|
|
## 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.
|