@cosmicdrift/kumiko-framework 0.265.0 → 0.268.0

package/src/pipeline/member-reader.ts

@@ -0,0 +1,108 @@
+// ctx.queryAsMember — reads a query handler as a stored tenant member. The
+// resolved SessionUser never leaves this module.
+
+import type { DbConnection, DbTx } from "../db/connection";
+import { buildSessionRoles } from "../engine/membership-roles";
+import type { MemberReader, SessionUser } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types";
+import type { TenantId } from "../engine/types/identifiers";
+import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors";
+import {
+  type ActiveMembershipPolicy,
+  resolveActiveMembershipFn,
+  resolvePrincipalPlugin,
+} from "./active-membership";
+import { executeQuery } from "./dispatch-query";
+import { type DispatchContext, resolveAuthClaimsFn, resolveDbSource } from "./dispatch-shared";
+import { isSystemIdentity } from "./system-identity-switch";
+
+// Stricter than interactive sign-in: an unknown principal or a tenant
+// mid-teardown must not resolve — there is no user-facing flow to recover.
+export const BACKGROUND_READ_POLICY: ActiveMembershipPolicy = {
+  allowPendingDestruction: false,
+  allowUnknownPrincipal: false,
+};
+
+// Generic on purpose — details never carry which check failed, so a caller
+// can't probe another user's membership state via the error shape.
+function memberResolutionDenied(): AccessDeniedError {
+  return new AccessDeniedError({
+    message: "not permitted to read as this member",
+    details: { reason: FrameworkReasons.memberResolutionDenied },
+  });
+}
+
+// Membership/principal/lifecycle resolve on the root connection, outside the
+// caller's tx — only the target query runs inside it (via the `tx` argument).
+async function resolveMember(
+  ctx: DispatchContext,
+  tenantId: TenantId,
+  userId: string,
+): Promise<SessionUser> {
+  const membership = await resolveActiveMembershipFn(ctx, userId, tenantId, BACKGROUND_READ_POLICY);
+  if (membership.kind === "rejected") throw memberResolutionDenied();
+
+  const principalPlugin = resolvePrincipalPlugin(ctx.registry);
+  const dbSource = resolveDbSource(ctx, undefined);
+  if (!dbSource) {
+    throw new InternalError({
+      message: "ctx.queryAsMember requires a database connection — none is configured.",
+    });
+  }
+  // resolveDbSource(ctx, undefined) never returns a tx, only AppContext.db.
+  const db = dbSource as DbConnection; // @cast-boundary db-operator
+
+  const profile = await principalPlugin.resolveProfile(userId, { db });
+  if (!profile) throw memberResolutionDenied();
+
+  // buildSessionRoles runs stripForbiddenMembershipRoles on the membership half (rebuild-resurrected roles).
+  const roles = buildSessionRoles(profile.globalRoles, membership.membership.roles);
+  const base: SessionUser = {
+    id: userId,
+    tenantId,
+    roles,
+    ...(profile.timezone !== undefined && { timezone: profile.timezone }),
+    ...(profile.locale !== undefined && { locale: profile.locale }),
+    origin: "member-resolution",
+  };
+  // Defense in depth: buildSessionRoles strips forbidden roles only from the
+  // membership half, not globalRoles — a resolved principal must never be SYSTEM.
+  if (isSystemIdentity(base)) throw memberResolutionDenied();
+
+  const claims = await resolveAuthClaimsFn(ctx, base);
+  return Object.keys(claims).length > 0 ? { ...base, claims } : base;
+}
+
+// One reader per handler invocation (shared with its hooks) or job run; a
+// nested dispatch builds its own reader with its own cache.
+export function createMemberReaderFn(
+  ctx: DispatchContext,
+  tenantId: TenantId,
+  tx?: DbTx,
+): MemberReader {
+  if (tenantId === SYSTEM_TENANT_ID) {
+    throw new InternalError({
+      message: "queryAsMember needs a tenant-scoped context — got SYSTEM_TENANT_ID.",
+    });
+  }
+
+  // Only successful resolutions are cached — a rejected/failed resolution
+  // deletes its own entry so a transient error can't poison the rest of the run.
+  const cache = new Map<string, Promise<SessionUser>>();
+
+  function resolve(userId: string): Promise<SessionUser> {
+    const cached = cache.get(userId);
+    if (cached) return cached;
+    const pending = resolveMember(ctx, tenantId, userId);
+    cache.set(userId, pending);
+    pending.catch(() => {
+      cache.delete(userId);
+    });
+    return pending;
+  }
+
+  return async (userId, qn, payload) => {
+    const user = await resolve(userId);
+    return executeQuery(ctx, qn, payload, user, tx);
+  };
+}

package/src/pipeline/system-identity-switch.ts

