@adonis-agora/authkit-server 0.77.0 → 0.79.0

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

@@ -0,0 +1,173 @@
+import '../augmentations.js';
+import { personalAgentsFor } from '../../agents/runtime.js';
+import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
+import { impersonationState } from '../impersonation_session.js';
+import { redirectExact } from '../redirect_exact.js';
+/** A tela nunca pode ser emoldurada (clickjacking — ver `agent_consent_controller.ts`). */
+function denyFraming(ctx) {
+    ctx.response.header('X-Frame-Options', 'DENY');
+    ctx.response.header('Content-Security-Policy', "frame-ancestors 'none'");
+}
+function chosenScopes(ctx) {
+    const raw = ctx.request.input('scope');
+    return (Array.isArray(raw) ? raw : raw ? [raw] : []).map(String);
+}
+/**
+ * Telas do usuário no Poppy: o consentimento do Direct Sign-In (o
+ * `authorization_endpoint`, §4.5) e a do Device Sign-In (o `verification_uri`,
+ * §4.6). Montadas atrás do `accountGuard`: sem sessão, o usuário passa pelo login
+ * DESTE app e volta. Abrir o link nunca aprova sozinho — a aprovação é um POST
+ * com CSRF. Recusadas durante impersonation.
+ */
+export default class PoppyConsentController {
+    /** GET {prefix}/oauth/authorize */
+    async authorize(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.direct)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const render = service.config.render;
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/consent', {
+                csrfToken: ctx.request.csrfToken,
+                action: poppy.urls.authorization,
+                request: null,
+                account: null,
+                error: 'agents.consent.impersonating',
+            });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const outcome = await poppy.startAuthorization(ctx.request.qs(), accountId);
+        if (outcome.kind === 'redirect')
+            return redirectExact(ctx.response, outcome.url);
+        if (outcome.kind === 'error') {
+            ctx.response.status(400);
+            return render(ctx, 'agents/done', { status: 'invalid', agentName: null, scopes: [] });
+        }
+        const account = await service.config.accountStore.findById(accountId);
+        return render(ctx, 'agents/consent', {
+            csrfToken: ctx.request.csrfToken,
+            action: poppy.urls.authorization,
+            request: {
+                agentName: outcome.request.agentName,
+                agentOrigin: outcome.request.agentOrigin,
+                logoUri: outcome.request.logoUri,
+                scopes: outcome.request.scopes,
+                hidden: [{ name: 'request_id', value: outcome.request.id }],
+            },
+            account: { email: account?.email ?? null },
+            error: null,
+        });
+    }
+    /** POST {prefix}/oauth/authorize — `request_id`, `decision=allow|deny`, `scope[]`. */
+    async decideAuthorization(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.direct)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const decided = await poppy.decideAuthorization({
+            requestId: String(ctx.request.input('request_id') ?? ''),
+            accountId,
+            allow: ctx.request.input('decision') === 'allow',
+            scopes: chosenScopes(ctx),
+        });
+        if (!decided) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        await cfg.audit?.record({
+            type: decided.approved ? 'agent.delegation_approved' : 'agent.delegation_denied',
+            accountId,
+            clientId: decided.clientId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { protocol: 'poppy', signIn: 'direct', scopes: decided.approved ?? [] },
+        });
+        return redirectExact(ctx.response, decided.url);
+    }
+    /** GET {prefix}/device?user_code=XXXX-XXXX */
+    async device(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.device)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const render = service.config.render;
+        const base = {
+            csrfToken: ctx.request.csrfToken,
+            action: poppy.urls.device,
+            request: null,
+            account: null,
+            error: null,
+        };
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/consent', { ...base, error: 'agents.consent.impersonating' });
+        }
+        const input = ctx.request.input('user_code');
+        if (!input)
+            return render(ctx, 'agents/consent', base);
+        const pending = await poppy.pendingDevice(input);
+        if (!pending) {
+            return render(ctx, 'agents/consent', { ...base, error: 'agents.consent.invalid_code' });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const account = await service.config.accountStore.findById(accountId);
+        return render(ctx, 'agents/consent', {
+            ...base,
+            request: {
+                userCode: pending.userCode,
+                agentName: pending.agentName,
+                agentOrigin: pending.agentOrigin,
+                scopes: pending.scopes,
+            },
+            account: { email: account?.email ?? null },
+        });
+    }
+    /** POST {prefix}/device — `user_code`, `decision`, `scope[]`. */
+    async decideDevice(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.device)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const userCode = String(ctx.request.input('user_code') ?? '');
+        const pending = await poppy.pendingDevice(userCode);
+        const decided = await poppy.decideDevice({
+            userCode,
+            accountId,
+            allow: ctx.request.input('decision') === 'allow',
+            scopes: chosenScopes(ctx),
+        });
+        if (!decided || !pending) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        await cfg.audit?.record({
+            type: decided.approved ? 'agent.delegation_approved' : 'agent.delegation_denied',
+            accountId,
+            clientId: decided.clientId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { protocol: 'poppy', signIn: 'device', scopes: decided.approved ?? [] },
+        });
+        return render(ctx, 'agents/done', {
+            status: decided.approved ? 'approved' : 'denied',
+            agentName: pending.agentName,
+            scopes: decided.approved ? poppy.describe(decided.approved) : [],
+        });
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Endpoints server-to-server do Poppy (§3, §4): descoberta, metadata RFC 8414,
+ * token, revogação, device authorization, Mediated Sign-In e a sessão de
+ * navegador (§5). Todos isentos de CSRF — ver `authkitCsrfExceptions`.
+ */
+export default class PoppyController {
+    /** `GET /.well-known/poppy.json` — só no domínio da empresa (ignorando `www.`). */
+    discovery(ctx: HttpContext): Promise<void>;
+    /** `GET /.well-known/oauth-authorization-server{prefix}` (RFC 8414 + `poppy_domains`). */
+    metadata(ctx: HttpContext): Promise<void>;
+    token(ctx: HttpContext): Promise<void>;
+    deviceAuthorization(ctx: HttpContext): Promise<void>;
+    /** RFC 7009: 200 também para token desconhecido. */
+    revoke(ctx: HttpContext): Promise<void>;
+    /** `POST auth.mediated.endpoint` (§4.7) — com o Session Token (DPoP). */
+    mediatedStart(ctx: HttpContext): Promise<void>;
+    /** `POST {mediated}/{sign_in_id}` (§4.7). */
+    mediatedCode(ctx: HttpContext): Promise<void>;
+    /**
+     * `POST web.browser_session_endpoint` (§5): asserção no corpo → cookie do app
+     * para a Session e 303 para `return_to`; qualquer falha → 400, sem cookie.
+     */
+    browserSession(ctx: HttpContext): Promise<void>;
+}

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

