@cosmicdrift/kumiko-bundled-features 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/__tests__/env-schemas.test.ts

@@ -245,8 +245,13 @@ describe("compose across all Phase-2 features", () => {
       const out = asBootError(err).format();
       expect(out).toContain("✗ JWT_SECRET (auth-email-password, required, missing)");
       expect(out).toContain("✗ KUMIKO_SECRETS_MASTER_KEY_V1 (secrets, required, missing)");
-      expect(out).toContain("✗ STRIPE_API_KEY (subscription-stripe, required, missing)");
       expect(out).toContain("✗ MOLLIE_API_KEY (subscription-mollie, required, missing)");
+      // subscription-stripe-v2: STRIPE_API_KEY/STRIPE_WEBHOOK_SECRET sind
+      // jetzt optionale env→secrets-Bridge-Fallbacks, also KEIN missing-
+      // required-Boot-Fehler mehr — credentials kommen zur Laufzeit aus
+      // secrets.
+      expect(out).not.toContain("STRIPE_API_KEY");
+      expect(out).not.toContain("STRIPE_WEBHOOK_SECRET");
     }
   });
 });

package/src/billing-foundation/types.ts

@@ -6,10 +6,14 @@
 // **Two-phase plugin contract:**
 //   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` läuft BEVOR
 //      ein Tenant aus dem Event aufgelöst ist — kein HandlerContext
-//      verfügbar. Plugin liest seinen webhook-secret aus
-//      module-load-Closure (ENV-VAR oder system-config), NICHT aus
-//      ctx. **Webhook-secret ist app-wide**, nicht per-tenant — das
-//      ist App-Owner's Stripe-/PayPal-Account, nicht Tenant-Sache.
+//      verfügbar. Das **Webhook-secret ist app-wide** (App-Owner's
+//      Stripe-/PayPal-Account, nicht Tenant-Sache). Damit ein Plugin den
+//      secret ZUR LAUFFZEIT aus dem secrets-Feature lesen kann (statt aus
+//      einem mount-time-Closure), reicht der webhook-handler einen
+//      optionalen system-scoped `SecretsContext` als 3. Arg durch — der
+//      Plugin liest seine app-wide-Secrets daraus un-audited unter
+//      SYSTEM_TENANT_ID. Plugins, die ihre Keys weiter aus einem Closure
+//      halten (z.B. mollie), ignorieren den Param → backward-compatible.
 //   2. **Post-tenant-resolution:** `createPortalSession` +
 //      `cancelSubscription` werden aus regulären write-handlern
 //      gerufen mit voll-aufgelöstem HandlerContext. Plugin kann
@@ -21,6 +25,7 @@
 // und sind über den Customer-Portal-Link erreichbar.
 
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { SubscriptionEventType, SubscriptionStatus } from "./constants";
 
 // =============================================================================
