@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,251 @@
+// kumiko-feature-version: 3
+//
+// subscription-stripe — Stripe-Plugin für die 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.
+//   - `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).
+//   - `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).
+//
+// **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.
+//
+// **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 {
+  access,
+  createSystemConfig,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import {
+  STRIPE_API_KEY_CONFIG,
+  STRIPE_BILLING_LIVE_CONFIG,
+  STRIPE_PROVIDER_NAME,
+  STRIPE_WEBHOOK_SECRET_CONFIG,
+  SUBSCRIPTION_STRIPE_FEATURE,
+} from "./constants.js";
+import {
+  createStripeCancelSubscription,
+  createStripeCheckoutSession,
+  createStripePlanSwitchSession,
+  createStripePortalSession,
+  createStripePriceCache,
+  createStripeRetrievePrices,
+  createStripeRetrieveSubscription,
+} from "./plugin-methods.js";
+import { createStripeRuntimes } from "./runtime.js";
+import { verifyAndParseStripeWebhook } from "./verify-webhook.js";
+
+/**
+ * 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_...`). 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_...`). Bridge-fallback — prefer the secret.",
+    )
+    .meta({ kumiko: { pulumi: { secret: true } } })
+    .optional(),
+});
+
+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. */
+  readonly webhookSecret?: string;
+  /** Bridge-fallback api-key. Optional: v2 liest aus dem
+   *  `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). */
+  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
+   *  customer for that payment. Default true. Stripe Invoicing charges a
+   *  per-invoice fee on top of the payment itself, so a high-volume,
+   *  low-value payment flow may want `false` to opt out. Never applied in
+   *  mode:"subscription" — Stripe rejects invoice_creation there; the
+   *  subscription's own invoicing covers it. */
+  readonly paymentInvoiceCreation?: boolean;
+  /** Allowlist of Stripe price-ids a mode:"payment" (one-off) checkout may
+   *  target — checkout-core's `openCheckout` rejects any other priceId as
+   *  `unknown_price`. App-specific and empty by default: without an
+   *  explicit allowlist every one-off checkout is closed, the same
+   *  fail-closed default `priceToTier` has for mode:"subscription". */
+  readonly oneOffPriceIds?: readonly string[];
+};
+
+// Validated once at feature-build time (not per-request) so a config typo
+// (a pasted-twice priceId, a blank string from a bad env-join) fails app
+// startup instead of silently widening — or narrowing — the one-off
+// allowlist at request time. Mirrors legal-pages' validateRoutes.
+function validateOneOffPriceIds(priceIds: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const priceId of priceIds) {
+    if (priceId.length === 0) {
+      throw new Error("subscription-stripe: oneOffPriceIds must not contain an empty string");
+    }
+    if (seen.has(priceId)) {
+      throw new Error(`subscription-stripe: duplicate oneOffPriceIds entry "${priceId}"`);
+    }
+    seen.add(priceId);
+  }
+}
+
+/**
+ * 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 = {},
+): FeatureDefinition {
+  validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+  return defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
+    r.describe(
+      'Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, `retrievePrices` (10-minute TTL-cached price lookup for the billing-plans catalog), `createPlanSwitchSession` (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), `retrieveSubscription` (live provider-side snapshot for the `sync-subscriptions` backfill job, mapped identically to the webhook path), plus `isBillingEnabled` (billingLive + an api-key existence probe, no secret read).',
+    );
+    r.uiHints({
+      displayLabel: "Billing · Stripe",
+      category: "billing",
+      recommended: false,
+    });
+    // Hard-deps: billing-foundation (plugin-host) + config (billing-live +
+    // backing:"secrets" credentials) + secrets (the store the backing:secrets
+    // dispatch reads/writes + its tenant_secrets table).
+    r.requires("billing-foundation");
+    r.requires("config");
+    r.requires("secrets");
+    r.envSchema(subscriptionStripeEnvSchema);
+
+    // Runtime config. api-key + webhook-secret declare backing:"secrets" —
+    // 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
+    // (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.
+          pattern: { regex: "^(sk|rk)_(test|live)_" },
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-stripe.api-key", icon: "key", order: 1 },
+        }),
+        [STRIPE_WEBHOOK_SECRET_CONFIG]: createSystemConfig("text", {
+          backing: "secrets",
+          pattern: { regex: "^whsec_" },
+          write: access.systemAdmin,
+          read: access.admin,
+          mask: { title: "subscription-stripe.webhook-secret", icon: "shield", order: 2 },
+        }),
+        [STRIPE_BILLING_LIVE_CONFIG]: createSystemConfig("boolean", {
+          default: false,
+          // privileged = ["system", "SystemAdmin"]: preserves the legacy
+          // writeAs(system-actor) flip path while the derived configEdit
+          // screen lets a human SystemAdmin toggle go-live directly.
+          write: access.privileged,
+          read: access.admin,
+          mask: { title: "subscription-stripe.billing-live", icon: "rocket", order: 3 },
+        }),
+      },
+    });
+
+    r.translations({
+      keys: {
+        "subscription-stripe.api-key": { en: "Stripe API key" },
+        "subscription-stripe.webhook-secret": { en: "Stripe webhook secret" },
+        "subscription-stripe.billing-live": { en: "Live billing" },
+        "subscription-stripe.settings": { en: "Stripe" },
+        "screen:subscription-stripe-system.title": { en: "Stripe" },
+      },
+    });
+
+    const runtimes = createStripeRuntimes({
+      apiKeyHandle: configKeys[STRIPE_API_KEY_CONFIG],
+      webhookSecretHandle: configKeys[STRIPE_WEBHOOK_SECRET_CONFIG],
+      billingLiveHandle: configKeys[STRIPE_BILLING_LIVE_CONFIG],
+      fallback: {
+        ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+        ...(options.webhookSecret !== undefined && { webhookSecret: options.webhookSecret }),
+      },
+    });
+
+    const priceCache = createStripePriceCache();
+    const portalConfigurationCache = new Map<string, string>();
+
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: verifyAndParseStripeWebhook(runtimes.webhook, {
+        priceToTier: options.priceToTier ?? {},
+      }),
+      createCheckoutSession: createStripeCheckoutSession(runtimes.ctx, {
+        ...(options.paymentInvoiceCreation !== undefined && {
+          paymentInvoiceCreation: options.paymentInvoiceCreation,
+        }),
+      }),
+      createPortalSession: createStripePortalSession(runtimes.ctx),
+      cancelSubscription: createStripeCancelSubscription(runtimes.ctx),
+      priceToTier: options.priceToTier ?? {},
+      oneOffPriceIds: options.oneOffPriceIds ?? [],
+      isBillingEnabled: runtimes.ctx.isBillingEnabled,
+      retrievePrices: createStripeRetrievePrices(runtimes.ctx, priceCache),
+      retrieveSubscription: createStripeRetrieveSubscription(runtimes.ctx, {
+        priceToTier: options.priceToTier ?? {},
+      }),
+      createPlanSwitchSession: createStripePlanSwitchSession(
+        runtimes.ctx,
+        priceCache,
+        portalConfigurationCache,
+      ),
+    };
+    r.useExtension("subscriptionProvider", STRIPE_PROVIDER_NAME, plugin);
+
+    return { configKeys };
+  });
+}

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

@@ -0,0 +1,18 @@
+// 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)
+
+export {
+  STRIPE_PROVIDER_NAME,
+  StripeEventTypes,
+  SUBSCRIPTION_STRIPE_FEATURE,
+} from "./constants.js";
+export {
+  createSubscriptionStripeFeature,
+  type SubscriptionStripeOptions,
+  subscriptionStripeEnvSchema,
+} from "./feature.js";