@adonis-agora/authkit-server 0.82.3 → 0.83.0

package/build/src/define_config.d.ts

@@ -23,8 +23,31 @@ import { type RedirectUriPolicy, type ResolvedRedirectUriPolicy, type ValidateRe
 export type { AuthAccount };
 export { adapters };
 export type AuthHostRenderer = (ctx: HttpContext, view: string, props: Record<string, unknown>) => unknown;
+/**
+ * Quando o login social pede o 2º fator da conta:
+ *  - `'enrolled'` (default): pede se a conta tem um fator cadastrado (TOTP,
+ *    passkey ou método custom de `mfa`). Quem ativou o fator espera que ele
+ *    valha em qualquer porta de entrada, inclusive "Continuar com Google".
+ *  - `'required'`: exige sempre; conta sem fator vê a tela de "configure o MFA"
+ *    (não há o que desafiar). Cuidado: tranca quem ainda não cadastrou fator.
+ *  - `'never'`: confia só no provider (o comportamento antigo).
+ */
+export type SocialSecondFactorPolicy = 'enrolled' | 'required' | 'never';
 export interface AuthSocialConfig {
     providers: string[];
+    /**
+     * 2º fator no login social. Aceita uma política fixa ou uma função por conta
+     * (ex.: `'required'` só para papéis administrativos). Default: `'enrolled'`.
+     *
+     * `roles` vem da MESMA fonte do claim de papéis: `resolveTokenRoles` quando o
+     * host o configura (ex.: `@adonis-agora/authz`), senão `account.globalRoles`.
+     * Só é resolvido quando a política é uma função.
+     */
+    secondFactor?: SocialSecondFactorPolicy | ((account: {
+        id: string;
+        email: string;
+        roles: string[];
+    }) => SocialSecondFactorPolicy | Promise<SocialSecondFactorPolicy>);
 }
 /**
  * Hooks de e-mail plugáveis (best-effort). Quando ausentes, o host-kit cai no
@@ -62,6 +85,12 @@ export interface MailHooks {
          * hosts existentes simplesmente ignoram este campo (back-compat).
          */
         channel?: 'code' | 'link';
+        /**
+         * `'signup'`: link de confirmação do cadastro passwordless (a conta é criada
+         * ao abri-lo). Ausente = login por magic link. O host pode trocar o texto do
+         * e-mail ("confirme seu cadastro"); ignorar o campo continua funcionando.
+         */
+        kind?: 'signup';
     }) => Promise<void>;
     /**
      * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo). Distinto de
@@ -488,10 +517,13 @@ export interface PasswordlessConfigInput {
     passkeyFirst?: boolean;
     /**
      * Liga o cadastro público passwordless: o signup pede só e-mail + nome (sem
-     * senha), cria a conta com uma senha aleatória inutilizável e envia um magic
-     * link que finaliza o login (o mesmo fluxo do login por magic link). Default:
-     * false. Exige que o accountStore implemente {@link MagicLinkCapability}; sem
-     * ela o cadastro passwordless fica indisponível e o fluxo de senha segue valendo.
+     * senha) e envia um link de confirmação (`onMagicLink` com `kind: 'signup'`).
+     * A conta só é criada quando o dono do e-mail abre o link: nasce com o e-mail
+     * verificado e uma senha aleatória inutilizável, e o login segue pelo magic
+     * link. E-mail que já tem conta recebe um magic link de login. Default: false.
+     * Exige que o accountStore implemente {@link MagicLinkCapability} e o serviço de
+     * encryption do app (APP_KEY), que assina o link; sem a capacidade o cadastro
+     * passwordless fica indisponível e o fluxo de senha segue valendo.
      */
     signup?: boolean;
 }

package/build/src/host/account_roles.d.ts

