@adonis-agora/authkit-server 0.34.0

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

@@ -0,0 +1,324 @@
+import { supportsOrganizations } from '../../accounts/account_store.js';
+import { resolveRoleCatalogList, isRoleInCatalog } from '../runtime_toggles.js';
+/**
+ * Lógica de gestão de organizações compartilhada entre o console admin (HTML)
+ * e a Admin REST API (JSON). Usada pelos `AdminOrgsController` e `ApiOrgsController`.
+ * Todos os métodos de escrita auditam com o `actor` informado.
+ */
+export class AdminOrgsService {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get supported() {
+        return supportsOrganizations(this.cfg.accountStore);
+    }
+    /**
+     * Resolve o catálogo efetivo de roles de org (runtime settings → config →
+     * defaults da lib), garantindo sempre a presença de `owner`. Fail-safe: sem
+     * `settings`, usa o catálogo do config estático (`cfg.organizations`).
+     */
+    async resolveRoleCatalog(settings, orgId) {
+        return resolveRoleCatalogList(settings, this.orgPolicyConfigDefaults(), orgId);
+    }
+    /** Defaults estáticos de policy de org derivados do config do host. */
+    orgPolicyConfigDefaults() {
+        return {
+            roles: this.cfg.organizations.roles,
+            allowSelfCreate: this.cfg.organizations.allowSelfCreate,
+            invitationTtlHours: this.cfg.organizations.invitationTtlHours,
+        };
+    }
+    /**
+     * Valida um `role` de org contra o catálogo efetivo. Retorna `true` quando o
+     * role faz parte do catálogo. H4: bloqueia roles fora do catálogo (incluindo
+     * roles arbitrárias e, quando não catalogadas, `owner`).
+     *
+     * Delega ao helper PURO `isRoleInCatalog` de `runtime_toggles` — mesmo ponto de
+     * verdade usado pelo caminho member-facing (`account_orgs_controller`).
+     */
+    async isRoleInCatalog(role, settings, orgId) {
+        return isRoleInCatalog(role, settings, this.orgPolicyConfigDefaults(), orgId);
+    }
+    /** Lista todas as orgs com contagem de membros. */
+    async listOrgs() {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        // O store não tem listAllOrgs — acumulamos via memberships de todas as contas.
+        // Para admin, fazemos um listAccounts full e coletamos todas as orgs únicas.
+        // Mais eficiente: usa a tabela de organizations diretamente pelo listOrgMembers
+        // mas o store não expõe listAllOrgs. Usamos hack: listAccounts com limit alto,
+        // coletamos orgs via listOrgsForAccount por conta.
+        // Para evitar N+1 excessivo, usamos uma abordagem "seen" de IDs.
+        const seen = new Map();
+        let page = 1;
+        const limit = 100;
+        while (true) {
+            const result = await store.listAccounts({ page, limit });
+            for (const account of result.data) {
+                const orgs = await store.listOrgsForAccount(account.id);
+                for (const org of orgs) {
+                    if (!seen.has(org.id)) {
+                        // Conta membros
+                        const members = await store.listOrgMembers(org.id);
+                        seen.set(org.id, { ...org, memberCount: members.length });
+                    }
+                }
+            }
+            if (result.data.length < limit)
+                break;
+            page++;
+        }
+        return Array.from(seen.values());
+    }
+    /** Obtém uma org pelo id, com membros e convites pendentes. */
+    async getOrg(orgId) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const org = await store.findOrgById(orgId);
+        if (!org)
+            return { ok: false, reason: 'not_found' };
+        const [members, pendingInvitations] = await Promise.all([
+            store.listOrgMembers(orgId),
+            store.listPendingInvitationsForOrg(orgId),
+        ]);
+        // Enriquece membros com e-mail da conta
+        const enrichedMembers = await Promise.all(members.map(async (m) => {
+            const account = await store.findById(m.accountId);
+            return { ...m, email: account?.email ?? null };
+        }));
+        return { ...org, members: enrichedMembers, pendingInvitations };
+    }
+    /** Cria uma org. */
+    async createOrg(input, actor) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        try {
+            const org = await store.createOrg({
+                name: input.name,
+                slug: input.slug,
+                logoUrl: input.logoUrl ?? null,
+                ownerAccountId: input.ownerAccountId,
+            });
+            await this.cfg.audit?.record({
+                type: 'organization.created',
+                accountId: input.ownerAccountId,
+                actorId: actor.actorId,
+                ip: actor.ip,
+                metadata: { slug: org.slug, ...(actor.source ? { actor: actor.source } : {}) },
+            });
+            return org;
+        }
+        catch {
+            return { ok: false, reason: 'slug_taken' };
+        }
+    }
+    /** Atualiza nome/logo de uma org. */
+    async updateOrg(orgId, patch, actor) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const existing = await store.findOrgById(orgId);
+        if (!existing)
+            return { ok: false, reason: 'not_found' };
+        try {
+            const updated = await store.updateOrg(orgId, {
+                name: patch.name,
+                logoUrl: patch.logoUrl,
+            });
+            if (!updated)
+                return { ok: false, reason: 'not_found' };
+            await this.cfg.audit?.record({
+                type: 'organization.updated',
+                actorId: actor.actorId,
+                ip: actor.ip,
+                metadata: { orgId, ...(actor.source ? { actor: actor.source } : {}) },
+            });
+            return updated;
+        }
+        catch {
+            return { ok: false, reason: 'slug_taken' };
+        }
+    }
+    /** Deleta uma org e todos os seus dados (membros + convites). */
+    async deleteOrg(orgId, actor) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const existing = await store.findOrgById(orgId);
+        if (!existing)
+            return { ok: false, reason: 'not_found' };
+        await store.deleteOrg(orgId);
+        await this.cfg.audit?.record({
+            type: 'organization.deleted',
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: { orgId, slug: existing.slug, ...(actor.source ? { actor: actor.source } : {}) },
+        });
+        return { ok: true };
+    }
+    /** Adiciona um membro a uma org. */
+    async addMember(orgId, input, actor, settings = null) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const org = await store.findOrgById(orgId);
+        if (!org)
+            return { ok: false, reason: 'not_found' };
+        // H4: valida o role contra o catálogo efetivo (runtime → config → defaults).
+        if (!(await this.isRoleInCatalog(input.role, settings, orgId))) {
+            return { ok: false, reason: 'invalid_role' };
+        }
+        const account = await store.findById(input.accountId);
+        if (!account)
+            return { ok: false, reason: 'account_not_found' };
+        await store.addOrgMember(orgId, input.accountId, input.role);
+        await this.cfg.audit?.record({
+            type: 'organization.member_added',
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: {
+                orgId,
+                accountId: input.accountId,
+                role: input.role,
+                ...(actor.source ? { actor: actor.source } : {}),
+            },
+        });
+        return { ok: true };
+    }
+    /** Remove um membro de uma org. Respeita invariante last_owner. */
+    async removeMember(orgId, accountId, actor) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const org = await store.findOrgById(orgId);
+        if (!org)
+            return { ok: false, reason: 'not_found' };
+        const result = await store.removeOrgMember(orgId, accountId);
+        if (!result.ok) {
+            if (result.reason === 'last_owner')
+                return { ok: false, reason: 'last_owner' };
+            return { ok: false, reason: 'member_not_found' };
+        }
+        await this.cfg.audit?.record({
+            type: 'organization.member_removed',
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: {
+                orgId,
+                targetAccountId: accountId,
+                ...(actor.source ? { actor: actor.source } : {}),
+            },
+        });
+        return { ok: true };
+    }
+    /** Troca o papel de um membro. Respeita invariante last_owner. */
+    async updateMemberRole(orgId, accountId, newRole, actor, settings = null) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const org = await store.findOrgById(orgId);
+        if (!org)
+            return { ok: false, reason: 'not_found' };
+        // H4: valida o role-alvo contra o catálogo efetivo antes de promover/rebaixar.
+        if (!(await this.isRoleInCatalog(newRole, settings, orgId))) {
+            return { ok: false, reason: 'invalid_role' };
+        }
+        const result = await store.updateOrgMemberRole(orgId, accountId, newRole);
+        if (!result.ok) {
+            if (result.reason === 'last_owner')
+                return { ok: false, reason: 'last_owner' };
+            return { ok: false, reason: 'member_not_found' };
+        }
+        await this.cfg.audit?.record({
+            type: 'organization.member_role_changed',
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: {
+                orgId,
+                targetAccountId: accountId,
+                newRole,
+                ...(actor.source ? { actor: actor.source } : {}),
+            },
+        });
+        return { ok: true };
+    }
+    /** Cria um convite por e-mail. Dispara o mail hook quando configurado. */
+    async createInvitation(orgId, input, actor, origin, settings = null) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const org = await store.findOrgById(orgId);
+        if (!org)
+            return { ok: false, reason: 'not_found' };
+        // H4: valida o role do convite contra o catálogo efetivo.
+        if (!(await this.isRoleInCatalog(input.role, settings, orgId))) {
+            return { ok: false, reason: 'invalid_role' };
+        }
+        const { invitation, token } = await store.createOrgInvitation({
+            organizationId: orgId,
+            email: input.email,
+            role: input.role,
+            invitedBy: actor.actorId ?? 'admin',
+            ttlHours: this.cfg.organizations.invitationTtlHours,
+        });
+        // Dispara mail hook (best-effort)
+        if (this.cfg.mail?.onOrgInvitation) {
+            const acceptUrl = `${origin}/account/orgs/invitations/${token}/accept`;
+            try {
+                await this.cfg.mail.onOrgInvitation({
+                    email: input.email,
+                    invitationId: invitation.id,
+                    orgName: org.name,
+                    orgSlug: org.slug,
+                    role: input.role,
+                    acceptUrl,
+                    token,
+                });
+            }
+            catch {
+                // best-effort
+            }
+        }
+        await this.cfg.audit?.record({
+            type: 'organization.invitation_sent',
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: {
+                orgId,
+                email: input.email,
+                role: input.role,
+                ...(actor.source ? { actor: actor.source } : {}),
+            },
+        });
+        return { ok: true, invitation, token };
+    }
+    /** Revoga um convite. */
+    async revokeInvitation(orgId, invitationId, actor) {
+        const store = this.cfg.accountStore;
+        if (!supportsOrganizations(store))
+            return { ok: false, reason: 'not_supported' };
+        const org = await store.findOrgById(orgId);
+        if (!org)
+            return { ok: false, reason: 'not_found' };
+        // Escopado por org: o convite só é revogado se pertencer a esta org —
+        // mesmo no Admin API global, evita revogar convite de outra org por id.
+        const revoked = await store.revokeInvitation(orgId, invitationId);
+        if (!revoked)
+            return { ok: false, reason: 'invitation_not_found' };
+        await this.cfg.audit?.record({
+            type: 'organization.invitation_revoked',
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: {
+                orgId,
+                invitationId,
+                ...(actor.source ? { actor: actor.source } : {}),
+            },
+        });
+        return { ok: true };
+    }
+}

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

