@cosmicdrift/kumiko-bundled-features 0.393.0 → 0.394.0

package/dist/subscription-paddle/plan-switch-methods.js

@@ -0,0 +1,114 @@
+// Paddle in-app plan switch (preview + apply) and retrieveSubscription.
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { paddleSubscriptionPath } from "./checkout-methods.js";
+import { PaddleHttpError } from "./client.js";
+import { paddleAmountSchema } from "./price-methods.js";
+import { mapPaddleSubscriptionState, paddleSubscriptionSchema } from "./subscription-state.js";
+import { signTenantBinding } from "./tenant-binding.js";
+const NOT_FOUND = 404;
+function parseAmount(amount) {
+    return Number.parseInt(amount, 10);
+}
+const previewResponseSchema = z.object({
+    data: z.object({
+        currency_code: z.string(),
+        immediate_transaction: z
+            .object({
+            details: z.object({
+                totals: z.object({
+                    grand_total: paddleAmountSchema,
+                    tax: paddleAmountSchema,
+                    currency_code: z.string().nullish(),
+                }),
+            }),
+        })
+            .nullish(),
+        recurring_transaction_details: z
+            .object({
+            // `total` is the full period price incl. tax; `grand_total` is already
+            // reduced by credit, so it would understate the recurring price.
+            totals: z.object({
+                total: paddleAmountSchema.nullish(),
+                tax: paddleAmountSchema.nullish(),
+            }),
+        })
+            .nullish(),
+        update_summary: z.object({ credit: z.object({ amount: paddleAmountSchema }) }).nullish(),
+    }),
+});
+function changePlanBody(targetPriceId) {
+    return {
+        items: [{ price_id: targetPriceId, quantity: 1 }],
+        proration_billing_mode: "prorated_immediately",
+    };
+}
+export function createPaddlePreviewPlanSwitch(runtime, now) {
+    return async (ctx, options) => {
+        const { data } = previewResponseSchema.parse(await runtime.call(ctx, {
+            method: "PATCH",
+            path: `${paddleSubscriptionPath(options.providerSubscriptionId)}/preview`,
+            body: changePlanBody(options.targetPriceId),
+        }));
+        const totals = data.immediate_transaction?.details.totals;
+        const recurring = data.recurring_transaction_details?.totals;
+        return {
+            amountDueNow: totals ? parseAmount(totals.grand_total) : 0,
+            tax: totals ? parseAmount(totals.tax) : null,
+            currency: (totals?.currency_code ?? data.currency_code).toLowerCase(),
+            credit: data.update_summary ? parseAmount(data.update_summary.credit.amount) : 0,
+            ...(recurring?.total != null && {
+                recurringAmount: parseAmount(recurring.total),
+                recurringTax: recurring.tax != null ? parseAmount(recurring.tax) : null,
+            }),
+            effectiveAt: Temporal.Instant.fromEpochMilliseconds(now()).toString(),
+        };
+    };
+}
+// The switch itself arrives later as a subscription.updated webhook;
+// prevent_change keeps the old plan if the immediate charge fails. PATCH
+// replaces custom_data as a whole, so the tenant binding is sent again.
+export function createPaddleApplyPlanSwitch(runtime) {
+    return async (ctx, options) => {
+        const bindingKey = await runtime.tenantBindingKey(ctx);
+        await runtime.call(ctx, {
+            method: "PATCH",
+            path: paddleSubscriptionPath(options.providerSubscriptionId),
+            body: {
+                ...changePlanBody(options.targetPriceId),
+                on_payment_failure: "prevent_change",
+                custom_data: {
+                    tenantId: options.tenantId,
+                    tenantBinding: signTenantBinding(bindingKey, options.tenantId),
+                    ...(options.consentId && { consentId: options.consentId }),
+                },
+            },
+        });
+    };
+}
+const subscriptionResponseSchema = z.object({ data: paddleSubscriptionSchema });
+export function createPaddleRetrieveSubscription(runtime, options) {
+    return async (ctx, providerSubscriptionId) => {
+        let raw;
+        try {
+            raw = await runtime.call(ctx, {
+                method: "GET",
+                path: paddleSubscriptionPath(providerSubscriptionId),
+            });
+        }
+        catch (error) {
+            if (error instanceof PaddleHttpError && error.status === NOT_FOUND)
+                return null;
+            throw error;
+        }
+        const { data: sub } = subscriptionResponseSchema.parse(raw);
+        const state = mapPaddleSubscriptionState(sub, options.priceToTier);
+        if (!state)
+            return null;
+        return {
+            providerCustomerId: sub.customer_id,
+            providerSubscriptionId: sub.id,
+            ...state,
+        };
+    };
+}

