@adonis-agora/authkit-server 0.34.0

package/build/src/host/admin_api/api_orgs_controller.js

@@ -0,0 +1,189 @@
+import '../augmentations.js';
+import { AdminOrgsService } from './admin_orgs_service.js';
+import { orgDto, orgDetailDto, orgInvitationDto, apiError } from './dto.js';
+import { resolveRuntimeSettings } from '../runtime_settings.js';
+import { orgCreateValidator, orgUpdateValidator, orgAddMemberValidator, orgMemberRoleValidator, orgInvitationValidator, } from '../admin_validators.js';
+/** Lê a config + monta o actor `admin-api` para auditoria. */
+async function ctxBits(ctx) {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const cfg = service.config;
+    const actor = { actorId: null, ip: ctx.request.ip?.() ?? null, source: 'admin-api' };
+    return { service, cfg, actor };
+}
+/** Helper: 404 JSON quando organizations não é suportado. */
+function notSupported(ctx) {
+    return ctx.response.notFound(apiError('capability_unsupported', 'Organizations não é suportado nesta instalação.'));
+}
+/**
+ * CRUD de organizações da Admin REST API.
+ * Todas as rotas ficam sob `/api/authkit/v1/organizations`.
+ */
+export default class ApiOrgsController {
+    /** GET /organizations — lista todas as orgs com contagem de membros. */
+    async index(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const result = await svc.listOrgs();
+        if (!Array.isArray(result)) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+        }
+        const orgs = result;
+        if (!Array.isArray(orgs))
+            return notSupported(ctx);
+        return { data: orgs.map(orgDto) };
+    }
+    /** POST /organizations — cria uma org. Body: { name, slug, ownerAccountId, logoUrl? } */
+    async store(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const { name, slug, ownerAccountId, logoUrl } = await ctx.request.validateUsing(orgCreateValidator);
+        const result = await svc.createOrg({ name, slug, logoUrl: logoUrl ?? null, ownerAccountId }, actor);
+        if ('ok' in result && result.ok === false) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            return ctx.response.conflict(apiError('slug_taken', 'Já existe uma org com este slug.'));
+        }
+        ctx.response.status(201);
+        return orgDto(result);
+    }
+    /** GET /organizations/:id — obtém uma org com membros e convites. */
+    async show(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const id = ctx.request.param('id');
+        const result = await svc.getOrg(id);
+        if ('ok' in result && result.ok === false) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+        }
+        return orgDetailDto(result);
+    }
+    /** PATCH /organizations/:id — atualiza nome e/ou logo. */
+    async update(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const id = ctx.request.param('id');
+        const { name, logoUrl } = await ctx.request.validateUsing(orgUpdateValidator);
+        const patch = {};
+        if (name !== undefined)
+            patch.name = name;
+        if (logoUrl !== undefined)
+            patch.logoUrl = logoUrl;
+        const result = await svc.updateOrg(id, patch, actor);
+        if ('ok' in result && result.ok === false) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            if (result.reason === 'not_found')
+                return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+            return ctx.response.conflict(apiError('slug_taken', 'Já existe uma org com este slug.'));
+        }
+        return orgDto(result);
+    }
+    /** DELETE /organizations/:id */
+    async destroy(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const id = ctx.request.param('id');
+        const result = await svc.deleteOrg(id, actor);
+        if (!result.ok) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+        }
+        return { id, deleted: true };
+    }
+    /** POST /organizations/:id/members — adiciona membro. Body: { accountId, role } */
+    async addMember(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const orgId = ctx.request.param('id');
+        const { accountId, role } = await ctx.request.validateUsing(orgAddMemberValidator);
+        const result = await svc.addMember(orgId, { accountId, role: role ?? 'member' }, actor, await resolveRuntimeSettings(ctx));
+        if (!result.ok) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            if (result.reason === 'not_found')
+                return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+            if (result.reason === 'invalid_role')
+                return ctx.response.unprocessableEntity(apiError('invalid_role', 'Role inválida — fora do catálogo da organização.'));
+            return ctx.response.notFound(apiError('account_not_found', 'Conta não encontrada.'));
+        }
+        ctx.response.status(201);
+        return { orgId, accountId, role, added: true };
+    }
+    /** DELETE /organizations/:id/members/:accountId */
+    async removeMember(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const orgId = ctx.request.param('id');
+        const accountId = ctx.request.param('accountId');
+        const result = await svc.removeMember(orgId, accountId, actor);
+        if (!result.ok) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            if (result.reason === 'not_found')
+                return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+            if (result.reason === 'last_owner')
+                return ctx.response.conflict(apiError('last_owner', 'Não é possível remover o último owner.'));
+            return ctx.response.notFound(apiError('member_not_found', 'Membro não encontrado.'));
+        }
+        return { orgId, accountId, removed: true };
+    }
+    /** PATCH /organizations/:id/members/:accountId — troca o papel. Body: { role } */
+    async updateMemberRole(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const orgId = ctx.request.param('id');
+        const accountId = ctx.request.param('accountId');
+        const { role } = await ctx.request.validateUsing(orgMemberRoleValidator);
+        const result = await svc.updateMemberRole(orgId, accountId, role, actor, await resolveRuntimeSettings(ctx));
+        if (!result.ok) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            if (result.reason === 'not_found')
+                return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+            if (result.reason === 'invalid_role')
+                return ctx.response.unprocessableEntity(apiError('invalid_role', 'Role inválida — fora do catálogo da organização.'));
+            if (result.reason === 'last_owner')
+                return ctx.response.conflict(apiError('last_owner', 'Não é possível rebaixar o último owner.'));
+            return ctx.response.notFound(apiError('member_not_found', 'Membro não encontrado.'));
+        }
+        return { orgId, accountId, role, updated: true };
+    }
+    /** POST /organizations/:id/invitations — cria convite. Body: { email, role } */
+    async createInvitation(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const orgId = ctx.request.param('id');
+        const { email, role } = await ctx.request.validateUsing(orgInvitationValidator);
+        const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+        const result = await svc.createInvitation(orgId, { email, role: role ?? 'member' }, actor, origin, await resolveRuntimeSettings(ctx));
+        if (!result.ok) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            if (result.reason === 'invalid_role')
+                return ctx.response.unprocessableEntity(apiError('invalid_role', 'Role inválida — fora do catálogo da organização.'));
+            return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+        }
+        ctx.response.status(201);
+        return orgInvitationDto(result.invitation);
+    }
+    /** DELETE /organizations/:id/invitations/:invitationId */
+    async revokeInvitation(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const svc = new AdminOrgsService(cfg);
+        const orgId = ctx.request.param('id');
+        const invitationId = ctx.request.param('invitationId');
+        const result = await svc.revokeInvitation(orgId, invitationId, actor);
+        if (!result.ok) {
+            if (result.reason === 'not_supported')
+                return notSupported(ctx);
+            if (result.reason === 'not_found')
+                return ctx.response.notFound(apiError('not_found', 'Organização não encontrada.'));
+            return ctx.response.notFound(apiError('invitation_not_found', 'Convite não encontrado.'));
+        }
+        return { orgId, invitationId, revoked: true };
+    }
+}