@@ -0,0 +1,163 @@
+import type { HttpContext } from "@adonisjs/core/http";
+import type { ResolvedServerConfig } from "../../define_config.js";
+import type { OidcService } from "../../provider/oidc_service.js";
+import type { AuthAccount } from "../../accounts/account_store.js";
+import { type DeletionResult } from "../account_deletion_service.js";
+import type { SettingsCapability } from "../runtime_settings.js";
+/** Quem disparou a operação (para auditoria). `admin-api` quando via REST API. */
+export interface AdminActor {
+    actorId: string | null;
+    ip: string | null;
+    /** Marca metadata da auditoria — 'admin-api' nas escritas via REST, 'admin' no console HTML. */
+    source?: "admin-api" | "admin";
+}
+/** Resultado da deleção via admin: false quando o store não suporta hard delete. */
+export type DeleteUserResult = {
+    ok: false;
+    reason: "not_found" | "unsupported";
+} | {
+    ok: true;
+    result: DeletionResult;
+}
+/** Deleção ENFILEIRADA (modo durável): o cascade roda async no WorkflowEngine. */
+ | {
+    ok: true;
+    enqueued: true;
+    runId: string;
+};
+/**
+ * Enfileira o cascade durável (modo opt-in). Injetado pelos controllers admin —
+ * mantém o `AdminUsersService` desacoplado do peer `@adonis-agora/durable`.
+ */
+export type EnqueueDeletion = (input: {
+    accountId: string;
+    actor: {
+        actorId: string | null;
+        ip: string | null;
+        source: "admin" | "admin-api";
+    };
+}) => Promise<string>;
+export interface CreateUserInput {
+    email: string;
+    name?: string | null;
+    password?: string | null;
+    /** Quando true (e sem password), cria com senha aleatória e envia convite/reset. */
+    invite?: boolean;
+}
+export type CreateUserResult = {
+    ok: true;
+    account: AuthAccount;
+    invited: boolean;
+} | {
+    ok: false;
+    reason: "email_taken";
+} | {
+    ok: false;
+    reason: "password_policy";
+    /** Chave i18n da regra violada + params para interpolar. */
+    messageKey: string;
+    messageParams?: Record<string, string | number>;
+};
+/**
+ * Lógica de gestão de usuários compartilhada entre o console admin (B6, HTML) e a
+ * Admin REST API (R6, JSON). Encapsula o fluxo "create + invite", reset de senha,
+ * troca de status e atualização de perfil/roles — todos auditando com o `actor`
+ * informado (`admin-api` nas chamadas REST).
+ */
+export declare class AdminUsersService {
+    private cfg;
+    constructor(cfg: ResolvedServerConfig);
+    /**
+     * Cria uma conta. Com `password`: já nasce com a senha. Sem `password` (ou
+     * `invite: true`): cria com senha aleatória forte e dispara o e-mail de reset
+     * (o usuário define a própria). Audita `user.created`.
+     */
+    create(ctx: HttpContext, input: CreateUserInput, actor: AdminActor): Promise<CreateUserResult>;
+    /** Emite token de reset + envia e-mail. Retorna a conta (ou null se inexistente). */
+    resetPassword(ctx: HttpContext, accountId: string, actor: AdminActor): Promise<AuthAccount | null>;
+    /**
+     * Habilita/desabilita uma conta. Retorna false quando o store não suporta a
+     * capacidade (o caller responde 409). Audita `user.disabled`/`user.enabled`.
+     */
+    setStatus(accountId: string, disable: boolean, actor: AdminActor): Promise<boolean>;
+    /**
+     * Substitui as roles globais de uma conta validando contra o catálogo runtime.
+     *
+     * Regras:
+     *   - Roles presentes no catálogo são aceitas.
+     *   - Roles que o usuário JÁ TEM mas que não estão no catálogo ("fora do catálogo")
+     *     podem ser REMOVIDAS (não incluir no array roles = remoção normal).
+     *   - Roles desconhecidas que não estão no catálogo E que o usuário não tinha
+     *     são REJEITADAS (retorna erro i18n).
+     *   - Quando settings não disponível, aceita tudo (fail-safe).
+     *
+     * @returns `null` quando OK; string i18n key quando há role inválida nova.
+     */
+    setGlobalRolesValidated(accountId: string, roles: string[], settings: SettingsCapability | null): Promise<string | null>;
+    /** Substitui as roles globais de uma conta (normaliza nada — recebe array pronto). */
+    setGlobalRoles(accountId: string, roles: string[]): Promise<void>;
+    /** Roles globais que conferem acesso de admin (default ['ADMIN']). */
+    private adminRoles;
+    /** Um conjunto de roles contém ao menos uma role de admin? */
+    private hasAdminRole;
+    /**
+     * Conta quantas contas possuem ao menos uma role de admin. Usado para a
+     * invariante de "último admin" — chamado apenas em mudanças de role.
+     *
+     * CAMINHO EFICIENTE: quando o store expõe `countByGlobalRole` E há exatamente
+     * UMA role de admin, conta direto no DB sem paginar a base. Com MÚLTIPLAS roles
+     * de admin NÃO usamos a capability: somar `countByGlobalRole` por role
+     * sobrecontaria contas que possuem 2+ roles de admin, e overcount aqui é uma
+     * regressão de SEGURANÇA (relaxaria o guard de last-admin). Nesse caso caímos
+     * no scan paginado, que deduplica naturalmente (conta cada conta uma vez).
+     *
+     * FALLBACK (sem capability ou múltiplas roles): pagina via `listAccounts`
+     * (store-agnóstico, não exige query SQL específica de dialeto sobre a coluna
+     * JSON `globalRoles`) e conta in-memory deduplicado.
+     */
+    countAdmins(): Promise<number>;
+    /**
+     * Fallback de contagem por paginação de `listAccounts` (deduplicado: cada
+     * conta é contada no máximo uma vez via {@link hasAdminRole}).
+     *
+     * Terminadores honestos (sem número mágico): a paginação para quando
+     *   - a página veio incompleta (`data.length < pageSize`) → última página, OU
+     *   - a página veio vazia (`data.length === 0`) → sem mais dados, OU
+     *   - já cobrimos o total reportado (`page * pageSize >= total`).
+     * Uma página COMPLETA com `total` ainda maior continua paginando. Isto encerra
+     * de forma garantida para qualquer store que devolva páginas finitas (a última
+     * página é, por definição, menor que `pageSize` ou vazia).
+     */
+    private countAdminsByScan;
+    /**
+     * Aplica proteções de segurança a uma troca de roles globais ANTES de gravar:
+     *
+     *   - `last_admin`: bloqueia remover a role de admin da ÚLTIMA conta que a possui
+     *     (evita lockout permanente do console). Só dispara quando o target ATUALMENTE
+     *     é admin, o novo conjunto NÃO é admin, e ele é o único admin.
+     *   - `cannot_self_demote`: bloqueia o ator remover a própria role de admin
+     *     (`actorId === targetId` e o novo conjunto não tem admin). Só aplica quando
+     *     há um `actorId` identificável.
+     *
+     * @returns código i18n/erro quando a operação deve ser bloqueada; `null` quando OK.
+     */
+    guardGlobalRolesChange(targetId: string, newRoles: string[], actorId: string | null): Promise<"last_admin" | "cannot_self_demote" | null>;
+    /** Atualiza nome/avatar (capacidade opcional). Retorna a conta ou null. */
+    updateProfile(accountId: string, patch: {
+        name?: string | null;
+        avatarUrl?: string | null;
+    }): Promise<AuthAccount | null>;
+    /**
+     * Deleta uma conta pelo admin, usando o MESMO cascade do self-service
+     * ({@link AccountDeletionService}). Precisa do {@link OidcService} (para revogar
+     * sessões/grants). Retorna `{ ok: false, reason }` se a conta não existe ou o
+     * store não suporta hard delete (o caller responde 404/409). Audita
+     * `account.deleted` (ator admin) dentro do cascade + `user.deleted` aqui (trilha
+     * administrativa).
+     */
+    delete(oidc: OidcService, accountId: string, actor: AdminActor, enqueue?: EnqueueDeletion): Promise<DeleteUserResult>;
+    /** Indica se a conta está desabilitada (false quando a capacidade não existe). */
+    isDisabled(accountId: string): Promise<boolean>;
+    /** Emite o token de reset e dispara o e-mail (hook do config tem prioridade). */
+    private sendResetEmail;
+}