@@ -19,8 +19,19 @@ type RoleResolverConfig = {
  * account's stored `globalRoles`. Falls back to `account.globalRoles ?? []` when no hook is set, so
  * default behavior is unchanged.
  *
- * The console is not OIDC-client- or org-scoped for role purposes, so the hook is called with an
- * empty context (`clientId: undefined`, `activeOrg: null`).
+ * Gates that are not tied to an OIDC client (console, maintenance mode, PAT introspection) call the
+ * hook with an empty context; callers that know the client (opaque access-token introspection) pass
+ * its `clientId`, matching what the token was minted with. `activeOrg` is always `null` here.
  */
-export declare function resolveAccountRoles(cfg: RoleResolverConfig, account: AuthAccount): Promise<string[]>;
+export declare function resolveAccountRoles(cfg: RoleResolverConfig, account: AuthAccount, context?: {
+    clientId?: string;
+}): Promise<string[]>;
+/**
+ * true quando os papéis da conta vêm de fora do authkit: o host configurou
+ * `resolveTokenRoles` (ex.: `@adonis-agora/authz` ou uma tabela própria). Nesse
+ * caso `globalRoles` não decide nada, então o console e a Admin API mostram os
+ * papéis do hook e recusam editá-los — gravar na coluna diria "salvo" sem mudar
+ * acesso nenhum. Quem edita é o próprio app, na fonte dele.
+ */
+export declare function rolesManagedExternally(cfg: RoleResolverConfig): boolean;
 export {};

package/build/src/host/account_roles.js

@@ -7,12 +7,23 @@
  * account's stored `globalRoles`. Falls back to `account.globalRoles ?? []` when no hook is set, so
  * default behavior is unchanged.
  *
- * The console is not OIDC-client- or org-scoped for role purposes, so the hook is called with an
- * empty context (`clientId: undefined`, `activeOrg: null`).
+ * Gates that are not tied to an OIDC client (console, maintenance mode, PAT introspection) call the
+ * hook with an empty context; callers that know the client (opaque access-token introspection) pass
+ * its `clientId`, matching what the token was minted with. `activeOrg` is always `null` here.
  */
-export async function resolveAccountRoles(cfg, account) {
+export async function resolveAccountRoles(cfg, account, context = {}) {
     if (cfg.resolveTokenRoles) {
-        return cfg.resolveTokenRoles(account, { clientId: undefined, activeOrg: null });
+        return cfg.resolveTokenRoles(account, { clientId: context.clientId, activeOrg: null });
     }
     return account.globalRoles ?? [];
 }
+/**
+ * true quando os papéis da conta vêm de fora do authkit: o host configurou
+ * `resolveTokenRoles` (ex.: `@adonis-agora/authz` ou uma tabela própria). Nesse
+ * caso `globalRoles` não decide nada, então o console e a Admin API mostram os
+ * papéis do hook e recusam editá-los — gravar na coluna diria "salvo" sem mudar
+ * acesso nenhum. Quem edita é o próprio app, na fonte dele.
+ */
+export function rolesManagedExternally(cfg) {
+    return typeof cfg.resolveTokenRoles === 'function';
+}

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

@@ -23,6 +23,7 @@ export default class ApiUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
     }>;
     /** POST /users — { email, name?, password? | invite?:true }. */
     store(ctx: HttpContext): Promise<void | {
@@ -32,6 +33,7 @@ export default class ApiUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
         invited: boolean;
     }>;
     /** PATCH /users/:id — { globalRoles?, name?, avatarUrl? }. */
@@ -42,6 +44,7 @@ export default class ApiUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
     }>;
     /** DELETE /users/:id — deleção completa (cascade) da conta. */
     destroy(ctx: HttpContext): Promise<void | {

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

@@ -1,11 +1,12 @@
 import '../augmentations.js';
 import { ADMIN_LIST_HTTP_DEFAULT_SIZE, parseListPage, parseListSize } from '../../pagination.js';
+import { rolesManagedExternally } from '../account_roles.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { adminUserCreateValidator, adminUserUpdateValidator } from '../admin_validators.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { enrichSessionsWithContext } from '../session_context.js';
 import { AdminUsersService } from './admin_users_service.js';
-import { apiError, grantDto, sessionDto, userDto } from './dto.js';
+import { apiError, grantDto, rolesManagedExternallyError, sessionDto, userDtoWithRoles, } from './dto.js';
 /**
  * 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
@@ -35,7 +36,7 @@ export default class ApiUsersController {
         const size = parseListSize(ctx.request.input('size'), ADMIN_LIST_HTTP_DEFAULT_SIZE);
         const result = await cfg.accountStore.listAccounts({ search, page, size });
         const users = new AdminUsersService(cfg);
-        const data = await Promise.all(result.data.map(async (u) => userDto(u, await users.isDisabled(u.id))));
+        const data = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
         return { meta: { page, size, total: result.total }, data };
     }
     /** GET /users/:id */
@@ -46,7 +47,7 @@ export default class ApiUsersController {
         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);
+        return userDtoWithRoles(cfg, account, disabled);
     }
     /** POST /users — { email, name?, password? | invite?:true }. */
     async store(ctx) {
@@ -66,7 +67,7 @@ export default class ApiUsersController {
             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 };
+        return { ...(await userDtoWithRoles(cfg, result.account)), invited: result.invited };
     }
     /** PATCH /users/:id — { globalRoles?, name?, avatarUrl? }. */
     async update(ctx) {
@@ -77,6 +78,9 @@ export default class ApiUsersController {
             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) && rolesManagedExternally(cfg)) {
+            return ctx.response.conflict(rolesManagedExternallyError());
+        }
         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.
