@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-provider-imap/sender-auth-headers.ts

@@ -0,0 +1,36 @@
+import {
+  fromDomainOf,
+  parseSenderAuthentication,
+  type SenderAuthentication,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { ParsedMail } from "mailparser";
+
+const HEADER_NAME = "authentication-results";
+
+// headerLines keeps every occurrence in file order, topmost first. Unlike `headers`, which merges
+// repeated headers, the order is what the trust rule depends on.
+function authenticationResultValues(parsed: ParsedMail): string[] {
+  return parsed.headerLines
+    .filter((header) => header.key === HEADER_NAME)
+    .map((header) => header.line.slice(header.line.indexOf(":") + 1));
+}
+
+// A From header with addresses of several domains cannot be bound to one DMARC verdict.
+function singleFromDomain(parsed: ParsedMail): string | null {
+  const domains = new Set(
+    (parsed.from?.value ?? []).map((address) => fromDomainOf(address.address ?? "")),
+  );
+  const [only] = domains;
+  return domains.size === 1 && only ? only : null;
+}
+
+export function senderAuthenticationOf(
+  parsed: ParsedMail,
+  trustedAuthservId: string | null,
+): SenderAuthentication | null {
+  return parseSenderAuthentication(
+    authenticationResultValues(parsed),
+    trustedAuthservId,
+    singleFromDomain(parsed),
+  );
+}

package/packages/bundled-features/src/inbound-provider-inmemory/feature.ts

@@ -13,11 +13,13 @@
 
 import {
   InboundAuthError,
+  type InboundContentFetchResult,
   type InboundFetchResult,
   type InboundMailContext,
   type InboundMailProviderPlugin,
   type MailAccountRecord,
   type RawInboundMessage,
+  type RejectedInboundMessage,
   type SyncCursorPayload,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
@@ -36,11 +38,21 @@ type WatchHandlers = {
   readonly onError: (err: unknown) => void;
 };
 
+type LogEntry =
+  | { readonly message: RawInboundMessage }
+  | { readonly rejected: RejectedInboundMessage };
+
 type AccountState = {
-  readonly log: RawInboundMessage[];
+  readonly log: LogEntry[];
+  // What fetchContent serves; a message that is not in here counts as gone from the server.
+  readonly fullContent: Map<string, RawInboundMessage>;
+  readonly contentFetches: string[][];
   watch: WatchHandlers | null;
+  watchedTrustedAuthservId: string | null | undefined;
   nextFetchError: unknown;
   nextVerifyError: unknown;
+  hangingFetch: Promise<void> | null;
+  lastFetchSignal: AbortSignal | undefined;
   credentialSecretKey: string | null;
 };
 
@@ -51,9 +63,14 @@ function stateFor(accountId: string): AccountState {
   if (!state) {
     state = {
       log: [],
+      fullContent: new Map(),
+      contentFetches: [],
       watch: null,
+      watchedTrustedAuthservId: undefined,
       nextFetchError: null,
       nextVerifyError: null,
+      hangingFetch: null,
+      lastFetchSignal: undefined,
       credentialSecretKey: null,
     };
     accounts.set(accountId, state);
@@ -66,10 +83,25 @@ function stateFor(accountId: string): AccountState {
  *  cursor — the foundation's deduplication makes this idempotent. */
 export async function seedInboundMessage(accountId: string, msg: RawInboundMessage): Promise<void> {
   const state = stateFor(accountId);
-  state.log.push(msg);
+  state.log.push({ message: msg });
   if (state.watch) await state.watch.onMessages([msg]);
 }
 
+/** Test helper: a mail the provider cannot parse; fetch reports it as rejected and moves on. */
+export function seedRejectedInboundMessage(accountId: string, providerMessageId: string): void {
+  stateFor(accountId).log.push({ rejected: { providerMessageId, reason: "unparseable" } });
+}
+
+/** Test helper: the full version of a message that fetchContent serves later. */
+export function setInboundFullContent(accountId: string, msg: RawInboundMessage): void {
+  stateFor(accountId).fullContent.set(msg.providerMessageId, msg);
+}
+
+/** Test helper: the provider message ids of every fetchContent call so far. */
+export function contentFetchesOf(accountId: string): readonly (readonly string[])[] {
+  return stateFor(accountId).contentFetches;
+}
+
 /** Test helper: injects a one-shot error into the next fetch (e.g.
  *  InboundAuthError or InboundCursorInvalidError). */
 export function failNextFetchWith(accountId: string, err: unknown): void {
@@ -81,6 +113,25 @@ export function failNextVerifyWith(accountId: string, err: unknown): void {
   stateFor(accountId).nextVerifyError = err;
 }
 
+/** Test helper: fetches of the account do not return until `release()`, whatever the abort signal
+ *  says, like a provider that ignores cancellation on a dead connection. */
+export function hangFetchesOf(accountId: string): { readonly release: () => void } {
+  const state = stateFor(accountId);
+  const { promise, resolve } = Promise.withResolvers<void>();
+  state.hangingFetch = promise;
+  return {
+    release: () => {
+      state.hangingFetch = null;
+      resolve();
+    },
+  };
+}
+
+/** Test helper: the abort signal the last fetch of the account received. */
+export function lastFetchSignalOf(accountId: string): AbortSignal | undefined {
+  return stateFor(accountId).lastFetchSignal;
+}
+
 /** Test helper: every fetch reads this tenant secret first, like a real
  *  provider reads its stored credentials; a missing secret is an auth error. */
 export function requireCredentialSecretOnFetch(accountId: string, key: string): void {
@@ -116,6 +167,11 @@ export function isWatching(accountId: string): boolean {
   return accounts.get(accountId)?.watch != null;
 }
 
+/** Test helper: the trustedAuthservId of the account the last watch was started with. */
+export function watchedTrustedAuthservIdOf(accountId: string): string | null | undefined {
+  return accounts.get(accountId)?.watchedTrustedAuthservId;
+}
+
 /** Test-Helper: kompletter State-Reset (Test-Isolation — Mock-States
  *  nie zwischen Tests teilen). */
 export function resetInboundInMemory(): void {
@@ -142,6 +198,8 @@ export const inMemoryInboundMailPlugin: InboundMailProviderPlugin = {
   },
   fetch: async (ctx, account, cursor, opts): Promise<InboundFetchResult> => {
     const state = stateFor(account.id);
+    state.lastFetchSignal = opts.signal;
+    if (state.hangingFetch) await state.hangingFetch;
     if (state.nextFetchError) {
       const err = state.nextFetchError;
       state.nextFetchError = null;
@@ -153,15 +211,29 @@ export const inMemoryInboundMailPlugin: InboundMailProviderPlugin = {
     const offset = offsetOf(cursor);
     const slice = state.log.slice(offset, offset + opts.maxMessages);
     const nextOffset = offset + slice.length;
+    const rejected = slice.flatMap((entry) => ("rejected" in entry ? [entry.rejected] : []));
     return {
-      messages: slice,
+      messages: slice.flatMap((entry) => ("message" in entry ? [entry.message] : [])),
+      ...(rejected.length > 0 && { rejected }),
       nextCursor: { offset: nextOffset },
       hasMore: nextOffset < state.log.length,
     };
   },
+  fetchContent: async (_ctx, account, providerMessageIds): Promise<InboundContentFetchResult> => {
+    const state = stateFor(account.id);
+    state.contentFetches.push([...providerMessageIds]);
+    const messages = providerMessageIds.flatMap((id) => state.fullContent.get(id) ?? []);
+    const found = new Set(messages.map((m) => m.providerMessageId));
+    return {
+      messages,
+      missing: providerMessageIds.filter((id) => !found.has(id)),
+      rejected: [],
+    };
+  },
   watch: async (_ctx, account, handlers) => {
     const state = stateFor(account.id);
     state.watch = handlers;
+    state.watchedTrustedAuthservId = account.trustedAuthservId ?? null;
     return async () => {
       if (state.watch === handlers) state.watch = null;
     };

package/packages/bundled-features/src/inbound-provider-inmemory/index.ts

@@ -1,13 +1,19 @@
 // Public API of the inbound-provider-inmemory bundled-feature.
 
 export {
+  contentFetchesOf,
   createInboundProviderInMemoryFeature,
   emitWatchError,
   failNextFetchWith,
   failNextVerifyWith,
+  hangFetchesOf,
   INMEMORY_PROVIDER_KEY,
   isWatching,
+  lastFetchSignalOf,
   requireCredentialSecretOnFetch,
   resetInboundInMemory,
   seedInboundMessage,
+  seedRejectedInboundMessage,
+  setInboundFullContent,
+  watchedTrustedAuthservIdOf,
 } from "./feature.ts";

package/packages/bundled-features/src/jobs/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "catchUp job consumers ignore foreign event types before upcasting, and catchUp with maxPerTenant skip fails at boot",
+    "detail": "A catch-up job consumer now filters on the trigger's event types before the stored event is upcast, so a foreign event with a failing upcaster no longer stalls the job cursor. Boot rejects `trigger.catchUp` together with `maxPerTenant` onLimit \"skip\" (including the number shorthand): a replay must not discard history. Use onLimit \"defer\"."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "r.job event triggers can catch up on stored events",
+    "detail": "trigger { on, catchUp: true } gives the job its own event consumer job:<jobQn> that starts at the beginning of the event store, so events from before the job existed run it too, once per event (job id derived from job QN and event id). Every \"on\" entry must be an r.defineEvent event, otherwise boot fails. The job is no longer fired by the shared job-trigger consumer. JobRunner gains handleCatchUpEvent."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "triggerName is documented as the firing event's qualified name",
+    "detail": "The JSDoc of `triggerName` said it names the handler that emitted the event; the job runner sets the event's qualified name, which multi-trigger jobs compare against the event QN constants."
+  },
   {
     "version": "0.390.0",
     "type": "fix",

package/packages/bundled-features/src/managed-pages/web/i18n.ts

@@ -16,6 +16,7 @@ export const MANAGED_PAGES_I18N: Readonly<Record<string, LocalizedString>> = {
   // Screen titles (global/unprefixed, screenTitleKey = screen:<id>.title)
   "screen:page-list.title": { en: "Pages" },
   "screen:page-edit.title": { en: "Edit page" },
+  "screen:page-edit.createTitle": { en: "New page" },
   "screen:branding-settings.title": { en: "Branding" },
 
   // Page-Entity Feld-Labels (managed-pages:entity:page:field:*)

package/packages/bundled-features/src/subscription-paddle/changes.json

@@ -0,0 +1,15 @@
+[
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Add subscription-paddle, a Paddle Billing provider plugin",
+    "detail": "Checkout via the Paddle.js overlay on a page served by the feature 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 transactions 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. Also ships customer portal, cancel, resume, batched price lookup, in-app plan switch and tenant binding of checkouts through an HMAC in custom_data."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "Remove subscription-dodo, replaced by subscription-paddle",
+    "detail": "Removed exports of @cosmicdrift/kumiko-bundled-features/subscription-dodo: DODO_BASE_URLS, DODO_PROVIDER_NAME, DodoEnvironment, DodoEnvironments, SUBSCRIPTION_DODO_FEATURE, SubscriptionDodoOptions, createSubscriptionDodoFeature, dodoEnvSchema, subscriptionDodoEnvSchema.",
+    "migration": "Replace createSubscriptionDodoFeature with createSubscriptionPaddleFeature from @cosmicdrift/kumiko-bundled-features/subscription-paddle and dodoEnvSchema with paddleEnvSchema. Map Paddle price ids (pri_...) to tiers in priceToTier, set PADDLE_API_KEY, PADDLE_WEBHOOK_SECRET, PADDLE_TENANT_BINDING_KEY and PADDLE_CLIENT_TOKEN (or the matching config keys) and point the Default Payment Link at /billing/paddle-checkout. Point the Paddle notification destination at /webhooks/subscription/paddle when billing is mounted through the server-runtime boot option (SUBSCRIPTION_WEBHOOK_PATH), or at /api/subscription/webhook/paddle when createSubscriptionWebhookRoute is mounted by hand. In server-runtime boot options, billing.dodo becomes billing.paddle. An app-own credit-pack env such as DODO_PRODUCT_PACKS becomes a list of Paddle pri_ ids; the pack size comes from the price or product custom_data.credits, which surfaces as ProviderPrice.metadata.credits. Existing Dodo subscriptions are not migrated; a subscription stays with the provider stored on it."
+  }
+]

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

@@ -0,0 +1,17 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { PaddleRuntimes } from "./runtime.ts";
+
+// Anonymous on purpose: the checkout page is public. The answer is the public
+// Paddle.js client token and the environment, nothing else.
+export function makeCheckoutConfigQuery(readCheckoutConfig: PaddleRuntimes["readCheckoutConfig"]) {
+  return defineQueryHandler({
+    name: "checkout-config",
+    schema: z.object({}),
+    access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+    rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    description:
+      "Answers the public Paddle.js client token and the Paddle environment for the checkout page; the client token is public by design and no other config leaves this handler.",
+    handler: async (_query, ctx) => readCheckoutConfig(ctx),
+  });
+}

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",
+};