@aglyn/plugins-commerce 1.0.0-beta.287 → 1.0.0-beta.289

package/src/lib/server/quote-link-token.js

@@ -0,0 +1,97 @@
+/**
+ * @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 { hostPublicOrigin } from "@aglyn/aglyn/server";
+import { createHmac, timingSafeEqual } from "crypto";
+import { quotePageHref } from "../constants/quote-page.js";
+import { tokenSigningSecret } from "./download.js";
+/**
+ * A quote's pay link (AGL-4094): `/pay-quote?q=<quoteId>&t=<token>` on the
+ * business's own site, where the customer sees the quote and pays it.
+ *
+ * The token is `<version>.<signature>`: the quote's link version
+ * (`quote.linkVersion`, absent reading as 1) and the first 32 hex characters of
+ * `HMAC(quote-link:hostId:quoteId:version)` under the commerce
+ * `TOKEN_SIGNING_SECRET`. A pure function of what the quote already holds, so
+ * nothing is stored per link and every message that carried the link carries
+ * the same working one. The `quote-link:` prefix keeps it from being replayed
+ * as an order-status, download or supplier token, which sign other payloads
+ * under the same secret.
+ *
+ * NO EXPIRY. A quote is paid when the customer is ready, and a link that died
+ * first would be a quote they could not pay. The version is what retires a
+ * link: replacing it bumps the version on the quote, and a link signed for an
+ * older version still verifies, so its page can say the quote was replaced,
+ * without showing any of it.
+ */ const SIGNATURE_LENGTH = 32;
+const MAX_VERSION = 1000000;
+function signQuoteLink(hostId, quoteId, version) {
+    return createHmac('sha256', tokenSigningSecret()).update(`quote-link:${hostId}:${quoteId}:${version}`).digest('hex').slice(0, SIGNATURE_LENGTH);
+}
+/** The token's two halves, or null for a token not shaped like one. */ export function parseQuoteLinkToken(token) {
+    const match = /^([1-9]\d{0,6})\.([0-9a-f]{32})$/.exec(String(token != null ? token : ''));
+    if (!match) return null;
+    const version = Number(match[1]);
+    if (!Number.isSafeInteger(version) || version > MAX_VERSION) return null;
+    return {
+        version,
+        signature: match[2]
+    };
+}
+/** The token for one version of a quote's link, or null when the signing secret is unset. */ export function mintQuoteLinkToken(hostId, quoteId, version) {
+    if (!hostId || !quoteId || !Number.isSafeInteger(version) || version < 1 || version > MAX_VERSION) {
+        return null;
+    }
+    try {
+        return `${version}.${signQuoteLink(hostId, quoteId, version)}`;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * Checks a presented token in constant time and answers the link version it
+ * was signed for, or null for a token that is wrong, malformed or unverifiable
+ * (no secret). The caller compares the version with the quote's own.
+ */ export function verifyQuoteLinkToken(hostId, quoteId, token) {
+    if (!hostId || !quoteId) return null;
+    const parsed = parseQuoteLinkToken(token);
+    if (!parsed) return null;
+    let expected;
+    try {
+        expected = signQuoteLink(hostId, quoteId, parsed.version);
+    } catch (unused) {
+        return null;
+    }
+    const a = Buffer.from(parsed.signature);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) return null;
+    return timingSafeEqual(new Uint8Array(a), new Uint8Array(b)) ? parsed.version : null;
+}
+/**
+ * The absolute pay link for a quote at a link version, or null when either
+ * half is missing: a site with no public address, or no signing secret. What
+ * the console copies, and what a quote or invoice email puts in front of the
+ * customer.
+ */ export function quotePayLinkUrl(host, hostId, quoteId, version) {
+    const origin = hostPublicOrigin({
+        cname: typeof (host == null ? void 0 : host.cname) === 'string' ? host.cname : null,
+        subdomain: typeof (host == null ? void 0 : host.subdomain) === 'string' ? host.subdomain : null
+    });
+    const token = mintQuoteLinkToken(hostId, quoteId, version);
+    if (!origin || !token) return null;
+    return `${origin}${quotePageHref(quoteId, token)}`;
+}
+
+//# sourceMappingURL=quote-link-token.js.map

package/src/lib/server/quote-link-token.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/quote-link-token.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 { hostPublicOrigin } from '@aglyn/aglyn/server'\nimport { createHmac, timingSafeEqual } from 'crypto'\nimport { quotePageHref } from '../constants/quote-page'\nimport { tokenSigningSecret } from './download'\n\n/**\n * A quote's pay link (AGL-4094): `/pay-quote?q=<quoteId>&t=<token>` on the\n * business's own site, where the customer sees the quote and pays it.\n *\n * The token is `<version>.<signature>`: the quote's link version\n * (`quote.linkVersion`, absent reading as 1) and the first 32 hex characters of\n * `HMAC(quote-link:hostId:quoteId:version)` under the commerce\n * `TOKEN_SIGNING_SECRET`. A pure function of what the quote already holds, so\n * nothing is stored per link and every message that carried the link carries\n * the same working one. The `quote-link:` prefix keeps it from being replayed\n * as an order-status, download or supplier token, which sign other payloads\n * under the same secret.\n *\n * NO EXPIRY. A quote is paid when the customer is ready, and a link that died\n * first would be a quote they could not pay. The version is what retires a\n * link: replacing it bumps the version on the quote, and a link signed for an\n * older version still verifies, so its page can say the quote was replaced,\n * without showing any of it.\n */\nconst SIGNATURE_LENGTH = 32\nconst MAX_VERSION = 1_000_000\n\nfunction signQuoteLink(hostId: string, quoteId: string, version: number): string {\n  return createHmac('sha256', tokenSigningSecret())\n    .update(`quote-link:${hostId}:${quoteId}:${version}`)\n    .digest('hex')\n    .slice(0, SIGNATURE_LENGTH)\n}\n\n/** The token's two halves, or null for a token not shaped like one. */\nexport function parseQuoteLinkToken(token: string): { version: number; signature: string } | null {\n  const match = /^([1-9]\\d{0,6})\\.([0-9a-f]{32})$/.exec(String(token ?? ''))\n  if (!match) return null\n  const version = Number(match[1])\n  if (!Number.isSafeInteger(version) || version > MAX_VERSION) return null\n  return { version, signature: match[2] }\n}\n\n/** The token for one version of a quote's link, or null when the signing secret is unset. */\nexport function mintQuoteLinkToken(hostId: string, quoteId: string, version: number): string | null {\n  if (!hostId || !quoteId || !Number.isSafeInteger(version) || version < 1 || version > MAX_VERSION) {\n    return null\n  }\n  try {\n    return `${version}.${signQuoteLink(hostId, quoteId, version)}`\n  } catch {\n    return null\n  }\n}\n\n/**\n * Checks a presented token in constant time and answers the link version it\n * was signed for, or null for a token that is wrong, malformed or unverifiable\n * (no secret). The caller compares the version with the quote's own.\n */\nexport function verifyQuoteLinkToken(hostId: string, quoteId: string, token: string): number | null {\n  if (!hostId || !quoteId) return null\n  const parsed = parseQuoteLinkToken(token)\n  if (!parsed) return null\n  let expected: string\n  try {\n    expected = signQuoteLink(hostId, quoteId, parsed.version)\n  } catch {\n    return null\n  }\n  const a = Buffer.from(parsed.signature)\n  const b = Buffer.from(expected)\n  if (a.length !== b.length) return null\n  return timingSafeEqual(new Uint8Array(a), new Uint8Array(b)) ? parsed.version : null\n}\n\n/**\n * The absolute pay link for a quote at a link version, or null when either\n * half is missing: a site with no public address, or no signing secret. What\n * the console copies, and what a quote or invoice email puts in front of the\n * customer.\n */\nexport function quotePayLinkUrl(\n  host: { cname?: unknown; subdomain?: unknown } | null | undefined,\n  hostId: string,\n  quoteId: string,\n  version: number,\n): string | null {\n  const origin = hostPublicOrigin({\n    cname: typeof host?.cname === 'string' ? host.cname : null,\n    subdomain: typeof host?.subdomain === 'string' ? host.subdomain : null,\n  })\n  const token = mintQuoteLinkToken(hostId, quoteId, version)\n  if (!origin || !token) return null\n  return `${origin}${quotePageHref(quoteId, token)}`\n}\n"],"names":["hostPublicOrigin","createHmac","timingSafeEqual","quotePageHref","tokenSigningSecret","SIGNATURE_LENGTH","MAX_VERSION","signQuoteLink","hostId","quoteId","version","update","digest","slice","parseQuoteLinkToken","token","match","exec","String","Number","isSafeInteger","signature","mintQuoteLinkToken","verifyQuoteLinkToken","parsed","expected","a","Buffer","from","b","length","Uint8Array","quotePayLinkUrl","host","origin","cname","subdomain"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,sBAAqB;AACtD,SAASC,UAAU,EAAEC,eAAe,QAAQ,SAAQ;AACpD,SAASC,aAAa,QAAQ,6BAAyB;AACvD,SAASC,kBAAkB,QAAQ,gBAAY;AAE/C;;;;;;;;;;;;;;;;;;CAkBC,GACD,MAAMC,mBAAmB;AACzB,MAAMC,cAAc;AAEpB,SAASC,cAAcC,MAAc,EAAEC,OAAe,EAAEC,OAAe;IACrE,OAAOT,WAAW,UAAUG,sBACzBO,MAAM,CAAC,CAAC,WAAW,EAAEH,OAAO,CAAC,EAAEC,QAAQ,CAAC,EAAEC,SAAS,EACnDE,MAAM,CAAC,OACPC,KAAK,CAAC,GAAGR;AACd;AAEA,qEAAqE,GACrE,OAAO,SAASS,oBAAoBC,KAAa;IAC/C,MAAMC,QAAQ,mCAAmCC,IAAI,CAACC,OAAOH,gBAAAA,QAAS;IACtE,IAAI,CAACC,OAAO,OAAO;IACnB,MAAMN,UAAUS,OAAOH,KAAK,CAAC,EAAE;IAC/B,IAAI,CAACG,OAAOC,aAAa,CAACV,YAAYA,UAAUJ,aAAa,OAAO;IACpE,OAAO;QAAEI;QAASW,WAAWL,KAAK,CAAC,EAAE;IAAC;AACxC;AAEA,2FAA2F,GAC3F,OAAO,SAASM,mBAAmBd,MAAc,EAAEC,OAAe,EAAEC,OAAe;IACjF,IAAI,CAACF,UAAU,CAACC,WAAW,CAACU,OAAOC,aAAa,CAACV,YAAYA,UAAU,KAAKA,UAAUJ,aAAa;QACjG,OAAO;IACT;IACA,IAAI;QACF,OAAO,GAAGI,QAAQ,CAAC,EAAEH,cAAcC,QAAQC,SAASC,UAAU;IAChE,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASa,qBAAqBf,MAAc,EAAEC,OAAe,EAAEM,KAAa;IACjF,IAAI,CAACP,UAAU,CAACC,SAAS,OAAO;IAChC,MAAMe,SAASV,oBAAoBC;IACnC,IAAI,CAACS,QAAQ,OAAO;IACpB,IAAIC;IACJ,IAAI;QACFA,WAAWlB,cAAcC,QAAQC,SAASe,OAAOd,OAAO;IAC1D,EAAE,eAAM;QACN,OAAO;IACT;IACA,MAAMgB,IAAIC,OAAOC,IAAI,CAACJ,OAAOH,SAAS;IACtC,MAAMQ,IAAIF,OAAOC,IAAI,CAACH;IACtB,IAAIC,EAAEI,MAAM,KAAKD,EAAEC,MAAM,EAAE,OAAO;IAClC,OAAO5B,gBAAgB,IAAI6B,WAAWL,IAAI,IAAIK,WAAWF,MAAML,OAAOd,OAAO,GAAG;AAClF;AAEA;;;;;CAKC,GACD,OAAO,SAASsB,gBACdC,IAAiE,EACjEzB,MAAc,EACdC,OAAe,EACfC,OAAe;IAEf,MAAMwB,SAASlC,iBAAiB;QAC9BmC,OAAO,QAAOF,wBAAAA,KAAME,KAAK,MAAK,WAAWF,KAAKE,KAAK,GAAG;QACtDC,WAAW,QAAOH,wBAAAA,KAAMG,SAAS,MAAK,WAAWH,KAAKG,SAAS,GAAG;IACpE;IACA,MAAMrB,QAAQO,mBAAmBd,QAAQC,SAASC;IAClD,IAAI,CAACwB,UAAU,CAACnB,OAAO,OAAO;IAC9B,OAAO,GAAGmB,SAAS/B,cAAcM,SAASM,QAAQ;AACpD"}

