@open-mercato/core 0.5.1-develop.2975.ccbadc8198 → 0.5.1-develop.2996.ce62fd491c

package/src/helpers/integration/authUi.ts

@@ -28,6 +28,6 @@ export async function createUserViaUi(page: Page, input: { email: string; passwo
 
   await page.getByRole('button', { name: 'Create' }).first().click();
   await expect(page).toHaveURL(/\/backend\/users(?:\?.*)?$/);
-  await page.getByRole('textbox', { name: 'Search' }).fill(input.email);
+  await page.getByRole('textbox', { name: 'Search', exact: true }).fill(input.email);
   await expect(page.getByRole('row', { name: new RegExp(input.email, 'i') })).toBeVisible();
 }

package/src/modules/audit_logs/services/actionLogService.ts

@@ -15,7 +15,10 @@ import {
   deriveActionLogProjection,
 } from '@open-mercato/core/modules/audit_logs/lib/projections'
 import { decryptWithAesGcm } from '@open-mercato/shared/lib/encryption/aes'
-import { TenantDataEncryptionService } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
+import {
+  TenantDataEncryptionService,
+  parseDecryptedFieldValue,
+} from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
 import { toOptionalString } from '@open-mercato/shared/lib/string/coerce'
 
 let validationWarningLogged = false
@@ -123,11 +126,7 @@ export class ActionLogService {
         if (typeof value === 'string' && value.split(':').length === 4 && value.endsWith(':v1')) {
           const decrypted = decryptWithAesGcm(value, dek.key)
           if (decrypted === null) return value
-          try {
-            return JSON.parse(decrypted)
-          } catch {
-            return decrypted
-          }
+          return parseDecryptedFieldValue(decrypted)
         }
         if (Array.isArray(value)) return value.map((item) => deepDecrypt(item))
         if (value && typeof value === 'object') {

package/src/modules/auth/api/sidebar/preferences/route.ts

@@ -1,8 +1,13 @@
 import { NextResponse } from 'next/server'
+import type { EntityManager, FilterQuery } from '@mikro-orm/postgresql'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-import { sidebarPreferencesInputSchema } from '../../../data/validators'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  sidebarPreferencesInputSchema,
+  sidebarPreferencesScopeSchema,
+} from '../../../data/validators'
 import {
   loadRoleSidebarPreferences,
   loadSidebarPreference,
@@ -17,6 +22,7 @@ import { z } from 'zod'
 export const metadata = {
   GET: { requireAuth: true },
   PUT: { requireAuth: true },
+  DELETE: { requireAuth: true },
 }
 
 const sidebarSettingsSchema = z.object({
@@ -25,6 +31,7 @@ const sidebarSettingsSchema = z.object({
   groupLabels: z.record(z.string(), z.string()),
   itemLabels: z.record(z.string(), z.string()),
   hiddenItems: z.array(z.string()),
+  itemOrder: z.record(z.string(), z.array(z.string())),
 })
 
 const sidebarRoleEntrySchema = z.object({
@@ -38,6 +45,7 @@ const sidebarPreferencesResponseSchema = z.object({
   settings: sidebarSettingsSchema,
   canApplyToRoles: z.boolean(),
   roles: z.array(sidebarRoleEntrySchema),
+  scope: sidebarPreferencesScopeSchema,
 })
 
 const sidebarPreferencesUpdateResponseSchema = sidebarPreferencesResponseSchema.extend({
@@ -45,25 +53,135 @@ const sidebarPreferencesUpdateResponseSchema = sidebarPreferencesResponseSchema.
   clearedRoles: z.array(z.string().uuid()),
 })
 
+const sidebarPreferencesDeleteResponseSchema = z.object({
+  ok: z.literal(true),
+  scope: sidebarPreferencesScopeSchema,
+})
+
 const sidebarErrorSchema = z.object({
   error: z.string(),
 })
 
+const FEATURE_MANAGE = 'auth.sidebar.manage'
+
+type EmptySettings = {
+  version: number
+  groupOrder: string[]
+  groupLabels: Record<string, string>
+  itemLabels: Record<string, string>
+  hiddenItems: string[]
+  itemOrder: Record<string, string[]>
+}
+
+function emptySettings(): EmptySettings {
+  return {
+    version: SIDEBAR_PREFERENCES_VERSION,
+    groupOrder: [],
+    groupLabels: {},
+    itemLabels: {},
+    hiddenItems: [],
+    itemOrder: {},
+  }
+}
+
+async function loadRolesPayload(
+  em: EntityManager,
+  options: { tenantId: string | null; locale: string },
+): Promise<Array<{ id: string; name: string; hasPreference: boolean }>> {
+  const roleScope: FilterQuery<Role> = options.tenantId
+    ? { $or: [{ tenantId: options.tenantId }, { tenantId: null }] }
+    : { tenantId: null }
+  const roles = await findWithDecryption(
+    em,
+    Role,
+    roleScope,
+    { orderBy: { name: 'asc' } },
+    { tenantId: options.tenantId, organizationId: null },
+  )
+  if (roles.length === 0) return []
+  const rolePrefs = await loadRoleSidebarPreferences(em, {
+    roleIds: roles.map((r: Role) => r.id),
+    tenantId: options.tenantId,
+    locale: options.locale,
+  })
+  return roles.map((role: Role) => ({
+    id: role.id,
+    name: role.name,
+    hasPreference: rolePrefs.has(role.id),
+  }))
+}
+
+async function findRoleInScope(
+  em: EntityManager,
+  options: { roleId: string; tenantId: string | null },
+): Promise<Role | null> {
+  const role = await findOneWithDecryption(
+    em,
+    Role,
+    { id: options.roleId },
+    undefined,
+    { tenantId: options.tenantId, organizationId: null },
+  )
+  if (!role) return null
+  // Cross-tenant guard: a role belongs to either the auth tenant or the global (null tenant) pool.
+  // Reject the lookup otherwise so a multi-tenant deployment can't leak across tenants.
+  if (role.tenantId && options.tenantId && role.tenantId !== options.tenantId) return null
+  if (role.tenantId && !options.tenantId) return null
+  return role
+}
+
 export async function GET(req: Request) {
   const auth = await getAuthFromRequest(req)
   if (!auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
 
+  const url = new URL(req.url)
+  const roleIdParam = url.searchParams.get('roleId')
+
   const { locale } = await resolveTranslations()
   const { resolve } = await createRequestContainer()
-  const em = resolve('em') as any
+  const em = resolve('em') as EntityManager
   const rbac = resolve('rbacService') as any
 
   const canApplyToRoles = await rbac.userHasAllFeatures?.(
     auth.sub,
-    ['auth.sidebar.manage'],
+    [FEATURE_MANAGE],
     { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null },
   ) ?? false
 
+  // Role-scoped read: requires `auth.sidebar.manage`.
+  if (roleIdParam) {
+    if (!canApplyToRoles) {
+      return NextResponse.json({ error: 'Forbidden', requiredFeatures: [FEATURE_MANAGE] }, { status: 403 })
+    }
+    const role = await findRoleInScope(em, { roleId: roleIdParam, tenantId: auth.tenantId ?? null })
+    if (!role) {
+      return NextResponse.json({ error: 'Role not found' }, { status: 404 })
+    }
+    const rolePrefs = await loadRoleSidebarPreferences(em, {
+      roleIds: [role.id],
+      tenantId: auth.tenantId ?? null,
+      locale,
+    })
+    const pref = rolePrefs.get(role.id) ?? null
+    const rolesPayload = await loadRolesPayload(em, { tenantId: auth.tenantId ?? null, locale })
+    return NextResponse.json({
+      locale,
+      settings: pref
+        ? {
+            version: pref.version ?? SIDEBAR_PREFERENCES_VERSION,
+            groupOrder: pref.groupOrder ?? [],
+            groupLabels: pref.groupLabels ?? {},
+            itemLabels: pref.itemLabels ?? {},
+            hiddenItems: pref.hiddenItems ?? [],
+            itemOrder: pref.itemOrder ?? {},
+          }
+        : emptySettings(),
+      canApplyToRoles,
+      roles: rolesPayload,
+      scope: { type: 'role', roleId: role.id },
+    })
+  }
+
   // For API key auth, use userId (the actual user) if available
   const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
   const settings = effectiveUserId
@@ -75,23 +193,9 @@ export async function GET(req: Request) {
       })
     : null
 
-  let rolesPayload: Array<{ id: string; name: string; hasPreference: boolean }> = []
-  if (canApplyToRoles) {
-    const roleScope = auth.tenantId
-      ? { $or: [{ tenantId: auth.tenantId }, { tenantId: null }] }
-      : { tenantId: null }
-    const roles = await em.find(Role, roleScope as any, { orderBy: { name: 'asc' } })
-    const rolePrefs = await loadRoleSidebarPreferences(em, {
-      roleIds: roles.map((r: Role) => r.id),
-      tenantId: auth.tenantId ?? null,
-      locale,
-    })
-    rolesPayload = roles.map((role: Role) => ({
-      id: role.id,
-      name: role.name,
-      hasPreference: rolePrefs.has(role.id),
-    }))
-  }
+  const rolesPayload = canApplyToRoles
+    ? await loadRolesPayload(em, { tenantId: auth.tenantId ?? null, locale })
+    : []
 
   return NextResponse.json({
     locale,
@@ -101,9 +205,11 @@ export async function GET(req: Request) {
       groupLabels: settings?.groupLabels ?? {},
       itemLabels: settings?.itemLabels ?? {},
       hiddenItems: settings?.hiddenItems ?? [],
+      itemOrder: settings?.itemOrder ?? {},
     },
     canApplyToRoles,
     roles: rolesPayload,
+    scope: { type: 'user' },
   })
 }
 
@@ -167,27 +273,86 @@ export async function PUT(req: Request) {
       }
       return values
     })(),
+    itemOrder: (() => {
+      const source = parsed.data.itemOrder ?? {}
+      const out: Record<string, string[]> = {}
+      for (const [groupKey, list] of Object.entries(source)) {
+        const trimmedGroup = groupKey.trim()
+        if (!trimmedGroup) continue
+        const seenItem = new Set<string>()
+        const values: string[] = []
+        for (const itemKey of list) {
+          const trimmedItem = itemKey.trim()
+          if (!trimmedItem || seenItem.has(trimmedItem)) continue
+          seenItem.add(trimmedItem)
+          values.push(trimmedItem)
+        }
+        if (values.length > 0) out[trimmedGroup] = values
+      }
+      return out
+    })(),
   }
 
   const { locale } = await resolveTranslations()
   const container = await createRequestContainer()
-  const em = container.resolve('em') as any
+  const em = container.resolve('em') as EntityManager
   const rbac = container.resolve('rbacService') as any
   const cache = container.resolve('cache') as { deleteByTags?: (tags: string[]) => Promise<unknown> } | undefined
 
-  const applyToRolesSource = parsed.data.applyToRoles ?? []
-  const applyToRoles = Array.from(new Set(applyToRolesSource.map((id) => id.trim()).filter((id) => id.length > 0)))
-  const clearRoleIdsSource = parsed.data.clearRoleIds ?? []
-  const clearRoleIds = Array.from(new Set(clearRoleIdsSource.map((id) => id.trim()).filter((id) => id.length > 0)))
-
   const canApplyToRoles = await rbac.userHasAllFeatures?.(
     auth.sub,
-    ['auth.sidebar.manage'],
+    [FEATURE_MANAGE],
     { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null },
   ) ?? false
 
+  const scope = parsed.data.scope ?? { type: 'user' as const }
+
+  // Role-scoped write: requires `auth.sidebar.manage` and a role visible to this tenant.
+  // applyToRoles/clearRoleIds are forbidden in role scope (validator already rejects them).
+  if (scope.type === 'role') {
+    if (!canApplyToRoles) {
+      return NextResponse.json({ error: 'Forbidden', requiredFeatures: [FEATURE_MANAGE] }, { status: 403 })
+    }
+    const role = await findRoleInScope(em, { roleId: scope.roleId, tenantId: auth.tenantId ?? null })
+    if (!role) {
+      return NextResponse.json({ error: 'Role not found' }, { status: 404 })
+    }
+    const saved = await saveRoleSidebarPreference(em, {
+      roleId: role.id,
+      tenantId: auth.tenantId ?? null,
+      locale,
+    }, payload)
+    if (cache?.deleteByTags) {
+      try {
+        await cache.deleteByTags([`nav:sidebar:role:${role.id}`])
+      } catch {}
+    }
+    const rolesPayload = await loadRolesPayload(em, { tenantId: auth.tenantId ?? null, locale })
+    return NextResponse.json({
+      locale,
+      settings: {
+        version: saved?.version ?? payload.version,
+        groupOrder: saved?.groupOrder ?? payload.groupOrder,
+        groupLabels: saved?.groupLabels ?? payload.groupLabels,
+        itemLabels: saved?.itemLabels ?? payload.itemLabels,
+        hiddenItems: saved?.hiddenItems ?? payload.hiddenItems,
+        itemOrder: saved?.itemOrder ?? payload.itemOrder,
+      },
+      canApplyToRoles,
+      roles: rolesPayload,
+      scope: { type: 'role', roleId: role.id },
+      appliedRoles: [],
+      clearedRoles: [],
+    })
+  }
+
+  const applyToRolesSource = parsed.data.applyToRoles ?? []
+  const applyToRoles = Array.from(new Set(applyToRolesSource.map((id) => id.trim()).filter((id) => id.length > 0)))
+  const clearRoleIdsSource = parsed.data.clearRoleIds ?? []
+  const clearRoleIds = Array.from(new Set(clearRoleIdsSource.map((id) => id.trim()).filter((id) => id.length > 0)))
+
   if ((applyToRoles.length > 0 || clearRoleIds.length > 0) && !canApplyToRoles) {
-    return NextResponse.json({ error: 'Forbidden', requiredFeatures: ['auth.sidebar.manage'] }, { status: 403 })
+    return NextResponse.json({ error: 'Forbidden', requiredFeatures: [FEATURE_MANAGE] }, { status: 403 })
   }
 
   const settings = await saveSidebarPreference(em, {
@@ -197,15 +362,21 @@ export async function PUT(req: Request) {
     locale,
   }, payload)
 
-  const roleScope = auth.tenantId
+  const roleScope: FilterQuery<Role> = auth.tenantId
     ? { $or: [{ tenantId: auth.tenantId }, { tenantId: null }] }
     : { tenantId: null }
   const availableRoles = canApplyToRoles
-    ? await em.find(Role, roleScope as any, { orderBy: { name: 'asc' } })
+    ? await findWithDecryption(
+        em,
+        Role,
+        roleScope,
+        { orderBy: { name: 'asc' } },
+        { tenantId: auth.tenantId ?? null, organizationId: null },
+      )
     : []
   const roleMap = new Map<string, Role>(availableRoles.map((role: Role) => [String(role.id), role]))
 
-  let updatedRoleIds: string[] = []
+  const updatedRoleIds: string[] = []
   if (applyToRoles.length > 0) {
     const missing = applyToRoles.filter((id) => !roleMap.has(id))
     if (missing.length) {
@@ -225,9 +396,11 @@ export async function PUT(req: Request) {
   const filteredClearRoleIds = clearRoleIds.filter((id) => !updatedRoleIds.includes(id) && !applyToRoles.includes(id))
 
   if (filteredClearRoleIds.length > 0) {
+    // Cross-locale: role preferences are unique per (role, tenantId); keep the delete
+    // filter aligned with save/load helpers so a clear from one locale does not leave
+    // a row created under another locale orphaned.
     await em.nativeDelete(RoleSidebarPreference, {
       role: { $in: filteredClearRoleIds },
-      locale,
       tenantId: auth.tenantId ?? null,
     })
     if (cache?.deleteByTags) {
@@ -267,26 +440,73 @@ export async function PUT(req: Request) {
     settings,
     canApplyToRoles,
     roles: rolesPayload,
+    scope: { type: 'user' },
     appliedRoles: updatedRoleIds,
     clearedRoles: filteredClearRoleIds,
   })
 }
 
+export async function DELETE(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+
+  const url = new URL(req.url)
+  const roleIdParam = url.searchParams.get('roleId')
+  if (!roleIdParam) {
+    return NextResponse.json({ error: 'roleId query parameter is required' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+  const rbac = container.resolve('rbacService') as any
+  const cache = container.resolve('cache') as { deleteByTags?: (tags: string[]) => Promise<unknown> } | undefined
+
+  const canApplyToRoles = await rbac.userHasAllFeatures?.(
+    auth.sub,
+    [FEATURE_MANAGE],
+    { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null },
+  ) ?? false
+  if (!canApplyToRoles) {
+    return NextResponse.json({ error: 'Forbidden', requiredFeatures: [FEATURE_MANAGE] }, { status: 403 })
+  }
+
+  const role = await findRoleInScope(em, { roleId: roleIdParam, tenantId: auth.tenantId ?? null })
+  if (!role) {
+    return NextResponse.json({ error: 'Role not found' }, { status: 404 })
+  }
+
+  // Cross-locale: keep the delete filter aligned with save/load helpers (no locale).
+  await em.nativeDelete(RoleSidebarPreference, {
+    role: role.id,
+    tenantId: auth.tenantId ?? null,
+  })
+
+  if (cache?.deleteByTags) {
+    try {
+      await cache.deleteByTags([`nav:sidebar:role:${role.id}`])
+    } catch {}
+  }
+
+  return NextResponse.json({ ok: true, scope: { type: 'role', roleId: role.id } })
+}
+
 export const openApi: OpenApiRouteDoc = {
   tag: 'Authentication & Accounts',
   summary: 'Sidebar preferences',
   methods: {
     GET: {
       summary: 'Get sidebar preferences',
-      description: 'Returns personal sidebar customization and any role-level preferences the user can manage.',
+      description: 'Returns sidebar customization for the current user (default) or the specified role (`?roleId=…`, requires `auth.sidebar.manage`).',
       responses: [
         { status: 200, description: 'Current sidebar configuration', schema: sidebarPreferencesResponseSchema },
         { status: 401, description: 'Unauthorized', schema: sidebarErrorSchema },
+        { status: 403, description: 'Missing features for role-scope read', schema: sidebarErrorSchema },
+        { status: 404, description: 'Role not found in current tenant scope', schema: sidebarErrorSchema },
       ],
     },
     PUT: {
       summary: 'Update sidebar preferences',
-      description: 'Updates personal sidebar configuration and, optionally, applies the same settings to selected roles.',
+      description: 'Updates sidebar configuration. With `scope.type === "user"` (default) writes the calling user\'s personal preferences and may optionally apply the same settings to selected roles via `applyToRoles[]`. With `scope.type === "role"` writes the named role variant directly (requires `auth.sidebar.manage`); `applyToRoles[]` and `clearRoleIds[]` are rejected in this mode.',
       requestBody: {
         contentType: 'application/json',
         schema: sidebarPreferencesInputSchema,
@@ -296,6 +516,18 @@ export const openApi: OpenApiRouteDoc = {
         { status: 400, description: 'Invalid payload', schema: sidebarErrorSchema },
         { status: 401, description: 'Unauthorized', schema: sidebarErrorSchema },
         { status: 403, description: 'Missing features for role-wide updates', schema: sidebarErrorSchema },
+        { status: 404, description: 'Role not found in current tenant scope', schema: sidebarErrorSchema },
+      ],
+    },
+    DELETE: {
+      summary: 'Delete a role sidebar variant',
+      description: 'Removes the role variant for the current tenant + locale. Idempotent. Requires `auth.sidebar.manage`.',
+      responses: [
+        { status: 200, description: 'Variant deleted (or never existed)', schema: sidebarPreferencesDeleteResponseSchema },
+        { status: 400, description: 'Missing roleId query parameter', schema: sidebarErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: sidebarErrorSchema },
+        { status: 403, description: 'Missing features', schema: sidebarErrorSchema },
+        { status: 404, description: 'Role not found in current tenant scope', schema: sidebarErrorSchema },
       ],
     },
   },

package/src/modules/auth/api/sidebar/variants/[id]/route.ts

@@ -0,0 +1,183 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { SIDEBAR_PREFERENCES_VERSION } from '@open-mercato/shared/modules/navigation/sidebarPreferences'
+import {
+  deleteSidebarVariant,
+  loadSidebarVariant,
+  updateSidebarVariant,
+  type SidebarVariantRecord,
+} from '../../../../services/sidebarPreferencesService'
+import {
+  sidebarVariantRecordSchema,
+  updateSidebarVariantInputSchema,
+} from '../../../../data/validators'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+
+export const metadata = {
+  GET: { requireAuth: true },
+  PUT: { requireAuth: true },
+  DELETE: { requireAuth: true },
+}
+
+const variantResponseSchema = z.object({
+  locale: z.string(),
+  variant: sidebarVariantRecordSchema,
+})
+
+const deleteResponseSchema = z.object({ ok: z.literal(true) })
+const errorSchema = z.object({ error: z.string() })
+
+function serializeVariant(record: SidebarVariantRecord) {
+  return {
+    id: record.id,
+    name: record.name,
+    isActive: record.isActive,
+    settings: {
+      version: record.settings.version ?? SIDEBAR_PREFERENCES_VERSION,
+      groupOrder: record.settings.groupOrder ?? [],
+      groupLabels: record.settings.groupLabels ?? {},
+      itemLabels: record.settings.itemLabels ?? {},
+      hiddenItems: record.settings.hiddenItems ?? [],
+      itemOrder: record.settings.itemOrder ?? {},
+    },
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt ? record.updatedAt.toISOString() : null,
+  }
+}
+
+function extractIdFromUrl(req: Request): string | null {
+  const url = new URL(req.url)
+  const segments = url.pathname.split('/').filter(Boolean)
+  // .../api/auth/sidebar/variants/<id>
+  return segments[segments.length - 1] || null
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
+  if (!effectiveUserId) return NextResponse.json({ error: 'No user context' }, { status: 403 })
+
+  const id = extractIdFromUrl(req)
+  if (!id) return NextResponse.json({ error: 'Invalid id' }, { status: 400 })
+
+  const { locale } = await resolveTranslations()
+  const { resolve } = await createRequestContainer()
+  const em = resolve('em') as EntityManager
+
+  const variant = await loadSidebarVariant(em, {
+    userId: effectiveUserId,
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    locale,
+  }, id)
+
+  if (!variant) return NextResponse.json({ error: 'Variant not found' }, { status: 404 })
+
+  return NextResponse.json({ locale, variant: serializeVariant(variant) })
+}
+
+export async function PUT(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
+  if (!effectiveUserId) return NextResponse.json({ error: 'No user context' }, { status: 403 })
+
+  const id = extractIdFromUrl(req)
+  if (!id) return NextResponse.json({ error: 'Invalid id' }, { status: 400 })
+
+  let parsedBody: unknown
+  try {
+    parsedBody = await req.json()
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })
+  }
+
+  const parsed = updateSidebarVariantInputSchema.safeParse(parsedBody)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
+  }
+
+  const { locale } = await resolveTranslations()
+  const { resolve } = await createRequestContainer()
+  const em = resolve('em') as EntityManager
+
+  const variant = await updateSidebarVariant(em, {
+    userId: effectiveUserId,
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    locale,
+  }, id, {
+    name: parsed.data.name,
+    settings: parsed.data.settings ?? null,
+    isActive: parsed.data.isActive,
+  })
+
+  if (!variant) return NextResponse.json({ error: 'Variant not found' }, { status: 404 })
+
+  return NextResponse.json({ locale, variant: serializeVariant(variant) })
+}
+
+export async function DELETE(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  const effectiveUserId = auth.isApiKey ? auth.userId : auth.sub
+  if (!effectiveUserId) return NextResponse.json({ error: 'No user context' }, { status: 403 })
+
+  const id = extractIdFromUrl(req)
+  if (!id) return NextResponse.json({ error: 'Invalid id' }, { status: 400 })
+
+  const { locale } = await resolveTranslations()
+  const { resolve } = await createRequestContainer()
+  const em = resolve('em') as EntityManager
+
+  const ok = await deleteSidebarVariant(em, {
+    userId: effectiveUserId,
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    locale,
+  }, id)
+
+  if (!ok) return NextResponse.json({ error: 'Variant not found' }, { status: 404 })
+
+  return NextResponse.json({ ok: true })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Authentication & Accounts',
+  summary: 'Sidebar variant',
+  methods: {
+    GET: {
+      summary: 'Get a sidebar variant',
+      responses: [
+        { status: 200, description: 'Variant', schema: variantResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Variant not found', schema: errorSchema },
+      ],
+    },
+    PUT: {
+      summary: 'Update a sidebar variant',
+      description: 'Updates the variant\'s name, settings, and/or isActive flag. Setting `isActive: true` deactivates other variants in the same scope (only one active per user/tenant/locale).',
+      requestBody: { contentType: 'application/json', schema: updateSidebarVariantInputSchema },
+      responses: [
+        { status: 200, description: 'Variant updated', schema: variantResponseSchema },
+        { status: 400, description: 'Invalid payload', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Variant not found', schema: errorSchema },
+      ],
+    },
+    DELETE: {
+      summary: 'Delete a sidebar variant',
+      description: 'Soft-deletes the variant (sets deleted_at).',
+      responses: [
+        { status: 200, description: 'Variant deleted', schema: deleteResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Variant not found', schema: errorSchema },
+      ],
+    },
+  },
+}