# 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.
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.

## 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.