@cosmicdrift/kumiko-bundled-features 0.41.0 → 0.42.0

package/src/subscription-stripe/__tests__/stripe-foundation.integration.test.ts

@@ -13,25 +13,43 @@
 // Verdrahtungs-Bugs ab.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
 import {
   billingFoundationFeature,
   createSubscriptionWebhookHandler,
   type SubscriptionProviderPlugin,
   subscriptionAggregateId,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable, loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
   testTenantId,
+  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { Hono } from "hono";
 import Stripe from "stripe";
+import { configValuesTable, createConfigFeature } from "../../config";
+import { createConfigAccessorFactory } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import {
+  createSecretsContext,
+  createSecretsFeature,
+  type SecretsContext,
+  tenantSecretsTable,
+} from "../../secrets";
 import { createSubscriptionStripeFeature } from "../feature";
 
+// Qualified-names der runtime-keys (drift-pin: müssen 1:1 dem entsprechen,
+// was r.secret(...) im feature build qualifiziert — `subscription-stripe:
+// secret:<shortName>`). Scenario 5 seedet darüber + beweist die Resolution.
+const API_KEY_SECRET_QN = "subscription-stripe:secret:api-key";
+const WEBHOOK_SECRET_QN = "subscription-stripe:secret:webhook-secret";
+
 // =============================================================================
 // Setup
 // =============================================================================
@@ -43,52 +61,93 @@ const PRICE_TO_TIER = { price_pro_monthly: "pro", price_business_yearly: "busine
 let stack: TestStack;
 let db: DbConnection;
 let webhookApp: Hono;
+/** Zweite webhook-app MIT system-secrets gewired — für Scenario 5
+ *  (runtime-secret-Pfad). */
+let webhookAppWithSecrets: Hono;
+let secretsCtx: SecretsContext;
 
 const stripeForFixtures = new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
 
 beforeAll(async () => {
+  // subscription-stripe requires jetzt config + secrets. Scenarios 1–4
+  // nutzen den factory-fallback (kein system-secret geseedet, kein
+  // systemSecrets gewired) → resolve fällt auf die options-Keys zurück.
   const stripeFeature = createSubscriptionStripeFeature({
     webhookSecret: TEST_SECRET,
     apiKey: TEST_API_KEY,
     priceToTier: PRICE_TO_TIER,
   });
 
+  const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ encryption });
+  const masterKeyProvider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
   stack = await setupTestStack({
-    features: [billingFoundationFeature, stripeFeature],
+    features: [
+      createConfigFeature(),
+      createSecretsFeature(),
+      billingFoundationFeature,
+      stripeFeature,
+    ],
+    masterKeyProvider,
+    extraContext: ({ db: ctxDb, registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      secrets: createSecretsContext({ db: ctxDb, masterKeyProvider }),
+    }),
   });
   db = stack.db;
   // subscriptionsProjectionTable wird von setupTestStack automatisch
-  // gepusht (r.projection mit `table`-Property → auto-push).
+  // gepusht (r.projection mit `table`-Property → auto-push). config +
+  // secrets brauchen ihre Tabellen explizit.
   await createEventsTable(db);
+  await unsafePushTables(db, { configValuesTable, tenant_secrets: tenantSecretsTable });
+  // Standalone-secrets-context (gleiche KEK) zum direkten Seeden +
+  // als systemSecrets für die zweite webhook-app.
+  secretsCtx = createSecretsContext({ db, masterKeyProvider });
 
   // Webhook-app: Hono mit der webhook-handler-Route.
   // dispatchWrite ruft `stack.http.write` mit dem System-User des
   // resolved-Tenants — das ist exakt was der App-Builder im echten
-  // bin/server.ts via extraRoutes wireup macht.
-  webhookApp = new Hono();
-  webhookApp.post(
-    "/api/subscription/webhook/:providerName",
-    createSubscriptionWebhookHandler({
-      dispatchWrite: async ({ handlerQn, payload, tenantId }) => {
-        const systemUser = createTestUser({
-          id: 1,
-          tenantId: tenantId as TenantId,
-          roles: ["SystemAdmin"],
-        });
-        const res = await stack.http.write(handlerQn, payload, systemUser);
-        const body = await res.json();
-        return body.isSuccess
-          ? { isSuccess: true, data: body.data }
-          : { isSuccess: false, error: body.error };
-      },
-      resolveProvider: (providerName) => {
-        const usage = stack.registry
-          .getExtensionUsages("subscriptionProvider")
-          .find((u) => u.entityName === providerName);
-        return usage?.options as SubscriptionProviderPlugin | undefined;
-      },
-    }),
-  );
+  // bin/server.ts via extraRoutes wireup macht. `systemSecrets` optional:
+  // ohne → factory-fallback-Pfad (Scenarios 1–4); mit → runtime-secret-
+  // Pfad (Scenario 5), exakt wie der App-Owner createSecretsContext wired.
+  const mountWebhook = (systemSecrets?: SecretsContext): Hono => {
+    const app = new Hono();
+    app.post(
+      "/api/subscription/webhook/:providerName",
+      createSubscriptionWebhookHandler({
+        dispatchWrite: async ({ handlerQn, payload, tenantId }) => {
+          const systemUser = createTestUser({
+            id: 1,
+            tenantId: tenantId as TenantId,
+            roles: ["SystemAdmin"],
+          });
+          const res = await stack.http.write(handlerQn, payload, systemUser);
+          const body = await res.json();
+          return body.isSuccess
+            ? { isSuccess: true, data: body.data }
+            : { isSuccess: false, error: body.error };
+        },
+        resolveProvider: (providerName) => {
+          const usage = stack.registry
+            .getExtensionUsages("subscriptionProvider")
+            .find((u) => u.entityName === providerName);
+          return usage?.options as SubscriptionProviderPlugin | undefined;
+        },
+        ...(systemSecrets && { systemSecrets }),
+      }),
+    );
+    return app;
+  };
+  webhookApp = mountWebhook();
+  webhookAppWithSecrets = mountWebhook(secretsCtx);
 });
 
 afterAll(async () => {
@@ -149,8 +208,8 @@ async function signEvent(payload: string, secret = TEST_SECRET): Promise<string>
   });
 }
 
