@cosmicdrift/kumiko-server-runtime 0.328.1 → 0.330.0

package/src/run-worker-app.ts

@@ -1,366 +0,0 @@
-// runWorkerApp — production-grade bootstrap wrapper for a dedicated
-// Kumiko worker process. Symmetric to runProdApp, but without HTTP: no
-// Hono app, no auth routes, no SSE broker, no seeds. Shares the boot core
-// with runProdApp (env fail-fast, Temporal polyfill, composeFeatures/
-// registry, PII invariants, KMS health gate, connections, schema-drift
-// gate, boot-crypto, extraContext) — see fw#1725: before this function,
-// every app deploying a worker rebuilt this boot by hand (solon#42), and
-// every deviation was silent: without `ensureTemporalPolyfill`, every job
-// in the worker fails with "Temporal is not defined" in a retry loop,
-// with no boot-time signal that anything is wrong.
-//
-// App-author writes:
-//   await runWorkerApp({ features, wireComponents: async (deps) => {...} });
-//
-// Container/Coolify sets the same env vars as runProdApp:
-//   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
-
-import { loadJwtSecretOrKeyring, type ServerOptions } from "@cosmicdrift/kumiko-framework/api";
-import {
-  configureBlindIndexKey,
-  configurePiiSubjectKms,
-  type KmsAdapter,
-  resolvePlatformKeks,
-} from "@cosmicdrift/kumiko-framework/crypto";
-import {
-  configureEntityFieldEncryption,
-  createDbConnection,
-  type DbConnection,
-} from "@cosmicdrift/kumiko-framework/db";
-import {
-  createRegistry,
-  type EffectiveFeaturesResolver,
-  type FeatureDefinition,
-  findTierResolverUsage,
-  type Registry,
-  type TierResolverPlugin,
-  type ValidateBootOptions,
-  validateBoot,
-} from "@cosmicdrift/kumiko-framework/engine";
-import {
-  createWorkerEntrypoint,
-  type WorkerEntrypoint,
-} from "@cosmicdrift/kumiko-framework/entrypoint";
-import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
-import {
-  assertKumikoSchemaCurrent,
-  SchemaDriftError,
-} from "@cosmicdrift/kumiko-framework/migrations";
-import type {
-  ObservabilityOptions,
-  ObservabilityProvider,
-} from "@cosmicdrift/kumiko-framework/observability";
-import {
-  createEntityCache,
-  createEventDedup,
-  createIdempotencyGuard,
-} from "@cosmicdrift/kumiko-framework/pipeline";
-import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
-import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import Redis from "ioredis";
-import { resolveBootCrypto } from "./boot/boot-crypto";
-import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
-import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot";
-import { composeFeatures } from "./compose-features";
-import { makeDispatchSystemWrite, type SystemWireDeps } from "./extra-routes-deps";
-import { assertPiiBootInvariants } from "./pii-boot-gate";
-import { requireEnv } from "./run-prod-app";
-import { addConfigAccessorFactory, buildBootExtraContext } from "./run-prod-app-boot-context";
-
-export type WorkerContextOption =
-  | Record<string, unknown>
-  | ((deps: WorkerDeps) => Record<string, unknown>);
-
-export type WorkerDeps = {
-  readonly db: DbConnection;
-  readonly redis: Redis;
-  readonly registry: Registry;
-};
-
-/** Deps for the `wireComponents` hook — app-wired co-running components
- *  (an analysis runner, an IMAP supervisor, ...) that need the system-
- *  write dispatcher and register their own shutdown hooks on the worker
- *  lifecycle. Same shape as the `wire` hook's SystemWireDeps, plus
- *  `lifecycle` for `registerShutdownHook`. */
-export type WorkerWireDeps = SystemWireDeps & {
-  readonly lifecycle: WorkerEntrypoint["lifecycle"];
-};
-
-export type RunWorkerAppOptions = {
-  /** App-specific features — same array as in the API/all-in-one process,
-   *  so the registry + schema stay identical across processes. */
-  readonly features: readonly FeatureDefinition[];
-  /** Opt-in boot-validator warnings — see ValidateBootOptions. */
-  readonly validateBootOptions?: ValidateBootOptions;
-  /** Mount the auto-mixed config/user/tenant/auth-email-password features —
-   *  MUST match the API process's `includeBundled` value, otherwise API
-   *  and worker run with a diverging registry topology. Also controls
-   *  whether buildBootExtraContext auto-wires `configResolver` (same
-   *  auth-mode gate as runProdApp). */
-  readonly includeBundled?: boolean;
-  /** Path to kumiko/migrations for the boot gate. See RunProdAppOptions
-   *  ["migrations"] — identical semantics. */
-  readonly migrations?: { readonly dir: string } | false;
-  /** Extra AppContext keys — same factory-union pattern as
-   *  RunProdAppOptions["extraContext"], without sseBroker (the worker
-   *  has none — see entrypoint/index.ts's documented SSE limitation). */
-  readonly extraContext?: WorkerContextOption;
-  /** MasterKeyProvider for ctx.secrets. Default: env-KEK (see
-   *  RunProdAppOptions["masterKey"]). */
-  readonly masterKey?: MasterKeyProvider;
-  /** Subject-key adapter for crypto-shredding — boot checks health()
-   *  before any connection (see RunProdAppOptions["kms"]). */
-  readonly kms?: KmsAdapter;
-  /** Blind-index key for lookupable fields (see
-   *  RunProdAppOptions["blindIndexKey"]). */
-  readonly blindIndexKey?: string;
-  /** Explicit opt-out from the PII boot gate (see
-   *  RunProdAppOptions["allowPlaintextPii"]). */
-  readonly allowPlaintextPii?: string;
-  readonly jobs?: {
-    readonly queueNamePrefix?: string;
-    /** Source of active tenant ids for `perTenant: true` jobs (see
-     *  RunProdAppOptions["jobs"]["getActiveTenantIds"]) — identical
-     *  semantics, framework falls back to the tenant feature's own
-     *  active-tenant-ids query when omitted. */
-    readonly getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
-  };
-  /** Tuning knobs for the event-dispatcher loop (pollIntervalMs, pgClient
-   *  for LISTEN/NOTIFY). */
-  readonly eventDispatcher?: ServerOptions["eventDispatcher"];
-  /** Hook for app-wired co-running components that need the system-write
-   *  dispatcher (e.g. an analysis runner, an IMAP supervisor). Runs AFTER
-   *  `entrypoint.start()` — the hook itself is responsible for starting
-   *  its component and registering a shutdown hook on `lifecycle`. */
-  readonly wireComponents?: (deps: WorkerWireDeps) => Promise<void> | void;
-  /** Feature-toggle resolver (see RunProdAppOptions["effectiveFeatures"]). */
-  readonly effectiveFeatures?: EffectiveFeaturesResolver;
-  /** Override `process.env` for env-validation (see
-   *  RunProdAppOptions["envSource"]). */
-  readonly envSource?: Record<string, string | undefined>;
-  /** Env names to decrypt from their `_CIPHERTEXT` twin at boot, typically
-   *  `kmsSlotsOf(composedEnv.schema)`. The worker parses no env schema, so it
-   *  cannot derive them; without this it reads the env as is. */
-  readonly kmsSlots?: readonly string[];
-  readonly observability?: ObservabilityProvider;
-  readonly observabilityOptions?: ObservabilityOptions;
-};
-
-export type WorkerAppHandle = {
-  /** In KUMIKO_DRY_RUN_ENV=boot mode with an injected envSource (test
-   *  path), no boot ran — this slot is an undefined-cast, do not access. */
-  readonly entrypoint: WorkerEntrypoint;
-  readonly stop: () => Promise<void>;
-};
-
-function makeBootModeHandle(): WorkerAppHandle {
-  return {
-    // @cast-boundary boot-mode: no entrypoint exists because no boot ran —
-    // callers on this path never read this slot.
-    entrypoint: undefined as unknown as WorkerEntrypoint,
-    stop: async () => {},
-  };
-}
-
-export async function runWorkerApp(options: RunWorkerAppOptions): Promise<WorkerAppHandle> {
-  const rawEnvSource = options.envSource ?? process.env;
-  const envSource: Record<string, string | undefined> = options.kmsSlots
-    ? await resolvePlatformKeks(rawEnvSource, {
-        slots: options.kmsSlots,
-        logPrefix: "[runWorkerApp]",
-      })
-    : rawEnvSource;
-
-  // 1. Polyfill before anything else — exactly the bug fw#1725 reports:
-  //    without it, every job in the worker fails with "Temporal is not
-  //    defined" in a retry loop, with no boot-time signal.
-  const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
-  await ensureTemporalPolyfill();
-
-  // 2. Env vars: fail-fast, same requireEnv as runProdApp. JWT_SECRET is
-  //    validated by loadJwtSecretOrKeyring itself (throws when neither
-  //    JWT_SECRET nor JWT_SECRET_V<n> is set).
-  const databaseUrl = requireEnv("DATABASE_URL", envSource, "runWorkerApp");
-  const redisUrl = requireEnv("REDIS_URL", envSource, "runWorkerApp");
-  const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
-
-  // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-  console.log("[runWorkerApp] booting Kumiko worker…");
-
-  // 3. Feature registry — identical to runProdApp, MUST be built with the
-  //    same `includeBundled` as the API process.
-  const features = composeFeatures(options.features, {
-    includeBundled: !!options.includeBundled,
-  });
-  validateBoot(features, { env: envSource, ...options.validateBootOptions });
-  warnIfNonUtcServerTimeZone();
-  assertPiiBootInvariants(features, {
-    kms: options.kms,
-    blindIndexKey: options.blindIndexKey,
-    allowPlaintextPii: options.allowPlaintextPii,
-    mode: "prod",
-  });
-  const registry = createRegistry(features);
-
-  // Boot-mode exit (parity with runProdApp's C1): validators ran and the
-  // registry is built, no DB/Redis client was constructed. Makes the boot
-  // testable without real Postgres/Redis infra.
-  if (envSource["KUMIKO_DRY_RUN_ENV"] === "boot") {
-    // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
-    console.log(
-      `[runWorkerApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`,
-    );
-    if (options.envSource === undefined) {
-      process.exit(0);
-    }
-    return makeBootModeHandle();
-  }
-
-  // 4. KMS health gate — runs BEFORE the connections, so an abort leaks
-  //    nothing (identical to runProdApp).
-  if (options.kms) {
-    const kmsHealth = await options.kms.health();
-    if (!kmsHealth.ok) {
-      throw new Error(
-        `[runWorkerApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`,
-      );
-    }
-  }
-
-  const { db, close: closeDb } = createDbConnection(databaseUrl);
-  const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
-
-  let resolvedEffectiveFeatures: EffectiveFeaturesResolver | undefined = options.effectiveFeatures;
-  if (resolvedEffectiveFeatures === undefined) {
-    const tierResolverUsage = findTierResolverUsage(features);
-    if (tierResolverUsage) {
-      const plugin = tierResolverUsage.options as TierResolverPlugin;
-      resolvedEffectiveFeatures = await plugin.build({ db, registry });
-    }
-  }
-
-  // 5. Schema-drift gate — identical to runProdApp.
-  if (options.migrations !== false) {
-    const migrationsDir = options.migrations?.dir ?? "./kumiko/migrations";
-    // biome-ignore lint/suspicious/noConsole: boot-time progress hint
-    console.log(`[runWorkerApp] checking schema drift (${migrationsDir})…`);
-    try {
-      await assertKumikoSchemaCurrent(db, migrationsDir);
-    } catch (err) {
-      if (err instanceof SchemaDriftError) {
-        // biome-ignore lint/suspicious/noConsole: terminal error message
-        console.error(`\n[runWorkerApp] BOOT ABORTED — ${err.message}\n`);
-      }
-      throw err;
-    }
-  }
-
-  // 6. Pipeline pieces — same defaults as runProdApp.
-  const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
-  const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
-  const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
-
-  // 7. Boot-crypto + extraContext — the core of fw#1725: KMS wiring,
-  //    blind-index, config-encryption must be wired in the worker exactly
-  //    like in the API, otherwise the worker writes rows the API can no
-  //    longer read (different cipher, missing blind index).
-  const deps: WorkerDeps = { db, redis, registry };
-  const resolvedExtraContext =
-    typeof options.extraContext === "function"
-      ? options.extraContext(deps)
-      : (options.extraContext ?? {});
-
-  const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
-  configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
-  configurePiiSubjectKms(options.kms);
-  configureBlindIndexKey(options.blindIndexKey);
-  const autoExtraContext = buildBootExtraContext({
-    db,
-    features,
-    envSource,
-    registry,
-    hasAuth: !!options.includeBundled,
-    crypto: bootCrypto,
-    ...(options.kms && { kms: options.kms }),
-  });
-  const extraContext = addConfigAccessorFactory(
-    { ...autoExtraContext, ...resolvedExtraContext },
-    registry,
-  );
-
-  const jobLogger = jobRunLoggerCallbacks(registry, db);
-  const entrypoint = createWorkerEntrypoint({
-    registry,
-    context: { db, redis, entityCache, registry, ...extraContext },
-    jwtSecret: jwtSecretOrKeyring,
-    dispatcherOptions: {
-      idempotency,
-      ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
-    },
-    eventDedup,
-    ...(options.observability && { observability: options.observability }),
-    ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
-    redisUrl,
-    ...jobLogger,
-    ...(options.jobs?.queueNamePrefix !== undefined && {
-      queueNamePrefix: options.jobs.queueNamePrefix,
-    }),
-    ...(options.jobs?.getActiveTenantIds !== undefined && {
-      getActiveTenantIds: options.jobs.getActiveTenantIds,
-    }),
-    ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
-  });
-
-  const handle: WorkerAppHandle = {
-    entrypoint,
-    stop: async () => {
-      await entrypoint.stop();
-      await closeDb();
-      redis.disconnect();
-    },
-  };
-
-  await entrypoint.start();
-  startPiiEventBackfillOnBoot({
-    db,
-    registry,
-    lifecycle: entrypoint.lifecycle,
-    envSource,
-  });
-
-  if (options.wireComponents) {
-    await options.wireComponents({
-      db,
-      redis,
-      registry,
-      dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
-      lifecycle: entrypoint.lifecycle,
-    });
-  }
-
-  let shuttingDown = false;
-  const shutdown = async (signal: string) => {
-    // skip: shutdown already in progress, avoid double-drain
-    if (shuttingDown) return;
-    shuttingDown = true;
-    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-    console.log(`[runWorkerApp] ${signal} received — draining…`);
-    try {
-      await handle.stop();
-      // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-      console.log("[runWorkerApp] graceful shutdown complete.");
-    } catch (e) {
-      // biome-ignore lint/suspicious/noConsole: shutdown-time error, only path is stderr
-      console.error("[runWorkerApp] error during shutdown:", e);
-    } finally {
-      process.exit(0);
-    }
-  };
-  process.on("SIGTERM", () => void shutdown("SIGTERM"));
-  process.on("SIGINT", () => void shutdown("SIGINT"));
-
-  // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-  console.log("[runWorkerApp] ready — worker running.");
-
-  return handle;
-}

