@open-mercato/shared 0.6.8-develop.7013.1.48f7adca80 → 0.6.8-develop.7016.1.4ed7b1e49d

package/dist/modules/events/factory.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/events/factory.ts"],
-  "sourcesContent": ["/**\n * Event Module Factory\n *\n * Provides factory functions for creating type-safe event configurations.\n */\n\nimport { createLogger } from '../../lib/logger'\nimport type {\n  EventDefinition,\n  EventModuleConfig,\n  EventPayload,\n  EmitOptions,\n  CreateModuleEventsOptions,\n  ModuleEventEmitter,\n} from './types'\n\nconst logger = createLogger('events').child({ component: 'factory' })\n\n// =============================================================================\n// Global Event Bus Reference\n// =============================================================================\n\n/**\n * Type for the global event bus interface\n */\ninterface GlobalEventBus {\n  emit(event: string, payload: unknown, options?: EmitOptions): Promise<void>\n}\n\nconst GLOBAL_EVENT_BUS_KEY = '__openMercatoGlobalEventBus__'\n\n// Global event bus reference (set during bootstrap)\nlet globalEventBus: GlobalEventBus | null = null\n\n/**\n * Set the global event bus instance.\n * Called during app bootstrap to wire up event emission.\n */\nexport function setGlobalEventBus(bus: GlobalEventBus): void {\n  globalEventBus = bus\n  try {\n    ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_BUS_KEY] = bus\n  } catch {\n    // ignore global assignment failures\n  }\n}\n\n/**\n * Get the global event bus instance.\n * Returns null if not yet bootstrapped.\n */\nexport function getGlobalEventBus(): GlobalEventBus | null {\n  try {\n    const sharedBus = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_BUS_KEY]\n    if (sharedBus && typeof sharedBus === 'object' && typeof (sharedBus as GlobalEventBus).emit === 'function') {\n      return sharedBus as GlobalEventBus\n    }\n  } catch {\n    // ignore global read failures\n  }\n  return globalEventBus\n}\n\n// =============================================================================\n// Event Registry for Validation\n// =============================================================================\n\n// Global set of all declared event IDs for runtime validation\nconst allDeclaredEventIds = new Set<string>()\n\n// Global registry of all declared events with their full definitions\nconst allDeclaredEvents: EventDefinition[] = []\n\nfunction addDeclaredEvent(event: EventDefinition): void {\n  allDeclaredEventIds.add(event.id)\n  // Avoid duplicates if createModuleEvents/registerEventModuleConfigs is called multiple times (e.g., HMR)\n  if (!allDeclaredEvents.find(e => e.id === event.id)) {\n    allDeclaredEvents.push(event)\n  }\n}\n\n/**\n * Check if an event ID has been declared by any module.\n * Used for runtime validation to ensure only declared events are emitted.\n */\nexport function isEventDeclared(eventId: string): boolean {\n  return allDeclaredEventIds.has(eventId)\n}\n\n/**\n * Get all declared event IDs.\n * Useful for debugging and introspection.\n */\nexport function getAllDeclaredEventIds(): string[] {\n  return Array.from(allDeclaredEventIds)\n}\n\n/**\n * Get all declared events with their full definitions.\n * Used by the API to return available events for workflow triggers.\n */\nexport function getDeclaredEvents(): EventDefinition[] {\n  return [...allDeclaredEvents]\n}\n\n/**\n * Check if an event has clientBroadcast enabled.\n * Used by the SSE endpoint to filter events for the DOM Event Bridge.\n */\nexport function isBroadcastEvent(eventId: string): boolean {\n  const event = allDeclaredEvents.find(e => e.id === eventId)\n  return event?.clientBroadcast === true\n}\n\n/**\n * Check if an event has portalBroadcast enabled.\n * Used by the portal SSE endpoint to filter events for the Portal Event Bridge.\n */\nexport function isPortalBroadcastEvent(eventId: string): boolean {\n  const event = allDeclaredEvents.find(e => e.id === eventId)\n  return event?.portalBroadcast === true\n}\n\n// =============================================================================\n// Bootstrap Registration (similar to searchModuleConfigs pattern)\n// =============================================================================\n\nlet _registeredEventConfigs: EventModuleConfig[] | null = null\n\n/**\n * Register event module configurations globally.\n * Called during app bootstrap with configs from events.generated.ts.\n */\nexport function registerEventModuleConfigs(configs: EventModuleConfig[]): void {\n  if (_registeredEventConfigs !== null && process.env.NODE_ENV === 'development') {\n    logger.debug('Event module configs re-registered (this may occur during HMR)')\n  }\n  _registeredEventConfigs = configs\n  for (const config of configs) {\n    for (const event of config.events) {\n      addDeclaredEvent(event)\n    }\n  }\n}\n\n/**\n * Get registered event module configurations.\n * Returns empty array if not registered.\n */\nexport function getEventModuleConfigs(): EventModuleConfig[] {\n  return _registeredEventConfigs ?? []\n}\n\n// =============================================================================\n// Factory Function\n// =============================================================================\n\n/**\n * Creates a type-safe event configuration for a module.\n *\n * Usage in module events.ts:\n * ```typescript\n * import { createModuleEvents } from '@open-mercato/shared/modules/events'\n *\n * const events = [\n *   { id: 'customers.people.created', label: 'Person Created', category: 'crud' },\n *   { id: 'customers.people.updated', label: 'Person Updated', category: 'crud' },\n * ] as const\n *\n * export const eventsConfig = createModuleEvents({\n *   moduleId: 'customers',\n *   events,\n * })\n *\n * // Export the typed emit function for use in commands\n * export const emitCustomersEvent = eventsConfig.emit\n *\n * // Export event IDs as a type for external use\n * export type CustomersEventId = typeof events[number]['id']\n *\n * export default eventsConfig\n * ```\n *\n * TypeScript will enforce that only declared event IDs can be emitted:\n * ```typescript\n * // \u2705 This compiles - event is declared\n * emitCustomersEvent('customers.people.created', { id: '123', tenantId: 'abc' })\n *\n * // \u274C TypeScript error - event not declared\n * emitCustomersEvent('customers.people.exploded', { id: '123' })\n * ```\n */\nexport function createModuleEvents<\n  const TEvents extends readonly { id: string }[],\n  TEventIds extends TEvents[number]['id'] = TEvents[number]['id']\n>(options: CreateModuleEventsOptions<TEventIds>): EventModuleConfig<TEventIds> {\n  const { moduleId, events, strict = false } = options\n\n  // Build set of valid event IDs for runtime validation\n  const validEventIds = new Set(events.map(e => e.id))\n\n  // Build full event definitions with module added\n  const fullEvents: EventDefinition[] = events.map(e => ({\n    ...e,\n    module: moduleId,\n  }))\n\n  // Register all event IDs and definitions in the global registry.\n  for (const event of fullEvents) {\n    addDeclaredEvent(event)\n  }\n\n  /**\n   * The emit function - validates events and delegates to the global event bus\n   */\n  const emit = async (\n    eventId: TEventIds,\n    payload: EventPayload,\n    emitOptions?: EmitOptions\n  ): Promise<void> => {\n    // Runtime validation - event must be declared\n    if (!validEventIds.has(eventId)) {\n      const message =\n        `[events] Module \"${moduleId}\" tried to emit undeclared event \"${eventId}\". ` +\n        `Add it to the module's events.ts file first.`\n\n      if (strict) {\n        throw new Error(message)\n      } else {\n        logger.error('Module tried to emit undeclared event \u2014 add it to the module events.ts first', { moduleId, eventId })\n        // In non-strict mode, still emit but with warning\n      }\n    }\n\n    // Get event bus from global reference\n    const eventBus = getGlobalEventBus()\n    if (!eventBus) {\n      logger.warn('Event bus not available, cannot emit event', { eventId })\n      return\n    }\n\n    await eventBus.emit(eventId, payload, emitOptions)\n  }\n\n  return {\n    moduleId,\n    events: fullEvents,\n    emit: emit as unknown as ModuleEventEmitter<TEventIds>,\n  }\n}\n"],
-  "mappings": "AAMA,SAAS,oBAAoB;AAU7B,MAAM,SAAS,aAAa,QAAQ,EAAE,MAAM,EAAE,WAAW,UAAU,CAAC;AAapE,MAAM,uBAAuB;AAG7B,IAAI,iBAAwC;AAMrC,SAAS,kBAAkB,KAA2B;AAC3D,mBAAiB;AACjB,MAAI;AACF;AAAC,IAAC,WAAuC,oBAAoB,IAAI;AAAA,EACnE,QAAQ;AAAA,EAER;AACF;AAMO,SAAS,oBAA2C;AACzD,MAAI;AACF,UAAM,YAAa,WAAuC,oBAAoB;AAC9E,QAAI,aAAa,OAAO,cAAc,YAAY,OAAQ,UAA6B,SAAS,YAAY;AAC1G,aAAO;AAAA,IACT;AAAA,EACF,QAAQ;AAAA,EAER;AACA,SAAO;AACT;AAOA,MAAM,sBAAsB,oBAAI,IAAY;AAG5C,MAAM,oBAAuC,CAAC;AAE9C,SAAS,iBAAiB,OAA8B;AACtD,sBAAoB,IAAI,MAAM,EAAE;AAEhC,MAAI,CAAC,kBAAkB,KAAK,OAAK,EAAE,OAAO,MAAM,EAAE,GAAG;AACnD,sBAAkB,KAAK,KAAK;AAAA,EAC9B;AACF;AAMO,SAAS,gBAAgB,SAA0B;AACxD,SAAO,oBAAoB,IAAI,OAAO;AACxC;AAMO,SAAS,yBAAmC;AACjD,SAAO,MAAM,KAAK,mBAAmB;AACvC;AAMO,SAAS,oBAAuC;AACrD,SAAO,CAAC,GAAG,iBAAiB;AAC9B;AAMO,SAAS,iBAAiB,SAA0B;AACzD,QAAM,QAAQ,kBAAkB,KAAK,OAAK,EAAE,OAAO,OAAO;AAC1D,SAAO,OAAO,oBAAoB;AACpC;AAMO,SAAS,uBAAuB,SAA0B;AAC/D,QAAM,QAAQ,kBAAkB,KAAK,OAAK,EAAE,OAAO,OAAO;AAC1D,SAAO,OAAO,oBAAoB;AACpC;AAMA,IAAI,0BAAsD;AAMnD,SAAS,2BAA2B,SAAoC;AAC7E,MAAI,4BAA4B,QAAQ,QAAQ,IAAI,aAAa,eAAe;AAC9E,WAAO,MAAM,gEAAgE;AAAA,EAC/E;AACA,4BAA0B;AAC1B,aAAW,UAAU,SAAS;AAC5B,eAAW,SAAS,OAAO,QAAQ;AACjC,uBAAiB,KAAK;AAAA,IACxB;AAAA,EACF;AACF;AAMO,SAAS,wBAA6C;AAC3D,SAAO,2BAA2B,CAAC;AACrC;AAyCO,SAAS,mBAGd,SAA6E;AAC7E,QAAM,EAAE,UAAU,QAAQ,SAAS,MAAM,IAAI;AAG7C,QAAM,gBAAgB,IAAI,IAAI,OAAO,IAAI,OAAK,EAAE,EAAE,CAAC;AAGnD,QAAM,aAAgC,OAAO,IAAI,QAAM;AAAA,IACrD,GAAG;AAAA,IACH,QAAQ;AAAA,EACV,EAAE;AAGF,aAAW,SAAS,YAAY;AAC9B,qBAAiB,KAAK;AAAA,EACxB;AAKA,QAAM,OAAO,OACX,SACA,SACA,gBACkB;AAElB,QAAI,CAAC,cAAc,IAAI,OAAO,GAAG;AAC/B,YAAM,UACJ,oBAAoB,QAAQ,qCAAqC,OAAO;AAG1E,UAAI,QAAQ;AACV,cAAM,IAAI,MAAM,OAAO;AAAA,MACzB,OAAO;AACL,eAAO,MAAM,qFAAgF,EAAE,UAAU,QAAQ,CAAC;AAAA,MAEpH;AAAA,IACF;AAGA,UAAM,WAAW,kBAAkB;AACnC,QAAI,CAAC,UAAU;AACb,aAAO,KAAK,8CAA8C,EAAE,QAAQ,CAAC;AACrE;AAAA,IACF;AAEA,UAAM,SAAS,KAAK,SAAS,SAAS,WAAW;AAAA,EACnD;AAEA,SAAO;AAAA,IACL;AAAA,IACA,QAAQ;AAAA,IACR;AAAA,EACF;AACF;",
+  "sourcesContent": ["/**\n * Event Module Factory\n *\n * Provides factory functions for creating type-safe event configurations.\n */\n\nimport { createLogger } from '../../lib/logger'\nimport type {\n  EventDefinition,\n  EventModuleConfig,\n  EventPayload,\n  EmitOptions,\n  CreateModuleEventsOptions,\n  ModuleEventEmitter,\n} from './types'\n\nconst logger = createLogger('events').child({ component: 'factory' })\n\n// =============================================================================\n// Global Event Bus Reference\n// =============================================================================\n\n/**\n * Type for the global event bus interface\n */\ninterface GlobalEventBus {\n  emit(event: string, payload: unknown, options?: EmitOptions): Promise<void>\n}\n\nconst GLOBAL_EVENT_BUS_KEY = '__openMercatoGlobalEventBus__'\n\n// Global event bus reference (set during bootstrap)\nlet globalEventBus: GlobalEventBus | null = null\n\n/**\n * Set the global event bus instance.\n * Called during app bootstrap to wire up event emission.\n */\nexport function setGlobalEventBus(bus: GlobalEventBus): void {\n  globalEventBus = bus\n  try {\n    ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_BUS_KEY] = bus\n  } catch {\n    // ignore global assignment failures\n  }\n}\n\n/**\n * Get the global event bus instance.\n * Returns null if not yet bootstrapped.\n */\nexport function getGlobalEventBus(): GlobalEventBus | null {\n  try {\n    const sharedBus = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_BUS_KEY]\n    if (sharedBus && typeof sharedBus === 'object' && typeof (sharedBus as GlobalEventBus).emit === 'function') {\n      return sharedBus as GlobalEventBus\n    }\n  } catch {\n    // ignore global read failures\n  }\n  return globalEventBus\n}\n\n// =============================================================================\n// Event Registry for Validation\n// =============================================================================\n\ntype EventRegistryState = {\n  declaredEventIds: Set<string>\n  declaredEvents: EventDefinition[]\n  registeredEventConfigs: EventModuleConfig[] | null\n}\n\nconst GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'\n\nconst fallbackEventRegistryState: EventRegistryState = {\n  declaredEventIds: new Set<string>(),\n  declaredEvents: [],\n  registeredEventConfigs: null,\n}\n\nfunction isEventRegistryState(value: unknown): value is EventRegistryState {\n  if (!value || typeof value !== 'object') return false\n  const candidate = value as Partial<EventRegistryState>\n  return candidate.declaredEventIds instanceof Set\n    && Array.isArray(candidate.declaredEvents)\n    && (candidate.registeredEventConfigs === null || Array.isArray(candidate.registeredEventConfigs))\n}\n\nfunction getEventRegistryState(): EventRegistryState {\n  try {\n    const globalScope = globalThis as Record<string, unknown>\n    const existing = globalScope[GLOBAL_EVENT_REGISTRY_KEY]\n    if (isEventRegistryState(existing)) return existing\n    globalScope[GLOBAL_EVENT_REGISTRY_KEY] = fallbackEventRegistryState\n    return fallbackEventRegistryState\n  } catch {\n    // Restricted runtimes may deny global access. Keep the previous\n    // module-local behavior as a safe fallback.\n    return fallbackEventRegistryState\n  }\n}\n\nfunction addDeclaredEvent(event: EventDefinition): void {\n  const state = getEventRegistryState()\n  state.declaredEventIds.add(event.id)\n  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === event.id)\n  if (existingIndex < 0) {\n    state.declaredEvents.push(event)\n    return\n  }\n  // Refresh a module's own definition in place during HMR without allowing a\n  // duplicate declaration from another module to take over the event id.\n  if (state.declaredEvents[existingIndex]?.module === event.module) {\n    state.declaredEvents[existingIndex] = event\n  }\n}\n\n/**\n * Check if an event ID has been declared by any module.\n * Used for runtime validation to ensure only declared events are emitted.\n */\nexport function isEventDeclared(eventId: string): boolean {\n  return getEventRegistryState().declaredEventIds.has(eventId)\n}\n\n/**\n * Get all declared event IDs.\n * Useful for debugging and introspection.\n */\nexport function getAllDeclaredEventIds(): string[] {\n  return Array.from(getEventRegistryState().declaredEventIds)\n}\n\n/**\n * Get all declared events with their full definitions.\n * Used by the API to return available events for workflow triggers.\n */\nexport function getDeclaredEvents(): EventDefinition[] {\n  return [...getEventRegistryState().declaredEvents]\n}\n\n/**\n * Check if an event has clientBroadcast enabled.\n * Used by the SSE endpoint to filter events for the DOM Event Bridge.\n */\nexport function isBroadcastEvent(eventId: string): boolean {\n  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)\n  return event?.clientBroadcast === true\n}\n\n/**\n * Check if an event should be published over the server-to-server event bridge.\n * Browser-broadcast events remain eligible for backward compatibility, while\n * crossProcessBroadcast supports private process coordination without SSE.\n */\nexport function isCrossProcessBroadcastEvent(eventId: string): boolean {\n  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)\n  return event?.clientBroadcast === true || event?.crossProcessBroadcast === true\n}\n\n/**\n * Check whether an event is reserved for private server-to-server\n * coordination. Workflow-authored EMIT_EVENT activities must not emit these\n * events because their payload and event id are tenant-managed input.\n */\nexport function isPrivateCrossProcessBroadcastEvent(eventId: string): boolean {\n  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)\n  return event?.crossProcessBroadcast === true && event?.clientBroadcast !== true\n}\n\n/**\n * Verify provenance for a private cross-process event. The module id is\n * stamped by a declared module emitter or another trusted server-side seam;\n * tenant-managed event payloads never participate in this decision.\n */\nexport function isPrivateCrossProcessEventEmitter(\n  eventId: string,\n  emitterModuleId: string | undefined,\n): boolean {\n  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)\n  if (event?.crossProcessBroadcast !== true) return true\n  return typeof event.module === 'string'\n    && event.module.length > 0\n    && event.module === emitterModuleId\n}\n\n/**\n * Check if an event has portalBroadcast enabled.\n * Used by the portal SSE endpoint to filter events for the Portal Event Bridge.\n */\nexport function isPortalBroadcastEvent(eventId: string): boolean {\n  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)\n  return event?.portalBroadcast === true\n}\n\n// =============================================================================\n// Bootstrap Registration (similar to searchModuleConfigs pattern)\n// =============================================================================\n\n/**\n * Register event module configurations globally.\n * Called during app bootstrap with configs from events.generated.ts.\n */\nexport function registerEventModuleConfigs(configs: EventModuleConfig[]): void {\n  const state = getEventRegistryState()\n  if (state.registeredEventConfigs !== null && process.env.NODE_ENV === 'development') {\n    logger.debug('Event module configs re-registered (this may occur during HMR)')\n  }\n  state.registeredEventConfigs = configs\n  for (const config of configs) {\n    for (const event of config.events) {\n      addDeclaredEvent(event)\n    }\n  }\n}\n\n/**\n * Get registered event module configurations.\n * Returns empty array if not registered.\n */\nexport function getEventModuleConfigs(): EventModuleConfig[] {\n  return getEventRegistryState().registeredEventConfigs ?? []\n}\n\n// =============================================================================\n// Factory Function\n// =============================================================================\n\n/**\n * Creates a type-safe event configuration for a module.\n *\n * Usage in module events.ts:\n * ```typescript\n * import { createModuleEvents } from '@open-mercato/shared/modules/events'\n *\n * const events = [\n *   { id: 'customers.people.created', label: 'Person Created', category: 'crud' },\n *   { id: 'customers.people.updated', label: 'Person Updated', category: 'crud' },\n * ] as const\n *\n * export const eventsConfig = createModuleEvents({\n *   moduleId: 'customers',\n *   events,\n * })\n *\n * // Export the typed emit function for use in commands\n * export const emitCustomersEvent = eventsConfig.emit\n *\n * // Export event IDs as a type for external use\n * export type CustomersEventId = typeof events[number]['id']\n *\n * export default eventsConfig\n * ```\n *\n * TypeScript will enforce that only declared event IDs can be emitted:\n * ```typescript\n * // \u2705 This compiles - event is declared\n * emitCustomersEvent('customers.people.created', { id: '123', tenantId: 'abc' })\n *\n * // \u274C TypeScript error - event not declared\n * emitCustomersEvent('customers.people.exploded', { id: '123' })\n * ```\n */\nexport function createModuleEvents<\n  const TEvents extends readonly { id: string }[],\n  TEventIds extends TEvents[number]['id'] = TEvents[number]['id']\n>(options: CreateModuleEventsOptions<TEventIds>): EventModuleConfig<TEventIds> {\n  const { moduleId, events, strict = false } = options\n\n  // Build set of valid event IDs for runtime validation\n  const validEventIds = new Set(events.map(e => e.id))\n\n  // Build full event definitions with module added\n  const fullEvents: EventDefinition[] = events.map(e => ({\n    ...e,\n    module: moduleId,\n  }))\n\n  // Register all event IDs and definitions in the global registry.\n  for (const event of fullEvents) {\n    addDeclaredEvent(event)\n  }\n\n  /**\n   * The emit function - validates events and delegates to the global event bus\n   */\n  const emit = async (\n    eventId: TEventIds,\n    payload: EventPayload,\n    emitOptions?: EmitOptions\n  ): Promise<void> => {\n    // Runtime validation - event must be declared\n    if (!validEventIds.has(eventId)) {\n      const message =\n        `[events] Module \"${moduleId}\" tried to emit undeclared event \"${eventId}\". ` +\n        `Add it to the module's events.ts file first.`\n\n      if (strict) {\n        throw new Error(message)\n      } else {\n        logger.error('Module tried to emit undeclared event \u2014 add it to the module events.ts first', { moduleId, eventId })\n        // In non-strict mode, still emit but with warning\n      }\n    }\n\n    // Get event bus from global reference\n    const eventBus = getGlobalEventBus()\n    if (!eventBus) {\n      logger.warn('Event bus not available, cannot emit event', { eventId })\n      return\n    }\n\n    const eventDefinition = fullEvents.find((event) => event.id === eventId)\n    const isClientBroadcast = eventDefinition?.clientBroadcast === true\n    const trustedOptions = eventDefinition?.crossProcessBroadcast === true || isClientBroadcast\n      ? {\n          ...emitOptions,\n          // Browser-broadcast module emitters historically accepted scope in\n          // their typed payload. Preserve that contract at the trusted module\n          // boundary while the event bus itself relies only on options.\n          ...(isClientBroadcast && emitOptions?.tenantId === undefined\n            ? { tenantId: payload.tenantId ?? null }\n            : {}),\n          ...(isClientBroadcast && emitOptions?.organizationId === undefined\n            ? { organizationId: payload.organizationId ?? null }\n            : {}),\n          ...(isClientBroadcast && emitOptions?.organizationIds === undefined && Array.isArray(payload.organizationIds)\n            ? { organizationIds: payload.organizationIds.filter((value): value is string => typeof value === 'string') }\n            : {}),\n          emitterModuleId: moduleId,\n        }\n      : emitOptions\n    await eventBus.emit(eventId, payload, trustedOptions)\n  }\n\n  return {\n    moduleId,\n    events: fullEvents,\n    emit: emit as unknown as ModuleEventEmitter<TEventIds>,\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.7013.1.48f7adca80",
+  "version": "0.6.8-develop.7016.1.4ed7b1e49d",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,6 +40,10 @@
       "types": "./src/lib/bootstrap/dynamicLoader.ts",
       "default": "./dist/lib/bootstrap/dynamicLoader.js"
     },