@@ -1,8 +1,10 @@
+import { type TenantDb, withUnsafeRawGrant } from "../db/tenant-db";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
   ActiveMembershipResult,
   EscapeHatchDeclaration,
   LifecycleHookFn,
+  MemberReader,
   SessionUser,
   WriteResult,
 } from "../engine/types";
@@ -37,8 +39,10 @@ export function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedErr
   });
 }
 
-// Reverse-lookup so withHookIdentitySwitchGrant can re-gate the SAME ungated pair under a narrower grant.
+// Reverse-lookup so withHookEscapeHatchGrant can re-gate the SAME ungated pair under a narrower grant.
 const ungatedByGated = new WeakMap<QueryAsFn | WriteAsFn, IdentitySwitch>();
+// Same idea, for ctx.queryAsMember — a single function rather than a pair.
+const ungatedMemberReaderByGated = new WeakMap<MemberReader, MemberReader>();
 
 export function createGatedIdentitySwitch(
   callerLabel: string,
@@ -63,15 +67,39 @@ export function createGatedIdentitySwitch(
   return gated;
 }
 
-function readIdentitySwitchFn<TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn>(
+// ctx.queryAsMember's gate: the caller never names the target identity up
+// front (it's resolved internally), so this is a flat allow/deny.
+export function createGatedMemberReader(
+  callerLabel: string,
+  allowSystemIdentity: boolean,
+  ungated: MemberReader,
+): MemberReader {
+  const gated: MemberReader = async (userId, qn, payload) => {
+    if (!allowSystemIdentity) throw systemIdentitySwitchDenied(callerLabel);
+    return ungated(userId, qn, payload);
+  };
+  ungatedMemberReaderByGated.set(gated, ungated);
+  return gated;
+}
+
+function readIdentitySwitchFn<
+  TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn | MemberReader,
+>(
   context: object,
-  key: "queryAs" | "writeAs" | "resolveActiveMembership",
+  key: "queryAs" | "writeAs" | "resolveActiveMembership" | "queryAsMember",
 ): TFn | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
   return typeof value === "function" ? (value as TFn) : undefined; // @cast-boundary engine-bridge — checked via typeof above
 }
 
+// context's own keys only — never touch a property of the resolved value, which may be a Proxy that throws on any get.
+function readDbLikeValue(context: object, key: "db" | "dbOutsideTransaction"): object | undefined {
+  if (!(key in context)) return undefined;
+  const value = (context as Record<string, unknown>)[key];
+  return typeof value === "object" && value !== null ? value : undefined;
+}
+
 function unavailableIdentitySwitchFn(callerLabel: string, kind: "queryAs" | "writeAs") {
   return async () => {
     throw new InternalError({
@@ -98,7 +126,8 @@ function fallbackUngatedIdentitySwitch(
   };
 }
 
-// Reuses the ORIGINAL ungated pair when known, so this grant doesn't compose with the caller's.
+// Resolved per function: a shared ungated pair would revive a member-resolution
+// ctx's deny-stubbed writeAs through its still-registered queryAs.
 function gatedIdentitySwitchFields(
   callerLabel: string,
   escapeHatch: EscapeHatchDeclaration | undefined,
@@ -106,10 +135,9 @@ function gatedIdentitySwitchFields(
   ctxWriteAs: WriteAsFn | undefined,
 ): Partial<IdentitySwitch> {
   if (!ctxQueryAs && !ctxWriteAs) return {};
-  const ungated: IdentitySwitch =
-    (ctxQueryAs && ungatedByGated.get(ctxQueryAs)) ??
-    (ctxWriteAs && ungatedByGated.get(ctxWriteAs)) ??
-    fallbackUngatedIdentitySwitch(callerLabel, ctxQueryAs, ctxWriteAs);
+  const ungatedQueryAs = ctxQueryAs && (ungatedByGated.get(ctxQueryAs)?.queryAs ?? ctxQueryAs);
+  const ungatedWriteAs = ctxWriteAs && (ungatedByGated.get(ctxWriteAs)?.writeAs ?? ctxWriteAs);
+  const ungated = fallbackUngatedIdentitySwitch(callerLabel, ungatedQueryAs, ungatedWriteAs);
   const gated = createGatedIdentitySwitch(callerLabel, escapeHatch !== undefined, ungated);
   return {
     ...(ctxQueryAs && { queryAs: gated.queryAs }),
@@ -117,7 +145,21 @@ function gatedIdentitySwitchFields(
   };
 }
 
-export function withHookIdentitySwitchGrant<TContext extends object>(
+// Unlike ctx.resolveActiveMembership (deny-only), a hook's own escapeHatch
+// can grant queryAsMember even when the enclosing handler has none.
+function gatedMemberReaderField(
+  callerLabel: string,
+  escapeHatch: EscapeHatchDeclaration | undefined,
+  ctxQueryAsMember: MemberReader | undefined,
+): { queryAsMember?: MemberReader } {
+  if (!ctxQueryAsMember) return {};
+  const ungated = ungatedMemberReaderByGated.get(ctxQueryAsMember) ?? ctxQueryAsMember;
+  return {
+    queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated),
+  };
+}
+
+export function withHookEscapeHatchGrant<TContext extends object>(
   context: TContext,
   callerLabel: string,
   escapeHatch: EscapeHatchDeclaration | undefined,
@@ -128,7 +170,19 @@ export function withHookIdentitySwitchGrant<TContext extends object>(
     context,
     "resolveActiveMembership",
   );
-  if (!ctxQueryAs && !ctxWriteAs && !ctxResolveActiveMembership) return context;
+  const ctxQueryAsMember = readIdentitySwitchFn<MemberReader>(context, "queryAsMember");
+  const ctxDb = readDbLikeValue(context, "db");
+  const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
+  if (
+    !ctxQueryAs &&
+    !ctxWriteAs &&
+    !ctxResolveActiveMembership &&
+    !ctxQueryAsMember &&
+    !ctxDb &&
+    !ctxDbOutsideTransaction
+  ) {
+    return context;
+  }
 
   return {
     ...context,
@@ -137,11 +191,17 @@ export function withHookIdentitySwitchGrant<TContext extends object>(
       escapeHatch === undefined && {
         resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
       }),
+    ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
+    // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
+    ...(ctxDb && { db: withUnsafeRawGrant(ctxDb as TenantDb, escapeHatch) }),
+    ...(ctxDbOutsideTransaction && {
+      dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction as TenantDb, escapeHatch),
+    }),
   };
 }
 
-// Re-gates a hook's own ctx.queryAs/ctx.writeAs instead of inheriting the handler's grant.
-export function bindHookIdentitySwitchGrant(
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
+export function bindHookEscapeHatchGrant(
   fn: LifecycleHookFn,
   label: string,
   escapeHatch: EscapeHatchDeclaration | undefined,
@@ -149,6 +209,6 @@ export function bindHookIdentitySwitchGrant(
   return ((payload: unknown, context: object) =>
     (fn as (payload: unknown, context: object) => unknown)(
       payload,
-      withHookIdentitySwitchGrant(context, label, escapeHatch),
+      withHookEscapeHatchGrant(context, label, escapeHatch),
     )) as LifecycleHookFn; // @cast-boundary engine-bridge — LifecycleHookFn union, same (payload, context) shape at runtime
 }

package/src/stack/test-stack.ts

@@ -13,7 +13,12 @@ import { createJobRunner, type JobRunner, type JobRunnerOptions } from "../jobs"
 import type { Lifecycle } from "../lifecycle";
 import { createNoopProvider, type ObservabilityProvider } from "../observability";
 import type { Dispatcher, EventDispatcher } from "../pipeline";
-import { createEntityCache, createEventDedup, createIdempotencyGuard } from "../pipeline";
+import {
+  createEntityCache,
+  createEventDedup,
+  createIdempotencyGuard,
+  dispatcherToWriteRef,
+} from "../pipeline";
 import { createInMemorySearchAdapter } from "../search";
 import type { SearchAdapter } from "../search/types";
 import { createTestDb } from "./db";
@@ -446,6 +451,10 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       })()),
     });
 
+    // Mirrors the prod entrypoints — without this, JobContext.write/writeAs/
+    // queryAs/queryAsMember throw on first use inside a test-stack job.
+    if (jobRunner) jobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
+
     const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
 
     // Pre-register consumer state rows so tests can call runOnce() directly

package/src/testing/handler-context.ts

@@ -9,6 +9,7 @@ import type {
   AppendEventArgs,
   FetchForWritingArgs,
   HandlerContext,
+  MemberReader,
   SessionUser,
   WriteResult,
 } from "../engine/types";
@@ -58,6 +59,7 @@ export function bridgeStub(opts?: {
   | "queryProjection"
   | "resolveAuthClaims"
   | "resolveActiveMembership"
+  | "queryAsMember"
   | "hasFeature"
   | "metrics"
   | "metricsFor"
@@ -122,6 +124,7 @@ export function bridgeStub(opts?: {
     resolveActiveMembership: notAvailable(
       "resolveActiveMembership",
     ) as unknown as HandlerContext["resolveActiveMembership"],
+    queryAsMember: notAvailable("queryAsMember") as unknown as MemberReader,
     // Stub defaults to always-enabled — matches the dispatcher's behaviour
     // when no effectiveFeatures resolver is wired (tests without toggles).
     hasFeature: async () => true,

package/src/ui-types/index.ts

@@ -56,6 +56,7 @@ export type {
   AccessRule,
   OpenToAllAccessRule,
   OpenToAllDeclaration,
+  OpenToAllPersonalData,
 } from "../engine/types/handlers";
 export { isOpenToAllGranted } from "../engine/types/handlers";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav";