@open-mercato/core 0.6.2-develop.3467.1.2a1818709d → 0.6.2

package/src/modules/auth/api/users/route.ts

@@ -13,7 +13,11 @@ import { E } from '#generated/entities.ids.generated'
 import { loadCustomFieldValues } from '@open-mercato/shared/lib/crud/custom-fields'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { userCrudEvents, userCrudIndexer } from '@open-mercato/core/modules/auth/commands/users'
-import { assertActorCanGrantRoleTokens } from '@open-mercato/core/modules/auth/lib/grantChecks'
+import {
+  assertActorCanGrantRoleTokens,
+  assertActorCanModifySuperAdminUserTarget,
+  listSuperAdminUserIds,
+} from '@open-mercato/core/modules/auth/lib/grantChecks'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { buildPasswordSchema } from '@open-mercato/shared/lib/auth/passwordPolicy'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
@@ -21,6 +25,10 @@ import { resolveSearchConfig } from '@open-mercato/shared/lib/search/config'
 import { tokenizeText } from '@open-mercato/shared/lib/search/tokenize'
 import { sql } from 'kysely'
 import { normalizeDisplayNameInput } from '@open-mercato/core/modules/auth/lib/displayName'
+import {
+  getSelectedTenantFromRequest,
+  resolveOrganizationScopeForRequest,
+} from '@open-mercato/core/modules/directory/utils/organizationScope'
 
 const querySchema = z.object({
   id: z.string().uuid().optional(),
@@ -86,6 +94,7 @@ const okResponseSchema = z.object({ ok: z.literal(true) })
 const errorResponseSchema = z.object({ error: z.string() })
 
 type CrudInput = Record<string, unknown>
+type UserListFilter = Record<string, unknown>
 
 const routeMetadata = {
   GET: { requireAuth: true, requireFeatures: ['auth.users.list'] },
@@ -128,6 +137,9 @@ const crud = makeCrudRoute<CrudInput, CrudInput, Record<string, unknown>>({
       schema: rawBodySchema,
       mapInput: async ({ parsed, ctx }) => {
         if (ctx.request) {
+          if (typeof parsed.id === 'string' && parsed.id.length) {
+            await assertCanModifySuperAdminTarget(ctx.request, parsed.id)
+          }
           await assertCanAssignRoles(ctx.request, parsed.roles, parsed)
         }
         return parsed
@@ -158,12 +170,12 @@ export async function GET(req: Request) {
   if (!parsed.success) return NextResponse.json({ items: [], total: 0, totalPages: 1 })
   const container = await createRequestContainer()
   const em = (container.resolve('em') as EntityManager)
-  let isSuperAdmin = false
+  let isSuperAdmin = auth.isSuperAdmin === true
   try {
     if (auth.sub) {
       const rbacService = container.resolve('rbacService') as any
       const acl = await rbacService.loadAcl(auth.sub, { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null })
-      isSuperAdmin = !!acl?.isSuperAdmin
+      isSuperAdmin = isSuperAdmin || !!acl?.isSuperAdmin
     }
   } catch (err) {
     console.error('users: failed to resolve rbac', err)
@@ -171,16 +183,62 @@ export async function GET(req: Request) {
   const { id, page, pageSize, search, name, organizationId, roleIds } = parsed.data
   const filters: any[] = [{ deletedAt: null }]
   const actorTenantId = auth.tenantId ? String(auth.tenantId) : null
+  let effectiveTenantId: string | null = null
+  let effectiveOrganizationIds: string[] | null = null
+  let effectiveSelectedOrganizationId: string | null = null
+  let usesSelectedTenantScope = false
   if (!isSuperAdmin) {
     if (!actorTenantId) {
       return NextResponse.json({ items: [], total: 0, totalPages: 1, isSuperAdmin })
     }
-    filters.push({ tenantId: actorTenantId })
+    effectiveTenantId = actorTenantId
+    const superAdminUserIds = await listSuperAdminUserIds(em, actorTenantId)
+    if (superAdminUserIds.size) {
+      filters.push({ id: { $nin: Array.from(superAdminUserIds) as any } })
+    }
+  } else {
+    const selectedTenantId = getSelectedTenantFromRequest(req)
+    if (typeof selectedTenantId === 'string' && selectedTenantId.trim().length > 0) {
+      const scope = await resolveOrganizationScopeForRequest({
+        container,
+        auth,
+        request: req,
+        tenantId: selectedTenantId.trim(),
+      })
+      if (!scope.tenantId) {
+        return NextResponse.json({ items: [], total: 0, totalPages: 1, isSuperAdmin })
+      }
+      effectiveTenantId = scope.tenantId
+      effectiveSelectedOrganizationId = scope.selectedId
+      usesSelectedTenantScope = true
+      if (Array.isArray(scope.filterIds)) {
+        if (scope.filterIds.length === 0) {
+          return NextResponse.json({ items: [], total: 0, totalPages: 1, isSuperAdmin })
+        }
+        effectiveOrganizationIds = scope.filterIds
+      }
+    }
+  }
+  if (effectiveTenantId) {
+    filters.push({ tenantId: effectiveTenantId })
+  }
+  if (effectiveOrganizationIds) {
+    filters.push({ organizationId: { $in: effectiveOrganizationIds as any } })
   }
+  const scopeOrganizationId = usesSelectedTenantScope
+    ? effectiveSelectedOrganizationId
+    : auth.orgId ?? null
   if (organizationId) filters.push({ organizationId })
   const trimmedName = typeof name === 'string' ? name.trim() : ''
   if (trimmedName) {
-    filters.push({ name: { $ilike: `%${escapeLikePattern(trimmedName)}%` } })
+    const searchPattern = `%${escapeLikePattern(trimmedName)}%`
+    const displayNameFilters: UserListFilter[] = [{ name: { $ilike: searchPattern } }]
+    const nameTokenScope: string | null | undefined = isSuperAdmin ? (effectiveTenantId ?? undefined) : auth.tenantId ?? null
+    const matchedDisplayNameIds = await findUserIdsBySearchTokens(em, E.auth.user, trimmedName, nameTokenScope, 'name')
+    if (matchedDisplayNameIds && matchedDisplayNameIds.length) {
+      displayNameFilters.push({ id: { $in: matchedDisplayNameIds } })
+    }
+    filters.push(displayNameFilters.length > 1 ? { $or: displayNameFilters } : displayNameFilters[0])
   }
   let idFilter: Set<string> | null = id ? new Set([id]) : null
   if (Array.isArray(roleIds) && roleIds.length > 0) {
@@ -204,7 +262,7 @@ export async function GET(req: Request) {
   const trimmedSearch = typeof search === 'string' ? search.trim() : ''
   if (trimmedSearch) {
     // Email is encrypted at rest, so plaintext search must go through search_tokens.
-    const tenantScope: string | null | undefined = isSuperAdmin ? undefined : auth.tenantId ?? null
+    const tenantScope: string | null | undefined = isSuperAdmin ? (effectiveTenantId ?? undefined) : auth.tenantId ?? null
     const searchFilters: any[] = []
 
     const matchedIds = await findUserIdsBySearchTokens(em, E.auth.user, trimmedSearch, tenantScope)
@@ -284,7 +342,10 @@ export async function GET(req: Request) {
         UserRole,
         { user: { $in: userIds as any } } as any,
         { populate: ['role'] },
-        { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null },
+        {
+          tenantId: effectiveTenantId ?? auth.tenantId ?? null,
+          organizationId: scopeOrganizationId,
+        },
       )
     : []
   const roleMap: Record<string, string[]> = {}
@@ -350,7 +411,7 @@ export async function GET(req: Request) {
         recordIds: userIds.map(String),
         tenantIdByRecord: tenantByUser,
         organizationIdByRecord: organizationByUser,
-        tenantFallbacks: auth.tenantId ? [auth.tenantId] : [],
+        tenantFallbacks: effectiveTenantId ? [effectiveTenantId] : auth.tenantId ? [auth.tenantId] : [],
       })
     : {}
 
@@ -379,8 +440,8 @@ export async function GET(req: Request) {
     items,
     idField: 'id',
     resourceKind: 'auth.user',
-    organizationId: null,
-    tenantId: auth.tenantId ?? null,
+    organizationId: effectiveSelectedOrganizationId,
+    tenantId: effectiveTenantId ?? auth.tenantId ?? null,
     query: parsed.data,
     accessType: id ? 'read:item' : undefined,
   })
@@ -395,13 +456,27 @@ export const PUT = async (req: Request) => {
   return crud.PUT(req)
 }
 
-export const DELETE = crud.DELETE
+export const DELETE = async (req: Request) => {
+  const targetId = new URL(req.url).searchParams.get('id')
+  if (targetId) {
+    try {
+      await assertCanModifySuperAdminTarget(req, targetId)
+    } catch (err) {
+      if (err instanceof CrudHttpError) {
+        return NextResponse.json(err.body, { status: err.status })
+      }
+      throw err
+    }
+  }
+  return crud.DELETE(req)
+}
 
 async function findUserIdsBySearchTokens(
   em: EntityManager,
   entityType: string,
   search: string,
   tenantScope: string | null | undefined,
+  field?: string,
 ): Promise<string[] | null> {
   const trimmed = search.trim()
   if (!trimmed) return null
@@ -418,6 +493,9 @@ async function findUserIdsBySearchTokens(
     .where('token_hash', 'in', hashes)
     .groupBy('entity_id')
     .having(sql<boolean>`count(distinct token_hash) >= ${hashes.length}`)
+  if (field) {
+    query = query.where('field', '=', field)
+  }
   if (tenantScope !== undefined) {
     query = query.where(sql<boolean>`tenant_id is not distinct from ${tenantScope}`)
   }
@@ -427,6 +505,21 @@ async function findUserIdsBySearchTokens(
     .filter((id): id is string => typeof id === 'string' && id.length > 0)
 }
 
+async function assertCanModifySuperAdminTarget(req: Request, targetUserId: string) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub) throw new CrudHttpError(401, { error: 'Unauthorized' })
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+  await assertActorCanModifySuperAdminUserTarget({
+    em,
+    rbacService: container.resolve('rbacService') as RbacService,
+    actorUserId: auth.sub,
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    targetUserId,
+  })
+}
+
 async function assertCanAssignRoles(req: Request, roles: unknown, payload: Record<string, unknown>) {
   if (!Array.isArray(roles)) return
   const auth = await getAuthFromRequest(req)
@@ -483,7 +576,7 @@ export const openApi: OpenApiRouteDoc = {
     GET: {
       summary: 'List users',
       description:
-        'Returns users for the current tenant. Search matches email, organization name, and role name. Super administrators may scope the response via organization or role filters.',
+        'Returns users for the effective selected tenant and organization scope. Search matches email, organization name, and role name. Super administrators may scope the response via the topbar context, organization filters, or role filters.',
       query: querySchema,
       responses: [
         { status: 200, description: 'User collection', schema: userListResponseSchema },

package/src/modules/auth/backend/roles/[id]/edit/page.tsx

@@ -9,6 +9,7 @@ import { AclEditor, type AclData } from '@open-mercato/core/modules/auth/compone
 import { WidgetVisibilityEditor, type WidgetVisibilityEditorHandle } from '@open-mercato/core/modules/dashboards/components/WidgetVisibilityEditor'
 import { E } from '#generated/entities.ids.generated'
 import { TenantSelect } from '@open-mercato/core/modules/directory/components/TenantSelect'
+import { Alert } from '@open-mercato/ui/primitives/alert'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-fields-client'
 
@@ -93,6 +94,7 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
         label: t('auth.roles.form.field.tenant', 'Tenant'),
         type: 'custom',
         required: true,
+        disabled,
         component: ({ value, setValue }) => {
           const normalizedValue = typeof value === 'string'
             ? value
@@ -104,10 +106,13 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
               onChange={(next) => {
                 const resolved = next ?? null
                 setValue(resolved)
+                if (selectedTenantId !== resolved) {
+                  setAclData((prev) => ({ ...prev, organizations: null }))
+                }
                 setSelectedTenantId(resolved)
-                setAclData({ isSuperAdmin: false, features: [], organizations: null })
               }}
               includeEmptyOption
+              disabled={disabled}
               className="w-full h-9 rounded border px-2 text-sm"
               tenants={preloadedTenants}
             />
@@ -131,19 +136,35 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
       id: 'acl',
       title: t('auth.roles.form.group.access', 'Access'),
       column: 1,
-      component: () => (id
-        ? (
-          <AclEditor
-            kind="role"
-            targetId={String(id)}
-            canEditOrganizations
-            value={aclData}
-            onChange={setAclData}
-            currentUserIsSuperAdmin={actorIsSuperAdmin}
-            tenantId={selectedTenantId ?? null}
-          />
+      component: () => {
+        if (!id) return null
+        const initialTenantId = initial?.tenantId ?? null
+        const tenantReassigned = actorIsSuperAdmin
+          && initial != null
+          && (selectedTenantId ?? null) !== (initialTenantId ?? null)
+        return (
+          <div className="space-y-3">
+            {tenantReassigned ? (
+              <Alert status="warning" style="lighter">
+                {t(
+                  'auth.roles.form.tenantReassignWarning',
+                  'This role is being reassigned to a different tenant. The permissions selected here will be saved under the new tenant when you submit.',
+                )}
+              </Alert>
+            ) : null}
+            <AclEditor
+              kind="role"
+              targetId={String(id)}
+              canEditOrganizations
+              value={aclData}
+              onChange={setAclData}
+              currentUserIsSuperAdmin={actorIsSuperAdmin}
+              tenantId={selectedTenantId ?? null}
+              preserveOnTenantChange
+            />
+          </div>
         )
-        : null),
+      },
     },
     {
       id: 'dashboardWidgets',
@@ -155,6 +176,7 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
             kind="role"
             targetId={String(id)}
             tenantId={selectedTenantId ?? (initial?.tenantId ?? null)}
+            preserveOnTenantChange
             ref={widgetEditorRef}
           />
         )

package/src/modules/auth/backend/users/[id]/edit/page.tsx

@@ -254,7 +254,7 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
     if (!actorResolved) return []
     if (actorIsSuperAdmin) {
       if (!selectedTenantId) return []
-      return fetchRoleOptions(query, { tenantId: selectedTenantId })
+      return fetchRoleOptions(query, { tenantId: selectedTenantId, includeSuperAdmin: true })
     }
     return fetchRoleOptions(query)
   }, [actorIsSuperAdmin, actorResolved, selectedTenantId])

package/src/modules/auth/backend/users/create/page.tsx

@@ -171,7 +171,7 @@ export default function CreateUserPage() {
     if (!actorResolved) return []
     if (actorIsSuperAdmin) {
       if (!selectedTenantId) return []
-      return fetchRoleOptions(query, { tenantId: selectedTenantId })
+      return fetchRoleOptions(query, { tenantId: selectedTenantId, includeSuperAdmin: true })
     }
     return fetchRoleOptions(query)
   }, [actorIsSuperAdmin, actorResolved, selectedTenantId])

package/src/modules/auth/backend/users/roleOptions.ts

@@ -7,6 +7,7 @@ type RoleListResponse = {
 
 type FetchRoleOptionsParams = {
   tenantId?: string | null
+  includeSuperAdmin?: boolean
 }
 
 export async function fetchRoleOptions(query?: string, params?: FetchRoleOptionsParams): Promise<CrudFieldOption[]> {
@@ -28,7 +29,7 @@ export async function fetchRoleOptions(query?: string, params?: FetchRoleOptions
         const id = typeof item?.id === 'string' ? item.id.trim() : ''
         const name = typeof item?.name === 'string' ? item?.name.trim() : ''
         if (!id || !name) return null
-        if (name === 'superadmin') return null
+        if (name === 'superadmin' && !params?.includeSuperAdmin) return null
         return { value: id, label: name }
       })
       .filter((opt): opt is CrudFieldOption => !!opt)

package/src/modules/auth/commands/roles.ts

@@ -235,6 +235,14 @@ const updateRoleCommand: CommandHandler<Record<string, unknown>, Role> = {
         }
       }
     }
+    const wantsTenantChange = parsed.tenantId !== undefined && parsed.tenantId !== current.tenantId
+    if (wantsTenantChange) {
+      const assignments = await em.count(UserRole, { role: current, deletedAt: null })
+      if (assignments > 0) {
+        throw new CrudHttpError(400, { error: 'Role cannot be moved to another tenant while users are assigned' })
+      }
+      await em.nativeDelete(RoleAcl, { role: parsed.id as unknown as Role })
+    }
     const de = (ctx.container.resolve('dataEngine') as DataEngine)
     const role = await de.updateOrmEntity({
       entity: Role,

package/src/modules/auth/commands/users.ts

@@ -286,6 +286,7 @@ const createUserCommand: CommandHandler<Record<string, unknown>, CreateUserResul
       resourceKind: 'auth.user',
       resourceId: String(user.id),
       tenantId: user.tenantId ? String(user.tenantId) : null,
+      organizationId: user.organizationId ? String(user.organizationId) : null,
       snapshotAfter: snapshot.view,
       payload: {
         undo: {
@@ -559,6 +560,7 @@ const updateUserCommand: CommandHandler<Record<string, unknown>, User> = {
       resourceKind: 'auth.user',
       resourceId: String(result.id),
       tenantId: result.tenantId ? String(result.tenantId) : null,
+      organizationId: result.organizationId ? String(result.organizationId) : null,
       changes,
       snapshotBefore: before ?? null,
       snapshotAfter: after,
@@ -689,6 +691,7 @@ const deleteUserCommand: CommandHandler<{ body?: Record<string, unknown>; query?
       resourceId: id,
       snapshotBefore: before ?? null,
       tenantId: before?.tenantId ?? null,
+      organizationId: before?.organizationId ?? null,
       payload: {
         undo: {
           before: beforeUndo,

package/src/modules/auth/components/AclEditor.tsx

@@ -100,6 +100,7 @@ export function AclEditor({
   userRoles,
   currentUserIsSuperAdmin,
   tenantId,
+  preserveOnTenantChange = false,
 }: {
   kind: 'user' | 'role'
   targetId: string
@@ -109,6 +110,7 @@ export function AclEditor({
   userRoles?: string[]
   currentUserIsSuperAdmin?: boolean
   tenantId?: string | null
+  preserveOnTenantChange?: boolean
 }) {
   const actorIsSuperAdmin = !!currentUserIsSuperAdmin
   const [loading, setLoading] = React.useState(true)
@@ -142,8 +144,33 @@ export function AclEditor({
     [actorSanitizeFeatures],
   )
 
+  const tenantIdRef = React.useRef(tenantId)
+  React.useEffect(() => { tenantIdRef.current = tenantId }, [tenantId])
+  const hasMountedRef = React.useRef(false)
+
+  const fetchAclState = React.useCallback(async (forTenantId: string | null | undefined, cancelledRef: { current: boolean }) => {
+    try {
+      const aclQuery = new URLSearchParams()
+      aclQuery.set(kind === 'user' ? 'userId' : 'roleId', targetId)
+      if (forTenantId) aclQuery.set('tenantId', forTenantId)
+      const aclQueryString = aclQuery.toString()
+      const aclJson = await readJsonOr<AclPayload>(
+        `/api/auth/${kind === 'user' ? 'users' : 'roles'}/acl${aclQueryString ? `?${aclQueryString}` : ''}`,
+        undefined,
+        { hasCustomAcl: true, isSuperAdmin: false, features: [], organizations: null },
+      )
+      if (cancelledRef.current) return
+      const customAclExists = aclJson.hasCustomAcl !== false
+      setHasCustomAcl(customAclExists)
+      setOverrideEnabled(customAclExists)
+      setIsSuperAdmin(!!aclJson.isSuperAdmin)
+      setGranted(actorSanitizeFeatures(aclJson.features))
+      setOrganizations(aclJson.organizations == null ? null : Array.isArray(aclJson.organizations) ? aclJson.organizations : [])
+    } catch {}
+  }, [kind, targetId, actorSanitizeFeatures])
+
   React.useEffect(() => {
-    let cancelled = false
+    const cancelled = { current: false }
     async function load() {
       setLoading(true)
       try {
@@ -152,30 +179,30 @@ export function AclEditor({
           undefined,
           { items: [], modules: [] },
         )
-        if (!cancelled) {
+        if (!cancelled.current) {
           setFeatures(fJson.items || [])
           setModules(fJson.modules || [])
         }
       } catch {}
-      try {
-        const aclQuery = new URLSearchParams()
-        aclQuery.set(kind === 'user' ? 'userId' : 'roleId', targetId)
-        if (tenantId) aclQuery.set('tenantId', tenantId)
-        const aclQueryString = aclQuery.toString()
-        const aclJson = await readJsonOr<AclPayload>(
-          `/api/auth/${kind === 'user' ? 'users' : 'roles'}/acl${aclQueryString ? `?${aclQueryString}` : ''}`,
-          undefined,
-          { hasCustomAcl: true, isSuperAdmin: false, features: [], organizations: null },
-        )
-        if (!cancelled) {
-          const customAclExists = aclJson.hasCustomAcl !== false
-          setHasCustomAcl(customAclExists)
-          setOverrideEnabled(customAclExists)
-          setIsSuperAdmin(!!aclJson.isSuperAdmin)
-          setGranted(actorSanitizeFeatures(aclJson.features))
-          setOrganizations(aclJson.organizations == null ? null : Array.isArray(aclJson.organizations) ? aclJson.organizations : [])
-        }
-      } catch {}
+      await fetchAclState(tenantIdRef.current, cancelled)
+      hasMountedRef.current = true
+      if (!cancelled.current) setLoading(false)
+    }
+    load()
+    return () => { cancelled.current = true }
+  }, [kind, targetId, fetchAclState])
+
+  React.useEffect(() => {
+    if (!hasMountedRef.current) return
+    if (preserveOnTenantChange) return
+    const cancelled = { current: false }
+    fetchAclState(tenantId, cancelled)
+    return () => { cancelled.current = true }
+  }, [tenantId, preserveOnTenantChange, fetchAclState])
+
+  React.useEffect(() => {
+    let cancelled = false
+    async function loadTenantScoped() {
       if (canEditOrganizations) {
         try {
           const orgQuery = new URLSearchParams()
@@ -206,11 +233,10 @@ export function AclEditor({
           }
         } catch {}
       }
-      if (!cancelled) setLoading(false)
     }
-    load()
+    loadTenantScoped()
     return () => { cancelled = true }
-  }, [kind, targetId, canEditOrganizations, userRoles, actorSanitizeFeatures, tenantId])
+  }, [kind, canEditOrganizations, userRoles, tenantId])
 
   // Notify parent of changes
   React.useEffect(() => {

package/src/modules/auth/lib/grantChecks.ts

@@ -1,8 +1,8 @@
 import type { EntityManager, FilterQuery } from '@mikro-orm/postgresql'
 import { CrudHttpError, forbidden } from '@open-mercato/shared/lib/crud/errors'
 import { hasFeature } from '@open-mercato/shared/security/features'
-import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import { Role, RoleAcl } from '@open-mercato/core/modules/auth/data/entities'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Role, RoleAcl, UserAcl, UserRole } from '@open-mercato/core/modules/auth/data/entities'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 
 type ActorAcl = {
@@ -33,6 +33,16 @@ type FeatureGrantCheckInput = GrantCheckContext & {
   organizations?: string[] | null
 }
 
+type SuperAdminUserTargetInput = GrantCheckContext & {
+  targetUserId: string
+  actorIsSuperAdmin?: boolean
+}
+
+type SuperAdminRoleTargetInput = GrantCheckContext & {
+  targetRoleId: string
+  actorIsSuperAdmin?: boolean
+}
+
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 export async function assertActorCanGrantRoleTokens(input: RoleTokenGrantCheckInput): Promise<Role[]> {
@@ -99,6 +109,110 @@ export function normalizeGrantFeatureList(features: unknown): string[] {
   return normalizeStringList(features)
 }
 
+export async function assertActorCanModifySuperAdminUserTarget(input: SuperAdminUserTargetInput): Promise<void> {
+  const actorIsSuperAdmin = await resolveActorIsSuperAdmin(input)
+  if (actorIsSuperAdmin) return
+  const targetIsSuperAdmin = await isUserEffectivelySuperAdmin(input.em, input.targetUserId)
+  if (targetIsSuperAdmin) {
+    throw forbidden('Only super administrators can modify super administrator accounts.')
+  }
+}
+
+export async function assertActorCanModifySuperAdminRoleTarget(input: SuperAdminRoleTargetInput): Promise<void> {
+  const actorIsSuperAdmin = await resolveActorIsSuperAdmin(input)
+  if (actorIsSuperAdmin) return
+  const targetIsSuperAdmin = await isRoleEffectivelySuperAdmin(input.em, input.targetRoleId)
+  if (targetIsSuperAdmin) {
+    throw forbidden('Only super administrators can modify super administrator roles.')
+  }
+}
+
+async function resolveActorIsSuperAdmin(input: GrantCheckContext & { actorIsSuperAdmin?: boolean }): Promise<boolean> {
+  if (typeof input.actorIsSuperAdmin === 'boolean') return input.actorIsSuperAdmin
+  const acl = await loadActorAcl(input)
+  return acl.isSuperAdmin
+}
+
+export async function isUserEffectivelySuperAdmin(em: EntityManager, userId: string): Promise<boolean> {
+  const directGrant = await em.findOne(
+    UserAcl,
+    { user: userId as unknown, isSuperAdmin: true } as FilterQuery<UserAcl>,
+  )
+  if (directGrant && (directGrant as { isSuperAdmin?: boolean }).isSuperAdmin === true) return true
+  const links = await findWithDecryption(
+    em,
+    UserRole,
+    { user: userId as unknown } as FilterQuery<UserRole>,
+    { populate: ['role'] },
+    { tenantId: null, organizationId: null },
+  )
+  const roleIds = (Array.isArray(links) ? links : [])
+    .map((link) => {
+      const role = (link as { role?: { id?: unknown } | string | null }).role
+      if (!role) return null
+      if (typeof role === 'string') return role
+      return role.id ? String(role.id) : null
+    })
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+  if (!roleIds.length) return false
+  const roleGrant = await em.findOne(
+    RoleAcl,
+    { role: { $in: roleIds } as unknown, isSuperAdmin: true } as FilterQuery<RoleAcl>,
+  )
+  return !!roleGrant && (roleGrant as { isSuperAdmin?: boolean }).isSuperAdmin === true
+}
+
+export async function isRoleEffectivelySuperAdmin(em: EntityManager, roleId: string): Promise<boolean> {
+  const grant = await em.findOne(
+    RoleAcl,
+    { role: roleId as unknown, isSuperAdmin: true } as FilterQuery<RoleAcl>,
+  )
+  return !!grant && (grant as { isSuperAdmin?: boolean }).isSuperAdmin === true
+}
+
+export async function listSuperAdminUserIds(em: EntityManager, tenantId: string | null): Promise<Set<string>> {
+  const ids = new Set<string>()
+  const userAclFilter: Record<string, unknown> = { isSuperAdmin: true }
+  if (tenantId) userAclFilter.tenantId = tenantId
+  const userAcls = await em.find(UserAcl, userAclFilter as FilterQuery<UserAcl>)
+  for (const acl of userAcls) {
+    const userRef = (acl as { user?: { id?: unknown } | string | null }).user
+    const userId = userRef && typeof userRef === 'object'
+      ? userRef.id
+      : userRef
+    if (userId) ids.add(String(userId))
+  }
+  const roleAcls = await em.find(
+    RoleAcl,
+    { isSuperAdmin: true } as FilterQuery<RoleAcl>,
+  )
+  const roleIds = roleAcls
+    .map((acl) => {
+      const roleRef = (acl as { role?: { id?: unknown } | string | null }).role
+      if (!roleRef) return null
+      if (typeof roleRef === 'string') return roleRef
+      return roleRef.id ? String(roleRef.id) : null
+    })
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+  if (roleIds.length) {
+    const links = await findWithDecryption(
+      em,
+      UserRole,
+      { role: { $in: roleIds } as unknown } as FilterQuery<UserRole>,
+      {},
+      { tenantId: null, organizationId: null },
+    )
+    for (const link of Array.isArray(links) ? links : []) {
+      const userRef = (link as { user?: { id?: unknown } | string | null }).user
+      const userId = userRef && typeof userRef === 'object'
+        ? userRef.id
+        : userRef
+      if (userId) ids.add(String(userId))
+    }
+  }
+  return ids
+}
+
 async function loadActorAcl(input: GrantCheckContext): Promise<ActorAcl> {
   const actorUserId = normalizeNullableString(input.actorUserId)
   if (!actorUserId) throw forbidden('Not authorized to grant ACL privileges.')