package/dist/subscription-paddle/price-methods.d.ts

@@ -0,0 +1,15 @@
+import { type ProviderPrice } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
+/** Paddle sends amounts as integer strings in the smallest currency unit. */
+export declare const paddleAmountSchema: z.ZodString;
+export type PaddlePriceCache = {
+    readonly get: (priceId: string) => ProviderPrice | undefined;
+    readonly set: (priceId: string, price: ProviderPrice) => void;
+};
+export type PaddlePriceCacheOptions = {
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+};
+export declare function createPaddlePriceCache({ ttlMs, now, }?: PaddlePriceCacheOptions): PaddlePriceCache;
+export declare function createPaddleRetrievePrices(runtime: PaddleCtxRuntime, cache: PaddlePriceCache): PaddlePluginMethod<"retrievePrices">;

package/dist/subscription-paddle/price-methods.js

@@ -0,0 +1,105 @@
+// Paddle price lookup for the billing-plans catalog: one batched request for all
+// cache misses, cached per price id.
+import { KNOWN_RECURRING_INTERVALS, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+const PRICES_PER_REQUEST = 200;
+/** Paddle sends amounts as integer strings in the smallest currency unit. */
+export const paddleAmountSchema = z.string().regex(/^-?\d+$/);
+const customDataSchema = z.record(z.string(), z.unknown()).nullish();
+const paddlePriceSchema = z.object({
+    id: z.string().min(1),
+    unit_price: z.object({ amount: paddleAmountSchema, currency_code: z.string() }),
+    billing_cycle: z.object({ interval: z.string(), frequency: z.number() }).nullable(),
+    status: z.string(),
+    custom_data: customDataSchema,
+    product: z.object({ custom_data: customDataSchema }).nullish(),
+});
+const pricesResponseSchema = z.object({ data: z.array(paddlePriceSchema) });
+function stringEntries(customData) {
+    return Object.entries(customData ?? {}).flatMap(([key, value]) => {
+        if (typeof value === "string")
+            return [[key, value]];
+        if (typeof value === "number")
+            return [[key, String(value)]];
+        return [];
+    });
+}
+// Price custom data wins over the product's.
+function metadataOf(price) {
+    return Object.fromEntries([
+        ...stringEntries(price.product?.custom_data),
+        ...stringEntries(price.custom_data),
+    ]);
+}
+function mapPaddlePrice(price) {
+    const base = {
+        priceId: price.id,
+        unitAmount: Number.parseInt(price.unit_price.amount, 10),
+        currency: price.unit_price.currency_code.toLowerCase(),
+        active: price.status === "active",
+        metadata: metadataOf(price),
+    };
+    const cycle = price.billing_cycle;
+    if (!cycle)
+        return { ...base, interval: null, intervalCount: 1 };
+    const interval = KNOWN_RECURRING_INTERVALS.find((known) => known === cycle.interval) ?? null;
+    return { ...base, interval, intervalCount: interval ? cycle.frequency : null };
+}
+// Keyed by price id alone: ids are unique per account and a cache hit must not
+// trigger an audited secret read on every billing-plans render. Failed lookups
+// are never cached.
+export function createPaddlePriceCache({ ttlMs = 600_000, now = () => Temporal.Now.instant().epochMilliseconds, } = {}) {
+    const store = new Map();
+    return {
+        get: (priceId) => {
+            const entry = store.get(priceId);
+            if (!entry)
+                return undefined;
+            if (entry.expiresAt <= now()) {
+                store.delete(priceId);
+                return undefined;
+            }
+            return entry.price;
+        },
+        set: (priceId, price) => {
+            store.set(priceId, { price, expiresAt: now() + ttlMs });
+        },
+    };
+}
+function chunked(items, size) {
+    const chunks = [];
+    for (let start = 0; start < items.length; start += size) {
+        chunks.push(items.slice(start, start + size));
+    }
+    return chunks;
+}
+async function fillPriceCache(runtime, cache, ctx, priceIds) {
+    const misses = [...new Set(priceIds.filter((priceId) => cache.get(priceId) === undefined))];
+    const settled = await Promise.allSettled(chunked(misses, PRICES_PER_REQUEST).map(async (ids) => pricesResponseSchema.parse(await runtime.call(ctx, {
+        method: "GET",
+        path: "/prices",
+        query: {
+            id: ids.join(","),
+            include: "product",
+            status: "active,archived",
+            per_page: String(PRICES_PER_REQUEST),
+        },
+    }))));
+    for (const outcome of settled) {
+        if (outcome.status === "fulfilled") {
+            for (const price of outcome.value.data)
+                cache.set(price.id, mapPaddlePrice(price));
+        }
+        else {
+            const message = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            ctx.obs.log?.warn("subscription-paddle: price lookup failed", { message });
+        }
+    }
+}
+export function createPaddleRetrievePrices(runtime, cache) {
+    return async (ctx, priceIds) => {
+        await fillPriceCache(runtime, cache, ctx, priceIds);
+        return priceIds.flatMap((priceId) => cache.get(priceId) ?? []);
+    };
+}

package/dist/subscription-paddle/runtime.d.ts

@@ -0,0 +1,42 @@
+import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { type ConfigKeyHandle, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { type PaddleRequest, type PaddleSend } from "./client.ts";
+import { type PaddleEnvironment } from "./constants.ts";
+export type PaddlePluginMethod<TName extends keyof SubscriptionProviderPlugin> = NonNullable<SubscriptionProviderPlugin[TName]>;
+export type PaddleFallbacks = {
+    readonly apiKey?: string;
+    readonly webhookSecret?: string;
+    readonly tenantBindingKey?: string;
+    readonly clientToken?: string;
+};
+export type PaddleRuntimeDeps = {
+    readonly apiKeyHandle: ConfigKeyHandle<"text">;
+    readonly webhookSecretHandle: ConfigKeyHandle<"text">;
+    readonly tenantBindingKeyHandle: ConfigKeyHandle<"text">;
+    readonly clientTokenHandle: ConfigKeyHandle<"text">;
+    readonly billingLiveHandle: ConfigKeyHandle<"boolean">;
+    readonly environmentHandle: ConfigKeyHandle<"select">;
+    readonly send: PaddleSend;
+    readonly fallback: PaddleFallbacks;
+};
+export type PaddleCtxRuntime = {
+    readonly call: (ctx: HandlerContext, request: PaddleRequest) => Promise<unknown>;
+    readonly assertBillingLive: (ctx: HandlerContext, handlerName?: string) => Promise<void>;
+    readonly isBillingEnabled: (ctx: HandlerContext) => Promise<boolean>;
+    readonly tenantBindingKey: (ctx: HandlerContext) => Promise<string>;
+};
+export type PaddleWebhookRuntime = {
+    readonly resolveWebhookSecret: (systemSecrets?: SecretsContext) => Promise<string>;
+    readonly resolveTenantBindingKey: (systemSecrets?: SecretsContext) => Promise<string>;
+};
+export type PaddleCheckoutConfig = {
+    readonly clientToken: string | null;
+    readonly environment: PaddleEnvironment;
+};
+export type PaddleRuntimes = {
+    readonly ctx: PaddleCtxRuntime;
+    readonly webhook: PaddleWebhookRuntime;
+    readonly readCheckoutConfig: (ctx: Pick<HandlerContext, "config">) => Promise<PaddleCheckoutConfig>;
+};
+export declare function createPaddleRuntimes(deps: PaddleRuntimeDeps): PaddleRuntimes;

package/dist/subscription-paddle/runtime.js

@@ -0,0 +1,109 @@
+// Call-time key/flag resolution for the subscription-paddle plugin, mirroring
+// subscription-stripe/runtime.ts: credentials come from backing:"secrets" config
+// keys under SYSTEM_TENANT_ID, so rotation and go-live need no redeploy.
+// The factory options survive as env-bridge fallbacks.
+//
+// Two read paths: post-tenant handlers read the key audited through the
+// HandlerContext; the pre-tenant webhook reads secrets un-audited from the
+// system SecretsContext the foundation passes in.
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import { createPaddleHttp } from "./client.js";
+import { PADDLE_BASE_URLS, PaddleEnvironments, SUBSCRIPTION_PADDLE_FEATURE, } from "./constants.js";
+// backing:"secrets" values are stored JSON-serialized, so the store read has to
+// be parsed back; the env fallback is a plain string and stays raw. The error
+// must not carry the input: the JSON parser's own message would repeat the
+// credential into logs and, for webhooks, into the 401 body.
+function parseStoredSecret(raw) {
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    const parsed = parseJsonSafe(raw, undefined);
+    if (parsed === undefined) {
+        throw new Error("subscription-paddle credential (backing:secrets) is not valid JSON");
+    }
+    return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
+}
+function hintFor(shortName) {
+    return `Set it via config:write:set on \`${SUBSCRIPTION_PADDLE_FEATURE}:config:${shortName}\` (or seed it from the matching PADDLE_* variable during the env bridge).`;
+}
+function environmentOf(value) {
+    return value === PaddleEnvironments.live ? PaddleEnvironments.live : PaddleEnvironments.sandbox;
+}
+export function createPaddleRuntimes(deps) {
+    const http = createPaddleHttp(deps.send);
+    async function ctxSecret(ctx, handle, fallback, shortName) {
+        let value;
+        if (ctx.services.secrets) {
+            const got = await requireSecretsContext({ secrets: ctx.services.secrets, user: ctx.user }, SUBSCRIPTION_PADDLE_FEATURE).get(SYSTEM_TENANT_ID, handle.name);
+            value = parseStoredSecret(got?.reveal());
+        }
+        if (!value && fallback && fallback.length > 0)
+            value = fallback;
+        if (!value) {
+            throw new UnconfiguredError({
+                feature: SUBSCRIPTION_PADDLE_FEATURE,
+                key: handle.name,
+                hint: hintFor(shortName),
+            });
+        }
+        return value;
+    }
+    async function webhookSecret(systemSecrets, handle, fallback) {
+        if (systemSecrets) {
+            // No auditCtx: every webhook would otherwise spam the audit trail.
+            const got = await systemSecrets.get(SYSTEM_TENANT_ID, handle.name);
+            const stored = parseStoredSecret(got?.reveal());
+            if (stored)
+                return stored;
+        }
+        if (fallback && fallback.length > 0)
+            return fallback;
+        throw new Error(`subscription-paddle: '${handle.name}' unresolved — no system-secret set and no factory fallback. Webhook cannot verify until it is configured.`);
+    }
+    async function hasSecret(ctx, handle, fallback) {
+        if (fallback !== undefined && fallback.length > 0)
+            return true;
+        // Existence-only probe on every billing-plans render: must stay un-audited.
+        return ctx.services.secrets
+            ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, handle.name)
+            : false;
+    }
+    async function baseUrlFor(ctx) {
+        const environment = ctx.config ? await ctx.config(deps.environmentHandle) : undefined;
+        return PADDLE_BASE_URLS[environmentOf(environment)];
+    }
+    return {
+        ctx: {
+            call: async (ctx, request) => http({
+                baseUrl: await baseUrlFor(ctx),
+                apiKey: await ctxSecret(ctx, deps.apiKeyHandle, deps.fallback.apiKey, "api-key"),
+            }, request),
+            assertBillingLive: async (ctx, handlerName = "create-checkout-session") => {
+                const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+                if (live !== true) {
+                    throw new FeatureDisabledError(SUBSCRIPTION_PADDLE_FEATURE, handlerName);
+                }
+            },
+            isBillingEnabled: async (ctx) => {
+                const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+                if (live !== true)
+                    return false;
+                return ((await hasSecret(ctx, deps.apiKeyHandle, deps.fallback.apiKey)) &&
+                    (await hasSecret(ctx, deps.tenantBindingKeyHandle, deps.fallback.tenantBindingKey)));
+            },
+            tenantBindingKey: (ctx) => ctxSecret(ctx, deps.tenantBindingKeyHandle, deps.fallback.tenantBindingKey, "tenant-binding-key"),
+        },
+        webhook: {
+            resolveWebhookSecret: (systemSecrets) => webhookSecret(systemSecrets, deps.webhookSecretHandle, deps.fallback.webhookSecret),
+            resolveTenantBindingKey: (systemSecrets) => webhookSecret(systemSecrets, deps.tenantBindingKeyHandle, deps.fallback.tenantBindingKey),
+        },
+        readCheckoutConfig: async (ctx) => {
+            const stored = ctx.config ? await ctx.config(deps.clientTokenHandle) : undefined;
+            const environment = ctx.config ? await ctx.config(deps.environmentHandle) : undefined;
+            const clientToken = stored || deps.fallback.clientToken || null;
+            return { clientToken, environment: environmentOf(environment) };
+        },
+    };
+}

package/dist/subscription-paddle/subscription-state.d.ts

@@ -0,0 +1,34 @@
+import { type SubscriptionStatus } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+export declare const paddleCustomDataSchema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+export declare const paddleSubscriptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+    customer_id: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        price: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+        quantity: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    custom_data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    current_billing_period: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        ends_at: z.ZodISODateTime;
+    }, z.core.$strip>>>;
+    next_billed_at: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    scheduled_change: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        action: z.ZodString;
+        effective_at: z.ZodISODateTime;
+    }, z.core.$strip>>>;
+    canceled_at: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+}, z.core.$strip>;
+export type PaddleSubscription = z.infer<typeof paddleSubscriptionSchema>;
+export type MappedPaddleSubscriptionState = {
+    readonly status: SubscriptionStatus;
+    readonly tier: string;
+    readonly currentPeriodEnd: string;
+    readonly cancelAt: string | null;
+};
+/** Null when the status is unknown, no item's price is in `priceToTier`
+ *  (SubscriptionEvent.tier is required) or no period end can be derived. */
+export declare function mapPaddleSubscriptionState(sub: PaddleSubscription, priceToTier: Readonly<Record<string, string>>): MappedPaddleSubscriptionState | null;

