@open-mercato/shared 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/lib/commands/scope.ts

@@ -1,44 +1,69 @@
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { isOrganizationAccessAllowed } from '@open-mercato/shared/lib/auth/organizationAccess'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { env } from 'process'
 
+function buildScopeLogContext(ctx: CommandRuntimeContext) {
+  const requestInfo =
+    ctx.request && typeof ctx.request === 'object'
+      ? {
+          method: (ctx.request as Request).method ?? undefined,
+          url: (ctx.request as Request).url ?? undefined,
+        }
+      : null
+  const scope = ctx.organizationScope
+    ? {
+        selectedId: ctx.organizationScope.selectedId ?? null,
+        tenantId: ctx.organizationScope.tenantId ?? null,
+        allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
+          ? ctx.organizationScope.allowedIds.length
+          : null,
+        filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
+          ? ctx.organizationScope.filterIds.length
+          : null,
+      }
+    : null
+  return {
+    userId: ctx.auth?.sub ?? null,
+    actorTenantId: ctx.auth?.tenantId ?? null,
+    actorOrganizationId: ctx.auth?.orgId ?? null,
+    selectedOrganizationId: ctx.selectedOrganizationId ?? null,
+    organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
+    scope,
+    request: requestInfo,
+  }
+}
+
+function isStrictOrganizationScopeEnforced(): boolean {
+  return parseBooleanWithDefault(env.OM_ENFORCE_ORG_SCOPE_STRICT, false)
+}
+
 function logScopeViolation(
   ctx: CommandRuntimeContext,
   expected: string,
   actual: string | null
 ): void {
   try {
-    const requestInfo =
-      ctx.request && typeof ctx.request === 'object'
-        ? {
-            method: (ctx.request as Request).method ?? undefined,
-            url: (ctx.request as Request).url ?? undefined,
-          }
-        : null
-    const scope = ctx.organizationScope
-      ? {
-          selectedId: ctx.organizationScope.selectedId ?? null,
-          tenantId: ctx.organizationScope.tenantId ?? null,
-          allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
-            ? ctx.organizationScope.allowedIds.length
-            : null,
-          filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
-            ? ctx.organizationScope.filterIds.length
-            : null,
-        }
-      : null
     if (env.NODE_ENV !== 'test') {
       console.warn('[scope] Forbidden organization scope mismatch detected', {
         expectedId: expected,
         actualId: actual,
-        userId: ctx.auth?.sub ?? null,
-        actorTenantId: ctx.auth?.tenantId ?? null,
-        actorOrganizationId: ctx.auth?.orgId ?? null,
-        selectedOrganizationId: ctx.selectedOrganizationId ?? null,
-        organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
-        scope,
-        request: requestInfo,
+        ...buildScopeLogContext(ctx),
+      })
+    }
+  } catch {
+    // best-effort logging
+  }
+}
+
+function logUnscopedOrganizationAccess(ctx: CommandRuntimeContext, organizationId: string): void {
+  try {
+    if (env.NODE_ENV !== 'test') {
+      console.warn('[scope] Unscoped organization command executed without organization context', {
+        targetOrganizationId: organizationId,
+        strictEnforcement: isStrictOrganizationScopeEnforced(),
+        ...buildScopeLogContext(ctx),
       })
     }
   } catch {
@@ -52,36 +77,11 @@ function logTenantScopeViolation(
   actualTenantId: string | null
 ): void {
   try {
-    const requestInfo =
-      ctx.request && typeof ctx.request === 'object'
-        ? {
-            method: (ctx.request as Request).method ?? undefined,
-            url: (ctx.request as Request).url ?? undefined,
-          }
-        : null
-    const scope = ctx.organizationScope
-      ? {
-          selectedId: ctx.organizationScope.selectedId ?? null,
-          tenantId: ctx.organizationScope.tenantId ?? null,
-          allowedIdsCount: Array.isArray(ctx.organizationScope.allowedIds)
-            ? ctx.organizationScope.allowedIds.length
-            : null,
-          filterIdsCount: Array.isArray(ctx.organizationScope.filterIds)
-            ? ctx.organizationScope.filterIds.length
-            : null,
-        }
-      : null
     if (env.NODE_ENV !== 'test') {
       console.warn('[scope] Forbidden tenant scope mismatch detected', {
         expectedTenantId,
         actualTenantId,
-        userId: ctx.auth?.sub ?? null,
-        actorTenantId: ctx.auth?.tenantId ?? null,
-        actorOrganizationId: ctx.auth?.orgId ?? null,
-        selectedOrganizationId: ctx.selectedOrganizationId ?? null,
-        organizationIdsCount: Array.isArray(ctx.organizationIds) ? ctx.organizationIds.length : null,
-        scope,
-        request: requestInfo,
+        ...buildScopeLogContext(ctx),
       })
     }
   } catch {
@@ -100,9 +100,24 @@ export function ensureOrganizationScope(ctx: CommandRuntimeContext, organization
   if (!scope) {
     if (isSuperAdmin) return
     const currentOrg = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
-    if (currentOrg && currentOrg !== organizationId) {
-      logScopeViolation(ctx, organizationId, currentOrg)
-      throw new CrudHttpError(403, { error: 'Forbidden' })
+    if (currentOrg) {
+      if (currentOrg !== organizationId) {
+        logScopeViolation(ctx, organizationId, currentOrg)
+        throw new CrudHttpError(403, { error: 'Forbidden' })
+      }
+      return
+    }
+    // No current org could be resolved either. This branch previously returned
+    // with no validation and no signal — a fail-open-by-omission shape (#2441):
+    // a new command path reaching here with `organizationScope: null` would act
+    // on an arbitrary target org silently. Preserve the legacy allow behavior by
+    // default (the path is load-bearing) but make the unscoped access observable,
+    // and let operators harden it into a deny via OM_ENFORCE_ORG_SCOPE_STRICT.
+    if (organizationId) {
+      logUnscopedOrganizationAccess(ctx, organizationId)
+      if (isStrictOrganizationScopeEnforced()) {
+        throw new CrudHttpError(403, { error: 'Forbidden' })
+      }
     }
     return
   }

package/src/lib/commands/types.ts

@@ -54,6 +54,38 @@ export type CommandExecuteResult<TResult> = {
   logEntry: any | null
 }
 
+/**
+ * Shape of the persisted action log handed to a command's `undo()` handler.
+ *
+ * IMPORTANT: there is intentionally **no `payload` field**. `buildLog()` returns
+ * a `payload` in its metadata, but the command bus persists that under
+ * `commandPayload` (column `command_payload`, wrapped in a redo envelope) — the
+ * stored row never has a top-level `payload`. Reading `logEntry.payload` in an
+ * undo handler is therefore always `undefined` and silently no-ops the undo
+ * (issue #2504). Always read the undo snapshot through
+ * `extractUndoPayload(logEntry)` from `@open-mercato/shared/lib/commands/undo`,
+ * which unwraps `commandPayload`/snapshots correctly. Omitting `payload` here
+ * makes the footgun a compile-time error instead of a runtime silent failure.
+ */
+export type CommandUndoLogEntry = {
+  id?: string
+  commandId?: string
+  commandPayload?: unknown | null
+  snapshotBefore?: unknown | null
+  snapshotAfter?: unknown | null
+  resourceKind?: string | null
+  resourceId?: string | null
+  undoToken?: string | null
+  actionLabel?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+  actorUserId?: string | null
+  changesJson?: Record<string, unknown> | null
+  contextJson?: Record<string, unknown> | null
+  createdAt?: Date | string
+  updatedAt?: Date | string
+}
+
 export type CommandLogBuilderArgs<TInput, TResult> = {
   input: TInput
   result: TResult
@@ -71,7 +103,18 @@ export interface CommandHandler<TInput = unknown, TResult = unknown> {
   execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
   buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined
   captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown
-  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: any }): Promise<void> | void
+  undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: CommandUndoLogEntry }): Promise<void> | void
+  /**
+   * Optional redo handler. When defined, the command bus calls this instead of
+   * `execute()` while replaying a previously undone action (the redo route passes
+   * `redoLogEntry` in the execution options). It receives the source action log so
+   * it can re-materialize the original record **reusing its id** — for a create
+   * command this restores the soft-deleted row (or re-creates it from the
+   * `snapshotAfter`) instead of minting a new id, keeping undo/redo snapshots and
+   * references stable (issue #2506, invariant I6). Handlers without `redo` keep the
+   * legacy behavior of replaying `execute(__redoInput)`.
+   */
+  redo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: CommandUndoLogEntry }): Promise<TResult> | TResult
 }
 
 export type CommandExecutionOptions<TInput> = {
@@ -79,6 +122,16 @@ export type CommandExecutionOptions<TInput> = {
   ctx: CommandRuntimeContext
   metadata?: CommandLogMetadata | null
   skipCacheInvalidation?: boolean
+  /**
+   * When set, marks this execution as a redo of a previously undone action. If the
+   * resolved handler defines a `redo` method, the command bus calls
+   * `handler.redo({ input, ctx, logEntry })` instead of `handler.execute(...)`. The
+   * rest of the pipeline (snapshots, buildLog, undo-token minting, persistence,
+   * cache invalidation, side effects) is identical, so the fresh log entry — and
+   * the `x-om-operation` header derived from it — automatically carry the restored
+   * resourceId. Ignored when the handler has no `redo` method (legacy replay path).
+   */
+  redoLogEntry?: CommandUndoLogEntry | null
 }
 
 export function defaultUndoToken(): string {

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -4,6 +4,11 @@ jest.mock('@open-mercato/cache', () => ({
 
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { registerApiInterceptors } from '@open-mercato/shared/lib/crud/interceptor-registry'
+import {
+  clearOptimisticLockReadersForTests,
+  getAllOptimisticLockReaders,
+  registerOptimisticLockReaders,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
 import { z } from 'zod'
 
@@ -754,3 +759,104 @@ describe('CRUD Factory', () => {
     expect(body._interceptor).toEqual({ ok: true, count: 1 })
   })
 })
+
+describe('CRUD Factory — optimistic-lock auto-registration', () => {
+  beforeEach(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  afterAll(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  function makeMinimalRoute(opts: { eventsResource: string; entity: any }) {
+    return makeCrudRoute({
+      metadata: { GET: { requireAuth: true } },
+      orm: { entity: opts.entity, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId' },
+      events: { module: opts.eventsResource.split('.')[0], entity: opts.eventsResource.split('.')[1], persistent: false } as any,
+      list: { schema: z.object({}).passthrough() as any },
+      create: {
+        commandId: `${opts.eventsResource}.create`,
+        schema: z.object({}).passthrough() as any,
+      },
+      update: {
+        commandId: `${opts.eventsResource}.update`,
+        schema: z.object({ id: z.string() }).passthrough() as any,
+      },
+      del: {
+        commandId: `${opts.eventsResource}.delete`,
+        schema: z.object({ id: z.string() }).passthrough() as any,
+      },
+    })
+  }
+
+  it('auto-registers a reader for the route resourceKind at factory call time', () => {
+    expect(getAllOptimisticLockReaders()).toEqual({})
+    makeMinimalRoute({ eventsResource: 'example.todo', entity: Todo })
+    const all = getAllOptimisticLockReaders()
+    expect(Object.keys(all)).toContain('example.todo')
+    expect(typeof all['example.todo']).toBe('function')
+  })
+
+  it('does NOT override an existing hand-wired reader (IfAbsent semantics)', () => {
+    const handWired = async () => 'hand-wired'
+    registerOptimisticLockReaders({ 'example.todo': handWired })
+    makeMinimalRoute({ eventsResource: 'example.todo', entity: Todo })
+    expect(getAllOptimisticLockReaders()['example.todo']).toBe(handWired)
+  })
+
+  it('skips registration when the entity has no resolvable resourceKind', () => {
+    expect(getAllOptimisticLockReaders()).toEqual({})
+    // Route with no events.module + no command IDs → resourceKind falls back to 'resource'
+    makeCrudRoute({
+      metadata: { GET: { requireAuth: true } },
+      orm: { entity: Todo },
+      list: { schema: z.object({}).passthrough() as any },
+    } as any)
+    // 'resource' is filtered out by the auto-registration guard
+    expect(getAllOptimisticLockReaders()['resource']).toBeUndefined()
+  })
+
+  it('the registered reader projects only updatedAt and fails open on schema mismatch', async () => {
+    makeMinimalRoute({ eventsResource: 'example.todo', entity: Todo })
+    const reader = getAllOptimisticLockReaders()['example.todo']
+    expect(reader).toBeDefined()
+    let captured: { entity: unknown; filter: Record<string, unknown>; options?: Record<string, unknown> } | null = null
+    const fakeEm = {
+      async findOne(entity: unknown, filter: Record<string, unknown>, options?: Record<string, unknown>) {
+        captured = { entity, filter, options }
+        return { updatedAt: new Date('2026-05-26T07:30:00.000Z') }
+      },
+    } as never
+    const out = await reader!(fakeEm, {
+      resourceKind: 'example.todo',
+      resourceId: 'todo-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    expect(out).toBe('2026-05-26T07:30:00.000Z')
+    expect(captured).not.toBeNull()
+    expect(captured!.entity).toBe(Todo)
+    expect(captured!.filter).toEqual({
+      id: 'todo-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      deletedAt: null,
+    })
+    expect(captured!.options).toEqual({ fields: ['updatedAt'] })
+
+    // Fail-open contract: throwing findOne yields null, not a re-thrown error.
+    const throwingEm = {
+      async findOne() {
+        throw new Error('schema mismatch')
+      },
+    } as never
+    const safe = await reader!(throwingEm, {
+      resourceKind: 'example.todo',
+      resourceId: 'todo-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    expect(safe).toBeNull()
+  })
+})