@cosmicdrift/kumiko-framework 0.263.0 → 0.264.0

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

@@ -0,0 +1,195 @@
+import { describe, expect, mock, test } from "bun:test";
+import { createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID } from "../../engine";
+import type { SessionUser } from "../../engine/types";
+import type { TenantId } from "../../engine/types/identifiers";
+import { AccessDeniedError, FrameworkReasons } from "../../errors";
+import {
+  createGatedIdentitySwitch,
+  type IdentitySwitch,
+  isSystemIdentity,
+  isSystemIdentitySwitchAllowed,
+  withHookIdentitySwitchGrant,
+} from "../system-identity-switch";
+
+const TENANT = "00000000-0000-4000-8000-00000000ab01" as TenantId;
+
+const normalUser: SessionUser = { id: crypto.randomUUID(), tenantId: TENANT, roles: ["User"] };
+const systemUserById: SessionUser = { id: SYSTEM_USER_ID, tenantId: TENANT, roles: ["User"] };
+const systemUserByRole: SessionUser = {
+  id: crypto.randomUUID(),
+  tenantId: TENANT,
+  roles: [SYSTEM_ROLE],
+};
+
+function makeUngated(): {
+  readonly ungated: IdentitySwitch;
+  readonly queryAsMock: ReturnType<typeof mock>;
+  readonly writeAsMock: ReturnType<typeof mock>;
+} {
+  const queryAsMock = mock(async (_user: SessionUser, _qn: string, _payload: unknown) => ({
+    ok: true,
+  }));
+  const writeAsMock = mock(async (_user: SessionUser, _qn: string, _payload: unknown) => ({
+    isSuccess: true as const,
+    data: { ok: true },
+  }));
+  return {
+    ungated: { queryAs: queryAsMock, writeAs: writeAsMock },
+    queryAsMock,
+    writeAsMock,
+  };
+}
+
+describe("isSystemIdentity", () => {
+  test("SYSTEM_USER_ID alone counts as SYSTEM", () => {
+    expect(isSystemIdentity(systemUserById)).toBe(true);
+  });
+
+  test("SYSTEM_ROLE alone counts as SYSTEM", () => {
+    expect(isSystemIdentity(systemUserByRole)).toBe(true);
+  });
+
+  test("a normal user is not SYSTEM", () => {
+    expect(isSystemIdentity(normalUser)).toBe(false);
+  });
+
+  test("createSystemUser(...) is SYSTEM", () => {
+    expect(isSystemIdentity(createSystemUser(TENANT))).toBe(true);
+  });
+});
+
+describe("isSystemIdentitySwitchAllowed", () => {
+  test("SYSTEM target requires allowSystemIdentity=true", () => {
+    expect(isSystemIdentitySwitchAllowed(systemUserById, false)).toBe(false);
+    expect(isSystemIdentitySwitchAllowed(systemUserById, true)).toBe(true);
+  });
+
+  test("a non-SYSTEM target is always allowed", () => {
+    expect(isSystemIdentitySwitchAllowed(normalUser, false)).toBe(true);
+    expect(isSystemIdentitySwitchAllowed(normalUser, true)).toBe(true);
+  });
+});
+
+describe("createGatedIdentitySwitch", () => {
+  test("queryAs to SYSTEM throws AccessDeniedError with the reason code, no asUser/tenantId/payload leak", async () => {
+    const { ungated } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', false, ungated);
+
+    let caught: unknown;
+    try {
+      await gated.queryAs(systemUserById, "some:target", { secret: "payload-value" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    const error = caught as AccessDeniedError;
+    expect(error.details).toEqual({ reason: FrameworkReasons.systemIdentitySwitchDenied });
+    expect(error.message).not.toContain(systemUserById.id);
+    expect(error.message).not.toContain(TENANT);
+    expect(error.message).not.toContain("payload-value");
+  });
+
+  test("writeAs to SYSTEM throws the same way (never falls back to a WriteResult failure)", async () => {
+    const { ungated } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', false, ungated);
+
+    await expect(gated.writeAs(systemUserById, "some:target", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+  });
+
+  test("allowSystemIdentity=true lets a SYSTEM switch pass through to the ungated pair", async () => {
+    const { ungated, queryAsMock, writeAsMock } = makeUngated();
+    const gated = createGatedIdentitySwitch('handler "x"', true, ungated);
+
+    await gated.queryAs(systemUserById, "q", { a: 1 });
+    await gated.writeAs(systemUserById, "w", { b: 2 });
+
+    expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", { a: 1 });
+    expect(writeAsMock).toHaveBeenCalledWith(systemUserById, "w", { b: 2 });
+  });
+
+  test("a non-system asUser always passes through, regardless of allowSystemIdentity", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const deniedByDefault = createGatedIdentitySwitch('handler "x"', false, ungated);
+
+    await deniedByDefault.queryAs(normalUser, "q", {});
+
+    expect(queryAsMock).toHaveBeenCalledWith(normalUser, "q", {});
+  });
+});
+
+describe("withHookIdentitySwitchGrant", () => {
+  test("hook without escapeHatch does NOT inherit the handler's SYSTEM grant", async () => {
+    const { ungated } = makeUngated();
+    // Simulates dispatch-shared.ts's buildHandlerContext for a handler that
+    // itself declared escapeHatch / is systemScope (allowSystemIdentity=true).
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', true, ungated) };
+
+    const hookCtx = withHookIdentitySwitchGrant(
+      handlerCtx,
+      'postSave hook of feature "f"',
+      undefined,
+    );
+
+    await expect(hookCtx.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+  });
+
+  test("hook WITH escapeHatch is allowed even when the handler's own grant was false", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    // Handler itself has NO escapeHatch (allowSystemIdentity=false).
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', false, ungated) };
+
+    const hookCtx = withHookIdentitySwitchGrant(handlerCtx, 'postSave hook of feature "f"', {
+      reason: "test hook needs SYSTEM",
+    });
+
+    await hookCtx.queryAs(systemUserById, "q", { a: 1 });
+    // Reaches the REAL ungated fn — not the handler's own (still-denying) gate.
+    expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", { a: 1 });
+  });
+
+  test("a non-system asUser is always allowed through the hook's own gate", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', false, ungated) };
+    const hookCtx = withHookIdentitySwitchGrant(handlerCtx, "hook", undefined);
+
+    await hookCtx.queryAs(normalUser, "q", {});
+    expect(queryAsMock).toHaveBeenCalledWith(normalUser, "q", {});
+  });
+
+  test("spreading the context ({...ctx}) still resolves back to the ungated pair", async () => {
+    const { ungated, queryAsMock } = makeUngated();
+    const handlerCtx = { ...createGatedIdentitySwitch('handler "outer"', true, ungated), extra: 1 };
+    const spread = { ...handlerCtx };
+
+    const hookCtx = withHookIdentitySwitchGrant(spread, "hook", { reason: "needs system" });
+    await hookCtx.queryAs(systemUserById, "q", {});
+
+    expect(queryAsMock).toHaveBeenCalledWith(systemUserById, "q", {});
+  });
+
+  test("a context without queryAs/writeAs is returned unchanged", () => {
+    const plainContext = { db: {} };
+    const result = withHookIdentitySwitchGrant(plainContext, "hook", { reason: "x" });
+    expect(result).toBe(plainContext);
+  });
+
+  test("an ungated context not built by the dispatcher bridge fails closed (unit-test stub)", async () => {
+    const stubQueryAs = mock(async (_user: SessionUser, _qn: string, _payload: unknown) => "ok");
+    const stubContext = { queryAs: stubQueryAs };
+
+    const hookCtx = withHookIdentitySwitchGrant(stubContext, "hook", undefined);
+    await expect(hookCtx.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(
+      AccessDeniedError,
+    );
+    expect(stubQueryAs).not.toHaveBeenCalled();
+
+    const allowedHookCtx = withHookIdentitySwitchGrant(stubContext, "hook", { reason: "x" });
+    await allowedHookCtx.queryAs(systemUserById, "q", {});
+    expect(stubQueryAs).toHaveBeenCalledWith(systemUserById, "q", {});
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -75,6 +75,7 @@ import {
 } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
+import { createGatedIdentitySwitch } from "./system-identity-switch";
 import type { TenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Framework/pipeline stays bundled-features-free, so this can't import the
@@ -208,6 +209,11 @@ export async function buildHandlerContext(
   const reqCtx = requestContext.get();
   // db.global()'s write-gate — undefined for query/stream handlers, which can't declare escapeHatch.
   const escapeHatch = registry.getWriteHandler(type)?.escapeHatch;
+  // Broader than `escapeHatch` above — a query handler can't reach db.global() but can still opt in here.
+  const allowSystemIdentity =
+    isSystem ||
+    (registry.getWriteHandler(type)?.escapeHatch ?? registry.getQueryHandler(type)?.escapeHatch) !==
+      undefined;
   const buildTenantScopedDb = (source: DbConnection | DbTx, signal: AbortSignal | undefined) =>
     createTenantDb(
       source,
@@ -304,29 +310,27 @@ export async function buildHandlerContext(
     ? (targetFeatureName: string) => createSafeMetricsHandle(meter, targetFeatureName)
     : () => createNoopMetricsHandle();
 
-  // Cross-feature bridge. Queries and writes invoked through ctx.* share:
-  //   - the current transaction (tx) — nested writes roll back with the parent
-  //   - the current afterCommitHooks sink — deferred side-effects fire once
-  //     when the outermost transaction commits
-  // `queryAs` / `writeAs` let a handler explicitly switch identity
-  // (e.g. system-privileged lookups that bypass field-access read filters).
+  // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
+  // queryAs/writeAs switch identity; SYSTEM needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
   const bridgeSink = afterCommitHooks ?? [];
   const scheduleAfterCommit = (hook: AfterCommitHook): void => {
     bridgeSink.push(hook);
   };
+  const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, allowSystemIdentity, {
+    queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
+      executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
+    writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
+      executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
+  });
   const bridge = {
     query: (targetType: string, payload: unknown) =>
       executeQuery(ctx, targetType, payload, user, tx), // @wrapper-known semantic-alias
-    queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-      executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
+    queryAs: identitySwitch.queryAs,
     write: async (targetType: string, payload: unknown) => {
       const res = await executeWrite(ctx, targetType, payload, user, tx, bridgeSink);
       return res;
     },
-    writeAs: async (asUser: SessionUser, targetType: string, payload: unknown) => {
-      const res = await executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink);
-      return res;
-    },
+    writeAs: identitySwitch.writeAs,
     // Strict + unsafe share the same runtime — only the type-surface
     // differs. The strict signature is what's exposed to typed callers;
     // unsafe is the explicit escape-hatch for runtime-pluggable events.
@@ -949,8 +953,8 @@ export async function enforceRateLimit(
 // Build the per-hook context every auth-claims invocation gets. Claims
 // hooks run OUTSIDE any request transaction (login is itself the root
 // operation, not a nested call) and read-only — so the TenantDb is
-// scoped as "tenant" and no tx is threaded through. Hooks that need
-// cross-tenant lookups opt in explicitly via queryAs(systemUser, ...).
+// scoped as "tenant" and no tx is threaded through. Cross-tenant lookups
+// go through queryAs(otherUser, ...); SYSTEM is always denied (no escapeHatch declaration site here).
 function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthClaimsContext {
   const { appContext: context } = ctx;
   const dbSource = resolveDbSource(ctx, undefined);
@@ -967,10 +971,18 @@ function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthCl
         secrets: context.secrets,
       })
     : undefined;
-  return {
-    db,
+  const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", false, {
     queryAs: (asUser: SessionUser, qn: string, payload: unknown) =>
       executeQuery(ctx, qn, payload, asUser), // @wrapper-known semantic-alias
+    writeAs: async () => {
+      throw new InternalError({
+        message: "r.authClaims hook context has no writeAs — auth-claims hooks are read-only.",
+      });
+    },
+  });
+  return {
+    db,
+    queryAs: identitySwitch.queryAs,
     ...(configAccessor && { config: configAccessor }),
   };
 }

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

@@ -0,0 +1,123 @@
+import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
+import type {
+  EscapeHatchDeclaration,
+  LifecycleHookFn,
+  SessionUser,
+  WriteResult,
+} from "../engine/types";
+import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors";
+
+export type QueryAsFn = (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+export type WriteAsFn = (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+export type IdentitySwitch = { readonly queryAs: QueryAsFn; readonly writeAs: WriteAsFn };
+
+export function isSystemIdentity(user: SessionUser): boolean {
+  return user.id === SYSTEM_USER_ID || user.roles.includes(SYSTEM_ROLE);
+}
+
+export function isSystemIdentitySwitchAllowed(
+  asUser: SessionUser,
+  allowSystemIdentity: boolean,
+): boolean {
+  return !isSystemIdentity(asUser) || allowSystemIdentity;
+}
+
+function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedError {
+  return new AccessDeniedError({
+    message:
+      `${callerLabel} may not switch identity to SYSTEM — declare r.systemScope() or ` +
+      "escapeHatch: { reason } on it",
+    details: { reason: FrameworkReasons.systemIdentitySwitchDenied },
+  });
+}
+
+// Reverse-lookup so withHookIdentitySwitchGrant can re-gate the SAME ungated pair under a narrower grant.
+const ungatedByGated = new WeakMap<QueryAsFn | WriteAsFn, IdentitySwitch>();
+
+export function createGatedIdentitySwitch(
+  callerLabel: string,
+  allowSystemIdentity: boolean,
+  ungated: IdentitySwitch,
+): IdentitySwitch {
+  const queryAs: QueryAsFn = async (asUser, qn, payload) => {
+    if (!isSystemIdentitySwitchAllowed(asUser, allowSystemIdentity)) {
+      throw systemIdentitySwitchDenied(callerLabel);
+    }
+    return ungated.queryAs(asUser, qn, payload);
+  };
+  const writeAs: WriteAsFn = async (asUser, qn, payload) => {
+    if (!isSystemIdentitySwitchAllowed(asUser, allowSystemIdentity)) {
+      throw systemIdentitySwitchDenied(callerLabel);
+    }
+    return ungated.writeAs(asUser, qn, payload);
+  };
+  const gated: IdentitySwitch = { queryAs, writeAs };
+  ungatedByGated.set(queryAs, ungated);
+  ungatedByGated.set(writeAs, ungated);
+  return gated;
+}
+
+function readIdentitySwitchFn<TFn extends QueryAsFn | WriteAsFn>(
+  context: object,
+  key: "queryAs" | "writeAs",
+): 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
+}
+
+function unavailableIdentitySwitchFn(callerLabel: string, kind: "queryAs" | "writeAs") {
+  return async () => {
+    throw new InternalError({
+      message: `${callerLabel}: this context has no ${kind} to switch identity with.`,
+    });
+  };
+}
+
+// Fail-closed fallback for a ctx not built by the dispatcher bridge (unit-test stub, duplicated module instance).
+function fallbackUngatedIdentitySwitch(
+  callerLabel: string,
+  ctxQueryAs: QueryAsFn | undefined,
+  ctxWriteAs: WriteAsFn | undefined,
+): IdentitySwitch {
+  return {
+    queryAs: ctxQueryAs ?? unavailableIdentitySwitchFn(callerLabel, "queryAs"),
+    writeAs: ctxWriteAs ?? unavailableIdentitySwitchFn(callerLabel, "writeAs"),
+  };
+}
+
+export function withHookIdentitySwitchGrant<TContext extends object>(
+  context: TContext,
+  callerLabel: string,
+  escapeHatch: EscapeHatchDeclaration | undefined,
+): TContext {
+  const ctxQueryAs = readIdentitySwitchFn<QueryAsFn>(context, "queryAs");
+  const ctxWriteAs = readIdentitySwitchFn<WriteAsFn>(context, "writeAs");
+  if (!ctxQueryAs && !ctxWriteAs) return context;
+
+  // Reuse the ORIGINAL ungated pair when known, so this grant doesn't compose with the caller's.
+  const ungated: IdentitySwitch =
+    (ctxQueryAs && ungatedByGated.get(ctxQueryAs)) ??
+    (ctxWriteAs && ungatedByGated.get(ctxWriteAs)) ??
+    fallbackUngatedIdentitySwitch(callerLabel, ctxQueryAs, ctxWriteAs);
+
+  const gated = createGatedIdentitySwitch(callerLabel, escapeHatch !== undefined, ungated);
+  return {
+    ...context,
+    ...(ctxQueryAs && { queryAs: gated.queryAs }),
+    ...(ctxWriteAs && { writeAs: gated.writeAs }),
+  };
+}
+
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs instead of inheriting the handler's grant.
+export function bindHookIdentitySwitchGrant(
+  fn: LifecycleHookFn,
+  label: string,
+  escapeHatch: EscapeHatchDeclaration | undefined,
+): LifecycleHookFn {
+  return ((payload: unknown, context: object) =>
+    (fn as (payload: unknown, context: object) => unknown)(
+      payload,
+      withHookIdentitySwitchGrant(context, label, escapeHatch),
+    )) as LifecycleHookFn; // @cast-boundary engine-bridge — LifecycleHookFn union, same (payload, context) shape at runtime
+}