@cosmicdrift/kumiko-bundled-features 0.41.1 → 0.43.0

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

@@ -4,7 +4,9 @@
 // Werden vom Plugin-build (feature.ts) als methods auf dem
 // SubscriptionProviderPlugin registriert. Anders als
 // verifyAndParseWebhook (= pre-tenant) bekommen diese den vollen
-// HandlerContext (für ggf. tenant-spezifische Lookups).
+// HandlerContext — sie lösen den Stripe-Client zur CALL-Zeit aus dem
+// runtime auf (api-key aus system-secrets, audited), statt aus einem
+// mount-time-Closure. Key-Rotation wirkt damit ohne Redeploy.
 //
 // **Type-Ableitung:** die options-shapes der drei methods werden
 // **direkt vom Plugin-Contract** abgeleitet (`Parameters<NonNullable
@@ -14,7 +16,7 @@
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
-import type Stripe from "stripe";
+import type { StripeCtxRuntime } from "./runtime";
 
 // =============================================================================
 // createCheckoutSession
@@ -30,8 +32,16 @@ export type StripeCheckoutOptions = Parameters<
   NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
 >[1];
 
-export function createStripeCheckoutSession(stripe: Stripe) {
-  return async (_ctx: HandlerContext, options: StripeCheckoutOptions): Promise<{ url: string }> => {
+export function createStripeCheckoutSession(runtime: StripeCtxRuntime) {
+  return async (ctx: HandlerContext, options: StripeCheckoutOptions): Promise<{ url: string }> => {
+    // #104-Invariante: ohne billing-live darf keine Stripe-Session
+    // entstehen (sk_test_-Keys in prod erzeugen sonst einen Test-Mode-
+    // Checkout). Throw VOR jedem Stripe-Call. Früher hielt diese Schranke
+    // das ungemountete Plugin; jetzt mountet stripe immer, also gatet der
+    // billing-live-config-key write-side.
+    await runtime.assertBillingLive(ctx);
+    const stripe = await runtime.clientForCtx(ctx);
+
     const session = await stripe.checkout.sessions.create({
       mode: "subscription",
       line_items: [{ price: options.priceId, quantity: 1 }],
@@ -66,8 +76,9 @@ export type StripePortalOptions = Parameters<
   NonNullable<SubscriptionProviderPlugin["createPortalSession"]>
 >[1];
 
-export function createStripePortalSession(stripe: Stripe) {
-  return async (_ctx: HandlerContext, options: StripePortalOptions): Promise<{ url: string }> => {
+export function createStripePortalSession(runtime: StripeCtxRuntime) {
+  return async (ctx: HandlerContext, options: StripePortalOptions): Promise<{ url: string }> => {
+    const stripe = await runtime.clientForCtx(ctx);
     const session = await stripe.billingPortal.sessions.create({
       customer: options.providerCustomerId,
       return_url: options.returnUrl,
@@ -84,8 +95,9 @@ export function createStripePortalSession(stripe: Stripe) {
 // state-update läuft über den normalen webhook-pfad. Diese function
 // triggert nur die API-Cancellation.
 
-export function createStripeCancelSubscription(stripe: Stripe) {
-  return async (_ctx: HandlerContext, providerSubscriptionId: string): Promise<void> => {
+export function createStripeCancelSubscription(runtime: StripeCtxRuntime) {
+  return async (ctx: HandlerContext, providerSubscriptionId: string): Promise<void> => {
+    const stripe = await runtime.clientForCtx(ctx);
     await stripe.subscriptions.cancel(providerSubscriptionId);
   };
 }

package/src/subscription-stripe/runtime.ts

@@ -0,0 +1,156 @@
+// 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 the **secrets** feature, stored
+//     under SYSTEM_TENANT_ID (Stripe is app-wide, not per-tenant — secrets
+//     v1 only declares `scope:"tenant"`, so app-wide values live under the
+//     system tenant, the same convention the config-resolver uses for
+//     system-scope rows).
+//   - `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,
+  type SecretKeyHandle,
+  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 Stripe from "stripe";
+import { STRIPE_API_VERSION, SUBSCRIPTION_STRIPE_FEATURE } from "./constants";
+
+const API_KEY_HINT =
+  "Set the system-scoped Stripe API key via secrets:write:set (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;
+    const client = new Stripe(apiKey, { apiVersion: STRIPE_API_VERSION });
+    cache.set(apiKey, client);
+    return client;
+  };
+}
+
+export type StripeRuntimeDeps = {
+  readonly apiKeyHandle: SecretKeyHandle;
+  readonly webhookSecretHandle: SecretKeyHandle;
+  readonly billingLiveHandle: ConfigKeyHandle<"boolean">;
+  readonly fallback: { readonly apiKey?: string; readonly webhookSecret?: string };
+};
+
+/** 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). */
+  readonly assertBillingLive: (ctx: HandlerContext) => Promise<void>;
+};
+
+/** 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,
+      );
+      key = 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: SecretKeyHandle,
+    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);
+      const value = got?.reveal();
+      if (value && value.length > 0) return value;
+    }
+    return fallback && fallback.length > 0 ? fallback : undefined;
+  }
+
+  return {
+    ctx: {
+      clientForCtx: async (ctx) => clientFor(await ctxApiKey(ctx)),
+      assertBillingLive: async (ctx) => {
+        const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+        if (live !== true) {
+          throw new FeatureDisabledError(SUBSCRIPTION_STRIPE_FEATURE, "create-checkout-session");
+        }
+      },
+    },
+    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/src/subscription-stripe/verify-webhook.ts

@@ -12,7 +12,16 @@
 //   3. Stripe-payload → SubscriptionEvent normalisieren
 //      (status-mapping, tenant-id aus metadata, price-to-tier-Lookup).
 //
-// **Invoice-event lazy-fetch (Phase 5.2b):**
+// **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:**
 // Bei `invoice.paid` und `invoice.payment_failed` enthält der webhook-
 // payload nur die subscription-id (Stripe-Webhooks expanden subscription
 // nicht automatisch). Plugin macht einen lazy-fetch via
@@ -29,50 +38,54 @@ import {
   type SubscriptionStatus,
   SubscriptionStatuses,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type Stripe from "stripe";
 import { STRIPE_PROVIDER_NAME, StripeEventTypes } from "./constants";
+import type { StripeWebhookRuntime } from "./runtime";
 
 // =============================================================================
 // Sig-verify + parse
 // =============================================================================
 
 export type StripeWebhookOptions = {
-  /** Webhook-secret aus dem Stripe-Dashboard. **App-wide**, nicht
-   *  per-tenant. Liest aus ENV-VAR oder system-config beim Plugin-
-   *  build. */
-  readonly webhookSecret: string;
   /** Price-to-tier-Map. Plugin liest die price-id aus dem event und
-   *  mapped auf tier-name. Fehlt die price-id im Mapping → null. */
+   *  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`. Closure über die `options` + den shared
- * Stripe-Client (kein ctx-arg — das ist die Pre-tenant-resolution-Phase).
- *
- * **Shared Stripe-Client:** Der Caller (feature.ts) baut EINEN Stripe-
- * Client beim mount und gibt ihn an alle vier plugin-methods weiter.
- * Konstruktor-API-version-pin ist damit zentral; verify-webhook nutzt
- * den client für `webhooks.constructEvent` (sig-verify) + lazy-fetch
- * der invoice-events.
+ * `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(
-  stripe: Stripe,
+  runtime: StripeWebhookRuntime,
   options: StripeWebhookOptions,
-): (rawBody: string, headers: Record<string, string>) => Promise<SubscriptionEvent | null> {
-  return async (rawBody, headers) => {
+): (
+  rawBody: string,
+  headers: Record<string, string>,
+  systemSecrets?: SecretsContext,
+) => Promise<SubscriptionEvent | 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.
     let event: Stripe.Event;
     try {
-      event = await stripe.webhooks.constructEventAsync(rawBody, sigHeader, options.webhookSecret);
+      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}`);
@@ -87,7 +100,7 @@ export function verifyAndParseStripeWebhook(
     // 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, Phase 5.2b).
+    //    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
@@ -193,8 +206,7 @@ export function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): Subsc
 
 /** 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
- *  (Phase 5.2b). */
+ *  und brauchen einen lazy-fetch via stripe.subscriptions.retrieve. */
 async function extractSubscriptionFromEvent(
   event: Stripe.Event,
   stripe: Stripe,