@cosmicdrift/kumiko-framework 0.264.1 → 0.266.0

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

@@ -1,14 +1,20 @@
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
+  ActiveMembershipResult,
   EscapeHatchDeclaration,
   LifecycleHookFn,
   SessionUser,
   WriteResult,
 } from "../engine/types";
+import type { TenantId } from "../engine/types/identifiers";
 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 ResolveActiveMembershipFn = (
+  userId: string,
+  tenantId: TenantId,
+) => Promise<ActiveMembershipResult>;
 export type IdentitySwitch = { readonly queryAs: QueryAsFn; readonly writeAs: WriteAsFn };
 
 export function isSystemIdentity(user: SessionUser): boolean {
@@ -22,7 +28,7 @@ export function isSystemIdentitySwitchAllowed(
   return !isSystemIdentity(asUser) || allowSystemIdentity;
 }
 
-function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedError {
+export function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedError {
   return new AccessDeniedError({
     message:
       `${callerLabel} may not switch identity to SYSTEM — declare r.systemScope() or ` +
@@ -57,9 +63,9 @@ export function createGatedIdentitySwitch(
   return gated;
 }
 
-function readIdentitySwitchFn<TFn extends QueryAsFn | WriteAsFn>(
+function readIdentitySwitchFn<TFn extends QueryAsFn | WriteAsFn | ResolveActiveMembershipFn>(
   context: object,
-  key: "queryAs" | "writeAs",
+  key: "queryAs" | "writeAs" | "resolveActiveMembership",
 ): TFn | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
@@ -74,6 +80,12 @@ function unavailableIdentitySwitchFn(callerLabel: string, kind: "queryAs" | "wri
   };
 }
 
+function deniedResolveActiveMembership(callerLabel: string): ResolveActiveMembershipFn {
+  return async () => {
+    throw systemIdentitySwitchDenied(callerLabel);
+  };
+}
+
 // Fail-closed fallback for a ctx not built by the dispatcher bridge (unit-test stub, duplicated module instance).
 function fallbackUngatedIdentitySwitch(
   callerLabel: string,
@@ -86,29 +98,48 @@ function fallbackUngatedIdentitySwitch(
   };
 }
 
-export function withHookIdentitySwitchGrant<TContext extends object>(
-  context: TContext,
+// Reuses the ORIGINAL ungated pair when known, so this grant doesn't compose with the caller's.
+function gatedIdentitySwitchFields(
   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.
+  ctxQueryAs: QueryAsFn | undefined,
+  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 gated = createGatedIdentitySwitch(callerLabel, escapeHatch !== undefined, ungated);
   return {
-    ...context,
     ...(ctxQueryAs && { queryAs: gated.queryAs }),
     ...(ctxWriteAs && { writeAs: gated.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");
+  const ctxResolveActiveMembership = readIdentitySwitchFn<ResolveActiveMembershipFn>(
+    context,
+    "resolveActiveMembership",
+  );
+  if (!ctxQueryAs && !ctxWriteAs && !ctxResolveActiveMembership) return context;
+
+  return {
+    ...context,
+    ...gatedIdentitySwitchFields(callerLabel, escapeHatch, ctxQueryAs, ctxWriteAs),
+    ...(ctxResolveActiveMembership &&
+      escapeHatch === undefined && {
+        resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
+      }),
+  };
+}
+
 // Re-gates a hook's own ctx.queryAs/ctx.writeAs instead of inheriting the handler's grant.
 export function bindHookIdentitySwitchGrant(
   fn: LifecycleHookFn,

package/src/testing/handler-context.ts

@@ -57,6 +57,7 @@ export function bridgeStub(opts?: {
   | "loadAggregateWithSnapshot"
   | "queryProjection"
   | "resolveAuthClaims"
+  | "resolveActiveMembership"
   | "hasFeature"
   | "metrics"
   | "metricsFor"
@@ -118,6 +119,9 @@ export function bridgeStub(opts?: {
     resolveAuthClaims: notAvailable(
       "resolveAuthClaims",
     ) as unknown as HandlerContext["resolveAuthClaims"],
+    resolveActiveMembership: notAvailable(
+      "resolveActiveMembership",
+    ) as unknown as HandlerContext["resolveActiveMembership"],
     // 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";