@cosmicdrift/kumiko-framework 0.165.0 → 0.165.1

package/src/engine/types/define-handler.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/define-handler";
+export type * from "@cosmicdrift/kumiko-types/define-handler";

package/src/engine/types/entity-handlers.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/entity-handlers";
+export type * from "@cosmicdrift/kumiko-types/entity-handlers";

package/src/engine/types/event-type-map.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/event-type-map";
+export type * from "@cosmicdrift/kumiko-types/event-type-map";

package/src/engine/types/feature.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/feature";
+export type * from "@cosmicdrift/kumiko-types/feature";

package/src/engine/types/fields.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/fields";
+export type * from "@cosmicdrift/kumiko-types/fields";

package/src/engine/types/handlers.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/handlers";
+export type * from "@cosmicdrift/kumiko-types/handlers";

package/src/engine/types/hooks.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/hooks";
+export type * from "@cosmicdrift/kumiko-types/hooks";

package/src/engine/types/http-route.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/http-route";
+export type * from "@cosmicdrift/kumiko-types/http-route";

package/src/engine/types/nav.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/nav";
+export type * from "@cosmicdrift/kumiko-types/nav";

package/src/engine/types/ownership.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/ownership";
+export type * from "@cosmicdrift/kumiko-types/ownership";

package/src/engine/types/projection.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/projection";
+export type * from "@cosmicdrift/kumiko-types/projection";

package/src/engine/types/relations.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/relations";
+export type * from "@cosmicdrift/kumiko-types/relations";

package/src/engine/types/screen.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/screen";
+export type * from "@cosmicdrift/kumiko-types/screen";

package/src/engine/types/step.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/step";
+export type * from "@cosmicdrift/kumiko-types/step";

package/src/engine/types/target-ref.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/target-ref";
+export type * from "@cosmicdrift/kumiko-types/target-ref";

package/src/engine/types/tree-node.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/tree-node";
+export type * from "@cosmicdrift/kumiko-types/tree-node";

package/src/engine/types/workspace.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/workspace";
+export type * from "@cosmicdrift/kumiko-types/workspace";

package/src/engine/validate-projection-allowlist.ts

@@ -23,6 +23,10 @@
 // caught by this validator. A future lint-rule will enforce the contract
 // statically; today it lives in this comment + the StepBuilder doc.
 
+import {
+  KUMIKO_META_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import { getStep } from "./define-step";
 import { buildPipelineSteps } from "./pipeline";
 import type { FeatureDefinition, SessionUser, TenantId, WriteEvent } from "./types";
@@ -55,13 +59,9 @@ function* walkAllSteps(steps: readonly StepInstance[]): Generator<StepInstance,
   }
 }
 
-// @cast-boundary drizzle-bridge — reads table name from a Symbol without
-// importing drizzle-orm (bun-db pattern, see bun-db/query.ts).
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
 // table()/buildEntityTable spread column handles as enumerable props, so an
 // entity field named `tableName`/`source` would shadow the matching meta key —
