@cosmicdrift/kumiko-framework 0.159.1 → 0.161.0

package/src/pipeline/dispatcher.ts

@@ -8,6 +8,7 @@ import { runBatch, unwrapSingle } from "./dispatch-batch";
 import { executeQuery } from "./dispatch-query";
 import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared";
 import { resolveAuthClaimsFn } from "./dispatch-shared";
+import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
@@ -52,6 +53,10 @@ export type Dispatcher = {
     requestId?: string,
   ): Promise<WriteResult>;
   query(type: HandlerType, payload: unknown, user: SessionUser): Promise<unknown>;
+  // AsyncGenerator, not Promise — gates (feature/rate-limit/access/
+  // validation) fire on the consumer's first `.next()` pull, not on this
+  // call, since they live inside the underlying async function*.
+  stream(type: HandlerType, payload: unknown, user: SessionUser): AsyncGenerator<unknown>;
   command(type: HandlerType, payload: unknown, user: SessionUser): Promise<void>;
   // Atomic multi-command write: all commands run in a single DB transaction.
   // On any failure, the transaction rolls back and afterCommit hooks do NOT fire.
@@ -114,6 +119,8 @@ export function createDispatcher(
 
     query: (typeOrRef, payload, user) => executeQuery(ctx, resolveType(typeOrRef), payload, user),
 
+    stream: (typeOrRef, payload, user) => executeStream(ctx, resolveType(typeOrRef), payload, user),
+
     async command(typeOrRef, payload, user) {
       const type = resolveType(typeOrRef);
       const batchResult = await runBatch(ctx, [{ type, payload }], user);

package/src/pipeline/multi-stream-apply-context.ts

@@ -1,50 +1,12 @@
+import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
 import type { DbRunner } from "../db/connection";
-import type {
-  AppendEventArgs,
-  AppendEventFn,
-  KumikoEventTypeMap,
-  Registry,
-  TenantId,
-  UnsafeAppendEventFn,
-} from "../engine/types";
-import { loadAggregate, loadAggregateAsOf, type StoredEvent } from "../event-store/event-store";
+import type { AppendEventArgs, AppendEventFn, Registry, TenantId } from "../engine/types";
+import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
 import { upcastStoredEvents } from "../event-store/upcaster";
 import type { FileContext } from "../files/file-handle";
 import { appendDomainEventCore } from "./append-event-core";
 
-// Minimal, read+write surface handed to a MultiStreamProjection's apply()
-// when it needs to produce follow-up events (saga / process-manager
-// pattern). Keeps the MSP feature-decoupled: applies don't reach into
-// handler-bridge (no query/write/writeAs), they just read the aggregate
-// stream and append new events — Marten's session scope for projections.
-//
-// TMap propagates the strict event-type-map (see HandlerContext). Default
-// matches the global KumikoEventTypeMap; runtime-pluggable callers route
-// through unsafeAppendEvent.
-export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
-  // Append a domain event onto an aggregate stream in the CURRENT tx.
-  // Schema-validated, archive-guarded, stream-version derived. Metadata
-  // inherits from the triggering event (correlationId) + requestContext
-  // (causationId is already set to the triggering event.id by the
-  // dispatcher wrap). Strict against KumikoEventTypeMap — same contract
-  // as HandlerContext.appendEvent (compile-time-validated payload).
-  readonly appendEvent: AppendEventFn<TMap>;
-  // Escape hatch for runtime-pluggable events without compile-time
-  // augmentation. Same runtime semantics; type-surface is `payload: unknown`.
-  readonly unsafeAppendEvent: UnsafeAppendEventFn;
-  // Read an aggregate stream — useful when a saga needs to inspect the
-  // current state of a different aggregate before deciding what to emit.
-  readonly loadAggregate: (
-    aggregateId: string,
-    options?: { readonly asOf?: Temporal.Instant },
-  ) => Promise<readonly StoredEvent[]>;
-  // Binary storage handle factory, mirrors AppContext.files. Present when
-  // the app booted with `files.storageProvider`; undefined otherwise.
-  // Post-processing MSPs (resize, EXIF-strip, virus-scan) read bytes via
-  // `ctx.files.ref(payload.storageKey).read()` and write derivates via
-  // `.derive("thumb").write(...)` — binaries never ride through events.
-  readonly files?: FileContext;
-};
+export type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
 
 export type MultiStreamApplyContextDeps = {
   readonly registry: Registry;

package/src/rate-limit/resolver.ts

@@ -1,3 +1,8 @@
+import type {
+  RateLimitConfig,
+  RateLimitDecision,
+  RateLimitResolver,
+} from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type Redis from "ioredis";
 import { RateLimitError } from "../errors";
 import { RedisKeys } from "../pipeline/redis-keys";
@@ -108,36 +113,11 @@ end
 return { math.floor(tokens), retryAfterMs }
 `;
 
-export type RateLimitDecision = {
-  readonly allowed: boolean;
-  readonly limit: number;
-  readonly remaining: number;
-  readonly retryAfterSeconds: number;
-  readonly windowSeconds: number;
-  readonly resetAt: Temporal.Instant;
-};
-
-export type RateLimitConfig = {
-  readonly limit: number;
-  readonly windowSeconds: number;
-  readonly cost?: number;
-};
-
-export type RateLimitResolver = {
-  // Atomic check + deduct. Returns the decision and current bucket state
-  // — caller decides whether to throw RateLimitError or proceed.
-  check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
-
-  // Convenience: throws RateLimitError when blocked. Useful inside the
-  // dispatcher / middleware code-paths where the failure shape is fixed.
-  enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
-
-  // Read-only inspection: returns the same shape as check() but never
-  // mutates the bucket — no token deduction, no refill-timestamp update.
-  // Use for ops/status queries (e.g. "kumiko rl status user:42") that
-  // must observe the bucket without disturbing it.
-  peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
-};
+export type {
+  RateLimitConfig,
+  RateLimitDecision,
+  RateLimitResolver,
+} from "@cosmicdrift/kumiko-types/rate-limit-types";
 
 export type RateLimitResolverOptions = {
   readonly redis: Redis;

package/src/secrets/envelope-cipher.ts

@@ -3,12 +3,15 @@
 // kekVersion inside makes every value rotatable via the MasterKeyProvider
 // keyring.
 
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
 import { InternalError } from "../errors/classes";
 import type { DekCache } from "./dek-cache";
 import { createDekCache, withDekCache } from "./dek-cache";
 import { decryptValue, encryptValue } from "./envelope";
 import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./stored-envelope";
-import type { KeyScope, MasterKeyProvider } from "./types";
+import type { MasterKeyProvider } from "./types";
+
+export type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
 
 export type EnvelopeCipherOptions = {
   // Shared DEK cache — pass the app-wide instance so config/entity reads
@@ -16,11 +19,6 @@ export type EnvelopeCipherOptions = {
   readonly dekCache?: DekCache;
 };
 
-export type EnvelopeCipher = {
-  encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
-  decrypt(stored: string, scope?: KeyScope): Promise<string>;
-};
-
 export function createEnvelopeCipher(
   provider: MasterKeyProvider,
   opts: EnvelopeCipherOptions = {},

package/src/secrets/types.ts

@@ -1,177 +1,2 @@
-// Envelope Encryption types. Separating DEK (per-value) from KEK (central)
-// is what makes key rotation cheap: on rotation we only re-wrap the small
-// encryptedDek, never touch the ciphertext.
-
-import type { TenantId } from "../engine";
-
-// Plaintext-secret wrapper (branded). Carries the actual string internally
-// but the nominal typing stops it from landing in an HTTP response by
-// accident — a response-serializer guard + the reveal() cost make the leak
-// intentional. Framework code that sees `Secret<string>` knows the caller
-// has already gone through the audited ctx.secrets.get path.
-//
-// The brand is a real (non-registered) Symbol so it exists at runtime for
-// isSecret() without clashing with user-land symbols of the same name.
-const SecretBrand: unique symbol = Symbol("kumiko.secret");
-
-export type Secret<T = string> = {
-  readonly [SecretBrand]: true;
-  readonly reveal: () => T;
-};
-
-// Implementation helper — bundled-features uses this to wrap a plaintext after
-// decryption. Kept in the framework so both sides share one canonical brand.
-export function createSecret<T>(value: T): Secret<T> {
-  return {
-    [SecretBrand]: true as const,
-    reveal: () => value,
-  };
-}
-
-// True for any object carrying the Secret brand. Used by the response guard
-// to reject leaks before serialization.
-export function isSecret(v: unknown): v is Secret<unknown> {
-  return typeof v === "object" && v !== null && SecretBrand in v;
-}
-
-// --- Compile-time response guard (R6) --------------------------------------
-//
-// ContainsSecret<T> is `true` only when a Secret<> is DEFINITELY present
-// somewhere in T. The handler-registration guard (defineWriteHandler/
-// defineQueryHandler) turns a `true` into a compile error — the static twin of
-// assertNoSecretLeak's runtime walk.
-//
-// Biased to `false`: anything it cannot inspect — a bare generic type param (a
-// handler generic over its response), `unknown`/`any`, `never` — resolves to
-// `false` = allowed, with the runtime guard as the backstop. The alternative
-// (default-to-leak) false-flags every legitimate generic-over-response handler.
-//
-// Branch order is load-bearing: never/unknown/any first (uninspectable), then
-// Secret, then primitives (covers branded primitives like TenantId without
-// enumerating them), then the SafeLeaf allowlist (opaque class instances that
-// blind `{ [K in keyof T] }` recursion would mangle — the type-level mirror of
-// leak-guard.ts skipping non-plain objects), then arrays, then a "does any
-// field contain a secret" fold over plain objects.
-type Primitive = string | number | boolean | bigint | symbol | null | undefined;
-
-// Opaque built-in leaves a response legitimately carries; never recurse into
-// them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
-// Map/Set (556/2): `keyof Map<K,V>` yields method names, not V, so these
-// already fell through to `false` via the object-mapped-type branch — listed
-// explicitly here so the compile-time treatment matches leak-guard.ts's
-// runtime `instanceof Map`/`instanceof Set` branch (walk entries separately)
-// instead of looking like an oversight.
-type SafeLeaf =
-  | Date
-  | RegExp
-  | Temporal.Instant
-  | Temporal.ZonedDateTime
-  | Temporal.PlainDate
-  | Temporal.PlainDateTime
-  | Temporal.PlainTime
-  | Temporal.PlainYearMonth
-  | Temporal.PlainMonthDay
-  | Temporal.Duration
-  | Map<unknown, unknown>
-  | Set<unknown>;
-
-export type ContainsSecret<T> = [T] extends [never]
-  ? false
-  : unknown extends T
-    ? false
-    : T extends Secret<unknown>
-      ? true
-      : T extends Primitive
-        ? false
-        : T extends SafeLeaf
-          ? false
-          : T extends readonly (infer U)[]
-            ? ContainsSecret<U>
-            : T extends object
-              ? true extends { [K in keyof T]-?: ContainsSecret<T[K]> }[keyof T]
-                ? true
-                : false
-              : false;
-
-// Per-read audit context. Populated by requireSecretsContext() wrapper so
-// handlers don't need to pass userId/handlerName manually on every call.
-// Undefined for framework-internal reads (rotation job, tests) — the audit
-// table stays a "who touched this credential" log, not a crash-report sink.
-export type SecretAuditContext = {
-  readonly userId: string;
-  readonly handlerName: string;
-};
-
-// Feature code can pass either the raw qualified-name string or a typed
-// handle returned by r.secret. The handle form is safer — renaming the
-// r.secret call updates all references through the import graph.
-export type SecretKeyRef = string | { readonly name: string };
-
-// The ctx.secrets contract. Concrete implementation lives in bundled-features
-// (createSecretsContext) where the DB and MasterKeyProvider are known. This
-// lean interface is what the framework's HandlerContext carries so engine
-// code can talk about it without pulling in bundled-features.
-export interface SecretsContext {
-  get(
-    tenantId: TenantId,
-    key: SecretKeyRef,
-    auditCtx?: SecretAuditContext,
-  ): Promise<Secret<string> | undefined>;
-  // Metadata-only existence probe: no decryption, no read-audit event.
-  // For readiness checks — use get() when the value itself is needed.
-  has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
-  set(
-    tenantId: TenantId,
-    key: SecretKeyRef,
-    value: string,
-    opts?: { redact?: (plaintext: string) => string; hint?: string; updatedBy?: string },
-  ): Promise<void>;
-  delete(tenantId: TenantId, key: SecretKeyRef, opts?: { deletedBy?: string }): Promise<boolean>;
-}
-
-export type Envelope = {
-  // AES-256-GCM ciphertext of the plaintext, keyed with a DEK.
-  readonly ciphertext: Buffer;
-  // GCM nonce (12 bytes). Generated fresh per encryption.
-  readonly iv: Buffer;
-  // GCM auth tag (16 bytes). Guarantees the ciphertext wasn't tampered.
-  readonly authTag: Buffer;
-  // DEK wrapped with the current KEK. Decryption needs provider.unwrapDek
-  // with the kekVersion to recover the DEK.
-  readonly encryptedDek: Buffer;
-  // Which KEK version was used to wrap the DEK. On rotation, rows with old
-  // versions still decrypt — the provider keeps a keyring of historical KEKs.
-  readonly kekVersion: number;
-};
-
-// BYOK hook: callers pass the tenant a value belongs to; a per-tenant-KMS
-// provider keys its wrap/unwrap on it. EnvMasterKeyProvider (app-wide
-// keyring) ignores it — the param exists so the contract doesn't have to
-// break when a tenant-scoped provider ships.
-export type KeyScope = {
-  readonly tenantId?: TenantId;
-};
-
-// The contract a KEK backend must fulfil. The framework sees only this
-// interface; concrete implementations live in separate packages
-// (@cosmicdrift/kumiko-secrets-vault, @cosmicdrift/kumiko-secrets-aws-kms, ...). The default is
-// EnvMasterKeyProvider which reads keys from environment variables.
-export interface MasterKeyProvider {
-  // Wrap a fresh DEK with the current KEK. Returns the wrapped bytes + the
-  // KEK version used — the version ends up in the Envelope so decryption
-  // later knows which KEK to ask for.
-  wrapDek(dek: Buffer, scope?: KeyScope): Promise<{ encryptedDek: Buffer; kekVersion: number }>;
-
-  // Unwrap a previously-wrapped DEK. During rotation the provider must
-  // accept older kekVersion values (2-version window minimum), otherwise
-  // old rows become unreadable.
-  unwrapDek(encryptedDek: Buffer, kekVersion: number, scope?: KeyScope): Promise<Buffer>;
-
-  // Which KEK version new wraps use. Rotation flips this to a new value
-  // and older-version reads continue to work until rows are re-wrapped.
-  currentVersion(): number;
-
-  // Health check: can the provider talk to its backend? Used by
-  // /health/ready. Cheap probe, no KEK material read.
-  isAvailable(): Promise<boolean>;
-}
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/secrets-types";

package/src/stack/request-helper.ts

@@ -1,4 +1,5 @@
 import type { Hono } from "hono";
+import type { SessionCreator } from "../api/auth-routes";
 import type { JwtHelper } from "../api/jwt";
 import type { SessionUser } from "../engine/types";
 
@@ -98,9 +99,25 @@ export type RequestHelper = {
   ) => Promise<Response>;
 };
 
-export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
+export type RequestHelperOptions = {
+  // When sessionChecker is wired (sessions feature), JWTs without jti are
+  // rejected as no_sid. Seed/test helpers that only jwt.sign(user) need a
+  // live sid — create one via the same sessionCreator login uses (#1372).
+  readonly sessionCreator?: SessionCreator;
+};
+
+export function createRequestHelper(
+  app: Hono,
+  jwt: JwtHelper,
+  options: RequestHelperOptions = {},
+): RequestHelper {
   async function authHeader(user: SessionUser): Promise<Record<string, string>> {
-    const token = await jwt.sign(user);
+    let forJwt = user;
+    if (options.sessionCreator && !user.sid) {
+      const sid = await options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
+      forJwt = { ...user, sid };
+    }
+    const token = await jwt.sign(forJwt);
     return { Authorization: `Bearer ${token}` };
   }
 

package/src/stack/test-stack.ts

@@ -124,6 +124,16 @@ export type TestStackOptions = {
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").ServerOptions["anonymousAccess"]);
+  /** Optional post-factory enricher (e.g. merge auth-foundation tenant
+   *  providers). Keeps framework free of a bundled-features dependency. */
+  enrichAnonymousAccess?: (
+    base: import("../api/server").ServerOptions["anonymousAccess"] | undefined,
+    deps: {
+      registry: Registry;
+      // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
+      db: any;
+    },
+  ) => Promise<import("../api/server").ServerOptions["anonymousAccess"] | undefined>;
   /** Opt-in JobRunner wired into ctx.jobRunner and merged into
    *  dispatcherOptions so event-triggered jobs enqueue on commit — mirrors
    *  the prod entrypoint's `buildJobRunnerWithHook`. Unlike prod (which
@@ -382,19 +392,24 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
         : {}),
       ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
       ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
-      ...(options.anonymousAccess
-        ? {
-            anonymousAccess:
-              typeof options.anonymousAccess === "function"
-                ? options.anonymousAccess({
-                    registry,
-                    db: testDb.db,
-                    sseBroker,
-                    redis: testRedis.redis,
-                  })
-                : options.anonymousAccess,
-          }
-        : {}),
+      ...(await (async () => {
+        const baseAnon =
+          typeof options.anonymousAccess === "function"
+            ? options.anonymousAccess({
+                registry,
+                db: testDb.db,
+                sseBroker,
+                redis: testRedis.redis,
+              })
+            : options.anonymousAccess;
+        const resolvedAnon = options.enrichAnonymousAccess
+          ? await options.enrichAnonymousAccess(baseAnon, {
+              registry,
+              db: testDb.db,
+            })
+          : baseAnon;
+        return resolvedAnon ? { anonymousAccess: resolvedAnon } : {};
+      })()),
     });
 
     const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
@@ -406,7 +421,11 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // timer loop call start() again (idempotent) after setup.
     if (eventDispatcher) await eventDispatcher.ensureRegistered();
 
-    const http = createRequestHelper(server.app, server.jwt);
+    const http = createRequestHelper(server.app, server.jwt, {
+      ...(options.authConfig?.sessionCreator !== undefined && {
+        sessionCreator: options.authConfig.sessionCreator,
+      }),
+    });
 
     return {
       app: server.app,

package/src/time/tz-context.ts

@@ -13,65 +13,18 @@
 // `tenant` + `user` sind die TZ-Defaults für den aktuellen Request. Aktueller
 // Stand: beide default auf "UTC" — sobald tenant.timezone +
 // user.timezone Felder existieren, lese ich sie aus dem Request-Context.
+//
+// Die reinen Type-Contracts (TzContext, TzContextOptions, LocatedTimestampJson)
+// leben in @cosmicdrift/kumiko-types/tz-context — hier nur die Factories.
 
-import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
+import type { TzContext, TzContextOptions } from "@cosmicdrift/kumiko-types/tz-context";
 import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 
-// JSON-Form für Wall-Clock+TZ — siehe createLocatedTimestampField() in
-// engine/factories.ts. Zwei Felder, idiotensicher.
-export type LocatedTimestampJson = {
-  /** Wall-Clock-ISO ohne Offset, z.B. "2026-04-03T10:00:00" */
-  readonly at: string;
-  /** IANA-Zone, z.B. "Europe/Lisbon" */
-  readonly tz: string;
-};
-
-export type TzContext = {
-  /** Default-TZ des Mandanten (aus tenant.timezone, default "UTC"). */
-  readonly tenant: string;
-  /** Anzeige-TZ des aktuellen Users (User-Profil-Override, fallback Tenant). */
-  readonly user: string;
-
-  /** Aktueller Moment als UTC-Instant. */
-  now(): Temporal.Instant;
-  /** Aktueller Moment als ZonedDateTime in der gewünschten Zone. */
-  nowIn(tz: string): Temporal.ZonedDateTime;
-
-  /** Heutiges Kalender-Datum in der gewünschten Zone. */
-  today(tz: string): Temporal.PlainDate;
-  /** Tagesgrenzen (00:00 bis 24:00 nächster Tag) als UTC-Instants — für DB-Range-Queries. */
-  todayRange(tz: string): { readonly start: Temporal.Instant; readonly end: Temporal.Instant };
-
-  /** Wall-Clock-String + IANA-Zone → ZonedDateTime. */
-  parse(wallClock: string, tz: string): Temporal.ZonedDateTime;
-
-  /** ZonedDateTime → UTC-Instant. */
-  toInstant(zdt: Temporal.ZonedDateTime): Temporal.Instant;
-
-  /** ZonedDateTime → JSON-Pair { at, tz } (API-Boundary). */
-  toLocatedJson(zdt: Temporal.ZonedDateTime): LocatedTimestampJson;
-
-  /** JSON-Pair { at, tz } → ZonedDateTime (Wall-Clock + IANA). */
-  fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
-
-  /** Geo-Koordinaten → IANA-Zone via konfiguriertem GeoTzProvider.
-   *  Wirft wenn kein Provider konfiguriert ist (v1-Default). */
-  fromCoordinates(coords: GeoCoordinates): Promise<string>;
-  /** Postadresse → IANA-Zone via GeoTzProvider. Wirft wenn kein Provider
-   *  konfiguriert ist ODER der Provider kein fromAddress unterstützt (der
-   *  Offline-lat/lng-Provider tut das nicht). */
-  fromAddress(address: GeoAddress): Promise<string>;
-};
-
-export type TzContextOptions = {
-  /** Tenant-Default-TZ. Default "UTC" wenn nicht gesetzt. */
-  readonly tenant?: string;
-  /** User-Override. Default = tenant. */
-  readonly user?: string;
-  /** Optionaler Geo→Zone-Adapter für ctx.tz.fromCoordinates / fromAddress.
-   *  Ohne Provider werfen diese Methoden. */
-  readonly geoTz?: GeoTzProvider;
-};
+export type {
+  LocatedTimestampJson,
+  TzContext,
+  TzContextOptions,
+} from "@cosmicdrift/kumiko-types/tz-context";
 
 /**
  * Factory: erzeugt einen TzContext für den aktuellen Request.