package/dist/subscription-paddle/subscription-state.js

@@ -0,0 +1,48 @@
+// Paddle's subscription entity and its mapping onto the foundation's state.
+// Shared by the webhook and retrieveSubscription so both map identically.
+import { SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+const PADDLE_SUBSCRIPTION_STATUSES = {
+    active: SubscriptionStatuses.active,
+    trialing: SubscriptionStatuses.trialing,
+    past_due: SubscriptionStatuses.pastDue,
+    paused: SubscriptionStatuses.pastDue,
+    canceled: SubscriptionStatuses.canceled,
+};
+const SCHEDULED_CANCEL_ACTION = "cancel";
+const instantSchema = z.iso.datetime({ offset: true });
+export const paddleCustomDataSchema = z.record(z.string(), z.unknown()).nullish();
+export const paddleSubscriptionSchema = z.object({
+    id: z.string().min(1),
+    status: z.string(),
+    customer_id: z.string().min(1),
+    items: z.array(z.object({
+        price: z.object({ id: z.string().min(1) }),
+        quantity: z.number().int().positive().optional(),
+    })),
+    custom_data: paddleCustomDataSchema,
+    current_billing_period: z.object({ ends_at: instantSchema }).nullish(),
+    next_billed_at: instantSchema.nullish(),
+    scheduled_change: z.object({ action: z.string(), effective_at: instantSchema }).nullish(),
+    canceled_at: instantSchema.nullish(),
+});
+/** Null when the status is unknown, no item's price is in `priceToTier`
+ *  (SubscriptionEvent.tier is required) or no period end can be derived. */
+export function mapPaddleSubscriptionState(sub, priceToTier) {
+    const status = Object.hasOwn(PADDLE_SUBSCRIPTION_STATUSES, sub.status)
+        ? PADDLE_SUBSCRIPTION_STATUSES[sub.status]
+        : undefined;
+    const tier = sub.items
+        .map((item) => Object.hasOwn(priceToTier, item.price.id) ? priceToTier[item.price.id] : undefined)
+        .find((name) => name);
+    const currentPeriodEnd = sub.current_billing_period?.ends_at ?? sub.next_billed_at ?? sub.canceled_at;
+    if (!status || !tier || !currentPeriodEnd)
+        return null;
+    const scheduled = sub.scheduled_change;
+    return {
+        status,
+        tier,
+        currentPeriodEnd,
+        cancelAt: scheduled?.action === SCHEDULED_CANCEL_ACTION ? scheduled.effective_at : null,
+    };
+}

package/dist/subscription-paddle/tenant-binding.d.ts

@@ -0,0 +1,8 @@
+export declare function signTenantBinding(key: string, tenantId: string): string;
+export declare function isValidTenantBinding(key: string, tenantId: string, binding: string): boolean;
+export type BoundTenant = {
+    readonly tenantId: string;
+    readonly consentId?: string;
+};
+/** Null unless `customData` names a tenant together with a binding that `key` signed. */
+export declare function boundTenantOf(customData: Readonly<Record<string, unknown>> | null | undefined, key: string): BoundTenant | null;

package/dist/subscription-paddle/tenant-binding.js

@@ -0,0 +1,26 @@
+// Paddle.js runs with a public client token and can open checkouts with any
+// `customData` from the browser, so `custom_data.tenantId` alone proves nothing.
+// The binding is an HMAC only the server can produce: webhooks whose tenantId
+// does not carry a valid binding are ignored.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { parseProviderConsentId } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+const BINDING_CONTEXT = "kumiko-paddle-tenant:v1:";
+export function signTenantBinding(key, tenantId) {
+    return createHmac("sha256", key).update(`${BINDING_CONTEXT}${tenantId}`).digest("base64url");
+}
+export function isValidTenantBinding(key, tenantId, binding) {
+    const expected = Buffer.from(signTenantBinding(key, tenantId));
+    const candidate = Buffer.from(binding);
+    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+}
+/** Null unless `customData` names a tenant together with a binding that `key` signed. */
+export function boundTenantOf(customData, key) {
+    const tenantId = customData?.["tenantId"];
+    const binding = customData?.["tenantBinding"];
+    if (typeof tenantId !== "string" || tenantId.length === 0)
+        return null;
+    if (typeof binding !== "string" || !isValidTenantBinding(key, tenantId, binding))
+        return null;
+    const consentId = parseProviderConsentId(customData?.["consentId"]);
+    return { tenantId, ...(consentId !== undefined && { consentId }) };
+}

package/dist/subscription-paddle/verify-webhook.d.ts

@@ -0,0 +1,4 @@
+export declare const PADDLE_WEBHOOK_TOLERANCE_SECONDS = 300;
+/** Throws unless one `h1` signature over `rawBody` is valid and the timestamp is
+ *  within the tolerance in both directions. Header names must be lower-case. */
+export declare function verifyPaddleSignature(rawBody: string, headers: Readonly<Record<string, string>>, secret: string, nowSeconds: number): void;

package/dist/subscription-paddle/verify-webhook.js

@@ -0,0 +1,55 @@
+// Paddle webhook signature check: `Paddle-Signature: ts=<unix>;h1=<hex>[;h1=<hex>]`,
+// HMAC-SHA256 over `${ts}:${rawBody}` keyed with the raw secret string.
+//
+// Verification always runs against the raw body string; re-serialized JSON
+// would change whitespace and break the HMAC. It happens before any parsing,
+// so no path bypasses it.
+import { createHmac, timingSafeEqual } from "node:crypto";
+// Paddle's own SDK accepts 5 s. 300 s matches Stripe here: the foundation
+// de-duplicates by event_id and pod clocks drift.
+export const PADDLE_WEBHOOK_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEADER = "paddle-signature";
+const TIMESTAMP_PATTERN = /^\d+$/;
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+function parseSignatureHeader(header) {
+    let timestamp;
+    const signatures = [];
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator < 0)
+            continue;
+        const name = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (name === "ts")
+            timestamp = value;
+        else if (name === "h1")
+            signatures.push(value);
+    }
+    return timestamp === undefined ? null : { timestamp, signatures };
+}
+/** Throws unless one `h1` signature over `rawBody` is valid and the timestamp is
+ *  within the tolerance in both directions. Header names must be lower-case. */
+export function verifyPaddleSignature(rawBody, headers, secret, nowSeconds) {
+    const header = headers[SIGNATURE_HEADER];
+    if (!header)
+        throw new Error("subscription-paddle: paddle-signature header missing");
+    const parsed = parseSignatureHeader(header);
+    if (!parsed || parsed.signatures.length === 0) {
+        throw new Error("subscription-paddle: paddle-signature header is malformed");
+    }
+    if (!TIMESTAMP_PATTERN.test(parsed.timestamp)) {
+        throw new Error("subscription-paddle: webhook ts is not a Unix timestamp in seconds");
+    }
+    if (Math.abs(nowSeconds - Number(parsed.timestamp)) > PADDLE_WEBHOOK_TOLERANCE_SECONDS) {
+        throw new Error("subscription-paddle: webhook timestamp outside the tolerance window");
+    }
+    const expected = createHmac("sha256", secret).update(`${parsed.timestamp}:${rawBody}`).digest();
+    const matches = parsed.signatures.some((signature) => {
+        if (!SHA256_HEX_PATTERN.test(signature))
+            return false;
+        const candidate = Buffer.from(signature, "hex");
+        return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+    });
+    if (!matches)
+        throw new Error("subscription-paddle: webhook signature verify failed");
+}

package/dist/subscription-paddle/webhook-events.d.ts

@@ -0,0 +1,9 @@
+import { type PaymentEvent, type SubscriptionEvent } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { PaddleWebhookRuntime } from "./runtime.ts";
+export type PaddleWebhookOptions = {
+    readonly priceToTier: Readonly<Record<string, string>>;
+    /** Test seam: Unix seconds. Defaults to the wall clock. */
+    readonly nowSeconds?: () => number;
+};
+export declare function verifyAndParsePaddleWebhook(runtime: PaddleWebhookRuntime, options: PaddleWebhookOptions): (rawBody: string, headers: Record<string, string>, systemSecrets?: SecretsContext) => Promise<SubscriptionEvent | PaymentEvent | null>;