@cosmicdrift/kumiko-framework 0.67.1 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.67.1",
+  "version": "0.70.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.67.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.70.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/define-handler.ts

@@ -1,4 +1,5 @@
 import type { ZodType, z } from "zod";
+import type { ContainsSecret } from "../secrets/types";
 import { runPipeline } from "./run-pipeline";
 import type {
   AccessRule,
@@ -83,6 +84,17 @@ export function defineWriteHandler<
   TMap extends object = KumikoEventTypeMap,
 >(
   def: WriteHandlerInput<TName, TSchema, TData, TMap>,
+  // R6: a phantom rest-param. When the inferred response `TData` carries a
+  // Secret<> anywhere, ContainsSecret<TData> is `true` and this resolves to a
+  // 1-tuple the caller can't supply → compile error at the leak site. Clean
+  // responses get `[]`, so existing call-sites are unaffected. Checking it in a
+  // parameter post-inference (not as a `TData extends …` constraint, which TS
+  // rejects as circular, TS2313) is what makes inference survive.
+  ..._noSecretInResponse: ContainsSecret<TData> extends true
+    ? [
+        secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field.",
+      ]
+    : []
 ): WriteHandlerDefinition<TName, TSchema, TData, TMap> {
   // Runtime-guard against accidentally setting BOTH handler+perform.
   // The discriminated-union type-error
@@ -160,6 +172,13 @@ export function defineQueryHandler<
   TMap extends object = KumikoEventTypeMap,
 >(
   def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>,
+  // R6: phantom rest-param — see defineWriteHandler. Forbids a Secret<> in the
+  // inferred query response `TResult` at compile time; `[]` for clean responses.
+  ..._noSecretInResponse: ContainsSecret<TResult> extends true
+    ? [
+        secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field.",
+      ]
+    : []
 ): QueryHandlerDefinition<TName, TSchema, TResult, TMap> {
   return def;
 }

package/src/schema-cli.ts

@@ -296,7 +296,7 @@ export async function runSchemaCli(
         return 0;
       } catch (e) {
         out.err("");
-        out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+        out.err(`  ✗ ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
         out.err("");
         return 1;
       } finally {

package/src/secrets/__tests__/contains-secret.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { TenantId } from "../../engine";
+import { defineQueryHandler } from "../../engine/define-handler";
+import { type ContainsSecret, createSecret, type Secret } from "../index";
+
+// R6 is a COMPILE-TIME guard. The type-level assertions below are the real
+// coverage — they are checked by tsc (the bun runtime strips types without
+// checking). The runtime test only proves the guarded registration functions
+// still build a clean handler.
+
+type Expect<T extends true> = T;
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+// One exported tuple so each case is checked by tsc without tripping
+// noUnusedLocals on a named alias. Any wrong predicate fails to compile here.
+export type _R6TypeAssertions = [
+  // Clean responses → false, incl. branded primitives (TenantId, via Primitive)
+  // and opaque leaves (Temporal.Instant, Date, via SafeLeaf). These double as
+  // the false-positive guard: a mangled leaf would flip the case to `true`.
+  Expect<Equal<ContainsSecret<{ ok: true; id: string }>, false>>,
+  Expect<Equal<ContainsSecret<{ id: TenantId; when: Temporal.Instant; at: Date }>, false>>,
+  Expect<Equal<ContainsSecret<{ items: { label: string }[]; total: number }>, false>>,
+  Expect<Equal<ContainsSecret<{ apiKey: string }>, false>>, // revealed → plain string
+  // A Secret<> anywhere → true.
+  Expect<Equal<ContainsSecret<{ apiKey: Secret<string> }>, true>>,
+  Expect<Equal<ContainsSecret<{ creds: { token: Secret<string> } }>, true>>,
+  Expect<Equal<ContainsSecret<{ keys: Secret<string>[] }>, true>>,
+  Expect<Equal<ContainsSecret<{ when: Temporal.Instant; secret: Secret<string> }>, true>>,
+  // Uninspectable types are biased to `false` (allowed) — the runtime guard is
+  // the backstop. This is what keeps generic-over-response handlers compiling.
+  Expect<Equal<ContainsSecret<unknown>, false>>,
+  Expect<Equal<ContainsSecret<never>, false>>,
+];
+
+const schema = z.object({ q: z.string() });
+declare const aSecret: Secret<string>;
+
+// End-to-end: a Secret<> in the query response is a compile error at the call.
+// @ts-expect-error — R6: Secret<> must not appear in a handler response
+defineQueryHandler({
+  name: "t:query:leak",
+  schema,
+  handler: async () => ({ apiKey: aSecret }),
+});
+
+// Regression: a handler generic over its response (the createTokenRequestHandler
+// pattern) must NOT false-flag — the guard allows what it cannot prove. This
+// call compiling at all is the assertion.
+function genericResponseHandler<K extends string>(kind: K) {
+  return defineQueryHandler({
+    name: "t:query:generic",
+    schema,
+    handler: async () => ({ kind, ok: true }) as { kind: K; ok: boolean },
+  });
+}
+void genericResponseHandler;
+
+describe("R6 ContainsSecret", () => {
+  test("a clean query handler still builds — the guard param is invisible", () => {
+    const def = defineQueryHandler({
+      name: "t:query:clean",
+      schema,
+      handler: async () => ({ ok: true, value: createSecret("x").reveal() }),
+    });
+    expect(def.name).toBe("t:query:clean");
+  });
+});

package/src/secrets/index.ts

@@ -8,6 +8,7 @@ export { decryptValue, encryptValue } from "./envelope";
 export { assertNoSecretLeak } from "./leak-guard";
 export { rewrapDek } from "./rotation";
 export {
+  type ContainsSecret,
   createSecret,
   type Envelope,
   isSecret,

package/src/secrets/types.ts

@@ -34,6 +34,58 @@ export function isSecret(v: unknown): v is Secret<unknown> {
   return typeof v === "object" && v !== null && SecretBrand in v;
 }
 
+// --- Compile-time response guard (R6) --------------------------------------
+//
+// ContainsSecret<T> is `true` only when a Secret<> is DEFINITELY present
+// somewhere in T. The handler-registration guard (defineWriteHandler/
+// defineQueryHandler) turns a `true` into a compile error — the static twin of
+// assertNoSecretLeak's runtime walk.
+//
+// Biased to `false`: anything it cannot inspect — a bare generic type param (a
+// handler generic over its response), `unknown`/`any`, `never` — resolves to
+// `false` = allowed, with the runtime guard as the backstop. The alternative
+// (default-to-leak) false-flags every legitimate generic-over-response handler.
+//
+// Branch order is load-bearing: never/unknown/any first (uninspectable), then
+// Secret, then primitives (covers branded primitives like TenantId without
+// enumerating them), then the SafeLeaf allowlist (opaque class instances that
+// blind `{ [K in keyof T] }` recursion would mangle — the type-level mirror of
+// leak-guard.ts skipping non-plain objects), then arrays, then a "does any
+// field contain a secret" fold over plain objects.
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+// Opaque built-in leaves a response legitimately carries; never recurse into
+// them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
+type SafeLeaf =
+  | Date
+  | RegExp
+  | Temporal.Instant
+  | Temporal.ZonedDateTime
+  | Temporal.PlainDate
+  | Temporal.PlainDateTime
+  | Temporal.PlainTime
+  | Temporal.PlainYearMonth
+  | Temporal.PlainMonthDay
+  | Temporal.Duration;
+
+export type ContainsSecret<T> = [T] extends [never]
+  ? false
+  : unknown extends T
+    ? false
+    : T extends Secret<unknown>
+      ? true
+      : T extends Primitive
+        ? false
+        : T extends SafeLeaf
+          ? false
+          : T extends readonly (infer U)[]
+            ? ContainsSecret<U>
+            : T extends object
+              ? true extends { [K in keyof T]-?: ContainsSecret<T[K]> }[keyof T]
+                ? true
+                : false
+              : false;
+
 // Per-read audit context. Populated by requireSecretsContext() wrapper so
 // handlers don't need to pass userId/handlerName manually on every call.
 // Undefined for framework-internal reads (rotation job, tests) — the audit