@mpgd/game-services 0.21.1 → 0.23.0

package/dist/commerce-evidence-registry.js

@@ -0,0 +1,773 @@
+import { commerceProtocolVersion, } from '@mpgd/platform/commerce';
+import { assertCommerceStoreId, } from './types.js';
+const defaultPurchaseCapabilities = Object.freeze({
+    consumable: true,
+    durable: true,
+    subscription: false,
+});
+/**
+ * The v1 request mapping (RFC "Open store ids"): a request without `store`
+ * names its store through its deployment target. `android` is `google-play`,
+ * `ios` is `app-store`, `ait` is `apps-in-toss`, `reddit` is `devvit`, and
+ * every other target is its own store id (`microsoft-store`, `verse8`,
+ * `oneplay`, or a project store that reuses its target name).
+ */
+export function resolveLegacyCommerceStoreId(target) {
+    switch (target) {
+        case 'android':
+            return 'google-play';
+        case 'ios':
+            return 'app-store';
+        case 'ait':
+            return 'apps-in-toss';
+        case 'reddit':
+            return 'devvit';
+        default:
+            return target;
+    }
+}
+/** The store a verify request names: its `store`, or the v1 mapping of its `target`. */
+export function resolveCommerceStoreId(request) {
+    return request.store ?? resolveLegacyCommerceStoreId(request.target);
+}
+/**
+ * Builds the registry. Construction fails when two entries claim one schema,
+ * when a `finish: 'server'` entry has no finalizer, when two entries of one
+ * store disagree on `finish`, or when more than one entry of a store accepts
+ * a missing envelope.
+ */
+export function createCommerceEvidenceRegistry(entries, options = {}) {
+    const bySchema = new Map();
+    const byStore = new Map();
+    const missingEvidenceByStore = new Map();
+    const frozenEntries = [];
+    for (const entry of entries) {
+        assertRegistryEntry(entry);
+        if (bySchema.has(entry.schema)) {
+            throw new TypeError(`Commerce evidence schema ${entry.schema} is claimed by two registry entries.`);
+        }
+        const siblings = byStore.get(entry.store) ?? [];
+        const sibling = siblings[0];
+        if (sibling !== undefined && sibling.finish !== entry.finish) {
+            throw new TypeError(`Commerce store ${entry.store} declares finish ${sibling.finish} for ${sibling.schema} `
+                + `and ${entry.finish} for ${entry.schema}; one store has one finish owner.`);
+        }
+        if (sibling !== undefined && !samePurchaseCapabilities(sibling.purchase, entry.purchase)) {
+            // What a store sells is one profile; two entries of one store must
+            // declare it identically (or both leave the default), never be merged.
+            throw new TypeError(`Commerce store ${entry.store} declares different purchase kinds for ${sibling.schema} `
+                + `and ${entry.schema}; every entry of a store declares the same purchase profile.`);
+        }
+        if (entry.acceptsMissingEvidence === true) {
+            if (missingEvidenceByStore.has(entry.store)) {
+                throw new TypeError(`Commerce store ${entry.store} has two entries that accept a missing evidence envelope.`);
+            }
+            missingEvidenceByStore.set(entry.store, entry);
+        }
+        const frozen = Object.freeze({ ...entry });
+        bySchema.set(entry.schema, frozen);
+        byStore.set(entry.store, [...siblings, frozen]);
+        frozenEntries.push(frozen);
+    }
+    const fallback = options.unregistered;
+    const fallbackStores = new Map();
+    for (const declared of fallback?.stores ?? []) {
+        assertCommerceStoreId(declared.store, 'unregistered.stores[].store');
+        if (byStore.has(declared.store)) {
+            throw new TypeError(`Commerce store ${declared.store} has registry entries and is also declared for the `
+                + 'unregistered fallback; one or the other serves it.');
+        }
+        if (fallbackStores.has(declared.store)) {
+            throw new TypeError(`Commerce store ${declared.store} is declared twice for the fallback.`);
+        }
+        if (declared.finish === 'server' && fallback?.finalizer === undefined) {
+            throw new TypeError(`Commerce store ${declared.store} is declared for the fallback with finish: server and `
+                + 'needs unregistered.finalizer; without one its grants would never be acknowledged.');
+        }
+        fallbackStores.set(declared.store, declared);
+    }
+    const unclaimedByStore = new Map();
+    for (const entry of frozenEntries) {
+        if (entry.acceptsUnclaimedSchemas === true) {
+            if (unclaimedByStore.has(entry.store)) {
+                throw new TypeError(`Commerce store ${entry.store} has two entries that accept unclaimed schemas.`);
+            }
+            unclaimedByStore.set(entry.store, entry);
+        }
+    }
+    const servesUndeclaredStores = fallback !== undefined
+        && (fallback.servesUndeclaredStores ?? fallback.stores === undefined);
+    const stores = new Set([...byStore.keys(), ...fallbackStores.keys()]);
+    const allowedTargets = (store) => {
+        const storeEntries = byStore.get(store);
+        if (storeEntries !== undefined) {
+            if (storeEntries.some((entry) => entry.targets === undefined)) {
+                return undefined;
+            }
+            return new Set(storeEntries.flatMap((entry) => entry.targets ?? []));
+        }
+        const declared = fallbackStores.get(store);
+        return declared?.targets === undefined ? undefined : new Set(declared.targets);
+    };
+    const resolveStore = (request) => resolveCommerceStoreId(request);
+    const targetAllowed = (allowed, target) => allowed === undefined || allowed.includes(target);
+    const routeToEntry = (store, target, entry) => {
+        if (entry.store !== store) {
+            return { status: 'rejected', store, reason: 'EVIDENCE_SCHEMA_STORE_MISMATCH' };
+        }
+        if (!targetAllowed(entry.targets, target)) {
+            return { status: 'rejected', store, reason: 'EVIDENCE_SCHEMA_TARGET_MISMATCH' };
+        }
+        return { status: 'routed', store, entry };
+    };
+    const route = (request) => {
+        const store = resolveStore(request);
+        const schema = request.evidence?.schema;
+        const claimed = schema === undefined ? undefined : bySchema.get(schema);
+        if (claimed !== undefined) {
+            return routeToEntry(store, request.target, claimed);
+        }
+        if (byStore.has(store)) {
+            // A store with entries is never served by the fallback: an unclaimed
+            // schema or a missing envelope reaches only the entry that opted in.
+            const owner = schema === undefined
+                ? missingEvidenceByStore.get(store)
+                : unclaimedByStore.get(store);
+            return owner === undefined
+                ? { status: 'rejected', store, reason: 'EVIDENCE_SCHEMA_UNSUPPORTED' }
+                : routeToEntry(store, request.target, owner);
+        }
+        const declared = fallbackStores.get(store);
+        if (declared !== undefined) {
+            return targetAllowed(declared.targets, request.target)
+                ? { status: 'unregistered', store }
+                : { status: 'rejected', store, reason: 'EVIDENCE_SCHEMA_TARGET_MISMATCH' };
+        }
+        if (!servesUndeclaredStores) {
+            return { status: 'rejected', store, reason: 'EVIDENCE_SCHEMA_UNSUPPORTED' };
+        }
+        if (dodgesServedStore(request)) {
+            return { status: 'rejected', store, reason: 'EVIDENCE_SCHEMA_STORE_MISMATCH' };
+        }
+        return { status: 'unregistered', store };
+    };
+    /**
+     * An undeclared `store` label on a target whose v1 store is served by an
+     * entry or a declared fallback store (`{ target: 'android', store: 'x' }`)
+     * would route the target's purchase around that entry; it is refused.
+     */
+    const dodgesServedStore = (request) => {
+        const legacy = resolveLegacyCommerceStoreId(request.target);
+        return request.store !== undefined && request.store !== legacy && stores.has(legacy);
+    };
+    /**
+     * The entry that owns a grant being finalized: the schema and store the
+     * grant's ledger payload recorded come first (a retry may carry another
+     * envelope), then the request's schema, then the single finalizing entry
+     * of the grant's store (a grant written before the payload carried
+     * `evidenceSchema`).
+     */
+    const routeFinalization = (input) => {
+        const payloadStore = input.evidencePayload?.store;
+        const store = typeof payloadStore === 'string' && payloadStore.length > 0
+            ? payloadStore
+            : resolveStore(input.request);
+        const payloadSchema = input.evidencePayload?.evidenceSchema;
+        const schema = typeof payloadSchema === 'string' && payloadSchema.length > 0
+            ? payloadSchema
+            : input.request.evidence?.schema;
+        if (schema !== undefined) {
+            const entry = bySchema.get(schema);
+            if (entry !== undefined) {
+                return entry.store === store ? { kind: 'entry', entry } : { kind: 'mismatch', entry };
+            }
+            const unclaimed = unclaimedByStore.get(store);
+            if (unclaimed !== undefined) {
+                return { kind: 'entry', entry: unclaimed };
+            }
+        }
+        const finalizing = (byStore.get(store) ?? []).filter((entry) => entry.finalizer !== undefined);
+        const single = finalizing[0];
+        if (finalizing.length === 1 && single !== undefined) {
+            return { kind: 'entry', entry: single };
+        }
+        if (!byStore.has(store) && (fallbackStores.has(store) || servesUndeclaredStores)) {
+            return { kind: 'fallback' };
+        }
+        return { kind: 'none' };
+    };
+    const finalizer = {
+        supportsPurchaseGrant(input) {
+            const owner = routeFinalization(input);
+            switch (owner.kind) {
+                case 'entry':
+                    return owner.entry.finalizer !== undefined
+                        && (owner.entry.finalizer.supportsPurchaseGrant?.(input) ?? true);
+                case 'fallback':
+                    return fallback?.finalizer !== undefined
+                        && (fallback.finalizer.supportsPurchaseGrant?.(input) ?? true);
+                case 'mismatch':
+                    // The owning entry has a finalizer that must not run for another
+                    // store's grant: the grant stays pending rather than reported done.
+                    return owner.entry.finalizer !== undefined;
+                case 'none':
+                    return false;
+            }
+        },
+        async finalizePurchaseGrant(input) {
+            const owner = routeFinalization(input);
+            const selected = owner.kind === 'entry'
+                ? owner.entry.finalizer
+                : owner.kind === 'fallback'
+                    ? fallback?.finalizer
+                    : undefined;
+            if (selected === undefined) {
+                return {
+                    status: 'pending',
+                    alreadyCompleted: false,
+                    reason: owner.kind === 'mismatch'
+                        ? 'PURCHASE_FINALIZER_STORE_MISMATCH'
+                        : 'PURCHASE_FINALIZER_UNREGISTERED',
+                };
+            }
+            return selected.finalizePurchaseGrant(input);
+        },
+    };
+    const purchaseProfileOf = (declared) => ({ ...(declared ?? defaultPurchaseCapabilities) });
+    const describeStore = (store, storeEntries) => {
+        const first = storeEntries[0];
+        if (first === undefined) {
+            throw new Error(`Commerce store ${store} has no registry entries.`);
+        }
+        return {
+            store,
+            schemas: storeEntries.map((entry) => entry.schema),
+            finish: first.finish,
+            purchase: purchaseProfileOf(first.purchase),
+        };
+    };
+    const getCapabilities = () => {
+        const published = [];
+        for (const [store, storeEntries] of byStore) {
+            published.push(describeStore(store, storeEntries));
+        }
+        for (const declared of fallbackStores.values()) {
+            published.push({
+                store: declared.store,
+                schemas: [],
+                finish: declared.finish,
+                purchase: purchaseProfileOf(declared.purchase),
+            });
+        }
+        return { commerceProtocolVersion, stores: published };
+    };
+    const serves = (request) => {
+        const store = resolveStore(request);
+        if (stores.has(store)) {
+            return true;
+        }
+        return servesUndeclaredStores && !dodgesServedStore(request);
+    };
+    const registry = {
+        entries: Object.freeze(frozenEntries),
+        stores,
+        serves,
+        servesUndeclaredStores,
+        allowedTargets,
+        resolveStore,
+        route,
+        async verifyPurchase(input) {
+            const routed = route(input.request);
+            if (routed.status === 'rejected') {
+                return { status: 'rejected', reason: routed.reason };
+            }
+            if (routed.status === 'unregistered') {
+                if (fallback === undefined) {
+                    return { status: 'rejected', reason: 'EVIDENCE_SCHEMA_UNSUPPORTED' };
+                }
+                return fallback.verifier.verifyPurchase(input);
+            }
+            return routed.entry.verifier.verifyPurchase(input);
+        },
+        finalizer,
+        getCapabilities,
+    };
+    return Object.freeze(registry);
+}
+function samePurchaseCapabilities(left, right) {
+    const a = left ?? defaultPurchaseCapabilities;
+    const b = right ?? defaultPurchaseCapabilities;
+    return a.consumable === b.consumable
+        && a.durable === b.durable
+        && a.subscription === b.subscription;
+}
+function assertRegistryEntry(entry) {
+    if (typeof entry.schema !== 'string'
+        || entry.schema.trim() === ''
+        || entry.schema.length > 512
+        || entry.schema.trim() !== entry.schema) {
+        throw new TypeError('A commerce evidence registry entry needs a bounded schema identifier.');
+    }
+    try {
+        assertCommerceStoreId(entry.store, 'store');
+    }
+    catch (error) {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof entry.verifier?.verifyPurchase !== 'function') {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema} needs a verifier with verifyPurchase.`);
+    }
+    if (entry.finish !== 'client'
+        && entry.finish !== 'server'
+        && entry.finish !== 'host'
+        && entry.finish !== 'none') {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema} declares an unknown finish owner.`);
+    }
+    if (entry.finalizer !== undefined && typeof entry.finalizer.finalizePurchaseGrant !== 'function') {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema} has a finalizer without finalizePurchaseGrant.`);
+    }
+    if (entry.finish === 'server' && entry.finalizer === undefined) {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema} (store ${entry.store}) declares `
+            + 'finish: server and needs a finalizer; a server-finish store without one would leave '
+            + 'every grant unacknowledged.');
+    }
+    if (entry.creditScope !== undefined
+        && entry.creditScope !== 'title'
+        && entry.creditScope !== 'cross-title') {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema} declares an unknown credit scope.`);
+    }
+    if (entry.acceptsMissingEvidence !== undefined && typeof entry.acceptsMissingEvidence !== 'boolean') {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema}: acceptsMissingEvidence must be a boolean.`);
+    }
+    if (entry.acceptsUnclaimedSchemas !== undefined && typeof entry.acceptsUnclaimedSchemas !== 'boolean') {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema}: acceptsUnclaimedSchemas must be a boolean.`);
+    }
+    if (entry.targets !== undefined
+        && (!Array.isArray(entry.targets) || entry.targets.length === 0
+            || entry.targets.some((target) => typeof target !== 'string' || target.length === 0))) {
+        throw new TypeError(`Commerce evidence registry entry ${entry.schema}: targets must list ledger target names.`);
+    }
+    if (entry.purchase !== undefined) {
+        const { consumable, durable, subscription } = entry.purchase;
+        if (typeof consumable !== 'boolean'
+            || typeof durable !== 'boolean'
+            || typeof subscription !== 'boolean') {
+            throw new TypeError(`Commerce evidence registry entry ${entry.schema}: purchase flags must be booleans.`);
+        }
+    }
+}
+// Reference entries. Each wraps a verifier (and finalizer) the kit already
+// ships with the RFC "Capabilities" profile row of its store.
+/** The ledger target each reference store's verify requests name (RFC "Open store ids"). */
+export const referenceCommerceLedgerTargets = Object.freeze({
+    'google-play': Object.freeze(['android']),
+    'app-store': Object.freeze(['ios']),
+    'microsoft-store': Object.freeze(['microsoft-store']),
+    'apps-in-toss': Object.freeze(['ait']),
+    devvit: Object.freeze(['reddit']),
+    verse8: Object.freeze(['verse8']),
+});
+/** The RFC profile purchase flags of the reference stores. */
+export const referenceCommercePurchaseCapabilities = Object.freeze({
+    'google-play': Object.freeze({ consumable: true, durable: true, subscription: false }),
+    'app-store': Object.freeze({ consumable: true, durable: true, subscription: false }),
+    'microsoft-store': Object.freeze({ consumable: true, durable: false, subscription: false }),
+    'apps-in-toss': Object.freeze({ consumable: true, durable: true, subscription: false }),
+    devvit: Object.freeze({ consumable: true, durable: true, subscription: false }),
+    verse8: Object.freeze({ consumable: true, durable: true, subscription: false }),
+});
+export const googlePlayCommerceStoreId = 'google-play';
+export const appStoreCommerceStoreId = 'app-store';
+export const microsoftStoreCommerceStoreId = 'microsoft-store';
+export const appsInTossCommerceStoreId = 'apps-in-toss';
+export const devvitCommerceStoreId = 'devvit';
+export const verse8CommerceStoreId = 'verse8';
+export const googlePlayCommerceEvidenceSchema = 'google-play.product-purchase.v2';
+export const appStoreCommerceEvidenceSchema = 'app-store.signed-transaction.v1';
+export const microsoftStoreCommerceEvidenceSchema = 'mpgd.microsoft-store.digital-goods.v1';
+export const appsInTossCommerceEvidenceSchema = 'apps-in-toss.iap.callback.v1';
+export const devvitPaymentOrderEvidenceSchema = 'devvit.payment-order.v1';
+export const devvitOrderEvidenceSchema = 'devvit.order.v1';
+export const verse8Agent8EventEvidenceSchema = 'verse8.agent8-event.v1';
+/**
+ * `google-play.product-purchase.v2`: the Play boundary verifies the purchase
+ * token and, after the ledger grant, acknowledges or consumes it
+ * (`finish: 'server'`). Pass `createGooglePlayProductPurchaseBoundary(...)`,
+ * or a verifier binding plus a separate finalizer.
+ */
+export function createGooglePlayCommerceEvidenceEntry(input) {
+    const finish = input.finish ?? 'server';
+    return {
+        schema: googlePlayCommerceEvidenceSchema,
+        store: googlePlayCommerceStoreId,
+        verifier: input.verifier,
+        ...(finish === 'server' ? { finalizer: input.finalizer } : {}),
+        finish,
+        creditScope: 'title',
+        ...optionalRouting(input),
+        targets: input.targets ?? referenceCommerceLedgerTargets['google-play'],
+        purchase: referenceCommercePurchaseCapabilities['google-play'],
+    };
+}
+function optionalRouting(input) {
+    return {
+        ...(input.acceptsMissingEvidence === undefined
+            ? {}
+            : { acceptsMissingEvidence: input.acceptsMissingEvidence }),
+        ...(input.acceptsUnclaimedSchemas === undefined
+            ? {}
+            : { acceptsUnclaimedSchemas: input.acceptsUnclaimedSchemas }),
+    };
+}
+/**
+ * `app-store.signed-transaction.v1`: the App Store verifier checks the
+ * StoreKit JWS offline and decides on the Server API status; a request
+ * without the envelope keeps the `Get Transaction Info` lookup, so the entry
+ * accepts a missing envelope. The client finishes after the ledger grant.
+ */
+export function createAppStoreCommerceEvidenceEntry(input) {
+    return {
+        schema: appStoreCommerceEvidenceSchema,
+        store: appStoreCommerceStoreId,
+        verifier: input.verifier,
+        finish: 'client',
+        creditScope: 'title',
+        ...optionalRouting(input),
+        acceptsMissingEvidence: input.acceptsMissingEvidence ?? true,
+        targets: input.targets ?? referenceCommerceLedgerTargets['app-store'],
+        purchase: referenceCommercePurchaseCapabilities['app-store'],
+    };
+}
+/**
+ * `mpgd.microsoft-store.digital-goods.v1`: the Collections verifier before
+ * the grant and the consume finalizer after it (`finish: 'server'`), always
+ * configured together.
+ */
+export function createMicrosoftStoreCommerceEvidenceEntry(input) {
+    return {
+        schema: microsoftStoreCommerceEvidenceSchema,
+        store: microsoftStoreCommerceStoreId,
+        verifier: input.verifier,
+        finalizer: input.finalizer,
+        finish: 'server',
+        ...optionalRouting(input),
+        targets: input.targets ?? referenceCommerceLedgerTargets['microsoft-store'],
+        purchase: referenceCommercePurchaseCapabilities['microsoft-store'],
+    };
+}
+/**
+ * `apps-in-toss.iap.callback.v1`: the production evidence verifier binds the
+ * order through the partner API; the host finishes (`completeProductGrant`)
+ * after the ledger grant.
+ */
+export function createAppsInTossCommerceEvidenceEntry(input) {
+    return {
+        schema: appsInTossCommerceEvidenceSchema,
+        store: appsInTossCommerceStoreId,
+        verifier: input.verifier,
+        finish: 'host',
+        ...optionalRouting(input),
+        targets: input.targets ?? referenceCommerceLedgerTargets['apps-in-toss'],
+        purchase: referenceCommercePurchaseCapabilities['apps-in-toss'],
+    };
+}
+/**
+ * The `devvit.payment-order.v1` verifier: the envelope
+ * `normalizeDevvitFulfillmentOrder` produced names the order, and the grant
+ * is decided by the deployment's payments authority (`PAID` or `DELIVERED`
+ * for the requesting player and SKU). Replay identity is the order id, so a
+ * second fulfillment of one order meets the first grant.
+ */
+export function createDevvitPaymentOrderEvidenceVerifier(input) {
+    const now = input.now ?? (() => new Date().toISOString());
+    return {
+        async verifyPurchase({ request, platformProductId, signal }) {
+            const envelope = request.evidence;
+            if (envelope?.schema !== devvitPaymentOrderEvidenceSchema) {
+                return { status: 'rejected', reason: 'EVIDENCE_SCHEMA_UNSUPPORTED' };
+            }
+            const orderId = readBoundedIdentifier(envelope.payload.orderId);
+            if (orderId === undefined || orderId !== request.platformTransactionId) {
+                return { status: 'rejected', reason: 'DEVVIT_ORDER_ID_MISMATCH' };
+            }
+            if (envelope.payload.status !== 'PAID') {
+                return { status: 'rejected', reason: 'DEVVIT_ORDER_NOT_PAID' };
+            }
+            let result;
+            try {
+                result = await input.authority.getOrder({
+                    orderId,
+                    playerId: request.playerId,
+                    platformSku: platformProductId,
+                    signal,
+                });
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    throw error;
+                }
+                return { status: 'pending', reason: 'DEVVIT_ORDER_AUTHORITY_UNAVAILABLE' };
+            }
+            if (result.decision === 'pending') {
+                return { status: 'pending', ...(result.reason === undefined ? {} : { reason: result.reason }) };
+            }
+            if (result.decision === 'rejected') {
+                return { status: 'rejected', reason: result.reason };
+            }
+            const order = result.order;
+            if (order.orderId !== orderId) {
+                return { status: 'rejected', reason: 'DEVVIT_ORDER_ID_MISMATCH' };
+            }
+            if (order.playerId !== request.playerId) {
+                return { status: 'rejected', reason: 'DEVVIT_ORDER_PLAYER_MISMATCH' };
+            }
+            if (order.sku !== platformProductId) {
+                return { status: 'rejected', reason: 'DEVVIT_ORDER_SKU_MISMATCH' };
+            }
+            if (order.status === 'REVERTED') {
+                return { status: 'rejected', reason: 'DEVVIT_ORDER_REVERTED' };
+            }
+            if (order.status !== 'PAID' && order.status !== 'DELIVERED') {
+                return { status: 'pending', reason: 'DEVVIT_ORDER_NOT_PAID' };
+            }
+            return {
+                status: 'verified',
+                verificationId: `devvit:payment-order:${orderId}`,
+                verifiedAt: now(),
+                platformEvidenceId: orderId,
+                payload: {
+                    devvitOrderId: orderId,
+                    devvitOrderStatus: order.status,
+                    ...(order.occurredAt === undefined ? {} : { devvitOrderOccurredAt: order.occurredAt }),
+                },
+            };
+        },
+    };
+}
+/** `devvit.payment-order.v1`: the fulfillment handler's own record, bound through the payments authority. */
+export function createDevvitPaymentOrderCommerceEvidenceEntry(input) {
+    return {
+        schema: devvitPaymentOrderEvidenceSchema,
+        store: devvitCommerceStoreId,
+        verifier: createDevvitPaymentOrderEvidenceVerifier(input),
+        finish: 'none',
+        targets: input.targets ?? referenceCommerceLedgerTargets.devvit,
+        purchase: referenceCommercePurchaseCapabilities.devvit,
+    };
+}
+/**
+ * A server-push lookup verifier (RFC "Evidence registry"): it never grants
+ * from the client envelope. It answers `settled` with the ledger entry the
+ * host's fulfillment path already wrote for the same store and transaction
+ * id, when that entry belongs to the requesting player and product and is
+ * not reversed; `pending` while no such entry exists; and `rejected` when the
+ * envelope names another transaction or product than the request, or the
+ * entry belongs to someone else.
+ */
+export function createCommerceLedgerLookupVerifier(input) {
+    return {
+        async verifyPurchase({ request, platformProductId }) {
+            const envelope = request.evidence;
+            if (envelope?.schema !== input.schema) {
+                return { status: 'rejected', reason: 'EVIDENCE_SCHEMA_UNSUPPORTED' };
+            }
+            const transactionId = input.readTransactionId(envelope.payload);
+            if (transactionId === undefined) {
+                return { status: 'rejected', reason: 'EVIDENCE_PAYLOAD_INVALID' };
+            }
+            if (transactionId !== request.platformTransactionId) {
+                return { status: 'rejected', reason: 'PLATFORM_TRANSACTION_ID_MISMATCH' };
+            }
+            const storeSku = input.readStoreSku?.(envelope.payload);
+            if (storeSku !== undefined && storeSku !== platformProductId) {
+                return { status: 'rejected', reason: 'PLATFORM_PRODUCT_MISMATCH' };
+            }
+            const grant = await findPurchaseGrantByPlatformEvidence(input.ledger, {
+                target: input.ledgerTarget ?? request.target,
+                platformEvidenceId: transactionId,
+            });
+            if (grant === undefined) {
+                return { status: 'pending', reason: 'LEDGER_GRANT_PENDING' };
+            }
+            if (grant.playerId !== request.playerId) {
+                return { status: 'rejected', reason: 'LEDGER_GRANT_PLAYER_MISMATCH' };
+            }
+            if (grant.grantId !== request.productId) {
+                return { status: 'rejected', reason: 'LEDGER_GRANT_PRODUCT_MISMATCH' };
+            }
+            const grantStore = grant.payload.store;
+            if (typeof grantStore === 'string' && grantStore.length > 0 && grantStore !== input.store) {
+                return { status: 'rejected', reason: 'EVIDENCE_SCHEMA_STORE_MISMATCH' };
+            }
+            if (input.ledger.findEntitlementRevocations !== undefined) {
+                const revocations = await input.ledger.findEntitlementRevocations({
+                    ledgerEntryIds: [grant.ledgerEntryId],
+                });
+                if (revocations.length > 0) {
+                    return { status: 'rejected', reason: 'LEDGER_GRANT_REVERSED' };
+                }
+            }
+            return {
+                status: 'settled',
+                ledgerEntryId: grant.ledgerEntryId,
+                ...(input.ledgerTarget === undefined ? {} : { ledgerTarget: input.ledgerTarget }),
+            };
+        },
+    };
+}
+/** The purchase grant written under a ledger target and store transaction id, through the store's index or a list scan. */
+export async function findPurchaseGrantByPlatformEvidence(ledger, identity) {
+    if (ledger.findEntitlementTransactionByPlatformEvidence !== undefined) {
+        return ledger.findEntitlementTransactionByPlatformEvidence({
+            source: 'purchase',
+            target: identity.target,
+            platformEvidenceId: identity.platformEvidenceId,
+        });
+    }
+    const transactions = await ledger.listEntitlementTransactions();
+    return transactions.find((transaction) => transaction.source === 'purchase'
+        && transaction.payload.target === identity.target
+        && transaction.payload.platformTransactionId === identity.platformEvidenceId);
+}
+/**
+ * `devvit.order.v1`: the client's order envelope (a checkout result or the
+ * paid-order list) looked up against the ledger the fulfillment handler
+ * wrote under target `reddit` (`createPlatformOrderLedgerGrant`).
+ */
+export function createDevvitOrderLookupCommerceEvidenceEntry(input) {
+    return {
+        schema: devvitOrderEvidenceSchema,
+        store: devvitCommerceStoreId,
+        verifier: createCommerceLedgerLookupVerifier({
+            schema: devvitOrderEvidenceSchema,
+            store: devvitCommerceStoreId,
+            ledger: input.ledger,
+            readTransactionId: (payload) => readBoundedIdentifier(payload.orderId),
+            readStoreSku: (payload) => readBoundedIdentifier(payload.sku),
+            ...(input.ledgerTarget === undefined ? {} : { ledgerTarget: input.ledgerTarget }),
+        }),
+        finish: 'none',
+        targets: input.targets ?? referenceCommerceLedgerTargets.devvit,
+        purchase: referenceCommercePurchaseCapabilities.devvit,
+    };
+}
+/**
+ * `verse8.agent8-event.v1`: the client's Agent8 purchase envelope looked up
+ * against the ledger the `$onItemPurchased` event wrote under target `verse8`
+ * (`createServerPushLedgerGrant`; the Agent8 commerce service writes it when
+ * given a ledger).
+ */
+export function createVerse8Agent8EventLookupCommerceEvidenceEntry(input) {
+    return {
+        schema: verse8Agent8EventEvidenceSchema,
+        store: verse8CommerceStoreId,
+        verifier: createCommerceLedgerLookupVerifier({
+            schema: verse8Agent8EventEvidenceSchema,
+            store: verse8CommerceStoreId,
+            ledger: input.ledger,
+            readTransactionId: (payload) => readBoundedIdentifier(payload.purchaseId),
+            readStoreSku: (payload) => readBoundedIdentifier(payload.productId),
+            ...(input.ledgerTarget === undefined ? {} : { ledgerTarget: input.ledgerTarget }),
+        }),
+        finish: 'none',
+        targets: input.targets ?? referenceCommerceLedgerTargets.verse8,
+        purchase: referenceCommercePurchaseCapabilities.verse8,
+    };
+}
+/**
+ * The ledger grant a host's fulfillment path writes for a server-push
+ * purchase, in the shape the lookup verifiers read: `payload.target`,
+ * `payload.store`, and `payload.platformTransactionId` identify it, and the
+ * platform-evidence unique index keeps a second write of the same transaction
+ * out. Write it with `GameServicesStore.recordEntitlementGrant`.
+ */
+export function createServerPushLedgerGrant(input) {
+    assertCommerceStoreId(input.store, 'store');
+    const transactionId = readBoundedIdentifier(input.transactionId);
+    if (transactionId === undefined) {
+        throw new TypeError('A server-push ledger grant needs a bounded transaction id.');
+    }
+    const evidenceVerificationId = input.evidenceVerificationId
+        ?? `${input.store}:${input.evidence.schema}:${transactionId}`;
+    const quantity = input.quantity ?? 1;
+    if (!Number.isSafeInteger(quantity) || quantity <= 0) {
+        throw new TypeError('A server-push ledger grant quantity must be a positive integer.');
+    }
+    const grant = input.product.grant;
+    const scaledGrant = quantity === 1 || grant.type === 'entitlement'
+        ? grant
+        : { ...grant, amount: grant.amount * quantity };
+    return {
+        playerId: input.playerId,
+        grantId: input.product.id,
+        source: 'purchase',
+        idempotencyKey: input.idempotencyKey
+            ?? `store:${encodeURIComponent(input.store)}:${encodeURIComponent(transactionId)}`,
+        grantedAt: input.grantedAt,
+        grant: scaledGrant,
+        evidenceVerificationId,
+        payload: {
+            target: input.target,
+            store: input.store,
+            ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
+            productId: input.product.id,
+            productType: input.product.type,
+            platformProductId: input.platformProductId,
+            platformTransactionId: transactionId,
+            quantity,
+            purchasedAt: input.purchasedAt,
+            evidenceSchema: input.evidence.schema,
+            evidenceVerificationId,
+            evidenceVerifiedAt: input.grantedAt,
+        },
+    };
+}
+/**
+ * Compares a provider's capability block with the backend's published
+ * capabilities (RFC "Provider capabilities endpoint"): a store the backend
+ * does not accept, a finish owner that disagrees, or another protocol major
+ * version sets the provider's availability to `configuration-required`
+ * before any purchase UI opens. The reconciler applies it at start.
+ */
+export function compareCommerceServiceCapabilities(input) {
+    const { store } = input;
+    if (majorVersionOf(input.service.commerceProtocolVersion) !== majorVersionOf(commerceProtocolVersion)) {
+        return {
+            status: 'configuration-required',
+            store,
+            reason: 'PROTOCOL_VERSION_MISMATCH',
+            message: `The backend speaks commerce protocol ${input.service.commerceProtocolVersion}; this client speaks ${commerceProtocolVersion}.`,
+        };
+    }
+    const accepted = input.service.stores.find((candidate) => candidate.store === store);
+    if (accepted === undefined) {
+        return {
+            status: 'configuration-required',
+            store,
+            reason: 'STORE_NOT_ACCEPTED',
+            message: `The backend accepts no evidence for store ${store}.`,
+        };
+    }
+    if (accepted.finish !== input.provider.lifecycle.finish) {
+        return {
+            status: 'configuration-required',
+            store,
+            reason: 'FINISH_OWNER_MISMATCH',
+            message: `The backend expects ${accepted.finish} to finish ${store} purchases; the provider declares ${input.provider.lifecycle.finish}.`,
+        };
+    }
+    return { status: 'aligned', store };
+}
+function majorVersionOf(version) {
+    return version.split('.')[0] ?? version;
+}
+function readBoundedIdentifier(value) {
+    if (typeof value !== 'string'
+        || value.length === 0
+        || value.length > 256
+        || value.trim() !== value
+        || /[\p{Cc}\p{Cf}]/u.test(value)) {
+        return undefined;
+    }
+    return value;
+}