@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/derivatives/derivatives-context.ts

@@ -1,314 +0,0 @@
-import type {
-  DerivativeRendererPlugin,
-  DerivativesContext,
-  OverlayLayer,
-  ResolvedOverlayLayer,
-  VariantSpec,
-} from "@cosmicdrift/kumiko-types/derivatives-types";
-import { type AnyDb, fetchOne } from "../bun-db/query";
-import {
-  EXT_DERIVATIVE_OVERLAY_RESOLVER,
-  EXT_DERIVATIVE_RENDERER,
-} from "../engine/extension-names";
-import type { Registry, TenantId } from "../engine/types";
-import { InternalError, NotFoundError } from "../errors";
-import type { FileContext } from "../files/file-handle";
-import { fileRefsTable } from "../files/file-ref-table";
-import { assertSafeStorageKey, normalizeMimeType } from "../files/types";
-import { variantSuffix } from "./variant-key";
-
-export type DerivativesContextDeps = {
-  readonly files: FileContext;
-  readonly registry: Registry;
-  readonly db: AnyDb;
-  readonly tenantId: TenantId;
-};
-
-// extension-usage `options` is engine-payload (unknown) — structurally validate
-// instead of casting blind, same pattern as isFileProviderPlugin.
-function isDerivativeRendererPlugin(o: unknown): o is DerivativeRendererPlugin {
-  return typeof o === "object" && o !== null && "render" in o && typeof o.render === "function";
-}
-
-export function resolveRenderer(
-  registry: Registry,
-  mimeType: string,
-): DerivativeRendererPlugin | undefined {
-  const normalized = normalizeMimeType(mimeType);
-  const usages = registry.getExtensionUsages(EXT_DERIVATIVE_RENDERER);
-
-  const exact = usages.find((u) => u.entityName === normalized);
-  if (exact) {
-    if (!isDerivativeRendererPlugin(exact.options))
-      throw new Error(
-        `derivatives.resolveRenderer: "${exact.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`,
-      );
-    return exact.options;
-  }
-
-  const wildcard = usages.find((u) => u.entityName === `${normalized.split("/")[0]}/*`);
-  if (wildcard) {
-    if (!isDerivativeRendererPlugin(wildcard.options))
-      throw new Error(
-        `derivatives.resolveRenderer: "${wildcard.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`,
-      );
-    return wildcard.options;
-  }
-
-  return undefined;
-}
-
-export type OverlayResolverArgs = {
-  readonly entityId: string;
-  readonly tenantId: TenantId;
-  readonly fieldName: string;
-  readonly dataToken: string;
-};
-
-export type OverlayResolverPlugin = {
-  readonly resolve: (args: OverlayResolverArgs) => string | Promise<string>;
-};
-
-// extension-usage `options` is engine-payload (unknown) — structurally validate
-// instead of casting blind, same pattern as isDerivativeRendererPlugin.
-function isOverlayResolverPlugin(o: unknown): o is OverlayResolverPlugin {
-  return typeof o === "object" && o !== null && "resolve" in o && typeof o.resolve === "function";
-}
-
-type FileRefRow = {
-  readonly storageKey: string;
-  readonly mimeType: string;
-  readonly entityType: string | null;
-  readonly entityId: string | null;
-  readonly fieldName: string | null;
-};
-
-function isFileRefRow(row: Record<string, unknown>): row is FileRefRow {
-  return (
-    typeof row["storageKey"] === "string" &&
-    typeof row["mimeType"] === "string" &&
-    (row["entityType"] === null || typeof row["entityType"] === "string") &&
-    (row["entityId"] === null || typeof row["entityId"] === "string") &&
-    (row["fieldName"] === null || typeof row["fieldName"] === "string")
-  );
-}
-
-// A qr overlay needs the FileRef's field identity to pick a resolver and to
-// hand the resolver something to look up — narrows the 3 nullable columns
-// together so the throw below can name whichever one is actually missing.
-type FieldIdentifiedFileRef = FileRefRow & {
-  readonly entityType: string;
-  readonly entityId: string;
-  readonly fieldName: string;
-};
-
-function hasFieldIdentity(row: FileRefRow): row is FieldIdentifiedFileRef {
-  return row.entityType !== null && row.entityId !== null && row.fieldName !== null;
-}
-
-type QrOverlayContext = {
-  readonly row: FieldIdentifiedFileRef;
-  readonly plugin: OverlayResolverPlugin;
-};
-
-// Looks up the entityType's resolver once per variant() call (not once per
-// qr layer) and fails before any layer is touched — a spec with 3 qr layers
-// and no registration throws once, not on the first layer only.
-function resolveQrOverlayContext(row: FileRefRow, registry: Registry): QrOverlayContext {
-  if (!hasFieldIdentity(row)) {
-    throw new InternalError({
-      message:
-        "derivatives.variant: a qr overlay requires the FileRef's entityType/entityId/fieldName, but at least one is missing.",
-      details: { entityType: row.entityType, entityId: row.entityId, fieldName: row.fieldName },
-    });
-  }
-  const usage = registry
-    .getExtensionUsages(EXT_DERIVATIVE_OVERLAY_RESOLVER)
-    .find((u) => u.entityName === row.entityType);
-  if (!usage) {
-    throw new InternalError({
-      message: `derivatives.variant: no ${EXT_DERIVATIVE_OVERLAY_RESOLVER} registered for entityType "${row.entityType}".`,
-      details: { entityType: row.entityType },
-    });
-  }
-  if (!isOverlayResolverPlugin(usage.options)) {
-    throw new Error(
-      `derivatives.variant: "${usage.entityName}" registered ${EXT_DERIVATIVE_OVERLAY_RESOLVER} without a resolve(args) — extension options must be an OverlayResolverPlugin.`,
-    );
-  }
-  return { row, plugin: usage.options };
-}
-
-async function resolveQrLayer(
-  layer: Extract<OverlayLayer, { kind: "qr" }>,
-  context: QrOverlayContext,
-  tenantId: TenantId,
-): Promise<ResolvedOverlayLayer> {
-  const { dataToken, ...placement } = layer;
-  const data = await context.plugin.resolve({
-    entityId: context.row.entityId,
-    tenantId,
-    fieldName: context.row.fieldName,
-    dataToken,
-  });
-  if (!data) {
-    throw new InternalError({
-      message: `derivatives.variant: ${EXT_DERIVATIVE_OVERLAY_RESOLVER} resolved dataToken "${dataToken}" to an empty value for entityType "${context.row.entityType}".`,
-      details: { entityType: context.row.entityType, dataToken },
-    });
-  }
-  return { ...placement, data };
-}
-
-// A non-qr layer is already ResolvedOverlayLayer-shaped (see
-// ResolvedOverlayLayer's `image` member) — this only exists because TS can't
-// derive that from `layer.kind !== "qr"` across a Promise.all/map boundary.
-function resolveOverlayLayer(
-  layer: OverlayLayer,
-  qrContext: QrOverlayContext | undefined,
-  tenantId: TenantId,
-): Promise<ResolvedOverlayLayer> | ResolvedOverlayLayer {
-  if (layer.kind !== "qr") return layer;
-  if (!qrContext) {
-    throw new Error(
-      "derivatives.variant: unreachable — resolveOverlaySpec only omits a qr context when the spec has no qr layer.",
-    );
-  }
-  return resolveQrLayer(layer, qrContext, tenantId);
-}
-
-// Resolves every `qr` layer's dataToken to a concrete value and moves the
-// whole overlay list to `resolvedOverlays` — BEFORE variantSuffix() hashes
-// the spec, so a resolver whose target changes (e.g. a base-URL rotation)
-// invalidates the cache instead of serving a stale target under the old key.
-async function resolveOverlaySpec(
-  spec: VariantSpec,
-  row: FileRefRow,
-  registry: Registry,
-  tenantId: TenantId,
-): Promise<VariantSpec> {
-  if (!spec.overlays || spec.overlays.length === 0) return spec;
-
-  const qrContext = spec.overlays.some((layer) => layer.kind === "qr")
-    ? resolveQrOverlayContext(row, registry)
-    : undefined;
-
-  const resolvedOverlays = await Promise.all(
-    spec.overlays.map((layer) => resolveOverlayLayer(layer, qrContext, tenantId)),
-  );
-  return { ...spec, overlays: undefined, resolvedOverlays };
-}
-
-// sourceMimeType is client-controlled (it's `file.type` off the upload — see
-// file-routes.ts's "a field without `accept` lets a client upload anything")
-// and, when spec.format is unset, a renderer is documented to preserve the
-// source's own format (DerivativeRendererPlugin's doc comment) — so the
-// bytes really are in this format, but the STRING itself must still be
-// allowlisted before it becomes a response Content-Type or storage-provider
-// metadata. Otherwise an app whose renderer wildcard is broad enough (e.g.
-// `image/*`) would let a client-declared `image/svg+xml` ride straight
-// through as an honestly-declared (non-sniffed) active-content type (#2021).
-const KNOWN_SAFE_VARIANT_MIME_TYPES: ReadonlySet<string> = new Set([
-  "image/jpeg",
-  "image/png",
-  "image/webp",
-  "image/avif",
-  "image/gif",
-]);
-
-// The spec — not the renderer — determines the output mimeType, so it's the
-// single source of truth for both what gets written to storage and what the
-// caller receives; a cache hit never runs the renderer, so there's nothing
-// else to derive it from.
-function outputMimeType(spec: VariantSpec, sourceMimeType: string): string {
-  switch (spec.format) {
-    case "webp":
-      return "image/webp";
-    case "avif":
-      return "image/avif";
-    case "jpeg":
-      return "image/jpeg";
-    default: {
-      const normalized = normalizeMimeType(sourceMimeType);
-      return KNOWN_SAFE_VARIANT_MIME_TYPES.has(normalized)
-        ? normalized
-        : "application/octet-stream";
-    }
-  }
-}
-
-// `deps.db` is whatever the caller passes through — in the write-handler
-// pipeline (dispatch-shared.ts) that's the handler's open DbTx. `variant()`
-// then holds that transaction open across a full render (decode/resize/
-// encode) plus the storage read+write, not just the fetchOne/exists checks.
-// On a later rollback in the same handler, a variant already written to
-// storage is orphaned there (row never committed, bytes never cleaned up).
-// Prefer this context from the job/MSP path, where `deps.db` isn't tied to
-// an in-flight write transaction; a synchronous write handler rendering a
-// large image should hand off to a job instead of calling `variant()` inline.
-export function createDerivativesContext(deps: DerivativesContextDeps): DerivativesContext {
-  return {
-    variant: async (fileRefId, spec, name) => {
-      const row = await fetchOne<Record<string, unknown>>(deps.db, fileRefsTable, {
-        id: fileRefId,
-        tenantId: deps.tenantId,
-        isDeleted: false,
-      });
-      if (!row) {
-        throw new NotFoundError("fileRef", fileRefId);
-      }
-      if (!isFileRefRow(row)) {
-        throw new NotFoundError("fileRef", fileRefId);
-      }
-
-      const renderer = resolveRenderer(deps.registry, row.mimeType);
-      if (!renderer) {
-        const known =
-          deps.registry
-            .getExtensionUsages(EXT_DERIVATIVE_RENDERER)
-            .map((u) => u.entityName)
-            .join(", ") || "<none>";
-        throw new InternalError({
-          message: `derivatives.variant: no renderer registered for mimeType "${row.mimeType}".`,
-          details: { knownRenderers: known },
-        });
-      }
-
-      // Resolves qr dataTokens to concrete values BEFORE the spec is hashed
-      // — see resolveOverlaySpec.
-      const resolvedSpec = await resolveOverlaySpec(spec, row, deps.registry, deps.tenantId);
-
-      const src = deps.files.ref(row.storageKey);
-      // ponytail: derived key keeps the source extension regardless of the
-      // spec's format — widen deriveKey if a storage backend ever routes on
-      // extension.
-      const target = src.derive(variantSuffix(name, resolvedSpec));
-      // Belt-and-suspenders: variantSuffix already rejects an unsafe name,
-      // this catches a traversal segment reaching the key through any other
-      // path (e.g. a future deriveKey change).
-      assertSafeStorageKey(target.key);
-      const mimeType = outputMimeType(resolvedSpec, row.mimeType);
-
-      // ponytail: exists→render→write is a TOCTOU window under concurrent
-      // requests for the same variant (duplicate render + write). Ceiling:
-      // non-atomic providers can briefly expose a half-written object as a
-      // cache hit. Upgrade: write to a temp key then atomic rename/copy.
-      if (await target.exists()) {
-        return {
-          storageKey: target.key,
-          mimeType,
-          rendered: false,
-        };
-      }
-
-      const original = await src.read();
-      const result = await renderer.render(original, resolvedSpec, row.mimeType);
-      await target.write(result, mimeType);
-      return {
-        storageKey: target.key,
-        mimeType,
-        rendered: true,
-      };
-    },
-  };
-}

