@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/contact-refund.js

@@ -0,0 +1,196 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * 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.
+ */ import { mergeContactInteraction, normalizeContactEmail } from "@aglyn/aglyn/server";
+import { firebaseAdmin, orgDataCollectionForHost } from "@aglyn/tenant-data-admin";
+// Leaf imports, not the barrel: `refund.spec.ts` and most specs in this
+// library mock `@aglyn/tenant-data-admin` wholesale, and a permissive stub of
+// either function would turn every case below green without a document ever
+// having to exist.
+import { findContactByEmail } from "@aglyn/tenant-data-admin/server/contact-email-index";
+import { updateExisting } from "@aglyn/tenant-data-admin/server/update-existing";
+/**
+ * Money going BACK to a customer, recorded on their contact (AGL-1754).
+ *
+ * `upsertHostContact` accumulates `ltvCents` and nothing anywhere decremented
+ * it, so a customer who bought $500 and returned all of it read identically to
+ * one who bought $500 and kept it — and the first surface built on the field
+ * (RFM segmentation, a lifetime-value column, a best-customers list) would have
+ * ranked a serial returner among the merchant's best customers.
+ *
+ * WHAT THIS WRITES, AND WHY IT IS NOT A DECREMENT
+ *
+ * `ltvCents` is left exactly as it is and the reversal is recorded BESIDE it:
+ *
+ * | field | meaning |
+ * | -- | -- |
+ * | `ltvCents` | gross money handed over, unchanged (AGL-1748) |
+ * | `refundedCents` | gross money handed back |
+ * | `ordersCount` | orders placed, unchanged |
+ * | `refundedOrdersCount` | of those, how many ended fully reversed |
+ * | `lastRefundAtMs` | when money last went back |
+ *
+ * This is the shape AGL-1747 chose two days earlier for the same question on
+ * the orders CSV — `amountUsd` stayed gross under its existing name and
+ * `refundedUsd`/`netUsd` were appended — and it is the shape AGL-1748 named
+ * when it recorded the gross semantics in `upsert-contact.ts`. Netting in
+ * place would make a stored number mean one thing for rows written before this
+ * commit and another for rows written after, with nothing on the document to
+ * tell the two apart. Two fields cost one number's worth of storage and keep
+ * both facts, and a reader that wants the net has `ltvCents - refundedCents`.
+ *
+ * It also answers "can it go negative?" by moving the question off storage.
+ * Both figures are monotonic counters of money that actually moved in one
+ * direction, so neither can go negative. The DERIVED net can, for exactly one
+ * reason: an order placed before AGL-1748 taught POS, drafts, reservations and
+ * bookings to pass `purchaseCents` at all, whose sale was never added and whose
+ * refund is subtracted here. That is a true statement about the data, and
+ * clamping it away at write time would erase the only evidence that a purchase
+ * is missing. AGL-1753 is the backfill that reconciles it, by SETTING both
+ * fields from the orders — which already carry `refundedCents`, so whatever a
+ * reader decides here costs the rebuild nothing. A merchant-facing reader
+ * should show gross and refunded, and clamp only the net it ranks on.
+ *
+ * `ordersCount` is deliberately NOT decremented. A fully refunded order still
+ * happened, and a decrement cannot be undone by a reader that would rather
+ * count it — while `refundedOrdersCount` beside it lets RFM's frequency term
+ * net the two, or not, at the point of display. Same argument as the amount,
+ * one field along.
+ *
+ * WHEN THE CONTACT IS MISSING, THIS REFUSES — and records the refusal.
+ *
+ * Refusing is right on AGL-1732's test, "does refusing discard money or work
+ * that already happened?", because it does not: the refund is durable on the
+ * order (`refundedCents`, the timeline entry, Stripe), and the contact is a
+ * derived aggregate that AGL-1753's rebuild reads back out of those same
+ * orders. Creating one here would be worse three ways — creation is audience
+ * BAND gated, so it hard-bands a Free org (raising the AGL-891 dropped-contacts
+ * alert for a record the merchant never had) or meters onto a paid invoice; the
+ * contact it created would hold a refund and no purchase, which is the negative
+ * lifetime value above with nothing to reconcile it against; and it is the
+ * phantom-document shape the `updateExisting` sweep spent yesterday closing.
+ *
+ * So the write is an `update()`, never `set(…, { merge: true })` — the contact
+ * may have been deleted between the query and the write, and a merge-set would
+ * resurrect it as a document holding nothing but a refund. Every refusal
+ * increments `hosts/{hostId}/counters/contactRefundsUnmatched`, the counter
+ * shape `contactsDropped` already uses, so a refund that reached no contact is
+ * countable rather than silent.
+ *
+ * CHARGEBACKS (AGL-1554) are a separate decision and are NOT handled here.
+ * This takes `kind` so the handler that eventually answers
+ * `charge.dispute.closed` can record a lost dispute through the same writer
+ * with the same fields: money reversed is money reversed, whichever door it
+ * left by, and only the wording of the timeline entry differs.
+ */ export async function recordContactRefund(options) {
+    // Swallow-all, like `upsertHostContact`: the money has already moved and the
+    // order already records it, so nothing here may fail the refund.
+    try {
+        var _snapshot_get, _snapshot_get1;
+        const amountCents = Math.round(Number(options.amountCents));
+        if (!(amountCents > 0)) return;
+        const email = normalizeContactEmail(options.email);
+        if (!email) {
+            await recordUnmatchedRefund(options.hostId, options.orderId, 'no-email');
+            return;
+        }
+        // Contacts are ORG-scoped (AGL-237), not `hosts/{h}/contacts`, and reads
+        // narrow to what this host may see (AGL-1039) — the same lookup
+        // `upsertHostContact` makes, through the org's address index
+        // (AGL-2633), so both writers resolve the same document even when the
+        // order's address is one a merge folded into the buyer's record.
+        const contactsRef = await orgDataCollectionForHost(options.hostId, 'contacts');
+        const snapshot = await findContactByEmail(contactsRef, email, {
+            hostId: options.hostId
+        });
+        if (!snapshot) {
+            await recordUnmatchedRefund(options.hostId, options.orderId, 'no-contact');
+            return;
+        }
+        const atMs = Date.now();
+        const interaction = {
+            // `refId` names an order, so the interaction is an order interaction.
+            // There is no `'refund'` ContactSource and this deliberately does not
+            // add one: `sources` records which capture silo produced the contact,
+            // and a refund captures nobody.
+            type: 'order',
+            atMs,
+            refId: options.orderId,
+            summary: `$${(amountCents / 100).toFixed(2)} ` + (options.kind === 'chargeback' ? 'charged back' : 'refunded') + (options.closedTheOrder ? ' (full)' : '')
+        };
+        // Reused for the newest-first ordering and the interactions cap; only the
+        // timeline is taken. The `sources` half of the merge is discarded on
+        // purpose, per the note above.
+        const { interactions } = mergeContactInteraction({
+            sources: (_snapshot_get = snapshot.get('sources')) != null ? _snapshot_get : {},
+            interactions: (_snapshot_get1 = snapshot.get('interactions')) != null ? _snapshot_get1 : []
+        }, {
+            source: 'order',
+            interaction
+        });
+        const FieldValue = firebaseAdmin.firestore.FieldValue;
+        // Every field is top-level. `update()` replaces a nested map wholesale
+        // rather than merging into it, so anything under a map would have to be
+        // written as a dotted path; there is nothing here that is.
+        //
+        // The amounts are increments, so two refunds settling at once both land.
+        // `interactions` is a read-modify-write and therefore CAN lose one of two
+        // concurrent entries — the same exposure `upsertHostContact` has on the
+        // same array, and it costs a timeline line rather than a number.
+        const landed = await updateExisting(snapshot.ref, _extends({
+            refundedCents: FieldValue.increment(amountCents)
+        }, options.closedTheOrder ? {
+            refundedOrdersCount: FieldValue.increment(1)
+        } : {}, {
+            lastRefundAtMs: atMs,
+            interactions,
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        if (!landed) {
+            await recordUnmatchedRefund(options.hostId, options.orderId, 'contact-deleted');
+        }
+    } catch (error) {
+        console.error('recordContactRefund failed', error);
+    }
+}
+/**
+ * A refund that reached no contact, recorded rather than dropped (AGL-1754).
+ *
+ * The `set(…, { merge: true })` here IS meant to conjure the document — it is
+ * a counter, and the shape is `counters/contactsDropped`'s, so an operator
+ * reading a host's counters finds both kinds of missed contact record in one
+ * place. The reason is stamped because the three cases want different answers:
+ * `no-email` is an order that never identified its buyer, `no-contact` is the
+ * AGL-1753 backfill's work, and `contact-deleted` is a contact removed between
+ * the sale and the refund, which nothing should recreate.
+ */ async function recordUnmatchedRefund(hostId, orderId, reason) {
+    console.warn('refund reached no contact', {
+        hostId,
+        orderId,
+        reason
+    });
+    const FieldValue = firebaseAdmin.firestore.FieldValue;
+    await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).collection('counters').doc('contactRefundsUnmatched').set({
+        total: FieldValue.increment(1),
+        lastOrderId: orderId,
+        lastReason: reason,
+        lastAtMs: Date.now()
+    }, {
+        merge: true
+    }).catch(()=>undefined);
+}
+
+//# sourceMappingURL=contact-refund.js.map

package/src/lib/server/contact-refund.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/contact-refund.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  mergeContactInteraction,\n  normalizeContactEmail,\n  type ContactInteraction,\n} from '@aglyn/aglyn/server'\nimport {\n  firebaseAdmin,\n  orgDataCollectionForHost,\n} from '@aglyn/tenant-data-admin'\n// Leaf imports, not the barrel: `refund.spec.ts` and most specs in this\n// library mock `@aglyn/tenant-data-admin` wholesale, and a permissive stub of\n// either function would turn every case below green without a document ever\n// having to exist.\nimport { findContactByEmail } from '@aglyn/tenant-data-admin/server/contact-email-index'\nimport { updateExisting } from '@aglyn/tenant-data-admin/server/update-existing'\n\n/**\n * Money going BACK to a customer, recorded on their contact (AGL-1754).\n *\n * `upsertHostContact` accumulates `ltvCents` and nothing anywhere decremented\n * it, so a customer who bought $500 and returned all of it read identically to\n * one who bought $500 and kept it — and the first surface built on the field\n * (RFM segmentation, a lifetime-value column, a best-customers list) would have\n * ranked a serial returner among the merchant's best customers.\n *\n * WHAT THIS WRITES, AND WHY IT IS NOT A DECREMENT\n *\n * `ltvCents` is left exactly as it is and the reversal is recorded BESIDE it:\n *\n * | field | meaning |\n * | -- | -- |\n * | `ltvCents` | gross money handed over, unchanged (AGL-1748) |\n * | `refundedCents` | gross money handed back |\n * | `ordersCount` | orders placed, unchanged |\n * | `refundedOrdersCount` | of those, how many ended fully reversed |\n * | `lastRefundAtMs` | when money last went back |\n *\n * This is the shape AGL-1747 chose two days earlier for the same question on\n * the orders CSV — `amountUsd` stayed gross under its existing name and\n * `refundedUsd`/`netUsd` were appended — and it is the shape AGL-1748 named\n * when it recorded the gross semantics in `upsert-contact.ts`. Netting in\n * place would make a stored number mean one thing for rows written before this\n * commit and another for rows written after, with nothing on the document to\n * tell the two apart. Two fields cost one number's worth of storage and keep\n * both facts, and a reader that wants the net has `ltvCents - refundedCents`.\n *\n * It also answers \"can it go negative?\" by moving the question off storage.\n * Both figures are monotonic counters of money that actually moved in one\n * direction, so neither can go negative. The DERIVED net can, for exactly one\n * reason: an order placed before AGL-1748 taught POS, drafts, reservations and\n * bookings to pass `purchaseCents` at all, whose sale was never added and whose\n * refund is subtracted here. That is a true statement about the data, and\n * clamping it away at write time would erase the only evidence that a purchase\n * is missing. AGL-1753 is the backfill that reconciles it, by SETTING both\n * fields from the orders — which already carry `refundedCents`, so whatever a\n * reader decides here costs the rebuild nothing. A merchant-facing reader\n * should show gross and refunded, and clamp only the net it ranks on.\n *\n * `ordersCount` is deliberately NOT decremented. A fully refunded order still\n * happened, and a decrement cannot be undone by a reader that would rather\n * count it — while `refundedOrdersCount` beside it lets RFM's frequency term\n * net the two, or not, at the point of display. Same argument as the amount,\n * one field along.\n *\n * WHEN THE CONTACT IS MISSING, THIS REFUSES — and records the refusal.\n *\n * Refusing is right on AGL-1732's test, \"does refusing discard money or work\n * that already happened?\", because it does not: the refund is durable on the\n * order (`refundedCents`, the timeline entry, Stripe), and the contact is a\n * derived aggregate that AGL-1753's rebuild reads back out of those same\n * orders. Creating one here would be worse three ways — creation is audience\n * BAND gated, so it hard-bands a Free org (raising the AGL-891 dropped-contacts\n * alert for a record the merchant never had) or meters onto a paid invoice; the\n * contact it created would hold a refund and no purchase, which is the negative\n * lifetime value above with nothing to reconcile it against; and it is the\n * phantom-document shape the `updateExisting` sweep spent yesterday closing.\n *\n * So the write is an `update()`, never `set(…, { merge: true })` — the contact\n * may have been deleted between the query and the write, and a merge-set would\n * resurrect it as a document holding nothing but a refund. Every refusal\n * increments `hosts/{hostId}/counters/contactRefundsUnmatched`, the counter\n * shape `contactsDropped` already uses, so a refund that reached no contact is\n * countable rather than silent.\n *\n * CHARGEBACKS (AGL-1554) are a separate decision and are NOT handled here.\n * This takes `kind` so the handler that eventually answers\n * `charge.dispute.closed` can record a lost dispute through the same writer\n * with the same fields: money reversed is money reversed, whichever door it\n * left by, and only the wording of the timeline entry differs.\n */\nexport async function recordContactRefund(options: {\n  hostId: string\n  /** The order the money went back on — the contact timeline's `refId`. */\n  orderId: string\n  /**\n   * The buyer as the ORDER recorded them, raw. Normalized here, because that\n   * is the key the contacts collection is stored under and orders are not\n   * consistent about it (AGL-1753 item 3). No `name` rides along on purpose: a\n   * refund is not a capture point and must not rewrite who the contact is.\n   */\n  email: unknown\n  /**\n   * Cents reversed by THIS attempt, never the order total. `refund.ts` caps\n   * each attempt against what is left, so several partials on one order sum to\n   * at most the order total; this follows that number rather than recomputing\n   * it.\n   */\n  amountCents: number\n  /**\n   * True only for the write that moved the order INTO `refunded`. Two partials\n   * settling concurrently can both observe a fully refunded total, so the\n   * caller decides this from the status transition it made, not from the\n   * total it read.\n   */\n  closedTheOrder: boolean\n  kind?: 'refund' | 'chargeback'\n}): Promise<void> {\n  // Swallow-all, like `upsertHostContact`: the money has already moved and the\n  // order already records it, so nothing here may fail the refund.\n  try {\n    const amountCents = Math.round(Number(options.amountCents))\n    if (!(amountCents > 0)) return\n    const email = normalizeContactEmail(options.email)\n    if (!email) {\n      await recordUnmatchedRefund(options.hostId, options.orderId, 'no-email')\n      return\n    }\n    // Contacts are ORG-scoped (AGL-237), not `hosts/{h}/contacts`, and reads\n    // narrow to what this host may see (AGL-1039) — the same lookup\n    // `upsertHostContact` makes, through the org's address index\n    // (AGL-2633), so both writers resolve the same document even when the\n    // order's address is one a merge folded into the buyer's record.\n    const contactsRef = await orgDataCollectionForHost(\n      options.hostId,\n      'contacts',\n    )\n    const snapshot = await findContactByEmail(contactsRef, email, {\n      hostId: options.hostId,\n    })\n    if (!snapshot) {\n      await recordUnmatchedRefund(options.hostId, options.orderId, 'no-contact')\n      return\n    }\n    const atMs = Date.now()\n    const interaction: ContactInteraction = {\n      // `refId` names an order, so the interaction is an order interaction.\n      // There is no `'refund'` ContactSource and this deliberately does not\n      // add one: `sources` records which capture silo produced the contact,\n      // and a refund captures nobody.\n      type: 'order',\n      atMs,\n      refId: options.orderId,\n      summary:\n        `$${(amountCents / 100).toFixed(2)} ` +\n        (options.kind === 'chargeback' ? 'charged back' : 'refunded') +\n        (options.closedTheOrder ? ' (full)' : ''),\n    }\n    // Reused for the newest-first ordering and the interactions cap; only the\n    // timeline is taken. The `sources` half of the merge is discarded on\n    // purpose, per the note above.\n    const { interactions } = mergeContactInteraction(\n      {\n        sources: snapshot.get('sources') ?? {},\n        interactions: snapshot.get('interactions') ?? [],\n      },\n      { source: 'order', interaction },\n    )\n\n    const FieldValue = firebaseAdmin.firestore.FieldValue\n    // Every field is top-level. `update()` replaces a nested map wholesale\n    // rather than merging into it, so anything under a map would have to be\n    // written as a dotted path; there is nothing here that is.\n    //\n    // The amounts are increments, so two refunds settling at once both land.\n    // `interactions` is a read-modify-write and therefore CAN lose one of two\n    // concurrent entries — the same exposure `upsertHostContact` has on the\n    // same array, and it costs a timeline line rather than a number.\n    const landed = await updateExisting(snapshot.ref, {\n      refundedCents: FieldValue.increment(amountCents),\n      ...(options.closedTheOrder\n        ? { refundedOrdersCount: FieldValue.increment(1) }\n        : {}),\n      lastRefundAtMs: atMs,\n      interactions,\n      updatedAt: FieldValue.serverTimestamp(),\n    })\n    if (!landed) {\n      await recordUnmatchedRefund(\n        options.hostId,\n        options.orderId,\n        'contact-deleted',\n      )\n    }\n  } catch (error) {\n    console.error('recordContactRefund failed', error)\n  }\n}\n\n/**\n * A refund that reached no contact, recorded rather than dropped (AGL-1754).\n *\n * The `set(…, { merge: true })` here IS meant to conjure the document — it is\n * a counter, and the shape is `counters/contactsDropped`'s, so an operator\n * reading a host's counters finds both kinds of missed contact record in one\n * place. The reason is stamped because the three cases want different answers:\n * `no-email` is an order that never identified its buyer, `no-contact` is the\n * AGL-1753 backfill's work, and `contact-deleted` is a contact removed between\n * the sale and the refund, which nothing should recreate.\n */\nasync function recordUnmatchedRefund(\n  hostId: string,\n  orderId: string,\n  reason: 'no-email' | 'no-contact' | 'contact-deleted',\n): Promise<void> {\n  console.warn('refund reached no contact', { hostId, orderId, reason })\n  const FieldValue = firebaseAdmin.firestore.FieldValue\n  await firebaseAdmin\n    .app()\n    .firestore()\n    .collection('hosts')\n    .doc(hostId)\n    .collection('counters')\n    .doc('contactRefundsUnmatched')\n    .set(\n      {\n        total: FieldValue.increment(1),\n        lastOrderId: orderId,\n        lastReason: reason,\n        lastAtMs: Date.now(),\n      },\n      { merge: true },\n    )\n    .catch(() => undefined)\n}\n"],"names":["mergeContactInteraction","normalizeContactEmail","firebaseAdmin","orgDataCollectionForHost","findContactByEmail","updateExisting","recordContactRefund","options","snapshot","amountCents","Math","round","Number","email","recordUnmatchedRefund","hostId","orderId","contactsRef","atMs","Date","now","interaction","type","refId","summary","toFixed","kind","closedTheOrder","interactions","sources","get","source","FieldValue","firestore","landed","ref","refundedCents","increment","refundedOrdersCount","lastRefundAtMs","updatedAt","serverTimestamp","error","console","reason","warn","app","collection","doc","set","total","lastOrderId","lastReason","lastAtMs","merge","catch","undefined"],"mappings":"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"}

package/src/lib/server/download.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * 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.
+ */
+import type { PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * Signing secret for commerce tokens (AGL-509). A dedicated env var with NO
+ * fallback: the previous `STRIPE_SECRET_KEY ?? 'aglyn'` recipe made download
+ * and supplier tokens forgeable on any deploy that had not set the Stripe key
+ * (payloads like `download:${hostId}:${orderId}` are guessable). Fails closed.
+ */
+export declare function tokenSigningSecret(): string;
+/**
+ * Order-scoped download token (AGL-302). Carries an embedded expiry (AGL-514)
+ * so a leaked receipt link doesn't grant perpetual re-download; the per-order
+ * download limit still bounds use within the window. Format: `${expMs}.${sig}`.
+ */
+export declare function mintDownloadToken(hostId: string, orderId: string): string;
+/** Constant-time verify of a download token, including its expiry. */
+export declare function verifyDownloadToken(hostId: string, orderId: string, token: string): boolean;
+/**
+ * Digital delivery (AGL-302): token-gated download for a paid order's
+ * digital product. Buyers always get the product's CURRENT files (new
+ * versions re-deliver automatically); attempts count against the
+ * product's download limit per order.
+ */
+export declare const downloadHandler: PluginApiHandler;

package/src/lib/server/download.js

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * 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.
+ */ import * as CommerceModel from "../model/index.js";
+import { firebaseAdmin, PAID_DOWNLOAD_LINK_TTL_MS } from "@aglyn/tenant-data-admin";
+import { createPaidMediaDeliveryIo, resolvePaidMediaDelivery } from "./paid-media-delivery.js";
+import { createHmac, timingSafeEqual } from "crypto";
+/**
+ * Signing secret for commerce tokens (AGL-509). A dedicated env var with NO
+ * fallback: the previous `STRIPE_SECRET_KEY ?? 'aglyn'` recipe made download
+ * and supplier tokens forgeable on any deploy that had not set the Stripe key
+ * (payloads like `download:${hostId}:${orderId}` are guessable). Fails closed.
+ */ export function tokenSigningSecret() {
+    const secret = process.env.TOKEN_SIGNING_SECRET;
+    if (!secret) {
+        throw new Error('TOKEN_SIGNING_SECRET is not configured');
+    }
+    return secret;
+}
+/** Download links expire 90 days after minting (AGL-514). */ const DOWNLOAD_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+function signDownload(hostId, orderId, exp) {
+    return createHmac('sha256', tokenSigningSecret()).update(`download:${hostId}:${orderId}:${exp}`).digest('hex').slice(0, 32);
+}
+/**
+ * Order-scoped download token (AGL-302). Carries an embedded expiry (AGL-514)
+ * so a leaked receipt link doesn't grant perpetual re-download; the per-order
+ * download limit still bounds use within the window. Format: `${expMs}.${sig}`.
+ */ export function mintDownloadToken(hostId, orderId) {
+    const exp = Date.now() + DOWNLOAD_TOKEN_TTL_MS;
+    return `${exp}.${signDownload(hostId, orderId, exp)}`;
+}
+/** Constant-time verify of a download token, including its expiry. */ export function verifyDownloadToken(hostId, orderId, token) {
+    const dot = token.indexOf('.');
+    if (dot <= 0) return false;
+    const exp = Number(token.slice(0, dot));
+    const sig = token.slice(dot + 1);
+    if (!Number.isFinite(exp) || Date.now() > exp) return false;
+    const expected = signDownload(hostId, orderId, exp);
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(new Uint8Array(a), new Uint8Array(b));
+}
+/**
+ * Digital delivery (AGL-302): token-gated download for a paid order's
+ * digital product. Buyers always get the product's CURRENT files (new
+ * versions re-deliver automatically); attempts count against the
+ * product's download limit per order.
+ */ export const downloadHandler = async (req, res)=>{
+    var _req_query_hostId, _req_query_orderId, _req_query_token, _req_query_productId, _req_query_file;
+    const hostId = String((_req_query_hostId = req.query.hostId) != null ? _req_query_hostId : '');
+    const orderId = String((_req_query_orderId = req.query.orderId) != null ? _req_query_orderId : '');
+    const token = String((_req_query_token = req.query.token) != null ? _req_query_token : '');
+    const productId = String((_req_query_productId = req.query.productId) != null ? _req_query_productId : '');
+    const fileIndex = Math.max(0, Number((_req_query_file = req.query.file) != null ? _req_query_file : 0));
+    if (!hostId || !orderId || !token || !productId) {
+        return res.status(400).send('Missing parameters');
+    }
+    if (!verifyDownloadToken(hostId, orderId, token)) {
+        return res.status(403).send('Invalid or expired download link');
+    }
+    try {
+        var _productSnapshot_data;
+        var _product_digitalFiles;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const orderRef = hostRef.collection('orders').doc(orderId);
+        const [orderSnapshot, productSnapshot] = await Promise.all([
+            orderRef.get(),
+            hostRef.collection('products').doc(productId).get()
+        ]);
+        if (!orderSnapshot.exists) return res.status(404).send('Unknown order');
+        const order = CommerceModel.liftLegacyOrder(orderSnapshot.data());
+        // ONE ENTITLEMENT TEST, AND IT KNOWS ABOUT PARTIAL REFUNDS (AGL-2454).
+        //
+        // This used to be a status test against the literal `'refunded'` followed
+        // by an ownership test, and `refund.ts` writes that literal only when the
+        // order is FULLY refunded — so a 99%-refunded order stayed `paid` and this
+        // gate went on serving the files. The two questions are now one call, and
+        // it also answers "was THIS line refunded by name", which is the case a
+        // line-scoped refund creates.
+        //
+        // The order-level refusal is kept separate from the ownership one so the
+        // shopper is told which of the two happened; collapsing them would answer
+        // "not part of this order" to a buyer whose own order was cancelled.
+        if (!CommerceModel.orderEntitlesProduct(order, 'any')) {
+            return res.status(403).send('This order cannot download files');
+        }
+        if (!CommerceModel.orderContainsProduct(order, productId)) {
+            return res.status(403).send('Not part of this order');
+        }
+        if (!CommerceModel.orderEntitlesProduct(order, productId)) {
+            return res.status(403).send('This purchase was refunded');
+        }
+        const product = CommerceModel.liftLegacyProduct((_productSnapshot_data = productSnapshot.data()) != null ? _productSnapshot_data : {});
+        const file = (_product_digitalFiles = product.digitalFiles) == null ? void 0 : _product_digitalFiles[fileIndex];
+        if (!(file == null ? void 0 : file.url)) return res.status(404).send('No file available');
+        /**
+     * Where the redirect lands, decided BEFORE an attempt is counted
+     * (AGL-2847).
+     *
+     * Everything above only guards the 302, so what the 302 points at is what
+     * a buyer, and anyone they forward the `Location` to, keeps. The resolver
+     * hands back a link that expires, or nothing: a CDN URL signed for
+     * {@link PAID_DOWNLOAD_LINK_TTL_MS} for a PRIVATE file in this site's
+     * library or its org's, a V4 signed Storage read for an object no media
+     * document owns, or an author-typed hotlink unchanged. A raw Storage
+     * download URL is never the answer, and a file that is still public is
+     * refused, because its URL already works for anyone forever.
+     *
+     * Resolving first means a refusal costs the buyer no attempt: the limit
+     * meters files that were handed out, not the seller's setup.
+     *
+     * `?download=1` rides inside the signed URL and makes the CDN answer with
+     * `attachment`. The signature covers `(scope, mediaId, exp)` and not the
+     * parameter, so it chooses a disposition for the one file signed and can
+     * reach no other.
+     */ const delivery = await resolvePaidMediaDelivery({
+            stored: file.url,
+            hostId,
+            ttlMs: PAID_DOWNLOAD_LINK_TTL_MS,
+            cdnParams: [
+                [
+                    'download',
+                    '1'
+                ]
+            ],
+            io: createPaidMediaDeliveryIo({
+                firestore,
+                bucket: firebaseAdmin.app().storage().bucket(process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET'])
+            })
+        });
+        if (delivery.ok === false) {
+            res.setHeader('Cache-Control', 'no-store');
+            console.error('[commerce/download] paid file not delivered', JSON.stringify({
+                hostId,
+                orderId,
+                productId,
+                file: fileIndex,
+                refusal: delivery.refusal
+            }));
+            return delivery.refusal === 'not-private' ? res.status(409).send('This file is not ready to download yet — contact the seller') : res.status(404).send('No file available');
+        }
+        // ATTEMPT ACCOUNTING, IN ONE TRANSACTION (AGL-2275).
+        //
+        // This was a read-then-write across an await, from a snapshot fetched
+        // before the check, with the failure swallowed — so N parallel requests
+        // all read the same count, all passed the limit, and all wrote
+        // `attempts + 1`. The counter advanced by one for N downloads, which
+        // makes `downloadLimit` unenforceable rather than merely approximate: a
+        // buyer who fans out ten requests takes ten copies against a limit of one.
+        // For a paid digital product that is the merchant's goods given away.
+        //
+        // It also wrote the WHOLE `downloadAttempts` map back from that stale
+        // snapshot, so a concurrent download of a DIFFERENT product in the same
+        // order had its increment erased.
+        //
+        // The half-finished conversion was visible in the file: `attemptsKey`
+        // built the dotted path `downloadAttempts.{productId}` and the next line
+        // threw it away with `void attemptsKey`. The dotted path is the right
+        // instrument and needs `update()` — which merges only that nested key, and
+        // whose "document must exist" precondition the transaction's own read has
+        // just satisfied. `set(..., { merge: true })` cannot express it: a dotted
+        // key there is a literal field name with a dot in it.
+        const attemptsKey = `downloadAttempts.${productId}`;
+        const limit = product.downloadLimit != null ? Math.max(1, product.downloadLimit) : null;
+        const withinLimit = await firestore.runTransaction(async (transaction)=>{
+            var _productId, _fresh_get;
+            const fresh = await transaction.get(orderRef);
+            if (!fresh.exists) return false;
+            const attempts = Number((_productId = ((_fresh_get = fresh.get('downloadAttempts')) != null ? _fresh_get : {})[productId]) != null ? _productId : 0);
+            if (limit != null && attempts >= limit) return false;
+            transaction.update(orderRef, {
+                [attemptsKey]: attempts + 1
+            });
+            return true;
+        });
+        if (!withinLimit) {
+            return res.status(429).send('Download limit reached — contact the seller for help');
+        }
+        // Per-order and time-boxed: no cache may keep a redirect that carries a
+        // signature past the link it opens.
+        res.setHeader('Cache-Control', 'no-store');
+        // The link dies within the hour, so a refund, an expired receipt token or
+        // a spent limit also ends what a forwarded `Location` can fetch: the next
+        // download has to come back through this route and its checks.
+        return res.redirect(302, delivery.location);
+    } catch (error) {
+        console.error(error);
+        return res.status(500).send('Download unavailable');
+    }
+};
+
+//# sourceMappingURL=download.js.map

package/src/lib/server/download.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/download.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport * as Aglyn from '@aglyn/aglyn/server'\nimport * as CommerceModel from '../model'\nimport {\n  firebaseAdmin,\n  PAID_DOWNLOAD_LINK_TTL_MS,\n} from '@aglyn/tenant-data-admin'\nimport {\n  createPaidMediaDeliveryIo,\n  resolvePaidMediaDelivery,\n} from './paid-media-delivery'\nimport { createHmac, timingSafeEqual } from 'crypto'\n\n/**\n * Signing secret for commerce tokens (AGL-509). A dedicated env var with NO\n * fallback: the previous `STRIPE_SECRET_KEY ?? 'aglyn'` recipe made download\n * and supplier tokens forgeable on any deploy that had not set the Stripe key\n * (payloads like `download:${hostId}:${orderId}` are guessable). Fails closed.\n */\nexport function tokenSigningSecret(): string {\n  const secret = process.env.TOKEN_SIGNING_SECRET\n  if (!secret) {\n    throw new Error('TOKEN_SIGNING_SECRET is not configured')\n  }\n  return secret\n}\n\n/** Download links expire 90 days after minting (AGL-514). */\nconst DOWNLOAD_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000\n\nfunction signDownload(hostId: string, orderId: string, exp: number): string {\n  return createHmac('sha256', tokenSigningSecret())\n    .update(`download:${hostId}:${orderId}:${exp}`)\n    .digest('hex')\n    .slice(0, 32)\n}\n\n/**\n * Order-scoped download token (AGL-302). Carries an embedded expiry (AGL-514)\n * so a leaked receipt link doesn't grant perpetual re-download; the per-order\n * download limit still bounds use within the window. Format: `${expMs}.${sig}`.\n */\nexport function mintDownloadToken(hostId: string, orderId: string): string {\n  const exp = Date.now() + DOWNLOAD_TOKEN_TTL_MS\n  return `${exp}.${signDownload(hostId, orderId, exp)}`\n}\n\n/** Constant-time verify of a download token, including its expiry. */\nexport function verifyDownloadToken(\n  hostId: string,\n  orderId: string,\n  token: string,\n): boolean {\n  const dot = token.indexOf('.')\n  if (dot <= 0) return false\n  const exp = Number(token.slice(0, dot))\n  const sig = token.slice(dot + 1)\n  if (!Number.isFinite(exp) || Date.now() > exp) return false\n  const expected = signDownload(hostId, orderId, exp)\n  const a = Buffer.from(sig)\n  const b = Buffer.from(expected)\n  if (a.length !== b.length) return false\n  return timingSafeEqual(new Uint8Array(a), new Uint8Array(b))\n}\n\n/**\n * Digital delivery (AGL-302): token-gated download for a paid order's\n * digital product. Buyers always get the product's CURRENT files (new\n * versions re-deliver automatically); attempts count against the\n * product's download limit per order.\n */\nexport const downloadHandler: PluginApiHandler = async (req, res) => {\n  const hostId = String(req.query.hostId ?? '')\n  const orderId = String(req.query.orderId ?? '')\n  const token = String(req.query.token ?? '')\n  const productId = String(req.query.productId ?? '')\n  const fileIndex = Math.max(0, Number(req.query.file ?? 0))\n  if (!hostId || !orderId || !token || !productId) {\n    return res.status(400).send('Missing parameters')\n  }\n  if (!verifyDownloadToken(hostId, orderId, token)) {\n    return res.status(403).send('Invalid or expired download link')\n  }\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const orderRef = hostRef.collection('orders').doc(orderId)\n    const [orderSnapshot, productSnapshot] = await Promise.all([\n      orderRef.get(),\n      hostRef.collection('products').doc(productId).get(),\n    ])\n    if (!orderSnapshot.exists) return res.status(404).send('Unknown order')\n    const order = CommerceModel.liftLegacyOrder(orderSnapshot.data() as any)\n    // ONE ENTITLEMENT TEST, AND IT KNOWS ABOUT PARTIAL REFUNDS (AGL-2454).\n    //\n    // This used to be a status test against the literal `'refunded'` followed\n    // by an ownership test, and `refund.ts` writes that literal only when the\n    // order is FULLY refunded — so a 99%-refunded order stayed `paid` and this\n    // gate went on serving the files. The two questions are now one call, and\n    // it also answers \"was THIS line refunded by name\", which is the case a\n    // line-scoped refund creates.\n    //\n    // The order-level refusal is kept separate from the ownership one so the\n    // shopper is told which of the two happened; collapsing them would answer\n    // \"not part of this order\" to a buyer whose own order was cancelled.\n    if (!CommerceModel.orderEntitlesProduct(order, 'any')) {\n      return res.status(403).send('This order cannot download files')\n    }\n    if (!CommerceModel.orderContainsProduct(order, productId)) {\n      return res.status(403).send('Not part of this order')\n    }\n    if (!CommerceModel.orderEntitlesProduct(order, productId)) {\n      return res.status(403).send('This purchase was refunded')\n    }\n    const product = CommerceModel.liftLegacyProduct(\n      (productSnapshot.data() as any) ?? {},\n    )\n    const file = product.digitalFiles?.[fileIndex]\n    if (!file?.url) return res.status(404).send('No file available')\n\n    /**\n     * Where the redirect lands, decided BEFORE an attempt is counted\n     * (AGL-2847).\n     *\n     * Everything above only guards the 302, so what the 302 points at is what\n     * a buyer, and anyone they forward the `Location` to, keeps. The resolver\n     * hands back a link that expires, or nothing: a CDN URL signed for\n     * {@link PAID_DOWNLOAD_LINK_TTL_MS} for a PRIVATE file in this site's\n     * library or its org's, a V4 signed Storage read for an object no media\n     * document owns, or an author-typed hotlink unchanged. A raw Storage\n     * download URL is never the answer, and a file that is still public is\n     * refused, because its URL already works for anyone forever.\n     *\n     * Resolving first means a refusal costs the buyer no attempt: the limit\n     * meters files that were handed out, not the seller's setup.\n     *\n     * `?download=1` rides inside the signed URL and makes the CDN answer with\n     * `attachment`. The signature covers `(scope, mediaId, exp)` and not the\n     * parameter, so it chooses a disposition for the one file signed and can\n     * reach no other.\n     */\n    const delivery = await resolvePaidMediaDelivery({\n      stored: file.url,\n      hostId,\n      ttlMs: PAID_DOWNLOAD_LINK_TTL_MS,\n      cdnParams: [['download', '1']],\n      io: createPaidMediaDeliveryIo({\n        firestore,\n        bucket: firebaseAdmin\n          .app()\n          .storage()\n          .bucket(process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET']),\n      }),\n    })\n    if (delivery.ok === false) {\n      res.setHeader('Cache-Control', 'no-store')\n      console.error(\n        '[commerce/download] paid file not delivered',\n        JSON.stringify({\n          hostId,\n          orderId,\n          productId,\n          file: fileIndex,\n          refusal: delivery.refusal,\n        }),\n      )\n      return delivery.refusal === 'not-private'\n        ? res\n            .status(409)\n            .send('This file is not ready to download yet — contact the seller')\n        : res.status(404).send('No file available')\n    }\n\n    // ATTEMPT ACCOUNTING, IN ONE TRANSACTION (AGL-2275).\n    //\n    // This was a read-then-write across an await, from a snapshot fetched\n    // before the check, with the failure swallowed — so N parallel requests\n    // all read the same count, all passed the limit, and all wrote\n    // `attempts + 1`. The counter advanced by one for N downloads, which\n    // makes `downloadLimit` unenforceable rather than merely approximate: a\n    // buyer who fans out ten requests takes ten copies against a limit of one.\n    // For a paid digital product that is the merchant's goods given away.\n    //\n    // It also wrote the WHOLE `downloadAttempts` map back from that stale\n    // snapshot, so a concurrent download of a DIFFERENT product in the same\n    // order had its increment erased.\n    //\n    // The half-finished conversion was visible in the file: `attemptsKey`\n    // built the dotted path `downloadAttempts.{productId}` and the next line\n    // threw it away with `void attemptsKey`. The dotted path is the right\n    // instrument and needs `update()` — which merges only that nested key, and\n    // whose \"document must exist\" precondition the transaction's own read has\n    // just satisfied. `set(..., { merge: true })` cannot express it: a dotted\n    // key there is a literal field name with a dot in it.\n    const attemptsKey = `downloadAttempts.${productId}`\n    const limit =\n      product.downloadLimit != null\n        ? Math.max(1, product.downloadLimit)\n        : null\n    const withinLimit = await firestore.runTransaction(async (transaction) => {\n      const fresh = await transaction.get(orderRef)\n      if (!fresh.exists) return false\n      const attempts = Number(\n        (fresh.get('downloadAttempts') ?? {})[productId] ?? 0,\n      )\n      if (limit != null && attempts >= limit) return false\n      transaction.update(orderRef, { [attemptsKey]: attempts + 1 })\n      return true\n    })\n    if (!withinLimit) {\n      return res\n        .status(429)\n        .send('Download limit reached — contact the seller for help')\n    }\n    // Per-order and time-boxed: no cache may keep a redirect that carries a\n    // signature past the link it opens.\n    res.setHeader('Cache-Control', 'no-store')\n    // The link dies within the hour, so a refund, an expired receipt token or\n    // a spent limit also ends what a forwarded `Location` can fetch: the next\n    // download has to come back through this route and its checks.\n    return res.redirect(302, delivery.location)\n  } catch (error) {\n    console.error(error)\n    return res.status(500).send('Download unavailable')\n  }\n}\n"],"names":["CommerceModel","firebaseAdmin","PAID_DOWNLOAD_LINK_TTL_MS","createPaidMediaDeliveryIo","resolvePaidMediaDelivery","createHmac","timingSafeEqual","tokenSigningSecret","secret","process","env","TOKEN_SIGNING_SECRET","Error","DOWNLOAD_TOKEN_TTL_MS","signDownload","hostId","orderId","exp","update","digest","slice","mintDownloadToken","Date","now","verifyDownloadToken","token","dot","indexOf","Number","sig","isFinite","expected","a","Buffer","from","b","length","Uint8Array","downloadHandler","req","res","String","query","productId","fileIndex","Math","max","file","status","send","productSnapshot","product","firestore","app","hostRef","collection","doc","orderRef","orderSnapshot","Promise","all","get","exists","order","liftLegacyOrder","data","orderEntitlesProduct","orderContainsProduct","liftLegacyProduct","digitalFiles","url","delivery","stored","ttlMs","cdnParams","io","bucket","storage","ok","setHeader","console","error","JSON","stringify","refusal","attemptsKey","limit","downloadLimit","withinLimit","runTransaction","transaction","fresh","attempts","redirect","location"],"mappings":"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"}

package/src/lib/server/draft-order.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * 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.
+ */
+import { type PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * Draft orders (AGL-287, Shopify parity): a manager builds an order in
+ * the console and sends the buyer a payment link. Creates the order doc
+ * (status `pending`, channel `draft`) with a sequential number, then a
+ * Stripe Checkout session on the merchant's connected account whose
+ * webhook completion flips the SAME doc to `paid`
+ * (metadata type `commerce-draft`).
+ */
+export declare const draftOrderHandler: PluginApiHandler;