@openlup/platform 0.16.0 → 0.18.0

package/dist/catalog/sellableBundleHandler.d.ts

@@ -0,0 +1,46 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { BundleResponseSchema } from "./adminBindings.js";
+import type { SellableBundle } from "./contracts/bundleAvailability.js";
+import type { BundleAvailability } from "./bundleAvailability.js";
+import type { ActiveBundleComposition } from "./bundleCatalogReadPort.js";
+import type { BundleAvailabilityService } from "./bundleAvailabilityService.js";
+/**
+ * The public sellable-bundle feed handler, shaped after the reference catalog
+ * handler: GET-only, one
+ * port call, validate the body before sending, and never serve an unvalidated
+ * shape.
+ *
+ * It composes rather than computes twice: the availability service already folds
+ * one batched stock answer into the live compositions, and the pricing kernel
+ * turns the stored target price into per-component money. This module only decides
+ * what a storefront is allowed to see.
+ *
+ * A bundle whose money cannot be derived is DROPPED from the feed, not published
+ * with a guessed figure. Three cases reach that door — an unpriced component, an
+ * empty composition, and a target price the kernel refuses — and all three mean
+ * the same thing to a storefront: this is not sellable today. Publishing it with a
+ * partial price would put a number on a shelf that no order line could reproduce.
+ */
+export interface SellableBundleHandlerDeps {
+    availabilityService: BundleAvailabilityService;
+    /** Narrow the feed to one currency; omitted means every currency an operator priced. */
+    currency?: string;
+    enabled: boolean;
+}
+export declare function createSellableBundleHandlers({ responder, sellableBundleListResponseSchema, SELLABLE_BUNDLE_CONTRACT_VERSION }: {
+    responder: BffResponder;
+    sellableBundleListResponseSchema: BundleResponseSchema;
+    SELLABLE_BUNDLE_CONTRACT_VERSION: "catalog.sellable-bundle.v1";
+}): {
+    createSellableBundleHandler: (deps: SellableBundleHandlerDeps) => (req: HttpRequest, res: HttpResponse) => Promise<void>;
+};
+/**
+ * Derive the row a storefront sees, or `null` when the money cannot be stated.
+ *
+ * The allocator emits TWO lines for a quantity whose subtotal does not divide
+ * evenly, which is exactly why the feed carries lines rather than a unit price per
+ * component: `unitPrice x quantity === lineSubtotal` holds on every line, and the
+ * lines sum to the bundle's price with no remainder.
+ */
+export declare function toSellableBundle(composition: ActiveBundleComposition, availability: BundleAvailability): SellableBundle | null;

package/dist/catalog/sellableBundleHandler.js