@@ -0,0 +1,194 @@
+import { PoppyError } from '../../agents/poppy/errors.js';
+import { publicRequestUrl, writePoppyAuthError } from '../../agents/poppy/resource.js';
+import { loginPoppyBrowser } from '../../agents/poppy/web_session.js';
+import { personalAgentsFor } from '../../agents/runtime.js';
+function noStore(ctx) {
+    ctx.response.header('Cache-Control', 'no-store');
+    ctx.response.header('Pragma', 'no-cache');
+}
+function withNonce(ctx, poppy) {
+    const nonce = poppy.nonce();
+    if (nonce)
+        ctx.response.header('DPoP-Nonce', nonce);
+}
+function oauthError(ctx, error) {
+    noStore(ctx);
+    for (const [k, v] of Object.entries(error.headers))
+        ctx.response.header(k, v);
+    if (error.code === 'invalid_dpop_proof' || error.code === 'use_dpop_nonce') {
+        ctx.response.header('WWW-Authenticate', `DPoP error="${error.code}"`);
+    }
+    return ctx.response.status(error.status).json(error.toJSON());
+}
+async function poppyOr404(ctx) {
+    const poppy = (await personalAgentsFor(ctx))?.poppy ?? null;
+    if (!poppy)
+        ctx.response.notFound();
+    return poppy;
+}
+/** Formulário (`application/x-www-form-urlencoded`) da request. */
+function form(ctx) {
+    return ctx.request.all();
+}
+/**
+ * Endpoints server-to-server do Poppy (§3, §4): descoberta, metadata RFC 8414,
+ * token, revogação, device authorization, Mediated Sign-In e a sessão de
+ * navegador (§5). Todos isentos de CSRF — ver `authkitCsrfExceptions`.
+ */
+export default class PoppyController {
+    /** `GET /.well-known/poppy.json` — só no domínio da empresa (ignorando `www.`). */
+    async discovery(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy)
+            return;
+        // `host()` mantém a porta (dev em `localhost:3333`): o `browser_session_endpoint` sai dele.
+        const doc = poppy.discoveryDocument(ctx.request.host() ?? ctx.request.hostname() ?? '');
+        if (!doc)
+            return ctx.response.notFound();
+        ctx.response.header('Access-Control-Allow-Origin', '*');
+        ctx.response.header('Cache-Control', 'public, max-age=300');
+        return ctx.response.json(doc);
+    }
+    /** `GET /.well-known/oauth-authorization-server{prefix}` (RFC 8414 + `poppy_domains`). */
+    async metadata(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy)
+            return;
+        ctx.response.header('Access-Control-Allow-Origin', '*');
+        ctx.response.header('Cache-Control', 'public, max-age=300');
+        return ctx.response.json(poppy.authorizationServerMetadata());
+    }
+    async token(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy)
+            return;
+        withNonce(ctx, poppy);
+        try {
+            const body = await poppy.token(form(ctx), ctx.request.header('dpop'));
+            noStore(ctx);
+            return ctx.response.json(body);
+        }
+        catch (error) {
+            if (error instanceof PoppyError)
+                return oauthError(ctx, error);
+            throw error;
+        }
+    }
+    async deviceAuthorization(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy)
+            return;
+        try {
+            const body = await poppy.deviceAuthorization(form(ctx));
+            noStore(ctx);
+            return ctx.response.json(body);
+        }
+        catch (error) {
+            if (error instanceof PoppyError)
+                return oauthError(ctx, error);
+            throw error;
+        }
+    }
+    /** RFC 7009: 200 também para token desconhecido. */
+    async revoke(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy)
+            return;
+        try {
+            await poppy.revoke(form(ctx));
+            noStore(ctx);
+            return ctx.response.status(200).send('');
+        }
+        catch (error) {
+            if (error instanceof PoppyError)
+                return oauthError(ctx, error);
+            throw error;
+        }
+    }
+    /** `POST auth.mediated.endpoint` (§4.7) — com o Session Token (DPoP). */
+    async mediatedStart(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy?.cfg.signIn.mediated)
+            return poppy ? ctx.response.notFound() : undefined;
+        const auth = await poppy.verifyAccess({
+            method: ctx.request.method(),
+            url: publicRequestUrl(ctx, poppy),
+            headers: ctx.request.headers(),
+        });
+        if (!auth.ok) {
+            const { ok: _ok, ...rest } = auth;
+            return writePoppyAuthError(ctx, { ok: false, ...rest });
+        }
+        try {
+            const body = await poppy.mediatedStart(auth.principal, auth.jkt, ctx.request.body(), ctx);
+            noStore(ctx);
+            return ctx.response.json(body);
+        }
+        catch (error) {
+            if (error instanceof PoppyError)
+                return oauthError(ctx, error);
+            throw error;
+        }
+    }
+    /** `POST {mediated}/{sign_in_id}` (§4.7). */
+    async mediatedCode(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy?.cfg.signIn.mediated)
+            return poppy ? ctx.response.notFound() : undefined;
+        const auth = await poppy.verifyAccess({
+            method: ctx.request.method(),
+            url: publicRequestUrl(ctx, poppy),
+            headers: ctx.request.headers(),
+        });
+        if (!auth.ok) {
+            const { ok: _ok, ...rest } = auth;
+            return writePoppyAuthError(ctx, { ok: false, ...rest });
+        }
+        try {
+            const body = await poppy.mediatedCode(auth.principal, auth.jkt, String(ctx.request.param('id') ?? ''), ctx.request.body());
+            noStore(ctx);
+            if (!body) {
+                return ctx.response
+                    .status(404)
+                    .json({ error: 'invalid_request', error_description: 'Unknown sign_in_id' });
+            }
+            return ctx.response.json(body);
+        }
+        catch (error) {
+            if (error instanceof PoppyError)
+                return oauthError(ctx, error);
+            throw error;
+        }
+    }
+    /**
+     * `POST web.browser_session_endpoint` (§5): asserção no corpo → cookie do app
+     * para a Session e 303 para `return_to`; qualquer falha → 400, sem cookie.
+     */
+    async browserSession(ctx) {
+        const poppy = await poppyOr404(ctx);
+        if (!poppy?.cfg.web?.browserSession)
+            return poppy ? ctx.response.notFound() : undefined;
+        noStore(ctx);
+        // A asserção vai NO CORPO, nunca na URL (§5).
+        if (ctx.request.qs().assertion !== undefined)
+            return badBrowserRequest(ctx);
+        let result;
+        try {
+            result = await poppy.verifyBrowserAssertion(ctx.request.input('assertion'), new URL(publicRequestUrl(ctx, poppy)).origin);
+        }
+        catch (error) {
+            if (error instanceof PoppyError)
+                return badBrowserRequest(ctx);
+            throw error;
+        }
+        await loginPoppyBrowser(ctx, result);
+        ctx.response.header('Location', result.returnTo);
+        return ctx.response.status(303).send('');
+    }
+}
+function badBrowserRequest(ctx) {
+    ctx.response.header('Content-Type', 'text/html; charset=utf-8');
+    return ctx.response
+        .status(400)
+        .send('<!doctype html><html><head><meta charset="utf-8"><title>Bad request</title></head><body><h1>Invalid browser session request</h1></body></html>');
+}

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