package/src/security-headers.ts

@@ -1,67 +0,0 @@
-export type SecurityHeadersOption =
-  | false
-  | {
-      /** `Strict-Transport-Security` value, or `false` to omit.
-       *  Default: `max-age=31536000; includeSubDomains`. */
-      readonly hsts?: string | false;
-      /** `X-Frame-Options` value, or `false` to omit. Default: `DENY`.
-       *  Apps that must be embeddable (iframe widgets) set `false` and
-       *  scope framing via a `csp` frame-ancestors directive instead. */
-      readonly frameOptions?: string | false;
-      /** `false` omits `X-Content-Type-Options: nosniff`. */
-      readonly contentTypeOptions?: false;
-      /** `Referrer-Policy` value, or `false` to omit.
-       *  Default: `strict-origin-when-cross-origin`. */
-      readonly referrerPolicy?: string | false;
-      /** `Content-Security-Policy` default for ALL responses. No built-in
-       *  default — a wrong CSP breaks app assets, so it stays opt-in.
-       *  A per-host CSP from `hostDispatch` wins over this value. */
-      readonly csp?: string;
-    };
-
-const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
-const DEFAULT_FRAME_OPTIONS = "DENY";
-const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
-
-export function resolveSecurityHeaders(
-  option: SecurityHeadersOption | undefined,
-): ReadonlyArray<readonly [string, string]> {
-  if (option === false) return [];
-  const opt = option ?? {};
-  const headers: Array<readonly [string, string]> = [];
-  const hsts = opt.hsts ?? DEFAULT_HSTS;
-  if (hsts !== false) headers.push(["strict-transport-security", hsts]);
-  const frameOptions = opt.frameOptions ?? DEFAULT_FRAME_OPTIONS;
-  if (frameOptions !== false) headers.push(["x-frame-options", frameOptions]);
-  if (opt.contentTypeOptions !== false) headers.push(["x-content-type-options", "nosniff"]);
-  const referrerPolicy = opt.referrerPolicy ?? DEFAULT_REFERRER_POLICY;
-  if (referrerPolicy !== false) headers.push(["referrer-policy", referrerPolicy]);
-  if (opt.csp) headers.push(["content-security-policy", opt.csp]);
-  return headers;
-}
-
-// Sets each header only when absent so per-response values (e.g. the
-// per-host CSP from hostDispatch) always win over the runtime default.
-export function withSecurityHeaders<TServeArg = string>(
-  handler: (req: Request, serveArg?: TServeArg) => Response | Promise<Response>,
-  option: SecurityHeadersOption | undefined,
-): (req: Request, serveArg?: TServeArg) => Response | Promise<Response> {
-  const defaults = resolveSecurityHeaders(option);
-  if (defaults.length === 0) return handler;
-  return async (req: Request, serveArg?: TServeArg): Promise<Response> => {
-    const res = await handler(req, serveArg);
-    try {
-      for (const [name, value] of defaults) {
-        if (!res.headers.has(name)) res.headers.set(name, value);
-      }
-      return res;
-    } catch {
-      // Immutable-headers Response (e.g. proxied fetch) — re-wrap.
-      const headers = new Headers(res.headers);
-      for (const [name, value] of defaults) {
-        if (!headers.has(name)) headers.set(name, value);
-      }
-      return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
-    }
-  };
-}