+    "./lib/auth/principal-service": {
+      "types": "./src/lib/auth/principal-service.ts",
+      "default": "./dist/lib/auth/principal-service.js"
+    },
     "./lib/webhooks": {
       "types": "./src/lib/webhooks/index.ts",
       "default": "./dist/lib/webhooks/index.js"
@@ -105,7 +109,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.7013.1.48f7adca80",
+    "@open-mercato/cache": "0.6.8-develop.7016.1.4ed7b1e49d",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/auth/__tests__/principalServiceExport.test.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..', '..')
+const SUBPATH = './lib/auth/principal-service'
+
+type ExportTarget = { types?: string | string[]; default?: string }
+
+function readExports(): Record<string, ExportTarget | string> {
+  const packageJson = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')) as {
+    exports?: Record<string, ExportTarget | string>
+  }
+  return packageJson.exports ?? {}
+}
+
+/**
+ * Node's subpath resolution: an exact key wins outright, and only when none
+ * matches do the `*` patterns compete on the longest static prefix. Mirroring
+ * it here is the point of the test — a subpath that resolves only through a
+ * wildcard is at the mercy of whichever resolver a consumer happens to run
+ * (packed tarball, bundler, Jest), and those do not agree on wildcard handling.
+ */
+function resolveSubpath(exports: Record<string, ExportTarget | string>, subpath: string): string | null {
+  if (Object.prototype.hasOwnProperty.call(exports, subpath)) return subpath
+  let best: string | null = null
+  for (const key of Object.keys(exports)) {
+    const star = key.indexOf('*')
+    if (star < 0) continue
+    const prefix = key.slice(0, star)
+    const suffix = key.slice(star + 1)
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue
+    if (subpath.length < prefix.length + suffix.length) continue
+    if (!best || prefix.length > best.slice(0, best.indexOf('*')).length) best = key
+  }
+  return best
+}
+
+describe('@open-mercato/shared principal-service export map', () => {
+  const exports = readExports()
+
+  it('resolves through an explicit entry rather than a wildcard pattern', () => {
+    expect(resolveSubpath(exports, SUBPATH)).toBe(SUBPATH)
+  })
+
+  it('maps types to the source module and default to the built module', () => {
+    const target = exports[SUBPATH]
+    expect(typeof target).toBe('object')
+    expect(target).toEqual({
+      types: './src/lib/auth/principal-service.ts',
+      default: './dist/lib/auth/principal-service.js',
+    })
+  })
+
+  // Both halves of the mapping must exist in a packed package. `default` is
+  // produced by `yarn build:packages`, which the validation gate runs before
+  // `yarn test`.
+  it('ships both mapped files', () => {
+    const target = exports[SUBPATH] as ExportTarget
+    expect(existsSync(join(PACKAGE_ROOT, target.types as string))).toBe(true)
+    expect(existsSync(join(PACKAGE_ROOT, target.default as string))).toBe(true)
+  })
+
+  it('keeps the module importable under the mapped default condition', async () => {
+    const target = exports[SUBPATH] as ExportTarget
+    await expect(import(join(PACKAGE_ROOT, target.default as string))).resolves.toBeDefined()
+  })
+})