@@ -0,0 +1,84 @@
+import { allocateBundleTargetPrice } from "@openlup/core/pricing";
+export function createSellableBundleHandlers({ responder, sellableBundleListResponseSchema, SELLABLE_BUNDLE_CONTRACT_VERSION }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    function createSellableBundleHandler(deps) {
+        return async function handler(req, res) {
+            if (req.method !== "GET") {
+                sendMethodNotAllowed(res, ["GET"]);
+                return;
+            }
+            if (!deps.enabled) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Bundle reads are disabled", {
+                    details: { reason: "feature_flag_disabled", featureFlag: "COMMERCE_BUNDLE_READ_ENABLED" },
+                });
+                return;
+            }
+            try {
+                const rows = await deps.availabilityService.describeActiveBundles(deps.currency ? { currency: deps.currency } : {});
+                const response = sellableBundleListResponseSchema.safeParse({
+                    contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION,
+                    bundles: rows
+                        .map((row) => toSellableBundle(row.composition, row.availability))
+                        .filter((bundle) => bundle !== null),
+                });
+                if (!response.success) {
+                    sendBffError(res, "INVALID_RESPONSE", "Sellable bundle feed returned an invalid shape");
+                    return;
+                }
+                sendBffSuccess(res, response.data, { contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION }, { cacheControl: "no-store" });
+            }
+            catch {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Sellable bundles are unavailable");
+            }
+        };
+    }
+    return { createSellableBundleHandler };
+}
+/**
+ * Derive the row a storefront sees, or `null` when the money cannot be stated.
+ *
+ * The allocator emits TWO lines for a quantity whose subtotal does not divide
+ * evenly, which is exactly why the feed carries lines rather than a unit price per
+ * component: `unitPrice x quantity === lineSubtotal` holds on every line, and the
+ * lines sum to the bundle's price with no remainder.
+ */
+export function toSellableBundle(composition, availability) {
+    if (composition.components.length === 0)
+        return null;
+    if (composition.components.some((component) => component.referenceUnitPriceMinor === null)) {
+        return null;
+    }
+    const allocation = allocateBundleTargetPrice({
+        components: composition.components.map((component) => ({
+            sku: component.sku,
+            quantity: component.quantity,
+            unitPriceMinor: component.referenceUnitPriceMinor,
+        })),
+        targetPriceMinor: composition.targetPriceMinor,
+    });
+    if (!allocation.ok)
+        return null;
+    // Basis points come from the per-component allocation, so a component split
+    // across two lines reports the same discount on both halves rather than two
+    // rounded figures that disagree.
+    const discountBpsBySku = new Map(allocation.components.map((component) => [component.sku, component.discountBps]));
+    return {
+        code: composition.code,
+        title: composition.title,
+        fulfillmentMode: composition.fulfillmentMode,
+        price: { amountMinor: composition.targetPriceMinor, currency: composition.currency },
+        components: allocation.lines.map((line) => ({
+            sku: line.sku,
+            quantity: line.quantity,
+            effectiveUnitPriceMinor: line.effectiveUnitPriceMinor,
+            lineSubtotalMinor: line.lineSubtotalMinor,
+            discountBps: discountBpsBySku.get(line.sku) ?? 0,
+        })),
+        availability: {
+            status: availability.status,
+            sellableNow: availability.sellableNow,
+            limitingSku: availability.limitingSku,
+            reasonCode: availability.reasonCode,
+        },
+    };
+}

package/dist/catalog/sellableSchemas.d.ts

