web/docs/handoff/member-channel-backend-checklist.md

Backend Handoff Checklist: Member App Channel

This checklist defines backend requirements for app-native member communication.

Implementation status:

1. Local reference implementation exists in /Users/vsg/Documents/VSG Codex/web/backend/secretapi (sqlite-backed) for register/unregister/events/ack/support.
2. Production deployment + wallet-session auth hardening still required before launch.

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.