@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/subscription-stripe/runtime.ts

@@ -0,0 +1,193 @@
+// Runtime key/flag-resolution for the subscription-stripe plugin.
+//
+// **Why this exists (the pivot away from mount-time closures):**
+// v1 of this feature baked the Stripe credentials into a closure at
+// `createSubscriptionStripeFeature({ apiKey, webhookSecret })`-mount-time.
+// Rotating a key or flipping prod live then needed a redeploy. This module
+// resolves both at CALL-time instead:
+//   - `api-key` + `webhook-secret` from system config keys with
+//     backing:"secrets" — the value lives in the secrets store under
+//     SYSTEM_TENANT_ID (Stripe is app-wide), JSON-serialized like any config
+//     value. Both read paths reach it via SecretsContext.get(config-QN) and
+//     parse the JSON back (parseStoredSecret).
+//   - `billing-live` from a **system config** key (default false) — the
+//     master switch that gates whether a checkout may create a live session.
+//
+// The factory-options (`apiKey` / `webhookSecret`) survive as **optional
+// fallbacks**: during the env→secrets bridge phase, and in tests that don't
+// wire a secrets-context, the closure value is used when no secret is set.
+//
+// **Two read-paths, by tenant-resolution phase:**
+//   - Post-tenant (checkout/portal/cancel): full HandlerContext with a
+//     caller identity → audited read via `requireSecretsContext`.
+//   - Pre-tenant (webhook sig-verify): no ctx, no caller → raw
+//     `SecretsContext.get(SYSTEM_TENANT_ID, handle)` (the sanctioned
+//     un-audited framework-internal path). The foundation builds and passes
+//     this SecretsContext as the 3rd webhook arg.
+
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  type ConfigKeyHandle,
+  type HandlerContext,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import Stripe from "stripe";
+import { SUBSCRIPTION_STRIPE_FEATURE } from "./constants.js";
+
+const API_KEY_HINT =
+  "Set the Stripe API key via config:write:set on `subscription-stripe:config:api-key` (or seed it from STRIPE_API_KEY during the env bridge).";
+
+/** Memoize Stripe clients by api-key string — a fresh client is built only
+ *  when the key actually changes (rotation), so steady-state calls reuse one
+ *  connection-pooled instance per key. */
+export function createStripeClientCache(): (apiKey: string) => Stripe {
+  const cache = new Map<string, Stripe>();
+  return (apiKey) => {
+    const cached = cache.get(apiKey);
+    if (cached) return cached;
+    // No apiVersion pin — a string literal breaks consumers' typecheck on newer
+    // stripe SDKs (#256); the SDK's own default keeps wire-version and types aligned.
+    const client = new Stripe(apiKey);
+    cache.set(apiKey, client);
+    return client;
+  };
+}
+
+export type StripeRuntimeDeps = {
+  readonly apiKeyHandle: ConfigKeyHandle<"text">;
+  readonly webhookSecretHandle: ConfigKeyHandle<"text">;
+  readonly billingLiveHandle: ConfigKeyHandle<"boolean">;
+  readonly fallback: { readonly apiKey?: string; readonly webhookSecret?: string };
+};
+
+// backing:"secrets" config keys store their value JSON-serialized in the
+// secrets store (config:write:set → JSON.stringify). A raw SecretsContext.get
+// (the un-audited webhook path + the audited ctx read here) therefore returns
+// the JSON-quoted string and must parse it back. The factory fallback is a
+// plain env string and stays raw — so parsing is applied only to the store
+// read, never to the fallback.
+function parseStoredSecret(raw: string | undefined): string | undefined {
+  if (raw === undefined || raw.length === 0) return undefined;
+  // parseJsonOrThrow is the sanctioned safe-parse (same helper the config
+  // resolver's deserializeValue uses for this very value) — mirrors how the
+  // store round-trips a backing:"secrets" text value.
+  const parsed = parseJsonOrThrow<unknown>(raw, "subscription-stripe credential (backing:secrets)");
+  return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
+}
+
+/** Post-tenant runtime: used by checkout/portal/cancel which carry a full
+ *  HandlerContext (audited secret reads, config-gate). */
+export type StripeCtxRuntime = {
+  readonly clientForCtx: (ctx: HandlerContext) => Promise<Stripe>;
+  /** Throws FeatureDisabledError unless `billing-live` config is true. The
+   *  #104 invariant: no Stripe session may be created while billing is not
+   *  live (sk_test_ keys in prod must not produce a live checkout).
+   *  `handlerName` names the write-handler in the thrown error — defaults to
+   *  "create-checkout-session" for existing callers, but plan-switch/portal
+   *  callers pass their own name so the error points at the right handler. */
+  readonly assertBillingLive: (ctx: HandlerContext, handlerName?: string) => Promise<void>;
+  /** Whether `billing-live` is currently true — used by `isBillingEnabled`
+   *  (billing-plans catalog rendering) where a disabled provider degrades
+   *  the UI instead of throwing. */
+  readonly isBillingEnabled: (ctx: HandlerContext) => Promise<boolean>;
+};
+
+/** Pre-tenant runtime: used by verifyAndParseWebhook (no ctx). Resolves both
+ *  keys from the foundation-supplied system SecretsContext, with fallback. */
+export type StripeWebhookRuntime = {
+  readonly resolve: (
+    systemSecrets?: SecretsContext,
+  ) => Promise<{ readonly stripe: Stripe; readonly webhookSecret: string }>;
+};
+
+export type StripeRuntimes = {
+  readonly ctx: StripeCtxRuntime;
+  readonly webhook: StripeWebhookRuntime;
+};
+
+export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
+  const clientFor = createStripeClientCache();
+
+  async function ctxApiKey(ctx: HandlerContext): Promise<string> {
+    let key: string | undefined;
+    if (ctx.secrets) {
+      const got = await requireSecretsContext(ctx, SUBSCRIPTION_STRIPE_FEATURE).get(
+        SYSTEM_TENANT_ID,
+        deps.apiKeyHandle.name,
+      );
+      key = parseStoredSecret(got?.reveal());
+    }
+    if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
+      key = deps.fallback.apiKey;
+    }
+    if (!key) {
+      throw new UnconfiguredError({
+        feature: SUBSCRIPTION_STRIPE_FEATURE,
+        key: deps.apiKeyHandle.name,
+        hint: API_KEY_HINT,
+      });
+    }
+    return key;
+  }
+
+  async function rawRead(
+    systemSecrets: SecretsContext | undefined,
+    handle: ConfigKeyHandle<"text">,
+    fallback: string | undefined,
+  ): Promise<string | undefined> {
+    if (systemSecrets) {
+      // No auditCtx → un-audited framework-internal read (every webhook would
+      // otherwise spam the audit trail). This is the sanctioned no-ctx path.
+      const got = await systemSecrets.get(SYSTEM_TENANT_ID, handle.name);
+      const value = parseStoredSecret(got?.reveal());
+      if (value && value.length > 0) return value;
+    }
+    return fallback && fallback.length > 0 ? fallback : undefined;
+  }
+
+  return {
+    ctx: {
+      // @wrapper-known semantic-alias
+      clientForCtx: async (ctx) => clientFor(await ctxApiKey(ctx)),
+      assertBillingLive: async (ctx, handlerName = "create-checkout-session") => {
+        const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+        if (live !== true) {
+          throw new FeatureDisabledError(SUBSCRIPTION_STRIPE_FEATURE, handlerName);
+        }
+      },
+      isBillingEnabled: async (ctx) => {
+        const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+        if (live !== true) return false;
+        const hasFallbackKey =
+          deps.fallback.apiKey !== undefined && deps.fallback.apiKey.length > 0;
+        if (hasFallbackKey) return true;
+        // Existence-only probe — called on every billing-plans page render,
+        // must stay un-audited (see SecretsContext.has's own doc comment).
+        return ctx.secrets
+          ? await ctx.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
+          : false;
+      },
+    },
+    webhook: {
+      resolve: async (systemSecrets) => {
+        const apiKey = await rawRead(systemSecrets, deps.apiKeyHandle, deps.fallback.apiKey);
+        const webhookSecret = await rawRead(
+          systemSecrets,
+          deps.webhookSecretHandle,
+          deps.fallback.webhookSecret,
+        );
+        if (!apiKey || !webhookSecret) {
+          const missing = !apiKey ? deps.apiKeyHandle.name : deps.webhookSecretHandle.name;
+          throw new Error(
+            `subscription-stripe: '${missing}' unresolved — no system-secret set and no factory fallback. ` +
+              "Webhook cannot verify until it is configured.",
+          );
+        }
+        return { stripe: clientFor(apiKey), webhookSecret };
+      },
+    },
+  };
+}

