@cosmicdrift/kumiko-types 0.266.0 → 0.269.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.266.0",
+  "version": "0.269.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/define-handler.ts

@@ -126,6 +126,10 @@ export type StreamHandlerDefinition<
   readonly schema: TSchema;
   readonly access: AccessRule;
   readonly rateLimit?: RateLimitOption;
+  // Stream handlers can't reach db.global() (that gate is write-only), but
+  // they can still switch identity to SYSTEM via ctx.queryAs — this opts
+  // in, same contract as WriteHandlerDefinition.escapeHatch.
+  readonly escapeHatch?: EscapeHatchDeclaration;
   readonly handler: (
     query: QueryEvent<z.infer<TSchema>>,
     context: HandlerContext<TMap>,

package/src/feature.ts

@@ -488,7 +488,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     name: string,
     schema: TSchema,
     handler: StreamHandlerFn<z.infer<TSchema>>,
-    options: { access: AccessRule; rateLimit?: RateLimitOption },
+    options: {
+      access: AccessRule;
+      rateLimit?: RateLimitOption;
+      escapeHatch?: EscapeHatchDeclaration;
+    },
   ): HandlerRef;
 
   relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
@@ -501,7 +505,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): void;
 
   hook(type: "validation", target: RefOrRefs, fn: ValidationHookFn): void;