-async function postStripeWebhook(payload: string, sig: string) {
-  return webhookApp.request("/api/subscription/webhook/stripe", {
+async function postStripeWebhook(payload: string, sig: string, app: Hono = webhookApp) {
+  return app.request("/api/subscription/webhook/stripe", {
     method: "POST",
     body: payload,
     headers: { "stripe-signature": sig, "content-type": "application/json" },
@@ -310,3 +369,69 @@ describe("scenario 4: ignored event-types pass through", () => {
     expect(subs.rows).toHaveLength(0);
   });
 });
+
+// =============================================================================
+// Scenario 5: runtime-secret-Pfad — webhook verifiziert gegen ein in der DB
+// geseedetes system-secret (NICHT gegen den factory-fallback). Beweist die
+// end-to-end-Resolution + dass das system-secret den Fallback schlägt
+// (Rotation ohne Redeploy).
+// =============================================================================
+
+const SEEDED_WEBHOOK_SECRET = "whsec_runtime_seeded_distinct";
+const SEEDED_API_KEY = "sk_test_runtime_seeded";
+
+describe("scenario 5: runtime-secret resolution", () => {
+  test("seeded system-secret schlägt factory-fallback: sig gegen seeded secret → 200 + DB-row", async () => {
+    // Seed beide Keys als echte (encrypted) system-secrets unter
+    // SYSTEM_TENANT_ID — exakt was der Bridge-Seed / die Admin-UI in prod
+    // schreibt. SEEDED_WEBHOOK_SECRET ≠ TEST_SECRET (der fallback).
+    await secretsCtx.set(SYSTEM_TENANT_ID, API_KEY_SECRET_QN, SEEDED_API_KEY, {
+      updatedBy: "test",
+    });
+    await secretsCtx.set(SYSTEM_TENANT_ID, WEBHOOK_SECRET_QN, SEEDED_WEBHOOK_SECRET, {
+      updatedBy: "test",
+    });
+
+    const tenantStringId = testTenantId(4005);
+    const payload = JSON.stringify(
+      buildStripeSubscriptionEvent({
+        eventId: "evt_4005_runtime",
+        tenantId: tenantStringId,
+        subscriptionId: "sub_4005",
+        customerId: "cus_4005",
+        priceId: "price_pro_monthly",
+      }),
+    );
+    // Signiert mit dem GESEEDETEN secret — würde der webhook noch den
+    // fallback (TEST_SECRET) nutzen, schlüge die Verifikation fehl.
+    const sig = await signEvent(payload, SEEDED_WEBHOOK_SECRET);
+
+    const res = await postStripeWebhook(payload, sig, webhookAppWithSecrets);
+    expect(res.status).toBe(200);
+
+    const admin = createTestUser({
+      id: 4005,
+      tenantId: tenantStringId,
+      roles: ["TenantAdmin", "SystemAdmin"],
+    });
+    const subs = (await stack.http.queryOk(
+      "billing-foundation:query:subscription:list",
+      {},
+      admin,
+    )) as { rows: Array<Record<string, unknown>> };
+    expect(subs.rows).toHaveLength(1);
+    expect(subs.rows[0]?.["providerSubscriptionId"]).toBe("sub_4005");
+    expect(subs.rows[0]?.["tier"]).toBe("pro");
+  });
+
+  test("sig gegen den (jetzt obsoleten) fallback-secret → 401, wenn system-secret gesetzt ist", async () => {
+    // Drift-pin der Präzedenz: nachdem das system-secret gesetzt ist,
+    // darf der alte env/fallback-secret NICHT mehr verifizieren.
+    const payload = JSON.stringify(
+      buildStripeSubscriptionEvent({ eventId: "evt_4005_stale", tenantId: testTenantId(4006) }),
+    );
+    const sigWithStaleFallback = await signEvent(payload, TEST_SECRET);
+    const res = await postStripeWebhook(payload, sigWithStaleFallback, webhookAppWithSecrets);
+    expect(res.status).toBe(401);
+  });
+});

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

@@ -13,6 +13,7 @@ import {
   SubscriptionStatuses,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import Stripe from "stripe";
+import type { StripeWebhookRuntime } from "../runtime";
 import {
   mapStripeEventType,
   mapStripeStatus,
@@ -28,6 +29,12 @@ const TEST_API_KEY = "sk_test_dummy_apikey";
 
 const stripeForFixtures = new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
 
+/** Test-runtime: liefert den fixture-Client + TEST_SECRET (statt sie aus
+ *  system-secrets aufzulösen — die Resolution testet runtime.test.ts). */
+function webhookRuntime(webhookSecret = TEST_SECRET): StripeWebhookRuntime {
+  return { resolve: async () => ({ stripe: stripeForFixtures, webhookSecret }) };
+}
+
 function buildSubscriptionEvent(overrides: {
   eventType?: string;
   eventId?: string;
@@ -95,8 +102,7 @@ async function signEvent(payload: string, secret = TEST_SECRET): Promise<string>
 // =============================================================================
 
 describe("verifyAndParseStripeWebhook — sig-verify", () => {
-  const verify = verifyAndParseStripeWebhook(stripeForFixtures, {
-    webhookSecret: TEST_SECRET,
+  const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
     priceToTier: { price_pro_monthly: "pro" },
   });
 
@@ -142,8 +148,7 @@ describe("verifyAndParseStripeWebhook — sig-verify", () => {
 // =============================================================================
 
 describe("verifyAndParseStripeWebhook — event-filter", () => {
-  const verify = verifyAndParseStripeWebhook(stripeForFixtures, {
-    webhookSecret: TEST_SECRET,
+  const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
     priceToTier: { price_pro_monthly: "pro" },
   });
 
@@ -211,8 +216,7 @@ describe("verifyAndParseStripeWebhook — event-filter", () => {
 // =============================================================================
 
 describe("verifyAndParseStripeWebhook — tenant-resolution + price-to-tier", () => {
-  const verify = verifyAndParseStripeWebhook(stripeForFixtures, {
-    webhookSecret: TEST_SECRET,
+  const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
     priceToTier: { price_pro_monthly: "pro", price_business_yearly: "business" },
   });
 

package/src/subscription-stripe/constants.ts

@@ -6,6 +6,17 @@ export const SUBSCRIPTION_STRIPE_FEATURE = "subscription-stripe" as const;
 // `/api/subscription/webhook/stripe`.
 export const STRIPE_PROVIDER_NAME = "stripe" as const;
 
+// Stripe-API-version-pin. Zentral, damit jeder Client (egal ob mount-time-
+// fallback oder runtime-rotiert) dieselbe API-Version spricht.
+export const STRIPE_API_VERSION = "2026-04-22.dahlia" as const;
+
+// Secret- + config-key short-names. Qualified zu `subscription-stripe:<name>`
+// (secrets) bzw. `subscription-stripe:config:<name>` (config) beim
+// registry-build.
+export const STRIPE_API_KEY_SECRET = "api-key" as const;
+export const STRIPE_WEBHOOK_SECRET_SECRET = "webhook-secret" as const;
+export const STRIPE_BILLING_LIVE_CONFIG = "billingLive" as const;
+
 // =============================================================================
 // Stripe-event-types die wir auf normalisierte SubscriptionEventTypes
 // mappen. Stripe hat ~80 event-types insgesamt; wir filtern auf 5.

package/src/subscription-stripe/feature.ts

@@ -1,151 +1,175 @@
-// kumiko-feature-version: 1
+// kumiko-feature-version: 2
 //
-// subscription-stripe — Stripe-Plugin für die subscription-foundation
+// subscription-stripe — Stripe-Plugin für die billing-foundation
 // Plugin-API.
 //
-// **Factory-Pattern (= createSubscriptionStripeFeature(options)):**
-// Im Gegensatz zu mail-transport-smtp / file-provider-s3 (die ihre
-// secrets aus tenant-secrets lesen) ist Stripe's webhook-secret
-// **app-wide** — App-Owner hat einen Stripe-account, alle Webhooks
-// gehen dorthin. Plugin braucht den secret beim webhook-sig-verify-
-// Zeitpunkt, der ist PRE-tenant-resolution (kein ctx).
+// **Runtime-config (v2):** Stripe-credentials + der billing-live-Master-
+// Switch kommen ZUR LAUFZEIT aus config/secrets, nicht mehr aus einem
+// mount-time-Closure. Damit lassen sich Keys rotieren und prod live-
+// schalten ohne Redeploy.
+//   - `subscription-stripe:api-key` + `:webhook-secret` → **secrets**
+//     (encrypted-at-rest), gespeichert/gelesen unter SYSTEM_TENANT_ID
+//     (Stripe ist app-wide, secrets-v1 deklariert nur `scope:"tenant"`,
+//     also lebt der app-wide-Wert unter dem System-Tenant — dieselbe
+//     Konvention die der config-resolver für system-scope-rows nutzt).
+//   - `subscription-stripe:config:billingLive` → **system config**
+//     (boolean, default false). Der Master-Switch: ohne ihn darf kein
+//     checkout eine Stripe-Session erzeugen (#104-Invariante, write-side
+//     im createCheckoutSession-Gate durchgesetzt).
 //
-// Lösung: factory-Funktion `createSubscriptionStripeFeature(options)`
-// liest webhook-secret + apiKey beim mount-time aus dem Caller (= App-
-// Builder's bin/server.ts der's aus process.env zieht). Closure
-// hält's für den verifyAndParseWebhook-call.
+// **Factory-options als Fallback:** `createSubscriptionStripeFeature({
+// apiKey, webhookSecret, priceToTier })` bleibt — apiKey/webhookSecret
+// sind jetzt OPTIONAL und dienen nur als Fallback während der env→secrets-
+// Bridge-Phase und in Tests, die keinen secrets-context wiren. `priceToTier`
+// (Stripe-price-id → app-tier-name) bleibt eine factory-option: app-
+// spezifisch, kein Secret, ändert sich selten.
 //
-// Beispiel-Verwendung in run-config.ts:
-//
-//   import { createSubscriptionStripeFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
-//
-//   const features = [
-//     billingFoundationFeature,
-//     createSubscriptionStripeFeature({
-//       webhookSecret: process.env.STRIPE_WEBHOOK_SECRET ?? "",
-//       apiKey: process.env.STRIPE_API_KEY ?? "",
-//       priceToTier: {
-//         "price_1ABC": "pro",
-//         "price_1XYZ": "business",
-//       },
-//     }),
-//   ];
-//
-// **Pattern-Vorbild:** mirrors createFeatureTogglesFeature(options) —
-// gleiche factory-Form für features die module-load-time-Konfiguration
-// haben (analog zum FeatureToggle-runtime-holder).
+// **Webhook + system-secrets:** verifyAndParseWebhook ist pre-tenant
+// (kein ctx). Der billing-foundation-webhook-handler reicht einen system-
+// scoped SecretsContext als 3. Arg durch, aus dem der Plugin api-key +
+// webhook-secret un-audited liest (sanctioned framework-internal read).
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import Stripe from "stripe";
+import {
+  createSystemConfig,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { STRIPE_PROVIDER_NAME, SUBSCRIPTION_STRIPE_FEATURE } from "./constants";
+import {
+  STRIPE_API_KEY_SECRET,
+  STRIPE_BILLING_LIVE_CONFIG,
+  STRIPE_PROVIDER_NAME,
+  STRIPE_WEBHOOK_SECRET_SECRET,
+  SUBSCRIPTION_STRIPE_FEATURE,
+} from "./constants";
 import {
   createStripeCancelSubscription,
   createStripeCheckoutSession,
   createStripePortalSession,
 } from "./plugin-methods";
+import { createStripeRuntimes } from "./runtime";
 import { verifyAndParseStripeWebhook } from "./verify-webhook";
 
 /**
- * Env-vars contract for the `subscription-stripe` feature.
- *
- * The feature itself reads via factory-options (`createSubscriptionStripeFeature({
- * webhookSecret, apiKey })`), so the schema is a Kumiko-pattern contract:
- * apps that mount stripe SHOULD load `STRIPE_WEBHOOK_SECRET` / `STRIPE_API_KEY`
- * from env and forward them. `composeEnvSchema({ features: [stripeFeature] })`
- * surfaces missing/empty values at boot, before
- * `createSubscriptionStripeFeature` throws on `webhookSecret.length === 0`.
+ * Env-vars contract for the `subscription-stripe` feature — now a **bridge
+ * contract**: both fields are optional. v2 reads credentials from secrets
+ * at runtime; `STRIPE_WEBHOOK_SECRET` / `STRIPE_API_KEY` are only consumed
+ * as factory-fallback during the env→secrets transition. The regex still
+ * validates the shape when a value IS present, so a typo'd bridge key fails
+ * at boot rather than at the first webhook.
  */
 export const subscriptionStripeEnvSchema = z.object({
   STRIPE_WEBHOOK_SECRET: z
     .string()
     .regex(/^whsec_/, "STRIPE_WEBHOOK_SECRET must start with 'whsec_'")
-    .describe("Stripe webhook-signing secret (`whsec_...` from the Stripe dashboard).")
-    .meta({ kumiko: { pulumi: { secret: true } } }),
+    .describe("Stripe webhook-signing secret (`whsec_...`). Bridge-fallback — prefer the secret.")
+    .meta({ kumiko: { pulumi: { secret: true } } })
+    .optional(),
   STRIPE_API_KEY: z
     .string()
     .regex(
       /^(sk|rk)_(test|live)_/,
       "STRIPE_API_KEY must start with 'sk_test_'/'sk_live_' or a restricted 'rk_test_'/'rk_live_' key",
     )
-    .describe("Stripe API key (`sk_live_...` / `sk_test_...`, restricted `rk_...` keys allowed).")
-    .meta({ kumiko: { pulumi: { secret: true } } }),
+    .describe(
+      "Stripe API key (`sk_live_...` / `sk_test_...`). Bridge-fallback — prefer the secret.",
+    )
+    .meta({ kumiko: { pulumi: { secret: true } } })
+    .optional(),
 });
 
 export type SubscriptionStripeOptions = {
-  /** Webhook-secret aus dem Stripe-Dashboard. App-wide. Plugin throws
-   *  beim runtime wenn empty (= App-Owner hat sub-stripe gemountet
-   *  aber Stripe-Account nicht konfiguriert). */
-  readonly webhookSecret: string;
-  /** Stripe-API-key (sk_live_... / sk_test_...). Heute nur für
-   *  constructEvent-API-Version-Pin gebraucht; Phase 5.2b nutzt's
-   *  für outgoing-API-calls (createPortalSession etc.). */
-  readonly apiKey: string;
-  /** Price-to-tier-Mapping. Plugin liest die price-id aus Stripe-event
-   *  (subscription.items.data[0].price.id) und mappt auf einen tier-
-   *  name. Fehlt die price-id im Mapping → null (foundation 200
-   *  ignored — App-Owner-Bug, hat den Stripe-price angelegt aber
-   *  nicht zur tier zugeordnet). */
-  readonly priceToTier: Readonly<Record<string, string>>;
+  /** Bridge-fallback webhook-secret. Optional: v2 liest aus
+   *  `subscription-stripe:webhook-secret` (system-secret). Gesetzt nur
+   *  während der env→secrets-Übergangsphase / in Tests. */
+  readonly webhookSecret?: string;
+  /** Bridge-fallback api-key. Optional: v2 liest aus
+   *  `subscription-stripe:api-key` (system-secret). */
+  readonly apiKey?: string;
+  /** Price-to-tier-Mapping. Plugin liest die price-id aus dem Stripe-event
+   *  (subscription.items.data[0].price.id) und mappt auf einen tier-name.
+   *  App-spezifisch → bleibt factory-option. Fehlt die price-id im Mapping
+   *  → null (event ignored). */
+  readonly priceToTier?: Readonly<Record<string, string>>;
 };
 
+const SECRET_REDACT = (plaintext: string): string =>
+  plaintext.length < 12
+    ? "•".repeat(plaintext.length)
+    : `${plaintext.slice(0, 8)}...${plaintext.slice(-4)}`;
+
 /**
- * Factory für das subscription-stripe-feature. Wird mit den App-Owner-
- * eigenen Stripe-Credentials gemountet. Der returnte FeatureDefinition
- * registriert den Plugin gegen subscription-foundation's
- * "subscriptionProvider"-extension-point unter entityName "stripe".
+ * Factory für das subscription-stripe-feature. Mountet IMMER (kein
+ * key-presence-Guard mehr) — die Aktivität wird runtime über config/secrets
+ * gegatet (Muster wie feature-toggles). Der returnte FeatureDefinition
+ * registriert den Plugin gegen billing-foundation's "subscriptionProvider"-
+ * extension unter entityName "stripe".
  */
 export function createSubscriptionStripeFeature(
-  options: SubscriptionStripeOptions,
+  options: SubscriptionStripeOptions = {},
 ): FeatureDefinition {
-  // Module-load-Validation: ohne webhook-secret kann der Plugin keinen
-  // single Webhook verifizieren. Throw vor dem mount damit der App-
-  // Owner nicht zur Laufzeit Mystery-401s sieht.
-  if (options.webhookSecret.length === 0) {
-    throw new Error(
-      "subscription-stripe: webhookSecret is empty. Set STRIPE_WEBHOOK_SECRET (or system-config) before mounting.",
-    );
-  }
-  if (options.apiKey.length === 0) {
-    throw new Error(
-      "subscription-stripe: apiKey is empty. Set STRIPE_API_KEY (or system-config) before mounting.",
-    );
-  }
-
-  // EIN Stripe-Client für alle vier plugin-methods (verify-webhook +
-  // checkout + portal + cancel). API-version-pin zentral, kein
-  // Connection-Duplikat.
-  const stripe = new Stripe(options.apiKey, { apiVersion: "2026-04-22.dahlia" });
-
-  const verifyAndParse = verifyAndParseStripeWebhook(stripe, {
-    webhookSecret: options.webhookSecret,
-    priceToTier: options.priceToTier,
-  });
-  const checkoutSession = createStripeCheckoutSession(stripe);
-  const portalSession = createStripePortalSession(stripe);
-  const cancel = createStripeCancelSubscription(stripe);
-
   return defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
     r.describe(
-      "Stripe payment provider plugin for `billing-foundation`. Mount via `createSubscriptionStripeFeature({ webhookSecret, apiKey, priceToTier })` \u2014 a factory function that holds the app-wide credentials in a closure for use before tenant resolution. Implements all four provider methods: `verifyAndParseWebhook` (HMAC signature verification), `createCheckoutSession`, `createPortalSession`, and `cancelSubscription`. The `priceToTier` map connects Stripe price IDs to your tier names.",
+      "Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from the **secrets** feature (stored under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. 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 all four provider methods (webhook verify, checkout, portal, cancel).",
     );
-    // Hard-deps: subscription-foundation als plugin-host. KEIN
-    // `r.requires("config", "secrets")` — der Plugin nutzt weder
-    // tenant-config noch tenant-secrets (alles app-wide via factory-
-    // options).
+    // Hard-deps: billing-foundation (plugin-host) + config (billing-live)
+    // + secrets (api-key/webhook-secret).
     r.requires("billing-foundation");
+    r.requires("config");
+    r.requires("secrets");
     r.envSchema(subscriptionStripeEnvSchema);
 
-    // Plugin: register against subscription-foundation's
-    // "subscriptionProvider" extension. entityName "stripe" matcht den
-    // path-segment in der webhook-URL (`/api/subscription/webhook/stripe`).
+    // Runtime-credentials. scope "tenant" (secrets-v1) — gespeichert/gelesen
+    // unter SYSTEM_TENANT_ID (app-wide). required:false: der factory-Fallback
+    // deckt die Bridge-Phase, also kein readiness-false-negative.
+    const apiKeySecret = r.secret(STRIPE_API_KEY_SECRET, {
+      label: { de: "Stripe API Key", en: "Stripe API Key" },
+      hint: {
+        de: "Geheimer Stripe-Schlüssel (`sk_live_...`). Im Stripe-Dashboard unter Entwickler → API-Schlüssel.",
+        en: "Stripe secret key (`sk_live_...`). Stripe dashboard → Developers → API keys.",
+      },
+      redact: SECRET_REDACT,
+      scope: "tenant",
+      required: false,
+    });
+    const webhookSecret = r.secret(STRIPE_WEBHOOK_SECRET_SECRET, {
+      label: { de: "Stripe Webhook Secret", en: "Stripe Webhook Secret" },
+      hint: {
+        de: "Webhook-Signing-Secret (`whsec_...`). Im Stripe-Dashboard beim Webhook-Endpoint.",
+        en: "Webhook signing secret (`whsec_...`). Stripe dashboard → the webhook endpoint.",
+      },
+      redact: SECRET_REDACT,
+      scope: "tenant",
+      required: false,
+    });
+
+    const configKeys = r.config({
+      keys: {
+        [STRIPE_BILLING_LIVE_CONFIG]: createSystemConfig("boolean", { default: false }),
+      },
+    });
+
+    const runtimes = createStripeRuntimes({
+      apiKeyHandle: apiKeySecret,
+      webhookSecretHandle: webhookSecret,
+      billingLiveHandle: configKeys[STRIPE_BILLING_LIVE_CONFIG],
+      fallback: {
+        ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+        ...(options.webhookSecret !== undefined && { webhookSecret: options.webhookSecret }),
+      },
+    });
+
     const plugin: SubscriptionProviderPlugin = {
-      verifyAndParseWebhook: verifyAndParse,
-      createCheckoutSession: checkoutSession,
-      createPortalSession: portalSession,
-      cancelSubscription: cancel,
+      verifyAndParseWebhook: verifyAndParseStripeWebhook(runtimes.webhook, {
+        priceToTier: options.priceToTier ?? {},
+      }),
+      createCheckoutSession: createStripeCheckoutSession(runtimes.ctx),
+      createPortalSession: createStripePortalSession(runtimes.ctx),
+      cancelSubscription: createStripeCancelSubscription(runtimes.ctx),
     };
     r.useExtension("subscriptionProvider", STRIPE_PROVIDER_NAME, plugin);
+
+    return { apiKeySecret, webhookSecret, configKeys };
   });
 }