package/src/lib/auth/__tests__/server.apiKeyCache.test.ts

@@ -94,6 +94,244 @@ describe('resolveApiKeyAuth caching + lastUsedAt debounce', () => {
     expect(emFlush).toHaveBeenCalledTimes(1)
   })
 
+  it('retains the creator identity for a regular tenant-scoped key', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-tenant-scoped',
+      name: 'tenant scoped',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-1', organizationId: 'creator-org' }
+      }
+      return null
+    })
+
+    const auth = await getAuthFromRequest(buildRequest('tenant-scoped-secret'))
+
+    expect(auth).toMatchObject({
+      sub: 'api_key:key-tenant-scoped',
+      tenantId: 'tenant-1',
+      orgId: null,
+      isApiKey: true,
+      keyId: 'key-tenant-scoped',
+      userId: 'creator-1',
+    })
+    // The creator remains the key's legacy identity, but its concrete
+    // organization does not narrow a tenant-scoped key.
+    expect(emFindOne).toHaveBeenCalledWith(
+      expect.anything(),
+      { id: 'creator-1', deletedAt: null },
+    )
+  })
+
+  it('rejects a tenant-scoped regular key once its creator is soft-deleted', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-deleted-creator',
+      name: 'deleted creator',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('deleted-creator-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('rejects a tenant-scoped regular key whose creator moved to another tenant', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-foreign-creator',
+      name: 'foreign creator',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-2', organizationId: null }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('foreign-creator-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('accepts a tenant-scoped regular key that records no creator', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-no-creator',
+      name: 'no creator',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: null,
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('no-creator-secret')),
+    ).resolves.toMatchObject({ keyId: 'key-no-creator', tenantId: 'tenant-1' })
+  })
+
+  it('retains the creator identity for an organization-scoped regular key', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-organization-scoped',
+      name: 'organization scoped',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-1', organizationId: 'org-1' }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('organization-scoped-secret')),
+    ).resolves.toMatchObject({
+      sub: 'api_key:key-organization-scoped',
+      tenantId: 'tenant-1',
+      orgId: 'org-1',
+      userId: 'creator-1',
+    })
+  })
+
+  it('rejects an organization-scoped regular key when its creator scope no longer matches', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-organization-mismatch',
+      name: 'organization mismatch',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-1', organizationId: 'org-2' }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('organization-scope-mismatch-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('keeps session keys strictly bound to their persisted user and scope', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-session-scoped',
+      name: 'session scoped',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: 'sess_123',
+      sessionUserId: 'session-user-1',
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'session-user-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'session-user-1') {
+        return { id: 'session-user-1', tenantId: 'tenant-1', organizationId: 'user-org' }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('session-scope-mismatch-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('fails closed when a row has session markers but no bound session user', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-malformed-session',
+      name: 'malformed session',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: 'sess_missing_user',
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('malformed-session-secret')),
+    ).resolves.toBeNull()
+    expect(emFindOne).not.toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ id: 'creator-1' }),
+    )
+  })
+
   it('caches negative lookups so invalid keys skip the bcrypt+DB path', async () => {
     const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
     findApiKeyBySecret.mockResolvedValue(null)
@@ -128,4 +366,90 @@ describe('resolveApiKeyAuth caching + lastUsedAt debounce', () => {
     await getAuthFromRequest(buildRequest('secret-invalidate'))
     expect(findApiKeyBySecret).toHaveBeenCalledTimes(2)
   })
+
+  describe('super-admin bit stays bounded by the effective key scope', () => {
+    async function resolveWithSuperAdminRole(input: {
+      secret: string
+      keyId: string
+      keyOrganizationId: string | null
+      aclOrganizations: string[] | null
+    }) {
+      const { RoleAcl } = await import('@open-mercato/core/modules/auth/data/entities')
+      const { Organization, Tenant } = await import('@open-mercato/core/modules/directory/data/entities')
+      const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+      // A creator-less key is validated against a live tenant (and organization when bound).
+      emFindOne.mockImplementation(async (entity: unknown) => {
+        if (entity === Tenant) return { id: 'tenant-1' }
+        if (entity === Organization) return { id: input.keyOrganizationId, tenant: { id: 'tenant-1' } }
+        return null
+      })
+      findApiKeyBySecret.mockResolvedValue({
+        id: input.keyId,
+        name: 'super admin key',
+        tenantId: 'tenant-1',
+        organizationId: input.keyOrganizationId,
+        rolesJson: ['role-super'],
+        sessionToken: null,
+        sessionUserId: null,
+        sessionSecretEncrypted: null,
+        opencodeSessionId: null,
+        createdBy: null,
+        expiresAt: null,
+        lastUsedAt: null,
+      })
+      emFind.mockImplementation(async (entity: unknown) => {
+        if (entity === RoleAcl) {
+          return [{ isSuperAdmin: true, organizationsJson: input.aclOrganizations }]
+        }
+        return []
+      })
+      return getAuthFromRequest(buildRequest(input.secret))
+    }
+
+    it('withholds it from an organization-bound key even when a role grants it', async () => {
+      // Generic guards trust this bit before live RBAC, so an organization-restricted key must
+      // never take super-admin shortcuts outside its own scope.
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-bound',
+        keyId: 'key-super-bound',
+        keyOrganizationId: 'org-1',
+        aclOrganizations: null,
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: false })
+    })
+
+    it('withholds it when the granting role ACL is itself organization-restricted', async () => {
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-restricted',
+        keyId: 'key-super-restricted',
+        keyOrganizationId: null,
+        aclOrganizations: ['org-1'],
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: false })
+    })
+
+    it('grants it for an unbound key with an unrestricted role grant', async () => {
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-global',
+        keyId: 'key-super-global',
+        keyOrganizationId: null,
+        aclOrganizations: null,
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: true })
+    })
+
+    it('grants it for an unbound key whose role ACL uses the __all__ sentinel', async () => {
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-all-sentinel',
+        keyId: 'key-super-all-sentinel',
+        keyOrganizationId: null,
+        aclOrganizations: ['__all__'],
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: true })
+    })
+  })
 })