@@ -10,6 +10,13 @@ export interface AuthkitCsrfOptions {
      * consentimento (`{prefix}/consent`) continua protegida.
      */
     personalAgentsPrefix?: string | false;
+    /**
+     * Prefixo do Poppy: isenta token/revoke/device authorization, o Mediated
+     * Sign-In e a sessão de navegador (POST cross-site autenticado pela asserção).
+     * Default: o do config. As telas `{prefix}/oauth/authorize` e `{prefix}/device`
+     * continuam protegidas. `false` desliga.
+     */
+    poppyPrefix?: string | false;
 }
 /**
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF

package/build/src/host/csrf.js

@@ -16,6 +16,7 @@
  * ```
  */
 import { normalizePersonalAgentsPrefix } from '../agents/config.js';
+import { normalizePoppyPrefix } from '../agents/poppy/config.js';
 import { getAuthHostConfig } from './auth_host_config.js';
 /**
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
@@ -33,8 +34,22 @@ export function authkitCsrfExceptions(url, options = {}) {
             ? normalizePersonalAgentsPrefix(options.personalAgentsPrefix)
             : getAuthHostConfig()?.personalAgents?.prefix;
     const agentsOAuth = agentsPrefix ? `${agentsPrefix}/oauth/` : null;
+    const poppyPrefix = options.poppyPrefix === false
+        ? undefined
+        : options.poppyPrefix !== undefined
+            ? normalizePoppyPrefix(options.poppyPrefix)
+            : getAuthHostConfig()?.personalAgents?.poppyPrefix;
+    const path = url.split('?')[0];
+    const poppyExempt = !!poppyPrefix &&
+        (path === `${poppyPrefix}/oauth/token` ||
+            path === `${poppyPrefix}/oauth/revoke` ||
+            path === `${poppyPrefix}/oauth/device` ||
+            path === `${poppyPrefix}/sign-in` ||
+            path.startsWith(`${poppyPrefix}/sign-in/`) ||
+            path === `${poppyPrefix}/browser-session`);
     return (url.includes(mountPath) ||
         url.includes('/authkit/pat') ||
         (backchannel !== null && url === backchannel) ||
-        (agentsOAuth !== null && url.startsWith(agentsOAuth)));
+        (agentsOAuth !== null && url.startsWith(agentsOAuth)) ||
+        poppyExempt);
 }

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

@@ -204,6 +204,8 @@ export declare const DEFAULT_MESSAGES: {
     'agents.done.revoke_hint': string;
     'agents.done.expired_title': string;
     'agents.done.expired_body': string;
+    'agents.done.invalid_title': string;
+    'agents.done.invalid_body': string;
     'account.apps.not_supported': string;
     'account.orgs.page_title': string;
     'account.orgs.title': string;
@@ -956,6 +958,8 @@ export declare const PT_BR_MESSAGES: {
     'agents.done.revoke_hint': string;
     'agents.done.expired_title': string;
     'agents.done.expired_body': string;
+    'agents.done.invalid_title': string;
+    'agents.done.invalid_body': string;
     'account.apps.not_supported': string;
     'account.orgs.page_title': string;
     'account.orgs.title': string;

package/build/src/host/i18n.js

@@ -212,6 +212,8 @@ export const DEFAULT_MESSAGES = {
     'agents.done.revoke_hint': 'To revoke this access later, go to the apps page of your account.',
     'agents.done.expired_title': 'Request expired',
     'agents.done.expired_body': 'This request is no longer valid. Ask your assistant to start again.',
+    'agents.done.invalid_title': 'Invalid request',
+    'agents.done.invalid_body': 'This sign-in link is not valid. Go back to your assistant and start again.',
     'account.apps.not_supported': 'The configured OIDC adapter does not support enumeration — listing apps is unavailable.',
     // Console de conta — organizations (account/orgs).
     'account.orgs.page_title': 'My Organizations',
@@ -1052,6 +1054,8 @@ export const PT_BR_MESSAGES = {
     'agents.done.revoke_hint': 'Para revogar este acesso depois, vá à página de apps da sua conta.',
     'agents.done.expired_title': 'Pedido expirado',
     'agents.done.expired_body': 'Este pedido não vale mais. Peça ao seu assistente para começar de novo.',
+    'agents.done.invalid_title': 'Pedido inválido',
+    'agents.done.invalid_body': 'Este link de acesso não é válido. Volte ao seu assistente e comece de novo.',
     'account.apps.not_supported': 'O adapter OIDC configurado não suporta enumeração — a listagem de apps fica indisponível.',
     // Console de conta — organizations (account/orgs).
     'account.orgs.page_title': 'Minhas Organizações',

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

@@ -0,0 +1,9 @@
+/**
+ * Session key que marca a sessão do navegador de um personal agent Poppy (§5):
+ * `{ sessionId, clientId, userId }`. Import-free (o barrel a reexporta — ver
+ * `account_session_key.ts`).
+ *
+ * Uma sessão marcada é do AGENTE, não do usuário: o console de conta, o admin e
+ * as telas de consentimento a recusam.
+ */
+export declare const POPPY_WEB_SESSION_KEY = "authkit_poppy_session";