package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts

@@ -0,0 +1,436 @@
+// verifyAndParseStripeWebhook — Stripe-spezifische sig-verify +
+// event-mapping. Wird vom Plugin-Build (feature.ts) als
+// `verifyAndParseWebhook` registriert.
+//
+// **Steps:**
+//   1. Sig-verify via stripe.webhooks.constructEvent (HMAC-SHA-256
+//      gegen rawBody + Stripe-Signature-Header). Wirft bei mismatch
+//      oder älter als 5min (Replay-Protection).
+//   1b. checkout.session.completed / .async_payment_succeeded branch off
+//       here into a PaymentEvent (one-off-payment, own aggregate) — see
+//       "One-off-payment" section below. Everything else falls through.
+//   2. Event-type-Filter: nur die 5 event-types die wir auf
+//      SubscriptionEventTypes mappen kommen weiter; alles andere
+//      returnt null (foundation antwortet 200 ignored).
+//   3. Stripe-payload → SubscriptionEvent normalisieren
+//      (status-mapping, tenant-id aus metadata, price-to-tier-Lookup).
+//
+// **Runtime-keys (pre-tenant):** api-key + webhook-secret kommen NICHT
+// mehr aus einem mount-time-Closure, sondern werden zur Webhook-Zeit aus
+// dem `StripeWebhookRuntime` aufgelöst. Der foundation-webhook-handler
+// reicht einen system-scoped SecretsContext als 3. Arg durch; der runtime
+// liest beide Keys daraus (un-audited, system-internal) mit Fallback auf
+// die factory-options. Damit rotiert ein Key ohne Redeploy — und der
+// invoice-lazy-fetch (unten) nutzt denselben rotierten Client wie der
+// sig-verify, kein split-brain.
+//
+// **Invoice-event lazy-fetch:**
+// Invoice payloads carry only the subscription id (Stripe does not expand
+// subscription in webhooks), so the plugin lazy-fetches via
+// `stripe.subscriptions.retrieve(subId)` to get the full subscription for
+// status/tier/period-end mapping. resource_missing (deleted between webhook
+// and retrieve) returns null; any other Stripe error becomes 503 so Stripe
+// redelivers.
+
+import type {
+  PaymentEvent,
+  SubscriptionEvent,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  BillingEventKinds,
+  parseProviderConsentId,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { ExtraRouteRejection } from "@cosmicdrift/kumiko-framework/api";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import Stripe from "stripe";
+import { Temporal } from "temporal-polyfill";
+import { STRIPE_PROVIDER_NAME, StripeEventTypes } from "./constants.js";
+import type { StripeWebhookRuntime } from "./runtime.js";
+
+const log = createFallbackLogger("subscription-stripe");
+
+export function isResourceMissingStripeError(error: unknown): boolean {
+  return (
+    error instanceof Stripe.errors.StripeInvalidRequestError && error.code === "resource_missing"
+  );
+}
+
+// Anything but resource_missing (network, 5xx, rate limit) is transient: a 503 makes Stripe retry,
+// whereas a silent null would be acknowledged as 200 and the event lost for good.
+function transientProviderRejection(error: unknown): ExtraRouteRejection {
+  return new ExtraRouteRejection(
+    503,
+    { error: { code: "subscription_provider_transient" } },
+    `stripe retrieve failed: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+// =============================================================================
+// Sig-verify + parse
+// =============================================================================
+
+export type StripeWebhookOptions = {
+  /** Price-to-tier-Map. Plugin liest die price-id aus dem event und
+   *  mapped auf tier-name. Fehlt die price-id im Mapping → null. App-
+   *  spezifisch, bleibt eine factory-option (kein Secret). */
+  readonly priceToTier: Readonly<Record<string, string>>;
+};
+
+/**
+ * Stripe-webhook-handler. Implementiert den Plugin-Contract
+ * `verifyAndParseWebhook`. **Pre-tenant-resolution** — kein
+ * HandlerContext; statt eines mount-time-Clients löst der `runtime` den
+ * Stripe-Client + das webhook-secret zur Call-Zeit aus dem optionalen
+ * system-SecretsContext (3. Arg) auf.
+ */
+export function verifyAndParseStripeWebhook(
+  runtime: StripeWebhookRuntime,
+  options: StripeWebhookOptions,
+): (
+  rawBody: string,
+  headers: Record<string, string>,
+  systemSecrets?: SecretsContext,
+) => Promise<SubscriptionEvent | PaymentEvent | null> {
+  return async (rawBody, headers, systemSecrets) => {
+    const sigHeader = headers["stripe-signature"];
+    if (!sigHeader) {
+      throw new Error("subscription-stripe: stripe-signature header missing");
+    }
+
+    // 0. Runtime-resolve: api-key (für client + lazy-fetch) + webhook-
+    //    secret (für sig-verify) aus system-secrets, Fallback factory-
+    //    options. Wirft wenn beide unkonfiguriert.
+    const { stripe, webhookSecret } = await runtime.resolve(systemSecrets);
+
+    // 1. Sig-verify. constructEvent throws bei mismatch (= invalid sig)
+    //    oder timestamp-tolerance-violation (default 5min). Foundation
+    //    mapped throw → HTTP 401. Applies to BOTH branches below — the
+    //    payment-branch only branches off AFTER this check; there's no
+    //    path that bypasses signature verification.
+    let event: Stripe.Event;
+    try {
+      event = await stripe.webhooks.constructEventAsync(rawBody, sigHeader, webhookSecret);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`subscription-stripe: webhook signature verify failed — ${msg}`);
+    }
+
+    // 1b. One-off-payment events (checkout mode "payment") branch off BEFORE
+    //     the mapStripeEventType filter below — they don't map to a
+    //     SubscriptionEventType and must not touch mapStripeEventType's
+    //     5-item whitelist (drift-pin in verify-webhook.test.ts still
+    //     expects null for "checkout.session.completed").
+    if (isCheckoutSessionEventType(event.type)) {
+      return await parsePaymentEvent(event, stripe);
+    }
+
+    // 2. Event-type-Filter — wir kennen nur 5.
+    const normalizedType = mapStripeEventType(event.type);
+    if (!normalizedType) {
+      return null; // foundation returnt 200 ignored
+    }
+
+    // 3. Payload-extraction. Stripe liefert je nach event.type
+    //    verschiedene data.object-shapes. Wir extrahieren die
+    //    Subscription-Daten — entweder direkt (subscription-events)
+    //    oder via lazy-fetch (invoice-events).
+    const sub = await extractSubscriptionFromEvent(event, stripe);
+    if (!sub) {
+      // event-type war unter den 5 (oben gefiltert), aber payload-shape
+      // matched nicht — Stripe-SDK-Schema-Drift, defensive null.
+      return null;
+    }
+
+    // 4. Tenant-resolution aus metadata. App-Builder setzt
+    //    `metadata.tenantId` beim createCheckoutSession-call.
+    const tenantId = sub.metadata?.["tenantId"];
+    if (!tenantId || tenantId.length === 0) {
+      // Subscription ohne tenant-metadata → kann kein subscription
+      // erstellen ohne tenant-resolution. Drop the event silent
+      // (foundation 200 ignored). App-Owner-Bug, nicht foundation-Bug.
+      return null;
+    }
+
+    // 5+6. Price-to-tier-Mapping + status/period-end/cancel_at — shared with
+    //      plugin-methods.ts's createStripeRetrieveSubscription so both the
+    //      webhook and the sync-subscriptions backfill map Stripe state
+    //      identically.
+    const state = mapStripeSubscriptionState(sub, options.priceToTier);
+    if (!state) {
+      return null;
+    }
+
+    const consentId = parseProviderConsentId(sub.metadata?.["consentId"]);
+    return {
+      providerEventId: event.id,
+      providerName: STRIPE_PROVIDER_NAME,
+      type: normalizedType,
+      tenantId,
+      ...(consentId !== undefined && { consentId }),
+      providerCustomerId: typeof sub.customer === "string" ? sub.customer : sub.customer.id,
+      providerSubscriptionId: sub.id,
+      ...state,
+    };
+  };
+}
+
+// =============================================================================
+// Shared subscription-state mapping (webhook + retrieveSubscription)
+// =============================================================================
+
+export type MappedStripeSubscriptionState = {
+  readonly status: SubscriptionStatus;
+  readonly tier: string;
+  readonly currentPeriodEnd: string;
+  readonly cancelAt: string | null;
+};
+
+/** Maps a Stripe subscription's price/status/period-end/cancel_at onto the
+ *  foundation's normalized shape. Null when the subscription's price isn't
+ *  in `priceToTier` (the app owner created the Stripe price but never
+ *  mapped it to a tier) or the item has no price id at all. */
+export function mapStripeSubscriptionState(
+  sub: Pick<Stripe.Subscription, "status" | "items" | "cancel_at" | "cancel_at_period_end">,
+  priceToTier: Readonly<Record<string, string>>,
+): MappedStripeSubscriptionState | null {
+  const priceId = sub.items.data[0]?.price.id;
+  if (!priceId) {
+    return null;
+  }
+  const tier = priceToTier[priceId];
+  if (!tier) {
+    return null;
+  }
+
+  // Since 2024 Stripe reports period-end per item
+  // (subscription.items.data[i].current_period_end), not per subscription.
+  // We read the first item; multi-item subscriptions (add-ons) aren't
+  // supported.
+  const status = mapStripeStatus(sub.status);
+  const periodEndUnixSec = sub.items.data[0]?.current_period_end ?? 0;
+  // Stripe returns Unix-seconds; Temporal.Instant.fromEpochMilliseconds
+  // expects ms. Multiply, then ISO. (No-Date-API-Guard forbids
+  // `new Date()` — static import above, not the ambient global, see #1490.)
+  const currentPeriodEnd = Temporal.Instant.fromEpochMilliseconds(
+    periodEndUnixSec * 1000,
+  ).toString();
+  const cancelAt = stripeCancelAtIso(sub, currentPeriodEnd);
+
+  return { status, tier, currentPeriodEnd, cancelAt };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** cancel_at is set once a cancellation is scheduled (an explicit future
+ *  cancel_at, or cancel_at_period_end which Stripe resolves to the period
+ *  end) — null means the subscription renews. cancel_at_period_end without
+ *  cancel_at falls back to currentPeriodEnd, the value Stripe would report
+ *  as cancel_at. */
+export function stripeCancelAtIso(
+  sub: Pick<Stripe.Subscription, "cancel_at" | "cancel_at_period_end">,
+  currentPeriodEndIso: string,
+): string | null {
+  if (sub.cancel_at) {
+    return Temporal.Instant.fromEpochMilliseconds(sub.cancel_at * 1000).toString();
+  }
+  return sub.cancel_at_period_end ? currentPeriodEndIso : null;
+}
+
+/** Stripe-event-type → normalisiert. null = ignore. */
+export function mapStripeEventType(stripeType: string): SubscriptionEventType | null {
+  switch (stripeType) {
+    case StripeEventTypes.customerSubscriptionCreated:
+      return SubscriptionEventTypes.created;
+    case StripeEventTypes.customerSubscriptionUpdated:
+      return SubscriptionEventTypes.updated;
+    case StripeEventTypes.customerSubscriptionDeleted:
+      return SubscriptionEventTypes.canceled;
+    case StripeEventTypes.invoicePaid:
+      return SubscriptionEventTypes.invoicePaid;
+    case StripeEventTypes.invoicePaymentFailed:
+      return SubscriptionEventTypes.invoicePaymentFailed;
+    default:
+      return null;
+  }
+}
+
+/** Stripe-status → normalisiert. Defensive: unbekannte Status →
+ *  incomplete (Plugin sollte das nicht erreichen, aber wir wollen
+ *  kein ungültiger status-string in der DB). */
+export function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): SubscriptionStatus {
+  switch (stripeStatus) {
+    case "active":
+      return SubscriptionStatuses.active;
+    case "trialing":
+      return SubscriptionStatuses.trialing;
+    case "past_due":
+    case "unpaid":
+    case "paused":
+      return SubscriptionStatuses.pastDue;
+    case "canceled":
+      return SubscriptionStatuses.canceled;
+    // incomplete_expired: the subscription's first payment never completed
+    // in time and Stripe abandoned it for good — unlike a live "incomplete"
+    // (payment still retryable), this is terminal. Mapping it to canceled
+    // (not incomplete) lets a tenant start a fresh checkout instead of
+    // openCheckout's "subscription already exists" conflict blocking them.
+    case "incomplete_expired":
+      return SubscriptionStatuses.canceled;
+    case "incomplete":
+      return SubscriptionStatuses.incomplete;
+    default:
+      return SubscriptionStatuses.incomplete;
+  }
+}
+
+/** Holt die Subscription aus dem Event. Subscription-events haben sie
+ *  direkt im data.object; invoice-events haben nur die subscription-id
+ *  und brauchen einen lazy-fetch via stripe.subscriptions.retrieve. */
+// @wrapper-known semantic-alias
+async function extractSubscriptionFromEvent(
+  event: Stripe.Event,
+  stripe: Stripe,
+): Promise<Stripe.Subscription | null> {
+  switch (event.type) {
+    case StripeEventTypes.customerSubscriptionCreated:
+    case StripeEventTypes.customerSubscriptionUpdated:
+    case StripeEventTypes.customerSubscriptionDeleted:
+      return event.data.object as Stripe.Subscription; // @cast-boundary engine-bridge
+    case StripeEventTypes.invoicePaid:
+    case StripeEventTypes.invoicePaymentFailed: {
+      // Lazy-fetch der subscription. invoice.subscription ist eine
+      // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
+      // full subscription-Object damit der downstream-mapping
+      // (status, tier via priceId, period-end) konsistent funktioniert.
+      const invoice = event.data.object as Stripe.Invoice; // @cast-boundary engine-bridge
+      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null }) // @cast-boundary engine-payload
+        .subscription;
+      if (!subRef) {
+        // Invoice ohne subscription-reference (= one-shot-invoice, nicht
+        // recurring). Nicht unsere Domain — ignorieren.
+        return null;
+      }
+      const subId = typeof subRef === "string" ? subRef : subRef.id;
+      try {
+        return await stripe.subscriptions.retrieve(subId);
+      } catch (error) {
+        // Subscription deleted between webhook and retrieve: null makes the
+        // foundation answer 200 ignored; the next subscription event carries
+        // the state.
+        if (isResourceMissingStripeError(error)) return null;
+        throw transientProviderRejection(error);
+      }
+    }
+    default:
+      return null;
+  }
+}
+
+// =============================================================================
+// One-off-payment (checkout mode "payment") extraction
+// =============================================================================
+
+function isCheckoutSessionEventType(stripeType: string): boolean {
+  return (
+    stripeType === StripeEventTypes.checkoutSessionCompleted ||
+    stripeType === StripeEventTypes.checkoutSessionAsyncPaymentSucceeded
+  );
+}
+
+// The session is already paid, so a silent drop means money collected with no
+// credit — warn (ids and reason only, no PII) so operators can spot it.
+function dropPaidSession(
+  event: Stripe.Event,
+  session: Stripe.Checkout.Session,
+  reason: string,
+): null {
+  log.warn("paid checkout session dropped", { eventId: event.id, sessionId: session.id, reason });
+  return null;
+}
+
+/** Parses a checkout.session.completed / .async_payment_succeeded event into
+ *  a PaymentEvent, or null if it isn't a paid one-off-payment session. */
+// kumiko-lint-ignore complexity-budget optional-field spreads over the session, one branch per optional provider field
+async function parsePaymentEvent(
+  event: Stripe.Event,
+  stripe: Stripe,
+): Promise<PaymentEvent | null> {
+  const session = event.data.object as Stripe.Checkout.Session; // @cast-boundary engine-bridge
+  // mode !== "payment" excludes subscription-checkout sessions (same event types);
+  // payment_status !== "paid" excludes an unpaid/expired session. Null here — not an
+  // error — maps to foundation's 200 "ignored", same as the subscription-path's filters.
+  if (session.mode !== "payment" || session.payment_status !== "paid") {
+    return null;
+  }
+
+  // Lazy-fetch with expand: the raw webhook payload carries neither
+  // line_items (needed for priceId) nor an expanded payment_intent (needed
+  // for tenantId — see below). Same lazy-fetch pattern as
+  // extractSubscriptionFromEvent's invoice-branch above, null only for resource_missing
+  // (session gone between webhook + retrieve), other failures reject with 503.
+  let expanded: Stripe.Checkout.Session;
+  try {
+    expanded = await stripe.checkout.sessions.retrieve(session.id, {
+      expand: ["line_items", "payment_intent"],
+    });
+  } catch (error) {
+    if (isResourceMissingStripeError(error)) return null;
+    throw transientProviderRejection(error);
+  }
+
+  // Tenant-resolution: mode:"payment" checkout sessions carry tenantId on
+  // the PaymentIntent's OWN metadata (plugin-methods.ts sets it via
+  // payment_intent_data.metadata), NOT on session-level metadata —
+  // session.metadata is unset for this mode. Reading it off the expanded,
+  // Stripe-verified PaymentIntent (not a freely-choosable payload field) is
+  // what keeps tenant-attribution trustworthy: the webhook signature proves
+  // this whole object chain came from Stripe, and the metadata itself was
+  // set by our own backend at checkout-creation time.
+  const paymentIntent = expanded.payment_intent;
+  if (!paymentIntent || typeof paymentIntent === "string") {
+    // Not expanded (Stripe-API-drift) or absent — no verified tenant-claim
+    // to trust.
+    return dropPaidSession(event, session, "payment_intent_not_expanded");
+  }
+  const tenantId = paymentIntent.metadata?.["tenantId"];
+  if (!tenantId || tenantId.length === 0) {
+    return dropPaidSession(event, session, "missing_tenant_id");
+  }
+
+  const priceId = expanded.line_items?.data[0]?.price?.id;
+  if (!priceId) {
+    return dropPaidSession(event, session, "missing_price_id");
+  }
+
+  // providerCustomerId: session.customer is null for guest checkouts (no
+  // customer_creation configured) — fall back to the PaymentIntent's own
+  // customer, which Stripe sets independently of the session-level field.
+  const sessionCustomer = expanded.customer;
+  const providerCustomerId =
+    (typeof sessionCustomer === "string" ? sessionCustomer : sessionCustomer?.id) ??
+    (typeof paymentIntent.customer === "string"
+      ? paymentIntent.customer
+      : paymentIntent.customer?.id);
+  if (!providerCustomerId) {
+    return dropPaidSession(event, session, "missing_customer");
+  }
+
+  const consentId = parseProviderConsentId(paymentIntent.metadata?.["consentId"]);
+  return {
+    kind: BillingEventKinds.payment,
+    providerEventId: event.id,
+    providerName: STRIPE_PROVIDER_NAME,
+    tenantId,
+    ...(consentId !== undefined && { consentId }),
+    providerCheckoutId: session.id,
+    providerCustomerId,
+    priceId,
+  };
+}

package/packages/bundled-features/src/tags/aggregate-id.ts

@@ -0,0 +1,23 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID namespace for tag-assignment aggregate-id derivation. Generated
+// once (2026-06-18), frozen: changing it would re-key every existing assignment
+// stream → broken replay. Drift-pinned in __tests__.
+const TAG_ASSIGNMENT_NAMESPACE = "a7f3c9d2-1b4e-4c8a-9f6d-2e5b8a1c3f7d";
+
+/**
+ * Deterministic aggregate-id for a tag-assignment from the tuple
+ * (tenantId, tagId, entityType, entityId). Exactly one aggregate exists per
+ * (tenant, tag, entity), so assigning the same tag twice collides on the same
+ * stream → version_conflict instead of a duplicate row. The assign handler
+ * pre-checks existence to keep re-assign idempotent (TX-safe).
+ */
+// @wrapper-known uuid-domain
+export function tagAssignmentAggregateId(
+  tenantId: string,
+  tagId: string,
+  entityType: string,
+  entityId: string,
+): string {
+  return uuidv5(`${tenantId}|${tagId}|${entityType}|${entityId}`, TAG_ASSIGNMENT_NAMESPACE);
+}

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

@@ -0,0 +1,16 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "ownership.write applies to assign-tag, remove-tag and add-note",
+    "detail": "tags and notes-history: `ownership.write` is now enforced by `assign-tag`, `remove-tag` and `add-note`. Each feature instance builds its write executor from the entity it registers; before, the handlers used a module-level executor without the mount's ownership, so a `from()` write rule never applied to them. The `delete-tag` cascade stays ungated.",
+    "migration": "Mounts that set `ownership.write` now see ownership_denied for callers the rule does not cover. Make sure the rule covers every role that tags or notes, or leave it unset."
+  },
+  {
+    "version": "0.246.0",
+    "type": "improvement",
+    "title": "assign-tag and remove-tag now verify entityType/entityId against the host entity's own read path",
+    "detail": "Before this change, assign-tag and remove-tag took entityType/entityId straight from the client with no check — any dispatch-eligible tenant user could attach a catalog tag to, or detach one from, any object in their tenant, including one they could not otherwise read. The tag-assignment aggregate-id is derived from the tenant, so this was never a cross-tenant hole; it was tagging inside your own tenant across a row-level ownership boundary. Both handlers now unconditionally verify that entityType names a registered entity and that the host row is visible to the caller through that entity's own read path (tenant scope plus its `access.read` ownership) before touching the assignment; either check failing returns a not_found response, the same answer a genuinely missing row gets, so nothing doubles as an existence oracle. The check runs before the assignment and tag lookups, so a denied caller cannot tell an invisible host row apart from a missing assignment. This mirrors the add-note gate shipped in 0.244.0 and shares its helper.",
+    "migration": "entityType must now name an entity registered in the same app (via r.entity(...) or a bundled feature), and the caller must be able to see the target row through that entity's own read path. Any consumer that called assign-tag or remove-tag with an entityType that is NOT a registered entity name, or with an entityId the caller could not otherwise read, will now get a not_found error instead of a successful write — register the host entity (and, if it needs row-level ownership, its `access.read` rule) before upgrading. Note the consequence for hard-deleted host rows: once the host row is gone, its assignment can no longer be removed through remove-tag; delete-tag's cascade still detaches it."
+  }
+]