@open-mercato/shared 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

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

@@ -10,6 +10,7 @@ jest.mock('next/headers', () => ({
 }))
 
 jest.mock('@open-mercato/shared/lib/auth/jwt', () => ({
+  ...jest.requireActual('@open-mercato/shared/lib/auth/jwt'),
   verifyJwt: (...args: unknown[]) => verifyJwt(...args),
 }))
 
@@ -162,6 +163,109 @@ describe('auth server integrity checks', () => {
     await expect(getAuthFromRequest(request)).resolves.toBeNull()
   })
 
+  describe('mfa-pending staff tokens', () => {
+    const pendingAuth = {
+      sub: '11111111-1111-4111-8111-111111111111',
+      sid: '44444444-4444-4444-8444-444444444444',
+      tenantId: '22222222-2222-4222-8222-222222222222',
+      orgId: '33333333-3333-4333-8333-333333333333',
+      roles: ['admin'],
+      mfa_pending: true,
+      mfa_verified: false,
+    }
+
+    function mfaPendingRequest(path: string, method: string): Request {
+      return new Request(`https://example.test${path}`, {
+        method,
+        headers: { authorization: `Bearer pending-token` },
+      })
+    }
+
+    beforeEach(async () => {
+      // The registry ships empty; completion routes are registered by their owning module
+      // (enterprise security). Register equivalent fixtures to exercise resolver mechanics.
+      const { registerMfaPendingAccessRoutes } = await import('../mfaPendingAccess')
+      registerMfaPendingAccessRoutes([
+        { path: '/api/security/mfa/prepare', methods: ['POST'] },
+        { path: '/api/security/mfa/verify', methods: ['POST'] },
+        { path: '/api/security/mfa/recovery', methods: ['POST'] },
+      ])
+      verifyJwt.mockReturnValue(pendingAuth)
+      resolveCanonicalStaffAuthContext.mockResolvedValue({ ...pendingAuth })
+    })
+
+    it('rejects a pending token on a general staff API before roles are restored', async () => {
+      const { resolveAuthFromRequestDetailed } = await import('@open-mercato/shared/lib/auth/server')
+
+      await expect(resolveAuthFromRequestDetailed(mfaPendingRequest('/api/customers/people', 'GET')))
+        .resolves.toEqual({ auth: null, status: 'invalid' })
+      expect(resolveCanonicalStaffAuthContext).not.toHaveBeenCalled()
+    })
+
+    it('still resolves a pending token on the registered MFA completion routes (POST)', async () => {
+      const { resolveAuthFromRequestDetailed } = await import('@open-mercato/shared/lib/auth/server')
+
+      for (const path of ['/api/security/mfa/prepare', '/api/security/mfa/verify', '/api/security/mfa/recovery']) {
+        resolveCanonicalStaffAuthContext.mockClear()
+        const resolution = await resolveAuthFromRequestDetailed(mfaPendingRequest(path, 'POST'))
+        expect(resolution.status).toBe('authenticated')
+        expect(resolution.auth).toEqual({ ...pendingAuth })
+        expect(resolveCanonicalStaffAuthContext).toHaveBeenCalledWith(em, pendingAuth)
+      }
+    })
+
+    it('rejects a pending token with a non-completion method on a completion route', async () => {
+      const { resolveAuthFromRequestDetailed } = await import('@open-mercato/shared/lib/auth/server')
+
+      await expect(resolveAuthFromRequestDetailed(mfaPendingRequest('/api/security/mfa/verify', 'GET')))
+        .resolves.toEqual({ auth: null, status: 'invalid' })
+      expect(resolveCanonicalStaffAuthContext).not.toHaveBeenCalled()
+    })
+
+    it('resolves the verified replacement token like a normal login', async () => {
+      const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+      const verifiedAuth = { ...pendingAuth, mfa_pending: false, mfa_verified: true }
+      verifyJwt.mockReturnValue(verifiedAuth)
+      resolveCanonicalStaffAuthContext.mockResolvedValue({ ...verifiedAuth, roles: ['employee'] })
+
+      const request = new Request('https://example.test/api/customers/people', {
+        headers: { authorization: 'Bearer verified-token' },
+      })
+
+      await expect(getAuthFromRequest(request)).resolves.toEqual({ ...verifiedAuth, roles: ['employee'] })
+      expect(resolveCanonicalStaffAuthContext).toHaveBeenCalledWith(em, verifiedAuth)
+    })
+
+    it('leaves tokens without MFA claims untouched', async () => {
+      const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+      const plainAuth = {
+        sub: '11111111-1111-4111-8111-111111111111',
+        tenantId: '22222222-2222-4222-8222-222222222222',
+        orgId: '33333333-3333-4333-8333-333333333333',
+        roles: [],
+      }
+      verifyJwt.mockReturnValue(plainAuth)
+      resolveCanonicalStaffAuthContext.mockResolvedValue(plainAuth)
+
+      const request = new Request('https://example.test/api/test', {
+        headers: { cookie: 'auth_token=jwt-token' },
+      })
+
+      await expect(getAuthFromRequest(request)).resolves.toEqual(plainAuth)
+    })
+
+    it('rejects a pending token from cookie-based page resolution unconditionally', async () => {
+      const { getAuthFromCookies, resolveAuthFromCookiesDetailed } = await import('@open-mercato/shared/lib/auth/server')
+      cookieStore.get.mockImplementation((name: string) => {
+        if (name === 'auth_token') return { value: 'pending-jwt-token' }
+        return undefined
+      })
+
+      await expect(getAuthFromCookies()).resolves.toBeNull()
+      await expect(resolveAuthFromCookiesDetailed()).resolves.toEqual({ auth: null, status: 'invalid' })
+      expect(resolveCanonicalStaffAuthContext).not.toHaveBeenCalled()
+    })
+  })
   it('reports a transient DB failure on the api-key path as "error" (retryable 503)', async () => {
     const { resolveAuthFromRequestDetailed } = await import('@open-mercato/shared/lib/auth/server')
     // Distinct secret so the shared api-key auth cache does not serve a prior miss.

package/src/lib/auth/jwt.ts

@@ -377,3 +377,20 @@ export function signAudienceJwt(
 export function verifyAudienceJwt(audience: string, token: string): JwtPayload | null {
   return verifyJwt(token, { audience })
 }
+
+/**
+ * True when a verified JWT payload represents an MFA challenge in progress: the second factor
+ * has not been completed yet (`mfa_pending: true`, `mfa_verified` not `true`). Such tokens are
+ * provisional — general staff APIs must reject them and only the MFA completion routes may
+ * accept them (see `@open-mercato/shared/lib/auth/mfaPendingAccess`).
+ *
+ * The predicate keys on `mfa_pending` alone by design. `mfa_verified` is NOT a durable session
+ * property: routes that legitimately re-sign a staff token (`PUT /api/auth/profile`,
+ * `GET|POST /api/auth/session/refresh`) rebuild the claims without it. Tightening this to require
+ * `mfa_verified === true` would therefore silently downgrade those sessions.
+ */
+export function isMfaPendingJwtPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') return false
+  const record = payload as Record<string, unknown>
+  return record.mfa_pending === true && record.mfa_verified !== true
+}

package/src/lib/auth/mfaPendingAccess.ts

@@ -0,0 +1,70 @@
+export type MfaPendingAccessRoute = {
+  path: string
+  methods: string[]
+}
+
+const registeredMethodsByPath = new Map<string, Set<string>>()
+
+function normalizePath(path: string): string | null {
+  if (typeof path !== 'string') return null
+  const trimmed = path.trim()
+  if (!trimmed || !trimmed.startsWith('/')) return null
+  return (trimmed.length > 1 ? trimmed.replace(/\/+$/, '') : trimmed).toLowerCase() || '/'
+}
+
+function normalizeMethods(methods: unknown): string[] {
+  if (!Array.isArray(methods)) return []
+  const normalized = methods
+    .filter((method): method is string => typeof method === 'string' && method.trim().length > 0)
+    .map((method) => method.trim().toUpperCase())
+  return Array.from(new Set(normalized)).sort((first, second) => (first < second ? -1 : first > second ? 1 : 0))
+}
+
+/**
+ * Register routes that may accept an MFA-pending staff token. The registry starts empty and
+ * stays generic: every module that completes an MFA challenge on its own endpoints registers
+ * them here during its bootstrap — the canonical `/api/security/mfa/*` completion routes are
+ * registered by the enterprise `security` module (`lib/mfaCompletionRoutes.ts`), third-party
+ * MFA implementations register theirs the same way. Registration is additive: methods merge
+ * into any existing entry for the same path and are never removed.
+ *
+ * Contract defined in `.ai/specs/enterprise/implemented/SPEC-ENT-007-2026-03-06-auth-login-interceptors-extension.md`
+ * (§ Amendment 2026-08-21 — central MFA-pending token gate).
+ */
+export function registerMfaPendingAccessRoutes(routes: MfaPendingAccessRoute[]): void {
+  for (const route of Array.isArray(routes) ? routes : []) {
+    const path = normalizePath(route?.path ?? '')
+    const methods = normalizeMethods(route?.methods)
+    if (!path || !methods.length) continue
+    const existing = registeredMethodsByPath.get(path)
+    if (!existing) {
+      registeredMethodsByPath.set(path, new Set(methods))
+      continue
+    }
+    for (const method of methods) existing.add(method)
+  }
+}
+
+/**
+ * Fail-closed check deciding whether an MFA-pending staff token may be resolved for this exact
+ * method + path pair. Only explicitly registered completion routes pass; every unregistered
+ * request is denied.
+ */
+export function isMfaPendingAccessAllowed(
+  method: string | null | undefined,
+  pathname: string | null | undefined,
+): boolean {
+  const path = normalizePath(typeof pathname === 'string' ? pathname : '')
+  if (!path) return false
+  if (typeof method !== 'string' || method.trim().length === 0) return false
+  const methods = registeredMethodsByPath.get(path)
+  if (!methods) return false
+  return methods.has(method.trim().toUpperCase())
+}
+
+/** Test/ops helper: current snapshot of the pending-access registry. */
+export function listMfaPendingAccessRoutes(): ReadonlyArray<Readonly<MfaPendingAccessRoute>> {
+  return Array.from(registeredMethodsByPath.entries())
+    .map(([path, methods]) => ({ path, methods: Array.from(methods).sort((first, second) => (first < second ? -1 : first > second ? 1 : 0)) }))
+    .sort((first, second) => (first.path < second.path ? -1 : first.path > second.path ? 1 : 0))
+}

package/src/lib/auth/organizationAccess.ts

@@ -4,6 +4,15 @@ export type OrganizationAccessDecisionInput = {
   targetOrganizationId: string | null
 }
 
+export type UnrestrictedOrganizationScopeInput = {
+  isSuperAdmin: boolean
+  allowedOrganizationIds: readonly string[] | null | undefined
+}
+
+export function isUnrestrictedOrganizationScope(input: UnrestrictedOrganizationScopeInput): boolean {
+  return input.isSuperAdmin || input.allowedOrganizationIds === null
+}
+
 /**
  * Fail-closed organization-access predicate. The single source of truth for
  * "may this principal act on `targetOrganizationId`".
@@ -15,8 +24,7 @@ export type OrganizationAccessDecisionInput = {
  * - restricted + target org            -> allow iff the target is a member of the allowed set
  */
 export function isOrganizationAccessAllowed(input: OrganizationAccessDecisionInput): boolean {
-  if (input.isSuperAdmin) return true
-  if (input.allowedOrganizationIds === null) return true
+  if (isUnrestrictedOrganizationScope(input)) return true
   if (!input.targetOrganizationId) return false
-  return input.allowedOrganizationIds.includes(input.targetOrganizationId)
+  return (input.allowedOrganizationIds ?? []).includes(input.targetOrganizationId)
 }

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>
+}

package/src/lib/auth/server.ts

@@ -1,9 +1,18 @@
 import { cookies } from 'next/headers.js'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { verifyJwt } from './jwt'
+import { isMfaPendingJwtPayload, verifyJwt } from './jwt'
+import { isMfaPendingAccessAllowed } from './mfaPendingAccess'
 import { getSharedApiKeyAuthCache } from './apiKeyAuthCache'
 import { isTransientDbError } from '@open-mercato/shared/lib/db/pg-errors'
 
+function readRequestPathname(req: Request): string | null {
+  try {
+    return new URL(req.url).pathname
+  } catch {
+    return null
+  }
+}
+
 const TENANT_COOKIE_NAME = 'om_selected_tenant'
 const ORGANIZATION_COOKIE_NAME = 'om_selected_org'
 const ALL_ORGANIZATIONS_COOKIE_VALUE = '__all__'
@@ -59,6 +68,16 @@ export type TrustedAuthContextEnvelope = {
   status?: AuthResolutionStatus
 }
 
+/**
+ * Attach an already-resolved auth context to a synthetic request.
+ *
+ * INVARIANT callers MUST uphold: `envelope.auth` has to be the product of a gated resolution —
+ * `getAuthFromRequest` / `getAuthFromCookies` (or an equivalently validated principal such as an
+ * API-key record). The envelope short-circuits `resolveAuthFromRequestDetailed` ahead of both the
+ * MFA-pending gate and `resolveCanonicalStaffAuthContext`, so an envelope built straight from an
+ * unvalidated JWT would reinstate the MFA bypass this module closes and skip session-revocation
+ * checks as well. Never populate it from raw request credentials.
+ */
 export function attachTrustedAuthContext(
   request: Request,
   envelope: TrustedAuthContextEnvelope
@@ -195,13 +214,33 @@ async function resolveApiKeyAuth(secret: string): Promise<AuthContext> {
       : []
     const roleNames = roles.map((role) => role.name).filter((name): name is string => typeof name === 'string' && name.length > 0)
 
+    // A role-level super-admin grant is authorization-grade only when it is genuinely
+    // unrestricted: the grant itself must not be organization-scoped, it must belong to the
+    // key's tenant, and the key must not be bound to a single organization. RbacService applies
+    // the same intersection when projecting the scoped ACL, but generic guards
+    // (tenantAccess.resolveIsSuperAdmin, the scoped-API helpers) trust this raw bit *before*
+    // live RBAC runs — so an organization-restricted key must never carry it.
     let keyIsSuperAdmin = false
-    if (roleIds.length) {
-      const superAcl = await em.findOne(
+    const keyOrganizationId = typeof record.organizationId === 'string' && record.organizationId.trim().length > 0
+      ? record.organizationId.trim()
+      : null
+    if (roleIds.length && !keyOrganizationId) {
+      const superAcls = await em.find(
         RoleAcl,
-        { role: { $in: roleIds } as any, isSuperAdmin: true, deletedAt: null } as any,
+        {
+          role: { $in: roleIds } as any,
+          tenantId: record.tenantId ?? null,
+          isSuperAdmin: true,
+          deletedAt: null,
+        } as any,
       )
-      keyIsSuperAdmin = !!(superAcl && (superAcl as { isSuperAdmin?: boolean }).isSuperAdmin)
+      keyIsSuperAdmin = superAcls.some((acl) => {
+        const organizations = Array.isArray((acl as { organizationsJson?: string[] | null }).organizationsJson)
+          ? (acl as { organizationsJson?: string[] | null }).organizationsJson as string[]
+          : null
+        // An empty list means "inherit the key's own binding"; with no binding that is tenant-wide.
+        return !organizations || organizations.length === 0 || organizations.includes('__all__')
+      })
     }
 
     if (cache.shouldWriteLastUsed(record.id)) {
@@ -213,8 +252,25 @@ async function resolveApiKeyAuth(secret: string): Promise<AuthContext> {
       }
     }
 
-    // For session keys, use sessionUserId; for regular keys, use createdBy
-    const actualUserId = record.sessionUserId ?? record.createdBy ?? null
+    // Ephemeral session keys are always user-bound. Regular keys retain their
+    // legacy creator identity, while tenant-scoped regular keys ignore only the
+    // creator's concrete organization when validating the wider key scope.
+    // Keep every session marker fail-closed so a malformed session key cannot
+    // fall back to the regular key path and escape its user/scope binding.
+    const isSessionBoundKey = Boolean(
+      record.sessionToken
+      || record.sessionUserId
+      || record.sessionSecretEncrypted
+      || record.opencodeSessionId
+    )
+    const actualUserId = isSessionBoundKey
+      ? record.sessionUserId ?? null
+      : record.createdBy ?? null
+
+    if (isSessionBoundKey && !actualUserId) {
+      cache.setMiss(secret)
+      return null
+    }
 
     if (actualUserId) {
       const user = await em.findOne(User, { id: actualUserId, deletedAt: null })
@@ -226,7 +282,8 @@ async function resolveApiKeyAuth(secret: string): Promise<AuthContext> {
         cache.setMiss(secret)
         return null
       }
-      if ((user.organizationId ?? null) !== (record.organizationId ?? null)) {
+      const requiresExactOrganization = isSessionBoundKey || Boolean(record.organizationId)
+      if (requiresExactOrganization && (user.organizationId ?? null) !== (record.organizationId ?? null)) {
         cache.setMiss(secret)
         return null
       }
@@ -315,6 +372,9 @@ export async function resolveAuthFromCookiesDetailed(): Promise<AuthResolution>
     const payload = verifyJwt(token) as AuthContext
     if (!payload) return { auth: null, status: 'invalid' }
     if (payload.type === 'customer') return { auth: null, status: 'invalid' }
+    // MFA-pending tokens are provisional: pages never complete the second factor, so they
+    // must not resolve to an authenticated context anywhere in the RSC/page flow.
+    if (isMfaPendingJwtPayload(payload)) return { auth: null, status: 'invalid' }
     const canonicalAuth = await resolveCanonicalInteractiveAuthContext(payload)
     if (!canonicalAuth) return { auth: null, status: 'invalid' }
     const tenantCookie = cookieStore.get(TENANT_COOKIE_NAME)?.value
@@ -334,6 +394,8 @@ export async function getAuthFromCookies(): Promise<AuthContext> {
 }
 
 export async function resolveAuthFromRequestDetailed(req: Request): Promise<AuthResolution> {
+  // Deliberately ahead of the MFA-pending gate below: the envelope carries a context that was
+  // already gated by its producer (see `attachTrustedAuthContext`), not raw request credentials.
   const trusted = readTrustedAuthContext(req)
   if (trusted) {
     return {
@@ -357,6 +419,14 @@ export async function resolveAuthFromRequestDetailed(req: Request): Promise<Auth
     try {
       const payload = verifyJwt(token) as AuthContext
       if (payload && payload.type === 'customer') return { auth: null, status: 'invalid' }
+      if (payload && isMfaPendingJwtPayload(payload)) {
+        // MFA-pending tokens authenticate only the registered challenge-completion routes;
+        // everywhere else they resolve to `invalid` so the dispatcher answers 401 (clearing
+        // staff auth cookies) instead of restoring the account's roles/features.
+        if (!isMfaPendingAccessAllowed(req.method, readRequestPathname(req))) {
+          return { auth: null, status: 'invalid' }
+        }
+      }
       if (payload) {
         const canonicalAuth = await resolveCanonicalInteractiveAuthContext(payload)
         if (canonicalAuth) {

package/src/lib/commands/__tests__/command-bus.test.ts

@@ -49,6 +49,37 @@ describe('CommandBus', () => {
     expect(logEntry).toEqual({ id: 'log-entry' })
   })
 
+  it('records the system actor marker when a trusted command has no auth actor', async () => {
+    const logMock = jest.fn(async () => ({ id: 'system-log-entry' }))
+    registerCommand({
+      id: 'test.system-command',
+      execute: jest.fn(async () => ({ ok: true })),
+      buildLog: jest.fn(() => ({ actionLabel: 'System test', resourceKind: 'test', resourceId: 'system-123' })),
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: null,
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+      systemActor: true,
+    }
+
+    await bus.execute('test.system-command', { input: {}, ctx })
+
+    expect(logMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        actorUserId: undefined,
+        context: { systemActor: 'system:command' },
+      })
+    )
+  })
+
   it('passes captureAfter snapshot to buildLog as snapshots.after', async () => {
     const logMock = jest.fn(async () => ({ id: 'log-entry-2' }))
     const buildLogMock = jest.fn(() => ({

package/src/lib/commands/command-bus.ts

@@ -583,6 +583,9 @@ export class CommandBus {
     const organizationId =
       metadata.organizationId ?? options.ctx.selectedOrganizationId ?? options.ctx.auth?.orgId ?? null
     const actorUserId = metadata.actorUserId ?? options.ctx.auth?.sub ?? null
+    const systemActorContext = !actorUserId && options.ctx.systemActor === true
+      ? { systemActor: 'system:command' }
+      : null
     const payload: Record<string, unknown> = {
       tenantId: tenantId ?? undefined,
       organizationId: organizationId ?? undefined,
@@ -603,7 +606,11 @@ export class CommandBus {
       if ('snapshotBefore' in metadata && metadata.snapshotBefore !== undefined) payload.snapshotBefore = metadata.snapshotBefore
       if ('snapshotAfter' in metadata && metadata.snapshotAfter !== undefined) payload.snapshotAfter = metadata.snapshotAfter
       if ('changes' in metadata && metadata.changes !== undefined && metadata.changes !== null) payload.changes = metadata.changes
-      if ('context' in metadata && metadata.context !== undefined && metadata.context !== null) payload.context = metadata.context
+      if ('context' in metadata && metadata.context !== undefined && metadata.context !== null) {
+        payload.context = { ...(systemActorContext ?? {}), ...metadata.context }
+      } else if (systemActorContext) {
+        payload.context = systemActorContext
+      }
     }
 
     const redoEnvelope = wrapRedoPayload('commandPayload' in payload ? (payload.commandPayload as unknown) : undefined, options.input)