@percayso-community/cayso-contracts 0.23.0

package/dist/marketplace-receipt.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The marketplace receipt: what Cayso signs about a marketplace sale or refund,
+ * and the exact bytes the signature is computed over (CAY-0083 §1).
+ *
+ * Store Platform grants a paid entitlement only on a receipt it verifies itself,
+ * for the exact order digest (Store's invariant 8). Piper carries the receipt from
+ * Cayso to Store Platform (Store decision V), so the receipt has to verify with no
+ * call back to Cayso: it is a {@link MarketplaceReceiptStatement} and a signature
+ * over {@link encodeMarketplaceReceiptStatement} of it, made with a key Cayso alone
+ * holds and that signs receipts only.
+ *
+ * ## What is signed
+ *
+ * CAY-0083 §1's list, and nothing else: the movement id, the order digest, the
+ * idempotency key, the sale's kind, each leg as a wallet id and a whole number of
+ * cents, the allocation-policy version and the time the movement was written. The
+ * statement adds three things the list implies. `movementKind` says which of the
+ * ledger's acts the movement is, and so which way its legs run. `buyerWalletId`
+ * names the other end of every leg. `keyId` names the key the signature was made
+ * with, so selecting the key is part of what is signed.
+ *
+ * **A receipt names wallet ids only, never a Percayso identity** (CAY-0006,
+ * CAY-0054). There is no field a subject could be put in.
+ *
+ * ## Four statements, and a type that cannot express a fifth
+ *
+ * A sale is a `marketplace_settlement` when a third party published the release and
+ * a plain `charge` when the house publisher did (CAY-0082 §1, §2). A refund is a
+ * `marketplace_refund` of either (§5), and names the order digest of the sale it
+ * refunds. Each is its own interface, discriminated by `movementKind` and
+ * `saleKind` together:
+ *
+ *   - a third-party statement has a publisher leg and a Community leg;
+ *   - a house-publisher statement has a Community leg and **no publisher leg field
+ *     at all**, so a house-publisher sale that pays a publisher is not a value of
+ *     this type; and
+ *   - there is one publisher leg or none, never a list, because a paid sale has
+ *     exactly one publisher (CAY-0082 §8) and a split among publishers is not
+ *     designed.
+ *
+ * On a sale every leg runs from the buyer's wallet to the leg's wallet. On a refund
+ * every leg runs from the leg's wallet to the buyer's. The Community leg's wallet is
+ * the Treasury, named by its wallet id like any other.
+ *
+ * ## The bytes that are signed
+ *
+ * {@link encodeMarketplaceReceiptStatement} is the one encoding, and the signer and
+ * every verifier call it: two implementations of "the same JSON" are two encodings
+ * that will one day disagree by a space, and a verifier that disagrees with its
+ * signer by a space refuses every receipt. It is the statement's fields in the order
+ * the interfaces declare them, as UTF-8 JSON with no whitespace.
+ *
+ * It is published here, where CAY-0072 keeps the assertion's encoding out, because
+ * the two cases differ in who owns the bytes. Percayso ID mints an assertion and
+ * owns its format; Cayso mints a receipt and owns this one, and writing it once
+ * where both sides import it is what stops the signer and Store Platform drifting.
+ * It pins no cryptographic dependency: it is JSON and a UTF-8 encoder.
+ *
+ * **The key set is closed, and the encoder refuses a statement that is not exactly
+ * one of the four.** A house-publisher statement carrying a `publisherLeg`, a leg
+ * carrying a field beside its wallet and cents, or any key a statement does not
+ * name is refused rather than dropped. Dropping it would leave a verifier holding an
+ * object with a field nobody signed, and a consumer that read it would be reading
+ * whatever the transport added.
+ *
+ * ## The algorithm and the key
+ *
+ * {@link MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM} is ECDSA over P-256 with SHA-256,
+ * written with its JOSE name, `ES256`. The signature is the fixed-length `r || s`
+ * concatenation, 64 bytes, as unpadded base64url, and never DER. That is the
+ * algorithm and encoding Store Platform already verifies its release statements
+ * with (Store `STO-0026`, `STO-0033`), so Store Platform checks a receipt with the
+ * code it already has (CAY-0083 §1).
+ *
+ * A {@link MarketplaceReceiptKeyId} is the RFC 7638 SHA-256 thumbprint of the key's
+ * public half as a P-256 JSON Web Key, unpadded base64url. Derived rather than
+ * minted, so a key id cannot be re-pointed at a different key.
+ *
+ * ## The status read: a receipt or "no movement", never "pending"
+ *
+ * The read exists for one case: the settle call went out and its answer did not
+ * come back (CAY-0083 §2). Piper asks it under the buyer's assertion
+ * (`read-marketplace-receipt`, read-scope in `ASSURANCE_POLICY`), and Store
+ * Platform never does. {@link MarketplaceReceiptReadResponse} has exactly two
+ * answers about the key and one refusal:
+ *
+ *   - **`receipt`** — the signed {@link MarketplaceReceipt} of the movement the key
+ *     landed, the same receipt the lost answer carried;
+ *   - **`no-movement`** — nothing was written under this key for this wallet. It
+ *     means **retry with the same key, never a new one**: the first attempt may
+ *     still be in flight, and the same key lands it exactly once either way; and
+ *   - **`refused`** — the question could not be asked, with one reason from
+ *     {@link MarketplaceReceiptReadRefusal}. It is not a third answer about the
+ *     key, and a caller must never read it as "no movement".
+ *
+ * **There is no `pending`, and no member could carry one.** A movement is written
+ * or it is not (CAY-0023): there is no status column to report, so a read that
+ * said "in progress" would be inventing a state the ledger does not have.
+ *
+ * **The paying wallet is the buyer's own, resolved from the verified subject**
+ * through the holders mapping, as settlement resolves it (CAY-0082 §1), and so
+ * {@link MarketplaceReceiptReadRequest} names no wallet. CAY-0083 keys the read by
+ * the paying wallet and the idempotency key; a request field for the wallet would
+ * be a claim about who the caller is, which Cayso never trusts (CAY-0021), and a
+ * place another holder's wallet id could be written to read their receipt. With no
+ * such field, a read of somebody else's receipt is not a request this type can
+ * express. When the subject has no live binding the read is refused rather than
+ * answered `no-movement`: the wallet cannot be resolved, so whether a movement
+ * exists is not known, and "no movement" would be a guess that invites a retry.
+ *
+ * The answer is one receipt, never a list, so it rests on a key naming at most one
+ * movement for one paying wallet. CAY-0082 §4 holds a sale's key to that across
+ * both sale kinds; a refund carries its own key, never the sale's, and the slice
+ * that stores a refund has to hold it to the same rule beside the sale's.
+ *
+ * **A read writes no row of its own and moves nothing**: no audit row, and nothing
+ * recording which key was asked. The one record it leaves is the one every verified
+ * assertion leaves, its use, which is what refuses a replay (CAY-0030). A holder
+ * reading their own record is not surveilled, as a holder reading their own balance
+ * is not.
+ *
+ * Every unconfigured seam the read meets is a `503` and is not in the refusal
+ * union, among them CAY-0083 §4's empty registry of Store Platform order keys,
+ * which closes all three marketplace operations. The spelling of that one is the
+ * registry's slice's to publish. A malformed key is `invalid_request`.
+ *
+ * ## What is not here
+ *
+ * No key material of any kind, and no key set: which receipt keys Store Platform
+ * trusts is Store Platform's configuration, empty by default, and how Cayso holds,
+ * rotates and revokes its key is Cayso's own, in `apps/api`. No verifier: Store
+ * Platform verifies. And no figure: a leg carries the cents the movement moved, and
+ * the allocation between publisher and Community is Store Platform's canon's.
+ */
+import type { Cents, Millis } from './wallet.js';
+/**
+ * The algorithm every marketplace receipt is signed with: ECDSA P-256 with SHA-256,
+ * `r || s` encoded (JOSE `ES256`), CAY-0083 §1.
+ */
+export declare const MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM: "ES256";
+/**
+ * The type of {@link MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM}. Written as the
+ * literal because the published schema describes literals and not `typeof`, and a
+ * test pins the two together.
+ */
+export type MarketplaceReceiptSignatureAlgorithm = 'ES256';
+/**
+ * The id of one receipt signing key: the RFC 7638 thumbprint of its public half.
+ * Opaque to a consumer: compare it, never parse it. It names the key and is never
+ * the key.
+ */
+export type MarketplaceReceiptKeyId = string;
+/**
+ * Who published the release a sale was for. A third party's sale is a marketplace
+ * settlement; the house publisher's is a charge (CAY-0082 §1, §2). Cayso decides it
+ * from Store Platform's signed order and never from the caller's word.
+ */
+export type MarketplaceSaleKind = 'third-party' | 'house-publisher';
+/**
+ * One leg of a receipt: the wallet at the far end from the buyer, and the whole
+ * cents that crossed between them. On a sale the cents arrived there; on a refund
+ * they were drawn from there.
+ */
+export interface MarketplaceReceiptLeg {
+    readonly walletId: string;
+    readonly cents: Cents;
+}
+/** A third-party sale: one `marketplace_settlement`, paying the publisher and the Treasury. */
+export interface MarketplaceSettlementReceiptStatement {
+    readonly movementKind: 'marketplace_settlement';
+    readonly saleKind: 'third-party';
+    readonly movementId: string;
+    /** The immutable digest of Store Platform's signed order this sale settled. */
+    readonly orderDigest: string;
+    /** The checkout's idempotency key, unique per paying wallet (CAY-0082 §4). */
+    readonly idempotencyKey: string;
+    /** The paying wallet. */
+    readonly buyerWalletId: string;
+    /** The publisher's share, to the publisher's Citizen Wallet. */
+    readonly publisherLeg: MarketplaceReceiptLeg;
+    /** The Community's share, straight to the Treasury. */
+    readonly communityLeg: MarketplaceReceiptLeg;
+    /** The allocation-policy version Store Platform's signed order named. */
+    readonly allocationPolicyVersion: string;
+    /** When the movement was written. */
+    readonly writtenAt: Millis;
+    /** The key the signature was made with. */
+    readonly keyId: MarketplaceReceiptKeyId;
+}
+/** A house-publisher sale: one `charge` to the Treasury, and no publisher leg. */
+export interface HousePublisherChargeReceiptStatement {
+    readonly movementKind: 'charge';
+    readonly saleKind: 'house-publisher';
+    readonly movementId: string;
+    readonly orderDigest: string;
+    readonly idempotencyKey: string;
+    /** The paying wallet. */
+    readonly buyerWalletId: string;
+    /** The whole price, to the Treasury. */
+    readonly communityLeg: MarketplaceReceiptLeg;
+    readonly allocationPolicyVersion: string;
+    readonly writtenAt: Millis;
+    readonly keyId: MarketplaceReceiptKeyId;
+}
+/** The refund of a third-party sale: each leg drawn back from where it landed, to the buyer. */
+export interface ThirdPartyRefundReceiptStatement {
+    readonly movementKind: 'marketplace_refund';
+    readonly saleKind: 'third-party';
+    readonly movementId: string;
+    /** The order digest of the sale this refunds. */
+    readonly orderDigest: string;
+    /** The refund's own idempotency key, never the sale's. */
+    readonly idempotencyKey: string;
+    /** The wallet refunded, which is the wallet that paid for the sale. */
+    readonly buyerWalletId: string;
+    /** The publisher's share, drawn from the publisher's wallet. */
+    readonly publisherLeg: MarketplaceReceiptLeg;
+    /** The Community's share, drawn from the Treasury. */
+    readonly communityLeg: MarketplaceReceiptLeg;
+    /** The allocation-policy version of the sale refunded. */
+    readonly allocationPolicyVersion: string;
+    readonly writtenAt: Millis;
+    readonly keyId: MarketplaceReceiptKeyId;
+}
+/** The refund of a house-publisher sale: the whole, drawn from the Treasury, to the buyer. */
+export interface HousePublisherRefundReceiptStatement {
+    readonly movementKind: 'marketplace_refund';
+    readonly saleKind: 'house-publisher';
+    readonly movementId: string;
+    /** The order digest of the sale this refunds. */
+    readonly orderDigest: string;
+    /** The refund's own idempotency key, never the sale's. */
+    readonly idempotencyKey: string;
+    readonly buyerWalletId: string;
+    /** The whole, drawn from the Treasury. */
+    readonly communityLeg: MarketplaceReceiptLeg;
+    readonly allocationPolicyVersion: string;
+    readonly writtenAt: Millis;
+    readonly keyId: MarketplaceReceiptKeyId;
+}
+/** What Cayso signs about one marketplace movement. Exactly one of the four. */
+export type MarketplaceReceiptStatement = MarketplaceSettlementReceiptStatement | HousePublisherChargeReceiptStatement | ThirdPartyRefundReceiptStatement | HousePublisherRefundReceiptStatement;
+/** A receipt: the statement, and Cayso's signature over its encoding. */
+export interface MarketplaceReceipt {
+    readonly statement: MarketplaceReceiptStatement;
+    /**
+     * The {@link MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM} signature over
+     * {@link encodeMarketplaceReceiptStatement}`(statement)`: `r || s`, 64 bytes, as
+     * unpadded base64url.
+     */
+    readonly signature: string;
+}
+/**
+ * Piper asking, for the buyer, what one idempotency key landed (CAY-0083 §2). The
+ * paying wallet is the verified subject's own and is never named here: see the file
+ * docblock.
+ */
+export interface MarketplaceReceiptReadRequest {
+    /** The key the sale or refund was presented under, exactly as it was presented. */
+    readonly idempotencyKey: string;
+}
+/** The key landed a movement: its signed receipt. */
+export interface MarketplaceReceiptFound {
+    readonly outcome: 'receipt';
+    readonly receipt: MarketplaceReceipt;
+}
+/**
+ * Nothing was written under this key for this wallet. Retry with the SAME key,
+ * never a new one: the first attempt may still be in flight, and the same key lands
+ * it exactly once either way. It is not "pending": there is no pending movement.
+ */
+export interface MarketplaceNoMovement {
+    readonly outcome: 'no-movement';
+}
+/**
+ * Why the read could not be asked. Closed, and a refusal is never a statement about
+ * the key: a caller must not read one as "no movement".
+ */
+export type MarketplaceReceiptReadRefusal = 
+/**
+ * No wallet is bound to the verified subject now, for example after erasure, so
+ * there is no paying wallet to ask about and whether the key landed is not known.
+ */
+'wallet_has_no_live_binding';
+/** The read was refused, with one reason. Nothing was written. */
+export interface MarketplaceReceiptReadRefused {
+    readonly outcome: 'refused';
+    readonly error: MarketplaceReceiptReadRefusal;
+}
+/**
+ * The ONE declared answer to the status read, discriminated by `outcome`: a receipt,
+ * "no movement for this key", or a refusal. Never "pending".
+ */
+export type MarketplaceReceiptReadResponse = MarketplaceReceiptFound | MarketplaceNoMovement | MarketplaceReceiptReadRefused;
+/**
+ * The exact bytes a marketplace receipt's signature is computed over.
+ *
+ * Builds a fresh object from the statement's named fields, in a fixed order, so the
+ * encoding depends on nothing but their values: not on the order a caller wrote
+ * them in. THROWS a `TypeError` for anything that is not exactly one of the four
+ * statements — a pair of kinds that is not admissible, a missing or extra field, a
+ * string field that is not a string, or cents or a time that is not a safe whole
+ * number no less than zero. A statement arrives from a transport before it is typed,
+ * and a value of the wrong kind would still encode, to something nobody signed.
+ */
+export declare function encodeMarketplaceReceiptStatement(statement: MarketplaceReceiptStatement): Uint8Array<ArrayBuffer>;

package/dist/marketplace-receipt.js

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The algorithm every marketplace receipt is signed with: ECDSA P-256 with SHA-256,
+ * `r || s` encoded (JOSE `ES256`), CAY-0083 §1.
+ */
+export const MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM = 'ES256';
+// --- The encoding ------------------------------------------------------------
+/** The statement's own fields, in the order they are encoded, before and after the legs. */
+const LEADING_FIELDS = [
+    'movementKind',
+    'saleKind',
+    'movementId',
+    'orderDigest',
+    'idempotencyKey',
+    'buyerWalletId',
+];
+const TRAILING_FIELDS = ['allocationPolicyVersion', 'writtenAt', 'keyId'];
+/** Every string field, each of which must be a string when it arrives. */
+const STRING_FIELDS = [
+    'movementId',
+    'orderDigest',
+    'idempotencyKey',
+    'buyerWalletId',
+    'allocationPolicyVersion',
+    'keyId',
+];
+/**
+ * The four admissible pairs of `movementKind` and `saleKind`, and whether each has a
+ * publisher leg. A pair not listed here is not a receipt.
+ */
+const ADMISSIBLE = [
+    { movementKind: 'marketplace_settlement', saleKind: 'third-party', publisherLeg: true },
+    { movementKind: 'charge', saleKind: 'house-publisher', publisherLeg: false },
+    { movementKind: 'marketplace_refund', saleKind: 'third-party', publisherLeg: true },
+    { movementKind: 'marketplace_refund', saleKind: 'house-publisher', publisherLeg: false },
+];
+/** The fields of a leg, in the order they are encoded. */
+const LEG_FIELDS = ['walletId', 'cents'];
+/**
+ * The exact bytes a marketplace receipt's signature is computed over.
+ *
+ * Builds a fresh object from the statement's named fields, in a fixed order, so the
+ * encoding depends on nothing but their values: not on the order a caller wrote
+ * them in. THROWS a `TypeError` for anything that is not exactly one of the four
+ * statements — a pair of kinds that is not admissible, a missing or extra field, a
+ * string field that is not a string, or cents or a time that is not a safe whole
+ * number no less than zero. A statement arrives from a transport before it is typed,
+ * and a value of the wrong kind would still encode, to something nobody signed.
+ */
+export function encodeMarketplaceReceiptStatement(statement) {
+    const value = statement;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('a marketplace receipt statement is an object');
+    }
+    const shape = ADMISSIBLE.find((candidate) => candidate.movementKind === value['movementKind'] && candidate.saleKind === value['saleKind']);
+    if (shape === undefined) {
+        throw new TypeError('a marketplace receipt statement names an admissible movement and sale kind');
+    }
+    const legFields = shape.publisherLeg ? ['publisherLeg', 'communityLeg'] : ['communityLeg'];
+    const fields = [...LEADING_FIELDS, ...legFields, ...TRAILING_FIELDS];
+    requireExactly(value, fields, 'a marketplace receipt statement carries exactly its own fields');
+    for (const field of STRING_FIELDS) {
+        if (typeof value[field] !== 'string') {
+            throw new TypeError('every identifier of a marketplace receipt statement is a string');
+        }
+    }
+    requireWholeNumber(value['writtenAt'], 'a marketplace receipt is written at whole milliseconds');
+    const canonical = {};
+    for (const field of LEADING_FIELDS)
+        canonical[field] = value[field];
+    for (const field of legFields)
+        canonical[field] = canonicalLeg(value[field]);
+    for (const field of TRAILING_FIELDS)
+        canonical[field] = value[field];
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+/** A leg rebuilt in its fixed order, or a refusal. */
+function canonicalLeg(leg) {
+    if (typeof leg !== 'object' || leg === null || Array.isArray(leg)) {
+        throw new TypeError('a marketplace receipt leg is an object');
+    }
+    const value = leg;
+    requireExactly(value, LEG_FIELDS, 'a marketplace receipt leg carries a wallet id and cents only');
+    if (typeof value['walletId'] !== 'string') {
+        throw new TypeError('a marketplace receipt leg names its wallet by id');
+    }
+    requireWholeNumber(value['cents'], 'a marketplace receipt leg carries whole cents');
+    return { walletId: value['walletId'], cents: value['cents'] };
+}
+/** Refuse an object whose own keys are not exactly `fields`. */
+function requireExactly(value, fields, category) {
+    const keys = Object.keys(value);
+    if (keys.length !== fields.length || !fields.every((field) => Object.hasOwn(value, field))) {
+        throw new TypeError(category);
+    }
+}
+/** Refuse anything that is not a safe whole number no less than zero. */
+function requireWholeNumber(value, category) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(category);
+    }
+}