@@ -0,0 +1,46 @@
+import { z } from "./validation.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export type { SellableCatalogItem, SellableCatalogProfile, SellableCatalogListResponse } from "./contracts/sellable.js";
+export declare const sellableCatalogItemSchema: z.ZodObject<{
+    sku: z.ZodString;
+    title: z.ZodString;
+    unitPrice: z.ZodObject<{
+        amountMinor: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strict>;
+    permittedPurchaseModes: z.ZodArray<z.ZodEnum<{
+        subscription: "subscription";
+        one_time: "one_time";
+    }>>;
+}, z.core.$strict>;
+export declare const sellableCatalogProfileSchema: z.ZodObject<{
+    id: z.ZodString;
+    brand: z.ZodString;
+    country: z.ZodString;
+    currency: z.ZodString;
+    locale: z.ZodString;
+    timezone: z.ZodString;
+}, z.core.$strict>;
+export declare const sellableCatalogListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"catalog.sellable.v1">;
+    profile: z.ZodObject<{
+        id: z.ZodString;
+        brand: z.ZodString;
+        country: z.ZodString;
+        currency: z.ZodString;
+        locale: z.ZodString;
+        timezone: z.ZodString;
+    }, z.core.$strict>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        title: z.ZodString;
+        unitPrice: z.ZodObject<{
+            amountMinor: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+        permittedPurchaseModes: z.ZodArray<z.ZodEnum<{
+            subscription: "subscription";
+            one_time: "one_time";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/catalog/sellableSchemas.js

@@ -0,0 +1,27 @@
+import { z } from "./validation.js";
+import { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+/** Minimal neutral storefront wire schema. */
+const sellableCatalogMoneySchema = z.object({
+    amountMinor: z.number().int().nonnegative(),
+    currency: z.string().regex(/^[A-Z]{3}$/),
+}).strict();
+export const sellableCatalogItemSchema = z.object({
+    sku: z.string().trim().min(1).max(128).regex(/^[a-zA-Z0-9._:-]+$/),
+    title: z.string().trim().min(1).max(160),
+    unitPrice: sellableCatalogMoneySchema,
+    permittedPurchaseModes: z.array(z.enum(["one_time", "subscription"])).min(1).max(2),
+}).strict();
+export const sellableCatalogProfileSchema = z.object({
+    id: z.string().trim().min(1).max(120),
+    brand: z.string().trim().min(1).max(160),
+    country: z.string().regex(/^[A-Z]{2}$/),
+    currency: z.string().regex(/^[A-Z]{3}$/),
+    locale: z.string().trim().min(2).max(35),
+    timezone: z.string().trim().min(1).max(80),
+}).strict();
+export const sellableCatalogListResponseSchema = z.object({
+    contractVersion: z.literal(SELLABLE_CATALOG_CONTRACT_VERSION),
+    profile: sellableCatalogProfileSchema,
+    items: z.array(sellableCatalogItemSchema).min(1),
+}).strict();

package/dist/catalog/sql.d.ts

@@ -0,0 +1,46 @@
+/** Sparse projections of canonical units, never an install chain. */
+export declare const BUNDLE_MIGRATIONS: readonly [{
+    readonly id: "20260812140000_sellable_bundle_catalog";
+    readonly catalogPath: "db/platform/migrations/20260812140000_sellable_bundle_catalog.sql";
+    readonly position: 16;
+    readonly sha256: "62fbf0910a3a7a2ee47e2d798933fe0a5a273fd1242cae7cc78ff237ba39e394";
+    readonly url: URL;
+}, {
+    readonly id: "20260812210000_bundle_operator_write_boundary";
+    readonly catalogPath: "db/platform/migrations/20260812210000_bundle_operator_write_boundary.sql";
+    readonly position: 19;
+    readonly sha256: "d0ec6674d7eedf4cd3ce0d8ccd7345ebe2f93da635316a68a6bd178ec55b2679";
+    readonly url: URL;
+}];
+/** Catalog foundation projections; install the complete canonical catalogue. */
+export declare const CATALOG_MIGRATIONS: readonly [{
+    readonly id: "20260807140000_read_parity_catalog";
+    readonly catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql";
+    readonly position: 1;
+    readonly sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea";
+    readonly url: URL;
+}, {
+    readonly id: "20260810120000_storefront_catalog_attributes";
+    readonly catalogPath: "db/platform/migrations/20260810120000_storefront_catalog_attributes.sql";
+    readonly position: 8;
+    readonly sha256: "2bf938f5d0076193557bea834f86dbd9bcb7f3e2de00f99fb91cc1229b93a14b";
+    readonly url: URL;
+}, {
+    readonly id: "20260827220000_catalog_document_revision_foundation";
+    readonly catalogPath: "db/platform/migrations/20260827220000_catalog_document_revision_foundation.sql";
+    readonly position: 58;
+    readonly sha256: "715e74d655b76d35b8a49e0d2a5625594a6c4856863f369cd1eadcd1fb1ae90e";
+    readonly url: URL;
+}, {
+    readonly id: "20260827220001_catalog_document_revision_foundation_validate";
+    readonly catalogPath: "db/platform/migrations/20260827220001_catalog_document_revision_foundation_validate.sql";
+    readonly position: 59;
+    readonly sha256: "f3cd7fb61dcebac1cf0468cf2d7c1f9dd036817ab0094c72864266e307b269de";
+    readonly url: URL;
+}, {
+    readonly id: "20260908100000_catalog_draft_foundation";
+    readonly catalogPath: "db/platform/migrations/20260908100000_catalog_draft_foundation.sql";
+    readonly position: 61;
+    readonly sha256: "ac0d614cdb2874df8fbdbbbda4f9455986ef95241fe1334b0b54a1fa6478ab2e";
+    readonly url: URL;
+}];

package/dist/catalog/sql.js

@@ -0,0 +1,13 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const BUNDLE_MIGRATIONS = [
+    { id: "20260812140000_sellable_bundle_catalog", catalogPath: "db/platform/migrations/20260812140000_sellable_bundle_catalog.sql", position: 16, sha256: "62fbf0910a3a7a2ee47e2d798933fe0a5a273fd1242cae7cc78ff237ba39e394", url: new URL("../../sql/20260812140000_sellable_bundle_catalog.sql", import.meta.url) },
+    { id: "20260812210000_bundle_operator_write_boundary", catalogPath: "db/platform/migrations/20260812210000_bundle_operator_write_boundary.sql", position: 19, sha256: "d0ec6674d7eedf4cd3ce0d8ccd7345ebe2f93da635316a68a6bd178ec55b2679", url: new URL("../../sql/20260812210000_bundle_operator_write_boundary.sql", import.meta.url) },
+];
+/** Catalog foundation projections; install the complete canonical catalogue. */
+export const CATALOG_MIGRATIONS = [
+    { id: "20260807140000_read_parity_catalog", catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql", position: 1, sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea", url: new URL("../../sql/20260807140000_read_parity_catalog.sql", import.meta.url) },
+    { id: "20260810120000_storefront_catalog_attributes", catalogPath: "db/platform/migrations/20260810120000_storefront_catalog_attributes.sql", position: 8, sha256: "2bf938f5d0076193557bea834f86dbd9bcb7f3e2de00f99fb91cc1229b93a14b", url: new URL("../../sql/20260810120000_storefront_catalog_attributes.sql", import.meta.url) },
+    { id: "20260827220000_catalog_document_revision_foundation", catalogPath: "db/platform/migrations/20260827220000_catalog_document_revision_foundation.sql", position: 58, sha256: "715e74d655b76d35b8a49e0d2a5625594a6c4856863f369cd1eadcd1fb1ae90e", url: new URL("../../sql/20260827220000_catalog_document_revision_foundation.sql", import.meta.url) },
+    { id: "20260827220001_catalog_document_revision_foundation_validate", catalogPath: "db/platform/migrations/20260827220001_catalog_document_revision_foundation_validate.sql", position: 59, sha256: "f3cd7fb61dcebac1cf0468cf2d7c1f9dd036817ab0094c72864266e307b269de", url: new URL("../../sql/20260827220001_catalog_document_revision_foundation_validate.sql", import.meta.url) },
+    { id: "20260908100000_catalog_draft_foundation", catalogPath: "db/platform/migrations/20260908100000_catalog_draft_foundation.sql", position: 61, sha256: "ac0d614cdb2874df8fbdbbbda4f9455986ef95241fe1334b0b54a1fa6478ab2e", url: new URL("../../sql/20260908100000_catalog_draft_foundation.sql", import.meta.url) },
+];

package/dist/catalog/validation.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/catalog/validation.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/dist/communications/accountingDocumentDelivery.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The sealed transport boundary for handing an accounting document to its recipient.
+ *
+ * The kernel exercises the whole capability up to this line: a document is owed, registered with
+ * whatever authority the market has, queued, claimed and settled against a receipt. What crosses
+ * the line is one opaque hand-off, and this adapter is the deliberately inert implementation of
+ * it -- deterministic, and leaving the installation by no route at all.
+ *
+ * It is FAIL CLOSED, and that is the whole design. An installation that has declared no delivery
+ * channel gets a refusal, never a silent success: a boundary whose default answer is "fine" is
+ * how a deployment discovers months later that nothing was ever handed to anyone.
+ */
+export type CapturedDocumentDeliveryCommand = {
+    readonly deliveryId: string;
+    readonly recipientReference: string;
+};
+export type CapturedDocumentDeliveryPort = {
+    deliver(command: CapturedDocumentDeliveryCommand): Promise<{
+        readonly receiptReference: string;
+    }>;
+};
+export type CapturedDocumentDeliveryResolution = {
+    readonly port: CapturedDocumentDeliveryPort;
+    readonly refused?: undefined;
+} | {
+    readonly port?: undefined;
+    readonly refused: string;
+};
+/** The one marker that opens the boundary. Anything else, including its absence, is a refusal. */
+export declare const CAPTURED_DOCUMENT_DELIVERY_CHANNEL = "captured";
+/**
+ * Resolve the boundary for one installation. The environment is the only input, and every path
+ * that is not an explicit declaration of the captured channel ends in a named refusal.
+ */
+export declare function resolveCapturedDocumentDelivery(env: Record<string, string | undefined>): CapturedDocumentDeliveryResolution;

package/dist/communications/accountingDocumentDelivery.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+/** The one marker that opens the boundary. Anything else, including its absence, is a refusal. */
+export const CAPTURED_DOCUMENT_DELIVERY_CHANNEL = "captured";
+const CHANNEL_KEY = "PLATFORM_DOCUMENT_DELIVERY_CHANNEL";
+const reference = (command) => `captured:${createHash("sha256")
+    .update(`${command.deliveryId}::${command.recipientReference}`)
+    .digest("hex")
+    .slice(0, 32)}`;
+/**
+ * Resolve the boundary for one installation. The environment is the only input, and every path
+ * that is not an explicit declaration of the captured channel ends in a named refusal.
+ */
+export function resolveCapturedDocumentDelivery(env) {
+    const declared = env[CHANNEL_KEY]?.trim().toLowerCase() ?? "";
+    if (declared === "")
+        return { refused: "document_delivery_channel_undeclared" };
+    if (declared !== CAPTURED_DOCUMENT_DELIVERY_CHANNEL) {
+        return { refused: "document_delivery_channel_unsupported" };
+    }
+    return {
+        port: {
+            async deliver(command) {
+                if (typeof command.deliveryId !== "string" || command.deliveryId.trim() === "") {
+                    throw new Error("document_delivery_command_invalid");
+                }
+                if (typeof command.recipientReference !== "string" || command.recipientReference.trim() === "") {
+                    throw new Error("document_delivery_recipient_missing");
+                }
+                return { receiptReference: reference(command) };
+            },
+        },
+    };
+}

package/dist/communications/authEmailError.d.ts

@@ -0,0 +1,5 @@
+/** Typed refusal used by public/default composition when product copy is absent. */
+export declare class AuthEmailContentUnavailableError extends Error {
+    readonly code = "auth_email_content_unavailable";
+    constructor();
+}

package/dist/communications/authEmailError.js

@@ -0,0 +1,8 @@
+/** Typed refusal used by public/default composition when product copy is absent. */
+export class AuthEmailContentUnavailableError extends Error {
+    code = "auth_email_content_unavailable";
+    constructor() {
+        super("Auth email content unavailable");
+        this.name = "AuthEmailContentUnavailableError";
+    }
+}

package/dist/communications/authEmailPorts.d.ts

@@ -0,0 +1,2 @@
+export type * from "./contracts/authEmail.js";
+export { AuthEmailContentUnavailableError } from "./authEmailError.js";

package/dist/communications/authEmailPorts.js

@@ -0,0 +1 @@
+export { AuthEmailContentUnavailableError } from "./authEmailError.js";

package/dist/communications/authSendEmailHook.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The Auth Send Email hook. Live, not a candidate.
+ *
+ * Supabase Auth targets `/api/auth-send-email` in staging and production - the
+ * hooks were repointed here on 2026-09-04 and the hosted Edge Functions were
+ * undeployed the same day, so this owns the raw-stream, signature, render/send
+ * and ledger contract for every magic link, recovery and confirmation the
+ * product sends. Rotating its signing secret is a human-only control-plane act.
+ */
+import type { HttpRequest as VercelRequest, HttpResponse as VercelResponse } from "../http/index.js";
+import type { EmailBrand, EmailRenderer } from "./contracts/email.js";
+import { type AuthEmailContentPort, type AuthEmailPersistencePort, type AuthEmailTransportPort } from "./authEmailPorts.js";
+export interface AuthSendEmailHookDeps {
+    transport: AuthEmailTransportPort;
+    persistence: AuthEmailPersistencePort;
+    content: AuthEmailContentPort;
+    fromEmail: string;
+    hookSecret: string;
+    authServiceUrl: string;
+    /** App-layer defaults injected at composition; no brand/env ownership lives here. */
+    defaultOrigin: string;
+    productionEmailHosts: string[];
+    legacyBaseUrl?: string | null;
+    emailBrandForOrigin: (origin: string) => EmailBrand;
+    defaultSandboxRecipient: string;
+    defaultRedirectTo?: string;
+    env: Record<string, string | undefined>;
+    now?: () => number;
+}
+export interface AuthEmailHookHost {
+    renderEmail: EmailRenderer;
+    readObservedEnvironment: (env: Record<string, string | undefined>) => string;
+    readHiddenPreviewEnabled: (env: Record<string, string | undefined>) => boolean;
+}
+export declare function createAuthSendEmailHookCandidate(deps: AuthSendEmailHookDeps, host: AuthEmailHookHost): (req: VercelRequest, res: VercelResponse) => Promise<void>;

package/dist/communications/authSendEmailHook.js

@@ -0,0 +1,250 @@
+import { readEmailOriginConfiguration, resolveEmailOrigin } from "./originPolicy.js";
+import { buildAuthVerifyUrl } from "../identity/index.js";
+import { AuthEmailContentUnavailableError, } from "./authEmailPorts.js";
+import { guardAuthEmailTransport } from "./emailEgress.js";
+import { verifyStandardWebhookSignature } from "./standardWebhooks.js";
+const CORS_HEADERS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-headers": "authorization, x-client-info, apikey, content-type",
+};
+const KNOWN_ACTION_TYPES = new Set([
+    "magiclink", "signup", "recovery", "invite", "email_change",
+    "email_change_current", "email_change_new", "email",
+]);
+function json(res, status, body) {
+    for (const [key, value] of Object.entries(CORS_HEADERS))
+        res.setHeader(key, value);
+    res.status(status).json(body);
+}
+function hookError(res, httpCode, message) {
+    json(res, httpCode, { error: { http_code: httpCode, message } });
+}
+async function readRawBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+function resolveRedirectTarget(data, defaultRedirectTo) {
+    if (data?.redirect_to?.trim())
+        return { redirectTo: data.redirect_to, source: "redirect_to" };
+    if (data?.site_url?.trim())
+        return { redirectTo: data.site_url, source: "site_url" };
+    return { redirectTo: defaultRedirectTo ?? "", source: "default_redirect" };
+}
+/**
+ * An email carries no base URL, so a relative action link is not a degraded
+ * link - it is an unclickable one. The Edge runtime supplied this origin for
+ * free; a Node deployment must be configured with it, and one that is not must
+ * refuse rather than send mail whose only working path is the OTP fallback.
+ */
+function absoluteAuthServiceUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+function uuidOrNull(value) {
+    return value && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+        ? value
+        : null;
+}
+function deliveryMode(result, env, recipient, defaultSandboxRecipient) {
+    // Preserve the existing Auth-hook audit vocabulary even though the Node
+    // transport's lower-level egress seam uses a richer set of route names.
+    if (result.outcome.egressMode === "production")
+        return "standard";
+    if ((env.EMAIL_DELIVERY_PROFILE ?? "").trim().toLowerCase() !== "production_like")
+        return "standard";
+    const sandboxRecipients = parseEmailList(env.EMAIL_SANDBOX_RECIPIENTS ?? env.COMMS_SANDBOX_SINK_ADDRESS ?? defaultSandboxRecipient);
+    return result.outcome.egressMode === "sandbox_sink"
+        || (result.outcome.adminDisabled === true && sandboxRecipients.has(recipient.trim().toLowerCase()))
+        ? "sandbox_recipient"
+        : "production_like_real";
+}
+function parseEmailList(value) {
+    return new Set((value ?? "")
+        .split(/[,\s;]+/)
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean));
+}
+function selectFromEmail(deps, recipient) {
+    const env = deps.env;
+    if ((env.EMAIL_DELIVERY_PROFILE ?? "").trim().toLowerCase() !== "production_like")
+        return deps.fromEmail;
+    const sandboxRecipients = parseEmailList(env.EMAIL_SANDBOX_RECIPIENTS ?? env.COMMS_SANDBOX_SINK_ADDRESS ?? deps.defaultSandboxRecipient);
+    if (sandboxRecipients.has(recipient.trim().toLowerCase()))
+        return deps.fromEmail;
+    return env.EMAIL_REAL_DELIVERY_FROM_EMAIL?.trim()
+        || env.AUTH_EMAIL_REAL_DELIVERY_FROM_EMAIL?.trim()
+        || deps.fromEmail;
+}
+function validateAuthEmailRedirectOrigin(deps, redirectTo, host) {
+    const env = deps.env;
+    const originConfiguration = readEmailOriginConfiguration(env, {
+        defaultOrigin: deps.defaultOrigin,
+        productionEmailHosts: deps.productionEmailHosts,
+    });
+    const environment = env.EMAIL_ENVIRONMENT ?? host.readObservedEnvironment(env);
+    const configured = resolveEmailOrigin({
+        ...originConfiguration,
+        explicitBaseUrl: env.APP_BASE_URL?.trim() || deps.legacyBaseUrl,
+        customerAuthRedirectOrigin: env.CUSTOMER_AUTH_REDIRECT_ORIGIN,
+        siteUrl: env.SITE_URL,
+        hiddenPreviewEnabled: host.readHiddenPreviewEnabled(env),
+        environment,
+    });
+    if (configured.ok === false)
+        return { ok: false, error: configured.error };
+    const redirect = resolveEmailOrigin({
+        ...originConfiguration,
+        explicitBaseUrl: redirectTo,
+        hiddenPreviewEnabled: host.readHiddenPreviewEnabled(env),
+        environment,
+    });
+    if (redirect.ok === false)
+        return { ok: false, error: redirect.error };
+    return {
+        ok: true,
+        environment: configured.resolved.environment,
+        origin: redirect.origin,
+        production: configured.resolved.production,
+    };
+}
+function persistenceOutcome(result) {
+    return {
+        ok: result.outcome.ok,
+        messageId: result.outcome.messageId,
+        providerError: result.outcome.providerError,
+        aborted: result.outcome.aborted,
+        skipReason: result.outcome.adminDisabled === true
+            ? "admin_disabled"
+            : result.outcome.suppressed === "drop" ? "egress_suppressed" : null,
+    };
+}
+export function createAuthSendEmailHookCandidate(deps, host) {
+    return async function authSendEmailHookCandidate(req, res) {
+        if (req.method === "OPTIONS") {
+            for (const [key, value] of Object.entries(CORS_HEADERS))
+                res.setHeader(key, value);
+            res.status(200).send("ok");
+            return;
+        }
+        if (req.method !== "POST")
+            return hookError(res, 405, "Method not allowed");
+        if (!deps.hookSecret) {
+            console.error("[auth-send-email] SEND_EMAIL_HOOK_SECRET not configured");
+            return hookError(res, 500, "Hook secret not configured");
+        }
+        if (!absoluteAuthServiceUrl(deps.authServiceUrl)) {
+            console.error("[auth-send-email] auth service URL not configured");
+            return hookError(res, 500, "Auth service URL not configured");
+        }
+        let rawBody;
+        try {
+            rawBody = await readRawBody(req);
+        }
+        catch {
+            return hookError(res, 400, "Invalid JSON payload");
+        }
+        const valid = await verifyStandardWebhookSignature({
+            headers: {
+                id: typeof req.headers["webhook-id"] === "string" ? req.headers["webhook-id"] : null,
+                timestamp: typeof req.headers["webhook-timestamp"] === "string" ? req.headers["webhook-timestamp"] : null,
+                signature: typeof req.headers["webhook-signature"] === "string" ? req.headers["webhook-signature"] : null,
+            },
+            rawBody,
+            secret: deps.hookSecret,
+            now: deps.now,
+        });
+        if (!valid)
+            return hookError(res, 401, "Invalid signature");
+        let payload;
+        try {
+            payload = JSON.parse(rawBody);
+        }
+        catch {
+            return hookError(res, 400, "Invalid JSON payload");
+        }
+        const email = payload.user?.email;
+        const data = payload.email_data;
+        const actionType = data?.email_action_type;
+        const tokenHash = data?.token_hash;
+        const redirect = resolveRedirectTarget(data, deps.defaultRedirectTo);
+        if (!email || !actionType || !tokenHash)
+            return hookError(res, 400, "Missing user email or email_data");
+        const redirectPolicy = validateAuthEmailRedirectOrigin(deps, redirect.redirectTo, host);
+        if (redirectPolicy.ok === false)
+            return hookError(res, 500, `Email origin policy failed: ${redirectPolicy.error}`);
+        if (!KNOWN_ACTION_TYPES.has(actionType))
+            console.warn("[auth-send-email] unknown email_action_type:", actionType);
+        let content;
+        try {
+            content = deps.content.buildAuthEmailContent({
+                actionType, userMetadata: payload.user?.user_metadata, redirectTo: redirect.redirectTo,
+                actionLink: buildAuthVerifyUrl(deps.authServiceUrl, actionType, tokenHash, redirect.redirectTo),
+                otp: data?.token ?? null,
+            });
+        }
+        catch (error) {
+            if (error instanceof AuthEmailContentUnavailableError)
+                return hookError(res, 503, error.message);
+            throw error;
+        }
+        const rendered = host.renderEmail({
+            brand: deps.emailBrandForOrigin(redirectPolicy.origin), locale: content.locale,
+            subject: content.subject, preheader: content.preheader, blocks: content.blocks,
+        });
+        const sendAttemptId = crypto.randomUUID();
+        const authUserId = uuidOrNull(payload.user?.id);
+        const aggregateId = authUserId ?? crypto.randomUUID();
+        // Match the hosted hook's ordering: persistence/control failure is a
+        // retryable refusal before any email side effect, never a post-send false 5xx.
+        const templateSlug = `auth-${actionType}`;
+        const enabled = await deps.persistence.isTemplateEnabled(templateSlug, new AbortController().signal);
+        const sendResult = enabled
+            ? await guardAuthEmailTransport(deps.transport).send({
+                sender: selectFromEmail(deps, email), recipient: email,
+                subject: rendered.subject, html: rendered.html, text: rendered.text,
+            })
+            : {
+                outcome: { ok: true, messageId: null, providerError: null, aborted: false, adminDisabled: true },
+                providerResponse: { skipped: "admin_disabled" },
+            };
+        const mode = deliveryMode(sendResult, deps.env, email, deps.defaultSandboxRecipient);
+        const originMetadata = {
+            emailBaseUrl: redirectPolicy.origin,
+            emailOriginSource: redirect.source,
+            emailEnvironment: redirectPolicy.environment,
+        };
+        await deps.persistence.recordSend({
+            templateSlug,
+            recipientEmail: email,
+            authUserId,
+            aggregateId,
+            dedupeKey: `auth-send-email:${actionType}:${sendAttemptId}`,
+            providerKind: deps.transport.providerKind,
+            outcome: persistenceOutcome(sendResult),
+            providerResponse: sendResult.providerResponse,
+            metadata: {
+                ...originMetadata,
+                authEmailDeliveryMode: mode,
+                deliveryMode: mode,
+                triggerSource: "auth-send-email",
+                triggerReason: actionType,
+                providerKind: deps.transport.providerKind,
+                sendAttemptId,
+                aggregateType: "auth_user",
+                aggregateId,
+            },
+        });
+        if (!sendResult.outcome.ok) {
+            console.error("[auth-send-email] transport send failed:", sendResult.outcome.providerError);
+            return hookError(res, 502, "Email delivery failed");
+        }
+        json(res, 200, {});
+    };
+}