@adonis-agora/authkit-server 0.34.0

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

@@ -0,0 +1,22 @@
+import type { HttpContext } from '@adonisjs/core/http';
+export default class PatIntrospectionController {
+    handle(ctx: HttpContext): Promise<void | {
+        active: boolean;
+        sub?: undefined;
+        email?: undefined;
+        name?: undefined;
+        roles?: undefined;
+        scopes?: undefined;
+        audience?: undefined;
+        exp?: undefined;
+    } | {
+        active: boolean;
+        sub: any;
+        email: any;
+        name: any;
+        roles: any;
+        scopes: any;
+        audience: any;
+        exp: any;
+    }>;
+}

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

@@ -0,0 +1,46 @@
+import { timingSafeEqual } from 'node:crypto';
+function bearerMatches(header, expected) {
+    if (!header || !header.startsWith('Bearer '))
+        return false;
+    const provided = header.slice(7);
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export default class PatIntrospectionController {
+    async handle(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const secret = cfg.patIntrospectionSecret;
+        if (!secret || !bearerMatches(ctx.request.header('authorization'), secret)) {
+            return ctx.response.unauthorized({ error: 'invalid_client' });
+        }
+        const token = ctx.request.input('token');
+        if (!token || typeof token !== 'string') {
+            return { active: false };
+        }
+        const meta = await cfg.patStore.findActiveByToken(token);
+        if (!meta)
+            return { active: false };
+        const account = await cfg.accountStore.findById(meta.accountId);
+        if (!account)
+            return { active: false };
+        await cfg.audit?.record({
+            type: 'pat.used',
+            accountId: account.id,
+            email: account.email,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { audience: meta.audience },
+        });
+        return {
+            active: true,
+            sub: account.id,
+            email: account.email,
+            name: account.name ?? null,
+            roles: account.globalRoles ?? [],
+            scopes: meta.scopes,
+            audience: meta.audience,
+            exp: meta.exp,
+        };
+    }
+}

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

@@ -0,0 +1,18 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+export default class AuthRegistrationController {
+    /** GET /auth/interaction/:uid/signup — tela de cadastro (dentro do fluxo OIDC). */
+    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/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). */
+    forgot(ctx: HttpContext): Promise<any>;
+    /** GET /auth/reset-password?token=... — tela standalone. */
+    showReset(ctx: HttpContext): Promise<any>;
+    /** POST /auth/reset-password — redefine a senha. */
+    reset(ctx: HttpContext): Promise<any>;
+    /** GET /auth/verify-email?token=... — consome o token e mostra sucesso/falha. */
+    verifyEmail(ctx: HttpContext): Promise<any>;
+}

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