-  // escapeHatch grants this hook (not the handler) SYSTEM identity-switches — see system-identity-switch.ts.
+  // escapeHatch grants this hook (not the handler) identity-switches beyond its caller — see system-identity-switch.ts.
   hook(
     type: "preSave",
     target: RefOrRefs,

package/src/handlers.ts

@@ -52,6 +52,10 @@ export function isOpenToAllGranted(rule: AccessRule): boolean {
 
 // --- Pipeline User ---
 
+// Set only on a SessionUser the framework resolved internally for a
+// background read (ctx.queryAsMember) — such a principal never carries `sid`.
+export type SessionUserOrigin = "member-resolution";
+
 export type SessionUser = {
   // UUID-string so user.id threads through the event-store (aggregate-id) and
   // the projection tables (uuid PK) without casts. Auth middleware reads the
@@ -92,6 +96,7 @@ export type SessionUser = {
     readonly scopes: readonly string[];
     readonly allowedQns: readonly string[];
   };
+  readonly origin?: SessionUserOrigin;
 };
 
 // --- Claim Keys (r.claimKey declarations) ---
@@ -231,6 +236,9 @@ import type { Registry } from "./feature";
 import type { TenantId } from "./identifiers";
 import type { UncheckedSystemDb } from "./tenant-db-types";
 
+// The framework resolves the member internally, so no hand-built SessionUser reaches app code.
+export type MemberReader = (userId: string, qn: string, payload: unknown) => Promise<unknown>;
+
 // Minimal interface for job event triggers (framework-owned, concrete type in jobs/)
 export type JobRunnerRef = {
   handleEvent(
@@ -249,6 +257,9 @@ export type JobRunnerRef = {
 export type DispatchWriteRef = {
   readonly write: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
   readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  // Builds a tenant-scoped MemberReader — one per JobContext.queryAsMember
+  // caller (job-runner.ts lazily creates one per job run).
+  readonly createMemberReader: (tenantId: TenantId) => MemberReader;
 };
 
 // Priority levels for notifications
@@ -355,6 +366,9 @@ type SharedContextFields = {
   // hooks synchronously (kumiko-framework#1566). Absent outside a write
   // pipeline — callers fall back to immediate fire (fixture / no-tx paths).
   readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
+  // Present on HandlerContext/JobContext; hooks receive HandlerContext as
+  // AppContext, so it's optional here. See HandlerContext.queryAsMember.
+  readonly queryAsMember?: MemberReader;
 };
 
 // All optional — used at pipeline/system boundaries.
@@ -401,8 +415,9 @@ export type AppContext = SharedContextFields & {
 //   sharing the active tx + afterCommit queue. Field-access filters apply.
 //   ctx.queryAs / ctx.writeAs switch identity (e.g. SYSTEM for privileged
 //   lookups like "find user by email for auth" — system reads aren't filtered
-//   by field-access read rules). SYSTEM as the target is gated: reachable
-//   only from an r.systemScope() feature, a job, or a handler/hook that
+//   by field-access read rules). Any target other than the caller itself (or
+//   a subset of its roles) is gated: reachable only from an r.systemScope()
+//   feature, a job, or a handler/hook that
 //   declared { escapeHatch: { reason } } (system-identity-switch.ts).
 //
 // The design: handlers are the contract between features. Feature A requires
@@ -640,6 +655,10 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     userId: string,
     tenantId: TenantId,
   ) => Promise<ActiveMembershipResult>;
+
+  // Read-only principal without `sid`; needs the same grant as a SYSTEM queryAs
+  // (membership is resolved as SYSTEM), cached per handler invocation or job run.
+  readonly queryAsMember: MemberReader;
 };
 
 // Job execution: db + registry + systemUser + logging guaranteed, plus a
@@ -686,6 +705,9 @@ export type JobContext = SharedContextFields & {
   readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
   readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
   readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  // Tenant = the job's resolved tenant (may originate from payload.tenantId
+  // for tenant-less triggers, see _tenantId below). Ungated, like queryAs.
+  readonly queryAsMember: MemberReader;
   // Multi-trigger jobs (`on: [...]`) use this to tell which trigger fired —
   // undefined for cron/manual jobs. Mirrors AppContext.triggerName.
   readonly triggerName?: string;
@@ -1107,4 +1129,8 @@ export type StreamHandlerDef = {
   readonly handler: StreamHandlerFn;
   readonly access: AccessRule;
   readonly rateLimit?: RateLimitOption;
+  // Stream handlers can't reach db.global() (that gate is write-only), but
+  // they can still switch identity to SYSTEM via ctx.queryAs — this opts
+  // in, same contract as WriteHandlerDef.escapeHatch.
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };

package/src/tenant-db-types.ts

@@ -57,11 +57,16 @@ export type TenantDb = {
    * Underlying DbRunner. Framework-internal use (event-store, migrations) —
    * bypasses tenant-filter. Feature code uses the typed helpers above so the
    * automatic scoping stays intact.
-   * @deprecated Use `ctx.systemDb.unsafeRaw(reason)` or `db.global(table)`
-   * instead — both make the cross-tenant intent an explicit, named
+   * @deprecated Use `ctx.db.unsafeRaw(reason)` / `db.global(table)` (method-
+   * form) instead — both make the cross-tenant intent an explicit, named
    * declaration instead of a silent unfiltered escape hatch. Removal fw#2860.
    */
   readonly raw: DbRunner;
+  /**
+   * Unfiltered DbRunner escape hatch for handlers/hooks that declare `escapeHatch: { reason }`.
+   * Throws `AccessDeniedError` when ungranted, or `Error` when `reason` is empty.
+   */
+  unsafeRaw(reason: string): DbRunner;
   /**
    * Reach a "global" table with the tenant filter lifted — reads always work; writes
    * reject unless the write handler declared `escapeHatch: { reason }`. "tenant"-tenancy is a compile error here.
@@ -70,12 +75,12 @@ export type TenantDb = {
     table: TTable,
   ): GlobalTableDb<TTable>;
   selectMany<T = Record<string, unknown>>(
-    table: SchemaTable,
+    table: SchemaTable | EntityTableMeta,
     where?: WhereObject,
     options?: SelectOptions,
   ): Promise<readonly T[]>;
   fetchOne<T = Record<string, unknown>>(
-    table: SchemaTable,
+    table: SchemaTable | EntityTableMeta,
     where: WhereObject,
   ): Promise<T | undefined>;
   insertOne<T = Record<string, unknown>>(