Product Contract — Concept Registry

Reading guide

Design reference, not a beginner tutorial. This registry defines entities such as Seller, License, Entitlement, and PaymentEvent, including current records and proposed models.

For an introduction start with Concepts; use this document when checking identifiers and invariant responsibilities.

Status: PROPOSAL, grounded in the current implementation. "Identity" is the real ID/key format found in code; "Owner" is the party accountable for the record's truth; "States" are the values actually written by the code today; "Permission scope" is who can read/write it under current authorization. Concepts that exist only as design (e.g. a first-class Buyer entity) are marked as such rather than invented.

1. Registry

Seller

• Identity: seller table id = seller_{12hex} (auth_impl.rs:460); legacy seed value seller_nougat. Slug: seller.slug → s-{…} on onboarding; public store path /store/{slug}.
• Owner: DevPay (identity) + the seller themselves (profile/payout fields).
• States: no seller-level state machine today — the seller row has no status column. Verification state lives separately (verification.status, e.g. NOT_REGISTERED on creation).
• Permission scope: users.role='seller' + seller_memberships row (role='owner') scoped via seller_scope_db — DB re-check on every request. Seller sees only own products/orders/licenses/subscriptions/ settlements. admin sees all.

Buyer

• Identity: two partial identities, no unified entity. (a) users.id = usr_{12hex} with role='buyer' (signup default, auth_impl.rs:366); (b) orders.buyer_email/licenses.buyer_email — checkout requires only an email string, no account.
• Owner: DevPay for users rows; the email identity is seller-visible data, not a platform credential.
• States: users.status = active | inactive (deactivate). Email-only buyers have no state.
• Permission scope: buyers can call public/checkout endpoints and own /me resources; no buyer dashboard exists. Buyer email is NOT proof of ownership (charter: unverified email must not claim purchases).

Product

• Identity: products.id = prod_{12hex} (verify_impl.rs product_create); unique (seller_id, slug) enforced at create/update.
• Owner: the owning seller; DevPay stores it.
• States: status — active | non-active (checkout refuses PRODUCT_INACTIVE); type ∈ one_time|subscription|free|donation (FE ProductType, fe/types/index.ts:25).
• Permission scope: public read via /public/stores/… (published sellers only); seller write own products; features_json/plans_json/ license_json/entitlements_json are the product's policy payloads — features_json is the sole entitlement namespace source of truth.

License

• Identity: licenses.id = lic_{12hex} (mock path, mk("lic")) or deterministic lic_{ord_id} (Toss finalize, toss_impl.rs:321 — INSERT OR IGNORE makes confirm/webhook retries idempotent). licenses.key has two observed formats: (a) purchase-issued (mock checkout checkout_impl.rs:165, Toss toss_impl.rs:323): NG-{8hex}-{8hex}-{8hex}-{8hex} — 128-bit; (b) seller-issued via POST /licenses (endpoints_impl.rs:554-557, Axum parity): NG-{4hex}-{4hex} — 32-bit only.
• KNOWN_LIMITATION: the 32-bit seller-issued key is brute-force feasible through the public, unauthenticated, un-rate-limitedPOST /licenses/verify — ~4.3 × 10⁹ keyspace is enumerable at API request rates. Recommend migrating seller-issued keys to the 128-bit format and/or rate-limiting verify (currently neither exists).
• Owner: DevPay issues; belongs to a product_id (→ seller) and a buyer_email; optional order_id/subscription_id back-references.
• States: active → suspended (payment failure), revoked (cancel/refund), expired (period end / expires_at passed); verify_status_error maps to REVOKED|SUSPENDED|EXPIRED|INVALID_STATUS (verify_impl.rs). max_devices (default 3) slots enforced via license_bindings atomic insert.
• Permission scope: seller CRUD own licenses (issue/patch/activations); public licenses/verify is lookup-only (no slot writes); PoP activate is key-holder + product-bound.
• Two device models coexist: legacy activations_json (display/records only — NOT authorization input) and license_bindings (jkt PoP slots — authorization).

Entitlement

