@cosmicdrift/kumiko-bundled-features 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @cosmicdrift/kumiko-bundled-features
 
+## 0.8.0
+
+### Minor Changes
+
+- 145b8df: Add env-var contracts for four bundled-features (Sprint 9.3, Migration Phase 2).
+
+  **New API:**
+
+  - `secretsEnvSchema` — `KUMIKO_SECRETS_MASTER_KEY_V1` (base64-32 KEK, refined for length) + `KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION` (default `"1"`).
+  - `authEmailPasswordEnvSchema` — `JWT_SECRET` (≥32 chars) + `JWT_ISSUER` (optional).
+  - `subscriptionStripeEnvSchema` — `STRIPE_WEBHOOK_SECRET` + `STRIPE_API_KEY` (both non-empty, both `pulumi.secret=true`).
+  - `subscriptionMollieEnvSchema` — `MOLLIE_API_KEY` (`test_` or `live_` prefix, `pulumi.secret=true`).
+
+  Each schema is exported from its feature's barrel and attached via `r.envSchema(...)` at feature-mount-time. Apps that mount these features via `composeEnvSchema({ features, ... })` get aggregated boot-validation for the relevant env-vars with source-attribution (`(auth-email-password)`, `(secrets)`, `(subscription-stripe)`, `(subscription-mollie)`).
+
+  **Plan-Doc-Drift dokumentiert:** `mail-transport-smtp` bekommt KEIN envSchema. SMTP_HOST/PORT/SECURE/FROM/AUTH-USER sind tenant-config, SMTP_PASSWORD ist tenant-secret via `r.secret()` — keine process.env-Vars im Feature. Apps die SMTP_HOST etc. aus env seeden, deklarieren das in ihrem `extend`-block.
+
+  **Kumiko-Pattern:** Das schema ist Contract, nicht Doku. Wenn eine App die var anders nennt (z.B. `MY_JWT` statt `JWT_SECRET`), ist sie off-pattern — `composeEnvSchema` würde sie unter dem standardisierten Namen erwarten.
+
+  **Backward-compat:** Purely additive. Apps ohne `composeEnvSchema({features})` behavior unverändert.
+
+### Patch Changes
+
+- Updated dependencies [f34af9a]
+- Updated dependencies [dff4123]
+  - @cosmicdrift/kumiko-framework@0.8.0
+  - @cosmicdrift/kumiko-renderer@0.8.0
+  - @cosmicdrift/kumiko-dispatcher-live@0.8.0
+  - @cosmicdrift/kumiko-renderer-web@0.8.0
+
 ## 0.7.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.7.0",
+  "version": "0.8.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>",
@@ -74,10 +74,10 @@
     "@aws-sdk/client-s3": "^3.1045.0",
     "@aws-sdk/lib-storage": "^3.1045.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@cosmicdrift/kumiko-dispatcher-live": "0.7.0",
-    "@cosmicdrift/kumiko-framework": "0.7.0",
-    "@cosmicdrift/kumiko-renderer": "0.7.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.7.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.8.0",
+    "@cosmicdrift/kumiko-framework": "0.8.0",
+    "@cosmicdrift/kumiko-renderer": "0.8.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.8.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

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