package/build/src/host/admin_api/api_settings_controller.d.ts

@@ -0,0 +1,55 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * CRUD de runtime settings da Admin REST API.
+ * Todas as rotas ficam sob `/api/authkit/v1/settings`.
+ * Retorna 404 (`capability_unsupported`) quando a tabela `auth_settings` não existe.
+ *
+ * Suporte a escopo por org via query param `?organizationId=`:
+ *   GET  /settings?organizationId={id}  → lista settings da org
+ *   PUT  /settings/:key?organizationId= → upsert no escopo da org
+ *   DEL  /settings/:key?organizationId= → remove no escopo da org
+ *
+ * Keys org-scopáveis: `organizations_policy`, `roles_catalog`.
+ */
+export default class ApiSettingsController {
+    /** GET /settings — lista settings (global por padrão, ou da org via ?organizationId=). */
+    index(ctx: HttpContext): Promise<void | {
+        data: {
+            lockedBy?: "config" | undefined;
+            key: string;
+            organizationId: string | null;
+            value: unknown;
+            updatedAt: string | null;
+            updatedBy: string | null;
+            locked: boolean;
+        }[];
+        locked: string[];
+    }>;
+    /** GET /settings/:key — obtém uma setting por key (global ou org). */
+    show(ctx: HttpContext): Promise<void | {
+        lockedBy?: "config" | undefined;
+        key: string;
+        organizationId: string | null;
+        value: unknown;
+        updatedAt: string | null;
+        updatedBy: string | null;
+        locked: boolean;
+    }>;
+    /** PUT /settings/:key — cria ou atualiza uma setting. Body: { value: any } */
+    upsert(ctx: HttpContext): Promise<void | {
+        lockedBy?: "config" | undefined;
+        key: string;
+        organizationId: string | null;
+        value: unknown;
+        updatedAt: string | null;
+        updatedBy: string | null;
+        locked: boolean;
+    }>;
+    /** DELETE /settings/:key */
+    destroy(ctx: HttpContext): Promise<void | {
+        key: string;
+        organizationId: string | null;
+        deleted: boolean;
+    }>;
+}