• Identity: compact ES256 JWS; claims iss (devpay-lic Worker / yp SDK default), lic_id, product_id, features[], jkt_bound, cnf.jkt, iat, exp — TTL 120 s (license-crypto/lib.rs). SDK variant adds optional aud, tenant_id.
• Owner: DevPay (Worker iss=devpay-lic) or the seller's license-server (BYOS, iss configurable). Signed token is stateless; live license status re-queried on every use — revocation beats token validity.
• States: none internally (exp-bound); effective states are derived: valid | expired | revoked-by-license-status.
• Permission scope: transport credential in Authorization: Entitlement <jws>; never grants beyond products.features_json.

Feature

• Identity: a string in products.features_json (e.g. premium_convert = FEATURE_PREMIUM_CONVERT in license-crypto/premium.rs).
• Owner: seller (product definition); DevPay enforces membership.
• States: none (namespace entries, not entities).
• Permission scope: entitlement features[] ⊂ product features; unknown/empty → 403 FORBIDDEN (has_feature, effective_features fail-closed). Only premium_convert is executable on the DevPay-hosted /licenses/execute today — other features → 400 unknown feature.

ProtectedOperation

• Identity: (product_id, feature) pair — the server-side action gated by entitlement+capability. DevPay-hosted: POST /licenses/execute with {feature, input, cap_id}. BYOS: any seller route behind license.server.authorize/issueCapability or requireLicense.
• Owner: DevPay for hosted execute (built-in premium_convert only); seller for BYOS operations.
• States: per-call, no persistent object — success emits UsageRecord.
• Permission scope: entitlement + fresh DPoP proof + unconsumed capability bound to lic_id+product_id+feature+jkt.

ExecutionCapability

• Identity: execution_capabilities.cap_id = cap_{16hex} (new_id("cap")).
• Owner: DevPay (Worker-issued) or seller store (BYOS createCapability).
• States: consumed 0→1 only; expiry via exp (TTL 60 s, CAPABILITY_TTL_SEC); prune by cron prune_expired.
• Permission scope: bound tuple cap_id+lic_id+product_id+feature+jkt; consume is one atomic UPDATE … WHERE consumed=0 — second use → 409 CAPABILITY_CONSUMED + security_events(capability_reuse).

UsageRecord

• Identity: license_usage.id = use_{16hex}; also security_events.id = sec_{16hex} for denials/replays/slot-overflow.
• Owner: DevPay (written by hosted execute/guard).
• States: append-only fact rows (lic_id, feature, at, meta_json incl. cap_id, product_id).
• Permission scope: written server-side best-effort after execute (non-transactional — see trust-model §3 usage limits); no read endpoint today → seller/buyer visibility NOT_IMPLEMENTED.

PaymentEvent

• Identity: payments.id = pay_{12hex}; payments.payment_key = PG paymentKey (toss). Money effects also land in transaction_ledger (led_{12hex}, event_type ∈ payment_captured|payment_refunded| currency_grant|currency_revoke|license_issued|settlement) and outbox (out_{12hex}, topic e.g. order.checkout).
• Owner: DevPay ledger is authority; PG state reconciled via checkout/confirm + webhooks/toss (signature-verified, ref-validated, refetched — never trusts the webhook body).
• States: payments.status = pending (Toss intent, toss_impl.rs:82) | paid (mock checkout / finalized Toss) | captured (feedback payments, endpoints_impl.rs:865) | refunded; orders.status ∈ paid|failed|canceled|refunded|pending|confirm_pending|partially_refunded.
• Permission scope: seller reads own order/payment; public order status via /public/orders/:id. provider ∈ mock|toss — mock blocked under PAYMENT_LIVE_ENABLED=true.

RefundEvent

• Identity: refund_attempts.id = ra_{12hex} (mk_id("ra")).
• Owner: DevPay record; initiated by owning seller (POST /orders/:id/refund); PG executes the actual cancel (/v1/payments/{key}/cancel).
• States: attempted → succeeded | failed | needs_review (timeout/5xx — uncertain, requires resolution; order.refunded_krw sums only succeeded). GET /orders/:id/refund-attempts is the audit view.
• Permission scope: seller-only, ownership-scoped; partial refunds capped at remaining amount_krw; full refund revokes license + fulfillment compensation in the same batch.

