@open-mercato/scheduler 0.7.1-develop.7113.1.9d83dca10c → 0.7.1-develop.7121.1.734c263bda

package/src/modules/scheduler/commands/__tests__/trigger.test.ts

@@ -0,0 +1,411 @@
+export {}
+
+const registerCommand = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/commands', () => ({
+  registerCommand,
+}))
+
+jest.mock('@open-mercato/shared/lib/i18n/server', () => ({
+  resolveTranslations: jest.fn().mockResolvedValue({
+    translate: (_key: string, fallback?: string) => fallback ?? _key,
+  }),
+}))
+
+const enqueue = jest.fn()
+const close = jest.fn()
+const createQueue = jest.fn(() => ({ enqueue, close }))
+
+// The bare `@open-mercato/queue` specifier is not resolvable under this package's
+// jest moduleNameMapper (only its subpaths are), matching how the scheduler worker
+// test mocks it.
+jest.mock('@open-mercato/queue', () => ({ createQueue }), { virtual: true })
+
+jest.mock('@open-mercato/shared/lib/redis/connection', () => ({
+  getRedisUrlOrThrow: jest.fn(() => 'redis://localhost:6379'),
+}))
+
+const SCHEDULE_ID = '11111111-1111-4111-8111-111111111111'
+const ACTOR_ID = '22222222-2222-4222-8222-222222222222'
+
+function loadTriggerCommand() {
+  let trigger: any
+  jest.isolateModules(() => {
+    require('../trigger')
+    trigger = registerCommand.mock.calls.find(([cmd]) => cmd.id === 'scheduler.jobs.trigger')?.[0]
+  })
+  return trigger
+}
+
+function makeSchedule(overrides: Record<string, unknown> = {}) {
+  return {
+    id: SCHEDULE_ID,
+    name: 'Nightly report',
+    scopeType: 'tenant',
+    tenantId: 'tenant-a',
+    organizationId: null,
+    targetType: 'queue',
+    targetQueue: 'reports',
+    targetCommand: null,
+    ...overrides,
+  }
+}
+
+function makeEm(schedule: Record<string, unknown> | null) {
+  return {
+    fork: jest.fn().mockReturnThis(),
+    findOne: jest.fn().mockResolvedValue(schedule),
+    flush: jest.fn().mockResolvedValue(undefined),
+  }
+}
+
+const userHasAllFeatures = jest.fn()
+
+function makeCtx(auth: Record<string, unknown> | null, em: any, rbacService: any = { userHasAllFeatures }) {
+  return {
+    auth,
+    container: {
+      resolve: jest.fn((name: string) => (name === 'rbacService' ? rbacService : em)),
+    },
+    selectedOrganizationId: null,
+  } as any
+}
+
+const tenantActor = { sub: ACTOR_ID, userId: ACTOR_ID, tenantId: 'tenant-a', orgId: null, isSuperAdmin: false }
+
+describe('scheduler.jobs.trigger', () => {
+  const previousStrategy = process.env.QUEUE_STRATEGY
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    jest.resetModules()
+    process.env.QUEUE_STRATEGY = 'async'
+    enqueue.mockResolvedValue('queue-job-1')
+    close.mockResolvedValue(undefined)
+    userHasAllFeatures.mockResolvedValue(true)
+  })
+
+  afterAll(() => {
+    if (previousStrategy === undefined) delete process.env.QUEUE_STRATEGY
+    else process.env.QUEUE_STRATEGY = previousStrategy
+  })
+
+  it('is not undoable, so a manual trigger mints no undo token', () => {
+    const trigger = loadTriggerCommand()
+    expect(trigger).toBeDefined()
+    expect(trigger.isUndoable).toBe(false)
+    expect(trigger.undo).toBeUndefined()
+    expect(trigger.redo).toBeUndefined()
+  })
+
+  it('enqueues the execution job and reports the queue job id', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+    const ctx = makeCtx(tenantActor, em)
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(result).toMatchObject({
+      scheduleId: SCHEDULE_ID,
+      scheduleName: 'Nightly report',
+      targetType: 'queue',
+      target: 'reports',
+      outcome: 'enqueued',
+      queueJobId: 'queue-job-1',
+      error: null,
+    })
+    expect(enqueue).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scheduleId: SCHEDULE_ID,
+        triggerType: 'manual',
+        triggeredByUserId: ACTOR_ID,
+      }),
+    )
+    expect(close).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports a command schedule target by its command id', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ targetType: 'command', targetQueue: null, targetCommand: 'scheduler.test.echo' }))
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result).toMatchObject({ targetType: 'command', target: 'scheduler.test.echo', outcome: 'enqueued' })
+  })
+
+  it('leaves triggeredByUserId null for a key-only caller so the run keeps acting as the creator', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+    // No bound user: a bare key id is not a user id, so it could never satisfy the
+    // worker's RBAC lookup and must fall back to the schedule's creator.
+    const ctx = makeCtx({ sub: 'api-key-1', tenantId: 'tenant-a', orgId: null, isApiKey: true }, em)
+
+    await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(enqueue).toHaveBeenCalledWith(expect.objectContaining({ triggeredByUserId: null }))
+  })
+
+  it('attributes an API key issued on a user behalf to that user', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+    // `resolveCommandActorUserId` reads `userId` before it considers `isApiKey`, so
+    // a user-bound key acts as its real user rather than falling back to the
+    // creator — the run is attributed to whoever it was actually made on behalf of.
+    const ctx = makeCtx(
+      { sub: 'api-key-1', userId: ACTOR_ID, tenantId: 'tenant-a', orgId: null, isApiKey: true },
+      em,
+    )
+
+    await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(enqueue).toHaveBeenCalledWith(expect.objectContaining({ triggeredByUserId: ACTOR_ID }))
+  })
+
+  it('returns not_found for a missing schedule without throwing', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(null)
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result.outcome).toBe('not_found')
+    expect(enqueue).not.toHaveBeenCalled()
+  })
+
+  it('returns not_found for another tenant schedule, never confirming the id exists', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ tenantId: 'tenant-b' }))
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result.outcome).toBe('not_found')
+    expect(result.scheduleName).toBeNull()
+    expect(result.target).toBeNull()
+    expect(enqueue).not.toHaveBeenCalled()
+  })
+
+  it('returns forbidden for a system-scoped schedule without super-admin', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ scopeType: 'system', tenantId: null }))
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result.outcome).toBe('forbidden')
+    expect(enqueue).not.toHaveBeenCalled()
+  })
+
+  it('allows a super admin to trigger a system-scoped schedule', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ scopeType: 'system', tenantId: null }))
+    const ctx = makeCtx({ ...tenantActor, isSuperAdmin: true }, em)
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(result.outcome).toBe('enqueued')
+  })
+
+  it('refuses a command schedule the triggering user is not authorized to run, instead of enqueueing it', async () => {
+    // The worker gates the run with this same assertion and can only throw when it
+    // refuses, which BullMQ retries forever while the caller has already been told
+    // the run was enqueued. Deciding here turns that into a 403 and an audit row.
+    userHasAllFeatures.mockResolvedValue(false)
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ targetType: 'command', targetQueue: null, targetCommand: 'scheduler.test.echo' }))
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result).toMatchObject({
+      outcome: 'forbidden',
+      queueJobId: null,
+      error: 'Scheduled command actor is not authorized',
+    })
+    // Access to the row was granted, so naming it discloses nothing the refusal withholds.
+    expect(result).toMatchObject({ scheduleName: 'Nightly report', target: 'scheduler.test.echo' })
+    expect(enqueue).not.toHaveBeenCalled()
+  })
+
+  it('authorizes the actor the worker will run as, not the caller when there is no bound user', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(
+      makeSchedule({
+        targetType: 'command',
+        targetQueue: null,
+        targetCommand: 'scheduler.test.echo',
+        createdByUserId: 'creator-1',
+      }),
+    )
+    // A key-only caller contributes no user id, so the run falls back to the
+    // creator — and the creator is who this pre-check must authorize.
+    const ctx = makeCtx({ sub: 'api-key-1', tenantId: 'tenant-a', orgId: null, isApiKey: true }, em)
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(result.outcome).toBe('enqueued')
+    expect(userHasAllFeatures).toHaveBeenCalledWith('creator-1', ['scheduler.jobs.manage'], {
+      tenantId: 'tenant-a',
+      organizationId: null,
+    })
+  })
+
+  it('refuses a command schedule with no actor at all rather than enqueueing an unrunnable job', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(
+      makeSchedule({ targetType: 'command', targetQueue: null, targetCommand: 'scheduler.test.echo' }),
+    )
+    const ctx = makeCtx({ sub: 'api-key-1', tenantId: 'tenant-a', orgId: null, isApiKey: true }, em)
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(result).toMatchObject({
+      outcome: 'forbidden',
+      error: 'Scheduled command requires an authenticated actor',
+    })
+    expect(enqueue).not.toHaveBeenCalled()
+  })
+
+  it('reports a failing authorization lookup as failed, not as a refusal', async () => {
+    // An RBAC store outage is not a decision about the actor. Calling it `forbidden`
+    // would tell the caller they lack access they may well hold, and file an audit
+    // row claiming a refusal that was never made.
+    userHasAllFeatures.mockRejectedValue(new Error('rbac store unavailable'))
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ targetType: 'command', targetQueue: null, targetCommand: 'scheduler.test.echo' }))
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result).toMatchObject({ outcome: 'failed', error: 'rbac store unavailable' })
+    expect(enqueue).not.toHaveBeenCalled()
+  })
+
+  it('reports an unresolvable rbacService as failed rather than throwing away the audit row', async () => {
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule({ targetType: 'command', targetQueue: null, targetCommand: 'scheduler.test.echo' }))
+    const ctx = makeCtx(tenantActor, em)
+    ctx.container.resolve = jest.fn((name: string) => {
+      if (name === 'rbacService') throw new Error('Could not resolve rbacService')
+      return em
+    })
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, ctx)
+
+    expect(result).toMatchObject({ outcome: 'failed', error: 'Could not resolve rbacService' })
+  })
+
+  it('leaves a queue schedule untouched by the scheduled-command gate', async () => {
+    userHasAllFeatures.mockResolvedValue(false)
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result.outcome).toBe('enqueued')
+    expect(userHasAllFeatures).not.toHaveBeenCalled()
+  })
+
+  it('returns strategy_unsupported when the queue strategy is not async', async () => {
+    delete process.env.QUEUE_STRATEGY
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result).toMatchObject({ outcome: 'strategy_unsupported', queueJobId: null, error: null })
+    // Access was granted, so the schedule's details are safe to record.
+    expect(result.scheduleName).toBe('Nightly report')
+    expect(createQueue).not.toHaveBeenCalled()
+  })
+
+  it('returns failed and still closes the queue when the enqueue rejects', async () => {
+    enqueue.mockRejectedValue(new Error('redis unavailable'))
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result).toMatchObject({ outcome: 'failed', queueJobId: null, error: 'redis unavailable' })
+    expect(close).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not fail a completed enqueue when closing the queue throws', async () => {
+    close.mockRejectedValue(new Error('close failed'))
+    const trigger = loadTriggerCommand()
+    const em = makeEm(makeSchedule())
+
+    const result = await trigger.execute({ id: SCHEDULE_ID }, makeCtx(tenantActor, em))
+
+    expect(result.outcome).toBe('enqueued')
+  })
+
+  describe('buildLog', () => {
+    it('records a successful trigger against the actor', async () => {
+      const trigger = loadTriggerCommand()
+      const ctx = makeCtx({ ...tenantActor, orgId: 'org-a' }, makeEm(makeSchedule()))
+      const result = {
+        scheduleId: SCHEDULE_ID,
+        scheduleName: 'Nightly report',
+        targetType: 'queue',
+        target: 'reports',
+        outcome: 'enqueued',
+        queueJobId: 'queue-job-1',
+        error: null,
+      }
+
+      const log = await trigger.buildLog({ input: { id: SCHEDULE_ID }, result, ctx, snapshots: {} })
+
+      expect(log).toMatchObject({
+        actionLabel: 'Trigger schedule',
+        resourceKind: 'scheduler.job',
+        resourceId: SCHEDULE_ID,
+        tenantId: 'tenant-a',
+        organizationId: 'org-a',
+      })
+      expect(log.payload).toEqual({
+        scheduleName: 'Nightly report',
+        targetType: 'queue',
+        target: 'reports',
+        outcome: 'enqueued',
+        queueJobId: 'queue-job-1',
+        error: null,
+      })
+    })
+
+    it('records a refusal against the actor and discloses nothing about the row', async () => {
+      const trigger = loadTriggerCommand()
+      const ctx = makeCtx(tenantActor, makeEm(null))
+      const result = {
+        scheduleId: SCHEDULE_ID,
+        scheduleName: null,
+        targetType: null,
+        target: null,
+        outcome: 'not_found',
+        queueJobId: null,
+        error: null,
+      }
+
+      const log = await trigger.buildLog({ input: { id: SCHEDULE_ID }, result, ctx, snapshots: {} })
+
+      // The requested id is recorded so that probing is traceable...
+      expect(log.resourceId).toBe(SCHEDULE_ID)
+      // ...but the scope is the caller's, never the target's, and no detail of the
+      // row leaks into a trail the caller can read.
+      expect(log.tenantId).toBe('tenant-a')
+      expect(log.payload).toMatchObject({ outcome: 'not_found', scheduleName: null, target: null })
+    })
+
+    it('always returns metadata, so no outcome can silently skip the audit row', async () => {
+      const trigger = loadTriggerCommand()
+      const ctx = makeCtx(tenantActor, makeEm(null))
+      const outcomes = ['enqueued', 'not_found', 'forbidden', 'strategy_unsupported', 'failed']
+
+      for (const outcome of outcomes) {
+        const log = await trigger.buildLog({
+          input: { id: SCHEDULE_ID },
+          result: { scheduleId: SCHEDULE_ID, scheduleName: null, targetType: null, target: null, outcome, queueJobId: null, error: null },
+          ctx,
+          snapshots: {},
+        })
+        expect(log?.skipLog).toBeUndefined()
+        expect(log?.resourceKind).toBe('scheduler.job')
+      }
+    })
+  })
+})