package/build/src/host/poppy_session_key.js

@@ -0,0 +1,9 @@
+/**
+ * Session key que marca a sessão do navegador de um personal agent Poppy (§5):
+ * `{ sessionId, clientId, userId }`. Import-free (o barrel a reexporta — ver
+ * `account_session_key.ts`).
+ *
+ * Uma sessão marcada é do AGENTE, não do usuário: o console de conta, o admin e
+ * as telas de consentimento a recusam.
+ */
+export const POPPY_WEB_SESSION_KEY = 'authkit_poppy_session';

package/build/src/host/register_auth_host.js

@@ -8,6 +8,7 @@ import { adminApiGuard } from './admin_api/admin_api_guard.js';
 import { normalizeAdminApiPrefix, normalizeAdminPrefix, setAdminApiPrefix, setAdminPrefix, } from './admin_prefix.js';
 import { getAuthHostConfig, markAuthHostAutoMounted, wasAuthHostAutoMounted, } from './auth_host_config.js';
 import { ensureConsoleSession } from './idp_session_bridge.js';
+import { POPPY_WEB_SESSION_KEY } from './poppy_session_key.js';
 import { createAuthThrottles } from './rate_limit.js';
 import { redirectExact } from './redirect_exact.js';
 import { requestPathWithQuery } from './request_url.js';