@@ -75,9 +80,12 @@ export type SubscriptionProviderPlugin = {
    * (Plugin macht die Tenant-Resolution selbst aus dem provider-
    * payload metadata).
    *
-   * Plugin liest seinen webhook-secret aus module-load-Closure
-   * (process.env.STRIPE_WEBHOOK_SECRET oder system-config), NICHT
-   * aus ctx. App-wide-secret = App-Owner's eigener Provider-Account.
+   * App-wide-secret = App-Owner's eigener Provider-Account. Der Plugin
+   * liest ihn entweder aus einem mount-time-Closure ODER — zur Laufzeit
+   * rotierbar — aus dem optionalen `systemSecrets`-Arg (system-scoped
+   * SecretsContext, vom webhook-handler durchgereicht). `systemSecrets`
+   * ist undefined, wenn der App-Owner keinen wired; Plugins müssen dann
+   * auf ihren Closure-Fallback zurückfallen.
    *
    * Returns null für events die der Plugin nicht versteht oder die
    * foundation nicht braucht (= filter out, foundation returnt 200
@@ -90,6 +98,7 @@ export type SubscriptionProviderPlugin = {
   readonly verifyAndParseWebhook: (
     rawBody: string,
     headers: Record<string, string>,
+    systemSecrets?: SecretsContext,
   ) => Promise<SubscriptionEvent | null>;
 
   /**

package/src/billing-foundation/webhook-handler.ts

@@ -72,6 +72,15 @@ export type SubscriptionWebhookDeps = {
    *  Pfad und returnt den passenden Plugin (= entityName-match in
    *  registry.getExtensionUsages("subscriptionProvider")). */
   readonly resolveProvider: (providerName: string) => SubscriptionProviderPlugin | undefined;
+
+  /** Optionaler system-scoped SecretsContext, durchgereicht an
+   *  `verifyAndParseWebhook` (3. Arg). Erlaubt Plugins, ihre app-wide-
+   *  Credentials (Stripe api-key/webhook-secret) zur Laufzeit aus
+   *  secrets unter SYSTEM_TENANT_ID zu lesen statt aus einem mount-time-
+   *  Closure. Der App-Owner baut ihn via `createSecretsContext({ db,
+   *  masterKeyProvider })` aus den extraRoutes-deps. Fehlt er, fallen
+   *  Plugins auf ihren Closure-Fallback zurück. */
+  readonly systemSecrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
 };
 
 /**
@@ -124,7 +133,7 @@ export function createSubscriptionWebhookHandler(deps: SubscriptionWebhookDeps)
     //    retry won't help, Provider stopp").
     let parsed: Awaited<ReturnType<SubscriptionProviderPlugin["verifyAndParseWebhook"]>>;
     try {
-      parsed = await plugin.verifyAndParseWebhook(rawBody, headers);
+      parsed = await plugin.verifyAndParseWebhook(rawBody, headers, deps.systemSecrets);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       return c.json(

package/src/subscription-stripe/__tests__/feature.test.ts

@@ -4,52 +4,55 @@ import { describe, expect, test } from "bun:test";
 import { STRIPE_PROVIDER_NAME, StripeEventTypes, SUBSCRIPTION_STRIPE_FEATURE } from "../constants";
 import { createSubscriptionStripeFeature } from "../feature";
 
-const VALID_OPTIONS = {
-  webhookSecret: "whsec_test_dummy",
-  apiKey: "sk_test_dummy",
+const OPTIONS = {
   priceToTier: { price_test: "pro" },
 };
 
 describe("createSubscriptionStripeFeature — shape", () => {
   test("has the expected name", () => {
-    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+    const feature = createSubscriptionStripeFeature(OPTIONS);
     expect(feature.name).toBe(SUBSCRIPTION_STRIPE_FEATURE);
     expect(feature.name).toBe("subscription-stripe");
   });
 
-  test("requires only subscription-foundation (NICHT config/secrets — alles app-wide via factory-options)", () => {
-    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+  test("requires billing-foundation + config + secrets (runtime-keys via config/secrets)", () => {
+    const feature = createSubscriptionStripeFeature(OPTIONS);
     expect(feature.requires).toContain("billing-foundation");
-    // Drift-Pin: webhook-secret + apiKey kommen aus factory-options
-    // (= module-load-Closure), NICHT aus tenant-config/-secrets.
-    expect(feature.requires).not.toContain("config");
-    expect(feature.requires).not.toContain("secrets");
+    // Drift-Pin (v2): api-key/webhook-secret kommen ZUR LAUFZEIT aus
+    // secrets, billing-live aus config — daher harte deps auf beide.
+    expect(feature.requires).toContain("config");
+    expect(feature.requires).toContain("secrets");
   });
 });
 
-describe("createSubscriptionStripeFeature — module-load validation", () => {
-  test("throws bei empty webhookSecret (= App-Owner hat sub-stripe gemountet aber Stripe-Account nicht konfiguriert)", () => {
+describe("createSubscriptionStripeFeature — mounts without mount-time credentials", () => {
+  test("mounts with no options at all (keys resolved at runtime from secrets)", () => {
+    // v1 warf hier bei leerem webhookSecret/apiKey. v2 mountet immer —
+    // die Credentials kommen erst zur Laufzeit aus config/secrets, der
+    // billing-live-Gate hält den Checkout solange inert.
+    expect(() => createSubscriptionStripeFeature()).not.toThrow();
+  });
+
+  test("mounts with only priceToTier (no api/webhook keys passed)", () => {
     expect(() =>
-      createSubscriptionStripeFeature({
-        ...VALID_OPTIONS,
-        webhookSecret: "",
-      }),
-    ).toThrow(/webhookSecret is empty/);
+      createSubscriptionStripeFeature({ priceToTier: { price_x: "pro" } }),
+    ).not.toThrow();
   });
 
-  test("throws bei empty apiKey", () => {
+  test("mounts with bridge-fallback keys passed (env→secrets transition)", () => {
     expect(() =>
       createSubscriptionStripeFeature({
-        ...VALID_OPTIONS,
-        apiKey: "",
+        apiKey: "sk_test_dummy",
+        webhookSecret: "whsec_dummy",
+        priceToTier: { price_x: "pro" },
       }),
-    ).toThrow(/apiKey is empty/);
+    ).not.toThrow();
   });
 });
 
 describe("subscription-stripe — plugin-registration", () => {
-  test("registers itself under entityName 'stripe' for subscription-foundation's extension", () => {
-    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+  test("registers itself under entityName 'stripe' for billing-foundation's extension", () => {
+    const feature = createSubscriptionStripeFeature(OPTIONS);
     const usages = feature.extensionUsages;
     expect(
       usages.some(
@@ -65,7 +68,7 @@ describe("subscription-stripe — plugin-registration", () => {
     // "method not supported"-error brechen — type-check würde es nicht
     // fangen weil die useExtension-options als `unknown` durchgereicht
     // werden.
-    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+    const feature = createSubscriptionStripeFeature(OPTIONS);
     const usage = feature.extensionUsages.find((u) => u.entityName === STRIPE_PROVIDER_NAME);
     expect(usage).toBeDefined();
     const options = usage?.options as {

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

@@ -2,15 +2,24 @@
 // createPortalSession, cancelSubscription). Stripe-SDK-calls werden via
 // spyOn gemockt — wir testen unsere Mapping-Logik (Argumente die wir
 // an Stripe schicken + Antwort-Parsing), NICHT Stripe selbst.
+//
+// **Runtime-Wrapper:** die methods nehmen jetzt einen StripeCtxRuntime
+// (löst Client + billing-live aus ctx auf), nicht mehr einen rohen
+// Stripe-Client. `ctxRuntime(stripe, billingLive)` baut einen Test-runtime
+// der den gespyten Client zurückgibt — die echte Resolution-Logik testet
+// runtime.test.ts.
 
 import { describe, expect, spyOn, test } from "bun:test";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureDisabledError } from "@cosmicdrift/kumiko-framework/errors";
 import Stripe from "stripe";
+import { SUBSCRIPTION_STRIPE_FEATURE } from "../constants";
 import {
   createStripeCancelSubscription,
   createStripeCheckoutSession,
   createStripePortalSession,
 } from "../plugin-methods";
+import type { StripeCtxRuntime } from "../runtime";
 
 const TEST_API_KEY = "sk_test_dummy";
 
@@ -18,6 +27,19 @@ function buildStripe(): Stripe {
   return new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
 }
 
+/** Test-runtime: gibt den gespyten Client zurück + ein billing-live-Gate
+ *  das (default) durchlässt. */
+function ctxRuntime(stripe: Stripe, billingLive = true): StripeCtxRuntime {
+  return {
+    clientForCtx: async () => stripe,
+    assertBillingLive: async () => {
+      if (!billingLive) {
+        throw new FeatureDisabledError(SUBSCRIPTION_STRIPE_FEATURE, "create-checkout-session");
+      }
+    },
+  };
+}
+
 const stubCtx = {} as HandlerContext;
 
 // =============================================================================
@@ -31,7 +53,7 @@ describe("createStripeCheckoutSession", () => {
       // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
       .mockResolvedValue({ url: "https://checkout.stripe.com/c/pay/test" } as any);
 
-    const checkout = createStripeCheckoutSession(stripe);
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe));
     const result = await checkout(stubCtx, {
       priceId: "price_pro_monthly",
       tenantId: "tenant-001",
@@ -55,13 +77,32 @@ describe("createStripeCheckoutSession", () => {
     });
   });
 
+  test("#104-Gate: throws FeatureDisabledError + ruft Stripe NICHT wenn billing-live aus", async () => {
+    const stripe = buildStripe();
+    const createMock = spyOn(stripe.checkout.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ url: "https://x" } as any);
+
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe, false));
+    await expect(
+      checkout(stubCtx, {
+        priceId: "price_x",
+        tenantId: "t",
+        successUrl: "https://x/s",
+        cancelUrl: "https://x/c",
+      }),
+    ).rejects.toBeInstanceOf(FeatureDisabledError);
+    // Kein Stripe-Call — die Schranke greift VOR jeder Session-Erstellung.
+    expect(createMock).not.toHaveBeenCalled();
+  });
+
   test("passes existing customer-id wenn gesetzt (Plan-Wechsel-Flow)", async () => {
     const stripe = buildStripe();
     const createMock = spyOn(stripe.checkout.sessions, "create")
       // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
       .mockResolvedValue({ url: "https://x" } as any);
 
-    const checkout = createStripeCheckoutSession(stripe);
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe));
     await checkout(stubCtx, {
       priceId: "price_x",
       tenantId: "tenant-002",
@@ -81,7 +122,7 @@ describe("createStripeCheckoutSession", () => {
       // biome-ignore lint/suspicious/noExplicitAny: SDK-Drift-Test
       .mockResolvedValue({ url: null } as any);
 
-    const checkout = createStripeCheckoutSession(stripe);
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe));
     await expect(
       checkout(stubCtx, {
         priceId: "p",
@@ -102,7 +143,7 @@ describe("createStripeCheckoutSession", () => {
       new Error("Stripe API: Internal server error"),
     );
 
-    const checkout = createStripeCheckoutSession(stripe);
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe));
     await expect(
       checkout(stubCtx, {
         priceId: "p",
@@ -125,7 +166,7 @@ describe("createStripePortalSession", () => {
       // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
       .mockResolvedValue({ url: "https://billing.stripe.com/p/session/test" } as any);
 
-    const portal = createStripePortalSession(stripe);
+    const portal = createStripePortalSession(ctxRuntime(stripe));
     const result = await portal(stubCtx, {
       providerCustomerId: "cus_001",
       returnUrl: "https://example.com/return",
@@ -151,7 +192,7 @@ describe("createStripeCancelSubscription", () => {
       // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
       .mockResolvedValue({ id: "sub_001", status: "canceled" } as any);
 
-    const cancel = createStripeCancelSubscription(stripe);
+    const cancel = createStripeCancelSubscription(ctxRuntime(stripe));
     await cancel(stubCtx, "sub_001");
 
     expect(cancelMock).toHaveBeenCalledTimes(1);

package/src/subscription-stripe/__tests__/runtime.test.ts

@@ -0,0 +1,180 @@
+// Unit-Tests für die Runtime-Key/Flag-Resolution (runtime.ts) — das Herz
+// des v2-Pivots weg von mount-time-Closures. Stub-ctx/SecretsContext
+// statt echter DB: wir testen die Resolution-Logik (secrets→fallback→throw,
+// billing-live-Gate, Client-Memoization), nicht die secrets-Persistenz
+// (das deckt der Integration-Test ab).
+
+import { describe, expect, test } from "bun:test";
+import type {
+  ConfigKeyHandle,
+  HandlerContext,
+  SecretKeyHandle,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { createSecret, type SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import Stripe from "stripe";
+import { createStripeClientCache, createStripeRuntimes } from "../runtime";
+
+const API_KEY_HANDLE: SecretKeyHandle = { name: "subscription-stripe:secret:api-key" };
+const WEBHOOK_SECRET_HANDLE: SecretKeyHandle = {
+  name: "subscription-stripe:secret:webhook-secret",
+};
+const BILLING_LIVE_HANDLE: ConfigKeyHandle<"boolean"> = {
+  name: "subscription-stripe:config:billingLive",
+  type: "boolean",
+};
+
+/** Stub-SecretsContext: liest aus einer in-memory-map, matcht per
+ *  qualified-name. Ignoriert auditCtx (irrelevant für die Resolution). */
+function stubSecrets(values: Record<string, string>): SecretsContext {
+  const nameOf = (k: string | { readonly name: string }): string =>
+    typeof k === "string" ? k : k.name;
+  return {
+    get: async (_tenantId, key) => {
+      const value = values[nameOf(key)];
+      return value === undefined ? undefined : createSecret(value);
+    },
+    has: async (_tenantId, key) => values[nameOf(key)] !== undefined,
+    set: async () => undefined,
+    delete: async () => false,
+  };
+}
+
+/** Minimaler HandlerContext-Stub mit nur den Feldern, die die ctx-
+ *  Resolution liest (secrets, _userId für audit, config). */
+function stubCtx(opts: { secrets?: SecretsContext; billingLive?: boolean }): HandlerContext {
+  return {
+    secrets: opts.secrets,
+    _userId: "tester",
+    config: async () => opts.billingLive,
+  } as unknown as HandlerContext; // @cast-boundary test-stub — partial ctx
+}
+
+function makeRuntimes(fallback: { apiKey?: string; webhookSecret?: string } = {}) {
+  return createStripeRuntimes({
+    apiKeyHandle: API_KEY_HANDLE,
+    webhookSecretHandle: WEBHOOK_SECRET_HANDLE,
+    billingLiveHandle: BILLING_LIVE_HANDLE,
+    fallback,
+  });
+}
+
+// =============================================================================
+// createStripeClientCache
+// =============================================================================
+
+describe("createStripeClientCache", () => {
+  test("memoizes by api-key — same key → same instance, rotated key → new instance", () => {
+    const cache = createStripeClientCache();
+    const a1 = cache("sk_test_aaa");
+    const a2 = cache("sk_test_aaa");
+    const b1 = cache("sk_test_bbb");
+
+    expect(a1).toBeInstanceOf(Stripe);
+    expect(a2).toBe(a1); // steady-state reuses one client per key
+    expect(b1).not.toBe(a1); // rotation builds a fresh client
+  });
+});
+
+// =============================================================================
+// ctx-runtime: api-key resolution (post-tenant, audited)
+// =============================================================================
+
+describe("StripeCtxRuntime.clientForCtx", () => {
+  test("reads api-key from system-secrets → builds a client", async () => {
+    const rt = makeRuntimes();
+    const ctx = stubCtx({ secrets: stubSecrets({ [API_KEY_HANDLE.name]: "sk_test_from_secret" }) });
+    const client = await rt.ctx.clientForCtx(ctx);
+    expect(client).toBeInstanceOf(Stripe);
+  });
+
+  test("secret takes precedence over factory-fallback; rotating the secret → new client", async () => {
+    const rt = makeRuntimes({ apiKey: "sk_test_fallback" });
+    const values: Record<string, string> = { [API_KEY_HANDLE.name]: "sk_test_v1" };
+    const ctx = stubCtx({ secrets: stubSecrets(values) });
+
+    const first = await rt.ctx.clientForCtx(ctx);
+    const again = await rt.ctx.clientForCtx(ctx);
+    expect(again).toBe(first); // same secret → memoized
+
+    values[API_KEY_HANDLE.name] = "sk_test_v2"; // operator rotates the secret
+    const afterRotation = await rt.ctx.clientForCtx(ctx);
+    expect(afterRotation).not.toBe(first); // runtime re-read picked up the new key
+  });
+
+  test("falls back to factory api-key when no secret is set", async () => {
+    const rt = makeRuntimes({ apiKey: "sk_test_fallback" });
+    const ctx = stubCtx({ secrets: stubSecrets({}) });
+    const client = await rt.ctx.clientForCtx(ctx);
+    expect(client).toBeInstanceOf(Stripe);
+  });
+
+  test("throws UnconfiguredError when neither secret nor fallback is set", async () => {
+    const rt = makeRuntimes();
+    const ctx = stubCtx({ secrets: stubSecrets({}) });
+    await expect(rt.ctx.clientForCtx(ctx)).rejects.toBeInstanceOf(UnconfiguredError);
+  });
+});
+
+// =============================================================================
+// ctx-runtime: billing-live gate (#104 invariant)
+// =============================================================================
+
+describe("StripeCtxRuntime.assertBillingLive", () => {
+  test("passes when billing-live config is true", async () => {
+    const rt = makeRuntimes();
+    await expect(rt.ctx.assertBillingLive(stubCtx({ billingLive: true }))).resolves.toBeUndefined();
+  });
+
+  test("throws FeatureDisabledError when billing-live is false", async () => {
+    const rt = makeRuntimes();
+    await expect(rt.ctx.assertBillingLive(stubCtx({ billingLive: false }))).rejects.toBeInstanceOf(
+      FeatureDisabledError,
+    );
+  });
+
+  test("throws FeatureDisabledError when billing-live is undefined (default-off)", async () => {
+    const rt = makeRuntimes();
+    await expect(
+      rt.ctx.assertBillingLive(stubCtx({ billingLive: undefined })),
+    ).rejects.toBeInstanceOf(FeatureDisabledError);
+  });
+});
+
+// =============================================================================
+// webhook-runtime: pre-tenant resolution (raw, un-audited)
+// =============================================================================
+
+describe("StripeWebhookRuntime.resolve", () => {
+  test("resolves client + webhook-secret from system-secrets", async () => {
+    const rt = makeRuntimes();
+    const secrets = stubSecrets({
+      [API_KEY_HANDLE.name]: "sk_test_wh",
+      [WEBHOOK_SECRET_HANDLE.name]: "whsec_runtime",
+    });
+    const { stripe, webhookSecret } = await rt.webhook.resolve(secrets);
+    expect(stripe).toBeInstanceOf(Stripe);
+    expect(webhookSecret).toBe("whsec_runtime");
+  });
+
+  test("falls back to factory keys when no system-secrets passed", async () => {
+    const rt = makeRuntimes({ apiKey: "sk_test_fb", webhookSecret: "whsec_fb" });
+    const { webhookSecret } = await rt.webhook.resolve(undefined);
+    expect(webhookSecret).toBe("whsec_fb");
+  });
+
+  test("system-secret wins over fallback (rotation without redeploy)", async () => {
+    const rt = makeRuntimes({ webhookSecret: "whsec_stale_env" });
+    const secrets = stubSecrets({
+      [API_KEY_HANDLE.name]: "sk_test_x",
+      [WEBHOOK_SECRET_HANDLE.name]: "whsec_rotated",
+    });
+    const { webhookSecret } = await rt.webhook.resolve(secrets);
+    expect(webhookSecret).toBe("whsec_rotated");
+  });
+
+  test("throws when a key is unresolved (no secret, no fallback)", async () => {
+    const rt = makeRuntimes({ apiKey: "sk_test_only" }); // webhook-secret missing
+    await expect(rt.webhook.resolve(stubSecrets({}))).rejects.toThrow(/webhook-secret.*unresolved/);
+  });
+});