64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# Backend Handoff Checklist: Member App Channel
|
|
|
|
This checklist defines backend requirements for app-native member communication.
|
|
|
|
Implementation status:
|
|
|
|
1. Local and deployed reference implementation exists in `/Users/vsg/Documents/VSG Codex/web/backend/secretapi` (sqlite-backed) for register/unregister/events/ack/support.
|
|
2. Wallet-session hardening is implemented via session tokens from `/secret/wallet/verify`; launch should set `SECRET_API_REQUIRE_WALLET_SESSION=true` to enforce fail-closed behavior.
|
|
|
|
## Required Endpoints
|
|
|
|
1. `POST /member/channel/device/register`
|
|
2. `POST /member/channel/device/unregister`
|
|
3. `GET /member/channel/events`
|
|
4. `POST /member/channel/events/{event_id}/ack`
|
|
5. `POST /member/channel/support/ticket` (owner-only)
|
|
|
|
## Contract Source
|
|
|
|
1. `docs/api/member-channel.openapi.yaml`
|
|
2. `docs/api/examples/member-channel.examples.md`
|
|
|
|
## Deterministic Rules
|
|
|
|
1. Wallet session is mandatory for all channel calls.
|
|
2. Membership status must be active for event delivery.
|
|
3. Event ids and dedupe keys are immutable once emitted.
|
|
4. Event ordering is monotonic by server sequence.
|
|
5. `ack` is idempotent per `event_id` + `device_id`.
|
|
6. Admin/support channel actions require principal role `org_root_owner`.
|
|
|
|
## Data Requirements
|
|
|
|
Persist at minimum:
|
|
|
|
1. Device channel binding (`wallet`, `device_id`, `platform`, `push_provider`, `push_token`)
|
|
2. Membership status snapshot at event emission time
|
|
3. Event envelope (`event_id`, class, title/body, payload, policy_hash, dedupe_key)
|
|
4. Delivery and ack timestamps
|
|
5. Principal role snapshot used for channel eligibility
|
|
|
|
## Security Requirements
|
|
|
|
1. Rate limit register/events/ack paths.
|
|
2. Validate wallet in request matches authenticated session wallet.
|
|
3. Reject event polling for suspended/revoked memberships.
|
|
4. Protect against cursor tampering and replay.
|
|
5. Reject support ticket creation for non-owner roles with `contact_your_org_admin`.
|
|
|
|
## Observability Requirements
|
|
|
|
1. Counter metrics per event class emitted.
|
|
2. Counter metrics for successful/failed ack calls.
|
|
3. Channel registration churn metrics by platform.
|
|
4. Correlation id in all responses and logs.
|
|
|
|
## Done Criteria
|
|
|
|
1. App can register channel and poll events deterministically.
|
|
2. Push loss does not lose events because inbox polling is canonical.
|
|
3. Membership status changes immediately gate event visibility.
|
|
4. API behavior matches OpenAPI contract and examples.
|
|
5. Admin/support controls are never exposed to non-owner principals.
|