@@ -113,7 +114,16 @@ function buildLoginRedirect(ctx, extra) {
  * classe NÃO era aplicada em runtime num grupo, deixando /account/tokens e
  * /account/mfa acessíveis sem sessão.
  */
+/** A sessão é do navegador de um personal agent Poppy (§5)? */
+function isPoppyBrowser(ctx) {
+    const marker = ctx.session?.get?.(POPPY_WEB_SESSION_KEY);
+    return typeof marker === 'object' && marker !== null && typeof marker.sessionId === 'string';
+}
 const accountGuard = async (ctx, next) => {
+    // O navegador de um personal agent Poppy (§5) não entra no console de conta nem
+    // nas telas de consentimento: a sessão é do agente, não do usuário.
+    if (isPoppyBrowser(ctx))
+        return ctx.response.status(403).send('');
     // Sessão do console — ou, com `accountSession.acceptIdpSession`, a do IdP (SSO).
     if (!(await ensureConsoleSession(ctx))) {
         return redirectExact(ctx.response, buildLoginRedirect(ctx));
@@ -145,6 +155,8 @@ export const adminGuard = async (ctx, next) => {
     if (!cfg.admin.enabled) {
         return ctx.response.notFound();
     }
+    if (isPoppyBrowser(ctx))
+        return ctx.response.status(403).send('');
     // Com `accountSession.acceptIdpSession`, a sessão do IdP também abre o console.
     await ensureConsoleSession(ctx);
     const accountId = ctx.session?.get(ACCOUNT_SESSION_KEY);
@@ -187,6 +199,8 @@ const C = {
     accountConfirm: () => import('./controllers/account_confirm_controller.js'),
     agentOAuth: () => import('./controllers/agent_oauth_controller.js'),
     agentConsent: () => import('./controllers/agent_consent_controller.js'),
+    poppy: () => import('./controllers/poppy_controller.js'),
+    poppyConsent: () => import('./controllers/poppy_consent_controller.js'),
     webauthnAsset: () => import('./controllers/webauthn_asset_controller.js'),
     logoutAsset: () => import('./controllers/logout_asset_controller.js'),
     passkeyAutofillAsset: () => import('./controllers/passkey_autofill_asset_controller.js'),
@@ -206,6 +220,7 @@ const C = {
     consoleSettings: () => import('./admin_console/console_settings_controller.js'),
     consoleKeys: () => import('./admin_console/console_keys_controller.js'),
     consoleImpersonation: () => import('./admin_console/console_impersonation_controller.js'),
+    consolePersonalAgents: () => import('./admin_console/console_personal_agents_controller.js'),
     apiUsers: () => import('./admin_api/api_users_controller.js'),
     apiClients: () => import('./admin_api/api_clients_controller.js'),
     apiMisc: () => import('./admin_api/api_misc_controller.js'),
@@ -508,6 +523,52 @@ export function registerAuthHost(router, opts = {}) {
         })
             .use([accountGuard]);
     }
+    // Personal Agent Protocol (Poppy): descoberta, authorization server (token,
+    // revogação, device authorization), Mediated Sign-In e sessão de navegador —
+    // server-to-server ou POST cross-site do navegador do agente (sem CSRF, ver
+    // `authkitCsrfExceptions`). As telas do usuário (authorize/device) exigem a
+    // sessão de conta e mantêm o CSRF.
+    const poppyPrefix = hostCfg?.personalAgents?.poppyPrefix;
+    if (poppyPrefix) {
+        // Nomes explícitos: o Router nomeia pela dupla controller.método, e as duas URLs da metadata
+        // (RFC 8414 na raiz e debaixo do issuer) usam o mesmo — "poppy.metadata already exists" no boot.
+        router.get('/.well-known/poppy.json', [C.poppy, 'discovery']).as('authkit.poppy.discovery');
+        router
+            .get(`/.well-known/oauth-authorization-server${poppyPrefix}`, [C.poppy, 'metadata'])
+            .as('authkit.poppy.metadata');
+        router
+            .get(`${poppyPrefix}/.well-known/oauth-authorization-server`, [C.poppy, 'metadata'])
+            .as('authkit.poppy.metadata_under_issuer');
+        router.post(`${poppyPrefix}/oauth/token`, [C.poppy, 'token']).as('authkit.poppy.token');
+        router.post(`${poppyPrefix}/oauth/revoke`, [C.poppy, 'revoke']).as('authkit.poppy.revoke');
+        router
+            .post(`${poppyPrefix}/oauth/device`, [C.poppy, 'deviceAuthorization'])
+            .as('authkit.poppy.device_authorization');
+        // Credenciais e códigos de uso único: throttle por IP (§4.7 exige rate limit).
+        withLogin(router.post(`${poppyPrefix}/sign-in`, [C.poppy, 'mediatedStart']).as('authkit.poppy.sign_in'));
+        withOtpLogin(router
+            .post(`${poppyPrefix}/sign-in/:id`, [C.poppy, 'mediatedCode'])
+            .as('authkit.poppy.sign_in_code'));
+        router
+            .post(`${poppyPrefix}/browser-session`, [C.poppy, 'browserSession'])
+            .as('authkit.poppy.browser_session');
+        router
+            .group(() => {
+            router
+                .get(`${poppyPrefix}/oauth/authorize`, [C.poppyConsent, 'authorize'])
+                .as('authkit.poppy.authorize');
+            router
+                .post(`${poppyPrefix}/oauth/authorize`, [C.poppyConsent, 'decideAuthorization'])
+                .as('authkit.poppy.authorize_decide');
+            withOtpLogin(router
+                .get(`${poppyPrefix}/device`, [C.poppyConsent, 'device'])
+                .as('authkit.poppy.device'));
+            withOtpLogin(router
+                .post(`${poppyPrefix}/device`, [C.poppyConsent, 'decideDevice'])
+                .as('authkit.poppy.device_decide'));
+        })
+            .use([accountGuard]);
+    }
     // Paths do console de conta (configuráveis/localizáveis via `accountRoutes`).
     // As TELAS vêm de `accountPath(key)` (prefixo + segmento configurável); os
     // action-subpaths concatenados (`/password`, `/enroll`, ...) são FIXOS —
@@ -855,6 +916,21 @@ export function registerAuthHost(router, opts = {}) {
             // Chave de assinatura managed (status + rotação ao vivo).
             router.get(`${ap}/api/keys`, [C.consoleKeys, 'status']);
             router.post(`${ap}/api/keys/rotate`, [C.consoleKeys, 'rotate']);
+            // Personal agents (capability-gated: 404 sem `personalAgents` ou sem banco).
+            router.get(`${ap}/api/personal-agents`, [C.consolePersonalAgents, 'index']);
+            router.get(`${ap}/api/personal-agents/connections`, [
+                C.consolePersonalAgents,
+                'connections',
+            ]);
+            router.post(`${ap}/api/personal-agents/connections/:grantId/revoke`, [
+                C.consolePersonalAgents,
+                'revokeConnection',
+            ]);
+            router.post(`${ap}/api/personal-agents/registry`, [C.consolePersonalAgents, 'upsert']);
+            router.delete(`${ap}/api/personal-agents/registry/:id`, [
+                C.consolePersonalAgents,
+                'destroy',
+            ]);
             // Impersonation (capability-gated: 404 quando desabilitado ou sem client).
             router.get(`${ap}/api/impersonation/:userId`, [C.consoleImpersonation, 'handle']);
             // ─── Shell HTML — POR ÚLTIMO (catch-all) ──────────────────────────────