@adonis-agora/authkit-server 0.75.0 → 0.76.0

package/build/src/host/register_auth_host.js

@@ -9,6 +9,8 @@ import { normalizeAdminApiPrefix, normalizeAdminPrefix, setAdminApiPrefix, setAd
 import { getAuthHostConfig, markAuthHostAutoMounted, wasAuthHostAutoMounted, } from './auth_host_config.js';
 import { ensureConsoleSession } from './idp_session_bridge.js';
 import { createAuthThrottles } from './rate_limit.js';
+import { redirectExact } from './redirect_exact.js';
+import { requestPathWithQuery } from './request_url.js';
 import { resolveRuntimeSettings } from './runtime_settings.js';
 import { resolveEffectiveSessionPolicy } from './runtime_toggles.js';
 import { magicLink as sudoMagicLink } from './sudo/methods/magic_link.js';
@@ -90,9 +92,7 @@ function buildLoginRedirect(ctx, extra) {
     // host que desmontou a tela de login (`account: { login: false }`) aponta para
     // a própria rota de login dele (ex.: `/login`). Ver `account_login_url.ts`.
     const loginUrl = getAccountLoginUrl();
-    const url = ctx.request?.url?.() ?? '';
-    const qs = ctx.request?.parsedUrl?.search ?? '';
-    const dest = qs ? `${url}${qs}` : url;
+    const dest = requestPathWithQuery(ctx.request);
     // Só inclui return_to quando há um caminho real (não vazio, não é o próprio login).
     if (dest && dest !== '/' && !dest.startsWith(loginUrl)) {
         const encoded = encodeURIComponent(dest);
@@ -116,12 +116,12 @@ function buildLoginRedirect(ctx, extra) {
 const accountGuard = async (ctx, next) => {
     // Sessão do console — ou, com `accountSession.acceptIdpSession`, a do IdP (SSO).
     if (!(await ensureConsoleSession(ctx))) {
-        return ctx.response.redirect(buildLoginRedirect(ctx));
+        return redirectExact(ctx.response, buildLoginRedirect(ctx));
     }
     // Idle timeout: encerra e redireciona com query param de motivo.
     const idleExpired = await checkAndRefreshIdle(ctx);
     if (idleExpired) {
-        return ctx.response.redirect(buildLoginRedirect(ctx, 'reason=idle'));
+        return redirectExact(ctx.response, buildLoginRedirect(ctx, 'reason=idle'));
     }
     return next();
 };
@@ -150,12 +150,12 @@ export const adminGuard = async (ctx, next) => {
     const accountId = ctx.session?.get(ACCOUNT_SESSION_KEY);
     if (!accountId) {
         // `/account/login` é sempre o login da conta — NÃO muda com o prefixo admin.
-        return ctx.response.redirect(buildLoginRedirect(ctx));
+        return redirectExact(ctx.response, buildLoginRedirect(ctx));
     }
     // Idle timeout: também protege o console admin.
     const idleExpired = await checkAndRefreshIdle(ctx);
     if (idleExpired) {
-        return ctx.response.redirect(buildLoginRedirect(ctx, 'reason=idle'));
+        return redirectExact(ctx.response, buildLoginRedirect(ctx, 'reason=idle'));
     }
     const allowed = cfg.admin.roles;
     const account = await cfg.accountStore.findById(accountId);
@@ -173,6 +173,7 @@ export const adminGuard = async (ctx, next) => {
 };
 const C = {
     oidc: () => import('../controllers/oidc_callback_controller.js'),
+    authorizationServerMetadata: () => import('../controllers/authorization_server_metadata_controller.js'),
     interaction: () => import('./controllers/interaction_controller.js'),
     registration: () => import('./controllers/registration_controller.js'),
     social: () => import('./controllers/social_controller.js'),
@@ -184,6 +185,8 @@ const C = {
     accountMfa: () => import('./controllers/account_mfa_controller.js'),
     accountOrgs: () => import('./controllers/account_orgs_controller.js'),
     accountConfirm: () => import('./controllers/account_confirm_controller.js'),
+    agentOAuth: () => import('./controllers/agent_oauth_controller.js'),
+    agentConsent: () => import('./controllers/agent_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'),
@@ -421,6 +424,15 @@ export function registerAuthHost(router, opts = {}) {
         .get('/authkit/assets/webauthn_confirm.js', [C.webauthnConfirmAsset])
         .as('authkit.assets.webauthnConfirm');
     router.get('/authkit/assets/submit_lock.js', [C.submitLockAsset]).as('authkit.assets.submitLock');
+    // Metadata do servidor de autorização no caminho da RFC 8414 §3.1 (issuer com path: os
+    // clientes MCP procuram `/.well-known/oauth-authorization-server/oidc` antes do OIDC Discovery).
+    // O issuer termina no mountPath, então o mount É o path do issuer.
+    const issuerPath = mount.replace(/\/+$/, '');
+    if (issuerPath !== '') {
+        router
+            .get(`/.well-known/oauth-authorization-server${issuerPath}`, [C.authorizationServerMetadata])
+            .as('authkit.oauth_authorization_server');
+    }
     // Provider OIDC (wildcard + root) — o que registerOidcRoutes fazia.
     router.any(`${mount}/*`, [C.oidc]).as('authkit.oidc.wildcard');
     router.any(mount, [C.oidc]).as('authkit.oidc.root');
@@ -463,6 +475,27 @@ export function registerAuthHost(router, opts = {}) {
     }
     // PAT introspection (server-to-server).
     withIntrospection(router.post('/authkit/pat/introspect', [C.patIntrospection, 'handle']));
+    // Personal agents (PACT §5): authorization server de delegação. Os endpoints
+    // OAuth são server-to-server (o agente se autentica pelo JWT dele, sem
+    // sessão); a tela de consentimento exige a sessão de conta — sem ela o
+    // `accountGuard` manda para o login com `return_to`, e o usuário volta com o
+    // `user_code`. Montado só quando `personalAgents` está no config.
+    const agentsPrefix = hostCfg?.personalAgents?.prefix;
+    if (agentsPrefix) {
+        const oauth = `${agentsPrefix}/oauth`;
+        router.get(`${oauth}/.well-known/oauth-authorization-server`, [C.agentOAuth, 'metadata']);
+        router.get(`${oauth}/jwks.json`, [C.agentOAuth, 'jwks']);
+        router.post(`${oauth}/device_authorization`, [C.agentOAuth, 'deviceAuthorization']);
+        router.post(`${oauth}/token`, [C.agentOAuth, 'token']);
+        // Throttle de código (bucket do OTP, por IP): o `user_code` tem 8 letras e
+        // a RFC 8628 §5.1 conta com rate limit para não ser adivinhável.
+        router
+            .group(() => {
+            withOtpLogin(router.get(`${agentsPrefix}/consent`, [C.agentConsent, 'show']));
+            withOtpLogin(router.post(`${agentsPrefix}/consent`, [C.agentConsent, '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 —
@@ -531,6 +564,9 @@ export function registerAuthHost(router, opts = {}) {
         if (mountApps) {
             router.get(appsPath, [C.accountApps, 'index']);
             router.post(`${appsPath}/:clientId/revoke`, [C.accountApps, 'revoke']);
+            if (agentsPrefix) {
+                router.post(`${appsPath}/agents/:grantId/revoke`, [C.accountApps, 'revokeAgent']);
+            }
         }
         // MFA — TOTP + passkeys (tela `mfa`).
         if (mountMfa) {
@@ -642,6 +678,11 @@ export function registerAuthHost(router, opts = {}) {
         // Apps (grants).
         router.get(`${apiBase}/apps`, [C.accountApi, 'listApps']);
         router.delete(`${apiBase}/apps/:clientId`, [C.accountApi, 'revokeApp']);
+        // Personal agents com delegação (PACT).
+        if (agentsPrefix) {
+            router.get(`${apiBase}/agents`, [C.accountApi, 'listAgents']);
+            router.delete(`${apiBase}/agents/:id`, [C.accountApi, 'revokeAgent']);
+        }
         // MFA + passkeys.
         router.get(`${apiBase}/mfa`, [C.accountApi, 'mfaStatus']);
         // Login methods preference (self-service, por usuário).

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

@@ -0,0 +1,10 @@
+/**
+ * Path + query string da request atual, para montar um `return_to`.
+ *
+ * `request.url(true)` é a API do AdonisJS que inclui a query. O código antigo lia
+ * `request.parsedUrl.search`, que o AdonisJS 7 não tem mais (o `parsedUrl` virou
+ * `{ pathname, query }`) — todo redirect para o login perdia a query em silêncio,
+ * e o usuário voltava para a página sem os parâmetros (um `user_code`, uma
+ * paginação). O `search` fica como fallback para hosts/dublês que ainda o expõem.
+ */
+export declare function requestPathWithQuery(request: any): string;

package/build/src/host/request_url.js

@@ -0,0 +1,17 @@
+/**
+ * Path + query string da request atual, para montar um `return_to`.
+ *
+ * `request.url(true)` é a API do AdonisJS que inclui a query. O código antigo lia
+ * `request.parsedUrl.search`, que o AdonisJS 7 não tem mais (o `parsedUrl` virou
+ * `{ pathname, query }`) — todo redirect para o login perdia a query em silêncio,
+ * e o usuário voltava para a página sem os parâmetros (um `user_code`, uma
+ * paginação). O `search` fica como fallback para hosts/dublês que ainda o expõem.
+ */
+export function requestPathWithQuery(request) {
+    const withQuery = request?.url?.(true) ?? '';
+    if (withQuery.includes('?'))
+        return withQuery;
+    const parsed = request?.parsedUrl;
+    const legacy = parsed?.search ?? (parsed?.query ? `?${parsed.query}` : '');
+    return `${withQuery}${legacy}`;
+}

package/build/src/host/sudo/methods/magic_link.js

@@ -2,6 +2,7 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { accountPath } from '../../account_paths.js';
 import { sendSudoLinkEmail } from '../../default_mailer.js';
 import { translate } from '../../i18n.js';
+import { redirectExact } from '../../redirect_exact.js';
 import { isSudoMethodEnabled } from '../runtime.js';
 /** Token de sudo pendente, guardado na sessão que o pediu. */
 export const SUDO_LINK_SESSION_KEY = 'authkit_sudo_link';
@@ -170,7 +171,7 @@ export function magicLink() {
                 // `translate(...)` em `confirmError`, e a tela leria dois formatos
                 // diferentes se este aqui mandasse a chave.
                 ctx.session.flash('confirmNotice', translate(c.cfg.messages, 'account.confirm.magic_link_sent'));
-                return ctx.response.redirect(`${accountPath('confirm')}${qs}`);
+                return redirectExact(ctx.response, `${accountPath('confirm')}${qs}`);
             });
             router.get(`${accountPath('confirm')}/magic-link/:token`, async (ctx) => {
                 const c = await h.contextFrom(ctx);

package/build/src/host/sudo/runtime.js

@@ -3,6 +3,7 @@ import { accountPath } from '../account_paths.js';
 import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
 import { validateReturnTo } from '../controllers/account_session_controller.js';
 import { translate } from '../i18n.js';
+import { redirectExact } from '../redirect_exact.js';
 import { markSudo } from '../sudo_mode.js';
 /** Último método usado com sucesso — só ordena a tela, não restringe nada. */
 export const LAST_METHOD_SESSION_KEY = 'authkit_sudo_last_method';
@@ -362,7 +363,7 @@ export async function completeSudo(c, methodId) {
         ip: c.ctx.request.ip?.() ?? null,
         metadata: { method: methodId },
     });
-    return c.ctx.response.redirect(c.returnTo ?? accountHome(c.cfg));
+    return redirectExact(c.ctx.response, c.returnTo ?? accountHome(c.cfg));
 }
 /**
  * Falha de confirmação: flash + volta pro /account/confirm preservando o
@@ -372,7 +373,7 @@ export async function completeSudo(c, methodId) {
 export async function fail(c, messageKey) {
     c.ctx.session.flash('confirmError', translate(c.cfg.messages, messageKey));
     const qs = c.returnTo ? `?return_to=${encodeURIComponent(c.returnTo)}` : '';
-    return c.ctx.response.redirect(`${accountPath('confirm')}${qs}`);
+    return redirectExact(c.ctx.response, `${accountPath('confirm')}${qs}`);
 }
 /**
  * Filtra os métodos disponíveis para esta conta e promove o último usado.

package/build/src/host/sudo_mode.js

@@ -15,6 +15,8 @@
  */
 import { accountPath } from './account_paths.js';
 import { ACCOUNT_SESSION_KEY } from './account_session_key.js';
+import { redirectExact } from './redirect_exact.js';
+import { requestPathWithQuery } from './request_url.js';
 import { SETTING_KEYS } from './runtime_toggles.js';
 export const SUDO_MODE_DEFAULTS = {
     enabled: true,
@@ -235,11 +237,9 @@ export async function requireSudo(ctx, settings) {
     if (await isSudoSatisfied(ctx, settings))
         return true;
     // Fora da graça: redireciona para confirmação.
-    const rawUrl = ctx.request.url?.() ?? '';
-    const qs = ctx.request.parsedUrl?.search ?? '';
-    const dest = qs ? `${rawUrl}${qs}` : rawUrl;
+    const dest = requestPathWithQuery(ctx.request);
     const returnTo = dest && dest !== '/' && !dest.startsWith(accountPath('confirm'))
         ? `?return_to=${encodeURIComponent(dest)}`
         : '';
-    return ctx.response.redirect(`${accountPath('confirm')}${returnTo}`);
+    return redirectExact(ctx.response, `${accountPath('confirm')}${returnTo}`);
 }

package/build/src/mcp/mcp_oauth.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Login OAuth de clientes MCP (Claude Code, Claude, ChatGPT, VS Code, Cursor) — a autorização da
+ * spec do MCP: OAuth 2.1 com PKCE, registro dinâmico (RFC 7591), metadata do servidor de
+ * autorização (RFC 8414) e o token amarrado ao servidor MCP pelo `resource` (RFC 8707).
+ *
+ * `mcp: true` na config liga tudo de uma vez:
+ *   - o registro dinâmico ABERTO, restrito aos redirects dos clientes MCP conhecidos
+ *     ({@link MCP_CLIENT_REDIRECTS}) — loopback para os de linha de comando;
+ *   - o refresh token desses clientes: o registro pede `offline_access` e o authorize ganha
+ *     `prompt=consent` (OIDC Core §11), então a pessoa consente uma vez e o cliente não precisa
+ *     logar de novo a cada hora;
+ *   - os `resource` dos servidores MCP: os de `mcp.resources` e os REGISTRADOS em runtime
+ *     ({@link registerOAuthResource}) — é por aí que o MCP do `@adonis-agora/agent` se anuncia
+ *     sem o app listar a URL dele aqui.
+ *
+ * Os clientes registrados pelo `/reg` se distinguem pelo `client_id_issued_at`, que só o registro
+ * dinâmico grava: clients estáticos ou criados pelo console/CLI não mudam de comportamento.
+ */
+import type { RedirectUriPolicy, ResolvedRedirectUriPolicy } from '../provider/registration_policy.js';
+/** Callbacks dos clientes MCP conhecidos. Loopback (Claude Code, CLIs) já entra pela política. */
+export declare const MCP_CLIENT_REDIRECTS: Required<RedirectUriPolicy>;
+/** Escopos de um token de servidor MCP: identidade + refresh. */
+export declare const MCP_RESOURCE_SCOPES: string[];
+export interface McpOAuthConfigInput {
+    /**
+     * Redirects aceitos ALÉM dos clientes MCP conhecidos — ex.: o callback de um cliente próprio.
+     * Somados a {@link MCP_CLIENT_REDIRECTS}.
+     */
+    redirectUris?: RedirectUriPolicy;
+    /**
+     * URLs dos servidores MCP para os quais este IdP emite tokens, além dos que se registram em
+     * runtime ({@link registerOAuthResource}). Ex.: `['https://app.example.com/mcp']`.
+     */
+    resources?: string[];
+}
+export interface ResolvedMcpOAuthConfig {
+    enabled: boolean;
+    redirectUriPolicy: ResolvedRedirectUriPolicy;
+    resources: string[];
+}
+export declare function resolveMcpOAuth(input?: boolean | McpOAuthConfigInput): ResolvedMcpOAuthConfig;
+/**
+ * Um servidor protegido (RFC 9728) que aceita tokens deste IdP. `url` é o `resource` exato; sem
+ * ela, `path` casa com qualquer `resource` na origem do issuer (quem registra no boot nem sempre
+ * sabe a URL pública).
+ */
+export interface OAuthResourceRegistration {
+    url?: string;
+    path?: string;
+    /** Escopos do token para este resource. Default: {@link MCP_RESOURCE_SCOPES}. */
+    scopes?: string[];
+}
+export declare function registerOAuthResource(resource: OAuthResourceRegistration): void;
+export declare function registeredOAuthResources(): readonly OAuthResourceRegistration[];
+/**
+ * O resource MCP que `indicator` nomeia, ou `null`. Casa com `mcp.resources`, com uma URL
+ * registrada, ou com um `path` registrado na origem do issuer. Barra final tolerada.
+ */
+export declare function findMcpResource(indicator: string, issuer: string, config: ResolvedMcpOAuthConfig): {
+    audience: string;
+    scopes: string[];
+} | null;
+/**
+ * Registro de um cliente MCP: quem pede `refresh_token` ganha `openid offline_access` no escopo
+ * registrado, senão o provider recusaria pedi-los no authorize.
+ */
+export declare function mcpClientRegistration(metadata: Record<string, unknown>): Record<string, unknown>;
+/**
+ * `scope`/`prompt` do authorize de um cliente MCP para que saia um refresh token: `offline_access`
+ * no escopo e `consent` no prompt (sem ele o provider descarta o `offline_access`). `null` quando
+ * já estão lá. `prompt=none` pede "sem interação", o contrário de consentir: sai.
+ */
+export declare function withOfflineAccess(params: Record<string, unknown>): {
+    scope: string;
+    prompt: string;
+} | null;
+/**
+ * Middleware do provider (Koa) que aplica {@link withOfflineAccess} ao `GET /auth` de um client
+ * registrado dinamicamente que tem o grant `refresh_token`.
+ */
+export declare function mcpAuthorizeMiddleware(provider: {
+    Client: {
+        find(id: string): Promise<any>;
+    };
+}): (ctx: any, next: () => Promise<void>) => Promise<void>;

package/build/src/mcp/mcp_oauth.js

@@ -0,0 +1,154 @@
+import { resolveRedirectUriPolicy } from '../provider/registration_policy.js';
+/** Callbacks dos clientes MCP conhecidos. Loopback (Claude Code, CLIs) já entra pela política. */
+export const MCP_CLIENT_REDIRECTS = {
+    loopback: true,
+    exact: [
+        'https://claude.ai/api/mcp/auth_callback',
+        'https://claude.com/api/mcp/auth_callback',
+        'https://chatgpt.com/connector_platform_oauth_redirect',
+        'https://vscode.dev/redirect',
+        'https://insiders.vscode.dev/redirect',
+    ],
+    appSchemes: ['cursor', 'vscode', 'vscode-insiders'],
+    anyHttps: false,
+};
+/** Escopos de um token de servidor MCP: identidade + refresh. */
+export const MCP_RESOURCE_SCOPES = ['openid', 'profile', 'email', 'offline_access'];
+export function resolveMcpOAuth(input) {
+    const options = typeof input === 'object' ? input : {};
+    const extra = options.redirectUris ?? {};
+    return {
+        enabled: input === true || typeof input === 'object',
+        redirectUriPolicy: resolveRedirectUriPolicy({
+            loopback: extra.loopback ?? MCP_CLIENT_REDIRECTS.loopback,
+            exact: [...new Set([...MCP_CLIENT_REDIRECTS.exact, ...(extra.exact ?? [])])],
+            appSchemes: [...new Set([...MCP_CLIENT_REDIRECTS.appSchemes, ...(extra.appSchemes ?? [])])],
+            anyHttps: extra.anyHttps ?? MCP_CLIENT_REDIRECTS.anyHttps,
+        }),
+        resources: [...(options.resources ?? [])],
+    };
+}
+/**
+ * Registro em runtime — um slot global, para que outra lib (o MCP do `@adonis-agora/agent`) se
+ * registre sem importar esta: o contrato é o símbolo, não o módulo.
+ */
+const REGISTRY = Symbol.for('@adonis-agora/oauth:resources');
+function registry() {
+    const slot = globalThis;
+    if (!Array.isArray(slot[REGISTRY]))
+        slot[REGISTRY] = [];
+    return slot[REGISTRY];
+}
+export function registerOAuthResource(resource) {
+    if (!resource.url && !resource.path) {
+        throw new Error('authkit: registerOAuthResource precisa de `url` ou `path`.');
+    }
+    registry().push({ ...resource });
+}
+export function registeredOAuthResources() {
+    return registry();
+}
+const trim = (value) => value.replace(/\/+$/, '');
+function normalizePath(path) {
+    return `/${path.replace(/^\/+|\/+$/g, '')}`;
+}
+/**
+ * O resource MCP que `indicator` nomeia, ou `null`. Casa com `mcp.resources`, com uma URL
+ * registrada, ou com um `path` registrado na origem do issuer. Barra final tolerada.
+ */
+export function findMcpResource(indicator, issuer, config) {
+    if (!config.enabled)
+        return null;
+    let url;
+    try {
+        url = new URL(indicator);
+    }
+    catch {
+        return null;
+    }
+    const wanted = trim(url.href);
+    for (const declared of config.resources) {
+        if (trim(declared) === wanted)
+            return { audience: trim(declared), scopes: MCP_RESOURCE_SCOPES };
+    }
+    const issuerOrigin = new URL(issuer).origin;
+    for (const resource of registeredOAuthResources()) {
+        const scopes = resource.scopes ?? MCP_RESOURCE_SCOPES;
+        if (resource.url && trim(resource.url) === wanted)
+            return { audience: trim(resource.url), scopes };
+        if (resource.path &&
+            url.origin === issuerOrigin &&
+            trim(url.pathname) === normalizePath(resource.path) &&
+            !url.search) {
+            return { audience: wanted, scopes };
+        }
+    }
+    return null;
+}
+/**
+ * Registro de um cliente MCP: quem pede `refresh_token` ganha `openid offline_access` no escopo
+ * registrado, senão o provider recusaria pedi-los no authorize.
+ */
+export function mcpClientRegistration(metadata) {
+    const grants = Array.isArray(metadata.grant_types)
+        ? metadata.grant_types
+        : ['authorization_code'];
+    if (!grants.includes('refresh_token') || typeof metadata.scope !== 'string')
+        return metadata;
+    const scopes = metadata.scope.split(' ').filter(Boolean);
+    for (const needed of ['openid', 'offline_access']) {
+        if (!scopes.includes(needed))
+            scopes.push(needed);
+    }
+    return { ...metadata, scope: scopes.join(' ') };
+}
+/**
+ * `scope`/`prompt` do authorize de um cliente MCP para que saia um refresh token: `offline_access`
+ * no escopo e `consent` no prompt (sem ele o provider descarta o `offline_access`). `null` quando
+ * já estão lá. `prompt=none` pede "sem interação", o contrário de consentir: sai.
+ */
+export function withOfflineAccess(params) {
+    const scopes = String(params.scope ?? '')
+        .split(' ')
+        .filter(Boolean);
+    const prompts = String(params.prompt ?? '')
+        .split(' ')
+        .filter(Boolean);
+    const needsScope = !scopes.includes('offline_access');
+    const needsPrompt = !prompts.includes('consent');
+    if (!needsScope && !needsPrompt)
+        return null;
+    if (!scopes.includes('openid'))
+        scopes.unshift('openid');
+    if (needsScope)
+        scopes.push('offline_access');
+    const prompt = needsPrompt ? [...prompts.filter((p) => p !== 'none'), 'consent'] : prompts;
+    return { scope: scopes.join(' '), prompt: prompt.join(' ') };
+}
+/**
+ * Middleware do provider (Koa) que aplica {@link withOfflineAccess} ao `GET /auth` de um client
+ * registrado dinamicamente que tem o grant `refresh_token`.
+ */
+export function mcpAuthorizeMiddleware(provider) {
+    return async (ctx, next) => {
+        if (ctx.method !== 'GET' || ctx.path !== '/auth')
+            return next();
+        const query = ctx.query;
+        const clientId = typeof query.client_id === 'string' ? query.client_id : '';
+        if (!clientId || (query.response_type !== undefined && query.response_type !== 'code')) {
+            return next();
+        }
+        const client = await provider.Client.find(clientId).catch(() => undefined);
+        const metadata = client?.metadata?.() ?? {};
+        const grants = metadata.grant_types;
+        if (metadata.client_id_issued_at === undefined ||
+            !Array.isArray(grants) ||
+            !grants.includes('refresh_token')) {
+            return next();
+        }
+        const widened = withOfflineAccess(query);
+        if (widened)
+            ctx.query = { ...query, ...widened };
+        return next();
+    };
+}

package/build/src/provider/build_provider.js

@@ -2,6 +2,7 @@ import * as oidc from 'oidc-provider';
 import { pickModelAdapterClass } from '../adapters/factory.js';
 import { normalizeActiveOrg, readActiveOrgFromKoaCtx } from '../host/active_org_cookie.js';
 import { assertClientMetadata } from '../host/client_metadata.js';
+import { findMcpResource, mcpAuthorizeMiddleware } from '../mcp/mcp_oauth.js';
 import { createDeviceSources } from './device_sources.js';
 import { createLogoutSources } from './logout_sources.js';
 import { registrationPolicyMiddleware } from './registration_policy.js';
@@ -77,7 +78,8 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
         const key = declaredResources.find((k) => k.replace(/\/+$/, '') === trimmed);
         return key ? { key, rc: at.resources[key] } : null;
     };
-    const resourceIndicatorFeatures = at.anyJwt || declaredResources.length > 0
+    const mcp = config.mcp;
+    const resourceIndicatorFeatures = at.anyJwt || declaredResources.length > 0 || mcp.enabled
         ? {
             resourceIndicators: {
                 enabled: true,
@@ -94,6 +96,15 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
                 getResourceServerInfo: (_ctx, resourceIndicator, _client) => {
                     const found = findResource(resourceIndicator);
                     const isDefault = at.anyJwt && resourceIndicator === at.audience;
+                    // Servidores MCP (`mcp`): os declarados e os registrados em runtime.
+                    const mcpResource = found || isDefault ? null : findMcpResource(resourceIndicator, config.issuer, mcp);
+                    if (mcpResource) {
+                        return {
+                            scope: mcpResource.scopes.join(' '),
+                            audience: mcpResource.audience,
+                            accessTokenFormat: 'opaque',
+                        };
+                    }
                     if (!found && !isDefault) {
                         throw new oidc.errors.InvalidTarget(`resource indicator not allowed: ${resourceIndicator}`);
                     }
@@ -341,6 +352,9 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
             validate: dynReg.validateRegistration,
         }));
     }
+    // Refresh token dos clientes MCP registrados dinamicamente (ver mcp/mcp_oauth.ts).
+    if (mcp.enabled)
+        provider.use(mcpAuthorizeMiddleware(provider));
     provider.proxy = true;
     return provider;
 }

package/build/src/provider/oidc_service.d.ts

@@ -17,6 +17,14 @@ export declare class OidcService {
     get publicJwks(): {
         keys: Record<string, any>[];
     };
+    /**
+     * @internal JWKS PRIVADO em uso (mesmas chaves do `publicJwks`). Só para quem
+     * assina in-process com o keystore do IdP — tokens de delegação e recibos de
+     * personal agents. Troca junto com o provider numa rotação.
+     */
+    get signingJwks(): {
+        keys: Record<string, any>[];
+    };
     /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */
     readonly mountPath: string;
     readonly recorder: MetricsRecorder;

package/build/src/provider/oidc_service.js

@@ -14,6 +14,7 @@ export class OidcService {
     #callback;
     #interactions;
     #publicJwks;
+    #signingJwks;
     #appKey;
     get provider() {
         return this.#provider;
@@ -32,6 +33,14 @@ export class OidcService {
     get publicJwks() {
         return this.#publicJwks;
     }
+    /**
+     * @internal JWKS PRIVADO em uso (mesmas chaves do `publicJwks`). Só para quem
+     * assina in-process com o keystore do IdP — tokens de delegação e recibos de
+     * personal agents. Troca junto com o provider numa rotação.
+     */
+    get signingJwks() {
+        return this.#signingJwks;
+    }
     /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */
     mountPath;
     recorder;
@@ -216,6 +225,7 @@ export class OidcService {
         this.#callback = callback;
         this.#interactions = interactions;
         this.#publicJwks = toPublicJwks(jwks);
+        this.#signingJwks = jwks;
     }
     /**
      * Recarrega as chaves de assinatura AO VIVO: relê o keystore do cofre e reconstrói

package/build/src/schema/ensure.js

@@ -203,6 +203,98 @@ const TABLES = [
             updated_at: (t) => t.timestamp('updated_at', { useTz: true }).nullable(),
         },
     },
+    /*
+     * As três tabelas de personal agents usam `dateTime(…, precision 3)` e não
+     * `timestamp`: no MySQL o TIMESTAMP sem fração arredonda o `last_polled_at`
+     * (um agente que respeita o `interval` levaria `slow_down`) e, com
+     * `explicit_defaults_for_timestamp=OFF`, o primeiro TIMESTAMP NOT NULL da
+     * tabela ganha `ON UPDATE CURRENT_TIMESTAMP` — marcar um refresh como usado
+     * reescreveria a validade dele. DATETIME não tem nenhum dos dois; no Postgres
+     * vira o mesmo `timestamptz`.
+     */
+    {
+        name: 'auth_agent_device_codes',
+        /**
+         * Pedidos de delegação de personal agents (device flow, RFC 8628). O
+         * `device_code` só existe como hash; o `user_code` é o que o usuário vê.
+         * Linhas expiradas são apagadas no próximo pedido.
+         */
+        create: (t) => {
+            t.string('id').primary();
+            t.string('device_code_hash', 64).notNullable().unique();
+            t.string('user_code', 16).notNullable().unique();
+            t.string('client_id', 2048).notNullable();
+            t.string('agent_sub').notNullable();
+            t.text('requested_scope').notNullable();
+            t.string('status', 16).notNullable();
+            t.string('account_id').nullable();
+            t.string('grant_id').nullable();
+            t.integer('interval_seconds').notNullable();
+            t.dateTime('last_polled_at', { useTz: true, precision: 3 }).nullable();
+            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable().index();
+            t.dateTime('created_at', { useTz: true, precision: 3 }).notNullable();
+        },
+        columns: {
+            device_code_hash: (t) => t.string('device_code_hash', 64),
+            user_code: (t) => t.string('user_code', 16),
+            client_id: (t) => t.string('client_id', 2048),
+            agent_sub: (t) => t.string('agent_sub'),
+            requested_scope: (t) => t.text('requested_scope'),
+            status: (t) => t.string('status', 16),
+            account_id: (t) => t.string('account_id').nullable(),
+            grant_id: (t) => t.string('grant_id').nullable(),
+            interval_seconds: (t) => t.integer('interval_seconds'),
+            last_polled_at: (t) => t.dateTime('last_polled_at', { useTz: true, precision: 3 }).nullable(),
+            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
+            created_at: (t) => t.dateTime('created_at', { useTz: true, precision: 3 }).nullable(),
+        },
+    },
+    {
+        name: 'auth_agent_grants',
+        /**
+         * O que um usuário autorizou um personal agent a fazer na conta dele: um
+         * grant por (conta, agente, usuário do agente); aprovar mais scopes soma.
+         * `revoked_at` preenchido = revogado (os tokens param na próxima request).
+         */
+        create: (t) => {
+            t.string('id').primary();
+            t.string('account_id').notNullable().index();
+            t.string('client_id', 2048).notNullable();
+            t.string('agent_sub').notNullable();
+            t.text('scope').notNullable();
+            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable();
+            t.dateTime('revoked_at', { useTz: true, precision: 3 }).nullable();
+            t.dateTime('created_at', { useTz: true, precision: 3 }).notNullable();
+            t.dateTime('updated_at', { useTz: true, precision: 3 }).notNullable();
+        },
+        columns: {
+            account_id: (t) => t.string('account_id'),
+            client_id: (t) => t.string('client_id', 2048),
+            agent_sub: (t) => t.string('agent_sub'),
+            scope: (t) => t.text('scope'),
+            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
+            revoked_at: (t) => t.dateTime('revoked_at', { useTz: true, precision: 3 }).nullable(),
+            created_at: (t) => t.dateTime('created_at', { useTz: true, precision: 3 }).nullable(),
+            updated_at: (t) => t.dateTime('updated_at', { useTz: true, precision: 3 }).nullable(),
+        },
+    },
+    {
+        name: 'auth_agent_refresh_tokens',
+        /** Refresh tokens dos grants de personal agents — só o hash, uso único. */
+        create: (t) => {
+            t.string('token_hash', 64).primary();
+            t.string('grant_id').notNullable().index();
+            t.dateTime('expires_at', { useTz: true, precision: 3 }).notNullable();
+            t.dateTime('used_at', { useTz: true, precision: 3 }).nullable();
+            t.dateTime('created_at', { useTz: true, precision: 3 }).notNullable();
+        },
+        columns: {
+            grant_id: (t) => t.string('grant_id').index(),
+            expires_at: (t) => t.dateTime('expires_at', { useTz: true, precision: 3 }).nullable(),
+            used_at: (t) => t.dateTime('used_at', { useTz: true, precision: 3 }).nullable(),
+            created_at: (t) => t.dateTime('created_at', { useTz: true, precision: 3 }).nullable(),
+        },
+    },
 ];
 /**
  * Probe searchPath-aware: `schema.hasTable` no Postgres ignora o