@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -1,18 +1,18 @@
-// verifyAndParseMollieWebhook — Mollie-spezifische lazy-fetch +
-// event-type-Heuristik. Wird vom Plugin-Build (feature.ts) als
-// `verifyAndParseWebhook` registriert.
+// verifyAndParseMollieWebhook: Mollie-specific lazy fetch plus event-type
+// heuristic. The plugin build (feature.ts) registers it as
+// `verifyAndParseWebhook`.
 //
-// Mollie's classic-webhook sendet nur eine `id` (form-urlencoded oder
-// JSON). Wir lazy-fetchen payment + subscription via Mollie-API. Sub-
-// xxx-events werden NICHT supported — App-Builder bekommt sie indirekt
-// via tr_xxx-payment-events (Mollie sendet beide parallel bei normalen
-// Lifecycle-Events).
+// Mollie's classic webhook sends only an `id` (form-urlencoded or JSON), so
+// the payment and subscription are lazily fetched through the Mollie API.
+// sub_xxx events are NOT supported; app builders get them indirectly through
+// tr_xxx payment events (Mollie sends both in parallel for normal lifecycle
+// events).
 //
-// **Mandate-setup-flow:** first-payment-paid kommt mit
-// `payment.subscriptionId === null` (Mollie's Pattern: App-Builder
-// muss `customerSubscriptions.create` selbst aufrufen). Wir machen
-// das im Plugin (idempotent via list-check), damit Foundation einen
-// Created-Event mit subscription-id bekommt.
+// **Mandate setup flow:** the first paid payment arrives with
+// `payment.subscriptionId === null` (Mollie's pattern: the app builder must
+// call `customerSubscriptions.create` itself). The plugin does that
+// (idempotent via a list check) so the foundation receives a created event
+// with a subscription id.
 
 import {
   parseProviderConsentId,
@@ -33,9 +33,9 @@ import type { MolliePriceConfig } from "./plugin-methods.ts";
 
 const log = createFallbackLogger("subscription-mollie");
 
-/** Minimal-Subset des Mollie-Clients, das der Plugin nutzt — separat
- *  damit Tests ohne den vollen MollieClient mocken können. Adapter in
- *  feature.ts bridged das gegen den echten SDK. */
+/** Minimal subset of the Mollie client used by the plugin — kept separate
+ *  so tests can mock it without the full MollieClient. The adapter in
+ *  feature.ts bridges it to the real SDK. */
 export type MollieClientShape = {
   readonly payments: { readonly get: (id: string) => Promise<MolliePayment> };
   readonly customerSubscriptions: {
@@ -54,11 +54,11 @@ export type MollieClientShape = {
 };
 
 export type MollieWebhookOptions = {
-  /** priceId (= virtueller Schlüssel aus subscription.metadata) → tier-name. */
+  /** priceId (= virtual key from subscription.metadata) → tier name. */
   readonly priceToTier: Readonly<Record<string, string>>;
-  /** priceId → amount/interval/description. Wird beim mandate-setup-
-   *  flow zum `customerSubscriptions.create`-Call gebraucht. App-
-   *  Builder pflegt die Map einmal in den factory-options. */
+  /** priceId → amount/interval/description. Needed for the mandate-setup
+   *  flow's `customerSubscriptions.create` call. The app builder maintains
+   *  this map once in the factory options. */
   readonly priceToConfig: Readonly<Record<string, MolliePriceConfig>>;
 };
 
@@ -97,7 +97,7 @@ export function verifyAndParseMollieWebhook(
         subscription = await ensureSubscriptionForMandate(client, options, payment);
         if (!subscription) return null;
       } else {
-        // One-shot oder first-payment-failed → nicht unsere Domain.
+        // One-shot or first-payment-failed events are outside our domain.
         return null;
       }
     } else if (id.startsWith("sub_")) {
@@ -121,8 +121,8 @@ export function verifyAndParseMollieWebhook(
     const status = mapMollieStatus(subscription.status);
     const periodEndSource = subscription.nextPaymentDate ?? subscription.startDate;
     if (!periodEndSource) {
-      // Mollie-API-Drift: valid Subs haben mindestens startDate. Loud-
-      // fail damit App-Owner's monitoring den drift sieht.
+      // Mollie API drift: valid subscriptions have at least startDate. Fail
+      // loudly so the app owner's monitoring can detect the drift.
       throw new Error(
         `subscription-mollie: subscription ${subscription.id} has neither nextPaymentDate nor startDate`,
       );
@@ -149,9 +149,9 @@ export function verifyAndParseMollieWebhook(
 // Mandate-setup: subscription on-the-fly erstellen
 // =============================================================================
 
-/** first-payment-paid OHNE subscriptionId → Mollie-Sub erstellen.
- *  Idempotent via list-check (replay-safe). Returns null bei
- *  unvollständiger metadata oder unbekanntem priceId. */
+/** `first-payment-paid` without subscriptionId → create a Mollie subscription.
+ *  Idempotent via a list check (replay-safe). Returns null for incomplete
+ *  metadata or an unknown priceId. */
 async function ensureSubscriptionForMandate(
   client: MollieClientShape,
   options: MollieWebhookOptions,
@@ -188,10 +188,10 @@ async function ensureSubscriptionForMandate(
 }
 
 // =============================================================================
-// Helpers (exported für Tests)
+// Helpers (exported for tests)
 // =============================================================================
 
-/** Extract `id` aus rawBody — handelt form-urlencoded + JSON. */
+/** Extracts `id` from rawBody — supports form-urlencoded and JSON. */
 export function extractMollieId(rawBody: string, headers: Record<string, string>): string | null {
   const contentType = headers["content-type"] ?? "";
   if (contentType.includes("application/json")) {
@@ -210,8 +210,8 @@ export function extractMollieId(rawBody: string, headers: Record<string, string>
   return params.get("id");
 }
 
-/** Mollie-subscription + optional payment → SubscriptionEventType.
- *  Heuristik (Mollie hat keine explicit-typed events). */
+/** Mollie subscription + optional payment → SubscriptionEventType.
+ *  Heuristic because Mollie has no explicitly typed events. */
 export function mapMollieEventType(
   subscription: MollieSubscription,
   triggerPayment: MolliePayment | null,
@@ -240,10 +240,10 @@ export function mapMollieStatus(mollieStatus: MollieSubscription["status"]): Sub
       return SubscriptionStatuses.active;
     case "canceled":
     case "completed":
-      // completed = alle `times`-charges durchgelaufen → wie canceled.
+      // completed = all `times` charges have run → treat it like canceled.
       return SubscriptionStatuses.canceled;
     case "suspended":
-      // Mandate ungültig / payment-method failed → grace-period.
+      // Invalid mandate / payment method failed → grace period.
       return SubscriptionStatuses.pastDue;
     case "pending":
       return SubscriptionStatuses.incomplete;
@@ -252,8 +252,8 @@ export function mapMollieStatus(mollieStatus: MollieSubscription["status"]): Sub
   }
 }
 
-/** Mollie liefert dates als YYYY-MM-DD; foundation will ISO-Instant.
- *  Throws bei malformed input (= Mollie-API-Drift, soll loud-fail). */
+/** Mollie provides dates as YYYY-MM-DD; Foundation requires an ISO Instant.
+ *  Throws on malformed input (= Mollie API drift, which should fail loudly). */
 function mollieDateStringToInstantIso(dateString: string): string {
   return Temporal.Instant.from(`${dateString.slice(0, 10)}T00:00:00Z`).toString();
 }

package/packages/bundled-features/src/subscription-stripe/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Stripe plugin has a displayName",
+    "detail": "The Stripe plugin sets displayName \"Stripe\", which the provider choice in the billing panel shows."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "A malformed stored credential no longer leaks into the error",
+    "detail": "A stored api-key or webhook-secret that is not valid JSON used to raise the JSON parser's own message, which repeats the value into logs and the webhook 401 body. The error now has a fixed text and names no input. subscription-dodo behaves the same."
+  },
   {
     "version": "0.370.0",
     "type": "improvement",

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

@@ -1,8 +1,8 @@
 // Feature name
 export const SUBSCRIPTION_STRIPE_FEATURE = "subscription-stripe" as const;
 
-// entityName under den der Plugin gegen "subscriptionProvider"
-// registriert. Matcht den path-segment in der webhook-URL
+// entityName under which the plugin registers itself as
+// "subscriptionProvider". It must match the path segment in the webhook URL
 // `/api/subscription/webhook/stripe`.
 export const STRIPE_PROVIDER_NAME = "stripe" as const;
 
@@ -14,10 +14,8 @@ export const STRIPE_API_KEY_CONFIG = "api-key" as const;
 export const STRIPE_WEBHOOK_SECRET_CONFIG = "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.
-// =============================================================================
+// Stripe event types that map to normalized SubscriptionEventTypes.
+// Stripe has approximately 80 event types; we filter to five.
 
 export const StripeEventTypes = {
   customerSubscriptionCreated: "customer.subscription.created",

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

@@ -1,35 +1,36 @@
 // kumiko-feature-version: 3
 //
-// subscription-stripe — Stripe-Plugin für die billing-foundation
-// Plugin-API.
+// subscription-stripe — Stripe plugin for the billing-foundation
+// plugin API.
 //
-// **Runtime-config (v3):** Stripe-credentials + der billing-live-Master-
-// Switch kommen ZUR LAUFZEIT aus dem config-Feature, nicht mehr aus einem
-// mount-time-Closure. Damit lassen sich Keys rotieren und prod live-
-// schalten ohne Redeploy — und die Eingabe-Maske entsteht von selbst.
+// **Runtime config (v3):** Stripe credentials and the billing-live master
+// switch come from the config feature AT RUNTIME, no longer from a
+// mount-time closure. This allows keys to rotate and production to go live
+// without a redeploy — and the input form is generated automatically.
 //   - `subscription-stripe:config:api-key` + `:webhook-secret` → system
-//     config keys mit **backing:"secrets"**: der Wert lebt envelope-
-//     verschlüsselt im secrets-Store unter SYSTEM_TENANT_ID, adressiert
-//     wird er als config-Key. `mask` leitet den Sysadmin-configEdit-Screen
-//     + Settings-Hub-Nav ab — kein handgeschriebenes r.screen/r.nav in der
-//     App mehr (v2 hatte die Keys als `r.secret` + App-eigene Maske).
+//     config keys with **backing:"secrets"**: the value is envelope-encrypted
+//     in the secrets store under SYSTEM_TENANT_ID and addressed as a
+//     config key. `mask` derives the sysadmin configEdit screen +
+//     Settings-Hub navigation — the app no longer needs handwritten
+//     r.screen/r.nav entries (v2 used `r.secret` keys + an app-owned form).
 //   - `subscription-stripe:config:billing-live` (shortKey `billingLive`,
-//     kebab-qualifiziert von r.config) → **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).
+//     kebab-qualified by r.config) → **system config**
+//     (boolean, default false). The master switch: without it, checkout may
+//     not create a Stripe session; this is enforced in the
+//     createCheckoutSession gate.
 //
-// **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.
+// **Factory options as fallback:** `createSubscriptionStripeFeature({
+// apiKey, webhookSecret, priceToTier })` remains — apiKey/webhookSecret
+// are now OPTIONAL and serve only as fallbacks during the env→secrets
+// bridge phase and in tests that do not wire a secrets context. `priceToTier`
+// (Stripe price ID → app tier name) remains a factory option: it is
+// app-specific, is not a secret, and changes infrequently.
 //
-// **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).
+// **Webhook + system secrets:** verifyAndParseWebhook is pre-tenant
+// (no ctx). The billing-foundation webhook handler passes a system-scoped
+// SecretsContext as the third argument, from which the plugin reads the
+// api key + webhook secret without auditing (a sanctioned framework-internal
+// read).
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
@@ -115,17 +116,17 @@ export function stripeEnvSchema<const TPrice extends string>(options: {
 }
 
 export type SubscriptionStripeOptions = {
-  /** Bridge-fallback webhook-secret. Optional: v2 liest aus dem
-   *  `subscription-stripe:config:webhook-secret`-Key (backing:"secrets").
-   *  Gesetzt nur während der env→secrets-Übergangsphase / in Tests. */
+  /** Bridge-fallback webhook secret. Optional: v2 reads from the
+   *  `subscription-stripe:config:webhook-secret` key (backing:"secrets").
+   *  Set only during the env→secrets transition phase / in tests. */
   readonly webhookSecret?: string;
-  /** Bridge-fallback api-key. Optional: v2 liest aus dem
-   *  `subscription-stripe:config:api-key`-Key (backing:"secrets"). */
+  /** Bridge-fallback API key. Optional: v2 reads from the
+   *  `subscription-stripe:config:api-key` key (backing:"secrets"). */
   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). */
+  /** Price-to-tier mapping. The plugin reads the price ID from the Stripe
+   *  event (subscription.items.data[0].price.id) and maps it to a tier name.
+   *  App-specific, so it remains a factory option. If the price ID is absent
+   *  from the mapping → null (event ignored). */
   readonly priceToTier?: Readonly<Record<string, string>>;
   /** Whether a mode:"payment" checkout (one-off top-ups etc.) gets a Stripe
    *  invoice — a receipt/invoice document Stripe generates and sends to the
@@ -161,11 +162,11 @@ function validateOneOffPriceIds(priceIds: readonly string[]): void {
 }
 
 /**
- * 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".
+ * Factory for the subscription-stripe feature. Always mounts (no
+ * key-presence guard) — activity is gated at runtime through config/secrets
+ * (following the feature-toggles pattern). The returned FeatureDefinition
+ * registers the plugin under billing-foundation's "subscriptionProvider"
+ * extension with entityName "stripe".
  */
 export function createSubscriptionStripeFeature(
   options: SubscriptionStripeOptions = {},
@@ -192,15 +193,15 @@ export function createSubscriptionStripeFeature(
     // the value lives envelope-encrypted in the secrets store under
     // SYSTEM_TENANT_ID, while `mask` derives the sysadmin settings screen +
     // Settings-Hub nav (no hand-written r.screen/r.nav in the consuming app).
-    // billingLive is the #104 master switch. The factory-fallback
+    // billingLive is the master switch. The factory-fallback
     // (options.apiKey/.webhookSecret) covers the env→secrets bridge + tests.
     const configKeys = r.config({
       keys: {
         [STRIPE_API_KEY_CONFIG]: createSystemConfig("text", {
           backing: "secrets",
-          // Prefix-Guard, deckungsgleich mit subscriptionStripeEnvSchema:
-          // fängt den Paste-the-wrong-field-Fehler (pk_/price_), ohne den
-          // base62-Body zu constrainen. Anchored, kein Backtracking → kein ReDoS.
+          // Prefix guard, matching subscriptionStripeEnvSchema:
+          // catches the wrong-field paste error (pk_/price_) without
+          // constraining the base62 body. Anchored, with no backtracking → no ReDoS.
           pattern: { regex: "^(sk|rk)_(test|live)_" },
           write: access.systemAdmin,
           read: access.admin,
@@ -249,6 +250,7 @@ export function createSubscriptionStripeFeature(
     const portalConfigurationCache = new Map<string, string>();
 
     const plugin: SubscriptionProviderPlugin = {
+      displayName: "Stripe",
       verifyAndParseWebhook: verifyAndParseStripeWebhook(runtimes.webhook, {
         priceToTier: options.priceToTier ?? {},
       }),

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

@@ -1,10 +1,10 @@
-// Public API of the subscription-stripe bundled-feature.
+// Public API of the subscription-stripe bundled feature.
 //
-// **Internal-only** (NICHT im public-barrel — App-Builder nutzt das nie direkt):
-//   - StripeWebhookOptions / verifyAndParseStripeWebhook (intern vom
-//     feature.ts factory aufgerufen)
-//   - mapStripeEventType / mapStripeStatus (pure helpers, test-only;
-//     direct-import aus dem File wenn echt mal extern gebraucht)
+// **Internal-only** (not in the public barrel — the App Builder never uses it directly):
+//   - StripeWebhookOptions / verifyAndParseStripeWebhook (called internally by the
+//     feature.ts factory)
+//   - mapStripeEventType / mapStripeStatus (pure helpers, for tests only;
+//     import directly from the file only if truly needed externally)
 
 export {
   STRIPE_PROVIDER_NAME,

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -1,19 +1,19 @@
-// Stripe-Plugin-Methoden für die POST-tenant-resolution-Phase:
+// Stripe plugin methods for the POST-tenant-resolution phase:
 // createCheckoutSession, createPortalSession, cancelSubscription,
-// retrieveSubscription, retrievePrices, planSwitchSession.
+// retrieveSubscription, retrievePrices, and planSwitchSession.
 //
-// Werden vom Plugin-build (feature.ts) als methods auf dem
-// SubscriptionProviderPlugin registriert. Anders als
-// verifyAndParseWebhook (= pre-tenant) bekommen diese den vollen
-// 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.
+// The plugin build (`feature.ts`) registers these as methods on
+// `SubscriptionProviderPlugin`. Unlike verifyAndParseWebhook (= pre-tenant),
+// they receive the full HandlerContext and resolve the Stripe client from
+// the runtime at call time (using the audited api-key from system-secrets),
+// rather than from a mount-time closure. Key rotation therefore works
+// without a redeploy.
 //
-// **Type-Ableitung:** die options-shapes der methods werden
-// **direkt vom Plugin-Contract** abgeleitet (`Parameters<NonNullable
-// <SubscriptionProviderPlugin["...method"]>>[1]`). Wenn Foundation den
-// Contract erweitert (z.B. neuer optionaler Field), bemerkt der
-// Stripe-Plugin das beim TS-Compile, nicht erst zur Laufzeit.
+// **Type derivation:** method option shapes are derived **directly from the
+// plugin contract** (`Parameters<NonNullable
+// <SubscriptionProviderPlugin["...method"]>>[1]`). If Foundation extends the
+// contract (for example, with a new optional field), the Stripe plugin detects
+// it at TypeScript compile time rather than at runtime.
 
 import { createHash } from "node:crypto";
 import {
@@ -30,15 +30,10 @@ import Stripe from "stripe";
 import type { StripeCtxRuntime } from "./runtime.ts";
 import { isResourceMissingStripeError, mapStripeSubscriptionState } from "./verify-webhook.ts";
 
-// =============================================================================
-// createCheckoutSession
-// =============================================================================
-//
-// Stripe-Checkout-Session erstellen. Der hosted-page-URL wird returnt;
-// der App-Builder redirected den Tenant-Admin dorthin. Nach erfolgreichem
-// checkout sendet Stripe `customer.subscription.created` mit
-// `metadata.tenantId` zurück — das ist wie der subsequent webhook den
-// Tenant resolved.
+// Create a Stripe Checkout Session and return its hosted-page URL for the
+// app builder to redirect the tenant admin. After checkout, Stripe sends
+// `customer.subscription.created` with `metadata.tenantId`; the subsequent
+// webhook uses it to resolve the tenant.
 
 export type StripeCheckoutOptions = Parameters<
   NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
@@ -120,11 +115,11 @@ export function createStripeCheckoutSession(
   { paymentInvoiceCreation = true }: StripeCheckoutSessionRuntimeOptions = {},
 ) {
   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.
+    // Invariant: without billing-live, no Stripe session may be created
+    // (sk_test_-keys in production would otherwise create a test-mode checkout).
+    // Throw before every Stripe call. The guard used to be provided by the
+    // unmounted plugin; Stripe is now always mounted, so the
+    // billing-live-config-key gates the write side.
     await runtime.assertBillingLive(ctx);
     const stripe = await runtime.clientForCtx(ctx);
     const mode = options.mode ?? "subscription";

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

@@ -33,7 +33,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import Stripe from "stripe";
 import { SUBSCRIPTION_STRIPE_FEATURE } from "./constants.ts";
 
@@ -49,7 +49,7 @@ export function createStripeClientCache(): (apiKey: string) => Stripe {
     const cached = cache.get(apiKey);
     if (cached) return cached;
     // No apiVersion pin — a string literal breaks consumers' typecheck on newer
-    // stripe SDKs (#256); the SDK's own default keeps wire-version and types aligned.
+    // stripe SDKs; the SDK's own default keeps wire-version and types aligned.
     const client = new Stripe(apiKey);
     cache.set(apiKey, client);
     return client;
@@ -68,13 +68,14 @@ export type StripeRuntimeDeps = {
 // (the un-audited webhook path + the audited ctx read here) therefore returns
 // the JSON-quoted string and must parse it back. The factory fallback is a
 // plain env string and stays raw — so parsing is applied only to the store
-// read, never to the fallback.
+// read, never to the fallback. The error must not carry the input: the JSON
+// parser's own message would repeat the credential into logs and the 401 body.
 function parseStoredSecret(raw: string | undefined): string | undefined {
   if (raw === undefined || raw.length === 0) return undefined;
-  // parseJsonOrThrow is the sanctioned safe-parse (same helper the config
-  // resolver's deserializeValue uses for this very value) — mirrors how the
-  // store round-trips a backing:"secrets" text value.
-  const parsed = parseJsonOrThrow<unknown>(raw, "subscription-stripe credential (backing:secrets)");
+  const parsed = parseJsonSafe<unknown>(raw, undefined);
+  if (parsed === undefined) {
+    throw new Error("subscription-stripe credential (backing:secrets) is not valid JSON");
+  }
   return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
 }
 
@@ -83,7 +84,7 @@ function parseStoredSecret(raw: string | undefined): string | undefined {
 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
+   *  invariant: no Stripe session may be created while billing is not
    *  live (sk_test_ keys in prod must not produce a live checkout).
    *  `handlerName` names the write-handler in the thrown error — defaults to
    *  "create-checkout-session" for existing callers, but plan-switch/portal