@cosmicdrift/kumiko-server-runtime 0.365.1 → 0.367.0

package/dist/extra-routes-deps.d.ts

@@ -1,5 +1,6 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import type { Redis } from "ioredis";
 export type { SystemDispatchArgs } from "@cosmicdrift/kumiko-framework/api";
 export { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "@cosmicdrift/kumiko-framework/api";
@@ -15,6 +16,8 @@ export type SystemWireDeps = {
     /** Feature-registry — e.g. for plugin-lookups via
      *  `registry.getExtensionUsages("subscriptionProvider")`. */
     readonly registry: Registry;
+    /** Same contract as `ctx.metricsFor`: unregistered metric names no-op. */
+    readonly metricsFor: (featureName: string) => MetricsHandle;
     /** Writes through the /api/*-command-dispatcher (same idempotency/job
      *  hooks) as an auto-constructed SystemAdmin of the target tenant,
      *  WITHOUT the route's own access-check. Privilege-scope: SystemAdmin is

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

@@ -1,5 +1,6 @@
 import { type EmailVerificationOptions, type PasswordResetOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import { resolveSessionStore } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { type UnsubscribeLinkConfig } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
@@ -30,6 +31,8 @@ export declare function buildBootExtraContext(opts: {
     readonly deliverQueuedInline?: boolean;
     /** Receives redacted delivery failures; without it they go to the console. */
     readonly log?: Logger;
+    /** Signs `unsubscribe: true` notifications' mail links; see runProdApp `unsubscribe`. */
+    readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 }): Record<string, unknown>;
 /** Die Auth-Felder die resolveAuthMail liest/normalisiert — beide
  *  App-Auth-Typen (prod + dev) erfüllen das strukturell. */

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