package/src/modules/scheduler/commands/jobs.ts

@@ -146,7 +146,7 @@ async function assertQueueTargetPayloadAllowed(queue: string, targetPayload: Rec
   if (reason) throw new CrudHttpError(422, { error: `Invalid target payload for queue ${queue}: ${reason}` })
 }
 
-function resolveCommandActorUserId(ctx: CommandRuntimeContext): string | null {
+export function resolveCommandActorUserId(ctx: CommandRuntimeContext): string | null {
   const auth = ctx.auth
   if (!auth) return null
   if (typeof auth.userId === 'string' && auth.userId.trim().length > 0) return auth.userId.trim()

package/src/modules/scheduler/commands/trigger.ts

@@ -0,0 +1,258 @@
+// =============================================================================
+// Manual Schedule Trigger Command — Undo Policy
+// =============================================================================
+//
+// `scheduler.jobs.trigger` is registered with `isUndoable: false` and defines no
+// `undo`/`redo`. It mutates no domain state itself: it enqueues an execution job,
+// and a worker picks that job up as soon as it is free. By the time an operator
+// could reach for Undo the run has already started, and whatever it did is
+// reversed through the action-log entries the run itself writes — the target
+// command's own `undo`, or the target queue's domain-level counter-action.
+//
+// Minting an undo token here would therefore offer to reverse an enqueue that no
+// longer exists, while leaving the run's real effects untouched. No `undo`
+// handler also means no `undoToken`, hence no `x-om-operation` header — which is
+// what `TC-UNDO-001 §4` pins.
+//
+// The command exists for the audit trail: manual triggering is an
+// authorised-looking way to make an automated job run at a moment of the actor's
+// choosing, so every authenticated attempt — refusals included — must leave an
+// `ActionLog` row naming the caller. The one exception is bus-wide rather than
+// local: `CommandBus.execute` throws `CommandInterceptorError` before `buildLog`
+// and `persistLog` run, so an attempt a `before` interceptor blocks is refused
+// without a row, exactly as it is for `scheduler.jobs.create`/`.update`/`.delete`.
+// =============================================================================
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler } from '@open-mercato/shared/lib/commands'
+import { createQueue } from '@open-mercato/queue'
+import type { Queue } from '@open-mercato/queue'
+import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { EntityManager } from '@mikro-orm/core'
+import { ScheduledJob } from '../data/entities.js'
+import { resolveScheduleAccess } from '../lib/scheduleAccess.js'
+import {
+  assertSchedulerSafeCommandAuthorized,
+  SchedulerCommandAuthorizationError,
+  type SchedulerCommandRbacService,
+} from '../lib/scheduler-safe-commands.js'
+import { resolveScheduledCommandActorUserId } from '../lib/commandContext.js'
+import { resolveCommandActorUserId } from './jobs.js'
+import type { ScheduleTriggerInput } from '../data/validators.js'
+import type { ExecuteSchedulePayload } from '../workers/execute-schedule.worker.js'
+
+const logger = createLogger('scheduler').child({ component: 'trigger' })
+
+/**
+ * Outcome of a manual trigger attempt.
+ *
+ * `execute()` returns this for every *expected* refusal instead of throwing.
+ * That is a hard requirement, not a style choice: `CommandBus.execute` has no
+ * try/catch, so a handler that throws skips `captureAfter`, `buildLog` and
+ * `persistLog` entirely and no `ActionLog` row is written — losing exactly the
+ * entries this command exists to create. The route maps `outcome` to HTTP.
+ */
+export type TriggerScheduleResult = {
+  scheduleId: string
+  scheduleName: string | null
+  targetType: 'queue' | 'command' | null
+  target: string | null
+  outcome: 'enqueued' | 'not_found' | 'forbidden' | 'strategy_unsupported' | 'failed'
+  queueJobId: string | null
+  error: string | null
+}
+
+/**
+ * A refused attempt records the requested id and nothing else about the row.
+ *
+ * `resolveScheduleAccess` deliberately answers `not_found` rather than 403 for
+ * another tenant's schedule, so that a caller cannot confirm an id exists.
+ * Echoing that row's name or target into the audit log would hand back exactly
+ * the fact the decision withholds, so schedule details are populated only once
+ * access has been granted.
+ */
+function refusedTrigger(
+  scheduleId: string,
+  outcome: 'not_found' | 'forbidden',
+): TriggerScheduleResult {
+  return {
+    scheduleId,
+    scheduleName: null,
+    targetType: null,
+    target: null,
+    outcome,
+    queueJobId: null,
+    error: null,
+  }
+}
+
+const triggerScheduleCommand: CommandHandler<ScheduleTriggerInput, TriggerScheduleResult> = {
+  id: 'scheduler.jobs.trigger',
+  isUndoable: false,
+
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em')
+
+    // Load by id alone, then apply isolation to the loaded row. Folding the actor's
+    // tenant/org into the lookup would make every system-scoped schedule unmatchable.
+    const schedule = await em.findOne(ScheduledJob, { id: input.id, deletedAt: null })
+    if (!schedule) return refusedTrigger(input.id, 'not_found')
+
+    // Single source of truth for schedule visibility, shared with update, delete,
+    // list and executions. Its `not_found` vs `forbidden` split is deliberate.
+    const access = resolveScheduleAccess(schedule, ctx.auth)
+    if (access === 'not_found') return refusedTrigger(input.id, 'not_found')
+    if (access === 'forbidden') return refusedTrigger(input.id, 'forbidden')
+
+    const details = {
+      scheduleId: schedule.id,
+      scheduleName: schedule.name ?? null,
+      targetType: schedule.targetType ?? null,
+      target:
+        (schedule.targetType === 'command' ? schedule.targetCommand : schedule.targetQueue) ?? null,
+    }
+
+    const queueStrategy = (process.env.QUEUE_STRATEGY || 'local') as 'local' | 'async'
+    if (queueStrategy !== 'async') {
+      return { ...details, outcome: 'strategy_unsupported', queueJobId: null, error: null }
+    }
+
+    // `resolveCommandActorUserId` resolves the bound user whenever the auth
+    // context carries one — including an API key issued on a user's behalf — and
+    // yields null only for a key-only context. That matters now that the worker
+    // authorizes and runs a manual command schedule as this identity: a bare key
+    // id is not a user id, so it falls back to the schedule's creator rather than
+    // failing an RBAC lookup that could never succeed.
+    const triggeredByUserId = resolveCommandActorUserId(ctx)
+
+    // Decide a command schedule's authorization here, where the audit row is
+    // written, rather than leaving it to the worker.
+    //
+    // The worker gates the run with the same assertion and throws when it refuses,
+    // and a throw inside a retrying queue is invisible: the caller has already been
+    // told the run was enqueued, the audit row already says `enqueued`, and BullMQ
+    // keeps retrying a refusal that no attempt can turn into a success. Answering
+    // `forbidden` now makes the refusal the caller's HTTP response and the audit
+    // row's outcome. The worker keeps its own gate as the authority — this decision
+    // can go stale between enqueue and execution — but the common case is decided
+    // where it can be seen.
+    //
+    // Unlike `refusedTrigger`, this refusal carries the schedule's details: access
+    // to the row has already been granted, so naming it discloses nothing new.
+    if (schedule.targetType === 'command') {
+      const actorUserId = resolveScheduledCommandActorUserId(schedule, { triggeredByUserId })
+      try {
+        await assertSchedulerSafeCommandAuthorized({
+          commandId: schedule.targetCommand,
+          actorUserId,
+          tenantId: schedule.tenantId,
+          organizationId: schedule.organizationId,
+          rbacService: ctx.container.resolve<SchedulerCommandRbacService>('rbacService'),
+        })
+      } catch (error) {
+        // Only an authorization decision is a refusal. `userHasAllFeatures` can
+        // also fail because its store is down, and answering `403` to an outage
+        // would tell the caller they lack access they may well hold, and file an
+        // audit row claiming a refusal that was never decided. Those become
+        // `failed`, the same outcome an unreachable queue produces — still audited,
+        // because a handler that throws writes no row at all.
+        const refused = error instanceof SchedulerCommandAuthorizationError
+        const message = error instanceof Error ? error.message : null
+        if (refused) {
+          logger.info('Manual trigger refused by scheduled-command authorization', {
+            scheduleId: schedule.id,
+            commandId: schedule.targetCommand,
+            reason: message,
+          })
+        } else {
+          logger.error('Scheduled-command authorization check failed', {
+            err: error,
+            scheduleId: schedule.id,
+            commandId: schedule.targetCommand,
+          })
+        }
+        return {
+          ...details,
+          outcome: refused ? 'forbidden' : 'failed',
+          queueJobId: null,
+          error: message,
+        }
+      }
+    }
+
+    const payload: ExecuteSchedulePayload = {
+      scheduleId: schedule.id,
+      tenantId: schedule.tenantId,
+      organizationId: schedule.organizationId,
+      scopeType: schedule.scopeType,
+      triggerType: 'manual',
+      triggeredByUserId,
+    }
+
+    let executionQueue: Queue<ExecuteSchedulePayload> | null = null
+    try {
+      executionQueue = createQueue<ExecuteSchedulePayload>('scheduler-execution', queueStrategy, {
+        connection: { url: getRedisUrlOrThrow('QUEUE') },
+      })
+      const queueJobId = await executionQueue.enqueue(payload)
+
+      logger.info('Manually triggered schedule', {
+        scheduleId: schedule.id,
+        scheduleName: schedule.name,
+        jobId: queueJobId,
+        triggeredBy: ctx.auth?.sub ?? null,
+      })
+
+      return { ...details, outcome: 'enqueued', queueJobId, error: null }
+    } catch (error) {
+      logger.error('Manual trigger failed', { err: error, scheduleId: schedule.id })
+      return {
+        ...details,
+        outcome: 'failed',
+        queueJobId: null,
+        error: error instanceof Error ? error.message : null,
+      }
+    } finally {
+      // Cleanup runs on the failure path too — the previous route-level code closed
+      // the queue only after a successful enqueue, leaking a Redis connection
+      // otherwise. A failure to close must not turn a completed enqueue into a
+      // failed request, so it is reported rather than thrown.
+      try {
+        await executionQueue?.close()
+      } catch (closeError) {
+        logger.warn('Failed to close scheduler execution queue', { err: closeError })
+      }
+    }
+  },
+
+  async buildLog({ result, ctx }) {
+    const { translate } = await resolveTranslations()
+
+    return {
+      // Keep the label free of create/update/delete/assign verbs: the action-log
+      // projection derives `actionType` by string-matching it.
+      actionLabel: translate('scheduler.audit.trigger', 'Trigger schedule'),
+      resourceKind: 'scheduler.job',
+      // The requested id, so that probing for ids that do not exist is traceable.
+      resourceId: result.scheduleId,
+      // The actor's scope on every outcome, unlike the sibling create/update/delete
+      // handlers which log the schedule's. A refusal must never carry the target's
+      // tenant: that would leak cross-tenant existence into the caller's trail and,
+      // because the action-log reader filters organization_id by strict equality,
+      // file the row where the caller's own auditors could never read it.
+      tenantId: ctx.auth?.tenantId ?? null,
+      organizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+      payload: {
+        scheduleName: result.scheduleName,
+        targetType: result.targetType,
+        target: result.target,
+        outcome: result.outcome,
+        queueJobId: result.queueJobId,
+        error: result.error,
+      },
+    }
+  },
+}
+
+registerCommand(triggerScheduleCommand)

package/src/modules/scheduler/i18n/de.json

@@ -7,6 +7,7 @@
   "scheduler.action.view": "Anzeigen",
   "scheduler.audit.create": "Zeitplan erstellen",
   "scheduler.audit.delete": "Zeitplan löschen",
+  "scheduler.audit.trigger": "Zeitplan ausführen",
   "scheduler.audit.update": "Zeitplan aktualisieren",
   "scheduler.confirm.delete": "Sind Sie sicher, dass Sie diesen Zeitplan löschen möchten?",
   "scheduler.confirm.trigger": "Sind Sie sicher, dass Sie \"{name}\" jetzt ausführen möchten?\n\nDies wird {targetType} sofort ausführen.",