@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/api/portal/tasks/[id]/complete/route.ts

@@ -0,0 +1,160 @@
+/**
+ * Portal User Task completion API
+ *
+ * - POST /api/workflows/portal/tasks/[id]/complete
+ *
+ * `actable` is the gate, and on the portal branch `actable` is true only for the
+ * assignee themselves: a portal admin who can READ a company member's task gets
+ * `visible` without `actable` and is refused here. The refusal is a 404, same as
+ * every other portal refusal — telling an admin "you may see this but not
+ * finish it" would disclose more than the read already did.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  getCustomerAuthFromRequest,
+  requireCustomerFeature,
+} from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
+import type { CustomerRbacService } from '@open-mercato/core/modules/customer_accounts/services/customerRbacService'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { UserTask } from '../../../../../data/entities'
+import { serializeUserTask } from '../../../../tasks/serialize'
+import type { TaskHandlerService } from '../../../../../lib/task-handler'
+import {
+  decidePortalTaskAccess,
+  PORTAL_TASK_REFUSAL,
+  PORTAL_TASKS_COMPLETE_FEATURE,
+  resolvePortalTaskPrincipal,
+} from '../../../../../lib/portal-task-access'
+import {
+  workflowsTag,
+  portalTaskCompleteRequestSchema,
+  portalTaskCompleteResponseSchema,
+  portalTaskErrorSchema,
+} from '../../../../openapi'
+
+const logger = createLogger('workflows')
+
+export const metadata: { requireAuth?: boolean } = { requireAuth: false }
+
+const completeSchema = z.object({
+  formData: z.record(z.string(), z.any()),
+  comments: z.string().optional(),
+  decisionId: z.string().min(1).optional(),
+})
+
+export async function POST(request: NextRequest, { params }: { params: { id: string } }) {
+  const auth = await getCustomerAuthFromRequest(request)
+  if (!auth) {
+    return NextResponse.json({ ok: false, error: 'Authentication required' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const rbac = container.resolve('customerRbacService') as CustomerRbacService
+
+  try {
+    await requireCustomerFeature(auth, [PORTAL_TASKS_COMPLETE_FEATURE], rbac)
+  } catch (response) {
+    return response as NextResponse
+  }
+
+  try {
+    const em = container.resolve('em') as import('@mikro-orm/postgresql').EntityManager
+    const acl = await rbac.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    const resolved = await resolvePortalTaskPrincipal({ auth, em, isPortalAdmin: acl.isPortalAdmin })
+    if (!resolved.ok) return NextResponse.json(resolved.body, { status: resolved.status })
+
+    const parsed = completeSchema.safeParse(await request.json())
+    if (!parsed.success) {
+      return NextResponse.json(
+        { ok: false, error: 'Invalid request body', details: parsed.error.format() },
+        { status: 400 },
+      )
+    }
+
+    const task = await em.findOne(UserTask, {
+      id: params.id,
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+    if (!task) {
+      return NextResponse.json(PORTAL_TASK_REFUSAL.body, { status: PORTAL_TASK_REFUSAL.status })
+    }
+
+    const decision = decidePortalTaskAccess(resolved.principal, task)
+    if (!decision.actable) {
+      return NextResponse.json(PORTAL_TASK_REFUSAL.body, { status: PORTAL_TASK_REFUSAL.status })
+    }
+
+    const taskHandler = container.resolve('taskHandler') as TaskHandlerService
+    await taskHandler.completeUserTask(em, container, {
+      taskId: params.id,
+      formData: parsed.data.formData,
+      // The portal principal's own id. `completeUserTask` compares it against
+      // `claimedBy ?? assignedTo`, which for a portal task is the same id space,
+      // so its own ownership check agrees with the predicate rather than
+      // fighting it.
+      userId: auth.sub,
+      comments: parsed.data.comments,
+      decisionId: parsed.data.decisionId,
+      scope: { tenantId: auth.tenantId, organizationId: auth.orgId },
+    })
+
+    const updated = await em.findOne(UserTask, {
+      id: params.id,
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    return NextResponse.json({
+      ok: true,
+      task: updated ? serializeUserTask(updated) : null,
+    })
+  } catch (error) {
+    const code = (error as { code?: unknown }).code
+    if (code === 'UNKNOWN_DECISION' || code === 'FORM_VALIDATION_FAILED') {
+      return NextResponse.json(
+        { ok: false, error: error instanceof Error ? error.message : 'Invalid submission' },
+        { status: 400 },
+      )
+    }
+    // Anything the handler refuses on ownership or status grounds collapses into
+    // the same 404 the predicate would have produced, so the act path discloses
+    // no more than the read path.
+    if (code === 'TASK_NOT_FOUND' || code === 'TASK_ASSIGNED_TO_ANOTHER_USER') {
+      return NextResponse.json(PORTAL_TASK_REFUSAL.body, { status: PORTAL_TASK_REFUSAL.status })
+    }
+    logger.error('Error completing portal task', { err: error })
+    return NextResponse.json({ ok: false, error: 'Failed to complete task' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Portal user task completion',
+  methods: {
+    POST: {
+      summary: 'Complete a portal task',
+      description:
+        'Completes a customer-assigned task and resumes the workflow. Only the assignee may complete; a portal admin who can read a company member\'s task is refused.',
+      requestBody: { schema: portalTaskCompleteRequestSchema },
+      responses: [
+        { status: 200, description: 'Task completed', schema: portalTaskCompleteResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid request body or form data', schema: portalTaskErrorSchema },
+        { status: 401, description: 'Authentication required', schema: portalTaskErrorSchema },
+        { status: 403, description: 'Insufficient permissions or no company association', schema: portalTaskErrorSchema },
+        { status: 404, description: 'Task not found or not actionable by this principal', schema: portalTaskErrorSchema },
+        { status: 500, description: 'Internal server error', schema: portalTaskErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/portal/tasks/[id]/route.ts

@@ -0,0 +1,124 @@
+/**
+ * Portal User Task detail API
+ *
+ * - GET /api/workflows/portal/tasks/[id]
+ *
+ * Every refusal is the same 404 with the same body — a foreign task id, another
+ * customer's task, an unbound task and a random uuid are indistinguishable. A
+ * portal principal has no legitimate knowledge that any row they cannot read
+ * exists, and a portal admin least of all.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import type { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  getCustomerAuthFromRequest,
+  requireCustomerFeature,
+} from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
+import type { CustomerRbacService } from '@open-mercato/core/modules/customer_accounts/services/customerRbacService'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { UserTask } from '../../../../data/entities'
+import { serializeUserTask } from '../../../tasks/serialize'
+import { loadTaskDecisionContext } from '../../../../lib/task-decision-context'
+import {
+  decidePortalTaskAccess,
+  PORTAL_TASK_REFUSAL,
+  PORTAL_TASKS_VIEW_FEATURE,
+  resolvePortalTaskPrincipal,
+} from '../../../../lib/portal-task-access'
+import {
+  workflowsTag,
+  portalTaskDetailResponseSchema,
+  portalTaskErrorSchema,
+} from '../../../openapi'
+
+const logger = createLogger('workflows')
+
+export const metadata: { requireAuth?: boolean } = { requireAuth: false }
+
+export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
+  const auth = await getCustomerAuthFromRequest(request)
+  if (!auth) {
+    return NextResponse.json({ ok: false, error: 'Authentication required' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const rbac = container.resolve('customerRbacService') as CustomerRbacService
+
+  try {
+    await requireCustomerFeature(auth, [PORTAL_TASKS_VIEW_FEATURE], rbac)
+  } catch (response) {
+    return response as NextResponse
+  }
+
+  try {
+    const em = container.resolve('em') as import('@mikro-orm/postgresql').EntityManager
+    const acl = await rbac.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    const resolved = await resolvePortalTaskPrincipal({ auth, em, isPortalAdmin: acl.isPortalAdmin })
+    if (!resolved.ok) return NextResponse.json(resolved.body, { status: resolved.status })
+
+    // Scoped at the lookup, so a foreign-tenant id resolves to nothing before the
+    // predicate ever runs.
+    const task = await em.findOne(UserTask, {
+      id: params.id,
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+    if (!task) {
+      return NextResponse.json(PORTAL_TASK_REFUSAL.body, { status: PORTAL_TASK_REFUSAL.status })
+    }
+
+    const decision = decidePortalTaskAccess(resolved.principal, task)
+    if (!decision.visible) {
+      return NextResponse.json(PORTAL_TASK_REFUSAL.body, { status: PORTAL_TASK_REFUSAL.status })
+    }
+
+    // Re-resolved from the instance's pinned definition, exactly as the
+    // backoffice detail does — the portal must offer the SAME named outcomes the
+    // author wrote, or a portal completion silently takes the default route.
+    const { decisions, formKey } = await loadTaskDecisionContext(em, task)
+
+    const body: z.infer<typeof portalTaskDetailResponseSchema> = {
+      ok: true,
+      task: serializeUserTask(task),
+      decisions,
+      formKey,
+      // What the UI needs to decide whether to render the completion form at
+      // all. A portal admin reading a member's task gets `false` — they see the
+      // work, they never finish it.
+      canComplete: decision.actable,
+    }
+
+    return NextResponse.json(body)
+  } catch (error) {
+    logger.error('Error loading portal task', { err: error })
+    return NextResponse.json({ ok: false, error: 'Failed to load task' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Portal user task detail',
+  methods: {
+    GET: {
+      summary: 'Read one portal task',
+      description:
+        'Returns a single customer-assigned task the portal principal owns. Every refusal — foreign tenant, another customer, an unbound task, a nonexistent id — is the same 404.',
+      responses: [
+        { status: 200, description: 'Portal task', schema: portalTaskDetailResponseSchema },
+      ],
+      errors: [
+        { status: 401, description: 'Authentication required', schema: portalTaskErrorSchema },
+        { status: 403, description: 'Insufficient permissions or no company association', schema: portalTaskErrorSchema },
+        { status: 404, description: 'Task not found', schema: portalTaskErrorSchema },
+        { status: 500, description: 'Internal server error', schema: portalTaskErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/portal/tasks/route.ts

@@ -0,0 +1,157 @@
+/**
+ * Portal User Tasks API
+ *
+ * - GET /api/workflows/portal/tasks — the customer's own task list
+ *
+ * NEW SURFACE, not a relaxation. The backoffice task routes are untouched: they
+ * still require a backoffice session and still refuse a portal token, and this
+ * route refuses a backoffice one. Two principals, two route trees, one shared
+ * predicate — which is the only reason the isolation is testable in both
+ * directions rather than merely asserted.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import type { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  getCustomerAuthFromRequest,
+  requireCustomerFeature,
+} from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
+import type { CustomerRbacService } from '@open-mercato/core/modules/customer_accounts/services/customerRbacService'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+import { UserTask } from '../../../data/entities'
+import { serializeUserTask } from '../../tasks/serialize'
+import {
+  buildPortalTaskConditions,
+  filterVisiblePortalTasks,
+  PORTAL_TASKS_VIEW_FEATURE,
+  resolvePortalTaskPrincipal,
+} from '../../../lib/portal-task-access'
+import {
+  workflowsTag,
+  portalTaskListQuerySchema,
+  portalTaskListResponseSchema,
+  portalTaskErrorSchema,
+} from '../../openapi'
+
+const logger = createLogger('workflows')
+
+const DEFAULT_PORTAL_TASK_LIMIT = 25
+const MAX_PORTAL_TASK_LIMIT = 100
+
+export const metadata: { requireAuth?: boolean } = { requireAuth: false }
+
+export async function GET(request: NextRequest) {
+  const auth = await getCustomerAuthFromRequest(request)
+  if (!auth) {
+    return NextResponse.json({ ok: false, error: 'Authentication required' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const rbac = container.resolve('customerRbacService') as CustomerRbacService
+
+  try {
+    await requireCustomerFeature(auth, [PORTAL_TASKS_VIEW_FEATURE], rbac)
+  } catch (response) {
+    return response as NextResponse
+  }
+
+  try {
+    const em = container.resolve('em') as import('@mikro-orm/postgresql').EntityManager
+    const acl = await rbac.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    const resolved = await resolvePortalTaskPrincipal({
+      auth,
+      em,
+      isPortalAdmin: acl.isPortalAdmin,
+    })
+    if (!resolved.ok) {
+      return NextResponse.json(resolved.body, { status: resolved.status })
+    }
+
+    const { searchParams } = new URL(request.url)
+    const status = searchParams.get('status')
+    const page = Math.max(1, parseNumberWithDefault(searchParams.get('page'), 1, { min: 1, integer: true }))
+    const pageSize = Math.min(
+      parseNumberWithDefault(searchParams.get('pageSize'), DEFAULT_PORTAL_TASK_LIMIT, {
+        min: 1,
+        integer: true,
+      }),
+      MAX_PORTAL_TASK_LIMIT,
+    )
+
+    const where: Record<string, unknown> = buildPortalTaskConditions({
+      principal: resolved.principal,
+      assigneeIds: resolved.assigneeIds,
+    })
+
+    if (status) {
+      const statusValues = status.split(',').map((value) => value.trim()).filter(Boolean)
+      if (statusValues.length === 1) where.status = statusValues[0]
+      else if (statusValues.length > 1) where.status = { $in: statusValues }
+    }
+
+    const [tasks, total] = await em.findAndCount(UserTask, where, {
+      orderBy: { createdAt: 'DESC' },
+      limit: pageSize,
+      offset: (page - 1) * pageSize,
+    })
+
+    // The SQL is the structural half; ownership is a per-row set membership the
+    // jsonb bindings cannot express, so this genuinely drops rows rather than
+    // being a belt-and-braces no-op. A drop means a task assigned to a company
+    // member is bound to a record outside that company — an authoring anomaly
+    // worth a log line, never a silent gap.
+    const visible = filterVisiblePortalTasks(resolved.principal, tasks)
+    if (visible.length !== tasks.length) {
+      logger.warn('Portal task page dropped rows that failed the ownership check', {
+        component: 'portal-tasks',
+        tenantId: auth.tenantId,
+        organizationId: auth.orgId,
+        dropped: tasks.length - visible.length,
+      })
+    }
+
+    const body: z.infer<typeof portalTaskListResponseSchema> = {
+      ok: true,
+      tasks: visible.map(serializeUserTask),
+      pagination: {
+        page,
+        pageSize,
+        total,
+        totalPages: Math.max(1, Math.ceil(total / pageSize)),
+      },
+    }
+
+    return NextResponse.json(body)
+  } catch (error) {
+    logger.error('Error listing portal tasks', { err: error })
+    return NextResponse.json({ ok: false, error: 'Failed to list tasks' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Portal user tasks',
+  methods: {
+    GET: {
+      summary: 'List the portal principal\'s tasks',
+      description:
+        'Returns the customer-assigned tasks this portal principal may see. A portal admin additionally sees their company members\' tasks but may not act on them. Tasks with no entity bindings are never portal-visible.',
+      query: portalTaskListQuerySchema,
+      responses: [
+        { status: 200, description: 'Portal task list', schema: portalTaskListResponseSchema },
+      ],
+      errors: [
+        { status: 401, description: 'Authentication required', schema: portalTaskErrorSchema },
+        { status: 403, description: 'Insufficient permissions or no company association', schema: portalTaskErrorSchema },
+        { status: 500, description: 'Internal server error', schema: portalTaskErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/rule-usage/route.ts

@@ -0,0 +1,94 @@
+/**
+ * Business Rule Usage in Workflows (dependency visibility)
+ *
+ * GET /api/workflows/rule-usage?ruleId=<business rule id>
+ *
+ * Backs the "used by: N workflows" panel the Studio renders beside the inline
+ * business-rule editor. It lives in workflows — not business_rules — so the
+ * upstream module never learns about its consumers.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { countReferencingWorkflows, findBusinessRuleUsage } from '../../lib/business-rule-usage'
+
+const logger = createLogger('workflows').child({ component: 'rule-usage-api' })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.definitions.view'],
+}
+
+const querySchema = z.object({
+  ruleId: z.string().min(1).max(50),
+})
+
+export async function GET(request: NextRequest) {
+  try {
+    const auth = await getAuthFromRequest(request)
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const url = new URL(request.url)
+    const parsed = querySchema.safeParse({ ruleId: url.searchParams.get('ruleId') || undefined })
+    if (!parsed.success) {
+      return NextResponse.json({ error: 'Invalid query parameters' }, { status: 400 })
+    }
+
+    const container = await createRequestContainer()
+    const em = container.resolve('em')
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const organizationId = scope?.selectedId ?? auth.orgId
+
+    if (!tenantId || !organizationId) {
+      return NextResponse.json({ error: 'Missing tenant or organization context' }, { status: 400 })
+    }
+
+    const references = await findBusinessRuleUsage(em, {
+      ruleId: parsed.data.ruleId,
+      tenantId,
+      organizationId,
+    })
+
+    return NextResponse.json({
+      ruleId: parsed.data.ruleId,
+      workflowCount: countReferencingWorkflows(references),
+      references,
+    })
+  } catch (error) {
+    logger.error('Failed to resolve business rule usage', { err: error })
+    return NextResponse.json({ error: 'Failed to resolve business rule usage' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      summary: 'List workflows referencing a business rule',
+      description: 'Returns the workflow definitions whose START pre-conditions or transition pre/post-conditions reference the given business rule.',
+      tags: ['Workflows'],
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Usage references',
+          example: {
+            ruleId: 'ORDER_ABOVE_LIMIT',
+            workflowCount: 1,
+            references: [
+              { workflowId: 'order-approval', version: 2, kind: 'transitionPreCondition', locationId: 'e_start_review' },
+            ],
+          },
+        },
+        { status: 400, description: 'Invalid query parameters', example: { error: 'Invalid query parameters' } },
+        { status: 401, description: 'Unauthorized', example: { error: 'Unauthorized' } },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/task-settings/route.ts

@@ -0,0 +1,138 @@
+/**
+ * Tenant task-permission settings (spec §6.4, design §6).
+ *
+ * - GET  /api/workflows/task-settings — read the opt-out
+ * - PUT  /api/workflows/task-settings — write it
+ *
+ * A new route, which BACKWARD_COMPATIBILITY.md §7 allows freely, and the bridge
+ * that discharges the deprecation protocol's "keep the old behaviour alongside
+ * the new one for at least one minor version" for the §6.4 visibility change.
+ *
+ * Shape copied field-for-field from `entities/api/entity-settings.ts` with one
+ * deliberate inversion: the read defaults to `true` (the NEW, narrower model)
+ * on failure rather than to the permissive value. See
+ * `lib/task-permission-settings.ts`.
+ *
+ * `tenantId` always comes from the authenticated context and never from the
+ * request body — a settings write that accepted a tenant id would be a
+ * cross-tenant write primitive.
+ */
+
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  readTaskPermissionsBusinessContext,
+  writeTaskPermissionsBusinessContext,
+  type TaskPermissionsConfigService,
+} from '../../lib/task-permission-settings'
+import { workflowsTag, workflowErrorSchema } from '../openapi'
+
+export const metadata = {
+  // Reading the tenant's task-permission posture is administration, not one's
+  // own work — the predicate reads the setting server-side for everyone else.
+  GET: { requireAuth: true, requireFeatures: ['workflows.tasks.view_all'] },
+  // Writing it is an administrative mutation that is not a reassignment.
+  PUT: { requireAuth: true, requireFeatures: ['workflows.tasks.manage'] },
+}
+
+const settingsResponseSchema = z.object({
+  taskPermissionsBusinessContext: z.boolean(),
+})
+
+const putBodySchema = z.object({
+  taskPermissionsBusinessContext: z.boolean(),
+})
+
+const putResponseSchema = settingsResponseSchema.extend({ ok: z.boolean() })
+
+async function resolveModuleConfigService(): Promise<TaskPermissionsConfigService | null> {
+  try {
+    const { resolve } = await createRequestContainer()
+    return resolve('moduleConfigService') as TaskPermissionsConfigService
+  } catch {
+    // Fails to the default, which is the NEW model — never the permissive one.
+    return null
+  }
+}
+
+export async function GET(request: Request) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const moduleConfigService = await resolveModuleConfigService()
+  const taskPermissionsBusinessContext = await readTaskPermissionsBusinessContext(
+    moduleConfigService,
+    auth.tenantId,
+  )
+  return NextResponse.json({ taskPermissionsBusinessContext })
+}
+
+export async function PUT(request: Request) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })
+  }
+
+  const parsed = putBodySchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: 'Validation failed', details: parsed.error.flatten() },
+      { status: 400 },
+    )
+  }
+
+  const moduleConfigService = await resolveModuleConfigService()
+  if (!moduleConfigService) {
+    return NextResponse.json({ error: 'Settings storage unavailable' }, { status: 503 })
+  }
+
+  await writeTaskPermissionsBusinessContext(
+    moduleConfigService,
+    auth.tenantId,
+    parsed.data.taskPermissionsBusinessContext,
+  )
+
+  return NextResponse.json({
+    ok: true,
+    taskPermissionsBusinessContext: parsed.data.taskPermissionsBusinessContext,
+  })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Tenant task-permission settings',
+  methods: {
+    GET: {
+      summary: 'Get tenant task-permission settings',
+      description:
+        'Returns whether the business-context task-permission model (spec §6.4) is enabled for the tenant. Defaults to true.',
+      responses: [
+        { status: 200, description: 'Current settings', schema: settingsResponseSchema },
+        { status: 401, description: 'Missing authentication', schema: workflowErrorSchema },
+      ],
+    },
+    PUT: {
+      summary: 'Update tenant task-permission settings',
+      description:
+        'Sets the tenant-scoped opt-out. Setting it to false restores the pre-6.4 READ filter on the task list, task detail and work inbox; it never affects claiming, completing, tenant/organization scoping or the portal task routes.',
+      requestBody: { schema: putBodySchema },
+      responses: [
+        { status: 200, description: 'Updated settings', schema: putResponseSchema },
+        { status: 400, description: 'Invalid payload', schema: workflowErrorSchema },
+        { status: 401, description: 'Missing authentication', schema: workflowErrorSchema },
+        { status: 503, description: 'Settings storage unavailable', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}