@open-mercato/core 0.6.6-develop.6229.1.ebe6706732 → 0.6.6-develop.6245.1.2be3b151f8

package/src/modules/entities/api/encryption.ts

@@ -4,8 +4,16 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { EncryptionMap } from '@open-mercato/core/modules/entities/data/entities'
 import { upsertEncryptionMapSchema } from '@open-mercato/core/modules/entities/data/validators'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 
+const ENCRYPTION_MAP_RESOURCE_KIND = 'entities.encryption_map'
+
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
   POST: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
@@ -18,6 +26,16 @@ function resolveScope(auth: { tenantId?: string | null; orgId?: string | null })
   }
 }
 
+function toIsoOrNull(value: Date | string | null | undefined): string | null {
+  if (value == null) return null
+  if (value instanceof Date) {
+    const ms = value.getTime()
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : null
+  }
+  const trimmed = String(value).trim()
+  return trimmed.length ? trimmed : null
+}
+
 export async function GET(req: Request) {
   const url = new URL(req.url)
   const entityId = url.searchParams.get('entityId') || ''
@@ -26,8 +44,8 @@ export async function GET(req: Request) {
   if (!auth?.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   const { tenantId, organizationId } = resolveScope(auth)
 
-  const { resolve } = await createRequestContainer()
-  const em = resolve('em') as any
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as any
   const repo = em.getRepository(EncryptionMap)
   // Prefer tenant+org, then tenant-global, then global
   const candidates = [
@@ -51,52 +69,114 @@ export async function GET(req: Request) {
     organizationId,
     fields: record?.fieldsJson ?? [],
     isActive: record?.isActive ?? true,
+    updatedAt: toIsoOrNull(record?.updatedAt),
   })
 }
 
 export async function POST(req: Request) {
-  const body = await req.json().catch(() => ({}))
-  const parsed = upsertEncryptionMapSchema.safeParse(body)
-  if (!parsed.success) {
-    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
-  }
-  const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  const scope = resolveScope(auth)
-  const payload = parsed.data
-  const tenantId = scope.tenantId
-  const organizationId = scope.organizationId
+  try {
+    const body = await req.json().catch(() => ({}))
+    const parsed = upsertEncryptionMapSchema.safeParse(body)
+    if (!parsed.success) {
+      return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
+    }
+    const auth = await getAuthFromRequest(req)
+    if (!auth?.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const scope = resolveScope(auth)
+    const payload = parsed.data
+    const tenantId: string = auth.tenantId
+    const organizationId = scope.organizationId
 
-  const { resolve } = await createRequestContainer()
-  const em = resolve('em') as any
-  const repo = em.getRepository(EncryptionMap)
-  const existing = await repo.findOne({ entityId: payload.entityId, tenantId, organizationId, deletedAt: null })
-  if (existing) {
-    existing.fieldsJson = payload.fields
-    existing.isActive = payload.isActive ?? true
-    existing.updatedAt = new Date()
-    await em.persist(existing).flush()
-  } else {
-    const map = repo.create({
-      entityId: payload.entityId,
+    const container = await createRequestContainer()
+    const em = container.resolve('em') as any
+    const repo = em.getRepository(EncryptionMap)
+    const existing = await repo.findOne({ entityId: payload.entityId, tenantId, organizationId, deletedAt: null })
+
+    // Reject stale writes: a save started from an older tab must not silently
+    // overwrite a newer encryption configuration. No-op when the client did not
+    // send the expected-version header (strictly additive).
+    if (existing) {
+      enforceCommandOptimisticLock({
+        resourceKind: ENCRYPTION_MAP_RESOURCE_KIND,
+        resourceId: existing.id,
+        current: existing.updatedAt,
+        request: req,
+      })
+    }
+
+    // Mutation-guard contract for custom write routes. The resource is the
+    // encryption map for this entity scoped to the tenant/organization.
+    const guardResult = await validateCrudMutationGuard(container, {
       tenantId,
       organizationId,
-      fieldsJson: payload.fields,
-      isActive: payload.isActive ?? true,
+      userId: auth.sub,
+      resourceKind: ENCRYPTION_MAP_RESOURCE_KIND,
+      resourceId: existing?.id ?? payload.entityId,
+      operation: existing ? 'update' : 'create',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: payload,
     })
-    await em.persist(map).flush()
-  }
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
 
-  try {
-    const svc = resolve('tenantEncryptionService') as { invalidateMap?: (e: string, t: string | null, o: string | null) => Promise<void> }
-    await svc?.invalidateMap?.(payload.entityId, tenantId, organizationId)
-  } catch {
-    // best-effort cache bust
-  }
+    let saved: any
+    if (existing) {
+      existing.fieldsJson = payload.fields
+      existing.isActive = payload.isActive ?? true
+      existing.updatedAt = new Date()
+      await em.persist(existing).flush()
+      saved = existing
+    } else {
+      const map = repo.create({
+        entityId: payload.entityId,
+        tenantId,
+        organizationId,
+        fieldsJson: payload.fields,
+        isActive: payload.isActive ?? true,
+      })
+      await em.persist(map).flush()
+      saved = map
+    }
+
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId,
+        organizationId,
+        userId: auth.sub,
+        resourceKind: ENCRYPTION_MAP_RESOURCE_KIND,
+        resourceId: saved?.id ?? payload.entityId,
+        operation: existing ? 'update' : 'create',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
+    try {
+      const svc = container.resolve('tenantEncryptionService') as { invalidateMap?: (e: string, t: string | null, o: string | null) => Promise<void> }
+      await svc?.invalidateMap?.(payload.entityId, tenantId, organizationId)
+    } catch {
+      // best-effort cache bust
+    }
 
-  return NextResponse.json({ ok: true })
+    return NextResponse.json({ ok: true, updatedAt: toIsoOrNull(saved?.updatedAt) })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    throw err
+  }
 }
 
+const conflictResponseSchema = z.object({
+  error: z.string(),
+  code: z.string(),
+  currentUpdatedAt: z.string(),
+  expectedUpdatedAt: z.string(),
+})
+
 export const openApi: OpenApiRouteDoc = {
   tag: 'Entities',
   summary: 'Manage encryption maps',
@@ -105,13 +185,16 @@ export const openApi: OpenApiRouteDoc = {
       summary: 'Fetch encryption map',
       description: 'Returns the encrypted field map for the current tenant/organization scope.',
       query: z.object({ entityId: z.string() }),
-      responses: [{ status: 200, description: 'Map', schema: z.object({ entityId: z.string(), fields: z.array(z.object({ field: z.string(), hashField: z.string().nullable().optional() })), isActive: z.boolean().optional() }) }],
+      responses: [{ status: 200, description: 'Map', schema: z.object({ entityId: z.string(), fields: z.array(z.object({ field: z.string(), hashField: z.string().nullable().optional() })), isActive: z.boolean().optional(), updatedAt: z.string().nullable().optional() }) }],
     },
     POST: {
       summary: 'Upsert encryption map',
-      description: 'Creates or updates the encryption map for the current tenant/organization scope.',
+      description: 'Creates or updates the encryption map for the current tenant/organization scope. Enforces optimistic locking when the caller sends the expected version header.',
       requestBody: { contentType: 'application/json', schema: upsertEncryptionMapSchema },
-      responses: [{ status: 200, description: 'Saved', schema: z.object({ ok: z.boolean() }) }],
+      responses: [
+        { status: 200, description: 'Saved', schema: z.object({ ok: z.boolean(), updatedAt: z.string().nullable().optional() }) },
+        { status: 409, description: 'Optimistic-lock conflict (stale write)', schema: conflictResponseSchema },
+      ],
     },
   },
 }

package/src/modules/entities/components/EncryptionManager.tsx

@@ -13,8 +13,10 @@ import {
 } from '@open-mercato/ui/primitives/select'
 import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useCustomFieldDefs, type CustomFieldDefDto } from '@open-mercato/ui/backend/utils/customFieldDefs'
 import { Plus, Save, Trash2 } from 'lucide-react'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -34,6 +36,7 @@ type EncryptionMapResponse = {
   entityId: string
   fields?: Array<{ field: string; hashField?: string | null }>
   isActive?: boolean
+  updatedAt?: string | null
 }
 
 type CanonicalOption = { value: string; label?: string }
@@ -225,6 +228,8 @@ export function EncryptionManager() {
     lastMapSignatureRef.current = signature
   }, [mapSignature, map, canonicalOptions, hasUserEdited])
 
+  const { runMutation } = useGuardedMutation({ contextId: 'entities.encryption-map' })
+
   const mutation = useMutation({
     mutationFn: async () => {
       const trimmed = fields
@@ -243,15 +248,29 @@ export function EncryptionManager() {
       if (!trimmed.length) {
         throw new Error(t('entities.encryption.errors.noFields', 'Add at least one field to encrypt'))
       }
-      const res = await apiCall('/api/entities/encryption', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ entityId: selectedEntityId, fields: trimmed, isActive }),
+      const payload = { entityId: selectedEntityId, fields: trimmed, isActive }
+      // Route the write through the guarded mutation helper so global injection
+      // modules (mutation guard, record-lock conflict handling) can run, and send
+      // the loaded map's version so a stale tab cannot silently overwrite a newer
+      // encryption configuration (the server rejects mismatches with a 409).
+      return runMutation({
+        operation: async () => {
+          const res = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(map?.updatedAt ?? null),
+            () => apiCall('/api/entities/encryption', {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(payload),
+            }),
+          )
+          if (!res.ok) {
+            await raiseCrudError(res.response, t('entities.encryption.errors.save', 'Failed to save encryption map'))
+          }
+          return true
+        },
+        context: {},
+        mutationPayload: payload,
       })
-      if (!res.ok) {
-        await raiseCrudError(res.response, t('entities.encryption.errors.save', 'Failed to save encryption map'))
-      }
-      return true
     },
     onSuccess: () => {
       flash(t('entities.encryption.flash.saved', 'Encryption map saved'), 'success')

package/src/modules/integrations/api/[id]/credentials/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { emitIntegrationsEvent } from '../../../events'
 import { saveCredentialsSchema } from '../../../data/validators'
 import {
@@ -58,8 +60,10 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
   let values: Record<string, unknown> | null
+  let updatedAt: Date | null
   try {
     values = await credentialsService.resolve(integration.id, scope)
+    updatedAt = await credentialsService.resolveUpdatedAt(integration.id, scope)
   } catch (error) {
     if (isCredentialsEncryptionUnavailableError(error)) {
       return NextResponse.json({ error: 'Integration credentials encryption is unavailable' }, { status: 503 })
@@ -71,6 +75,7 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
     integrationId: integration.id,
     schema: credentialsService.getSchema(integration.id),
     credentials: values ?? {},
+    updatedAt: updatedAt?.toISOString() ?? null,
   })
 }
 
@@ -130,6 +135,24 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
   const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
+  try {
+    const currentUpdatedAt = await credentialsService.resolveUpdatedAt(integration.id, scope)
+    enforceCommandOptimisticLock({
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      current: currentUpdatedAt,
+      request: req,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    if (isCredentialsEncryptionUnavailableError(error)) {
+      return NextResponse.json({ error: 'Integration credentials encryption is unavailable' }, { status: 503 })
+    }
+    throw error
+  }
+
   const credentialFieldErrors = collectCredentialUrlValidationErrors(
     credentialsService.getSchema(integration.id),
     payloadData.credentials,

package/src/modules/integrations/api/[id]/route.ts

@@ -59,11 +59,15 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
   const logService = container.resolve('integrationLogService') as IntegrationLogService
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
-  const [credentials, state, analyticsMap] = await Promise.all([
+  const [credentials, credentialsUpdatedAt, state, analyticsMap] = await Promise.all([
     credentialsService.resolve(integration.id, scope).catch((err) => {
       if (err instanceof CredentialsEncryptionUnavailableError) return null
       throw err
     }),
+    credentialsService.resolveUpdatedAt(integration.id, scope).catch((err) => {
+      if (err instanceof CredentialsEncryptionUnavailableError) return null
+      throw err
+    }),
     stateService.resolveState(integration.id, scope),
     logService.aggregateAnalytics([integration.id], scope, 30),
   ])
@@ -102,6 +106,7 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
             lastHealthCheckedAt: resolvedState.lastHealthCheckedAt?.toISOString() ?? null,
             lastHealthLatencyMs: resolvedState.lastHealthLatencyMs,
             enabledAt: resolvedState.enabledAt?.toISOString() ?? null,
+            updatedAt: resolvedState.updatedAt?.toISOString() ?? null,
           },
         }
       }),
@@ -132,8 +137,10 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
         lastHealthCheckedAt: state.lastHealthCheckedAt?.toISOString() ?? null,
         lastHealthLatencyMs: state.lastHealthLatencyMs,
         enabledAt: state.enabledAt?.toISOString() ?? null,
+        updatedAt: state.updatedAt?.toISOString() ?? null,
       },
       hasCredentials,
+      credentialsUpdatedAt: credentialsUpdatedAt?.toISOString() ?? null,
       healthStatus,
       analytics,
     },

package/src/modules/integrations/api/[id]/state/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { emitIntegrationsEvent } from '../../../events'
 import { updateStateSchema } from '../../../data/validators'
 import type { IntegrationStateService } from '../../../lib/state-service'
@@ -80,6 +82,22 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
   }
 
   const stateService = container.resolve('integrationStateService') as IntegrationStateService
+  const stateScope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  try {
+    const current = await stateService.resolveState(integration.id, stateScope)
+    enforceCommandOptimisticLock({
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      current: current.updatedAt,
+      request: req,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    throw error
+  }
 
   const state = await stateService.upsert(
     integration.id,
@@ -87,10 +105,7 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
       isEnabled: payloadData.isEnabled,
       reauthRequired: payloadData.reauthRequired,
     },
-    {
-      organizationId: auth.orgId as string,
-      tenantId: auth.tenantId,
-    },
+    stateScope,
   )
 
   await emitIntegrationsEvent('integrations.state.updated', {
@@ -117,5 +132,6 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
     isEnabled: state.isEnabled,
     reauthRequired: state.reauthRequired,
     apiVersion: state.apiVersion ?? null,
+    updatedAt: state.updatedAt?.toISOString() ?? null,
   })
 }

package/src/modules/integrations/api/[id]/version/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { emitIntegrationsEvent } from '../../../events'
 import { updateVersionSchema } from '../../../data/validators'
 import type { IntegrationStateService } from '../../../lib/state-service'
@@ -102,7 +104,22 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
   const stateService = container.resolve('integrationStateService') as IntegrationStateService
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
-  const before = await stateService.resolveApiVersion(integration.id, scope)
+  const currentState = await stateService.resolveState(integration.id, scope)
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      current: currentState.updatedAt,
+      request: req,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    throw error
+  }
+
+  const before = currentState.apiVersion
   await stateService.upsert(integration.id, { apiVersion: payloadData.apiVersion }, scope)
 
   await emitIntegrationsEvent('integrations.version.changed', {

package/src/modules/integrations/api/route.ts

@@ -93,6 +93,7 @@ export async function GET(req: Request) {
     lastHealthCheckedAt: string | null
     lastHealthLatencyMs: number | null
     enabledAt: string | null
+    stateUpdatedAt: string | null
     sortEnabledAtMs: number
     sortTitle: string
     sortCategory: string
@@ -140,6 +141,7 @@ export async function GET(req: Request) {
         lastHealthCheckedAt: state.lastHealthCheckedAt?.toISOString() ?? null,
         lastHealthLatencyMs: state.lastHealthLatencyMs,
         enabledAt: state.enabledAt?.toISOString() ?? null,
+        stateUpdatedAt: state.updatedAt?.toISOString() ?? null,
         sortEnabledAtMs: enabledAtMs,
         sortTitle: integration.title.toLowerCase(),
         sortCategory: (integration.category ?? '').toLowerCase(),
@@ -220,6 +222,7 @@ export async function GET(req: Request) {
       lastHealthCheckedAt: row.lastHealthCheckedAt,
       lastHealthLatencyMs: row.lastHealthLatencyMs,
       enabledAt: row.enabledAt,
+      stateUpdatedAt: row.stateUpdatedAt,
       analytics: analytics ?? {
         lastActivityAt: null,
         totalCount: 0,

package/src/modules/integrations/backend/integrations/[id]/page.tsx

@@ -24,7 +24,8 @@ import { PasswordInput } from '@open-mercato/ui/primitives/password-input'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@open-mercato/ui/primitives/tabs'
 import { JsonDisplay } from '@open-mercato/ui/backend/JsonDisplay'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -105,8 +106,10 @@ type IntegrationDetail = {
     lastHealthCheckedAt: string | null
     lastHealthLatencyMs: number | null
     enabledAt: string | null
+    updatedAt: string | null
   }
   hasCredentials: boolean
+  credentialsUpdatedAt?: string | null
   healthStatus: 'healthy' | 'degraded' | 'unhealthy' | 'unconfigured'
   analytics: IntegrationLogAnalytics
 }
@@ -423,6 +426,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
   const [isNotFound, setIsNotFound] = React.useState(false)
 
   const [credValues, setCredValues] = React.useState<Record<string, unknown>>({})
+  const [credentialsUpdatedAt, setCredentialsUpdatedAt] = React.useState<string | null>(null)
   const [credentialsFormKey, setCredentialsFormKey] = React.useState(0)
   const [isSavingCredentials, setIsSavingCredentials] = React.useState(false)
 
@@ -486,11 +490,14 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
   const loadCredentials = React.useCallback(async () => {
     const currentIntegrationId = resolveCurrentIntegrationId()
     if (!currentIntegrationId) return
-    const call = await apiCall<{ credentials: Record<string, unknown> }>(
+    const call = await apiCall<{ credentials: Record<string, unknown>; updatedAt?: string | null }>(
       `/api/integrations/${encodeURIComponent(currentIntegrationId)}/credentials`,
       undefined,
       { fallback: null },
     )
+    if (call.ok && call.result) {
+      setCredentialsUpdatedAt(call.result.updatedAt ?? null)
+    }
     if (call.ok && call.result?.credentials) {
       const next = { ...call.result.credentials }
       if (currentIntegrationId === 'storage_s3') {
@@ -671,11 +678,14 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
       const call = await runMutationWithContext({
         actionId: 'toggle-state',
         mutationPayload: { integrationId: currentIntegrationId, isEnabled: enabled },
-        operation: () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/state`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ isEnabled: enabled }),
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(detail?.state.updatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/state`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ isEnabled: enabled }),
+          }, { fallback: null }),
+        ),
       })
       if (call.ok) {
         setDetail((prev) => prev ? {
@@ -687,6 +697,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
           },
         } : prev)
         flash(t('integrations.detail.stateUpdated'), 'success')
+        void refreshDetail()
       } else {
         flash(t('integrations.detail.stateError'), 'error')
       }
@@ -695,7 +706,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
     } finally {
       setIsTogglingState(false)
     }
-  }, [resolveCurrentIntegrationId, runMutationWithContext, t])
+  }, [detail?.state.updatedAt, refreshDetail, resolveCurrentIntegrationId, runMutationWithContext, t])
 
   const handleSaveCredentials = React.useCallback(async (values: Record<string, unknown>) => {
     const currentIntegrationId = resolveCurrentIntegrationId()
@@ -719,17 +730,21 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
         actionId: 'save-credentials',
         tabId: 'credentials',
         mutationPayload: { integrationId: currentIntegrationId, credentials: sanitizedValues },
-        operation: () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/credentials`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ credentials: sanitizedValues }),
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(credentialsUpdatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/credentials`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ credentials: sanitizedValues }),
+          }, { fallback: null }),
+        ),
       })
 
       if (call.ok) {
         setCredValues(sanitizedValues)
         setCredentialsFormKey((current) => current + 1)
         flash(t('integrations.detail.credentials.saved'), 'success')
+        void loadCredentials()
         return
       }
 
