@cosmicdrift/kumiko-bundled-features 0.51.0 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.51.0",
+  "version": "0.52.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/subscription-stripe/__tests__/feature.test.ts

@@ -18,8 +18,9 @@ describe("createSubscriptionStripeFeature — shape", () => {
   test("requires billing-foundation + config + secrets (runtime-keys via config/secrets)", () => {
     const feature = createSubscriptionStripeFeature(OPTIONS);
     expect(feature.requires).toContain("billing-foundation");
-    // Drift-Pin (v2): api-key/webhook-secret kommen ZUR LAUFZEIT aus
-    // secrets, billing-live aus config — daher harte deps auf beide.
+    // Drift-Pin (v3): api-key/webhook-secret sind config-Keys mit
+    // backing:"secrets" (Wert im secrets-Store), billing-live plain config —
+    // daher harte deps auf config UND secrets (Store + tenant_secrets-Tabelle).
     expect(feature.requires).toContain("config");
     expect(feature.requires).toContain("secrets");
   });

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

@@ -5,19 +5,19 @@
 // (das deckt der Integration-Test ab).
 
 import { describe, expect, test } from "bun:test";
-import type {
-  ConfigKeyHandle,
-  HandlerContext,
-  SecretKeyHandle,
-} from "@cosmicdrift/kumiko-framework/engine";
+import type { ConfigKeyHandle, HandlerContext } 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 API_KEY_HANDLE: ConfigKeyHandle<"text"> = {
+  name: "subscription-stripe:config:api-key",
+  type: "text",
+};
+const WEBHOOK_SECRET_HANDLE: ConfigKeyHandle<"text"> = {
+  name: "subscription-stripe:config:webhook-secret",
+  type: "text",
 };
 const BILLING_LIVE_HANDLE: ConfigKeyHandle<"boolean"> = {
   name: "subscription-stripe:config:billingLive",
@@ -25,14 +25,16 @@ const BILLING_LIVE_HANDLE: ConfigKeyHandle<"boolean"> = {
 };
 
 /** Stub-SecretsContext: liest aus einer in-memory-map, matcht per
- *  qualified-name. Ignoriert auditCtx (irrelevant für die Resolution). */
+ *  qualified-name. backing:"secrets" persistiert config-Werte JSON-
+ *  serialisiert — der Stub spiegelt das, damit der Runtime-parseStoredSecret
+ *  denselben Pfad nimmt wie gegen den echten Store. Ignoriert auditCtx. */
 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);
+      return value === undefined ? undefined : createSecret(JSON.stringify(value));
     },
     has: async (_tenantId, key) => values[nameOf(key)] !== undefined,
     set: async () => undefined,

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

@@ -45,10 +45,11 @@ import {
 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";
+// was r.config(...) im feature build qualifiziert — `subscription-stripe:
+// config:<shortName>`, backing:"secrets"). Scenario 5 setzt sie via
+// config:write:set + beweist die Resolution durch den Webhook.
+const API_KEY_CONFIG_QN = "subscription-stripe:config:api-key";
+const WEBHOOK_SECRET_CONFIG_QN = "subscription-stripe:config:webhook-secret";
 
 // =============================================================================
 // Setup
@@ -382,15 +383,26 @@ 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",
+    // Set beide Keys via config:write:set (backing:"secrets") als SystemAdmin
+    // — exakt was der abgeleitete Sysadmin-configEdit-Screen / der Bridge-Seed
+    // in prod dispatcht. Der Wert landet JSON-serialisiert envelope-encrypted
+    // im secrets-Store; der Webhook löst ihn via parseStoredSecret wieder auf.
+    // SEEDED_WEBHOOK_SECRET ≠ TEST_SECRET (der fallback).
+    const sysAdmin = createTestUser({
+      id: 9001,
+      tenantId: SYSTEM_TENANT_ID,
+      roles: ["SystemAdmin"],
     });
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: API_KEY_CONFIG_QN, value: SEEDED_API_KEY, scope: "system" },
+      sysAdmin,
+    );
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: WEBHOOK_SECRET_CONFIG_QN, value: SEEDED_WEBHOOK_SECRET, scope: "system" },
+      sysAdmin,
+    );
 
     const tenantStringId = testTenantId(4005);
     const payload = JSON.stringify(

package/src/subscription-stripe/constants.ts

@@ -6,11 +6,12 @@ export const SUBSCRIPTION_STRIPE_FEATURE = "subscription-stripe" as const;
 // `/api/subscription/webhook/stripe`.
 export const STRIPE_PROVIDER_NAME = "stripe" 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;
+// Config-key short-names, qualified to `subscription-stripe:config:<name>`
+// at registry-build. api-key + webhook-secret declare backing:"secrets"
+// (value lives envelope-encrypted in the secrets store under SYSTEM_TENANT_ID)
+// but are addressed as config keys; billingLive is a plain system config flag.
+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;
 
 // =============================================================================

package/src/subscription-stripe/feature.ts

@@ -1,17 +1,18 @@
-// kumiko-feature-version: 2
+// kumiko-feature-version: 3
 //
 // subscription-stripe — Stripe-Plugin für die billing-foundation
 // Plugin-API.
 //
-// **Runtime-config (v2):** Stripe-credentials + der billing-live-Master-
-// Switch kommen ZUR LAUFZEIT aus config/secrets, nicht mehr aus einem
+// **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.
-//   - `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).
+// 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:billingLive` → **system config**
 //     (boolean, default false). Der Master-Switch: ohne ihn darf kein
 //     checkout eine Stripe-Session erzeugen (#104-Invariante, write-side
@@ -31,16 +32,17 @@
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
+  access,
   createSystemConfig,
   defineFeature,
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import {
-  STRIPE_API_KEY_SECRET,
+  STRIPE_API_KEY_CONFIG,
   STRIPE_BILLING_LIVE_CONFIG,
   STRIPE_PROVIDER_NAME,
-  STRIPE_WEBHOOK_SECRET_SECRET,
+  STRIPE_WEBHOOK_SECRET_CONFIG,
   SUBSCRIPTION_STRIPE_FEATURE,
 } from "./constants";
 import {
@@ -80,12 +82,12 @@ export const subscriptionStripeEnvSchema = z.object({
 });
 
 export type SubscriptionStripeOptions = {
-  /** Bridge-fallback webhook-secret. Optional: v2 liest aus
-   *  `subscription-stripe:webhook-secret` (system-secret). Gesetzt nur
-   *  während der env→secrets-Übergangsphase / in Tests. */
+  /** 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
-   *  `subscription-stripe:api-key` (system-secret). */
+  /** 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.
@@ -94,11 +96,6 @@ export type SubscriptionStripeOptions = {
   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. Mountet IMMER (kein
  * key-presence-Guard mehr) — die Aktivität wird runtime über config/secrets
@@ -111,48 +108,70 @@ export function createSubscriptionStripeFeature(
 ): FeatureDefinition {
   return defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
     r.describe(
-      "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).",
+      '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 all four provider methods (webhook verify, checkout, portal, cancel).',
     );
-    // Hard-deps: billing-foundation (plugin-host) + config (billing-live)
-    // + secrets (api-key/webhook-secret).
+    // 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-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.",
+    // 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 },
+        }),
       },
-      redact: SECRET_REDACT,
-      scope: "tenant",
-      required: false,
     });
 
-    const configKeys = r.config({
+    r.translations({
       keys: {
-        [STRIPE_BILLING_LIVE_CONFIG]: createSystemConfig("boolean", { default: false }),
+        "subscription-stripe.api-key": { de: "Stripe API Key", en: "Stripe API Key" },
+        "subscription-stripe.webhook-secret": {
+          de: "Stripe Webhook Secret",
+          en: "Stripe Webhook Secret",
+        },
+        "subscription-stripe.billing-live": {
+          de: "Stripe Billing live",
+          en: "Stripe Billing Live",
+        },
       },
     });
 
     const runtimes = createStripeRuntimes({
-      apiKeyHandle: apiKeySecret,
-      webhookSecretHandle: webhookSecret,
+      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 }),
@@ -170,6 +189,6 @@ export function createSubscriptionStripeFeature(
     };
     r.useExtension("subscriptionProvider", STRIPE_PROVIDER_NAME, plugin);
 
-    return { apiKeySecret, webhookSecret, configKeys };
+    return { configKeys };
   });
 }

package/src/subscription-stripe/runtime.ts

@@ -5,11 +5,11 @@
 // `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).
+//   - `api-key` + `webhook-secret` from system config keys with
+//     backing:"secrets" — the value lives in the secrets store under
+//     SYSTEM_TENANT_ID (Stripe is app-wide), JSON-serialized like any config
+//     value. Both read paths reach it via SecretsContext.get(config-QN) and
+//     parse the JSON back (parseStoredSecret).
 //   - `billing-live` from a **system config** key (default false) — the
 //     master switch that gates whether a checkout may create a live session.
 //
@@ -29,16 +29,16 @@ import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secr
 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 { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import Stripe from "stripe";
 import { 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).";
+  "Set the Stripe API key via config:write:set on `subscription-stripe:config:api-key` (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
@@ -57,12 +57,27 @@ export function createStripeClientCache(): (apiKey: string) => Stripe {
 }
 
 export type StripeRuntimeDeps = {
-  readonly apiKeyHandle: SecretKeyHandle;
-  readonly webhookSecretHandle: SecretKeyHandle;
+  readonly apiKeyHandle: ConfigKeyHandle<"text">;
+  readonly webhookSecretHandle: ConfigKeyHandle<"text">;
   readonly billingLiveHandle: ConfigKeyHandle<"boolean">;
   readonly fallback: { readonly apiKey?: string; readonly webhookSecret?: string };
 };
 
+// backing:"secrets" config keys store their value JSON-serialized in the
+// secrets store (config:write:set → JSON.stringify). A raw SecretsContext.get
+// (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.
+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)");
+  return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
+}
+
 /** Post-tenant runtime: used by checkout/portal/cancel which carry a full
  *  HandlerContext (audited secret reads, config-gate). */
 export type StripeCtxRuntime = {
@@ -94,9 +109,9 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
     if (ctx.secrets) {
       const got = await requireSecretsContext(ctx, SUBSCRIPTION_STRIPE_FEATURE).get(
         SYSTEM_TENANT_ID,
-        deps.apiKeyHandle,
+        deps.apiKeyHandle.name,
       );
-      key = got?.reveal();
+      key = parseStoredSecret(got?.reveal());
     }
     if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
       key = deps.fallback.apiKey;
@@ -113,14 +128,14 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
 
   async function rawRead(
     systemSecrets: SecretsContext | undefined,
-    handle: SecretKeyHandle,
+    handle: ConfigKeyHandle<"text">,
     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();
+      const got = await systemSecrets.get(SYSTEM_TENANT_ID, handle.name);
+      const value = parseStoredSecret(got?.reveal());
       if (value && value.length > 0) return value;
     }
     return fallback && fallback.length > 0 ? fallback : undefined;