@@ -107,7 +111,7 @@ export default class ApiUsersController {
             await users.updateProfile(id, patch);
         }
         const updated = await cfg.accountStore.findById(id);
-        return userDto(updated, await users.isDisabled(id));
+        return userDtoWithRoles(cfg, updated, await users.isDisabled(id));
     }
     /** DELETE /users/:id — deleção completa (cascade) da conta. */
     async destroy(ctx) {

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

@@ -1,5 +1,6 @@
 import type { AuthAccount, OrgInvitation, OrgMember, OrgSummary } from '../../accounts/account_store.js';
 import type { StoredAuditEvent } from '../../audit/audit_sink.js';
+import { resolveAccountRoles } from '../account_roles.js';
 import type { AdminClient, CreatedClient } from '../admin_clients_service.js';
 import type { AdminGrant, AdminSession } from '../admin_sessions_service.js';
 import type { OrgDetail } from './admin_orgs_service.js';
@@ -12,6 +13,21 @@ export declare function userDto(account: AuthAccount, disabled?: boolean): {
     globalRoles: string[];
     disabled: boolean;
 };
+/**
+ * {@link userDto} + `roles`: os papéis efetivos da conta, pela mesma fonte do
+ * claim (`resolveAccountRoles`). Sem `resolveTokenRoles` é igual a
+ * `globalRoles`; com ele, é o que o app diz (ex.: authz) e `globalRoles` segue
+ * sendo só a coluna guardada.
+ */
+export declare function userDtoWithRoles(cfg: Parameters<typeof resolveAccountRoles>[0], account: AuthAccount, disabled?: boolean): Promise<{
+    id: string;
+    email: string;
+    name: string | null;
+    avatarUrl: string | null;
+    globalRoles: string[];
+    disabled: boolean;
+    roles: string[];
+}>;
 export declare function clientDto(client: AdminClient): {
     clientId: string;
     confidential: boolean;
@@ -129,3 +145,11 @@ export declare function settingDto(row: SettingRow): {
     locked: boolean;
     lockedBy?: "config" | undefined;
 };
+/** 409 de quem tenta editar papéis geridos fora do authkit (`resolveTokenRoles`). */
+export declare function rolesManagedExternallyError(): {
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | undefined;
+    };
+};

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

@@ -1,3 +1,4 @@
+import { resolveAccountRoles } from '../account_roles.js';
 /** Projeta uma conta para a forma JSON (camelCase) da Admin REST API. */
 export function userDto(account, disabled = false) {
     return {
@@ -9,6 +10,15 @@ export function userDto(account, disabled = false) {
         disabled,
     };
 }
+/**
+ * {@link userDto} + `roles`: os papéis efetivos da conta, pela mesma fonte do
+ * claim (`resolveAccountRoles`). Sem `resolveTokenRoles` é igual a
+ * `globalRoles`; com ele, é o que o app diz (ex.: authz) e `globalRoles` segue
+ * sendo só a coluna guardada.
+ */
+export async function userDtoWithRoles(cfg, account, disabled = false) {
+    return { ...userDto(account, disabled), roles: await resolveAccountRoles(cfg, account) };
+}
 export function clientDto(client) {
     return {
         clientId: client.clientId,
@@ -121,3 +131,7 @@ export function settingDto(row) {
         ...(locked ? { lockedBy: 'config' } : {}),
     };
 }
+/** 409 de quem tenta editar papéis geridos fora do authkit (`resolveTokenRoles`). */
+export function rolesManagedExternallyError() {
+    return apiError('roles_managed_externally', 'Os papéis desta instalação vêm do app (resolveTokenRoles) e só podem ser alterados lá.');
+}

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

@@ -1,3 +1,4 @@
+import { resolveAccountRoles } from '../account_roles.js';
 /**
  * Introspecção genérica de token usada pela Admin REST API (`POST /tokens/verify`).
  * Roteia por prefixo: tokens `pat_...` vão pelo {@link PatStore} (mesma rota do
@@ -36,7 +37,7 @@ export class TokenVerifyService {
             sub: account.id,
             email: account.email,
             name: account.name ?? null,
-            roles: account.globalRoles ?? [],
+            roles: await resolveAccountRoles(this.cfg, account),
             scopes: meta.scopes,
             audience: meta.audience,
             exp: meta.exp,
@@ -64,7 +65,11 @@ export class TokenVerifyService {
             sub,
             email: account?.email ?? null,
             name: account?.name ?? null,
-            roles: account?.globalRoles ?? [],
+            roles: account
+                ? await resolveAccountRoles(this.cfg, account, {
+                    clientId: at.clientId ?? undefined,
+                })
+                : [],
             scopes,
             audience: at.aud ?? null,
             clientId: at.clientId ?? null,

package/build/src/host/admin_console/admin_shell_controller.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { accountPath } from '../account_paths.js';
-import { resolveAccountRoles } from '../account_roles.js';
+import { resolveAccountRoles, rolesManagedExternally } from '../account_roles.js';
 import { getAdminPrefix } from '../admin_prefix.js';
 // ─── Shell HTML cache ─────────────────────────────────────────────────────────
 /**
@@ -141,6 +141,8 @@ export default class AdminShellController {
             features: {
                 // A página de personal agents só aparece com `personalAgents` no config.
                 personalAgents: !!cfg.personalAgents,
+                // Papéis vindos de fora (resolveTokenRoles): a tela só mostra, não edita.
+                rolesManagedExternally: rolesManagedExternally(cfg),
             },
         };
         const { html: rawHtml } = await loadShell();

package/build/src/host/admin_console/console_users_controller.d.ts

@@ -35,6 +35,7 @@ export default class ConsoleUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
         sessionsSupported: boolean;
         sessions: {
             id: string;
@@ -70,6 +71,7 @@ export default class ConsoleUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
         invited: boolean;
     }>;
     /** PATCH {prefix}/api/users/:id/roles */
@@ -80,6 +82,7 @@ export default class ConsoleUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
     }>;
     /** POST {prefix}/api/users/:id/disable */
     disable(ctx: HttpContext): Promise<void | {}>;
@@ -91,6 +94,7 @@ export default class ConsoleUsersController {
         avatarUrl: string | null;
         globalRoles: string[];
         disabled: boolean;
+        roles: string[];
     }>;
     /** POST {prefix}/api/users/:id/reset-password */
     resetPassword(ctx: HttpContext): Promise<void | {}>;

package/build/src/host/admin_console/console_users_controller.js

@@ -1,9 +1,10 @@
 import '../augmentations.js';
 import { supportsAccountDeletion, supportsAccountStatus } from '../../accounts/account_store.js';
 import { ADMIN_LIST_HTTP_DEFAULT_SIZE, parseListPage, parseListSize } from '../../pagination.js';
+import { rolesManagedExternally } from '../account_roles.js';
 import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
 import { AdminUsersService } from '../admin_api/admin_users_service.js';
-import { apiError, grantDto, sessionDto, userDto } from '../admin_api/dto.js';
+import { apiError, grantDto, rolesManagedExternallyError, sessionDto, userDtoWithRoles, } from '../admin_api/dto.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { adminUserCreateValidator, adminUserRolesValidator } from '../admin_validators.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
@@ -61,7 +62,7 @@ export default class ConsoleUsersController {
             size,
         });
         const users = new AdminUsersService(cfg);
-        const data = await Promise.all(result.data.map(async (u) => userDto(u, await users.isDisabled(u.id))));
+        const data = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
         return { meta: { page, size, total: result.total }, data };
     }
     /** GET {prefix}/api/users/:id */