@@ -0,0 +1,382 @@
+import '../augmentations.js';
+import { brandFor } from '../branding.js';
+import { signupValidator, forgotPasswordValidator, resetPasswordValidator } from '../validators.js';
+import { sendPasswordResetEmail, sendEmailVerificationEmail } from '../default_mailer.js';
+import { translate } from '../i18n.js';
+import { PasswordPolicyError } from '../../password/password_manager.js';
+import { guardBotProtection, resolveEffectiveBotProtection } from '../bot_protection.js';
+import { RuntimeSettings, resolveRuntimeSettings } from '../runtime_settings.js';
+import { resolveEffectiveRegistration, resolveEffectiveMaintenanceMode, resolveEffectiveAuthMethods, } from '../runtime_toggles.js';
+import { dispatchSecurityNotice } from '../security_notice_service.js';
+import { AdminSessionsService } from '../admin_sessions_service.js';
+/**
+ * Best-effort: returns a RuntimeSettings backed by the container DB, or a no-op
+ * fallback. Contrato NON-NULL preservado (callers passam direto p/ resolvers que
+ * exigem SettingsCapability). Reusa a fábrica canônica `resolveRuntimeSettings`
+ * e degrada para o RuntimeSettings no-op (probe via SELECT lança → tabela ausente
+ * → config fallback) quando a resolução falha.
+ */
+async function getRuntimeSettings(ctx) {
+    const rs = await resolveRuntimeSettings(ctx);
+    return rs ?? new RuntimeSettings({ table: () => { throw new Error('no-op'); } });
+}
+export default class AuthRegistrationController {
+    /** GET /auth/interaction/:uid/signup — tela de cadastro (dentro do fluxo OIDC). */
+    async showSignup(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const details = await service.interactions.details(ctx);
+        const brand = brandFor(cfg.branding, details.params.client_id);
+        const runtimeSettings = await getRuntimeSettings(ctx);
+        // Maintenance mode: mostra página de manutenção se ativo.
+        const maintenance = await resolveEffectiveMaintenanceMode(runtimeSettings);
+        if (maintenance.enabled) {
+            return render(ctx, 'maintenance', {
+                csrfToken: ctx.request.csrfToken,
+                message: maintenance.message ?? translate(cfg.messages, 'maintenance.default_message'),
+                brand,
+            });
+        }
+        // Registration disabled: mostra mensagem clara na tela de signup.
+        const registrationEnabled = await resolveEffectiveRegistration(cfg.registration?.enabled ?? true, runtimeSettings);
+        if (!registrationEnabled) {
+            return render(ctx, 'signup', {
+                uid: details.uid,
+                csrfToken: ctx.request.csrfToken,
+                brand,
+                registrationDisabled: true,
+                registrationDisabledMessage: translate(cfg.messages, 'errors.registration_disabled'),
+            });
+        }
+        const effectiveBot = await resolveEffectiveBotProtection(cfg.botProtection, runtimeSettings);
+        return render(ctx, 'signup', {
+            uid: details.uid,
+            csrfToken: ctx.request.csrfToken,
+            brand,
+            botProtection: effectiveBot?.on.includes('signup') ? effectiveBot.widget : undefined,
+        });
+    }
+    /** POST /auth/interaction/:uid/signup — cria o usuário e finaliza o login. */
+    async signup(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const details = await service.interactions.details(ctx);
+        const brand = brandFor(cfg.branding, details.params.client_id);
+        const runtimeSettings = await getRuntimeSettings(ctx);
+        // Maintenance mode: rejeita o POST durante manutenção.
+        const maintenance = await resolveEffectiveMaintenanceMode(runtimeSettings);
+        if (maintenance.enabled) {
+            return render(ctx, 'maintenance', {
+                csrfToken: ctx.request.csrfToken,
+                message: maintenance.message ?? translate(cfg.messages, 'maintenance.default_message'),
+                brand,
+            });
+        }
+        // Registration disabled: rejeita o POST — mesmo que alguém bata diretamente.
+        const registrationEnabled = await resolveEffectiveRegistration(cfg.registration?.enabled ?? true, runtimeSettings);
+        if (!registrationEnabled) {
+            return render(ctx, 'signup', {
+                uid: ctx.request.param('uid'),
+                csrfToken: ctx.request.csrfToken,
+                brand,
+                registrationDisabled: true,
+                registrationDisabledMessage: translate(cfg.messages, 'errors.registration_disabled'),
+            });
+        }
+        // Effective bot protection: may be overridden at runtime via auth_settings.
+        const effectiveBotSignup = await resolveEffectiveBotProtection(cfg.botProtection, runtimeSettings);
+        const cfgWithEffectiveBotSignup = effectiveBotSignup !== cfg.botProtection
+            ? { ...cfg, botProtection: effectiveBotSignup }
+            : cfg;
+        // Bot protection (plugável): valida o token do widget ANTES de criar a conta.
+        // Fail-safe: erro/timeout no verify do host PERMITE o cadastro.
+        const clientId = details.params.client_id ?? null;
+        if (!(await guardBotProtection(ctx, cfgWithEffectiveBotSignup, 'signup', { clientId }))) {
+            return render(ctx, 'signup', {
+                uid: ctx.request.param('uid'),
+                csrfToken: ctx.request.csrfToken,
+                error: translate(cfg.messages, 'errors.bot_protection_failed'),
+                brand,
+                botProtection: effectiveBotSignup?.widget,
+            });
+        }
+        const data = await ctx.request.validateUsing(signupValidator);
+        const accountStore = cfg.accountStore;
+        const existing = await accountStore.findByEmail(data.email);
+        if (existing) {
+            return render(ctx, 'signup', {
+                uid: ctx.request.param('uid'),
+                csrfToken: ctx.request.csrfToken,
+                error: translate(cfg.messages, 'errors.email_taken'),
+                brand,
+                botProtection: effectiveBotSignup?.on.includes('signup') ? effectiveBotSignup.widget : undefined,
+            });
+        }
+        let created;
+        try {
+            created = await accountStore.create({
+                email: data.email,
+                password: data.password,
+                fullName: data.fullName,
+            });
+        }
+        catch (error) {
+            // Política de senha (comprimento/complexidade/vazamento) violada → re-renderiza
+            // com a mensagem i18n específica da regra.
+            if (error instanceof PasswordPolicyError) {
+                return render(ctx, 'signup', {
+                    uid: ctx.request.param('uid'),
+                    csrfToken: ctx.request.csrfToken,
+                    error: translate(cfg.messages, error.key, error.params),
+                    brand,
+                    botProtection: effectiveBotSignup?.on.includes('signup') ? effectiveBotSignup.widget : undefined,
+                });
+            }
+            throw error;
+        }
+        await cfg.audit?.record({
+            type: 'signup',
+            accountId: created?.id ?? null,
+            email: data.email,
+            ip: ctx.request.ip?.() ?? null,
+            clientId: details.params.client_id ?? null,
+        });
+        // Finaliza a interaction como login (interactionFinished escreve o redirect 303 que
+        // retoma o authorize; o form nativo da tela segue esse redirect no sucesso).
+        const result = await service.interactions.login(ctx, {
+            email: data.email,
+            password: data.password,
+        });
+        if (!result.ok) {
+            return render(ctx, 'signup', {
+                uid: ctx.request.param('uid'),
+                csrfToken: ctx.request.csrfToken,
+                error: translate(cfg.messages, 'errors.signup_failed'),
+                brand,
+                botProtection: effectiveBotSignup?.on.includes('signup') ? effectiveBotSignup.widget : undefined,
+            });
+        }
+        // Verificação de e-mail (best-effort — não bloqueia nem reverte o login).
+        try {
+            const issued = await accountStore.issueEmailVerificationToken(data.email);
+            if (issued) {
+                await cfg.audit?.record({
+                    type: 'email_verification.issued',
+                    accountId: created?.id ?? null,
+                    email: data.email,
+                    ip: ctx.request.ip?.() ?? null,
+                });
+                const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+                const verifyUrl = `${origin}/auth/verify-email?token=${issued.token}`;
+                // Hook do config tem prioridade (override); senão usa o mailer default do host.
+                if (cfg.mail?.onEmailVerification) {
+                    await cfg.mail.onEmailVerification({ email: data.email, verifyUrl, token: issued.token });
+                }
+                else {
+                    await sendEmailVerificationEmail(ctx, { email: data.email, verifyUrl });
+                }
+            }
+        }
+        catch (error) {
+            ctx.logger.error({ err: error, email: data.email }, 'authkit: falha ao enviar verificação de e-mail');
+        }
+    }
+    /** GET /auth/forgot-password — tela standalone. */
+    async showForgot(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const runtimeSettings = await getRuntimeSettings(ctx);
+        // Maintenance mode: mostra página de manutenção.
+        const maintenance = await resolveEffectiveMaintenanceMode(runtimeSettings);
+        if (maintenance.enabled) {
+            return render(ctx, 'maintenance', {
+                csrfToken: ctx.request.csrfToken,
+                message: maintenance.message ?? translate(cfg.messages, 'maintenance.default_message'),
+            });
+        }
+        // auth_methods: se forgotPassword efetivo for false → 404 (endpoint desligado).
+        const authMethods = await resolveEffectiveAuthMethods(runtimeSettings, {
+            configuredSocialProviders: cfg.social?.providers ?? [],
+            magicLinkCapable: cfg.passwordless?.magicLink && typeof cfg.accountStore.issueMagicLinkToken === 'function',
+        });
+        if (!authMethods.forgotPassword) {
+            return ctx.response.notFound({ error: translate(cfg.messages, 'errors.not_found') });
+        }
+        const effectiveBot = await resolveEffectiveBotProtection(cfg.botProtection, runtimeSettings);
+        return render(ctx, 'forgot', {
+            csrfToken: ctx.request.csrfToken,
+            botProtection: effectiveBot?.on.includes('reset') ? effectiveBot.widget : undefined,
+        });
+    }
+    /** POST /auth/forgot-password — gera token e (dev) loga o link. Sempre responde sucesso (não vaza emails). */
+    async forgot(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const runtimeSettings = await getRuntimeSettings(ctx);
+        // Maintenance mode: rejeita o POST.
+        const maintenance = await resolveEffectiveMaintenanceMode(runtimeSettings);
+        if (maintenance.enabled) {
+            return render(ctx, 'maintenance', {
+                csrfToken: ctx.request.csrfToken,
+                message: maintenance.message ?? translate(cfg.messages, 'maintenance.default_message'),
+            });
+        }
+        // auth_methods: se forgotPassword efetivo for false → 404 (endpoint desligado).
+        const authMethods = await resolveEffectiveAuthMethods(runtimeSettings, {
+            configuredSocialProviders: cfg.social?.providers ?? [],
+            magicLinkCapable: cfg.passwordless?.magicLink && typeof cfg.accountStore.issueMagicLinkToken === 'function',
+        });
+        if (!authMethods.forgotPassword) {
+            return ctx.response.notFound({ error: translate(cfg.messages, 'errors.not_found') });
+        }
+        // Effective bot protection: may be overridden at runtime via auth_settings.
+        const effectiveBotForgot = await resolveEffectiveBotProtection(cfg.botProtection, runtimeSettings);
+        const cfgWithEffectiveBotForgot = effectiveBotForgot !== cfg.botProtection
+            ? { ...cfg, botProtection: effectiveBotForgot }
+            : cfg;
+        // Bot protection (plugável): valida o token do widget ANTES de emitir o token
+        // de reset. Fail-safe: erro/timeout no verify do host PERMITE o fluxo.
+        if (!(await guardBotProtection(ctx, cfgWithEffectiveBotForgot, 'reset'))) {
+            return render(ctx, 'forgot', {
+                csrfToken: ctx.request.csrfToken,
+                error: translate(cfg.messages, 'errors.bot_protection_failed'),
+                botProtection: effectiveBotForgot?.widget,
+            });
+        }
+        const { email } = await ctx.request.validateUsing(forgotPasswordValidator);
+        const accountStore = cfg.accountStore;
+        const result = await accountStore.issuePasswordResetToken(email);
+        if (result) {
+            await cfg.audit?.record({
+                type: 'password_reset.issued',
+                email,
+                ip: ctx.request.ip?.() ?? null,
+            });
+            const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+            const url = `${origin}/auth/reset-password?token=${result.token}`;
+            // Hook do config tem prioridade (override); senão usa o mailer default do host.
+            if (cfg.mail?.onPasswordReset) {
+                await cfg.mail.onPasswordReset({ email, resetUrl: url, token: result.token });
+            }
+            else {
+                await sendPasswordResetEmail(ctx, { email, resetUrl: url });
+            }
+        }
+        return render(ctx, 'forgot', {
+            csrfToken: ctx.request.csrfToken,
+            sent: true,
+        });
+    }
+    /** GET /auth/reset-password?token=... — tela standalone. */
+    async showReset(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const token = ctx.request.qs().token ?? '';
+        return render(ctx, 'reset', { token, csrfToken: ctx.request.csrfToken });
+    }
+    /** POST /auth/reset-password — redefine a senha. */
+    async reset(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const { token, password } = await ctx.request.validateUsing(resetPasswordValidator);
+        const accountStore = cfg.accountStore;
+        // Pré-lookup da conta pelo token (best-effort) para a notificação de segurança.
+        // O token é consumido a seguir, então buscamos antes de chamar consumePasswordResetToken.
+        let accountForNotice;
+        try {
+            // issuePasswordResetToken coloca o token no campo passwordResetToken; podemos
+            // procurar pelo e-mail via store se ele suportar lookup por token (não é um
+            // método público). Tentamos via findByPasswordResetToken se disponível; senão
+            // pulamos o aviso graciosamente.
+            const storeAny = accountStore;
+            if (typeof storeAny.findByPasswordResetToken === 'function') {
+                accountForNotice = await storeAny.findByPasswordResetToken(token);
+            }
+        }
+        catch {
+            // Silencioso — aviso é best-effort.
+        }
+        let ok;
+        try {
+            ok = await accountStore.consumePasswordResetToken(token, password);
+        }
+        catch (error) {
+            // Política de senha violada → re-renderiza a tela de reset com a regra.
+            if (error instanceof PasswordPolicyError) {
+                return render(ctx, 'reset', {
+                    token,
+                    csrfToken: ctx.request.csrfToken,
+                    error: translate(cfg.messages, error.key, error.params),
+                });
+            }
+            throw error;
+        }
+        if (!ok) {
+            return ctx.response.badRequest({ error: translate(cfg.messages, 'errors.invalid_or_expired_token') });
+        }
+        await cfg.audit?.record({
+            type: 'password_reset.consumed',
+            ip: ctx.request.ip?.() ?? null,
+        });
+        // M2: reset de senha INVALIDA todas as sessões/grants da conta (segurança >
+        // conveniência — quem reseta a senha pode estar recuperando uma conta
+        // comprometida). Best-effort/fail-safe: uma falha aqui NÃO falha o reset.
+        if (accountForNotice) {
+            try {
+                const sessions = new AdminSessionsService(service);
+                const result = await sessions.revokeAll(accountForNotice.id);
+                await cfg.audit?.record({
+                    type: 'session.revoked_all',
+                    accountId: accountForNotice.id,
+                    actorId: null,
+                    ip: ctx.request.ip?.() ?? null,
+                    metadata: {
+                        sessions: result.sessions,
+                        grants: result.grants,
+                        accessTokens: result.accessTokens,
+                        refreshTokens: result.refreshTokens,
+                        source: 'password-reset',
+                    },
+                });
+            }
+            catch {
+                // fail-safe: a troca de senha já vale; a invalidação é best-effort.
+            }
+        }
+        // Notificação de segurança: senha alterada via reset (best-effort, fail-safe).
+        if (accountForNotice) {
+            await dispatchSecurityNotice(ctx, {
+                account: accountForNotice,
+                kind: 'password_changed',
+                ip: ctx.request.ip?.() ?? null,
+                timestamp: new Date().toISOString(),
+            }, cfg.mail, cfg.audit);
+        }
+        return render(ctx, 'reset', {
+            token: '',
+            csrfToken: ctx.request.csrfToken,
+            done: true,
+        });
+    }
+    /** GET /auth/verify-email?token=... — consome o token e mostra sucesso/falha. */
+    async verifyEmail(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const token = ctx.request.qs().token ?? '';
+        const ok = await cfg.accountStore.consumeEmailVerificationToken(token);
+        if (ok) {
+            await cfg.audit?.record({
+                type: 'email_verification.consumed',
+                ip: ctx.request.ip?.() ?? null,
+            });
+        }
+        return render(ctx, 'verify-email', { verified: ok });
+    }
+}

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

