@cosmicdrift/kumiko-framework 0.255.0 → 0.255.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.255.0",
+  "version": "0.255.2",
   "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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.255.0",
+    "@cosmicdrift/kumiko-types": "0.255.2",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.255.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.255.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/crypto/__tests__/subject-id-schema.test.ts

@@ -0,0 +1,60 @@
+// subjectIdSchema is `satisfies z.ZodType<SubjectId>` at the definition site
+// (kms-adapter.ts) — a future 4th SubjectId variant or a renamed field fails
+// to compile there. This file pins the runtime side of that binding: exactly
+// the three SubjectId shapes parse, everything else is refused.
+
+import { describe, expect, test } from "bun:test";
+import { subjectIdSchema } from "../kms-adapter";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+
+describe("subjectIdSchema", () => {
+  test("accepts a user subject", () => {
+    expect(subjectIdSchema.safeParse({ kind: "user", userId: UUID_A }).success).toBe(true);
+  });
+
+  test("accepts a tenant subject", () => {
+    expect(subjectIdSchema.safeParse({ kind: "tenant", tenantId: UUID_A }).success).toBe(true);
+  });
+
+  test("accepts a record subject", () => {
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "mail-account", id: UUID_A }).success,
+    ).toBe(true);
+  });
+
+  test("mints tenantId as a branded TenantId, not a plain string type", () => {
+    const result = subjectIdSchema.parse({ kind: "tenant", tenantId: UUID_A });
+    expect(result).toEqual({ kind: "tenant", tenantId: UUID_A });
+  });
+
+  test("rejects a non-UUID userId", () => {
+    expect(subjectIdSchema.safeParse({ kind: "user", userId: "not-a-uuid" }).success).toBe(false);
+  });
+
+  test("rejects a non-UUID tenantId", () => {
+    expect(subjectIdSchema.safeParse({ kind: "tenant", tenantId: "not-a-uuid" }).success).toBe(
+      false,
+    );
+  });
+
+  test("rejects a non-UUID record id", () => {
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "mail-account", id: "not-a-uuid" })
+        .success,
+    ).toBe(false);
+  });
+
+  test("rejects a record entity that violates RECORD_ENTITY_PATTERN", () => {
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "_internal", id: UUID_A }).success,
+    ).toBe(false);
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "v2.digest", id: UUID_A }).success,
+    ).toBe(false);
+  });
+
+  test("rejects an unknown subject kind", () => {
+    expect(subjectIdSchema.safeParse({ kind: "bogus", id: UUID_A }).success).toBe(false);
+  });
+});

package/src/crypto/index.ts

@@ -30,6 +30,7 @@ export {
   type SubjectId,
   type SubjectKey,
   subjectIdFromKey,
+  subjectIdSchema,
   subjectIdToKey,
   subjectKeyForRecord,
   subjectKeyForTenant,

package/src/crypto/kms-adapter.ts

@@ -1,10 +1,34 @@
-import { type SubjectId, subjectIdToKey } from "@cosmicdrift/kumiko-types/kms-adapter-types";
+import {
+  RECORD_ENTITY_PATTERN,
+  type SubjectId,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-types/kms-adapter-types";
+import { z } from "zod";
+import type { TenantId } from "../engine/types/identifiers";
 
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
 
 // The KMS error classes live here and not in kumiko-types (#1629): callers
 // branch on them with `instanceof`, which needs a single copy of the class.
 
+// `satisfies z.ZodType<SubjectId>` binds this to the TS type at compile time
+// (fw#2801) — mint (subjectKeyForRecord) and shred (forget-subject) can no
+// longer drift apart on which subjects are valid, the way #2809 happened.
+export const subjectIdSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("user"), userId: z.uuid() }),
+  z.object({
+    kind: z.literal("tenant"),
+    // z.uuid() only proves string shape; TenantId is a nominal brand on top
+    // of that, minted here right after validation (@cast-boundary).
+    tenantId: z.uuid().transform((value) => value as TenantId),
+  }),
+  z.object({
+    kind: z.literal("record"),
+    entity: z.string().regex(RECORD_ENTITY_PATTERN),
+    id: z.uuid(),
+  }),
+]) satisfies z.ZodType<SubjectId>;
+
 export class KeyErasedError extends Error {
   constructor(public readonly subject: SubjectId) {
     super(`Subject key erased: ${subjectIdToKey(subject)}`);

package/src/crypto/subject-resolver.ts

@@ -171,8 +171,8 @@ export function resolveEventSubject(
       );
     }
     // aggregate_type is a free-form text column (events-schema.ts) — reject
-    // here rather than mint a record key that subjectIdSchema (forget-
-    // subject.write.ts) would later refuse to shred.
+    // here rather than mint a record key that subjectIdSchema (kms-adapter.ts)
+    // would later refuse to shred.
     if (!RECORD_ENTITY_PATTERN.test(envelope.aggregateType)) {
       throw new SubjectResolutionError(
         fieldName,

package/src/engine/boot-validator/__tests__/record-owned.test.ts

@@ -1,9 +1,8 @@
 // fw#2809 — a recordOwned field is encrypted under `record:<entity>:<id>`
-// (kms-adapter-types.ts) and forgetSubject's subjectIdSchema validates that
-// id as a UUID (crypto-shredding/handlers/forget-subject.write.ts). An
-// idType: "serial" entity would encrypt such a field but could never satisfy
-// a forget-subject request for it — the boot guard catches that combination
-// before it ships.
+// (kms-adapter-types.ts) and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts)
+// validates that id as a UUID. An idType: "serial" entity would encrypt such
+// a field but could never satisfy a forget-subject request for it — the boot
+// guard catches that combination before it ships.
 
 import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../define-feature";

package/src/engine/boot-validator/record-owned.ts

@@ -2,10 +2,9 @@ import type { FeatureDefinition } from "../types";
 import type { ResolvedPiiFlags } from "../types/fields";
 
 // A recordOwned field is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
-// and forgetSubject's subjectIdSchema requires that id to be a UUID
-// (crypto-shredding/handlers/forget-subject.write.ts) — an entity with
-// idType: "serial" would encrypt the field but could never satisfy a
-// forget-subject request for it.
+// and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts) requires that id
+// to be a UUID — an entity with idType: "serial" would encrypt the field but
+// could never satisfy a forget-subject request for it.
 export function validateRecordOwnedSubjects(feature: FeatureDefinition): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     if (entity.idType !== "serial") continue;

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -64,7 +64,7 @@ const mailerFeature = defineFeature("mailer", (r) => {
   ).name;
 });
 
-// fw#2801 step 2: custom events declaring a tenant/self subject — no entity,
+// fw#2801: custom events declaring a tenant/self subject — no entity,
 // pure catalog events — proving the catalog branch resolves through the
 // same resolveEventSubject the live append path uses.
 let TENANT_NOTE_EVENT_TYPE: string;