@@ -745,7 +760,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
     } finally {
       setIsSavingCredentials(false)
     }
-  }, [resolveCurrentIntegrationId, runMutationWithContext, t])
+  }, [credentialsUpdatedAt, loadCredentials, resolveCurrentIntegrationId, runMutationWithContext, t])
 
   const handleVersionChange = React.useCallback(async (version: string) => {
     const currentIntegrationId = resolveCurrentIntegrationId()
@@ -755,22 +770,26 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
         actionId: 'change-version',
         tabId: 'version',
         mutationPayload: { integrationId: currentIntegrationId, apiVersion: version },
-        operation: () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/version`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ apiVersion: version }),
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(detail?.state.updatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/version`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ apiVersion: version }),
+          }, { fallback: null }),
+        ),
       })
       if (call.ok) {
         setDetail((prev) => prev ? { ...prev, state: { ...prev.state, apiVersion: version } } : prev)
         flash(t('integrations.detail.version.saved'), 'success')
+        void refreshDetail()
       } else {
         flash(t('integrations.detail.version.saveError'), 'error')
       }
     } catch {
       flash(t('integrations.detail.version.saveError'), 'error')
     }
-  }, [resolveCurrentIntegrationId, runMutationWithContext, t])
+  }, [detail?.state.updatedAt, refreshDetail, resolveCurrentIntegrationId, runMutationWithContext, t])
 
   const handleHealthCheck = React.useCallback(async () => {
     const currentIntegrationId = resolveCurrentIntegrationId()