@tokenoftrust/storefront-runner 6.5.1 → 6.5.3

package/apps/storefront/migrations-apps/0027_app_contact_authority.sql

@@ -0,0 +1,70 @@
+-- Owner consent for a Private App install to read order recipients for one purpose. Opaque ids and
+-- times only; granted_by is sha256 of the owner actor id. Revoke sets revoked_at once; rows are never
+-- deleted, and re-granting inserts a new row.
+CREATE TABLE `app_contact_consents` (
+  `consent_id` text PRIMARY KEY NOT NULL,
+  `install_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `purpose` text NOT NULL CHECK (`purpose` = 'fulfillment-shipping'),
+  `granted_by` text NOT NULL CHECK (length(`granted_by`) = 64 AND `granted_by` NOT GLOB '*[^0-9a-f]*'),
+  `granted_at` text NOT NULL,
+  `expires_at` text NOT NULL,
+  `revoked_at` text,
+  CHECK (`expires_at` > `granted_at`),
+  CHECK (julianday(`expires_at`) IS NOT NULL AND julianday(`granted_at`) IS NOT NULL
+    AND julianday(`expires_at`) - julianday(`granted_at`) <= 365)
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `app_contact_consents_live`
+ON `app_contact_consents` (`install_id`, `tenant_id`, `stage`, `purpose`)
+WHERE `revoked_at` IS NULL;
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_consents_no_delete`
+BEFORE DELETE ON `app_contact_consents`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_consents_revoke_only`
+BEFORE UPDATE ON `app_contact_consents`
+WHEN OLD.`revoked_at` IS NOT NULL
+  OR NEW.`revoked_at` IS NULL
+  OR NEW.`consent_id` IS NOT OLD.`consent_id`
+  OR NEW.`install_id` IS NOT OLD.`install_id`
+  OR NEW.`tenant_id` IS NOT OLD.`tenant_id`
+  OR NEW.`stage` IS NOT OLD.`stage`
+  OR NEW.`purpose` IS NOT OLD.`purpose`
+  OR NEW.`granted_by` IS NOT OLD.`granted_by`
+  OR NEW.`granted_at` IS NOT OLD.`granted_at`
+  OR NEW.`expires_at` IS NOT OLD.`expires_at`
+BEGIN
+  SELECT RAISE(ABORT, 'revoke-only');
+END;
+--> statement-breakpoint
+-- Every admitted app read of an order recipient, written before anything is decrypted. Opaque ids
+-- only; append-only.
+CREATE TABLE `app_contact_access_audit` (
+  `audit_id` text PRIMARY KEY NOT NULL,
+  `install_id` text NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `purpose` text NOT NULL CHECK (`purpose` = 'fulfillment-shipping'),
+  `at` text NOT NULL,
+  `outcome` text NOT NULL CHECK (`outcome` = 'admitted')
+);
+--> statement-breakpoint
+CREATE INDEX `idx_app_contact_access_audit_quota` ON `app_contact_access_audit` (`install_id`, `tenant_id`, `at`);
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_access_audit_no_update`
+BEFORE UPDATE ON `app_contact_access_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;
+--> statement-breakpoint
+CREATE TRIGGER `app_contact_access_audit_no_delete`
+BEFORE DELETE ON `app_contact_access_audit`
+BEGIN
+  SELECT RAISE(ABORT, 'append-only');
+END;

package/apps/storefront/src/lib/customers/contactVault/contactAudit.ts

@@ -18,7 +18,8 @@ export function auditRecordIds(ids: readonly string[]): string | null {
   if (ids.length > AUDIT_RECORD_IDS_MAX) throw new Error("contact audit: too many record ids");
   return ids.length === 0 ? null : ids.join(",");
 }
-const HOUR_MS = 3_600_000;
+/** The quota window. A row counts while its `at` is strictly after `now - HOUR_MS`: one exactly an hour old no longer counts. */
+export const HOUR_MS = 3_600_000;
 
 export interface ContactActor {
   actorId: string;
@@ -88,6 +89,60 @@ export async function admitAudit(db: AuditDb, statement: AuditStatement): Promis
   }
 }
 
+/** Admitted app recipient reads per install and tenant per hour. */
+export const APP_CONTACT_READS_PER_HOUR = 300;
+export const APP_CONTACT_PURPOSE = "fulfillment-shipping";
+
+/**
+ * The app-access audit insert (`app_contact_access_audit`): the recipient read's admission and its
+ * only write. It inserts one row only when, at that instant, the install is active on the tenant
+ * holding `scope`, the assignment is the install's active assignment of the order, the order still
+ * stands at `eventVersion` (the version its releasability was computed at), a live consent covers
+ * (install, tenant, stage, purpose), and the install has fewer than
+ * {@link APP_CONTACT_READS_PER_HOUR} admitted rows on the tenant in the last hour.
+ */
+export function appAuditStatement(input: {
+  auditId: string;
+  installId: string;
+  tenantId: string;
+  stage: VaultStage;
+  orderId: string;
+  assignmentId: string;
+  eventVersion: number;
+  scope: string;
+  now: Date;
+}): AuditStatement {
+  const { auditId, installId, tenantId, stage, orderId, assignmentId, eventVersion, scope, now } = input;
+  const at = now.toISOString();
+  const hourAgo = new Date(now.getTime() - HOUR_MS).toISOString();
+  return {
+    sql: `INSERT INTO app_contact_access_audit (audit_id, install_id, tenant_id, stage, order_id, purpose, at, outcome)
+          SELECT ?, ?, ?, ?, ?, '${APP_CONTACT_PURPOSE}', ?, 'admitted'
+          WHERE EXISTS (SELECT 1 FROM app_installs AS ai
+                  WHERE ai.install_id = ? AND ai.tenant_id = ? AND ai.status = 'active'
+                    AND EXISTS (SELECT 1 FROM json_each(ai.scopes) WHERE json_each.value = ?))
+            AND EXISTS (SELECT 1 FROM fulfillment_assignments AS fa
+                  WHERE fa.assignment_id = ? AND fa.tenant_id = ? AND fa.stage = ? AND fa.order_id = ?
+                    AND fa.install_id = ? AND fa.state = 'active')
+            AND EXISTS (SELECT 1 FROM scrappy_commerce_orders AS o
+                  WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ? AND o.event_version = ?)
+            AND EXISTS (SELECT 1 FROM app_contact_consents AS c
+                  WHERE c.install_id = ? AND c.tenant_id = ? AND c.stage = ? AND c.purpose = '${APP_CONTACT_PURPOSE}'
+                    AND c.revoked_at IS NULL AND c.expires_at > ?)
+            AND (SELECT COUNT(*) FROM app_contact_access_audit AS q
+                  WHERE q.install_id = ? AND q.tenant_id = ? AND q.at > ?) < ?
+          RETURNING audit_id`,
+    params: [
+      auditId, installId, tenantId, stage, orderId, at,
+      installId, tenantId, scope,
+      assignmentId, tenantId, stage, orderId, installId,
+      tenantId, stage, orderId, eventVersion,
+      installId, tenantId, stage, at,
+      installId, tenantId, hourAgo, APP_CONTACT_READS_PER_HOUR,
+    ],
+  };
+}
+
 /** The same insert without RETURNING, for use inside a batch whose later statements check the row. */
 export function batchAuditStatement(statement: AuditStatement): AuditStatement {
   return { sql: statement.sql.replace(/\s*RETURNING audit_id$/, ""), params: statement.params };

package/apps/storefront/src/lib/fulfillment/admin/commerceDesk.ts

@@ -1,6 +1,7 @@
 /** Operational browser client. All authority and state changes remain in the authenticated APIs. */
 import type { FulfillmentView } from "../fulfillmentService.js";
 import { parseCommerceDeskApiRoot } from "./commerceDeskRouting.js";
+import { trackingUrlAllowed } from "../carrierEvidence.js";
 export function mountCommerceDesk(root: HTMLElement): void {
   const status = root.querySelector<HTMLElement>("[data-desk-status]")!;
   const rows = root.querySelector<HTMLElement>("[data-desk-orders]")!;
@@ -31,6 +32,30 @@ export function mountCommerceDesk(root: HTMLElement): void {
     parent.append(node);
     return node;
   }
+  /** Label and handoff state, carrier and tracking. The link is set only for an allowlisted https tracking URL. */
+  function renderShipment(shipment: NonNullable<FulfillmentView["shipment"]>, card: HTMLElement): void {
+    const block = document.createElement("div");
+    block.dataset.shipment = "";
+    card.append(block);
+    const state = text("p", `Label ${shipment.labelPurchaseState} · Handoff ${shipment.handoffState}`, block);
+    state.dataset.labelState = shipment.labelPurchaseState;
+    state.dataset.handoffState = shipment.handoffState;
+    if (shipment.carrier) {
+      const carrier = text("p", [shipment.carrier, shipment.service].filter(Boolean).join(" · "), block);
+      carrier.dataset.carrier = shipment.carrier;
+    }
+    if (shipment.trackingNumber) {
+      const tracking = text("a", `Tracking ${shipment.trackingNumber}`, block) as HTMLAnchorElement;
+      tracking.dataset.trackingNumber = shipment.trackingNumber;
+      tracking.rel = "noopener noreferrer";
+      tracking.referrerPolicy = "no-referrer";
+      if (trackingUrlAllowed(shipment.carrier, shipment.trackingUrl)) {
+        tracking.href = shipment.trackingUrl;
+        tracking.target = "_blank";
+        tracking.dataset.trackingUrl = shipment.trackingUrl;
+      }
+    }
+  }
   function render(order: FulfillmentView): void {
     const card = document.createElement("section");
     card.dataset.orderId = order.orderId;
@@ -43,6 +68,7 @@ export function mountCommerceDesk(root: HTMLElement): void {
       const owner = text("p", `Assigned to processor ${order.assignment.installId} · ${order.assignment.state}`, card);
       owner.dataset.assignmentState = order.assignment.state;
     }
+    if (order.shipment) renderShipment(order.shipment, card);
     const actions = order.batch
       ? [
           ["pick", "Confirm pick"],

package/apps/storefront/src/lib/fulfillment/admin/viewmodels/fulfillment.ts

@@ -21,11 +21,11 @@ import {
   type PublicCommerceEvent,
   type StockState,
 } from "@tot/public-runtime";
+import { trackingHostsFor } from "../../carrierEvidence.js";
 
 export const SCRAPPY_FULFILLMENT_PATH = "/scrappy-fulfillment";
 export const WORKSPACE_PAGE_LIMIT = 4;
 export const TEST_ADAPTER_QUOTE_MINOR = 640;
-export const TRACKING_HOSTS = ["tracking.example"] as const;
 
 export const WORKSPACE_QUEUES = ["ready", "held", "in_progress", "shipped"] as const;
 export type WorkspaceQueue = (typeof WORKSPACE_QUEUES)[number];
@@ -98,6 +98,7 @@ interface WorkspaceOrder {
   purchaseKey: string | null;
   purchaseId: string | null;
   labelCostMinor: number | null;
+  carrier: string | null;
   trackingNumber: string | null;
   trackingUrl: string | null;
   ownerDestination: string;
@@ -353,6 +354,7 @@ export function initialWorkspaceState(tenantId: string, stage: CommerceStage = "
     purchaseKey: extra.purchaseKey ?? null,
     purchaseId: extra.purchaseId ?? null,
     labelCostMinor: extra.labelCostMinor ?? null,
+    carrier: extra.carrier ?? null,
     trackingNumber: extra.trackingNumber ?? null,
     trackingUrl: extra.trackingUrl ?? null,
     ownerDestination: `dest-${id}`,
@@ -445,8 +447,9 @@ export function initialWorkspaceState(tenantId: string, stage: CommerceStage = "
         purchaseKey: "key-shipped",
         purchaseId: "test-key-shipped",
         labelCostMinor: TEST_ADAPTER_QUOTE_MINOR,
+        carrier: "UPS",
         trackingNumber: "TRK-ord-shipped",
-        trackingUrl: "https://tracking.example/label/ord-shipped",
+        trackingUrl: "https://www.ups.com/track?tracknum=TRKORDSHIPPED",
       }),
     ],
     events: [],
@@ -471,7 +474,7 @@ function projectOrder(state: WorkspaceState, order: WorkspaceOrder, actor: Comme
       actor,
       resource: scope,
       trackingUrl: order.trackingUrl,
-      allowedHosts: TRACKING_HOSTS,
+      allowedHosts: trackingHostsFor(order.carrier),
     });
     if (admitted.ok) trackingUrl = order.trackingUrl;
   }
@@ -740,8 +743,9 @@ function applyToOrder(state: WorkspaceState, order: WorkspaceOrder, command: Wor
     });
     if (!decision.admit) return refuse(decision.reason);
     order.fulfillment = "handed_off";
+    order.carrier = "UPS";
     order.trackingNumber = `TRK-${order.id}`;
-    order.trackingUrl = `https://tracking.example/label/${encodeURIComponent(order.id)}`;
+    order.trackingUrl = `https://www.ups.com/track?tracknum=${encodeURIComponent(order.id)}`;
     return finish({ ...blankResult(command.command, order.id, "admitted", "handed-off"), purchaseId: order.purchaseId });
   }
 