package/build/src/host/admin_api/api_settings_controller.js

@@ -0,0 +1,134 @@
+import '../augmentations.js';
+import { resolveRuntimeSettings } from '../runtime_settings.js';
+import { settingDto, apiError } from './dto.js';
+import { isSettingLocked, lockedSettingKeys, SettingLockedError } from '../config_locks.js';
+/** 423 Locked: a setting foi travada via defineConfig (não editável em runtime). */
+function lockedResponse(ctx, err) {
+    return ctx.response
+        .status(423)
+        .send(apiError('setting_locked', err.message, { key: err.key, lockedBy: 'config' }));
+}
+/** Helper: 404 JSON when settings capability is not available (table absent). */
+function notSupported(ctx) {
+    return ctx.response.notFound(apiError('capability_unsupported', 'Runtime settings não é suportado nesta instalação (tabela auth_settings ausente).'));
+}
+/** Extrai organizationId do query string. null = global. */
+function resolveOrgId(ctx) {
+    const qs = ctx.request.qs();
+    if ('organizationId' in qs) {
+        const v = qs['organizationId'];
+        return v && v.trim() ? v.trim() : null;
+    }
+    return null;
+}
+/**
+ * CRUD de runtime settings da Admin REST API.
+ * Todas as rotas ficam sob `/api/authkit/v1/settings`.
+ * Retorna 404 (`capability_unsupported`) quando a tabela `auth_settings` não existe.
+ *
+ * Suporte a escopo por org via query param `?organizationId=`:
+ *   GET  /settings?organizationId={id}  → lista settings da org
+ *   PUT  /settings/:key?organizationId= → upsert no escopo da org
+ *   DEL  /settings/:key?organizationId= → remove no escopo da org
+ *
+ * Keys org-scopáveis: `organizations_policy`, `roles_catalog`.
+ */
+export default class ApiSettingsController {
+    /** GET /settings — lista settings (global por padrão, ou da org via ?organizationId=). */
+    async index(ctx) {
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        // Probe table presence before returning list.
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        const orgId = resolveOrgId(ctx);
+        const rows = await svc.listSettings(orgId);
+        // `locked` lista TODAS as keys travadas por config (mesmo as sem row em auth_settings,
+        // pois config-only não persiste row). A UI usa isto p/ desabilitar + avisar.
+        return { data: rows.map(settingDto), locked: lockedSettingKeys() };
+    }
+    /** GET /settings/:key — obtém uma setting por key (global ou org). */
+    async show(ctx) {
+        const key = ctx.request.param('key');
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        const orgId = resolveOrgId(ctx);
+        const value = await svc.getSetting(key, orgId);
+        if (value === null) {
+            return ctx.response.notFound(apiError('not_found', 'Setting não encontrada.'));
+        }
+        return settingDto({ key, organizationId: orgId, value, updatedAt: null, updatedBy: null });
+    }
+    /** PUT /settings/:key — cria ou atualiza uma setting. Body: { value: any } */
+    async upsert(ctx) {
+        const key = ctx.request.param('key');
+        const body = ctx.request.body();
+        if (!body || !('value' in body)) {
+            return ctx.response.badRequest(apiError('invalid_request', 'O campo `value` é obrigatório.'));
+        }
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        // Travada via defineConfig → 423 antes de qualquer escrita.
+        if (isSettingLocked(key))
+            return lockedResponse(ctx, new SettingLockedError(key));
+        const orgId = resolveOrgId(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        try {
+            await svc.setSetting(key, body.value, null, orgId);
+        }
+        catch (err) {
+            if (err instanceof SettingLockedError)
+                return lockedResponse(ctx, err);
+            throw err;
+        }
+        await cfg.audit?.record({
+            type: 'settings.updated',
+            actorId: null,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { key, value: body.value, organizationId: orgId },
+        });
+        const saved = await svc.getSetting(key, orgId);
+        return settingDto({ key, organizationId: orgId, value: saved, updatedAt: new Date(), updatedBy: null });
+    }
+    /** DELETE /settings/:key */
+    async destroy(ctx) {
+        const key = ctx.request.param('key');
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        if (isSettingLocked(key))
+            return lockedResponse(ctx, new SettingLockedError(key));
+        const orgId = resolveOrgId(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        try {
+            await svc.deleteSetting(key, orgId);
+        }
+        catch (err) {
+            if (err instanceof SettingLockedError)
+                return lockedResponse(ctx, err);
+            throw err;
+        }
+        await cfg.audit?.record({
+            type: 'settings.updated',
+            actorId: null,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { key, action: 'deleted', organizationId: orgId },
+        });
+        return { key, organizationId: orgId, deleted: true };
+    }
+}

package/build/src/host/admin_api/api_users_controller.d.ts

@@ -0,0 +1,108 @@
+import "../augmentations.js";
+import type { HttpContext } from "@adonisjs/core/http";
+/**
+ * Recurso de usuários da Admin REST API (R6). JSON puro (camelCase), erros no
+ * envelope `{ error: { code, message } }`. Toda escrita audita com `actor: 'admin-api'`.
+ */
+export default class ApiUsersController {
+    #private;
+    /** GET /users — listagem paginada com busca por e-mail. */
+    index(ctx: HttpContext): Promise<{
+        data: any[];
+        total: any;
+        page: number;
+        limit: number;
+    }>;
+    /** GET /users/:id */
+    show(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST /users — { email, name?, password? | invite?:true }. */
+    store(ctx: HttpContext): Promise<void | {
+        invited: boolean;
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** PATCH /users/:id — { globalRoles?, name?, avatarUrl? }. */
+    update(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** DELETE /users/:id — deleção completa (cascade) da conta. */
+    destroy(ctx: HttpContext): Promise<void | {
+        id: any;
+        deleted: boolean;
+        enqueued: boolean;
+        runId: string;
+    } | {
+        ok: boolean;
+        sessions: number;
+        grants: number;
+        accessTokens: number;
+        refreshTokens: number;
+        pats: number;
+        passkeys: number;
+        providerIdentities: number;
+        auditAnonymized: number;
+        avatarDeleted: boolean;
+        orgMemberships: number;
+        orgInvitations: number;
+        id: any;
+        deleted: boolean;
+        enqueued?: undefined;
+        runId?: undefined;
+    }>;
+    /** POST /users/:id/disable */
+    disable(ctx: HttpContext): Promise<void | {
+        id: any;
+        disabled: boolean;
+    }>;
+    /** POST /users/:id/enable */
+    enable(ctx: HttpContext): Promise<void | {
+        id: any;
+        disabled: boolean;
+    }>;
+    /** POST /users/:id/reset-password — envia o e-mail de reset. */
+    resetPassword(ctx: HttpContext): Promise<void | {
+        id: any;
+        sent: boolean;
+    }>;
+    /** GET /users/:id/sessions — sessões (enriquecidas com contexto) + grants ativos. */
+    sessions(ctx: HttpContext): Promise<{
+        canList: boolean;
+        sessions: {
+            id: string;
+            accountId: string;
+            email: string | null;
+            loginTs: number | null;
+            amr: string[];
+            userAgent: string | null;
+            browser: string | null;
+            os: string | null;
+            ip: string | null;
+            location: string | null;
+        }[];
+        grants: {
+            id: string;
+            accountId: string;
+            clientId: string | null;
+            accessTokens: number;
+            refreshTokens: number;
+        }[];
+    }>;
+    /** POST /users/:id/revoke-sessions — revoga todas as sessões/grants. */
+    revokeSessions(ctx: HttpContext): Promise<import("../admin_sessions_service.js").RevokeResult>;
+}

package/build/src/host/admin_api/api_users_controller.js

@@ -0,0 +1,187 @@
+import "../augmentations.js";
+import { AdminUsersService } from "./admin_users_service.js";
+import { AdminSessionsService } from "../admin_sessions_service.js";
+import { enrichSessionsWithContext } from "../session_context.js";
+import { resolveRuntimeSettings } from "../runtime_settings.js";
+import { userDto, sessionDto, grantDto, apiError } from "./dto.js";
+import { adminUserCreateValidator, adminUserUpdateValidator, } from "../admin_validators.js";
+const PAGE_SIZE = 20;
+/**
+ * Lê a config + monta o actor `admin-api` para auditoria. O `actorId` recebe o
+ * id NÃO-SENSÍVEL da API key que autenticou (anexado pelo `adminApiGuard` em
+ * `ctx.adminApiKeyId`) — assim a trilha REST registra QUAL key agiu (M9) sem
+ * vazar o segredo. `null` apenas se a guard não anexou (defensivo).
+ */
+async function ctxBits(ctx) {
+    const service = await ctx.containerResolver.make("authkit.server");
+    const cfg = service.config;
+    const actor = {
+        actorId: ctx.adminApiKeyId ?? null,
+        ip: ctx.request.ip?.() ?? null,
+        source: "admin-api",
+    };
+    return { service, cfg, actor };
+}
+/**
+ * Recurso de usuários da Admin REST API (R6). JSON puro (camelCase), erros no
+ * envelope `{ error: { code, message } }`. Toda escrita audita com `actor: 'admin-api'`.
+ */
+export default class ApiUsersController {
+    /** GET /users — listagem paginada com busca por e-mail. */
+    async index(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const search = ctx.request.input("search", "").trim();
+        const page = Math.max(1, Number.parseInt(ctx.request.input("page", "1"), 10) || 1);
+        const limit = Math.max(1, Math.min(100, Number.parseInt(ctx.request.input("limit", String(PAGE_SIZE)), 10) ||
+            PAGE_SIZE));
+        const result = await cfg.accountStore.listAccounts({ search, page, limit });
+        const users = new AdminUsersService(cfg);
+        const data = await Promise.all(result.data.map(async (u) => userDto(u, await users.isDisabled(u.id))));
+        return { data, total: result.total, page, limit };
+    }
+    /** GET /users/:id */
+    async show(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        const disabled = await new AdminUsersService(cfg).isDisabled(id);
+        return userDto(account, disabled);
+    }
+    /** POST /users — { email, name?, password? | invite?:true }. */
+    async store(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const { email, name, password, invite } = await ctx.request.validateUsing(adminUserCreateValidator);
+        const users = new AdminUsersService(cfg);
+        const result = await users.create(ctx, {
+            email,
+            name: name ?? null,
+            password: password ?? null,
+            invite: invite ?? false,
+        }, actor);
+        if (!result.ok) {
+            if (result.reason === "password_policy") {
+                return ctx.response.badRequest(apiError("password_policy", cfg.messages[result.messageKey] ?? result.messageKey));
+            }
+            return ctx.response.conflict(apiError("email_taken", "Já existe uma conta com este e-mail."));
+        }
+        ctx.response.status(201);
+        return { ...userDto(result.account), invited: result.invited };
+    }
+    /** PATCH /users/:id — { globalRoles?, name?, avatarUrl? }. */
+    async update(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        const users = new AdminUsersService(cfg);
+        const { globalRoles: roles, name, avatarUrl, } = await ctx.request.validateUsing(adminUserUpdateValidator);
+        if (Array.isArray(roles)) {
+            const normalized = Array.from(new Set(roles.map((r) => r.trim()).filter(Boolean)));
+            // Proteções de escalonamento/lockout: último admin + auto-rebaixamento.
+            // O actorId vem do id da API key (M9); self-demote só aplica se identificável.
+            const guard = await users.guardGlobalRolesChange(id, normalized, actor.actorId);
+            if (guard === "last_admin") {
+                return ctx.response.conflict(apiError("last_admin", "Não é possível remover a última conta com a role de administrador."));
+            }
+            if (guard === "cannot_self_demote") {
+                return ctx.response.conflict(apiError("cannot_self_demote", "Você não pode remover a sua própria role de administrador."));
+            }
+            // Valida contra o catálogo (mesmo caminho do console) — roles fora do
+            // catálogo (e que o usuário não tinha) → 422.
+            const settings = await resolveRuntimeSettings(ctx);
+            const errorKey = await users.setGlobalRolesValidated(id, normalized, settings);
+            if (errorKey) {
+                return ctx.response
+                    .status(422)
+                    .send(apiError("invalid_role", cfg.messages[errorKey] ?? errorKey));
+            }
+        }
+        if (name !== undefined || avatarUrl !== undefined) {
+            const patch = {};
+            if (name !== undefined)
+                patch.name = name;
+            if (avatarUrl !== undefined)
+                patch.avatarUrl = avatarUrl;
+            await users.updateProfile(id, patch);
+        }
+        const updated = await cfg.accountStore.findById(id);
+        return userDto(updated, await users.isDisabled(id));
+    }
+    /** DELETE /users/:id — deleção completa (cascade) da conta. */
+    async destroy(ctx) {
+        const { service, cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        // OPT-IN durável: passa o enqueue (cascade async); senão delete() roda síncrono.
+        const enqueue = cfg.accountLifecycle?.durable
+            ? (await import("../durable/index.js")).enqueueDeletionVia(ctx.containerResolver)
+            : undefined;
+        const outcome = await new AdminUsersService(cfg).delete(service, id, actor, enqueue);
+        if (!outcome.ok) {
+            if (outcome.reason === "not_found") {
+                return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+            }
+            return ctx.response.conflict(apiError("capability_unsupported", "O store de contas não suporta deletar usuários."));
+        }
+        // Modo durável: a deleção foi ENFILEIRADA (cascade async) — responde 202-style.
+        if ("enqueued" in outcome) {
+            return { id, deleted: true, enqueued: true, runId: outcome.runId };
+        }
+        return { id, deleted: true, ...outcome.result };
+    }
+    /** POST /users/:id/disable */
+    async disable(ctx) {
+        return this.#setStatus(ctx, true);
+    }
+    /** POST /users/:id/enable */
+    async enable(ctx) {
+        return this.#setStatus(ctx, false);
+    }
+    async #setStatus(ctx, disable) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        const applied = await new AdminUsersService(cfg).setStatus(id, disable, actor);
+        if (!applied) {
+            return ctx.response.conflict(apiError("capability_unsupported", "O store de contas não suporta habilitar/desabilitar."));
+        }
+        return { id, disabled: disable };
+    }
+    /** POST /users/:id/reset-password — envia o e-mail de reset. */
+    async resetPassword(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        const account = await new AdminUsersService(cfg).resetPassword(ctx, id, actor);
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        return { id, sent: true };
+    }
+    /** GET /users/:id/sessions — sessões (enriquecidas com contexto) + grants ativos. */
+    async sessions(ctx) {
+        const { service, cfg } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        const admin = new AdminSessionsService(service);
+        const sessions = await enrichSessionsWithContext(cfg, id, await admin.listSessions(id));
+        const grants = await admin.listGrants(id);
+        return {
+            canList: admin.canList,
+            sessions: sessions.map(sessionDto),
+            grants: grants.map(grantDto),
+        };
+    }
+    /** POST /users/:id/revoke-sessions — revoga todas as sessões/grants. */
+    async revokeSessions(ctx) {
+        const { service, cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param("id");
+        const result = await new AdminSessionsService(service).revokeAll(id);
+        await cfg.audit?.record({
+            type: "session.revoked_all",
+            accountId: id,
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: { actor: actor.source, ...result },
+        });
+        return result;
+    }
+}