@cosmicdrift/kumiko-server-runtime 0.387.0 → 0.388.0

package/dist/run-prod-app-handle.js

@@ -0,0 +1,104 @@
+import { flushEscapeHatchAudits } from "@cosmicdrift/kumiko-framework/pipeline";
+import { installShutdownSignals } from "./boot-options/process-signals.js";
+import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
+import { installFatalErrorHandlers } from "./fatal-error-handlers.js";
+import { uninstallProcessLogger } from "./process-logger.js";
+import { buildStaticFallback, resolveCspScriptHashes, resolveHostDispatchScriptHashes, } from "./run-prod-app-static-files.js";
+import { withSecurityHeaders } from "./security-headers.js";
+import { stripNoRouteMatchHeader } from "./try-hono-first.js";
+const SERVER_GRACEFUL_STOP_MS = 10_000;
+// stop() without force waits for open connections (SSE never ends on its own); force-close after the grace period.
+async function stopServerGracefully(server) {
+    let graceTimer;
+    const graceElapsed = new Promise((resolve) => {
+        graceTimer = setTimeout(resolve, SERVER_GRACEFUL_STOP_MS);
+    });
+    try {
+        await Promise.race([server.stop(), graceElapsed]);
+    }
+    finally {
+        clearTimeout(graceTimer);
+    }
+    await server.stop(true);
+}
+// Static-fallback for non-/api/ paths wired via a wrapper so Hono owns
+// /api/* + extraRoutes and disk owns the rest. Tests use this directly;
+// listen() wraps it in Bun.serve.
+export async function buildProdFetchHandler(options, config, entrypoint) {
+    const cspScriptHashes = await resolveCspScriptHashes(options.staticDir, options.securityHeaders);
+    const hostDispatchScriptHashes = options.hostDispatch !== undefined && options.staticDir !== undefined
+        ? await resolveHostDispatchScriptHashes(options.staticDir, options.securityHeaders, cspScriptHashes)
+        : [];
+    const fetchHandler = withSecurityHeaders(config.bootOptionWiring.wrapFetch(options.staticDir
+        ? buildStaticFallback(entrypoint.app.fetch.bind(entrypoint.app), options.staticDir, options.hostDispatch, options.resolvePageHead
+            ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
+            : undefined, entrypoint.dispatcher, config.trustedProxyHops ?? 0, hostDispatchScriptHashes)
+        : // No staticDir (split-deploy / API-only container) → app.fetch's
+            // response goes straight to the client, bypassing buildStaticFallback
+            // (and with it tryHonoFirst) entirely. Must strip the router-miss
+            // marker here too, same reason as the /api/* passthrough in
+            // run-prod-app-static-files.ts (see try-hono-first.ts).
+            async (req, socketAddress) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, socketAddress))), options.securityHeaders, cspScriptHashes);
+    return { fetchHandler, cspScriptHashes };
+}
+export function createProdAppHandle(input) {
+    const { options, config, composed, connections, entrypoint, log } = input;
+    const { fetchHandler, cspScriptHashes } = input.fetch;
+    // Upgrade rejections (401/403/426...) are ordinary responses and get the same headers as fetchHandler.
+    const securedUpgradeFetch = withSecurityHeaders(async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env)), options.securityHeaders, cspScriptHashes);
+    const webSocketUpgradeFetch = async (req, env) => securedUpgradeFetch(req, env);
+    let uninstallShutdownSignals;
+    let uninstallFatalHandlers;
+    const handle = {
+        entrypoint,
+        fetch: fetchHandler,
+        webSocketUpgradeFetch,
+        listen: async (listenPort = config.port) => {
+            // Bun.serve provides production HTTP. Tests run under Node, so they call the
+            // fetch handler directly instead. buildBunServeOptions centralizes the
+            // options shape, including `idleTimeout: 0` for SSE.
+            if (typeof Bun === "undefined") {
+                // Throw a clear error instead of a raw ReferenceError when listen() is called
+                // under Node/vitest without autoListen:false, making the runtime
+                // requirement explicit.
+                throw new Error("[runProdApp] listen() requires Bun runtime (Bun.serve). " +
+                    "Under Node/vitest pass `autoListen: false` and call the returned `fetch()` directly.");
+            }
+            handle.server = Bun.serve(buildBunServeOptions(listenPort, fetchHandler, options.maxRequestBodySize ?? resolveDerivedMaxRequestBodySize(composed.registry), { upgradeFetch: webSocketUpgradeFetch }));
+            // SIGTERM/SIGINT — graceful shutdown. Only registered when we
+            // actually own a Bun-server, otherwise the test process picks up
+            // signals it shouldn't respond to.
+            if (options.signals !== false) {
+                uninstallShutdownSignals?.();
+                uninstallShutdownSignals = installShutdownSignals({
+                    stop: () => handle.stop(),
+                    ...(options.signals?.drainTimeoutMs !== undefined && {
+                        drainTimeoutMs: options.signals.drainTimeoutMs,
+                    }),
+                });
+                uninstallFatalHandlers?.();
+                uninstallFatalHandlers = installFatalErrorHandlers({
+                    logger: log,
+                    stop: () => handle.stop(),
+                });
+            }
+            log.info(`ready on http://0.0.0.0:${listenPort}`);
+        },
+        stop: async () => {
+            uninstallFatalHandlers?.();
+            uninstallFatalHandlers = undefined;
+            await entrypoint.stop();
+            if (handle.server)
+                await stopServerGracefully(handle.server);
+            await flushEscapeHatchAudits();
+            await connections.closeDb();
+            await connections.closeOutsideTransactionDb();
+            connections.redis.disconnect();
+            await config.bootKms.close();
+            uninstallShutdownSignals?.();
+            uninstallShutdownSignals = undefined;
+            uninstallProcessLogger();
+        },
+    };
+    return handle;
+}

