@cosmicdrift/kumiko-framework 0.266.0 → 0.269.0

package/src/engine/boot-validator/global-tenancy.ts

@@ -0,0 +1,17 @@
+import type { FeatureDefinition } from "../types";
+
+// Boot-time twin of event-store-executor-context.ts's buildExecutorContext check —
+// surfaces the systemStream invariant once across all features before any dispatch.
+export function validateGlobalTenancyEntities(features: readonly FeatureDefinition[]): void {
+  for (const feature of features) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      if (entity.tenancy === "global" && entity.systemStream !== true) {
+        throw new Error(
+          `Feature "${feature.name}" entity "${entityName}": tenancy: "global" entities must ` +
+            "also declare systemStream: true — a global aggregate's event stream must live on " +
+            "the system tenant, not the creating tenant's.",
+        );
+      }
+    }
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -36,6 +36,7 @@ import {
 } from "./entity-handler";
 import { validateEntityListScreens } from "./entity-list-screens";
 import { validateGdprStoragePersistence } from "./gdpr-storage";
+import { validateGlobalTenancyEntities } from "./global-tenancy";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import {
   collectKnownRoles,
@@ -238,6 +239,7 @@ export function validateBoot(
   validateRelatedListSectionQueries(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
+  validateGlobalTenancyEntities(features);
   validateFeatureBootChecks(features);
 
   if (hasEncryptedFields) {

package/src/engine/feature-entity-handlers.ts

@@ -228,7 +228,11 @@ export function buildEntityHandlerMethods<TName extends string>(
       nameOrDef: string | StreamHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
       handler?: StreamHandlerFn<z.infer<TSchema>>,
-      options?: { access: AccessRule; rateLimit?: RateLimitOption },
+      options?: {
+        access: AccessRule;
+        rateLimit?: RateLimitOption;
+        escapeHatch?: EscapeHatchDeclaration;
+      },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
         const def = nameOrDef;
@@ -239,6 +243,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           handler: def.handler as StreamHandlerFn, // @cast-boundary engine-bridge
           access: def.access,
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
         };
         return { name: def.name };
       }
@@ -249,6 +254,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         handler: inline.handler as StreamHandlerFn, // @cast-boundary engine-bridge
         access: inline.options.access,
         ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
+        ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
       };
       return { name: nameOrDef };
     },

package/src/engine/feature-ui-extensions.ts

@@ -1,5 +1,5 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
-import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
+import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { LifecycleHookTypes } from "./constants";
 import type { FeatureBuilderState } from "./feature-builder-state";
 import { resolveName } from "./handler-helpers";
@@ -143,7 +143,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       const wrapped: LifecycleHookFn | ValidationHookFn =
         type === "validation"
           ? fn
-          : bindHookIdentitySwitchGrant(fn as LifecycleHookFn, hookLabel, options?.escapeHatch); // @cast-boundary engine-bridge
+          : bindHookEscapeHatchGrant(fn as LifecycleHookFn, hookLabel, options?.escapeHatch); // @cast-boundary engine-bridge
 
       // Entity-wide target ("all write/query handlers of this entity") —
       // replaces the old r.entityHook(type, entity, fn).

package/src/engine/index.ts

@@ -4,6 +4,7 @@ export { hasAccess } from "./access";
 export {
   isPrincipalStatusPlugin,
   isTenantLifecycleStatusPlugin,
+  type PrincipalProfile,
   type PrincipalStatus,
   type PrincipalStatusPlugin,
   TENANT_TEARDOWN_STATUSES,
@@ -410,6 +411,7 @@ export type {
   ListSortSpec,
   LongTextFindability,
   ManyToManyRelation,
+  MemberReader,
   MetricNavigate,
   MetricSpec,
   MspErrorMode,
@@ -478,6 +480,7 @@ export type {
   SecretsEditSection,
   SelectFieldDef,
   SessionUser,
+  SessionUserOrigin,
   StreamHandlerDef,
   StreamHandlerFn,
   Subscribe,

package/src/engine/registry-validate.ts

@@ -1,5 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
-import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
+import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
   RegistryState,
@@ -126,10 +126,10 @@ export function applyExtensionUsages(state: RegistryState): void {
     // RegistrarExtensionRegistration and use that here.
     const extOwner = "*";
     // Extensions have no declaration site for escapeHatch, so SYSTEM is always denied
-    // (system-identity-switch.ts) — bindHookIdentitySwitchGrant(..., undefined) below.
+    // (system-identity-switch.ts) — bindHookEscapeHatchGrant(..., undefined) below.
     if (ext.hooks) {
       if (ext.hooks.postSave) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.postSave,
           `postSave hook of extension "${usage.extensionName}"`,
           undefined,
@@ -143,7 +143,7 @@ export function applyExtensionUsages(state: RegistryState): void {
         state.entityPostSaveHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.preDelete) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.preDelete,
           `preDelete hook of extension "${usage.extensionName}"`,
           undefined,
@@ -157,7 +157,7 @@ export function applyExtensionUsages(state: RegistryState): void {
         state.entityPreDeleteHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.postDelete) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.postDelete,
           `postDelete hook of extension "${usage.extensionName}"`,
           undefined,
@@ -172,7 +172,7 @@ export function applyExtensionUsages(state: RegistryState): void {
       }
       // preSave on extensions: store as handler hook for all CRUD handlers of this entity
       if (ext.hooks.preSave) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.preSave,
           `preSave hook of extension "${usage.extensionName}"`,
           undefined,

package/src/engine/steps/call-feature.ts

@@ -1,6 +1,6 @@
 // r.step.callFeature — typed sub-command on another Kumiko feature.
 // Tier-2: requires r.requires.step("callFeature"). Sync (no dispatcher).
-// Cross-tenant via opts.as (Sysadmin-role-checked at the dispatcher layer).
+// opts.as other than the caller itself needs escapeHatch on the handler (system-identity-switch.ts).
 
 import { defineStep } from "../define-step";
 import type { SessionUser } from "../types";

package/src/engine/types/index.ts

@@ -171,6 +171,7 @@ export type {
   HandlerRef,
   JobContext,
   JobRunnerRef,
+  MemberReader,
   NameOrRef,
   NotifyFactory,
   NotifyFn,
@@ -186,6 +187,7 @@ export type {
   RateLimitOption,
   RateLimitPer,
   SessionUser,
+  SessionUserOrigin,
   StreamHandlerDef,
   StreamHandlerFn,
   TryAppendEventFn,

package/src/entrypoint/index.ts

@@ -38,7 +38,7 @@ import { buildServer, withFileProviderResolver } from "../api/server";
 import type { SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
-import type { AppContext, DispatchWriteRef, JobRunIn, Registry, RunIn } from "../engine/types";
+import type { AppContext, JobRunIn, Registry, RunIn } from "../engine/types";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner";
 import { createJobRunner } from "../jobs/job-runner";
 import type { Lifecycle } from "../lifecycle";
@@ -47,6 +47,7 @@ import type { ObservabilityOptions, ObservabilityProvider } from "../observabili
 import { createNoopProvider } from "../observability";
 import type { EventDedup, EventDispatcher } from "../pipeline";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher";
+import { dispatcherToWriteRef } from "../pipeline/dispatcher";
 import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
 
 // Shared fields across all three modes. A caller that swaps between
@@ -206,18 +207,6 @@ function contextWithObservability(
   };
 }
 
-// Adapts the command-dispatcher's positional (type, payload, user) calls to
-// DispatchWriteRef's (user, qn, payload) shape — JobContext.write/queryAs
-// pass identity explicitly per call (boot-time singleton), while Dispatcher
-// takes it last (request-scoped closure caller). Same underlying pipeline,
-// different argument order.
-function dispatcherToWriteRef(dispatcher: Dispatcher): DispatchWriteRef {
-  return {
-    write: (user, qn, payload) => dispatcher.write(qn, payload, user),
-    queryAs: (user, qn, payload) => dispatcher.query(qn, payload, user),
-  };
-}
-
 // buildApiServer shapes ServerOptions from API-mode caller-options.
 // AllInOneEntrypointOptions extends ApiEntrypointOptions, so structural
 // subtyping makes the all-in-one path a valid caller without an explicit

package/src/errors/i18n/de.yaml

@@ -97,6 +97,42 @@ system_identity_switch_denied:
     (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
     oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
 
+identity_switch_denied:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein Handler oder Hook hat `ctx.queryAs`/`ctx.writeAs`
+    mit einer anderen Identität als dem eigenen Caller aufgerufen — andere
+    User-ID, anderer Tenant, andere Claims oder Origin, oder Rollen, die der
+    Caller nicht hat — ohne `r.systemScope()`-Handler, Job zu sein oder
+    `escapeHatch: { reason }` zu deklarieren. Der Wechsel auf den Caller selbst
+    oder eine Teilmenge seiner Rollen bleibt frei.
+
+    Deklariere `escapeHatch: { reason: "..." }` am Write- oder Query-Handler
+    (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
+    oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
+
+member_resolution_denied:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: `ctx.queryAsMember(userId, ...)` konnte für `userId`
+    keine aktive Mitgliedschaft im Tenant des Aufrufers auflösen (kein
+    Mitglied, Principal gesperrt, oder der Tenant befindet sich im Teardown).
+    Bewusst generisch — `details` verrät nie, welche Prüfung fehlgeschlagen ist.
+
+member_resolution_read_only:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein über `ctx.queryAsMember` erreichter Query-Handler
+    hat versucht zu schreiben (`ctx.write`/`writeAs`/`appendEvent`/
+    `jobRunner`/...). Aufgelöste Member-Principals sind nur lesend — es gibt
+    kein `writeAsMember`.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -94,6 +94,40 @@ system_identity_switch_denied:
     (or on the `r.hook(...)` call, if the switch happens inside a hook), or
     move the logic into an `r.systemScope()` feature or a job.
 
+identity_switch_denied:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a handler or hook called `ctx.queryAs`/`ctx.writeAs`
+    with an identity other than its own caller — a different user id, tenant,
+    claims or origin, or roles the caller does not have — without being an
+    `r.systemScope()` handler, a job, or declaring `escapeHatch: { reason }`.
+    Switching to the caller itself or to a subset of its roles stays free.
+
+    Declare `escapeHatch: { reason: "..." }` on the write or query handler
+    (or on the `r.hook(...)` call, if the switch happens inside a hook), or
+    move the logic into an `r.systemScope()` feature or a job.
+
+member_resolution_denied:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: `ctx.queryAsMember(userId, ...)` could not resolve an
+    active membership for `userId` in the caller's tenant (not a member,
+    principal blocked, or the tenant is in teardown). Deliberately generic —
+    `details` never says which check failed.
+
+member_resolution_read_only:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a query handler reached via `ctx.queryAsMember` tried
+    to write (`ctx.write`/`writeAs`/`appendEvent`/`jobRunner`/...). Resolved
+    member principals are read-only — there is no `writeAsMember`.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -42,6 +42,19 @@ export const FrameworkReasons = {
   // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
   // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
   systemIdentitySwitchDenied: "system_identity_switch_denied",
+
+  // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+  // non-SYSTEM identity other than its own caller (different user, tenant,
+  // claims, origin or extra roles) without r.systemScope() or escapeHatch.
+  identitySwitchDenied: "identity_switch_denied",
+
+  // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
+  // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
+  memberResolutionDenied: "member_resolution_denied",
+
+  // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
+  // write — a resolved member principal is read-only by construction.
+  memberResolutionReadOnly: "member_resolution_read_only",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];

package/src/jobs/job-runner.ts

@@ -10,6 +10,7 @@ import {
   type DispatchWriteRef,
   type JobContext,
   type JobRunIn,
+  type MemberReader,
   type Registry,
   type SessionUser,
   SYSTEM_TENANT_ID,
@@ -552,6 +553,9 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             tenantId,
           })
         : context.derivatives;
+    // Per-job-run reader, created lazily on queryAsMember's first call and
+    // cached for the rest of this run.
+    let memberReader: MemberReader | undefined;
     const jobContext: JobContext = {
       ...context,
       // Same union as configDb above — job runners are always constructed
@@ -597,6 +601,16 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         }
         return dispatchWriteRef.queryAs(user, qn, payload);
       },
+      queryAsMember: (userId: string, qn: string, payload: unknown) => {
+        if (!dispatchWriteRef) {
+          throw new Error(
+            "JobContext.queryAsMember called before dispatcher attached — call attachDispatcher() first",
+          );
+        }
+        // Lazy per-run reader, mirroring the handler-context reader.
+        memberReader ??= dispatchWriteRef.createMemberReader(tenantId);
+        return memberReader(userId, qn, payload);
+      },
     };
 
     await options.onJobStart?.(jobName, jobId, meta);

package/src/pipeline/__tests__/dispatcher-utils.test.ts

@@ -51,6 +51,23 @@ describe("dispatcherSpanAttributes", () => {
       "kumiko.feature": "feat",
     });
   });
+
+  test("includes kumiko.user_origin when the user has one", () => {
+    const user = {
+      id: "u1",
+      tenantId: "tenant-1",
+      roles: [],
+      origin: "member-resolution" as const,
+    };
+    const attrs = dispatcherSpanAttributes("feat:query:task:list", "query", user, "feat");
+    expect(attrs["kumiko.user_origin"]).toBe("member-resolution");
+  });
+
+  test("omits kumiko.user_origin when the user has none", () => {
+    const user = createSystemUser("tenant-1");
+    const attrs = dispatcherSpanAttributes("feat:query:task:list", "query", user, "feat");
+    expect(attrs["kumiko.user_origin"]).toBeUndefined();
+  });
 });
 
 describe("prefixValidationPath", () => {

package/src/pipeline/__tests__/escape-hatch.integration.test.ts

@@ -19,7 +19,6 @@ const globalStoreTable = defineUnmanagedTable({
       primaryKey: true,
       defaultSql: "gen_random_uuid()",
     },
-    { name: "tenant_id", pgType: "uuid", notNull: true },
     { name: "note", pgType: "text", notNull: true },
   ],
 });
@@ -36,7 +35,6 @@ const escapeHatchFeature = defineFeature("escape-hatch-probe", (r) => {
     escapeHatch: { reason: "fw#2855 integration test — declared cross-tenant write" },
     handler: async (event, ctx) => {
       const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
-        tenantId: event.user.tenantId,
         note: event.payload.note,
       });
       return { isSuccess: true as const, data: row };
@@ -49,7 +47,6 @@ const escapeHatchFeature = defineFeature("escape-hatch-probe", (r) => {
     access: { roles: ["User"] },
     handler: async (event, ctx) => {
       const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
-        tenantId: event.user.tenantId,
         note: event.payload.note,
       });
       return { isSuccess: true as const, data: row };