Subscription

• Identity: subscriptions.id = sub_{12hex} (mock checkout) or sub_{ord_id} (toss path — toss_impl.rs:320, deterministic alongside lic_{ord_id}); tracks license_id, order_ids_json.
• Owner: DevPay record; seller manages via POST /subscriptions/:id/event {event: renew|fail|expire|cancel}.
• States: trialing (trial plan) | active | past_due | expired | canceled. Transitions: renew→active(+new paid order+ledger); fail→ past_due(+license suspended); expire→expired(+license expired); cancel→canceled(+license revoked). canceled/expired are terminal for renew (409 SUB_ENDED).
• Permission scope: seller events scoped to own products; renew requires non-live payment env (402 NOT_LIVE_PAYMENT under live).

Tenant

• Identity: the seller boundary — seller_id column on projects/products/orders + seller_memberships; in the SDK a tenantId/tenant_id claim concept exists (server.mjsexpectedTenantId, entitlement tenant_id).
• Owner: DevPay (membership/scope enforcement via seller_scope_db).
• States: membership rows (mem_{10hex}, role='owner').
• Permission scope: seller token → Some(seller_id) scope → WHERE clauses; admin → None (unscoped). Worker entitlement has no tenant_id claim — tenancy on the hosted path is lic_id+product_id+jkt binding.

ProtectionSpecification

• Identity: JSON document, version:1 (spec/protection-spec.schema.json); bound downstream by spec_sha256 inside the plan. project.id names the subject.
• Owner: the seller/agent drafting it; approval is a human/process act outside the tool (no signature field — deliberate).
• States: draft → approved → implemented → verified. Drafts may carry literal REQUIRES_APPROVAL markers; --apply-auto on a still-marked spec is refused (exit 2).
• Permission scope: closed invariant registry (13 IDs, all requires_server) — unregistered IDs make the spec invalid; auto_partition:"always" cannot override refusal screens.

ProtectionEvidence

• Identity: evidence record schema_version:1 (evidence/schema/evidence-schema.json) — one per (requirement_id, asset_id); artifacts sha256-pinned; commit_sha + worktree_dirty recorded.
• Owner: independent verification principal (QA/Security lanes) — never the implementing party.
• States: verdicts VERIFIED_WITHIN_SCOPE | FAILED | PARTIALLY_VERIFIED | NOT_VERIFIED | NOT_APPLICABLE per invariant (closed enum, evidence-schema.json:200); leg-level PASS | FAIL | ATTACK_BLOCKED | ATTACK_REPRODUCED | LIMITATION_CONFIRMED | NOT_VERIFIED | NOT_APPLICABLE.
• Permission scope: append-only evidence; validator enforces claim-gates (empty execution ≠ evidence; every asserted invariant needs a verdict; absolute claims rejected by claims-scan).

2. Cross-cutting identity formats (observed)

ord_{12hex} order · pay_{12hex} payment · lic_{12hex}/lic_{ord_id} license · sub_{12hex}/sub_{ord_id} subscription · set_{12hex} settlement (settlement_no = ST-YYYY-NNNN) · ord_{…}+order_no = NG-YYYYMMDD-NNNN (counter-atomic) · led/aud/out/act/gi/idem_{12hex} · cap/use/sec_{16hex} · ra_{12hex} refund attempt · usr_{12hex} user · seller_{12hex} seller · proj_{12hex} project · plr_{12hex} player · ff_{12hex} fulfillment · mem_{10hex} membership · sset_{10hex} settings · ver_{10hex}/ver_{seller_id} verification · lease_{8hex} outbox lease-owner token (not an entity — claim marker, checkout_impl.rs:285).

3. Invariants that must survive any redesign

1. products.features_json is the only entitlement namespace.
2. License status is re-read at every authorization — tokens never override revocation.
3. Every consumption primitive is a single atomic statement (slots, jti, capability, counters, partial-refund cap).
4. Missing row ≠ permission — every lookup failure denies (fail closed).
5. device_id/legacy activations_json is never an authorization input; license_bindings (jkt) is.