@@ -60,6 +60,7 @@ function buildDeliveryNotifyFactory(opts) {
         ...(opts.escapeHatchAuditSink && { escapeHatchAuditSink: opts.escapeHatchAuditSink }),
         ...(opts.log && { log: opts.log }),
         ...(opts.tenantUserIdsQuery && { tenantUserIdsQuery: opts.tenantUserIdsQuery }),
+        ...(opts.unsubscribeLinks && { unsubscribeLinks: opts.unsubscribeLinks }),
         ...(configAccessorFactory && {
             tenantConfigFor: (tenantId) => {
                 const systemUser = createSystemUser(tenantId);
@@ -147,6 +148,7 @@ export function buildBootExtraContext(opts) {
                 ...(hasTenantFeature && { tenantUserIdsQuery: TenantQueries.resolveUserIds }),
                 configResolver: bootConfigResolver,
                 deliverQueuedInline: opts.deliverQueuedInline,
+                unsubscribeLinks: opts.unsubscribeLinks,
             }),
         }),
         // Top-level provider so feature jobs (secrets rotate, config reencrypt)

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

@@ -1,6 +1,7 @@
 /// <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 UnsubscribeLinkConfig } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { type ExtraRouteDefinition, type KumikoServeEnv, type PostAuthLandingResolver, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { type EffectiveFeaturesResolver, type FeatureDefinition, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
@@ -8,12 +9,13 @@ import { type AllInOneEntrypoint, type ApiEntrypoint } from "@cosmicdrift/kumiko
 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 { ObservabilityOptions, ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
+import { type ObservabilityOptions, type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery } from "@cosmicdrift/kumiko-headless/apex";
 import { Redis } from "ioredis";
 import { type SystemWireDeps } from "./extra-routes-deps.js";
 import { type SecurityHeadersOption } from "./security-headers.js";
+import { type SeedCreateFileRef } from "./seed-dispatcher.js";
 export { buildBunServeOptions } from "./bun-serve-options.js";
 export { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.js";
 export { staticCachePolicy } from "./run-prod-app-static-files.js";
@@ -175,6 +177,9 @@ export type ProdSeedFn = (deps: {
     db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
     registry: import("@cosmicdrift/kumiko-framework/engine").Registry;
     dispatcher: import("@cosmicdrift/kumiko-framework/pipeline").Dispatcher;
+    /** Stores bytes as a fileRef of `tenantId` (same validation and storage
+     *  layout as POST /files) without a helper write handler. */
+    createFileRef: SeedCreateFileRef;
 }) => Promise<void>;
 /** Boot-Time-Deps die `extraContext` + `anonymousAccess` Factories als
  *  Argument bekommen. Closure dann in der returned Config (z.B. ein
@@ -392,6 +397,22 @@ export type RunProdAppOptions = {
      *  inside buildServer, right after the r.httpRoute loop, before seeds
      *  (kumiko-framework#3050). */
     readonly extraRoutes?: readonly ExtraRouteDefinition[];
+    /** Framework-managed unsubscribe links. Mounts `createUnsubscribeRoutes({ secret })` and makes
+     *  delivery sign `data.unsubscribeUrl` (path `DELIVERY_UNSUBSCRIBE_PATH`) for every email
+     *  notification declared with `unsubscribe: true`, for user and `route` recipients; a link the
+     *  caller put into `data.unsubscribeUrl` wins. `secret` must be dedicated (≥32 chars), not the
+     *  session JWT secret. Links point at the origin of `auth.publicOrigin`, then `auth.mail.baseUrl`,
+     *  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,
+     *  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`. */
+    readonly unsubscribe?: {
+        readonly secret: string;
+        readonly tenantOrigin?: UnsubscribeLinkConfig["tenantOrigin"];
+    };
     /** Hook for app-wired co-running components that need the system-write
      *  dispatcher (e.g. wiring a webhook plugin's system-scoped secrets, or
      *  starting a co-running supervisor) — runs after buildServer, before

package/dist/run-prod-app.js

@@ -43,12 +43,13 @@ import { AuthErrors, AuthHandlers, AuthQueries, } from "@cosmicdrift/kumiko-bund
 import { seedAdminGuarded, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
 import { EXT_SESSION_STORE, EXT_TOKEN_VERIFIER, resolveAnonymousAccessFromRegistry, resolveTokenVerifier, } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { AUTH_MFA_FEATURE, AuthMfaHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { createUnsubscribeRoutes, } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { PAT_FEATURE, patRateLimitFromFeature, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { SECRETS_MASTER_KEK_ENV_KEYS } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
-import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
+import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, publicOriginOf, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
 import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
@@ -57,7 +58,9 @@ import { KumikoBootError, kmsSlotsOf, parseEnv, withOptionalEnvKeys, } from "@co
 import { renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
 import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
+import { createMetricsForFactory, } from "@cosmicdrift/kumiko-framework/observability";
 import { createDispatcher, createEntityCache, createEventDedup, createIdempotencyGuard, flushEscapeHatchAudits, } from "@cosmicdrift/kumiko-framework/pipeline";
 import { createRedisCacheSyncBus, redisClientOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
@@ -72,10 +75,11 @@ import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-se
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features.js";
 import { makeDispatchSystemWrite } from "./extra-routes-deps.js";
 import { assertPiiBootInvariants } from "./pii-boot-gate.js";
-import { resolveAuthPublicOrigin } from "./resolve-auth-public-origin.js";
+import { APP_BASE_URL_ENV, resolveAuthPublicOrigin } from "./resolve-auth-public-origin.js";
 import { addConfigAccessorFactory, buildBootExtraContext, buildProdSessionAuth, loggerFromExtraContext, resolveAuthMail, wireProdPatAutoRevoke, } from "./run-prod-app-boot-context.js";
 import { buildStaticFallback } from "./run-prod-app-static-files.js";
 import { withSecurityHeaders } from "./security-headers.js";
+import { makeSeedCreateFileRef, withSeedErrorContext, } from "./seed-dispatcher.js";
 import { assertSessionBootInvariants } from "./session-boot-gate.js";
 import { shouldWireProdSessions } from "./session-wiring.js";
 import { stripNoRouteMatchHeader } from "./try-hono-first.js";
@@ -287,6 +291,27 @@ export async function runProdApp(options) {
             console.warn(message);
         })
         : undefined;
+    const unsubscribeBaseUrl = options.unsubscribe
+        ? publicOriginOf(effectiveAuth?.publicOrigin ??
+            effectiveAuth?.mail?.baseUrl ??
+            envSource[APP_BASE_URL_ENV] ??
+            "")
+        : undefined;
+    if (options.unsubscribe && unsubscribeBaseUrl === undefined) {
+        createFallbackLogger("runProdApp").warn(`unsubscribe is enabled but no valid public app URL is known (auth.publicOrigin, auth.mail.baseUrl or ${APP_BASE_URL_ENV}), so mails get no unsubscribe link.`);
+    }
+    const unsubscribeLinks = options.unsubscribe && unsubscribeBaseUrl !== undefined
+        ? {
+            secret: options.unsubscribe.secret,
+            baseUrl: unsubscribeBaseUrl,
+            ...(options.unsubscribe.tenantOrigin !== undefined && {
+                tenantOrigin: options.unsubscribe.tenantOrigin,
+            }),
+        }
+        : undefined;
+    const unsubscribeRoutes = options.unsubscribe
+        ? createUnsubscribeRoutes({ secret: options.unsubscribe.secret })
+        : [];
     // 3. Feature registry. Auth-mode auto-mixes config/user/tenant/auth-email-
     //    password via composeFeatures — same source-of-truth as runDevApp
     //    AND the per-app drizzle-Schema-Generator, so Migration und Runtime
@@ -451,6 +476,7 @@ export async function runProdApp(options) {
         crypto: bootCrypto,
         ...(options.kms && { kms: options.kms }),
         ...(bootLogger && { log: bootLogger }),
+        ...(unsubscribeLinks && { unsubscribeLinks }),
     });
     const extraContext = {
         ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
@@ -533,7 +559,9 @@ export async function runProdApp(options) {
         ...(options.rateLimit && { rateLimit: options.rateLimit }),
         ...(trustedProxyHops !== undefined && { trustedProxyHops }),
         ...(options.errorDocs && { errorDocs: options.errorDocs }),
-        ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
+        ...((options.extraRoutes || options.unsubscribe) && {
+            extraRoutes: [...(options.extraRoutes ?? []), ...unsubscribeRoutes],
+        }),
         ...(effectiveAuth && {
             auth: {
                 membershipQuery: TenantQueries.memberships,
@@ -685,6 +713,7 @@ export async function runProdApp(options) {
             db,
             redis,
             registry,
+            metricsFor: createMetricsForFactory(entrypoint.observability.meter),
             dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
         });
     }
@@ -701,12 +730,20 @@ export async function runProdApp(options) {
         db,
         ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
     });
-    const seedDispatcher = (options.seeds?.length ?? 0) > 0 || options.seedsDir !== undefined
-        ? createDispatcher(registry, withFileProviderResolver(registry, { db, redis, entityCache, registry, ...extraContext }, cacheSync))
+    const hasSeeds = (options.seeds?.length ?? 0) > 0 || options.seedsDir !== undefined;
+    const seedContext = hasSeeds
+        ? withFileProviderResolver(registry, { db, redis, entityCache, registry, ...extraContext }, cacheSync)
+        : undefined;
+    const seedDispatcher = seedContext
+        ? withSeedErrorContext(createDispatcher(registry, seedContext, {
+            ...baseEntrypointOptions.dispatcherOptions,
+            ...(entrypoint.mode === "all-in-one" && { jobRunner: entrypoint.jobRunner }),
+        }))
         : undefined;
-    if (seedDispatcher) {
+    if (seedDispatcher && seedContext) {
+        const createFileRef = makeSeedCreateFileRef({ db, registry, context: seedContext });
         for (const seed of options.seeds ?? []) {
-            await seed({ db, registry, dispatcher: seedDispatcher });
+            await seed({ db, registry, dispatcher: seedDispatcher, createFileRef });
         }
     }
     // ES-Operations / Seed-Migrations (Phase 1). Läuft NACH applyBootSeeds +

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

@@ -4,7 +4,7 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { EffectiveFeaturesResolver, FeatureDefinition, Registry, ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
 import type { WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
-import type { ObservabilityOptions, ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
+import { type ObservabilityOptions, type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import { type WorkerMetricsOptions, type WorkerMetricsServer } from "./boot/worker-metrics-server.js";

package/dist/run-worker-app.js

@@ -15,6 +15,7 @@
 // Container/Coolify sets the same env vars as runProdApp:
 //   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
+import { createMetricsForFactory, } from "@cosmicdrift/kumiko-framework/observability";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
 import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
 import { bootWorkerProcess, resolveWorkerEnvSource } from "./boot/worker-boot-core.js";
@@ -70,6 +71,7 @@ export async function runWorkerApp(options) {
             db,
             redis,
             registry,
+            metricsFor: createMetricsForFactory(entrypoint.observability.meter),
             dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
             lifecycle: entrypoint.lifecycle,
             ...(boot.secrets && { secrets: boot.secrets }),

package/dist/seed-dispatcher.d.ts

@@ -0,0 +1,11 @@
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type AppContext, type Registry, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { type CreatedFileRef, type CreateFileRefInput } from "@cosmicdrift/kumiko-framework/files";
+import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
+export type SeedCreateFileRef = (tenantId: TenantId, input: CreateFileRefInput) => Promise<WriteResult<CreatedFileRef>>;
+export declare function makeSeedCreateFileRef(deps: {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly context: AppContext;
+}): SeedCreateFileRef;
+export declare function withSeedErrorContext<D extends Pick<Dispatcher, "write">>(dispatcher: D): D;

package/dist/seed-dispatcher.js

@@ -0,0 +1,36 @@
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { createFileContext, createFileRefFromBytes, } from "@cosmicdrift/kumiko-framework/files";
+export function makeSeedCreateFileRef(deps) {
+    const { db, registry, context } = deps;
+    const fileResolver = context._fileProviderResolver;
+    return (tenantId, input) => createFileRefFromBytes({
+        db: createTenantDb(db, tenantId),
+        files: fileResolver
+            ? createFileContext(() => fileResolver(tenantId), tenantId)
+            : context.files,
+        registry,
+        user: createSystemUser(tenantId),
+    }, input);
+}
+// The dispatcher masks a thrown handler error as "internal error" and keeps the
+// cause only on a side channel; a seed has no HTTP client to protect, so the
+// handler name and cause message go into the message the seed caller sees.
+export function withSeedErrorContext(dispatcher) {
+    return {
+        ...dispatcher,
+        async write(type, payload, user, requestId) {
+            const result = await dispatcher.write(type, payload, user, requestId);
+            if (result.isSuccess || result.error.code !== "internal_error")
+                return result;
+            const cause = reraiseAsKumikoError(result.error).cause;
+            const causeMessage = cause instanceof Error ? cause.message : undefined;
+            const detail = causeMessage ? `${type}: ${causeMessage}` : type;
+            return {
+                isSuccess: false,
+                error: { ...result.error, message: `${result.error.message} (${detail})` },
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.365.1",
+  "version": "0.367.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -84,12 +84,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.365.1",
-    "@cosmicdrift/kumiko-framework": "0.365.1",
-    "@cosmicdrift/kumiko-headless": "0.365.1",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.365.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.365.1",
-    "@cosmicdrift/kumiko-types": "0.365.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.367.0",
+    "@cosmicdrift/kumiko-framework": "0.367.0",
+    "@cosmicdrift/kumiko-headless": "0.367.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.367.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.367.0",
+    "@cosmicdrift/kumiko-types": "0.367.0",
     "bun-types": "^1.3.13",
     "ioredis": "^5.10.1",
     "temporal-polyfill": "^0.3.2"