-// the canonical meta under this symbol is the only collision-safe source.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
+// the canonical meta under KUMIKO_META_SYMBOL is the only collision-safe source.
 
 function resolveTableNameFromStep(table: unknown): string {
   if (typeof table === "object" && table !== null) {

package/src/errors/classes.ts

@@ -138,6 +138,27 @@ export class VersionConflictError extends ConflictError {
   }
 }
 
+// The caller retried a write with an idempotencyKey it had already used —
+// the event-store's partial unique index on metadata.idempotencyKey caught
+// the duplicate. Distinct from unique_violation/version_conflict: this is
+// not an error the caller should retry, it means the earlier attempt
+// already succeeded and this one is a no-op replay.
+export class IdempotentReplayError extends ConflictError {
+  override readonly code: string = "idempotent_replay";
+
+  constructor(
+    details: { readonly idempotencyKey: string },
+    opts?: Pick<ErrorOpts, "i18nKey" | "cause">,
+  ) {
+    super({
+      message: `event with idempotencyKey "${details.idempotencyKey}" was already appended`,
+      i18nKey: opts?.i18nKey ?? "errors.idempotentReplay",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
 // Entity-level unique-index violation. Distinct from VersionConflictError:
 // version_conflict means "two writers raced on the events_aggregate_version
 // _uq index" (optimistic-concurrency); unique_violation means "you tried to

package/src/errors/index.ts

@@ -13,6 +13,7 @@ export {
   AccessDeniedError,
   ConflictError,
   FeatureDisabledError,
+  IdempotentReplayError,
   InternalError,
   NotFoundError,
   RateLimitError,

package/src/errors/write-error-info.ts

@@ -7,8 +7,12 @@ import { KumikoError } from "./kumiko-error";
 import { FrameworkReasons } from "./reasons";
 import { buildInvalidTransitionDetails } from "./transition-details";
 
-// Legacy types — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/write-error-info-types";
+// Re-exported so a caller importing this module directly (instead of via
+// the `./errors` barrel, which already re-exports these by name) still
+// gets the types — explicit, not a wildcard: this module isn't a public
+// subpath export (see package.json `exports`), so the only readers are
+// framework-internal.
+export type { WriteErrorInfo, WriteFailure };
 
 // Convenience for call sites that return a failed WriteResult. Keeps the
 // pattern `return writeFailure(new NotFoundError(...))` compact so handlers

package/src/event-store/__tests__/admin-api.integration.test.ts

@@ -15,7 +15,7 @@ import { asRawClient, selectMany } from "../../db/query";
 import { createTestDb, type TestDb } from "../../stack";
 import { generateId as uuid } from "../../utils";
 import { appendRaw, appendRawBatch, type RawEventToAppend } from "../admin-api";
-import { VersionConflictError } from "../errors";
+import { IdempotentAppendConflictError, VersionConflictError } from "../errors";
 import { append, loadAggregate } from "../event-store";
 import { createEventsTable, eventsTable } from "../events-schema";
 
@@ -187,6 +187,32 @@ describe("appendRaw — single event", () => {
     ).rejects.toBeInstanceOf(VersionConflictError);
   });
 
+  test("appendRaw distinguishes an idempotency-key replay from a version conflict (#1499)", async () => {
+    const idempotencyKey = uuid();
+    await appendRaw(
+      testDb.db,
+      makeEvent({
+        aggregateId: uuid(),
+        expectedVersion: 0,
+        metadata: { userId: userMigration, idempotencyKey },
+      }),
+    );
+
+    // A second, different aggregate reusing the same idempotencyKey hits
+    // the tenant-scoped partial unique index — distinct from a version
+    // race on the same aggregate, and must not be reported as one.
+    await expect(
+      appendRaw(
+        testDb.db,
+        makeEvent({
+          aggregateId: uuid(),
+          expectedVersion: 0,
+          metadata: { userId: userMigration, idempotencyKey },
+        }),
+      ),
+    ).rejects.toBeInstanceOf(IdempotentAppendConflictError);
+  });
+
   test("version_conflict on missing predecessor (appendRaw v=5 without v=1..4)", async () => {
     const aggregateId = uuid();
     // Try to write version=5 (expectedVersion=4) against an empty stream.

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

@@ -60,6 +60,38 @@ describe("event-store: append + load", () => {
     expect(events[0]?.metadata.userId).toBe(userA);
   });
 
+  test("kumiko-framework#1490: subsequent append doesn't rely on globalThis.Temporal", async () => {
+    const aggregateId = uuid();
+    const first = await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Buy milk" },
+      metadata: { userId: userA },
+    });
+
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      const second = await append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: first.version,
+        type: "task.updated",
+        payload: { title: "Buy oat milk" },
+        metadata: { userId: userA },
+      });
+      expect(second.version).toBe(2);
+      expect(second.createdAt).toBeDefined();
+    } finally {
+      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+    }
+  });
+
   test("subsequent appends increment version and are ordered", async () => {
     const aggregateId = uuid();
     const base = {

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -12,8 +12,6 @@ const ALLOWED_FILES = new Set([
   "packages/framework/src/event-store/index.ts",
   "packages/bundled-features/src/tenant/seeding.ts",
   "packages/bundled-features/src/tier-engine/feature.ts",
-  "packages/bundled-features/src/auth-email-password/__tests__/email-verification.integration.test.ts",
-  "packages/bundled-features/src/auth-email-password/__tests__/password-reset.integration.test.ts",
   "packages/framework/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts",
 ]);
 
@@ -21,11 +19,31 @@ const REPO_ROOT = `${import.meta.dir}/../../../../..`;
 
 describe("unscoped stream primitives — caller allowlist", () => {
   test("only seed/system-internal paths reference the existence-oracle primitives", async () => {
-    const glob = new Glob("packages/{framework,bundled-features}/src/**/*.ts");
+    // Widened from {framework,bundled-features} — the primitives are exported
+    // from the public @cosmicdrift/kumiko-framework/event-store barrel, so any
+    // package (server-runtime, dispatcher-live, headless, renderer-web, cli, ...)
+    // can import and call them; the allowlist must cover all of them, not just
+    // the two packages that happened to have callers when this guard was written.
+    const glob = new Glob("packages/*/src/**/*.ts");
     const matches = new Set<string>();
     for await (const relPath of glob.scan({ cwd: REPO_ROOT })) {
       const content = await Bun.file(`${REPO_ROOT}/${relPath}`).text();
-      if (RESTRICTED_SYMBOLS.some((symbol) => content.includes(symbol))) {
+      // Strip full-line `//` comments before scanning — a bare
+      // `content.includes(symbol)` also matches a symbol only mentioned in
+      // prose (e.g. explaining why a helper isn't needed), which would force
+      // an unrelated file into the allowlist for a reference that isn't an
+      // actual import or call.
+      const code = content
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("//"))
+        .join("\n");
+      const referencesSymbol = (symbol: string): boolean =>
+        new RegExp(`\\b${symbol}\\s*\\(`).test(code) ||
+        // Covers both `import { symbol } from "..."` and a re-export barrel
+        // (`export { symbol } from "./event-store"`) — a new barrel that
+        // surfaces the oracle primitive must widen the allowlist too.
+        new RegExp(`\\b(import|export)\\b[^;]*\\b${symbol}\\b`).test(code);
+      if (RESTRICTED_SYMBOLS.some(referencesSymbol)) {
         matches.add(relPath);
       }
     }

package/src/event-store/admin-api.ts

@@ -8,7 +8,7 @@
 // selbst, das Guard-Script selbst.
 
 import type { DbRunner } from "../db";
-import { isUniqueViolation } from "../db/pg-error";
+import { constraintOf, isUniqueViolation } from "../db/pg-error";
 import {
   eventPredecessorExists,
   findExistingEventVersion,
@@ -17,7 +17,7 @@ import {
   insertRawSubsequentEvent,
 } from "../db/queries/event-store-admin";
 import type { TenantId } from "../engine/types";
-import { VersionConflictError } from "./errors";
+import { IdempotentAppendConflictError, VersionConflictError } from "./errors";
 import type { EventMetadata } from "./event-store";
 
 export type RawEventToAppend = {
@@ -39,6 +39,13 @@ export type RawEventToAppend = {
   readonly createdBy: string;
 };
 
+function mapEventUniqueViolation(e: unknown, event: RawEventToAppend): Error {
+  if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {
+    return new IdempotentAppendConflictError(event.tenantId, event.metadata.idempotencyKey);
+  }
+  return new VersionConflictError(event.aggregateId, event.expectedVersion);
+}
+
 // Mirrors append()'s two-path structure: typed builder equivalent for v=0,
 // INSERT … SELECT … WHERE EXISTS gate for v>0. Caller-supplied createdAt +
 // createdBy skip the usual userResolver/now() paths.
@@ -54,7 +61,7 @@ export async function appendRaw(runner: DbRunner, event: RawEventToAppend): Prom
     }
   } catch (e) {
     if (isUniqueViolation(e)) {
-      throw new VersionConflictError(event.aggregateId, event.expectedVersion);
+      throw mapEventUniqueViolation(e, event);
     }
     throw e;
   }
@@ -143,7 +150,7 @@ export async function appendRawBatch(
     if (isUniqueViolation(e)) {
       // Pre-flight ran but lost a race against a concurrent writer. Rare for
       // migration (single-runner) but possible; we can't name the exact row.
-      throw new VersionConflictError(firstEvent.aggregateId, firstEvent.expectedVersion);
+      throw mapEventUniqueViolation(e, firstEvent);
     }
     throw e;
   }

package/src/event-store/event-store.ts

@@ -1,4 +1,11 @@
 import type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
+// Value-only import, aliased to avoid shadowing the ambient global
+// `Temporal` TYPE this file's other Temporal.Instant annotations resolve
+// against (StoredEvent.createdAt et al. — importing the bare name here
+// conflicts with that ambient type, see #1438). Bun doesn't expose Temporal
+// as a runtime value on globalThis, so the un-aliased call below crashed
+// with "Temporal is not defined" outside boot paths that install it (#1480).
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
 import { constraintOf, isUniqueViolation } from "../db/pg-error";
@@ -151,12 +158,20 @@ async function insertSubsequentEvent(
     expectedVersion: event.expectedVersion,
   });
   if (!row) throw new VersionConflictError(event.aggregateId, event.expectedVersion);
+  const createdAt =
+    row.created_at instanceof Date
+      ? TemporalPolyfill.Instant.fromEpochMilliseconds(row.created_at.getTime())
+      : TemporalPolyfill.Instant.from(row.created_at);
   return {
     id: typeof row.id === "bigint" ? row.id : BigInt(row.id),
-    createdAt:
-      row.created_at instanceof Date
-        ? Temporal.Instant.fromEpochMilliseconds(row.created_at.getTime())
-        : Temporal.Instant.from(row.created_at),
+    // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+    // at runtime, two separate .d.ts sources (temporal-polyfill's bundled
+    // types vs the ambient temporal-spec global) disagree on a couple of
+    // method-overload signatures (until/equals argument types), so TS treats
+    // them as nominally distinct. Safe: this value is only ever consumed as
+    // a Temporal.Instant (comparisons, .toString(), arithmetic), never
+    // narrowed on the specific overload shape that differs.
+    createdAt: createdAt as unknown as Temporal.Instant,
   };
 }
 

package/src/event-store/types.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/event-store-types";
+export type * from "@cosmicdrift/kumiko-types/event-store-types";

package/src/files/__tests__/build-storage-key.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { buildStorageKey } from "../types";
+
+describe("buildStorageKey", () => {
+  test("uses the lowercased extension for a normal filename", () => {
+    const key = buildStorageKey("T1" as never, "invoice", 1, "attachment", "logo.PNG", "u1");
+    expect(key).toBe("T1/invoice/1/attachment/u1.png");
+  });
+
+  test("uses the sole segment as extension when there is no dot", () => {
+    const key = buildStorageKey("T1" as never, "invoice", 1, "attachment", "noext", "u1");
+    expect(key).toBe("T1/invoice/1/attachment/u1.noext");
+  });
+
+  test("rejects a path-traversal filename and falls back to bin instead of leaking the payload", () => {
+    const key = buildStorageKey(
+      "T1" as never,
+      "unattached",
+      "file",
+      "u",
+      "a.b/../../../../evil",
+      "u1",
+    );
+    expect(key).toBe("T1/unattached/file/u/u1.bin");
+    expect(key).not.toContain("..");
+    expect(key.split("/")).toHaveLength(5);
+  });
+});

package/src/files/__tests__/local-provider.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createLocalProvider } from "../local-provider";
+
+describe("createLocalProvider path-traversal guard", () => {
+  const basePath = join(tmpdir(), `kumiko-local-provider-test-${Date.now()}`);
+  const provider = createLocalProvider(basePath);
+
+  afterEach(async () => {
+    await rm(basePath, { recursive: true, force: true });
+  });
+
+  test("rejects a key with a `..` segment even when it resolves inside basePath", async () => {
+    await expect(
+      provider.write("T1/e/1/f/x.png/../../../../T2/y.png", new Uint8Array([1])),
+    ).rejects.toThrow(/path-traversal/);
+  });
+
+  test("rejects a `..` segment on read/delete too, and exists() reports false instead of throwing", async () => {
+    await expect(provider.read("a/../../etc/passwd")).rejects.toThrow(/path-traversal/);
+    await expect(provider.delete("a/../../etc/passwd")).rejects.toThrow(/path-traversal/);
+    expect(await provider.exists("a/../../etc/passwd")).toBe(false);
+  });
+
+  test("still allows a normal, contained key", async () => {
+    await provider.write("T1/entity/1/field/file.png", new Uint8Array([1, 2, 3]));
+    expect(await provider.exists("T1/entity/1/field/file.png")).toBe(true);
+  });
+});

package/src/files/__tests__/write-stream.test.ts

@@ -153,10 +153,10 @@ describe("FileStorageProvider.writeStream — local-filesystem", () => {
     const escapingKey = "../../etc/passwd";
 
     await expect(provider.write(escapingKey, new Uint8Array([1]))).rejects.toThrow(
-      /escapes basePath/,
+      /path-traversal/,
     );
-    await expect(provider.read(escapingKey)).rejects.toThrow(/escapes basePath/);
-    await expect(provider.delete(escapingKey)).rejects.toThrow(/escapes basePath/);
+    await expect(provider.read(escapingKey)).rejects.toThrow(/path-traversal/);
+    await expect(provider.delete(escapingKey)).rejects.toThrow(/path-traversal/);
     // exists() treats any stat failure (missing file, escaping key) as "not there".
     expect(await provider.exists(escapingKey)).toBe(false);
   });

package/src/files/index.ts

@@ -34,6 +34,6 @@ export type {
   SignedUrlOptions,
   WriteStreamOptions,
 } from "./types";
-export { buildStorageKey, parseMaxSize, validateFile } from "./types";
+export { assertSafeStorageKey, buildStorageKey, parseMaxSize, validateFile } from "./types";
 export type { ZipEntry } from "./zip-stream";
 export { createZipStream } from "./zip-stream";

package/src/files/local-provider.ts

@@ -2,7 +2,7 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
-import type { FileStorageProvider } from "./types";
+import { assertSafeStorageKey, type FileStorageProvider } from "./types";
 
 // Local-filesystem backend — intended for dev + tests. Production deploys
 // pick an object-store provider (S3/R2/…). mimeType is ignored here; the
@@ -16,6 +16,11 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
   // segment that slipped past an upstream check), regardless of the key's
   // source.
   function resolveContainedPath(key: string): string {
+    assertSafeStorageKey(key);
+    // assertSafeStorageKey rejects every literal "."/".." segment, which
+    // covers all string-based traversal a join+resolve can produce; this
+    // startsWith check is a second, independent line of defense in case a
+    // future caller feeds resolveContainedPath something pre-resolved.
     const filePath = resolve(join(basePath, key));
     if (filePath !== resolvedBase && !filePath.startsWith(resolvedBase + sep)) {
       throw new Error(`storage key escapes basePath: "${key}"`);

package/src/files/types.ts

@@ -84,6 +84,12 @@ export function validateFile(
   return null;
 }
 
+export function assertSafeStorageKey(key: string): void {
+  if (key.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new Error(`storage key contains a path-traversal segment: "${key}"`);
+  }
+}
+
 export function buildStorageKey(
   tenantId: TenantId,
   entityType: string,
@@ -92,6 +98,7 @@ export function buildStorageKey(
   fileName: string,
   uniqueId: string,
 ): string {
-  const ext = fileName.split(".").pop() ?? "bin";
+  const rawExt = fileName.split(".").pop() ?? "";
+  const ext = /^[A-Za-z0-9]+$/.test(rawExt) ? rawExt.toLowerCase() : "bin";
   return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
 }