package/src/derivatives/field-variants.ts

@@ -1,20 +0,0 @@
-import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
-import type { Registry } from "../engine/types";
-
-// The field definition IS the whitelist: a request carries a variant NAME,
-// never a spec, so no caller can drive an arbitrary render. `hasOwn` and not
-// a plain index — `name` comes off a URL segment, and `__proto__` would
-// otherwise resolve to something truthy that is not a VariantSpec.
-export function resolveFieldVariant(
-  registry: Registry,
-  entityType: string | null,
-  fieldName: string | null,
-  name: string,
-): VariantSpec | undefined {
-  if (entityType === null || fieldName === null) return undefined;
-  const field = registry.getEntity(entityType)?.fields[fieldName];
-  if (field === undefined) return undefined;
-  if (field.type !== "image" && field.type !== "images") return undefined;
-  if (field.variants === undefined || !Object.hasOwn(field.variants, name)) return undefined;
-  return field.variants[name];
-}

package/src/derivatives/index.ts

@@ -1,14 +0,0 @@
-export type { StoredFileStore } from "./delete-stored-file";
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file";
-export type { DerivativesContextDeps } from "./derivatives-context";
-export { createDerivativesContext, resolveRenderer } from "./derivatives-context";
-export { resolveFieldVariant } from "./field-variants";
-export {
-  canonicalJson,
-  derivativeListPrefix,
-  isDerivativeKeyOf,
-  parseDerivativeKey,
-  specHash,
-  VARIANT_NAME_PATTERN,
-  variantSuffix,
-} from "./variant-key";