package/apps/storefront/src/lib/fulfillment/appShipmentEvidence.ts

@@ -0,0 +1,245 @@
+/**
+ * The processor's shipment-evidence contract: the closed request schema, the minimized response,
+ * the active-install and active-assignment predicate every app write carries in its first
+ * statement, and the idempotency record a replay returns.
+ */
+import type { LabelState } from "@tot/public-runtime";
+import { PROCESSOR_SCOPE } from "./assignmentStore.js";
+import type { SqlStatement } from "./store.js";
+import { CARRIER_SERVICE, TRACKING_NUMBER, parseCarrierCode, trackingUrlAllowed, type CarrierCode } from "./carrierEvidence.js";
+
+/** The calling install and the assignment it writes under. Every app write requires both. */
+export interface AppAssignmentBinding {
+  readonly installId: string;
+  readonly assignmentId: string;
+}
+
+export type AdultSignatureResult = "accepted" | "refused" | "absent";
+
+export interface LabelOutcomeEvidence {
+  kind: "label-outcome";
+  assignmentId: string;
+  purchaseId: string;
+  outcome: "purchased" | "unknown" | "voided";
+  carrier?: CarrierCode;
+  service?: string;
+  trackingNumber?: string;
+  trackingUrl?: string;
+  adultSignature: AdultSignatureResult;
+  expectedVersion?: number;
+}
+
+export interface HandoffEvidence {
+  kind: "handoff";
+  assignmentId: string;
+  purchaseId: string;
+  carrier: CarrierCode;
+  expectedVersion?: number;
+}
+
+export type ShipmentEvidence = LabelOutcomeEvidence | HandoffEvidence;
+
+export interface AppShipmentView {
+  orderId: string;
+  version: number;
+  label: LabelState;
+  handoff: "none" | "handed_off" | "unknown";
+  purchaseId: string;
+  carrier?: CarrierCode;
+  tracking?: { number: string; url: string };
+}
+
+export interface AppRefusalBody {
+  code: string;
+  error: string;
+  holds?: readonly string[];
+}
+
+export interface AppEvidenceResponse {
+  status: number;
+  body: AppShipmentView | AppRefusalBody;
+}
+
+/** The facts a label-outcome audit row stores, read back by the desk and the app view. */
+export interface StoredLabelFacts {
+  outcome: LabelOutcomeEvidence["outcome"] | null;
+  adultSignature: AdultSignatureResult;
+  carrier: CarrierCode | null;
+  service: string | null;
+  trackingNumber: string | null;
+  trackingUrl: string | null;
+}
+
+const OPAQUE = /^[A-Za-z0-9._:-]{1,128}$/;
+export const IDEMPOTENCY_KEY = /^[\x21-\x7e]{8,128}$/;
+const LABEL_KEYS = new Set([
+  "kind",
+  "assignmentId",
+  "purchaseId",
+  "outcome",
+  "carrier",
+  "service",
+  "trackingNumber",
+  "trackingUrl",
+  "adultSignature",
+  "expectedVersion",
+]);
+const HANDOFF_KEYS = new Set(["kind", "assignmentId", "purchaseId", "carrier", "expectedVersion"]);
+const PURCHASED_REQUIRES = ["carrier", "service", "trackingNumber", "trackingUrl", "adultSignature"] as const;
+
+function opaque(value: unknown): value is string {
+  return typeof value === "string" && OPAQUE.test(value) && !value.includes("@");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The body in the closed schema, or null (400 malformed): unknown keys, a null value, unknown carrier, unsafe URL. */
+export function parseShipmentEvidence(body: unknown): ShipmentEvidence | null {
+  if (!isRecord(body)) return null;
+  const keys = body.kind === "label-outcome" ? LABEL_KEYS : body.kind === "handoff" ? HANDOFF_KEYS : null;
+  if (!keys || Object.keys(body).some((key) => !keys.has(key))) return null;
+  if (Object.values(body).some((value) => value === null)) return null;
+  if (!opaque(body.assignmentId) || !opaque(body.purchaseId)) return null;
+  if (body.expectedVersion !== undefined && (!Number.isSafeInteger(body.expectedVersion) || Number(body.expectedVersion) < 0)) return null;
+  const expected = body.expectedVersion === undefined ? {} : { expectedVersion: Number(body.expectedVersion) };
+  if (body.kind === "handoff") {
+    const carrier = parseCarrierCode(body.carrier);
+    if (!carrier) return null;
+    return { kind: "handoff", assignmentId: body.assignmentId, purchaseId: body.purchaseId, carrier, ...expected };
+  }
+  if (body.outcome !== "purchased" && body.outcome !== "unknown" && body.outcome !== "voided") return null;
+  if (body.outcome === "purchased" && PURCHASED_REQUIRES.some((key) => body[key] === undefined)) return null;
+  const carrier = body.carrier === undefined ? undefined : parseCarrierCode(body.carrier);
+  if (carrier === null) return null;
+  if (body.service !== undefined && (typeof body.service !== "string" || !CARRIER_SERVICE.test(body.service))) return null;
+  if (body.trackingNumber !== undefined && (typeof body.trackingNumber !== "string" || !TRACKING_NUMBER.test(body.trackingNumber))) return null;
+  if (body.trackingUrl !== undefined && !trackingUrlAllowed(carrier, body.trackingUrl)) return null;
+  const adult = body.adultSignature ?? "absent";
+  if (adult !== "accepted" && adult !== "refused" && adult !== "absent") return null;
+  return {
+    kind: "label-outcome",
+    assignmentId: body.assignmentId,
+    purchaseId: body.purchaseId,
+    outcome: body.outcome,
+    adultSignature: adult,
+    ...(carrier ? { carrier } : {}),
+    ...(typeof body.service === "string" ? { service: body.service } : {}),
+    ...(typeof body.trackingNumber === "string" ? { trackingNumber: body.trackingNumber } : {}),
+    ...(typeof body.trackingUrl === "string" ? { trackingUrl: body.trackingUrl } : {}),
+    ...expected,
+  };
+}
+
+/** The label-outcome audit `to_state`: closed keys, absent facts omitted. */
+export function labelOutcomeRecord(evidence: LabelOutcomeEvidence): Record<string, string> {
+  return {
+    outcome: evidence.outcome,
+    adultSignature: evidence.adultSignature,
+    ...(evidence.carrier ? { carrier: evidence.carrier } : {}),
+    ...(evidence.service ? { service: evidence.service } : {}),
+    ...(evidence.trackingNumber ? { trackingNumber: evidence.trackingNumber } : {}),
+    ...(evidence.trackingUrl ? { trackingUrl: evidence.trackingUrl } : {}),
+  };
+}
+
+/** A stored label-outcome audit `to_state`, re-validated on read. Facts that fail their shape read as absent. */
+export function parseStoredLabelFacts(value: unknown): StoredLabelFacts | null {
+  if (!isRecord(value)) return null;
+  if (value.adultSignature !== "accepted" && value.adultSignature !== "refused" && value.adultSignature !== "absent") return null;
+  const carrier = parseCarrierCode(value.carrier);
+  const outcome = value.outcome === "purchased" || value.outcome === "unknown" || value.outcome === "voided" ? value.outcome : null;
+  return {
+    outcome,
+    adultSignature: value.adultSignature,
+    carrier,
+    service: typeof value.service === "string" && CARRIER_SERVICE.test(value.service) ? value.service : null,
+    trackingNumber: typeof value.trackingNumber === "string" && TRACKING_NUMBER.test(value.trackingNumber) ? value.trackingNumber : null,
+    trackingUrl: trackingUrlAllowed(carrier, value.trackingUrl) ? value.trackingUrl : null,
+  };
+}
+
+/** True when a recorded purchase carries exactly these facts. */
+export function sameLabelFacts(stored: StoredLabelFacts | null, evidence: LabelOutcomeEvidence): boolean {
+  return (
+    stored !== null &&
+    stored.adultSignature === evidence.adultSignature &&
+    stored.carrier === (evidence.carrier ?? null) &&
+    stored.service === (evidence.service ?? null) &&
+    stored.trackingNumber === (evidence.trackingNumber ?? null) &&
+    stored.trackingUrl === (evidence.trackingUrl ?? null)
+  );
+}
+
+/**
+ * SQL condition (no leading AND) every app write carries in statements[0]: the calling install is
+ * active on the host tenant with the processor scope, and the bound assignment of this order names
+ * it and is active.
+ */
+export function appWritePredicate(
+  binding: AppAssignmentBinding,
+  scope: { tenantId: string; stage: string; orderId: string },
+): SqlStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM app_installs AS ai
+        WHERE ai.install_id = ? AND ai.tenant_id = ? AND ai.status = 'active'
+          AND EXISTS (SELECT 1 FROM json_each(ai.scopes) WHERE json_each.value = '${PROCESSOR_SCOPE}')
+      ) AND EXISTS (
+        SELECT 1 FROM fulfillment_assignments AS fa
+        WHERE fa.assignment_id = ? AND fa.tenant_id = ? AND fa.stage = ? AND fa.order_id = ?
+          AND fa.install_id = ? AND fa.state = 'active'
+      )`,
+    params: [
+      binding.installId,
+      scope.tenantId,
+      binding.assignmentId,
+      scope.tenantId,
+      scope.stage,
+      scope.orderId,
+      binding.installId,
+    ],
+  };
+}
+
+const STATUS: Record<string, number> = {
+  malformed: 400,
+  invalid_token: 401,
+  scope_denied: 403,
+  denied: 403,
+  "not-assigned": 404,
+  unavailable: 503,
+};
+
+/** A refusal response: `{ code, error }`, plus `holds` on a handoff refusal. */
+export function appRefusal(code: string, holds?: readonly string[]): AppEvidenceResponse {
+  if (code === "invalid_token") return { status: 401, body: { error: "Unauthorized", code } };
+  const body: AppRefusalBody = holds && holds.length > 0 ? { code, error: code, holds: [...holds] } : { code, error: code };
+  return { status: STATUS[code] ?? 409, body };
+}
+
+/** The idempotency record: the response status and body a same-key, same-body retry returns. */
+export function idempotencyRecord(response: AppEvidenceResponse): string {
+  return JSON.stringify({ status: response.status, body: response.body });
+}
+
+/** A recorded response, or null when the record is not one this route wrote. */
+export function replayedResponse(recorded: unknown): AppEvidenceResponse | null {
+  if (!isRecord(recorded) || !Number.isSafeInteger(recorded.status) || !isRecord(recorded.body)) return null;
+  return { status: Number(recorded.status), body: recorded.body as unknown as AppShipmentView | AppRefusalBody };
+}
+
+/** The batch key insert: a plain INSERT, so a same-key race rolls the whole batch back. */
+export function idempotencyInsertStatement(input: {
+  installId: string;
+  key: string;
+  bodyHash: string;
+  response: AppEvidenceResponse;
+  now: string;
+}): SqlStatement {
+  return {
+    sql: `INSERT INTO idempotency_keys (install_id, idempotency_key, body_hash, response_body, created_at) VALUES (?, ?, ?, ?, ?)`,
+    params: [input.installId, input.key, input.bodyHash, idempotencyRecord(input.response), input.now],
+  };
+}

package/apps/storefront/src/lib/fulfillment/carrierEvidence.ts

@@ -0,0 +1,65 @@
+/**
+ * Carrier evidence a fulfillment processor reports: a closed set of canonical carrier codes and,
+ * per carrier, the tracking hosts a tracking URL may name. The same allowlist validates an app's
+ * write and gates the merchant desk's tracking link. Tracking URLs are never fetched.
+ */
+export const CARRIER_CODES = ["UPS", "FEDEX", "USPS", "DHL"] as const;
+export type CarrierCode = (typeof CARRIER_CODES)[number];
+
+export const CARRIER_TRACKING_HOSTS: Readonly<Record<CarrierCode, readonly string[]>> = {
+  UPS: ["www.ups.com"],
+  FEDEX: ["www.fedex.com"],
+  USPS: ["tools.usps.com"],
+  DHL: ["www.dhl.com"],
+};
+
+export const TRACKING_NUMBER = /^[A-Z0-9]{6,40}$/;
+export const CARRIER_SERVICE = /^[A-Z0-9_]{1,40}$/;
+export const TRACKING_URL_MAX = 2048;
+export const TRACKING_PART_MAX = 512;
+
+/** The canonical form every carrier comparison uses: trimmed and uppercased. */
+export function canonicalCarrier(value: string): string {
+  return value.trim().toUpperCase();
+}
+
+/** A supplied carrier as its canonical code, or null when it is not in the closed set. */
+export function parseCarrierCode(value: unknown): CarrierCode | null {
+  if (typeof value !== "string") return null;
+  const canonical = canonicalCarrier(value);
+  return (CARRIER_CODES as readonly string[]).includes(canonical) ? (canonical as CarrierCode) : null;
+}
+
+/** The tracking hosts allowed for `carrier`; none for a value outside the closed set. */
+export function trackingHostsFor(carrier: unknown): readonly string[] {
+  const code = parseCarrierCode(carrier);
+  return code ? CARRIER_TRACKING_HOSTS[code] : [];
+}
+
+/**
+ * True when `url` is an https URL on one of `carrier`'s tracking hosts: at most 2048 characters,
+ * printable ASCII only, the authority exactly an allowed host (so no userinfo, port or IP literal),
+ * no fragment, and a path and query of at most 512 characters each.
+ */
+export function trackingUrlAllowed(carrier: unknown, url: unknown): url is string {
+  if (typeof url !== "string" || url.length > TRACKING_URL_MAX) return false;
+  if (!/^[\x21-\x7e]+$/.test(url) || url.includes("#") || url.includes("\\")) return false;
+  if (!url.startsWith("https://")) return false;
+  const authority = url.slice("https://".length).split(/[/?]/, 1)[0] ?? "";
+  if (!trackingHostsFor(carrier).includes(authority)) return false;
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" || parsed.port !== "") return false;
+  if (parsed.host !== authority || parsed.hash !== "") return false;
+  return parsed.pathname.length <= TRACKING_PART_MAX && parsed.search.replace(/^\?/, "").length <= TRACKING_PART_MAX;
+}
+
+/** True when `carrier` is in either prohibited set, both compared in canonical form. */
+export function carrierProhibited(carrier: string, ...prohibited: ReadonlyArray<readonly string[]>): boolean {
+  const canonical = canonicalCarrier(carrier);
+  return prohibited.some((set) => set.some((item) => canonicalCarrier(item) === canonical));
+}