@cosmicdrift/kumiko-samples 0.393.0 → 0.394.0

package/packages/bundled-features/src/subscription-paddle/checkout-methods.ts

@@ -0,0 +1,107 @@
+// Paddle plugin methods for checkout, portal, cancel and resume. Every response
+// is validated with Zod; every non-2xx throws a PaddleHttpError.
+
+import { SubscriptionCancelTimings } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
+import { signTenantBinding } from "./tenant-binding.ts";
+
+export function paddleSubscriptionPath(providerSubscriptionId: string): string {
+  return `/subscriptions/${encodeURIComponent(providerSubscriptionId)}`;
+}
+
+function relativeTarget(url: string): string {
+  const parsed = new URL(url);
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+
+const checkoutResponseSchema = z.object({
+  data: z.object({
+    id: z.string(),
+    checkout: z.object({ url: z.string().nullable() }).nullish(),
+  }),
+});
+
+export function createPaddleCheckoutSession(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"createCheckoutSession"> {
+  return async (ctx, options) => {
+    // No Paddle transaction may be created while billing is not live.
+    await runtime.assertBillingLive(ctx);
+    const bindingKey = await runtime.tenantBindingKey(ctx);
+    // No `checkout.url` in the body: Paddle rejects unapproved domains and otherwise
+    // answers with the dashboard's Default Payment Link plus `?_ptxn=`.
+    const { data } = checkoutResponseSchema.parse(
+      await runtime.call(ctx, {
+        method: "POST",
+        path: "/transactions",
+        body: {
+          items: [{ price_id: options.priceId, quantity: 1 }],
+          ...(options.providerCustomerId && { customer_id: options.providerCustomerId }),
+          custom_data: {
+            tenantId: options.tenantId,
+            tenantBinding: signTenantBinding(bindingKey, options.tenantId),
+            ...(options.consentId && { consentId: options.consentId }),
+          },
+        },
+      }),
+    );
+    if (!data.checkout?.url) {
+      throw new Error("subscription-paddle: transaction was created without a checkout url");
+    }
+    const url = new URL(data.checkout.url);
+    url.searchParams.set("success", relativeTarget(options.successUrl));
+    url.searchParams.set("cancel", relativeTarget(options.cancelUrl));
+    if (options.locale) url.searchParams.set("locale", options.locale);
+    return { url: url.href };
+  };
+}
+
+const portalResponseSchema = z.object({
+  data: z.object({ urls: z.object({ general: z.object({ overview: z.string() }) }) }),
+});
+
+// Paddle's portal has no return url, so options.returnUrl is not used.
+export function createPaddlePortalSession(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"createPortalSession"> {
+  return async (ctx, options) => {
+    const response = portalResponseSchema.parse(
+      await runtime.call(ctx, {
+        method: "POST",
+        path: `/customers/${encodeURIComponent(options.providerCustomerId)}/portal-sessions`,
+        body: {},
+      }),
+    );
+    return { url: response.data.urls.general.overview };
+  };
+}
+
+export function createPaddleCancelSubscription(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"cancelSubscription"> {
+  return async (ctx, options) => {
+    await runtime.call(ctx, {
+      method: "POST",
+      path: `${paddleSubscriptionPath(options.providerSubscriptionId)}/cancel`,
+      body: {
+        effective_from:
+          options.when === SubscriptionCancelTimings.periodEnd
+            ? "next_billing_period"
+            : "immediately",
+      },
+    });
+  };
+}
+
+export function createPaddleResumeSubscription(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"resumeSubscription"> {
+  return async (ctx, options) => {
+    await runtime.call(ctx, {
+      method: "PATCH",
+      path: paddleSubscriptionPath(options.providerSubscriptionId),
+      body: { scheduled_change: null },
+    });
+  };
+}

package/packages/bundled-features/src/subscription-paddle/checkout-page.ts

@@ -0,0 +1,154 @@
+// The Default Payment Link page. Paddle has no hosted checkout, so Paddle.js
+// runs on this page and opens the overlay for the `?_ptxn=` transaction by
+// itself. The page never reflects `_ptxn`.
+
+import { createHash } from "node:crypto";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
+import type { Context } from "hono";
+import * as z from "zod";
+import type { SystemQueryFn } from "../shared/index.ts";
+import { PADDLE_CHECKOUT_CONFIG_QUERY, PaddleEnvironments } from "./constants.ts";
+
+const PADDLE_JS_URL = "https://cdn.paddle.com/paddle/v2/paddle.js";
+const MAX_REDIRECT_LENGTH = 2048;
+const FALLBACK_REDIRECT = "/";
+const LOCALE_PATTERN = /^[a-z]{2}(-[A-Z]{2})?$/;
+// Control characters, which browsers strip or reinterpret inside URLs.
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+
+// Static on purpose: its sha256 goes into the CSP, so nothing may be interpolated.
+export const PADDLE_INIT_SCRIPT = `(function () {
+  var data = document.getElementById("kumiko-paddle-checkout").dataset;
+  var completed = false;
+  if (data.environment === "sandbox") Paddle.Environment.set("sandbox");
+  var settings = { displayMode: "overlay", successUrl: new URL(data.successUrl, location.origin).href };
+  if (data.locale) settings.locale = data.locale;
+  Paddle.Initialize({
+    token: data.clientToken,
+    checkout: { settings: settings },
+    eventCallback: function (event) {
+      if (event.name === "checkout.completed") completed = true;
+      if (event.name === "checkout.closed" && !completed) {
+        location.assign(new URL(data.cancelUrl, location.origin).href);
+      }
+    }
+  });
+})();`;
+
+const INIT_SCRIPT_HASH = createHash("sha256").update(PADDLE_INIT_SCRIPT).digest("base64");
+
+export const PADDLE_CHECKOUT_CSP = [
+  "default-src 'none'",
+  `script-src 'sha256-${INIT_SCRIPT_HASH}' https://cdn.paddle.com`,
+  "style-src 'unsafe-inline' https://cdn.paddle.com",
+  "img-src data: https://*.paddle.com",
+  "connect-src https://*.paddle.com",
+  "frame-src https://buy.paddle.com https://sandbox-buy.paddle.com",
+  "frame-ancestors 'none'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "object-src 'none'",
+].join("; ");
+
+// Own header set: `securePageHeaders` pins `script-src 'none'`. The global
+// wrapper only fills headers that are absent, so these win.
+function pageHeaders(): Record<string, string> {
+  return {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "referrer-policy": "no-referrer",
+    "x-frame-options": "DENY",
+    "x-content-type-options": "nosniff",
+    "content-security-policy": PADDLE_CHECKOUT_CSP,
+  };
+}
+
+/** Same-origin path only: anything else would make the page an open redirector. */
+export function safeRedirectPath(raw: string | undefined): string {
+  if (
+    raw === undefined ||
+    raw.length > MAX_REDIRECT_LENGTH ||
+    !raw.startsWith("/") ||
+    raw.startsWith("//") ||
+    raw.startsWith("/\\") ||
+    CONTROL_CHARACTERS.test(raw)
+  ) {
+    return FALLBACK_REDIRECT;
+  }
+  return raw;
+}
+
+export function safeLocale(raw: string | undefined): string | undefined {
+  return raw !== undefined && LOCALE_PATTERN.test(raw) ? raw : undefined;
+}
+
+type CheckoutPageValues = {
+  readonly clientToken: string;
+  readonly environment: string;
+  readonly successUrl: string;
+  readonly cancelUrl: string;
+  readonly locale: string | undefined;
+};
+
+export function renderCheckoutPage(values: CheckoutPageValues): string {
+  const attributesHtml = [
+    ["data-client-token", values.clientToken],
+    ["data-environment", values.environment],
+    ["data-success-url", values.successUrl],
+    ["data-cancel-url", values.cancelUrl],
+    ...(values.locale ? [["data-locale", values.locale]] : []),
+  ]
+    .map(([name, value]) => `${name}="${escapeHtml(value ?? "")}"`)
+    .join(" ");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Checkout</title>
+</head>
+<body>
+<div id="kumiko-paddle-checkout" ${attributesHtml}></div>
+<noscript>JavaScript is required to complete the checkout.</noscript>
+<script src="${PADDLE_JS_URL}"></script>
+<script>${PADDLE_INIT_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+
+const checkoutConfigSchema = z.object({
+  clientToken: z.string().nullable(),
+  environment: z.string(),
+});
+
+export async function servePaddleCheckoutPage(
+  c: Context,
+  { systemQuery }: { readonly systemQuery: SystemQueryFn },
+): Promise<Response> {
+  let config: z.infer<typeof checkoutConfigSchema>;
+  try {
+    config = checkoutConfigSchema.parse(
+      await systemQuery(PADDLE_CHECKOUT_CONFIG_QUERY, {}, SYSTEM_TENANT_ID),
+    );
+  } catch {
+    return unavailable(c);
+  }
+  if (!config.clientToken) return unavailable(c);
+  const html = renderCheckoutPage({
+    clientToken: config.clientToken,
+    environment:
+      config.environment === PaddleEnvironments.live
+        ? PaddleEnvironments.live
+        : PaddleEnvironments.sandbox,
+    successUrl: safeRedirectPath(c.req.query("success")),
+    cancelUrl: safeRedirectPath(c.req.query("cancel")),
+    locale: safeLocale(c.req.query("locale")),
+  });
+  return new Response(html, { status: 200, headers: pageHeaders() });
+}
+
+function unavailable(c: Context): Response {
+  return c.text("checkout unavailable", 503, { "cache-control": "no-store" });
+}

package/packages/bundled-features/src/subscription-paddle/client.ts

@@ -0,0 +1,78 @@
+// Thin JSON-over-fetch client for the Paddle Billing REST API. All traffic goes
+// through the injected `send`, which defaults to the SSRF-safe egress in
+// feature.ts and is replaced by a mock in tests.
+
+import { parseJsonOrThrow, parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+
+export type PaddleSend = (url: string, init?: RequestInit) => Promise<Response>;
+
+export type PaddleRequest = {
+  readonly method: "GET" | "POST" | "PATCH";
+  /** Path segments interpolated into it must already be encodeURIComponent'ed. */
+  readonly path: string;
+  readonly query?: Readonly<Record<string, string>>;
+  readonly body?: unknown;
+};
+
+export type PaddleTarget = { readonly baseUrl: string; readonly apiKey: string };
+
+const PADDLE_API_VERSION = "1";
+
+const paddleErrorBodySchema = z.object({ error: z.object({ type: z.string(), code: z.string() }) });
+// Both values come from outside; anything beyond a plain identifier is dropped so
+// no customer text reaches the logs.
+const ERROR_IDENTIFIER = /^[a-z0-9_]{1,100}$/;
+
+type PaddleErrorDetails = { readonly type?: string; readonly code?: string };
+
+function paddleErrorDetails(bodyText: string): PaddleErrorDetails {
+  const parsed = paddleErrorBodySchema.safeParse(parseJsonSafe<unknown>(bodyText, undefined));
+  if (!parsed.success) return {};
+  const { type, code } = parsed.data.error;
+  return {
+    ...(ERROR_IDENTIFIER.test(type) && { type }),
+    ...(ERROR_IDENTIFIER.test(code) && { code }),
+  };
+}
+
+// Carries only the status and Paddle's error type and code, never `detail`, the
+// rest of the body or the key: they can hold customer data or secrets.
+export class PaddleHttpError extends Error {
+  readonly status: number;
+  readonly paddleErrorType?: string;
+  readonly paddleErrorCode?: string;
+  constructor(request: PaddleRequest, status: number, details: PaddleErrorDetails = {}) {
+    const suffix = [details.type && `type ${details.type}`, details.code && `code ${details.code}`]
+      .filter(Boolean)
+      .join(", ");
+    super(
+      `subscription-paddle: ${request.method} ${request.path} failed with status ${status}${suffix ? ` (${suffix})` : ""}`,
+    );
+    this.name = "PaddleHttpError";
+    this.status = status;
+    if (details.type) this.paddleErrorType = details.type;
+    if (details.code) this.paddleErrorCode = details.code;
+  }
+}
+
+export function createPaddleHttp(send: PaddleSend) {
+  return async (target: PaddleTarget, request: PaddleRequest): Promise<unknown> => {
+    const query = request.query ? `?${new URLSearchParams(request.query).toString()}` : "";
+    const response = await send(`${target.baseUrl}${request.path}${query}`, {
+      method: request.method,
+      headers: {
+        Authorization: `Bearer ${target.apiKey}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "Paddle-Version": PADDLE_API_VERSION,
+      },
+      ...(request.body !== undefined && { body: JSON.stringify(request.body) }),
+    });
+    const text = await response.text();
+    if (!response.ok) throw new PaddleHttpError(request, response.status, paddleErrorDetails(text));
+    return text.length === 0
+      ? null
+      : parseJsonOrThrow<unknown>(text, "subscription-paddle response");
+  };
+}

package/packages/bundled-features/src/subscription-paddle/constants.ts

@@ -0,0 +1,32 @@
+export const SUBSCRIPTION_PADDLE_FEATURE = "subscription-paddle" as const;
+
+// Must match the last path segment of the webhook URL (`/webhooks/subscription/paddle` via the boot option).
+export const PADDLE_PROVIDER_NAME = "paddle" as const;
+
+// Paddle has no hosted checkout page, so the feature serves the Default Payment
+// Link itself; the same path goes into the Paddle dashboard.
+export const PADDLE_CHECKOUT_PATH = "/billing/paddle-checkout" as const;
+
+// Config-key short-names, qualified to `subscription-paddle:config:<name>` at
+// registry-build. api-key, webhook-secret and tenant-binding-key are backing:"secrets".
+export const PADDLE_API_KEY_CONFIG = "api-key" as const;
+export const PADDLE_WEBHOOK_SECRET_CONFIG = "webhook-secret" as const;
+export const PADDLE_TENANT_BINDING_KEY_CONFIG = "tenant-binding-key" as const;
+export const PADDLE_CLIENT_TOKEN_CONFIG = "client-token" as const;
+export const PADDLE_ENVIRONMENT_CONFIG = "environment" as const;
+export const PADDLE_BILLING_LIVE_CONFIG = "billingLive" as const;
+
+export const PADDLE_CHECKOUT_CONFIG_QUERY = `${SUBSCRIPTION_PADDLE_FEATURE}:query:checkout-config`;
+
+// Separate from billingLive on purpose: staging runs Paddle's sandbox with
+// billingLive on, production flips both.
+export const PaddleEnvironments = {
+  sandbox: "sandbox",
+  live: "live",
+} as const;
+export type PaddleEnvironment = (typeof PaddleEnvironments)[keyof typeof PaddleEnvironments];
+
+export const PADDLE_BASE_URLS: Readonly<Record<PaddleEnvironment, string>> = {
+  sandbox: "https://sandbox-api.paddle.com",
+  live: "https://api.paddle.com",
+};

package/packages/bundled-features/src/subscription-paddle/feature.ts

@@ -0,0 +1,265 @@
+// kumiko-feature-version: 1
+//
+// subscription-paddle — Paddle Billing (merchant of record) plugin for the
+// billing-foundation plugin API. Credentials, the billing-live master switch and
+// the API environment (sandbox | live) are config keys resolved at call time, like
+// subscription-stripe. The `apiKey` / `webhookSecret` / `tenantBindingKey` /
+// `clientToken` options are env→config bridge fallbacks.
+
+import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  access,
+  createSystemConfig,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type FeatureWithEnvSchema, featureWithEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { egress } from "@cosmicdrift/kumiko-framework/http";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { makeCheckoutConfigQuery } from "./checkout-config.query.ts";
+import {
+  createPaddleCancelSubscription,
+  createPaddleCheckoutSession,
+  createPaddlePortalSession,
+  createPaddleResumeSubscription,
+} from "./checkout-methods.ts";
+import { servePaddleCheckoutPage } from "./checkout-page.ts";
+import type { PaddleSend } from "./client.ts";
+import {
+  PADDLE_API_KEY_CONFIG,
+  PADDLE_BILLING_LIVE_CONFIG,
+  PADDLE_CLIENT_TOKEN_CONFIG,
+  PADDLE_ENVIRONMENT_CONFIG,
+  PADDLE_PROVIDER_NAME,
+  PADDLE_TENANT_BINDING_KEY_CONFIG,
+  PADDLE_WEBHOOK_SECRET_CONFIG,
+  PaddleEnvironments,
+  SUBSCRIPTION_PADDLE_FEATURE,
+} from "./constants.ts";
+import {
+  createPaddleApplyPlanSwitch,
+  createPaddlePreviewPlanSwitch,
+  createPaddleRetrieveSubscription,
+} from "./plan-switch-methods.ts";
+import { createPaddlePriceCache, createPaddleRetrievePrices } from "./price-methods.ts";
+import { createPaddleRuntimes } from "./runtime.ts";
+import { verifyAndParsePaddleWebhook } from "./webhook-events.ts";
+
+/** Bridge contract: all fields are optional fallbacks for the config store. */
+export const subscriptionPaddleEnvSchema = z.object({
+  PADDLE_API_KEY: z
+    .string()
+    .min(1)
+    .describe("Paddle API key. Bridge-fallback — prefer the secret.")
+    .meta({ kumiko: { pulumi: { secret: true } } })
+    .optional(),
+  PADDLE_WEBHOOK_SECRET: z
+    .string()
+    .min(1)
+    .describe("Paddle notification secret (`pdl_ntfset_...`). Bridge-fallback — prefer the secret.")
+    .meta({ kumiko: { pulumi: { secret: true } } })
+    .optional(),
+  PADDLE_TENANT_BINDING_KEY: z
+    .string()
+    .min(1)
+    .describe(
+      "Server-only HMAC key binding a Paddle checkout to its tenant. Bridge-fallback — prefer the secret.",
+    )
+    .meta({ kumiko: { pulumi: { secret: true } } })
+    .optional(),
+  PADDLE_CLIENT_TOKEN: z
+    .string()
+    .regex(/^(test|live)_/, "PADDLE_CLIENT_TOKEN must start with 'test_' or 'live_'")
+    .describe("Paddle.js client-side token (public). Bridge-fallback for the config key.")
+    .optional(),
+});
+
+type PaddlePriceEnvShape<TPrice extends string> = {
+  [Key in `PADDLE_PRICE_${TPrice}`]: z.ZodOptional<z.ZodString>;
+};
+
+/** Paddle env block plus one `PADDLE_PRICE_<NAME>` slot per plan price the app
+ *  maps to a tier, e.g. `paddleEnvSchema({ prices: ["PRO", "TEAM"] })`.
+ *  Shares its bridge fields with `subscriptionPaddleEnvSchema`, so spreading
+ *  it into `composeEnvSchema({ extend })` next to the mounted feature is no
+ *  key clash. */
+export function paddleEnvSchema<const TPrice extends string>(options: {
+  readonly prices: readonly TPrice[];
+}) {
+  const priceShape = Object.fromEntries(
+    options.prices.map((price) => [
+      `PADDLE_PRICE_${price}`,
+      z
+        .string()
+        .regex(/^pri_/, `PADDLE_PRICE_${price} must start with 'pri_'`)
+        .optional()
+        .describe(`Paddle price id (\`pri_...\`) of the ${price} plan.`),
+    ]),
+    // @cast-boundary schema-walk — Object.fromEntries widens to an index signature; the entries are exactly one optional string per listed price.
+  ) as PaddlePriceEnvShape<TPrice>;
+  return z.object({ ...subscriptionPaddleEnvSchema.shape, ...priceShape });
+}
+
+export type SubscriptionPaddleOptions = {
+  /** Bridge-fallback API key; the `api-key` config key wins when set. */
+  readonly apiKey?: string;
+  /** Bridge-fallback webhook secret; the `webhook-secret` config key wins when set. */
+  readonly webhookSecret?: string;
+  /** Bridge-fallback tenant binding key; the `tenant-binding-key` config key wins when set. */
+  readonly tenantBindingKey?: string;
+  /** Bridge-fallback Paddle.js client token; the `client-token` config key wins when set. */
+  readonly clientToken?: string;
+  /** Paddle price id → app tier name. Prices absent here drop the event. */
+  readonly priceToTier?: Readonly<Record<string, string>>;
+  /** Price ids a mode:"payment" checkout may target; empty = one-off checkouts closed. */
+  readonly oneOffPriceIds?: readonly string[];
+  /** HTTP transport; defaults to the SSRF-safe external egress. Test seam. */
+  readonly send?: PaddleSend;
+  /** Epoch milliseconds for the plan-switch preview timestamp. Test seam. */
+  readonly now?: () => number;
+  /** Unix seconds for the webhook tolerance window. Test seam. */
+  readonly nowSeconds?: () => number;
+};
+
+// Validated once at feature-build time so a typo fails app startup instead of
+// silently widening or narrowing the one-off allowlist at request time.
+function validateOneOffPriceIds(priceIds: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const priceId of priceIds) {
+    if (priceId.length === 0) {
+      throw new Error("subscription-paddle: oneOffPriceIds must not contain an empty string");
+    }
+    if (seen.has(priceId)) {
+      throw new Error(`subscription-paddle: duplicate oneOffPriceIds entry "${priceId}"`);
+    }
+    seen.add(priceId);
+  }
+}
+
+export function createSubscriptionPaddleFeature(
+  options: SubscriptionPaddleOptions = {},
+): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionPaddleEnvSchema.shape> {
+  validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+  const now = options.now ?? (() => Temporal.Now.instant().epochMilliseconds);
+  const feature: FeatureDefinition = defineFeature(SUBSCRIPTION_PADDLE_FEATURE, (r) => {
+    r.describe(
+      'Paddle Billing provider plugin for `billing-foundation`. Paddle acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key, webhook secret and tenant binding key from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant), the public Paddle.js `client-token`, a `billingLive` master switch and an `environment` key (sandbox | live). `environment` is its own key because Paddle serves sandbox and live from different API hosts and a live key must never hit the sandbox host or the other way round; `billingLive` only decides whether checkouts are offered at all. All of them are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionPaddleFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret`/`tenantBindingKey`/`clientToken` options are env to config bridge fallbacks (`PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TENANT_BINDING_KEY`, `PADDLE_CLIENT_TOKEN`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, and billing counts as enabled only with API key and binding key present. Webhooks arrive at `/webhooks/subscription/paddle` when mounted through the server-runtime `billing.paddle` boot option, or at `/api/subscription/webhook/paddle` when `createSubscriptionWebhookRoute` is mounted by hand and are verified with the `Paddle-Signature` header (HMAC-SHA256 over `ts:rawBody` keyed with the raw secret, any `h1` may match, 5 minute tolerance). Paddle.js can open checkouts with arbitrary `customData` from the browser, so `custom_data.tenantId` is only trusted together with `tenantBinding`, an HMAC of the tenant id under the binding key; events without a valid binding, for prices outside `priceToTier` or without a tenant are dropped. Rotating the binding key makes the webhooks of existing subscriptions fail that check until they are re-bound. Paddle has no hosted checkout page, so the feature serves the Default Payment Link itself at `/billing/paddle-checkout` (the Default Payment Link in the Paddle dashboard must point to `<APP_BASE_URL>/billing/paddle-checkout`; it is the only source, because checkouts are created without a `checkout.url`). Create subscription prices in the Paddle catalog with quantity minimum and maximum 1; for one-off packs set the quantity limits on purpose, because the payment event carries `quantity` and the app has to multiply its credits by it: an anonymous page with its own CSP that loads Paddle.js from cdn.paddle.com, the one external script this framework allows, and opens the overlay for the transaction. Implements checkout, customer portal, cancel and resume, `retrievePrices` (batched, 10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `subscription.updated` webhook to move the tier.',
+    );
+    r.uiHints({
+      displayLabel: "Billing · Paddle",
+      category: "billing",
+      recommended: false,
+    });
+    r.requires({ features: ["billing-foundation"] });
+    r.requires({ features: ["config"] });
+    r.requires({ features: ["secrets"] });
+    r.envSchema(subscriptionPaddleEnvSchema);
+
+    const configKeys = r.config({
+      keys: {
+        [PADDLE_API_KEY_CONFIG]: createSystemConfig("text", {
+          backing: "secrets",
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-paddle.api-key", icon: "key", order: 1 },
+        }),
+        [PADDLE_WEBHOOK_SECRET_CONFIG]: createSystemConfig("text", {
+          backing: "secrets",
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-paddle.webhook-secret", icon: "shield", order: 2 },
+        }),
+        [PADDLE_TENANT_BINDING_KEY_CONFIG]: createSystemConfig("text", {
+          backing: "secrets",
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-paddle.tenant-binding-key", icon: "lock", order: 3 },
+        }),
+        [PADDLE_CLIENT_TOKEN_CONFIG]: createSystemConfig("text", {
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-paddle.client-token", icon: "settings", order: 4 },
+        }),
+        [PADDLE_ENVIRONMENT_CONFIG]: createSystemConfig("select", {
+          default: PaddleEnvironments.sandbox,
+          options: [PaddleEnvironments.sandbox, PaddleEnvironments.live],
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-paddle.environment", icon: "server", order: 5 },
+        }),
+        [PADDLE_BILLING_LIVE_CONFIG]: createSystemConfig("boolean", {
+          default: false,
+          write: access.privileged,
+          read: access.admin,
+          mask: { title: "subscription-paddle.billing-live", icon: "rocket", order: 6 },
+        }),
+      },
+    });
+
+    r.translations({
+      keys: {
+        "subscription-paddle.api-key": { en: "Paddle API key" },
+        "subscription-paddle.webhook-secret": { en: "Paddle webhook secret" },
+        "subscription-paddle.tenant-binding-key": { en: "Paddle tenant binding key" },
+        "subscription-paddle.client-token": { en: "Paddle client-side token" },
+        "subscription-paddle.environment": { en: "Paddle environment" },
+        "subscription-paddle.billing-live": { en: "Live billing" },
+        "subscription-paddle.settings": { en: "Paddle" },
+        "screen:subscription-paddle-system.title": { en: "Paddle" },
+      },
+    });
+
+    const priceToTier = options.priceToTier ?? {};
+    const runtimes = createPaddleRuntimes({
+      apiKeyHandle: configKeys[PADDLE_API_KEY_CONFIG],
+      webhookSecretHandle: configKeys[PADDLE_WEBHOOK_SECRET_CONFIG],
+      tenantBindingKeyHandle: configKeys[PADDLE_TENANT_BINDING_KEY_CONFIG],
+      clientTokenHandle: configKeys[PADDLE_CLIENT_TOKEN_CONFIG],
+      billingLiveHandle: configKeys[PADDLE_BILLING_LIVE_CONFIG],
+      environmentHandle: configKeys[PADDLE_ENVIRONMENT_CONFIG],
+      send: options.send ?? egress({ kind: "external" }),
+      fallback: {
+        ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+        ...(options.webhookSecret !== undefined && { webhookSecret: options.webhookSecret }),
+        ...(options.tenantBindingKey !== undefined && {
+          tenantBindingKey: options.tenantBindingKey,
+        }),
+        ...(options.clientToken !== undefined && { clientToken: options.clientToken }),
+      },
+    });
+
+    r.queryHandler(makeCheckoutConfigQuery(runtimes.readCheckoutConfig));
+    r.httpRoute({
+      method: "GET",
+      // Literal for the feature-AST extractor; must equal PADDLE_CHECKOUT_PATH (integration test).
+      path: "/billing/paddle-checkout",
+      anonymous: true,
+      rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+      handler: (c, deps) => servePaddleCheckoutPage(c, deps),
+    });
+
+    const plugin: SubscriptionProviderPlugin = {
+      displayName: "Paddle",
+      verifyAndParseWebhook: verifyAndParsePaddleWebhook(runtimes.webhook, {
+        priceToTier,
+        ...(options.nowSeconds && { nowSeconds: options.nowSeconds }),
+      }),
+      createCheckoutSession: createPaddleCheckoutSession(runtimes.ctx),
+      createPortalSession: createPaddlePortalSession(runtimes.ctx),
+      cancelSubscription: createPaddleCancelSubscription(runtimes.ctx),
+      resumeSubscription: createPaddleResumeSubscription(runtimes.ctx),
+      priceToTier,
+      oneOffPriceIds: options.oneOffPriceIds ?? [],
+      isBillingEnabled: runtimes.ctx.isBillingEnabled,
+      retrievePrices: createPaddleRetrievePrices(runtimes.ctx, createPaddlePriceCache({ now })),
+      retrieveSubscription: createPaddleRetrieveSubscription(runtimes.ctx, { priceToTier }),
+      previewPlanSwitch: createPaddlePreviewPlanSwitch(runtimes.ctx, now),
+      applyPlanSwitch: createPaddleApplyPlanSwitch(runtimes.ctx),
+    };
+    r.useExtension("subscriptionProvider", PADDLE_PROVIDER_NAME, plugin);
+
+    return { configKeys };
+  });
+  return featureWithEnvSchema(feature, subscriptionPaddleEnvSchema);
+}

package/packages/bundled-features/src/subscription-paddle/index.ts

@@ -0,0 +1,17 @@
+// Public API of the subscription-paddle bundled feature. The webhook verifier,
+// client and plugin methods are internal to feature.ts.
+
+export {
+  PADDLE_BASE_URLS,
+  PADDLE_CHECKOUT_PATH,
+  PADDLE_PROVIDER_NAME,
+  type PaddleEnvironment,
+  PaddleEnvironments,
+  SUBSCRIPTION_PADDLE_FEATURE,
+} from "./constants.ts";
+export {
+  createSubscriptionPaddleFeature,
+  paddleEnvSchema,
+  type SubscriptionPaddleOptions,
+  subscriptionPaddleEnvSchema,
+} from "./feature.ts";