package/src/derivatives/variant-key.ts

@@ -1,108 +0,0 @@
-import { createHash } from "node:crypto";
-import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
-
-// Deterministic JSON: object keys sorted (recursively), `undefined` values
-// dropped, arrays keep their order. Two specs that are semantically equal
-// (same keys, different insertion order; explicit `undefined` vs. omitted)
-// serialize identically.
-export function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) {
-    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
-  }
-  if (value !== null && typeof value === "object") {
-    const entries = Object.entries(value as Record<string, unknown>)
-      .filter(([, v]) => v !== undefined)
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}
-
-// A key built from the variant name alone would keep serving stale pixels
-// forever after a spec change; hashing the spec into the key means a
-// changed spec is automatically a new URL.
-export function specHash(spec: VariantSpec): string {
-  return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 16);
-}
-
-export const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
-
-export function variantSuffix(name: string, spec: VariantSpec): string {
-  // `name` ends up in a storage key (see deriveKey) — an unvalidated value
-  // like "../../other-tenant/x" would escape the tenant prefix the key is
-  // built under.
-  if (!VARIANT_NAME_PATTERN.test(name)) {
-    throw new Error(
-      `derivatives: variant name must match ${VARIANT_NAME_PATTERN.source} (letters, digits, hyphens; max 32 chars), got "${name}"`,
-    );
-  }
-  return `${name}-${specHash(spec)}`;
-}
-
-// A full derivative-suffix segment is `<name>-<16 hex chars>` — mirrors
-// VARIANT_NAME_PATTERN (name grammar) + specHash's fixed 16-char slice.
-// Keep in sync with both if either changes.
-const DERIVATIVE_SUFFIX_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}-[0-9a-f]{16}$/i;
-
-// Mirrors deriveKey's own split so callers get the exact same base/ext this
-// key's derivatives were built from.
-function splitKey(key: string): { readonly base: string; readonly ext: string } {
-  const lastSlash = key.lastIndexOf("/");
-  const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
-  const lastDot = lastSegment.lastIndexOf(".");
-  if (lastDot === -1) return { base: key, ext: "" };
-  const base = key.slice(0, key.length - lastSegment.length + lastDot);
-  return { base, ext: lastSegment.slice(lastDot) };
-}
-
-// List-prefix that covers every derivative deriveKey() can produce for
-// `originalKey` — pass to FileStorageProvider.list() to enumerate candidates,
-// then filter with isDerivativeKeyOf before deleting any of them.
-export function derivativeListPrefix(originalKey: string): string {
-  return `${splitKey(originalKey).base}.`;
-}
-
-// True when `candidateKey` is a derivative deriveKey() could have produced
-// for `originalKey` — anchored to originalKey's own basename AND extension.
-// Without the extension anchor, a same-directory sibling original with a
-// different extension (a different file, possibly another user's) would
-// match on prefix alone and get swept into a forget/tenant-destroy delete.
-export function isDerivativeKeyOf(originalKey: string, candidateKey: string): boolean {
-  const { base, ext } = splitKey(originalKey);
-  const prefix = `${base}.`;
-  if (!candidateKey.startsWith(prefix) || !candidateKey.endsWith(ext)) return false;
-  const middle = candidateKey.slice(prefix.length, candidateKey.length - ext.length);
-  return DERIVATIVE_SUFFIX_PATTERN.test(middle);
-}
-
-// buildStorageKey (files/types.ts) always produces exactly 5 "/"-segments
-// ending in "<uniqueId>.<ext>" — a single dot, non-empty on both sides.
-// Anchoring parseDerivativeKey's reconstructed candidate to this shape
-// rejects lookalikes that were never written by buildStorageKey (a GDPR
-// export bundle, a local-provider `*.tmp` write-in-progress file) even when
-// their last segment happens to contain a "name-16hex"-shaped middle token.
-const BUILT_STORAGE_KEY_LAST_SEGMENT_PATTERN = /^[^./]+\.[^./]+$/;
-
-function looksLikeBuiltStorageKey(key: string): boolean {
-  const segments = key.split("/");
-  if (segments.length !== 5) return false;
-  return BUILT_STORAGE_KEY_LAST_SEGMENT_PATTERN.test(segments[4] ?? "");
-}
-
-// Reverse of deriveKey: given a key found on a full storage listing, guesses
-// the original key it would be a derivative of. Used by the orphaned-
-// derivative backfill/GC sweep, which has no audit trail of past forgets to
-// work from — only the deterministic key grammar itself. Returns null for
-// anything that isn't derivative-shaped (including a plain original, which
-// splits with no second dot) or whose reconstructed original doesn't match
-// buildStorageKey's own shape.
-export function parseDerivativeKey(candidateKey: string): { readonly originalKey: string } | null {
-  const { base: withSuffix, ext } = splitKey(candidateKey);
-  const { base: outerBase, ext: suffixExt } = splitKey(withSuffix);
-  if (suffixExt === "") return null;
-  const suffixCandidate = suffixExt.slice(1);
-  if (!DERIVATIVE_SUFFIX_PATTERN.test(suffixCandidate)) return null;
-  const originalKey = `${outerBase}${ext}`;
-  if (!looksLikeBuiltStorageKey(originalKey)) return null;
-  return { originalKey };
-}

