@cosmicdrift/kumiko-bundled-features 0.320.0 → 0.321.0

package/src/step-dispatcher/feature.ts

@@ -8,12 +8,13 @@
 // the audit trail lives in the event log only — no separate status table.
 
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import * as z from "zod";
-import { type MailSpec, performMailDispatch } from "./mail-runner";
+import { mailSpecSchema, performMailDispatch } from "./mail-runner";
 import {
   performWebhookDispatch,
   WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
-  type WebhookSpec,
+  webhookSpecSchema,
 } from "./webhook-runner";
 
 export const stepDispatcherEnvSchema = z.object({
@@ -30,21 +31,33 @@ export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-request
 export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
 export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
 
-type DispatchRequestedPayload =
-  | {
-      readonly stepKind: "webhook.send";
-      readonly spec: WebhookSpec;
-      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
-    }
-  | {
-      readonly stepKind: "mail.send";
-      readonly spec: MailSpec;
-    };
+// Runtime-validated instead of cast — `event.payload` is `unknown` at the
+// MSP-apply boundary (unsafeAppendEvent), so a payload in an older or
+// foreign shape must end as dispatch-failed, never reach performWebhookDispatch.
+const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
+  z.object({
+    stepKind: z.literal("webhook.send"),
+    spec: webhookSpecSchema,
+    retry: z.object({ times: z.number(), backoff: z.enum(["exponential", "linear"]) }).optional(),
+  }),
+  z.object({ stepKind: z.literal("mail.send"), spec: mailSpecSchema }),
+]);
+
+// zod issue messages can echo the invalid value (e.g. a rejected url) back
+// into the tenant-visible dispatch-failed event — keep this generic.
+const INVALID_DISPATCH_PAYLOAD_ERROR = "invalid dispatch payload";
+
+const rawStepKindSchema = z.object({ stepKind: z.string() });
+
+function rawStepKindOf(payload: unknown): string {
+  const parsed = rawStepKindSchema.safeParse(payload);
+  return parsed.success ? parsed.data.stepKind : "unknown";
+}
 
 export function createStepDispatcherFeature(): FeatureDefinition {
   return defineFeature("step-dispatcher", (r) => {
     r.describe(
-      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`.",
+      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
     );
     r.uiHints({
       displayLabel: "Step Dispatcher · Deferred Side-Effects",
@@ -52,15 +65,35 @@ export function createStepDispatcherFeature(): FeatureDefinition {
       recommended: false,
     });
     r.envSchema(stepDispatcherEnvSchema);
+    r.requires("secrets");
 
     r.multiStreamProjection({
       name: "step-dispatcher",
       apply: {
         [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
-          const payload = event.payload as DispatchRequestedPayload;
+          const parsed = dispatchRequestedPayloadSchema.safeParse(event.payload);
+          if (!parsed.success) {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCH_FAILED_TYPE,
+              payload: {
+                stepKind: rawStepKindOf(event.payload),
+                error: INVALID_DISPATCH_PAYLOAD_ERROR,
+                attempt: 1,
+              },
+            });
+            // skip: invalid payload already recorded via step.dispatch-failed above, nothing left to dispatch
+            return;
+          }
+          const payload = parsed.data;
           const result =
             payload.stepKind === "webhook.send"
-              ? await performWebhookDispatch(payload.spec)
+              ? await performWebhookDispatch(payload.spec, {
+                  tenantId: event.tenantId,
+                  userId: event.metadata.userId || SYSTEM_USER_ID,
+                  secrets: ctx.secrets,
+                })
               : await performMailDispatch(payload.spec);
           if (result.ok) {
             await ctx.unsafeAppendEvent({

package/src/step-dispatcher/index.ts

@@ -15,9 +15,11 @@ export {
   readAllowedPrivateWebhookHostsFromEnv,
   setWebhookFetch,
   setWebhookHostLookup,
-  setWebhookSecretResolver,
   WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  WEBHOOK_AUTH_SECRET_KEY_PREFIX,
+  type WebhookDispatchDeps,
   type WebhookDispatchResult,
   type WebhookSpec,
+  webhookAuthSecretKey,
   webhookSpecSchema,
 } from "./webhook-runner";

package/src/step-dispatcher/webhook-runner.ts

@@ -14,6 +14,11 @@
 // tenant can never grant themselves the bypass. Own key, not the mail
 // features' — step-dispatcher has no dependency relation to mail-transport-
 // smtp/inbound-provider-imap and shouldn't require mounting them.
+//
+// `auth.secret` resolves through the secrets feature under the tenant-owned
+// namespace `step-dispatcher:webhook-auth.<secret>` — the target URL is
+// tenant/request-controlled, so a webhook can never read a platform-wide or
+// another tenant's secret.
 
 import type { lookup } from "node:dns/promises";
 import {
@@ -23,6 +28,8 @@ import {
   resolvePublicHostname,
 } from "@cosmicdrift/kumiko-framework/http";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { TenantId } from "@cosmicdrift/kumiko-types/identifiers";
 import * as z from "zod";
 
 const log = createFallbackLogger("step-dispatcher");
@@ -51,6 +58,25 @@ export function setWebhookHostLookup(fn: typeof lookup | undefined): void {
   webhookHostLookup = fn;
 }
 
+// Tenant-owned namespace every webhook auth secret lives under in the
+// secrets feature. Applied at resolution time, never at step-build time,
+// so `auth.secret` stays a short, human-picked name (e.g. "smtp.password")
+// while the stored key stays collision-free with every other feature's
+// secrets.
+export const WEBHOOK_AUTH_SECRET_KEY_PREFIX = "step-dispatcher:webhook-auth.";
+
+export function webhookAuthSecretKey(name: string): string {
+  return `${WEBHOOK_AUTH_SECRET_KEY_PREFIX}${name}`;
+}
+
+const WEBHOOK_AUTH_SECRET_NAME_MAX_LENGTH = 100 - WEBHOOK_AUTH_SECRET_KEY_PREFIX.length;
+
+const webhookAuthSecretNameSchema = z
+  .string()
+  .min(1)
+  .max(WEBHOOK_AUTH_SECRET_NAME_MAX_LENGTH)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+
 export const webhookSpecSchema = z.object({
   url: z.string(),
   method: z.enum(["POST", "PUT", "PATCH"]),
@@ -58,8 +84,12 @@ export const webhookSpecSchema = z.object({
   body: z.unknown().optional(),
   auth: z
     .union([
-      z.object({ kind: z.literal("bearer"), secretRef: z.string() }),
-      z.object({ kind: z.literal("header"), name: z.string(), secretRef: z.string() }),
+      z.object({ kind: z.literal("bearer"), secret: webhookAuthSecretNameSchema }),
+      z.object({
+        kind: z.literal("header"),
+        name: z.string(),
+        secret: webhookAuthSecretNameSchema,
+      }),
     ])
     .optional(),
 });
@@ -70,31 +100,38 @@ export type WebhookDispatchResult =
   | { readonly ok: true; readonly status: number }
   | { readonly ok: false; readonly error: string };
 
-// Resolves a secretRef via the test-injectable secret-store. Default
-// implementation reads from process.env at the prefix WEBHOOK_SECRET_.
-// Tests pass a custom resolver via setWebhookSecretResolver.
-let secretResolver: (ref: string) => string | undefined = (ref) =>
-  process.env[`WEBHOOK_SECRET_${ref}`];
-
-export function setWebhookSecretResolver(fn: (ref: string) => string | undefined): void {
-  secretResolver = fn;
-}
-
 let fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis);
 
 export function setWebhookFetch(fn: typeof fetch): void {
   fetchImpl = fn;
 }
 
-function buildWebhookHeaders(
+export type WebhookDispatchDeps = {
+  readonly tenantId: TenantId;
+  readonly userId: string;
+  readonly secrets: SecretsContext | undefined;
+};
+
+// Never includes the secret name or value — spec.auth.secret is a
+// tenant-chosen name, but the error still reaches the tenant via the
+// dispatch-failed event, so it stays generic.
+const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
+
+async function buildWebhookHeaders(
   spec: WebhookSpec,
-): { ok: true; headers: Record<string, string> } | { ok: false; error: string } {
+  deps: WebhookDispatchDeps,
+): Promise<{ ok: true; headers: Record<string, string> } | { ok: false; error: string }> {
   const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
   if (!spec.auth) return { ok: true, headers };
-  const secret = secretResolver(spec.auth.secretRef);
-  if (!secret) {
-    return { ok: false, error: `secret "${spec.auth.secretRef}" not configured` };
+  if (!deps.secrets) return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
+  const revealed = await deps.secrets.get(deps.tenantId, webhookAuthSecretKey(spec.auth.secret), {
+    userId: deps.userId,
+    handlerName: "step-dispatcher:webhook.send",
+  });
+  if (!revealed) {
+    return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
   }
+  const secret = revealed.reveal();
   if (spec.auth.kind === "bearer") {
     headers["authorization"] = `Bearer ${secret}`;
   } else {
@@ -128,7 +165,10 @@ async function resolveWebhookFetchTarget(
   }
 }
 
-export async function performWebhookDispatch(spec: WebhookSpec): Promise<WebhookDispatchResult> {
+export async function performWebhookDispatch(
+  spec: WebhookSpec,
+  deps: WebhookDispatchDeps,
+): Promise<WebhookDispatchResult> {
   // Host-egress guard at the primitive boundary: only http(s), the target
   // host must resolve to a public address (unless operator-allowlisted),
   // and redirects are never followed — a 3xx could point at an internal/
@@ -145,7 +185,7 @@ export async function performWebhookDispatch(spec: WebhookSpec): Promise<Webhook
     return { ok: false, error: `unsupported url scheme "${url.protocol}"` };
   }
 
-  const headers = buildWebhookHeaders(spec);
+  const headers = await buildWebhookHeaders(spec, deps);
   if (!headers.ok) return headers;
 
   const target = await resolveWebhookFetchTarget(spec.url, url, headers.headers);

package/src/subscription-stripe/__tests__/plugin-methods.test.ts

@@ -26,6 +26,7 @@ import {
   createStripePortalSession,
   createStripePriceCache,
   createStripeRetrievePrices,
+  createStripeRetrieveSubscription,
 } from "../plugin-methods";
 import type { StripeCtxRuntime } from "../runtime";
 
@@ -830,3 +831,119 @@ describe("createStripePlanSwitchSession", () => {
     expect(retrieveMock).not.toHaveBeenCalled();
   });
 });
+
+// =============================================================================
+// retrieveSubscription — sync-subscriptions backfill, same status/tier/
+// period-end/cancel_at mapping as verify-webhook.ts's mapStripeSubscriptionState.
+// =============================================================================
+
+const PRICE_TO_TIER = { price_retrieve_pro: "pro" };
+
+function stripeSubscriptionForRetrieve(overrides: Record<string, unknown> = {}) {
+  return stripeSubscription({
+    status: "active",
+    items: {
+      data: [
+        {
+          id: "si_001",
+          price: stripePrice({ id: "price_retrieve_pro" }),
+          quantity: 1,
+          current_period_end: 1_800_000_000,
+        },
+      ],
+    },
+    cancel_at: null,
+    cancel_at_period_end: false,
+    ...overrides,
+  });
+}
+
+describe("createStripeRetrieveSubscription", () => {
+  test("maps a live subscription to a ProviderSubscriptionSnapshot", async () => {
+    const stripe = buildStripe();
+    spyOn(stripe.subscriptions, "retrieve").mockResolvedValue(stripeSubscriptionForRetrieve());
+    const retrieve = createStripeRetrieveSubscription(ctxRuntime(stripe), {
+      priceToTier: PRICE_TO_TIER,
+    });
+
+    const result = await retrieve(stubCtx, "sub_switch_001");
+
+    expect(result).toEqual({
+      providerCustomerId: "cus_switch_001",
+      providerSubscriptionId: "sub_switch_001",
+      status: "active",
+      tier: "pro",
+      currentPeriodEnd: "2027-01-15T08:00:00Z",
+      cancelAt: null,
+      rawPayload: JSON.stringify(stripeSubscriptionForRetrieve()),
+    });
+  });
+
+  test("a resource_missing StripeInvalidRequestError resolves to null instead of throwing", async () => {
+    const stripe = buildStripe();
+    spyOn(stripe.subscriptions, "retrieve").mockRejectedValue(
+      new Stripe.errors.StripeInvalidRequestError({
+        message: "No such subscription: 'sub_gone'",
+        code: "resource_missing",
+      }),
+    );
+    const retrieve = createStripeRetrieveSubscription(ctxRuntime(stripe), {
+      priceToTier: PRICE_TO_TIER,
+    });
+
+    expect(await retrieve(stubCtx, "sub_gone")).toBeNull();
+  });
+
+  test("an unmapped priceId resolves to null (same as verify-webhook's silent-drop)", async () => {
+    const stripe = buildStripe();
+    spyOn(stripe.subscriptions, "retrieve").mockResolvedValue(
+      stripeSubscriptionForRetrieve({
+        items: {
+          data: [
+            {
+              id: "si_001",
+              price: stripePrice({ id: "price_unmapped" }),
+              quantity: 1,
+              current_period_end: 1_800_000_000,
+            },
+          ],
+        },
+      }),
+    );
+    const retrieve = createStripeRetrieveSubscription(ctxRuntime(stripe), {
+      priceToTier: PRICE_TO_TIER,
+    });
+
+    expect(await retrieve(stubCtx, "sub_switch_001")).toBeNull();
+  });
+
+  test("a non-resource_missing Stripe error rethrows", async () => {
+    const stripe = buildStripe();
+    spyOn(stripe.subscriptions, "retrieve").mockRejectedValue(
+      new Stripe.errors.StripeInvalidRequestError({
+        message: "rate limited",
+        code: "rate_limit",
+      }),
+    );
+    const retrieve = createStripeRetrieveSubscription(ctxRuntime(stripe), {
+      priceToTier: PRICE_TO_TIER,
+    });
+
+    await expect(retrieve(stubCtx, "sub_switch_001")).rejects.toBeInstanceOf(
+      Stripe.errors.StripeInvalidRequestError,
+    );
+  });
+
+  test("a scheduled cancel_at is mapped through", async () => {
+    const stripe = buildStripe();
+    spyOn(stripe.subscriptions, "retrieve").mockResolvedValue(
+      stripeSubscriptionForRetrieve({ cancel_at: 1_850_000_000 }),
+    );
+    const retrieve = createStripeRetrieveSubscription(ctxRuntime(stripe), {
+      priceToTier: PRICE_TO_TIER,
+    });
+
+    const result = await retrieve(stubCtx, "sub_switch_001");
+    expect(result?.cancelAt).toBe("2028-08-16T00:53:20Z");
+  });
+});

package/src/subscription-stripe/feature.ts

@@ -53,6 +53,7 @@ import {
   createStripePortalSession,
   createStripePriceCache,
   createStripeRetrievePrices,
+  createStripeRetrieveSubscription,
 } from "./plugin-methods";
 import { createStripeRuntimes } from "./runtime";
 import { verifyAndParseStripeWebhook } from "./verify-webhook";
@@ -144,7 +145,7 @@ export function createSubscriptionStripeFeature(
   validateOneOffPriceIds(options.oneOffPriceIds ?? []);
   return defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
     r.describe(
-      'Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, `retrievePrices` (10-minute TTL-cached price lookup for the billing-plans catalog) and `createPlanSwitchSession` (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), plus `isBillingEnabled` (billingLive + an api-key existence probe, no secret read).',
+      'Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, `retrievePrices` (10-minute TTL-cached price lookup for the billing-plans catalog), `createPlanSwitchSession` (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), `retrieveSubscription` (live provider-side snapshot for the `sync-subscriptions` backfill job, mapped identically to the webhook path), plus `isBillingEnabled` (billingLive + an api-key existence probe, no secret read).',
     );
     r.uiHints({
       displayLabel: "Billing · Stripe",
@@ -234,6 +235,9 @@ export function createSubscriptionStripeFeature(
       oneOffPriceIds: options.oneOffPriceIds ?? [],
       isBillingEnabled: runtimes.ctx.isBillingEnabled,
       retrievePrices: createStripeRetrievePrices(runtimes.ctx, priceCache),
+      retrieveSubscription: createStripeRetrieveSubscription(runtimes.ctx, {
+        priceToTier: options.priceToTier ?? {},
+      }),
       createPlanSwitchSession: createStripePlanSwitchSession(
         runtimes.ctx,
         priceCache,

package/src/subscription-stripe/plugin-methods.ts

@@ -18,6 +18,7 @@ import { createHash } from "node:crypto";
 import {
   KNOWN_RECURRING_INTERVALS,
   type ProviderPrice,
+  type ProviderSubscriptionSnapshot,
   type RecurringInterval,
   type SubscriptionProviderPlugin,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
@@ -25,6 +26,7 @@ import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import Stripe from "stripe";
 import type { StripeCtxRuntime } from "./runtime";
+import { mapStripeSubscriptionState } from "./verify-webhook";
 
 // =============================================================================
 // createCheckoutSession
@@ -127,6 +129,57 @@ export function createStripeCancelSubscription(runtime: StripeCtxRuntime) {
   };
 }
 
+// =============================================================================
+// retrieveSubscription — live provider-side snapshot for the
+// sync-subscriptions backfill job
+// =============================================================================
+//
+// Same status/tier/period-end/cancel_at mapping as verify-webhook.ts, via
+// the shared mapStripeSubscriptionState — the sync path and the webhook path
+// must never disagree on what a given Stripe subscription object means.
+
+export type StripeRetrieveSubscriptionOptions = {
+  readonly priceToTier: Readonly<Record<string, string>>;
+};
+
+function isResourceMissingStripeError(error: unknown): boolean {
+  return (
+    error instanceof Stripe.errors.StripeInvalidRequestError && error.code === "resource_missing"
+  );
+}
+
+export function createStripeRetrieveSubscription(
+  runtime: StripeCtxRuntime,
+  { priceToTier }: StripeRetrieveSubscriptionOptions,
+) {
+  return async (
+    ctx: HandlerContext,
+    providerSubscriptionId: string,
+  ): Promise<ProviderSubscriptionSnapshot | null> => {
+    const stripe = await runtime.clientForCtx(ctx);
+    let subscription: Stripe.Subscription;
+    try {
+      subscription = await stripe.subscriptions.retrieve(providerSubscriptionId);
+    } catch (error) {
+      if (isResourceMissingStripeError(error)) return null;
+      throw error;
+    }
+
+    const state = mapStripeSubscriptionState(subscription, priceToTier);
+    if (!state) return null;
+
+    return {
+      providerCustomerId:
+        typeof subscription.customer === "string"
+          ? subscription.customer
+          : subscription.customer.id,
+      providerSubscriptionId: subscription.id,
+      ...state,
+      rawPayload: JSON.stringify(subscription),
+    };
+  };
+}
+
 // =============================================================================
 // retrievePrices — bulk price lookup for the billing-plans catalog
 // =============================================================================

package/src/subscription-stripe/verify-webhook.ts

@@ -137,32 +137,14 @@ export function verifyAndParseStripeWebhook(
       return null;
     }
 
-    // 5. Price-to-tier-Mapping. Stripe-subscription hat items[0].price.id.
-    const priceId = sub.items.data[0]?.price.id;
-    if (!priceId) {
+    // 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 tier = options.priceToTier[priceId];
-    if (!tier) {
-      // Price-id nicht im Mapping → App-Owner hat den Stripe-price
-      // angelegt aber nicht zur tier zugeordnet. Drop silent.
-      return null;
-    }
-
-    // 6. Status-Mapping + period-end. Stripe hat den period-end seit
-    //    2024 vom subscription-level auf item-level migriert (=
-    //    subscription.items.data[i].current_period_end). Wir lesen
-    //    das vom ersten item; multi-item-subs (Add-Ons) sind kein
-    //    Phase-5-Scope.
-    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 {
       providerEventId: event.id,
@@ -171,15 +153,57 @@ export function verifyAndParseStripeWebhook(
       tenantId,
       providerCustomerId: typeof sub.customer === "string" ? sub.customer : sub.customer.id,
       providerSubscriptionId: sub.id,
-      status,
-      tier,
-      currentPeriodEnd,
-      cancelAt,
+      ...state,
       rawPayload: JSON.stringify(event),
     };
   };
 }
 
+// =============================================================================
+// 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
 // =============================================================================