85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
# Backend Handoff Checklist: Marketplace Checkout and Entitlements
|
|
|
|
This checklist maps store behavior to required marketplace backend implementation.
|
|
|
|
## Required Endpoints
|
|
|
|
1. `GET /marketplace/offers`
|
|
2. `GET /marketplace/offers/{offer_id}`
|
|
3. `POST /marketplace/checkout/quote`
|
|
4. `POST /marketplace/checkout/confirm`
|
|
5. `GET /marketplace/entitlements?wallet=...`
|
|
|
|
All marketplace endpoints require authenticated app/session context.
|
|
|
|
## Required Gate Behavior
|
|
|
|
1. Quote endpoint must deny checkout when membership is not active.
|
|
2. Confirm endpoint must verify quote policy hash and tx match.
|
|
3. Entitlement state must default fail-closed for unknown values.
|
|
4. Quote/confirm must deny cross-boundary paid execution when `org_root_id` does not match active suite entitlement.
|
|
5. `availability_state=parked` must block paid execution paths.
|
|
6. Quote generation must fail closed when entitlement contract is unconfigured (`entitlement_contract_unconfigured`).
|
|
|
|
## Store Dependency Mapping
|
|
|
|
1. Store catalog requests `/marketplace/offers` (fallback to local JSON until live).
|
|
2. Store quote action posts selected `offer_id` and ownership wallet.
|
|
3. Optional payer wallet may differ and must include ownership proof.
|
|
4. Store sends org-boundary context (`org_root_id`, `principal_id`, `workspace_id`) when available.
|
|
5. Store expects quote payload with tx execution fields.
|
|
6. Store confirm path expects `entitlement_active` response.
|
|
|
|
## Quote Response Requirements
|
|
|
|
1. `quote_id`
|
|
2. `wallet` (ownership wallet)
|
|
3. `payer_wallet` (optional)
|
|
4. `offer_id`
|
|
5. `currency`
|
|
6. `amount` or `amount_atomic + decimals`
|
|
7. `total_amount` or `total_amount_atomic + decimals`
|
|
8. `membership_activation_included`
|
|
9. `line_items` with transparent breakdown (license + optional membership)
|
|
10. `policy_hash`
|
|
11. `expires_at`
|
|
12. `tx` execution object or equivalent fields
|
|
13. `org_root_id` (when workspace-bound)
|
|
14. `availability_state` and `access_class` snapshot
|
|
|
|
## Confirm Response Requirements
|
|
|
|
1. `status = entitlement_active`
|
|
2. `entitlement_id`
|
|
3. `offer_id`
|
|
4. `wallet` (ownership wallet)
|
|
5. `payer_wallet` (optional)
|
|
6. `tx_hash`
|
|
7. `policy_hash`
|
|
8. `activated_at`
|
|
9. `org_root_id` and `principal_id` (when provided)
|
|
10. `availability_state` snapshot
|
|
|
|
## Persistence Requirements
|
|
|
|
1. Quote record with policy hash and expiry.
|
|
2. Confirm record linked to tx hash and entitlement id.
|
|
3. Entitlement lifecycle state with immutable issued event evidence.
|
|
|
|
## Security Requirements
|
|
|
|
1. Membership gate check on quote and confirm paths.
|
|
2. Quote TTL enforcement.
|
|
3. Tx chain, amount, and destination validation.
|
|
4. Idempotent confirm handling for repeated tx hash submissions.
|
|
5. Ownership wallet proof validation when payer wallet differs.
|
|
6. Bundled membership component must be explicit in quote line items when included.
|
|
7. Continuity policy enforcement: growth actions blocked when `availability_state=continuity`.
|
|
|
|
## Done Criteria
|
|
|
|
1. Store can request quotes for active members only.
|
|
2. Confirm endpoint issues active entitlements deterministically.
|
|
3. Entitlement listing endpoint returns current state records.
|
|
4. API matches `docs/api/marketplace.openapi.yaml`.
|