package/src/session-boot-gate.ts

@@ -1,34 +0,0 @@
-export type SessionBootGateOptions = {
-  readonly hasAuth: boolean;
-  readonly sessionStoreProviderMounted: boolean;
-  /** prod fails hard on a missing sessionStore provider (stateless JWTs would
-   *  silently skip server-side revocation and any session-list UI stays
-   *  empty); dev only warns — a forgotten sessions mount in a local sample
-   *  app shouldn't crash the dev-server boot, but it must not stay silent
-   *  either (#2027 — dev previously had no gate here at all). */
-  readonly mode: "prod" | "dev";
-};
-
-// Catch a forgotten sessions mount at boot instead of silently degrading
-// into stateless JWTs (#1372). Mount createSessionsFeature() for revocable
-// sessions; there is no auth.sessions opt-out anymore.
-export function assertSessionBootInvariants(opts: SessionBootGateOptions): void {
-  // skip: no auth mounted — nothing to gate.
-  if (!opts.hasAuth) return;
-  // skip: sessionStore provider is wired (sessions feature).
-  if (opts.sessionStoreProviderMounted) return;
-
-  const tag = opts.mode === "prod" ? "runProdApp" : "runDevApp";
-  const message =
-    "auth is mounted but no sessionStore provider is registered. JWTs would be stateless " +
-    "(no server-side revocation) and any session-list screen stays empty. Mount " +
-    "createSessionsFeature() (@cosmicdrift/kumiko-bundled-features/sessions) alongside auth-foundation.";
-
-  if (opts.mode === "dev") {
-    // biome-ignore lint/suspicious/noConsole: boot-time ops warning, no logger configured this early
-    console.warn(`[${tag}] ${message}`);
-    // skip: dev mode, warning already logged above — never abort dev boot.
-    return;
-  }
-  throw new Error(`[${tag}] BOOT ABORTED — ${message}`);
-}