package/dist/run-prod-app-request-context.d.ts

@@ -0,0 +1,15 @@
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+export declare function buildProdRequestContext(options: RunProdAppOptions, config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections): Promise<{
+    idempotency: import("@cosmicdrift/kumiko-framework/pipeline").IdempotencyGuard;
+    eventDedup: import("@cosmicdrift/kumiko-framework/pipeline").EventDedup;
+    entityCache: import("@cosmicdrift/kumiko-types/entity-cache").EntityCache;
+    sseBroker: import("@cosmicdrift/kumiko-framework/api").SseBroker;
+    ownedRedisSseBroker: import("@cosmicdrift/kumiko-framework/api").RedisSseBroker | undefined;
+    extraContext: {
+        defaultLocale?: string | undefined;
+    };
+    resolvedAnonymousAccess: import("@cosmicdrift/kumiko-framework/api").AnonymousAccessResolved | undefined;
+}>;
+export type ProdRequestContext = Awaited<ReturnType<typeof buildProdRequestContext>>;

package/dist/run-prod-app-request-context.js

@@ -0,0 +1,103 @@
+import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createDefaultSseBroker } from "@cosmicdrift/kumiko-framework/api";
+import { configureBlindIndexKey, configurePiiSubjectKms, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import { createFallbackLogger, setProcessLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, } from "./run-prod-app-boot-context.js";
+function buildProdExtraContext(options, config, composed, connections, deps) {
+    const { envSource, bootKms } = config;
+    const { registry, features, effectiveAuth, bootCrypto, unsubscribeLinks } = composed;
+    const resolvedExtraContext = typeof options.extraContext === "function"
+        ? options.extraContext(deps)
+        : (options.extraContext ?? {});
+    // Install framework defaults first; app values in resolvedExtraContext always
+    // win (for example, an app-specific configResolver).
+    // The app-wide cipher is resolved lazily, so entities without encrypted
+    // fields never access it.
+    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+    // Subject-key KMS for pii-annotated fields (crypto-shredding).
+    // No adapter only gets this far when assertPiiBootInvariants above let it
+    // through: no PII carriers, or an explicit allowPlaintextPii opt-out. The
+    // engine then stays off and those fields are stored in plaintext.
+    configurePiiSubjectKms(bootKms.kms);
+    // Blind-index key boot gate: with KMS enabled, lookupable fields are stored as
+    // ciphertext. Without the key, equality lookups such as login by email cannot
+    // work, so fail fast rather than allowing silently broken authentication.
+    configureBlindIndexKey(bootKms.blindIndexKey);
+    const bootLogger = loggerFromExtraContext(resolvedExtraContext);
+    if (bootLogger)
+        setProcessLogger(bootLogger);
+    const autoExtraContext = buildBootExtraContext({
+        db: connections.db,
+        features,
+        envSource,
+        registry,
+        hasAuth: !!effectiveAuth,
+        sseBroker: deps.sseBroker,
+        redis: connections.redis,
+        crypto: bootCrypto,
+        ...(bootKms.kms && { kms: bootKms.kms }),
+        ...(bootLogger && { log: bootLogger }),
+        ...(unsubscribeLinks && { unsubscribeLinks }),
+        ...(options.appOverrides && { appOverrides: options.appOverrides }),
+    });
+    return {
+        ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
+        ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
+    };
+}
+async function resolveProdAnonymousAccess(options, deps) {
+    const baseAnonymousAccess = typeof options.anonymousAccess === "function"
+        ? options.anonymousAccess(deps)
+        : options.anonymousAccess;
+    // tenantResolver / tenantExists come from auth-foundation providers.
+    return resolveAnonymousAccessFromRegistry(baseAnonymousAccess, {
+        db: deps.db,
+        registry: deps.registry,
+        warn: (message) => createFallbackLogger("runProdApp").warn(message),
+    });
+}
+export async function buildProdRequestContext(options, config, composed, connections) {
+    const { db, redis } = connections;
+    const { registry, bootCrypto } = composed;
+    // Pipeline pieces — same default config as runDevApp's setupTestStack.
+    const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
+    const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
+    const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
+    // When no lifecycle is supplied, createApiEntrypoint builds and owns it;
+    // the handle exposes it for SIGTERM.
+    //
+    // extraContext and anonymousAccess accept either an object or a factory that
+    // receives {db, redis, registry}; factories are useful when boot-time database
+    // access is needed, such as a subdomain-to-tenant resolver.
+    //
+    // Build the SSE broker here so extraContext factories can close over it, and
+    // pass the same broker into createApiEntrypoint (sseBroker option) so
+    // server-internal broadcasts and app-specific publishes share one broker. Use
+    // createDefaultSseBroker so REDIS_URL selects a Redis-backed broker; an
+    // unconditional in-memory broker would silently override buildServer's
+    // Redis-backed default (ServerOptions.sseBroker always wins) and prevent
+    // cross-replica fanout.
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker(config.envSource);
+    const deps = {
+        db,
+        redis,
+        registry,
+        sseBroker,
+        env: config.envSource,
+        ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+        ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+    };
+    const extraContext = buildProdExtraContext(options, config, composed, connections, deps);
+    const resolvedAnonymousAccess = await resolveProdAnonymousAccess(options, deps);
+    return {
+        idempotency,
+        eventDedup,
+        entityCache,
+        sseBroker,
+        ownedRedisSseBroker,
+        extraContext,
+        resolvedAnonymousAccess,
+    };
+}

package/dist/run-prod-app-seeds.d.ts

@@ -0,0 +1,13 @@
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+import type { ProdEntrypoint, ProdEntrypointOptions } from "./run-prod-app-entrypoint.ts";
+import type { ProdRequestContext } from "./run-prod-app-request-context.ts";
+export type ProdSeedRun = {
+    readonly options: RunProdAppOptions;
+    readonly config: ProdBootConfig;
+    readonly composed: ProdComposedFeatures;
+    readonly connections: ProdConnections;
+    readonly requestContext: ProdRequestContext;
+};
+export declare function runProdBootSeeds(run: ProdSeedRun, entrypoint: ProdEntrypoint, dispatcherOptions: ProdEntrypointOptions["dispatcherOptions"]): Promise<void>;

package/dist/run-prod-app-seeds.js

@@ -0,0 +1,86 @@
+import { withFileProviderResolver } from "@cosmicdrift/kumiko-framework/api";
+import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
+import { createDispatcher, createUnlimitedRateLimitResolver, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { applyStandardBootSeeds } from "./boot/shared-boot-steps.js";
+import { makeSeedCreateFileRef, withSeedErrorContext, } from "./seed-dispatcher.js";
+// Seeds are bootstrap writes, not tenant traffic: they always get the unlimited resolver,
+// even when the app has a real one, so a handler's rateLimit can neither fail nor drain them.
+function buildSeedContext(run) {
+    const { registry } = run.composed;
+    const { db, redis, cacheSync } = run.connections;
+    return withFileProviderResolver(registry, {
+        db,
+        redis,
+        entityCache: run.requestContext.entityCache,
+        registry,
+        ...run.requestContext.extraContext,
+        rateLimit: createUnlimitedRateLimitResolver(),
+    }, cacheSync);
+}
+async function runCustomSeeds(run, seedContext, seedDispatcher) {
+    const { db } = run.connections;
+    const { registry, bootCrypto } = run.composed;
+    const createFileRef = makeSeedCreateFileRef({
+        db,
+        registry,
+        context: seedContext,
+    });
+    for (const seed of run.config.bootOptionWiring.customSeeds) {
+        await seed({
+            db,
+            registry,
+            dispatcher: seedDispatcher,
+            createFileRef,
+            ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+            ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+        });
+    }
+}
+// ES operations and seed migrations run after applyBootSeeds and the existing
+// seeds array. Declarative seeds insert missing records; seed migrations
+// diff and update state that existing seeds cannot revise, such as membership
+// roles changed after initial seed creation.
+async function runSeedMigrations(run, seedsDir, seedDispatcher) {
+    const { db } = run.connections;
+    await createEsOperationsTable(db);
+    await runPendingSeedMigrations({
+        db,
+        seedsDir,
+        appliedBy: "boot",
+        registry: run.composed.registry, // The dry-run validator catches handler QN typos before writing.
+        // @wrapper-known semantic-alias
+        createContext: (dbRunner) => createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
+    });
+}
+// Seeds: admin first, then config-seeds from r.config({seeds}),
+// then app-specific. All idempotent — runProdApp doesn't gate
+// "first boot" via flag, every seed-step checks its own
+// preconditions. Config-seeds rely on a deterministic
+// aggregate-id so re-boot becomes a version_conflict skip.
+export async function runProdBootSeeds(run, entrypoint, dispatcherOptions) {
+    const { options, config, composed, connections } = run;
+    await applyStandardBootSeeds({
+        db: connections.db,
+        registry: composed.registry,
+        admin: composed.effectiveAuth?.admin,
+        shortcutSeeds: config.bootOptionWiring.shortcutSeeds,
+        cipher: composed.bootCrypto.configCipher,
+    });
+    const hasSeeds = config.bootOptionWiring.customSeeds.length > 0 || options.seedsDir !== undefined;
+    const seedContext = hasSeeds ? buildSeedContext(run) : undefined;
+    const seedDispatcher = seedContext
+        ? withSeedErrorContext(createDispatcher(composed.registry, seedContext, {
+            ...dispatcherOptions,
+            lifecycle: entrypoint.lifecycleHooks,
+            ...(entrypoint.mode === "all-in-one" && { jobRunner: entrypoint.jobRunner }),
+        }))
+        : undefined;
+    if (seedDispatcher && seedContext) {
+        await runCustomSeeds(run, seedContext, seedDispatcher);
+    }
+    if (seedDispatcher &&
+        options.seedsDir !== undefined &&
+        config.envSource["KUMIKO_SKIP_ES_OPS"] !== "1") {
+        await runSeedMigrations(run, options.seedsDir, seedDispatcher);
+    }
+}

package/dist/run-prod-app.d.ts

@@ -1,36 +1,36 @@
 /// <reference types="bun-types" preserve="true" />
-import { type AccountLockoutOptions, type AccountUnlockOptions, type AuthMailLocale, type AuthPaths, type EmailVerificationOptions, type InviteOptions, type PasswordResetOptions, type SignupOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
-import { type ExtraRouteDefinition, type KumikoServeEnv, type PostAuthLandingResolver, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
-import { type FeatureDefinition, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
-import { type AllInOneEntrypoint, type ApiEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { AccountLockoutOptions, AccountUnlockOptions, AuthMailLocale, AuthPaths, EmailVerificationOptions, InviteOptions, PasswordResetOptions, SignupOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import type { SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import type { ExtraRouteDefinition, KumikoServeEnv, PostAuthLandingResolver, SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { FeatureDefinition, ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import type { AllInOneEntrypoint, ApiEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
 import type { ComposedEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
 import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
-import { type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
+import type { ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery } from "@cosmicdrift/kumiko-renderer/headless/apex";
-import { Redis } from "ioredis";
+import type { Redis } from "ioredis";
 import type { BillingBootOption } from "./boot-options/billing-option.ts";
 import type { DemoModeOption } from "./boot-options/demo-mode.ts";
 import type { FileStorageBootOption } from "./boot-options/file-storage-option.ts";
 import type { KmsMode } from "./boot-options/kms-mode.ts";
 import type { MailBootOption } from "./boot-options/mail-option.ts";
-import { type SignalsOption } from "./boot-options/process-signals.ts";
+import type { SignalsOption } from "./boot-options/process-signals.ts";
 import type { ProdSeedsConfig } from "./boot-options/seed-shortcuts.ts";
-import { type SystemWireDeps } from "./extra-routes-deps.ts";
-import { type RateLimitOption } from "./rate-limit-defaults.ts";
-import { type UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
-import { type ConfigOverridesInput } from "./run-prod-app-boot-context.ts";
-import { type SecurityHeadersOption } from "./security-headers.ts";
-import { type SeedCreateFileRef } from "./seed-dispatcher.ts";
+import type { SystemWireDeps } from "./extra-routes-deps.ts";
+import type { RateLimitOption } from "./rate-limit-defaults.ts";
+import type { UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
+import type { ConfigOverridesInput } from "./run-prod-app-boot-context.ts";
+import type { SecurityHeadersOption } from "./security-headers.ts";
+import type { SeedCreateFileRef } from "./seed-dispatcher.ts";
 export { parseRunMode } from "./boot/env-gate.ts";
 export { buildBunServeOptions } from "./bun-serve-options.ts";
+export { requireEnv } from "./require-env.ts";
 export { resolveUnsubscribeWiring, type UnsubscribeOption, } from "./resolve-unsubscribe-wiring.ts";
 export { addConfigAccessorFactory, buildBootExtraContext, type ConfigOverridesInput, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.ts";
 export { staticCachePolicy } from "./run-prod-app-static-files.ts";
-export declare function requireEnv(name: string, src?: Record<string, string | undefined>, context?: string): string;
 /** Wrapper API for the password-reset flow.
  *
  *  Since the delivery migration PasswordResetOptions carries `appUrl`
@@ -380,7 +380,7 @@ export type RunProdAppOptions = {
      *  @example
      *  fileStorage: { provider: "auto" } */
     readonly fileStorage?: FileStorageBootOption;
-    /** Stripe billing: `subscription-stripe` plus the tier-syncing webhook
+    /** Billing: `subscription-stripe` and/or `subscription-dodo` plus one tier-syncing webhook
      *  route. Needs `billing-foundation` and `tier-engine`. See `BillingBootOption`.
      *  @example
      *  billing: { stripe: { priceToTier: { [env.STRIPE_PRICE_PRO]: "pro" } }, defaultTier: "free" } */
@@ -449,7 +449,9 @@ export type RunProdAppOptions = {
      *  then the `APP_BASE_URL` env; with none of them no link is added (boot warning). Address
      *  recipients need a blind-index key, otherwise they get no link. Do not also mount
      *  `createUnsubscribeRoutes` via `extraRoutes`. `tenantOrigin` points a tenant's links at
-     *  its own subdomain or custom domain (the host must serve this app's `/api` routes); null,
+     *  its own subdomain or custom domain (the host must serve this app's `/api` routes, and
+     *  the callback must only return a verified, active domain, else null: the link carries a bearer
+     *  token a stale domain's new owner would receive); null,
      *  a throw or a non-https value fall back to the app origin. The link carries the mail's
      *  locale, so the confirmation pages speak the mail's language. An app reacts to an address
      *  opt-out with an `r.job` triggered on `DeliveryHandlers.unsubscribeAddress`. */