@cosmicdrift/kumiko-dev-server 0.214.0 → 0.215.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.214.0",
-  "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Not shipped into production node_modules — see @cosmicdrift/kumiko-server-runtime for the prod boot path.",
+  "version": "0.215.0",
+  "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
@@ -30,6 +30,10 @@
       "types": "./src/compose-stacks.ts",
       "default": "./src/compose-stacks.ts"
     },
+    "./env-schema": {
+      "types": "./src/env-schema.ts",
+      "default": "./src/env-schema.ts"
+    },
     "./setup-test-stack-from-features": {
       "types": "./src/setup-test-stack-from-features.ts",
       "default": "./src/setup-test-stack-from-features.ts"
@@ -55,9 +59,9 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.214.0",
-    "@cosmicdrift/kumiko-framework": "0.214.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.214.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.215.0",
+    "@cosmicdrift/kumiko-framework": "0.215.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.215.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/runtime-classification.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { frameworkCoreEnvSchema as envSchemaViaRelative } from "../env-schema";
+
+// Mirrors infra/guards/runtime-isolation-classify.ts `classifyByDirective`
+// as of kumiko-framework#2337 (first 600 bytes, first 8 lines,
+// `// @runtime <kind>`) — guards against a reformat of compose-stacks.ts
+// pushing the directive out of that window. Doesn't catch infra changing
+// the window/regex itself; that lives in the infra repo's own tests.
+function classifyByDirective(filePath: string): string | null {
+  const head = readFileSync(filePath, "utf8").slice(0, 600);
+  for (const line of head.split("\n").slice(0, 8)) {
+    const match = line.match(/\/\/\s*@runtime\s+(\w+)/);
+    if (match) return match[1] ?? null;
+  }
+  return null;
+}
+
+describe("compose-stacks.ts runtime directive", () => {
+  it("carries a @runtime runtime directive the guard's classifyByDirective will find", () => {
+    const composeStacksPath = fileURLToPath(new URL("../compose-stacks.ts", import.meta.url));
+    expect(classifyByDirective(composeStacksPath)).toBe("runtime");
+  });
+});
+
+describe("@cosmicdrift/kumiko-dev-server/env-schema subpath", () => {
+  it("resolves the same schema as the relative import, and it parses", async () => {
+    const { frameworkCoreEnvSchema: envSchemaViaSubpath } = await import(
+      "@cosmicdrift/kumiko-dev-server/env-schema"
+    );
+    expect(envSchemaViaSubpath).toBe(envSchemaViaRelative);
+    const parsed = envSchemaViaSubpath.parse({
+      DATABASE_URL: "postgres://localhost:5432/db",
+      REDIS_URL: "redis://localhost:6379",
+    });
+    expect(parsed.PORT).toBe("3000");
+  });
+});

package/src/__tests__/scaffold-app.test.ts

@@ -154,6 +154,19 @@ describe("scaffoldApp", () => {
     expect(env).toContain("DATABASE_URL=");
   });
 
+  // kumiko-framework#2330: unset (not pre-filled) so the default stays on
+  // resolveKmsWiring's plaintext fallback — a half-filled trio would throw
+  // the all-or-none error instead of booting.
+  test(".env.example documents the PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY trio, unset by default", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const env = readFileSync(join(dest, ".env.example"), "utf-8");
+    expect(env).toContain("PLATFORM_KEK=\n");
+    expect(env).toContain("SUBJECT_KEYS_DATABASE_URL=\n");
+    expect(env).toContain("KUMIKO_BLIND_INDEX_KEY=\n");
+  });
+
   test("docker-compose.yml ports + credentials match the .env.example *_URL defaults", async () => {
     const dest = join(tmp, "my-shop");
     await scaffoldApp({ name: "my-shop", destination: dest });
@@ -198,6 +211,15 @@ describe("scaffoldApp", () => {
     expect(readme).toContain("- `delivery`");
   });
 
+  test("README documents the plaintext-PII default until PLATFORM_KEK/SUBJECT_KEYS_DATABASE_URL/KUMIKO_BLIND_INDEX_KEY are set", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const readme = readFileSync(join(dest, "README.md"), "utf-8");
+    expect(readme).toContain("PLATFORM_KEK");
+    expect(readme).toContain("plaintext");
+  });
+
   test("callExpression/export-callability mismatch throws instead of silently mis-instantiating", async () => {
     const dest = join(tmp, "my-shop");
     await expect(
@@ -243,6 +265,22 @@ describe("scaffoldApp", () => {
     );
   });
 
+  // kumiko-framework#2330: the --yes recommended set mounts PII-annotated
+  // entities (user, tenant-invitation, fileRef via user-data-rights), so
+  // runProdApp's PII boot gate throws BOOT ABORTED unless kms/allowPlaintextPii
+  // is wired. resolveKmsWiring supplies a real KMS when the env trio is set,
+  // otherwise an explicit, logged plaintext fallback — never a silent one.
+  test("bin/main.ts wires resolveKmsWiring into runProdApp so the PII boot gate doesn't abort", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
+    expect(main).toContain('from "@cosmicdrift/kumiko-framework/crypto"');
+    expect(main).toContain("resolveKmsWiring(process.env");
+    expect(main).toContain('if ("allowPlaintextPii" in kmsWiring)');
+    expect(main).toContain("...kmsWiring,");
+  });
+
   test("src/run-config.ts mounts secrets + sessions + tasks + HAS_AUTH", async () => {
     const dest = join(tmp, "my-shop");
     await scaffoldApp({ name: "my-shop", destination: dest });

package/src/compose-stacks.ts

@@ -1,3 +1,9 @@
+// @runtime runtime
+// Despite living in this "dev"-marked package, every preset here composes
+// @cosmicdrift/kumiko-bundled-features factories, and run-config.ts in every
+// app repo feeds it into the runProdApp boot path, not just runDevApp
+// (kumiko-framework#2337).
+//
 // Composable SaaS stack presets — explicit opt-in blocks for run-config.ts.
 // Presets export feature instances only; no implicit PAT scopes, anonymousAccess,
 // or tier maps (those stay in bin/server.ts / app run-config).

package/src/scaffold-app.ts

@@ -437,6 +437,10 @@ function renderMain(appName: string): string {
     moduleSpecifier: "@cosmicdrift/kumiko-framework/env",
     namedImports: ["composeEnvSchema"],
   });
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-framework/crypto",
+    namedImports: ["resolveKmsWiring"],
+  });
   sf.addImportDeclaration({
     moduleSpecifier: "../src/run-config",
     namedImports: ["APP_FEATURES", "HAS_AUTH"],
@@ -477,6 +481,37 @@ function renderMain(appName: string): string {
     ],
   });
 
+  // Subject-key KMS for the pii-annotated entities the --yes recommended set
+  // mounts (user, tenant-invitation, fileRef). Without the PLATFORM_KEK /
+  // SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY trio this falls back
+  // to plaintext PII with a loud boot warning — fine to get running locally,
+  // never for a real deploy (kumiko-framework#2330).
+  sf.addVariableStatement({
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [
+      {
+        name: "kmsWiring",
+        initializer: (writer) => {
+          writer.write("resolveKmsWiring(process.env, ").inlineBlock(() => {
+            writer.writeLine(`logPrefix: "[${appName}]",`);
+            writer.writeLine(
+              `plaintextReason: "no PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY set — see .env.example",`,
+            );
+          });
+          writer.write(")");
+        },
+      },
+    ],
+  });
+
+  sf.addStatements((writer) => {
+    writer.write('if ("allowPlaintextPii" in kmsWiring) ').inlineBlock(() => {
+      writer.writeLine(
+        `console.warn(\`[${appName}] PII IS STORED IN PLAINTEXT — \${kmsWiring.allowPlaintextPii}\`);`,
+      );
+    });
+  });
+
   sf.addStatements((writer) => {
     writer
       .write("await runProdApp(")
@@ -484,6 +519,7 @@ function renderMain(appName: string): string {
         writer.writeLine("features: APP_FEATURES,");
         writer.writeLine("envSchema,");
         writer.writeLine('staticDir: "./dist",');
+        writer.writeLine("...kmsWiring,");
         writer.write("auth: ").inlineBlock(() => {
           writer.write("admin: ").inlineBlock(() => {
             writer.writeLine(`email: "admin@${appName}.local",`);
@@ -661,6 +697,14 @@ JWT_SECRET=change-me-min-32-chars-change-me-min-32
 # Generate with: openssl rand -base64 32
 KUMIKO_SECRETS_MASTER_KEY_V1=
 
+# Subject-keys KMS for PII fields (user, tenant-invitation, fileRef). Unset by
+# default — bin/main.ts then boots with plaintext PII and a loud warning, fine
+# to get running locally. Set all three before a real deploy (crypto-shredding
+# needs it for GDPR erasure): PLATFORM_KEK generate with: openssl rand -base64 32
+PLATFORM_KEK=
+SUBJECT_KEYS_DATABASE_URL=
+KUMIKO_BLIND_INDEX_KEY=
+
 # Dev-only: persistent DB for \`bun dev\`. Without this var every reboot starts
 # a fresh kumiko_test_<random> DB → admin login + data gone on every edit.
 # With it the DB persists across reboots (schema pushes are idempotent).
@@ -744,6 +788,11 @@ bun run boot
 Runs \`KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts\` — validates feature composition
 + env schema, exits 0 without touching DB/Redis. Useful in CI.
 
+Without \`PLATFORM_KEK\` / \`SUBJECT_KEYS_DATABASE_URL\` / \`KUMIKO_BLIND_INDEX_KEY\`
+set (see \`.env.example\`), both \`bun run boot\` and \`bun run start\` boot with
+PII fields (user, tenant-invitation, fileRef) stored in plaintext and a loud
+warning — set all three before a real deploy.
+
 ## Production build + schema
 
 \`\`\`sh