package/src/lib/auth/principal-service.ts

@@ -0,0 +1,110 @@
+import type { AuthContext } from './server'
+
+export type PrincipalScope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type AuthPrincipalType = 'user' | 'role'
+
+export type AuthPrincipalLabel = {
+  id: string
+  label: string
+  secondary: string | null
+}
+
+export type AuthPrincipalRolePage = {
+  items: AuthPrincipalLabel[]
+  page: number
+  pageSize: number
+  total: number
+}
+
+/** Public, request-scoped read boundary owned by the Auth module. */
+export interface AuthPrincipalService {
+  principalExists(input: {
+    type: AuthPrincipalType
+    id: string
+    scope: PrincipalScope
+  }): Promise<boolean>
+  resolveActiveUserRoleIds(userId: string, scope: PrincipalScope): Promise<string[]>
+  filterActiveRoleIds(roleIds: string[], scope: PrincipalScope): Promise<string[]>
+  resolveLabels(input: {
+    type: AuthPrincipalType
+    ids: string[]
+    scope: PrincipalScope
+  }): Promise<AuthPrincipalLabel[]>
+  /**
+   * Optional additive capability for organization-eligible role pickers.
+   * Implementations must apply eligibility before pagination and bound the
+   * advertised result window so sparse ACL matches cannot amplify requests.
+   */
+  queryActiveRolePage?(input: {
+    scope: PrincipalScope
+    search?: string
+    excludedIds?: string[]
+    page: number
+    pageSize: number
+  }): Promise<AuthPrincipalRolePage>
+  listSuperAdminUserIds(tenantId: string): Promise<string[]>
+}
+
+/** Public, request-scoped read boundary owned by the API Keys module. */
+export interface ApiKeyPrincipalService {
+  resolveAssignedRoleIds(apiKeyId: string, scope: PrincipalScope): Promise<string[]>
+}
+
+export type OrganizationScope = {
+  selectedId: string | null
+  filterIds: string[] | null
+  allowedIds: string[] | null
+  tenantId: string | null
+  // True when an explicit organization selection could not be honored. Reads
+  // fall back to the caller's accessible organizations; writes must fail.
+  selectionRejected?: boolean
+}
+
+export type OrganizationScopeAcl = {
+  isSuperAdmin: boolean
+  features: string[]
+  organizations: string[] | null
+}
+
+export type OrganizationScopeRequest = Request | {
+  cookies?: { get: (name: string) => { value: string } | undefined }
+  headers?: { get(name: string): string | null }
+}
+
+/**
+ * Narrow, request-scoped hierarchy boundary owned by Directory.
+ *
+ * `null` means the selected organization does not exist in the requested
+ * tenant. An empty array means it exists but has no ancestors.
+ */
+export interface OrganizationHierarchyService {
+  resolveAncestorIds(input: {
+    tenantId: string
+    organizationId: string
+  }): Promise<string[] | null>
+}
+
+/** Public, request-scoped organization expansion boundary owned by Directory. */
+export interface OrganizationScopeService {
+  resolve(input: {
+    auth: AuthContext | null | undefined
+    selectedId?: string | null
+    tenantId?: string | null
+    freshAcl?: boolean
+  }): Promise<OrganizationScope>
+  resolveFresh(input: {
+    auth: NonNullable<AuthContext>
+    selectedId?: string | null
+    tenantId?: string | null
+  }): Promise<{ scope: OrganizationScope; acl: OrganizationScopeAcl }>
+  resolveForRequest(input: {
+    auth: AuthContext | null | undefined
+    request?: OrganizationScopeRequest
+    selectedId?: string | null
+    tenantId?: string | null
+  }): Promise<OrganizationScope>
+}