@@ -92,7 +93,7 @@ export default class ConsoleUsersController {
             // fail-safe
         }
         return {
-            ...userDto(account, disabled),
+            ...(await userDtoWithRoles(cfg, account, disabled)),
             sessionsSupported: sessions.canList,
             sessions: enriched.map(sessionDto),
             grants: grants.map(grantDto),
@@ -122,7 +123,7 @@ export default class ConsoleUsersController {
             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 };
+        return { ...(await userDtoWithRoles(cfg, result.account)), invited: result.invited };
     }
     /** PATCH {prefix}/api/users/:id/roles */
     async updateRoles(ctx) {
@@ -132,6 +133,11 @@ export default class ConsoleUsersController {
         const account = await cfg.accountStore.findById(id);
         if (!account)
             return ctx.response.notFound(apiError('not_found', 'Usuário não encontrado.'));
+        // Papéis de fora do authkit (resolveTokenRoles): a coluna não decide acesso,
+        // então gravar nela seria um "salvo" mentiroso. O app edita na fonte dele.
+        if (rolesManagedExternally(cfg)) {
+            return ctx.response.status(409).send(rolesManagedExternallyError());
+        }
         const actorId = ctx.session?.get(ACCOUNT_SESSION_KEY) ?? null;
         const { roles: rolesInput } = await ctx.request.validateUsing(adminUserRolesValidator);
         const roles = Array.from(new Set((rolesInput ?? []).map((r) => r.trim()).filter(Boolean)));
@@ -156,7 +162,7 @@ export default class ConsoleUsersController {
         }
         const updated = await cfg.accountStore.findById(id);
         const disabled = await users.isDisabled(id);
-        return userDto(updated, disabled);
+        return userDtoWithRoles(cfg, updated, disabled);
     }
     /** POST {prefix}/api/users/:id/disable */
     async disable(ctx) {
@@ -193,7 +199,7 @@ export default class ConsoleUsersController {
         }
         const updated = await cfg.accountStore.findById(id);
         const disabled = await users.isDisabled(id);
-        return userDto(updated, disabled);
+        return userDtoWithRoles(cfg, updated, disabled);
     }
     /** POST {prefix}/api/users/:id/reset-password */
     async resetPassword(ctx) {

package/build/src/host/controllers/interaction_controller.d.ts

@@ -136,6 +136,14 @@ export default class AuthInteractionController {
      * Consome o magic link. Em sucesso finaliza o login (amr `['email']`). Token
      * inválido/expirado volta ao início do login.
      */
+    /**
+     * GET /auth/interaction/:uid/social/continue — segunda metade do login social
+     * quando a conta deve o 2º fator (ver `AuthSocialController#callback`). Lê o
+     * login pendente da sessão UMA vez, confere que é desta interaction e passa
+     * pelo mesmo `secondFactorGate` dos outros fluxos, com `fed` como fator
+     * primário no `amr`.
+     */
+    socialContinue(ctx: HttpContext): Promise<any>;
     magicLinkConsume(ctx: HttpContext): Promise<any>;
     /**
      * POST /auth/interaction/:uid/otp-verify

package/build/src/host/controllers/interaction_controller.js

@@ -1,5 +1,6 @@
 import '../augmentations.js';
 import { supportsLoginMethodsPreference, supportsMagicLink, supportsOtpLogin, supportsPasskeys, } from '../../accounts/account_store.js';
+import { resolveAccountRoles } from '../account_roles.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { guardBotProtection, resolveEffectiveBotProtection } from '../bot_protection.js';
 import { brandFor, isFirstParty } from '../branding.js';
@@ -16,8 +17,19 @@ import { authkitOrigin } from '../origin.js';
 import { createOtpLockout, generateOtpUnlockToken, rawToDbOtpUnlockToken, resolveEffectiveOtpLockout, } from '../otp_lockout.js';
 import { resolveRuntimeSettingsOrNoop } from '../runtime_settings.js';
 import { resolveEffectiveAuthMethods, resolveEffectiveMaintenanceMode, resolveEffectiveRegistration, resolveEffectiveSessionPolicy, } from '../runtime_toggles.js';
+import { SOCIAL_PENDING_KEY, SOCIAL_PENDING_TTL_MS, } from '../social_pending.js';
 import { buildTrustedDevicePayload, isTrustedDeviceValid, TRUSTED_DEVICE_COOKIE, } from '../trusted_device.js';
 import { normalizeUserLoginMethods, resolveEffectiveUserLoginMethods, } from '../user_login_methods.js';
+/**
+ * Conta com papel administrativo (`cfg.admin.roles`, default `['ADMIN']`) — o
+ * bypass do modo manutenção. Os papéis vêm de `resolveAccountRoles`, a mesma
+ * fonte do claim (`resolveTokenRoles`, ex.: authz), não só do `globalRoles`.
+ */
+async function isAdminAccount(cfg, account) {
+    const adminRoles = cfg.admin?.roles ?? ['ADMIN'];
+    const roles = await resolveAccountRoles(cfg, account);
+    return adminRoles.some((role) => roles.includes(role));
+}
 /**
  * Chave i18n do erro de status de conta (disabled/expired) compartilhada pelos
  * fluxos passwordless (magic link, OTP, passkey).
@@ -105,8 +117,7 @@ export default class AuthInteractionController {
         if (!status.allowed)
             return fail(accountStatusErrorKey(status.reason));
         const maintenance = await resolveEffectiveMaintenanceMode(settings);
-        if (maintenance.enabled &&
-            !(cfg.admin?.roles ?? ['ADMIN']).some((role) => (account.globalRoles ?? []).includes(role))) {
+        if (maintenance.enabled && !(await isAdminAccount(cfg, account))) {
             return render(ctx, 'maintenance', {
                 uid: details.uid,
                 csrfToken: ctx.request.csrfToken,
@@ -468,9 +479,7 @@ export default class AuthInteractionController {
         // Contas admin (role em cfg.admin.roles) CONTINUAM podendo logar.
         // Contas comuns são bloqueadas com a tela de manutenção.
         if (maintenance.enabled) {
-            const adminRoles = cfg.admin?.roles ?? ['ADMIN'];
-            const accountRoles = acc.globalRoles ?? [];
-            const isAdmin = adminRoles.some((r) => accountRoles.includes(r));
+            const isAdmin = await isAdminAccount(cfg, acc);
             if (!isAdmin) {
                 return render(ctx, 'maintenance', {
                     uid: details.uid,
@@ -563,9 +572,9 @@ export default class AuthInteractionController {
             ...(used.has('webauthn') ? { passkeyAvailable: false } : {}),
         });
     }
-    async configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless = primary !== 'pwd') {
+    async configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless = primary !== 'pwd', forceRequired = false) {
         const requiredFactors = cfg.mfa?.requiredFactors ?? 2;
-        const mfaRequired = this.acrRequiresMfa(cfg, details) || cfg.mfa?.requiredFactors !== undefined;
+        const mfaRequired = forceRequired || this.acrRequiresMfa(cfg, details) || cfg.mfa?.requiredFactors !== undefined;
         const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
         const enrolledTotp = mfa.totp ?? mfa.enabled;
         const enrolledPasskey = await this.hasPasskeys(cfg, accountId);
@@ -736,8 +745,7 @@ export default class AuthInteractionController {
             });
         }
         const maintenance = await resolveEffectiveMaintenanceMode(settings);
-        if (maintenance.enabled &&
-            !(cfg.admin?.roles ?? ['ADMIN']).some((role) => (account.globalRoles ?? []).includes(role))) {
+        if (maintenance.enabled && !(await isAdminAccount(cfg, account))) {
             return cfg.render(ctx, 'maintenance', {
                 uid: flow.uid,
                 csrfToken: ctx.request.csrfToken,
@@ -950,12 +958,12 @@ export default class AuthInteractionController {
      *  - caso geral → `challenge`, com o accountId em `MFA_PENDING_KEY` e o fator
      *    primário (`primary`) em `MFA_PRIMARY_KEY`.
      */
-    async secondFactorGate(ctx, cfg, accountId, details, primary, primaryFactorId = primary, rememberRequested, passwordless = primary !== 'pwd') {
+    async secondFactorGate(ctx, cfg, accountId, details, primary, primaryFactorId = primary, rememberRequested, passwordless = primary !== 'pwd', forceRequired = false) {
         ctx.session.forget(MFA_CUSTOM_PRIMARY_KEY);
         clearMfaFlow(ctx);
         if (cfg.mfa)
-            return this.configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless);
-        const mfaRequired = this.acrRequiresMfa(cfg, details);
+            return this.configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless, forceRequired);
+        const mfaRequired = forceRequired || this.acrRequiresMfa(cfg, details);
         const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
         // Passkey disponível como alternativa ao TOTP se o store suporta E a conta
         // tem ao menos uma credencial registrada.
@@ -1212,6 +1220,32 @@ export default class AuthInteractionController {
      * Consome o magic link. Em sucesso finaliza o login (amr `['email']`). Token
      * inválido/expirado volta ao início do login.
      */
+    /**
+     * GET /auth/interaction/:uid/social/continue — segunda metade do login social
+     * quando a conta deve o 2º fator (ver `AuthSocialController#callback`). Lê o
+     * login pendente da sessão UMA vez, confere que é desta interaction e passa
+     * pelo mesmo `secondFactorGate` dos outros fluxos, com `fed` como fator
+     * primário no `amr`.
+     */
+    async socialContinue(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const uid = ctx.request.param('uid');
+        const pending = ctx.session.get(SOCIAL_PENDING_KEY);
+        ctx.session.forget(SOCIAL_PENDING_KEY);
+        const details = await service.interactions.details(ctx);
+        if (!pending ||
+            pending.uid !== uid ||
+            details.uid !== uid ||
+            details.prompt.name !== 'login' ||
+            Date.now() - pending.at > SOCIAL_PENDING_TTL_MS) {
+            return ctx.response.redirect(`/auth/interaction/${uid}`);
+        }
+        const gate = await this.secondFactorGate(ctx, cfg, pending.accountId, details, 'fed', 'fed', undefined, true, pending.required);
+        if (gate.kind === 'challenge')
+            return gate.response;
+        return service.interactions.completeLogin(ctx, pending.accountId, { amr: ['fed'] });
+    }
     async magicLinkConsume(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;

package/build/src/host/controllers/pat_introspection_controller.d.ts

@@ -14,7 +14,7 @@ export default class PatIntrospectionController {
         sub: any;
         email: any;
         name: any;
-        roles: any;
+        roles: string[];
         scopes: any;
         audience: any;
         exp: any;

package/build/src/host/controllers/pat_introspection_controller.js

@@ -1,4 +1,5 @@
 import { timingSafeEqual } from 'node:crypto';
+import { resolveAccountRoles } from '../account_roles.js';
 function bearerMatches(header, expected) {
     if (!header || !header.startsWith('Bearer '))
         return false;
@@ -47,7 +48,7 @@ export default class PatIntrospectionController {
             sub: account.id,
             email: account.email,
             name: account.name ?? null,
-            roles: account.globalRoles ?? [],
+            roles: await resolveAccountRoles(cfg, account),
             scopes: meta.scopes,
             audience: meta.audience,
             exp: meta.exp,

package/build/src/host/controllers/registration_controller.d.ts

@@ -6,6 +6,16 @@ export default class AuthRegistrationController {
     showSignup(ctx: HttpContext): Promise<any>;
     /** POST /auth/interaction/:uid/signup — cria o usuário e finaliza o login. */
     signup(ctx: HttpContext): Promise<any>;
+    /**
+     * GET /auth/interaction/:uid/signup/confirm?token= — o dono do e-mail abriu o
+     * link do cadastro passwordless. Cria a conta (e-mail já verificado: quem
+     * clicou provou a caixa de entrada) e conclui pelo fluxo de magic link, que
+     * aplica os mesmos gates do login (status, manutenção, 2º fator).
+     *
+     * Conta que já existe → o link é recusado e a pessoa volta ao login: é o que
+     * faz o link valer uma vez só, sem estado no banco.
+     */
+    signupConfirm(ctx: HttpContext): Promise<void>;
     /** GET /auth/forgot-password — tela standalone. */
     showForgot(ctx: HttpContext): Promise<any>;
     /** POST /auth/forgot-password — gera token e (dev) loga o link. Sempre responde sucesso (não vaza emails). */