package/src/engine/__tests__/_pipeline-test-utils.ts

@@ -1,23 +0,0 @@
-// Shared helpers for unit-tests of pipeline.ts / run-pipeline.ts and the
-// step-builders. The minimal-ctx helper was 4 lines duplicated in every
-// pipeline-* test file; centralised here for the M.1.6 cleanup-pass
-// (Followup #7 splitting).
-//
-// Real-ctx integration lives in pipeline-handler.integration.ts —
-// these helpers are deliberately for the no-DB tests where step-args
-// + assembly + boot-time guards are what's exercised.
-
-import type { HandlerContext } from "../types/handlers";
-
-/**
- * Returns an empty object cast as HandlerContext. Steps that only
- * exercise their own arg-resolution + step-list-assembly don't read
- * any ctx field; the runner needs an object-shaped ctx but no surface
- * beyond that.
- *
- * Tests that actually use ctx fields (db, query, appendEvent, etc.)
- * belong in pipeline-handler.integration.ts against the real stack.
- */
-export function buildMinimalCtx(): HandlerContext {
-  return {} as HandlerContext;
-}

package/src/engine/__tests__/auth-claims-registrar.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { createRegistry, defineFeature } from "../index";
-
-describe("r.authClaims() — registrar collection", () => {
-  test("feature without authClaims has an empty hooks list", () => {
-    const feature = defineFeature("empty", () => {});
-    expect(feature.authClaimsHooks).toEqual([]);
-  });
-
-  test("single authClaims call stores the fn on the feature definition", () => {
-    const hook = async () => ({ teamId: "t-1" });
-    const feature = defineFeature("drivers", (r) => {
-      r.authClaims(hook);
-    });
-    expect(feature.authClaimsHooks).toHaveLength(1);
-    expect(feature.authClaimsHooks[0]).toBe(hook);
-  });
-
-  test("multiple authClaims calls inside one feature are all retained (last-wins is a merge concern, not a storage concern)", () => {
-    const feature = defineFeature("billing", (r) => {
-      r.authClaims(async () => ({ plan: "free" }));
-      r.authClaims(async () => ({ plan: "pro" }));
-    });
-    expect(feature.authClaimsHooks).toHaveLength(2);
-  });
-});
-
-describe("Registry.getAuthClaimsHooks — aggregation across features", () => {
-  test("empty registry has no hooks", () => {
-    const reg = createRegistry([]);
-    expect(reg.getAuthClaimsHooks()).toEqual([]);
-  });
-
-  test("aggregates hooks from multiple features with feature name tagged", () => {
-    const driversFeature = defineFeature("drivers", (r) => {
-      r.authClaims(async () => ({ teamId: "t-1" }));
-    });
-    const billingFeature = defineFeature("billing", (r) => {
-      r.authClaims(async () => ({ plan: "pro" }));
-    });
-    const reg = createRegistry([driversFeature, billingFeature]);
-
-    const hooks = reg.getAuthClaimsHooks();
-    expect(hooks).toHaveLength(2);
-
-    const names = hooks.map((h) => h.featureName).sort();
-    expect(names).toEqual(["billing", "drivers"]);
-  });
-
-  test("preserves registration order within a feature", () => {
-    const feature = defineFeature("billing", (r) => {
-      r.authClaims(async () => ({ x: 1 }));
-      r.authClaims(async () => ({ x: 2 }));
-    });
-    const reg = createRegistry([feature]);
-
-    const hooks = reg.getAuthClaimsHooks();
-    expect(hooks).toHaveLength(2);
-    // Both carry the same featureName; the resolver decides the merge policy.
-    expect(hooks.every((h) => h.featureName === "billing")).toBe(true);
-  });
-
-  test("features without r.authClaims contribute nothing", () => {
-    const plain = defineFeature("plain", () => {});
-    const withClaims = defineFeature("drivers", (r) => {
-      r.authClaims(async () => ({ teamId: "t-1" }));
-    });
-    const reg = createRegistry([plain, withClaims]);
-
-    const hooks = reg.getAuthClaimsHooks();
-    expect(hooks).toHaveLength(1);
-    expect(hooks[0]?.featureName).toBe("drivers");
-  });
-});