package/src/lib/server/quote-pay.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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, type PluginApiRequest } from '@aglyn/aglyn/server';
+import * as CommerceModel from '../model';
+import { type CheckoutSessionExpiry } from './checkout-session-expiry';
+import { resolveManualTaxRateId } from './manual-tax-rate';
+import { type NativeCheckoutMode } from './native-checkout';
+import { ensureCheckoutDomain } from './payment-method-domains';
+/** Lookups and presses one address may make per site, per ten minutes. */
+export declare const QUOTE_VIEW_LOOKUPS_PER_WINDOW = 60;
+export declare const QUOTE_PAY_PRESSES_PER_WINDOW = 20;
+export declare const QUOTE_WINDOW_MS: number;
+export interface QuotePayDeps {
+    firestore(): FirebaseFirestore.Firestore;
+    consumeRateLimit(key: string, options: {
+        limit: number;
+        windowMs: number;
+    }): Promise<{
+        allowed: boolean;
+        resetMs: number;
+    }>;
+    orgForHost(hostId: string): Promise<{
+        id?: string;
+        org?: any;
+    } | null>;
+    nativeMode(orgId: string): Promise<NativeCheckoutMode>;
+    /** The store's manual tax rate as a Stripe tax rate, or null when one cannot be had. */
+    taxRateId(input: Parameters<typeof resolveManualTaxRateId>[0]): Promise<string | null>;
+    createSession(params: URLSearchParams, headers: Record<string, string>): Promise<{
+        ok: boolean;
+        session: {
+            id?: string;
+            url?: string;
+            client_secret?: string;
+            error?: unknown;
+        };
+    }>;
+    expireSession(sessionId: string): Promise<CheckoutSessionExpiry>;
+    /** Registers the page's domain for Apple Pay; never throws. */
+    ensureDomain(input: Parameters<typeof ensureCheckoutDomain>[0]): Promise<unknown>;
+    now(): number;
+}
+export declare function defaultQuotePayDeps(): QuotePayDeps;
+type Outcome = {
+    status: number;
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+};
+/** `GET /api/commerce/quote-view`: the quote page's data. */
+export declare function handleQuoteView(deps: QuotePayDeps, req: PluginApiRequest): Promise<Outcome>;
+/** The Checkout Session a quote's Pay opens, as form params. Pure over its inputs. */
+export declare function buildQuoteSessionParams(input: {
+    hostId: string;
+    quoteId: string;
+    order: CommerceModel.HostOrder;
+    charge: CommerceModel.QuoteCheckoutCharge;
+    accountId: string;
+    feeCents: number;
+    taxRateId: string;
+    returnUrl: string;
+    paymentMethods: CommerceModel.StorefrontPaymentMethodControls;
+}): URLSearchParams;
+/** `POST /api/commerce/quote-pay`: a fresh Checkout Session for the quote. */
+export declare function handleQuotePay(deps: QuotePayDeps, req: PluginApiRequest): Promise<Outcome>;
+/** `GET /api/commerce/quote-view`. */
+export declare const quoteViewHandler: PluginApiHandler;
+/** `POST /api/commerce/quote-pay`. */
+export declare const quotePayHandler: PluginApiHandler;
+export {};