@@ -0,0 +1,8 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+export default class AuthSocialController {
+    /** GET /auth/:provider/redirect/:uid — guarda o uid e redireciona para o provider OAuth. */
+    redirect(ctx: HttpContext): Promise<void>;
+    /** GET /auth/:provider/callback — retorno do provider → acha/cria AuthUser → conclui a interaction. */
+    callback(ctx: HttpContext): Promise<void>;
+}

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

@@ -0,0 +1,89 @@
+import '../augmentations.js';
+import { randomUUID } from 'node:crypto';
+import { supportsProviderIdentity } from '../../accounts/account_store.js';
+const UID_SESSION_KEY = 'authkit_social_uid';
+/**
+ * `AllyService.use()` é tipado contra a interface `SocialProviders`, que só é
+ * preenchida pelo HOST (a lib não conhece os providers configurados). Para um
+ * nome de provider dinâmico (vindo da rota), o retorno colapsa em `never`, então
+ * resolvemos via o contrato genérico do driver — sem cast pro `HttpContext` inteiro.
+ */
+function useProvider(ctx, provider) {
+    return ctx.ally.use(provider);
+}
+export default class AuthSocialController {
+    /** GET /auth/:provider/redirect/:uid — guarda o uid e redireciona para o provider OAuth. */
+    async redirect(ctx) {
+        const provider = ctx.request.param('provider');
+        ctx.session.put(UID_SESSION_KEY, ctx.request.param('uid'));
+        return useProvider(ctx, provider).redirect();
+    }
+    /** GET /auth/:provider/callback — retorno do provider → acha/cria AuthUser → conclui a interaction. */
+    async callback(ctx) {
+        const provider = ctx.request.param('provider');
+        const social = useProvider(ctx, provider);
+        const uid = ctx.session.get(UID_SESSION_KEY);
+        const backToLogin = uid ? `/auth/interaction/${uid}` : '/health';
+        if (social.accessDenied() || social.stateMisMatch() || social.hasError()) {
+            ctx.session.forget(UID_SESSION_KEY);
+            return ctx.response.redirect(backToLogin);
+        }
+        const profile = await social.user();
+        // `profile.id` é o id estável do usuário no provider — independe do e-mail.
+        if (!profile.id) {
+            ctx.session.forget(UID_SESSION_KEY);
+            return ctx.response.redirect(backToLogin);
+        }
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const store = cfg.accountStore;
+        const email = profile.email ?? undefined;
+        // Account linking exige a capacidade de provider-identity (model wired no store).
+        // Ausente → não há como ligar a identidade; volta ao login em vez de quebrar.
+        if (!supportsProviderIdentity(store)) {
+            ctx.session.forget(UID_SESSION_KEY);
+            return ctx.response.redirect(backToLogin);
+        }
+        // Precedência do account linking:
+        //  1. Identidade de provider já ligada → loga essa conta.
+        //  2. Senão, e-mail conhecido → acha por e-mail e LIGA a identidade (linking).
+        //  3. Senão → cria conta nova e liga a identidade.
+        let user = await store.findByProviderIdentity(provider, profile.id);
+        if (!user && email) {
+            const byEmail = await store.findByEmail(email);
+            if (byEmail) {
+                await store.linkProviderIdentity({
+                    accountId: byEmail.id,
+                    provider,
+                    providerUserId: profile.id,
+                    email,
+                });
+                user = byEmail;
+            }
+        }
+        if (!user) {
+            // Sem e-mail não há como criar/identificar uma conta — volta ao login.
+            if (!email) {
+                ctx.session.forget(UID_SESSION_KEY);
+                return ctx.response.redirect(backToLogin);
+            }
+            const created = await store.create({
+                email,
+                password: randomUUID(),
+                fullName: profile.name ?? null,
+                emailVerified: true,
+            });
+            await store.linkProviderIdentity({
+                accountId: created.id,
+                provider,
+                providerUserId: profile.id,
+                email,
+            });
+            user = created;
+        }
+        ctx.session.forget(UID_SESSION_KEY);
+        // Conclui a interaction OIDC para este usuário (escreve o 303 de volta ao authorize).
+        // O cookie de interaction (path '/') sobrevive ao round-trip do provider OAuth.
+        await service.interactions.completeLogin(ctx, user.id);
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Helper de exceções de CSRF para as rotas machine-to-machine do AuthKit.
+ *
+ * Os endpoints do IdP (token/introspection/PAT) e o back-channel logout são
+ * server-to-server (sem browser/token XSRF). Em vez de cada app reescrever a
+ * checagem de URL no `config/shield.ts`, use este helper:
+ *
+ * ```ts
+ * // config/shield.ts
+ * import { authkitCsrfExceptions } from '@adonis-agora/authkit-server'
+ * csrf: {
+ *   enabled: true,
+ *   exceptRoutes: (ctx) => authkitCsrfExceptions(ctx.request.url(), { mountPath: '/oidc' })
+ *     || ctx.request.url().includes('/api'),
+ * }
+ * ```
+ */
+export interface AuthkitCsrfOptions {
+    /** mountPath do IdP (mesmo de defineConfig/registerAuthHost). Default: `/oidc`. */
+    mountPath?: string;
+    /** Inclui a rota de back-channel logout do CLIENT (default: `/auth/backchannel-logout`). */
+    backchannelLogoutPath?: string | false;
+}
+/**
+ * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
+ * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
+ * rota de back-channel logout do client.
+ */
+export declare function authkitCsrfExceptions(url: string, options?: AuthkitCsrfOptions): boolean;

package/build/src/host/csrf.js

@@ -0,0 +1,14 @@
+/**
+ * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
+ * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
+ * rota de back-channel logout do client.
+ */
+export function authkitCsrfExceptions(url, options = {}) {
+    const mountPath = options.mountPath ?? '/oidc';
+    const backchannel = options.backchannelLogoutPath === false
+        ? null
+        : (options.backchannelLogoutPath ?? '/auth/backchannel-logout');
+    return (url.includes(mountPath) ||
+        url.includes('/authkit/pat') ||
+        (backchannel !== null && url === backchannel));
+}