@@ -0,0 +1,210 @@
+import { randomBytes } from "node:crypto";
+import {
+  composeEnvSchema,
+  type KumikoBootError,
+  parseEnv,
+} from "@cosmicdrift/kumiko-framework/env";
+import { describe, expect, it } from "vitest";
+import { authEmailPasswordEnvSchema, createAuthEmailPasswordFeature } from "../auth-email-password";
+import { createSecretsFeature, secretsEnvSchema } from "../secrets";
+import {
+  createSubscriptionMollieFeature,
+  subscriptionMollieEnvSchema,
+} from "../subscription-mollie";
+import {
+  createSubscriptionStripeFeature,
+  subscriptionStripeEnvSchema,
+} from "../subscription-stripe";
+
+const validKek = randomBytes(32).toString("base64");
+
+describe("secretsEnvSchema", () => {
+  it("accepts a base64-32 KEK and defaults CURRENT_VERSION to '1'", () => {
+    const env = parseEnv(secretsEnvSchema, {
+      KUMIKO_SECRETS_MASTER_KEY_V1: validKek,
+    });
+    expect(env.KUMIKO_SECRETS_MASTER_KEY_V1).toBe(validKek);
+    expect(env.KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION).toBe("1");
+  });
+
+  it("rejects a base64 value that decodes to !=32 bytes", () => {
+    try {
+      parseEnv(secretsEnvSchema, { KUMIKO_SECRETS_MASTER_KEY_V1: "dGVzdA==" });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const boot = err as KumikoBootError;
+      const v1 = boot.errors.find((e) => e.name === "KUMIKO_SECRETS_MASTER_KEY_V1");
+      expect(v1?.kind).toBe("invalid");
+      expect(v1?.message).toContain("32 bytes");
+    }
+  });
+
+  it("rejects a non-numeric CURRENT_VERSION", () => {
+    try {
+      parseEnv(secretsEnvSchema, {
+        KUMIKO_SECRETS_MASTER_KEY_V1: validKek,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "two",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const cur = (err as KumikoBootError).errors.find(
+        (e) => e.name === "KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION",
+      );
+      expect(cur?.kind).toBe("invalid");
+    }
+  });
+
+  it("attaches the schema via r.envSchema() on createSecretsFeature()", () => {
+    const f = createSecretsFeature();
+    expect(f.envSchema).toBe(secretsEnvSchema);
+  });
+});
+
+describe("authEmailPasswordEnvSchema", () => {
+  it("accepts JWT_SECRET ≥32 chars; JWT_ISSUER stays optional", () => {
+    const env = parseEnv(authEmailPasswordEnvSchema, {
+      JWT_SECRET: "x".repeat(32),
+    });
+    expect(env.JWT_SECRET.length).toBe(32);
+    expect(env.JWT_ISSUER).toBeUndefined();
+  });
+
+  it("rejects a short JWT_SECRET", () => {
+    try {
+      parseEnv(authEmailPasswordEnvSchema, { JWT_SECRET: "short" });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const jwt = (err as KumikoBootError).errors.find((e) => e.name === "JWT_SECRET");
+      expect(jwt?.kind).toBe("invalid");
+    }
+  });
+
+  it("attaches the schema via r.envSchema() on createAuthEmailPasswordFeature()", () => {
+    const f = createAuthEmailPasswordFeature();
+    expect(f.envSchema).toBe(authEmailPasswordEnvSchema);
+  });
+});
+
+describe("subscriptionStripeEnvSchema", () => {
+  it("accepts non-empty webhookSecret + apiKey", () => {
+    const env = parseEnv(subscriptionStripeEnvSchema, {
+      STRIPE_WEBHOOK_SECRET: "whsec_abc",
+      STRIPE_API_KEY: "sk_test_xyz",
+    });
+    expect(env.STRIPE_WEBHOOK_SECRET).toBe("whsec_abc");
+    expect(env.STRIPE_API_KEY).toBe("sk_test_xyz");
+  });
+
+  it("rejects empty values", () => {
+    try {
+      parseEnv(subscriptionStripeEnvSchema, {
+        STRIPE_WEBHOOK_SECRET: "",
+        STRIPE_API_KEY: "",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const boot = err as KumikoBootError;
+      expect(boot.errors.length).toBe(2);
+    }
+  });
+
+  it("attaches the schema via r.envSchema() on the factory", () => {
+    const f = createSubscriptionStripeFeature({
+      webhookSecret: "whsec_x",
+      apiKey: "sk_test_y",
+      priceToTier: {},
+    });
+    expect(f.envSchema).toBe(subscriptionStripeEnvSchema);
+  });
+});
+
+describe("subscriptionMollieEnvSchema", () => {
+  it("accepts test_ and live_ prefixes", () => {
+    expect(parseEnv(subscriptionMollieEnvSchema, { MOLLIE_API_KEY: "test_abc" })).toBeDefined();
+    expect(parseEnv(subscriptionMollieEnvSchema, { MOLLIE_API_KEY: "live_xyz" })).toBeDefined();
+  });
+
+  it("rejects an unprefixed key", () => {
+    try {
+      parseEnv(subscriptionMollieEnvSchema, { MOLLIE_API_KEY: "no-prefix" });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const k = (err as KumikoBootError).errors.find((e) => e.name === "MOLLIE_API_KEY");
+      expect(k?.kind).toBe("invalid");
+    }
+  });
+
+  it("attaches the schema via r.envSchema() on the factory", () => {
+    const f = createSubscriptionMollieFeature({
+      apiKey: "test_x",
+      webhookUrl: "https://example.com/webhook",
+      priceToTier: {},
+      priceToConfig: {},
+    });
+    expect(f.envSchema).toBe(subscriptionMollieEnvSchema);
+  });
+});
+
+describe("compose across all Phase-2 features", () => {
+  it("merges all four schemas with correct source attribution", () => {
+    const features = [
+      createSecretsFeature(),
+      createAuthEmailPasswordFeature(),
+      createSubscriptionStripeFeature({
+        webhookSecret: "whsec_x",
+        apiKey: "sk_test_y",
+        priceToTier: {},
+      }),
+      createSubscriptionMollieFeature({
+        apiKey: "test_x",
+        webhookUrl: "https://example.com",
+        priceToTier: {},
+        priceToConfig: {},
+      }),
+    ];
+    const { schema, sources } = composeEnvSchema({ features });
+    const keys = Object.keys(schema.shape).sort();
+    expect(keys).toEqual([
+      "JWT_ISSUER",
+      "JWT_SECRET",
+      "KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION",
+      "KUMIKO_SECRETS_MASTER_KEY_V1",
+      "MOLLIE_API_KEY",
+      "STRIPE_API_KEY",
+      "STRIPE_WEBHOOK_SECRET",
+    ]);
+    expect(sources["JWT_SECRET"]).toBe("auth-email-password");
+    expect(sources["KUMIKO_SECRETS_MASTER_KEY_V1"]).toBe("secrets");
+    expect(sources["STRIPE_API_KEY"]).toBe("subscription-stripe");
+    expect(sources["MOLLIE_API_KEY"]).toBe("subscription-mollie");
+  });
+
+  it("KumikoBootError.format() shows feature-source for missing feature-env-vars", () => {
+    const features = [
+      createSecretsFeature(),
+      createAuthEmailPasswordFeature(),
+      createSubscriptionStripeFeature({
+        webhookSecret: "whsec_x",
+        apiKey: "sk_test_y",
+        priceToTier: {},
+      }),
+      createSubscriptionMollieFeature({
+        apiKey: "test_x",
+        webhookUrl: "https://example.com",
+        priceToTier: {},
+        priceToConfig: {},
+      }),
+    ];
+    const composed = composeEnvSchema({ features });
+    try {
+      parseEnv(composed.schema, {}, { sources: composed.sources });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const out = (err as KumikoBootError).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)");
+    }
+  });
+});

package/src/auth-email-password/feature.ts

@@ -1,4 +1,5 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
 import { changePasswordWrite } from "./handlers/change-password.write";
 import { createInviteAcceptHandler } from "./handlers/invite-accept.write";
 import { createInviteAcceptWithLoginHandler } from "./handlers/invite-accept-with-login.write";
@@ -19,6 +20,31 @@ import {
 } from "./handlers/signup-request.write";
 import { createVerifyEmailHandler } from "./handlers/verify-email.write";
 
+/**
+ * Env-vars contract for the `auth-email-password` feature.
+ *
+ * `JWT_SECRET` is read by `runProdApp` at boot to sign session JWTs.
+ * Apps mount this feature via `createAuthEmailPasswordFeature(opts)` and
+ * pass `jwtSecret` to `runProdApp` separately — declaring it here means
+ * `composeEnvSchema({ features: [authFeature, ...] })` flags a missing
+ * or short JWT_SECRET at the aggregated boot-validation stage instead of
+ * letting it surface as a JWT-decode-failure on first login.
+ *
+ * `JWT_ISSUER` is optional (Hono-JWT pins the `iss` claim when set).
+ */
+export const authEmailPasswordEnvSchema = z.object({
+  JWT_SECRET: z
+    .string()
+    .min(32, "JWT_SECRET must be ≥32 chars (HS256 minimum)")
+    .describe("Symmetric secret for signing session JWTs (HS256).")
+    .meta({ kumiko: { pulumi: { generator: "openssl rand -base64 48", secret: true } } }),
+  JWT_ISSUER: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Optional `iss` claim pinned on every minted JWT."),
+});
+
 // Opt-in configuration for the password-reset flow. When omitted the
 // request-password-reset / reset-password handlers are not registered —
 // the framework-level routes stay 404 and callers know the flow is off.
@@ -101,6 +127,7 @@ export function createAuthEmailPasswordFeature(
   return defineFeature("auth-email-password", (r) => {
     r.requires("user");
     r.requires("tenant");
+    r.envSchema(authEmailPasswordEnvSchema);
 
     const handlers = {
       login: r.writeHandler(

package/src/auth-email-password/index.ts

@@ -25,7 +25,7 @@ export type {
   PasswordResetOptions,
   SignupOptions,
 } from "./feature";
-export { createAuthEmailPasswordFeature } from "./feature";
+export { authEmailPasswordEnvSchema, createAuthEmailPasswordFeature } from "./feature";
 export { hashPassword, verifyPassword } from "./password-hashing";
 // Generic HMAC-signed single-purpose token helpers. Re-exported damit
 // app-spezifische out-of-band-Flows (subscriber-confirm, magic-links,

package/src/secrets/feature.ts

@@ -1,6 +1,7 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { z } from "zod";
 import { deleteWrite } from "./handlers/delete.write";
 import { listQuery } from "./handlers/list.query";
 import { rotateJob } from "./handlers/rotate.job";
@@ -8,6 +9,41 @@ import { setWrite } from "./handlers/set.write";
 import { secretReadSchema } from "./secrets-context";
 import { tenantSecretEntity } from "./table";
 
+/**
+ * Env-vars contract for the `secrets` feature. Apps merge this via
+ * `composeEnvSchema({ features: [secretsFeature, ...] })` so boot-time
+ * validation catches a missing/short KEK before the first `.get()` call.
+ *
+ * Rotation: declare additional versions (V2, V3, …) in the app's `extend`
+ * block — the env-master-key-provider scans the env for any
+ * `KUMIKO_SECRETS_MASTER_KEY_V<n>` matching `/^KUMIKO_SECRETS_MASTER_KEY_V(\d+)$/`
+ * and picks the highest as the active KEK unless
+ * `KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION` pins one explicitly.
+ */
+export const secretsEnvSchema = z.object({
+  KUMIKO_SECRETS_MASTER_KEY_V1: z
+    .string()
+    .refine(
+      (v) => {
+        try {
+          return Buffer.from(v, "base64").length === 32;
+        } catch {
+          return false;
+        }
+      },
+      { message: "must be base64-encoded 32 bytes (AES-256 KEK)" },
+    )
+    .describe("AES-256 master-key (KEK) for tenant-secrets encryption.")
+    .meta({ kumiko: { pulumi: { generator: "openssl rand -base64 32", secret: true } } }),
+  KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: z
+    .string()
+    .regex(/^\d+$/, "must be a positive integer (V<n> selector)")
+    .default("1")
+    .describe(
+      "Pins the active KEK version. Default '1'. Bump after writing a higher KUMIKO_SECRETS_MASTER_KEY_V<n>.",
+    ),
+});
+
 export {
   createSecretsContext,
   type SecretsContext,
@@ -53,6 +89,8 @@ export function requireSecretsContext(
 
 export function createSecretsFeature(): FeatureDefinition {
   return defineFeature("secrets", (r) => {
+    r.envSchema(secretsEnvSchema);
+
     // ES entity: set/delete go through the executor, `tenantSecret.created/
     // .updated/.deleted` events land on the aggregate stream. Reads fire a
     // separate `tenantSecretRead` event per call (see secrets-context.get

package/src/secrets/index.ts

@@ -6,6 +6,7 @@ export {
   type SecretsContextOptions,
   type StoredEnvelope,
   type StoredMetadata,
+  secretsEnvSchema,
   TENANT_SECRET_READ_EVENT,
   tenantSecretsTable,
 } from "./feature";

package/src/subscription-mollie/feature.ts

@@ -42,10 +42,25 @@
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createMollieClient } from "@mollie/api-client";
+import { z } from "zod";
 import { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants";
 import { createMollieCheckoutSession, type MolliePriceConfig } from "./plugin-methods";
 import { type MollieClientShape, verifyAndParseMollieWebhook } from "./verify-webhook";
 
+/**
+ * Env-vars contract for the `subscription-mollie` feature.
+ * Apps load `MOLLIE_API_KEY` from env and forward it to
+ * `createSubscriptionMollieFeature({ apiKey, ... })`.
+ */
+export const subscriptionMollieEnvSchema = z.object({
+  MOLLIE_API_KEY: z
+    .string()
+    .min(1, "MOLLIE_API_KEY must not be empty")
+    .regex(/^(test|live)_/, "MOLLIE_API_KEY must start with 'test_' or 'live_'")
+    .describe("Mollie API key (`test_...` for sandbox, `live_...` for production).")
+    .meta({ kumiko: { pulumi: { secret: true } } }),
+});
+
 export type SubscriptionMollieOptions = {
   /** Mollie-API-key (`test_...` oder `live_...`). App-wide, beim Plugin-
    *  mount aus process.env oder system-config. */
@@ -132,6 +147,7 @@ export function createSubscriptionMollieFeature(
 
   return defineFeature(SUBSCRIPTION_MOLLIE_FEATURE, (r) => {
     r.requires("billing-foundation");
+    r.envSchema(subscriptionMollieEnvSchema);
 
     const plugin: SubscriptionProviderPlugin = {
       verifyAndParseWebhook: verifyAndParse,

package/src/subscription-mollie/index.ts

@@ -9,5 +9,6 @@ export { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants";
 export {
   createSubscriptionMollieFeature,
   type SubscriptionMollieOptions,
+  subscriptionMollieEnvSchema,
 } from "./feature";
 export type { MolliePriceConfig } from "./plugin-methods";

package/src/subscription-stripe/feature.ts

@@ -38,6 +38,7 @@
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import Stripe from "stripe";
+import { z } from "zod";
 import { STRIPE_PROVIDER_NAME, SUBSCRIPTION_STRIPE_FEATURE } from "./constants";
 import {
   createStripeCancelSubscription,
@@ -46,6 +47,29 @@ import {
 } from "./plugin-methods";
 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`.
+ */
+export const subscriptionStripeEnvSchema = z.object({
+  STRIPE_WEBHOOK_SECRET: z
+    .string()
+    .min(1, "STRIPE_WEBHOOK_SECRET must not be empty")
+    .describe("Stripe webhook-signing secret (`whsec_...` from the Stripe dashboard).")
+    .meta({ kumiko: { pulumi: { secret: true } } }),
+  STRIPE_API_KEY: z
+    .string()
+    .min(1, "STRIPE_API_KEY must not be empty")
+    .describe("Stripe API key (`sk_live_...` / `sk_test_...`).")
+    .meta({ kumiko: { pulumi: { secret: true } } }),
+});
+
 export type SubscriptionStripeOptions = {
   /** Webhook-secret aus dem Stripe-Dashboard. App-wide. Plugin throws
    *  beim runtime wenn empty (= App-Owner hat sub-stripe gemountet
@@ -105,6 +129,7 @@ export function createSubscriptionStripeFeature(
     // tenant-config noch tenant-secrets (alles app-wide via factory-
     // options).
     r.requires("billing-foundation");
+    r.envSchema(subscriptionStripeEnvSchema);
 
     // Plugin: register against subscription-foundation's
     // "subscriptionProvider" extension. entityName "stripe" matcht den

package/src/subscription-stripe/index.ts

@@ -11,4 +11,8 @@ export {
   StripeEventTypes,
   SUBSCRIPTION_STRIPE_FEATURE,
 } from "./constants";
-export { createSubscriptionStripeFeature, type SubscriptionStripeOptions } from "./feature";
+export {
+  createSubscriptionStripeFeature,
+  type SubscriptionStripeOptions,
+  subscriptionStripeEnvSchema,
+} from "./feature";