@adonis-agora/authkit-server 0.78.0 → 0.80.0

package/build/src/agents/runtime.js

@@ -8,6 +8,7 @@ import { hmacNonceSource } from './poppy/dpop.js';
 import { databaseReplayStore, memoryLimiter, memoryReplayStore, redisReplayStore, } from './poppy/replay.js';
 import { PoppyService, poppyUrls } from './poppy/service.js';
 import { PoppyStore } from './poppy/store.js';
+import { AgentRegistryStore } from './registry_store.js';
 import { keystoreSigner } from './signer.js';
 /**
  * Deriva as URLs da ORIGEM do issuer configurado — nunca do Host da request
@@ -92,6 +93,41 @@ async function resolveReplay(replay, conn, make) {
     const redis = await make('redis');
     return redisReplayStore(redis.connection(name));
 }
+/**
+ * Config com o registro do console por cima: um agente BLOQUEADO no console é
+ * recusado mesmo que o config o liste; um LIBERADO entra mesmo fora da lista.
+ * O que o config bloqueia continua bloqueado.
+ */
+function withRegistry(config, registry) {
+    const resolveAgent = async (issuer) => {
+        const row = await registry.find('pact', issuer);
+        if (row?.status === 'blocked') {
+            return { issuer, jwksUri: row.jwksUri ?? '', name: row.name ?? undefined, enabled: false };
+        }
+        const configured = await config.resolveAgent(issuer);
+        if (configured)
+            return configured;
+        if (row?.status === 'allowed' && row.jwksUri) {
+            return { issuer, jwksUri: row.jwksUri, name: row.name ?? undefined };
+        }
+        return null;
+    };
+    const poppy = config.poppy;
+    return {
+        ...config,
+        resolveAgent,
+        poppy: poppy && {
+            ...poppy,
+            clients: {
+                ...poppy.clients,
+                isBlocked: async (id) => (await poppy.clients.isBlocked(id)) ||
+                    (await registry.find('poppy', id))?.status === 'blocked',
+                isRegistered: async (id) => (await poppy.clients.isRegistered(id)) ||
+                    (await registry.find('poppy', id))?.status === 'allowed',
+            },
+        },
+    };
+}
 /**
  * Monta (uma vez por `OidcService`) o runtime de personal agents. `null` quando
  * `personalAgents` não está no config — as rotas respondem 404.
@@ -112,12 +148,25 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
                 return !(supportsAccountStatus(store) && (await store.isDisabled(accountId)));
             };
             let conn = null;
+            const connection = service.config.schema.connection;
             if (config.delegation || config.poppy) {
                 const db = await makeDb();
-                const connection = service.config.schema.connection;
                 conn = () => (connection ? db.connection(connection) : db.connection());
             }
+            else {
+                // PACT só de identidade não precisa de banco; com ele, o console pode bloquear.
+                try {
+                    const db = await makeDb();
+                    if (db)
+                        conn = () => (connection ? db.connection(connection) : db.connection());
+                }
+                catch {
+                    conn = null;
+                }
+            }
             const store = conn ? new DelegationStore(conn) : null;
+            const registry = conn ? new AgentRegistryStore(conn) : null;
+            const effective = registry ? withRegistry(config, registry) : config;
             let delegation = null;
             if (config.delegation && store) {
                 delegation = new PersonalAgentDelegation({
@@ -129,8 +178,8 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
                 });
             }
             let poppy = null;
-            if (config.poppy && store && conn) {
-                const cfg = config.poppy;
+            if (effective.poppy && store && conn) {
+                const cfg = effective.poppy;
                 const limiter = cfg.rateLimit === false
                     ? null
                     : typeof cfg.rateLimit === 'function'
@@ -165,14 +214,47 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
                     count += await delegation.revokeAllGrants(accountId);
                 return count;
             };
+            const revokeGrantById = async (grantId) => {
+                if (!store)
+                    return null;
+                const grant = await store.findGrant(grantId);
+                const now = options.now?.() ?? new Date();
+                // Expirado já não vale: revogar não muda nada (e não vira evento de auditoria).
+                if (!grant || grant.revokedAt || grant.expiresAt <= now)
+                    return null;
+                if (grantId.startsWith('pgrant_')) {
+                    if (!poppy)
+                        return null;
+                    await poppy.revokeGrant(grantId);
+                }
+                else {
+                    await store.revokeGrantById(grantId, now);
+                }
+                return grant;
+            };
+            const disconnectAgent = async (protocol, identifier) => {
+                if (!store)
+                    return 0;
+                if (protocol === 'poppy')
+                    return poppy ? poppy.disconnectClient(identifier) : 0;
+                const ids = (await store.unrevokedGrantIdsOfClient(identifier)).filter((id) => !id.startsWith('pgrant_'));
+                const at = options.now?.() ?? new Date();
+                for (const id of ids)
+                    await store.revokeGrantById(id, at);
+                return ids.length;
+            };
             return {
-                config,
+                config: effective,
                 urls,
-                verifier: new PersonalAgentVerifier(config),
+                verifier: new PersonalAgentVerifier(effective),
                 delegation,
                 poppy,
                 revokeAgentGrant,
                 revokeAllAgentGrants,
+                registry,
+                grants: store,
+                revokeGrantById,
+                disconnectAgent,
             };
         })();
         // Falha (DB indisponível) não fica em cache — a próxima request tenta de novo.

package/build/src/audit/audit_sink.d.ts

@@ -8,7 +8,7 @@
  * varre os `audit.record({ type: ... })` do `src/` e falha quando um evento
  * emitido não está aqui.
  */
-export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'mfa.recovery_codes_regenerated', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated', 'agent.delegation_approved', 'agent.delegation_denied', 'agent.grant_revoked'];
+export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'mfa.recovery_codes_regenerated', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated', 'agent.delegation_approved', 'agent.delegation_denied', 'agent.grant_revoked', 'agent.grant_revoked_by_admin', 'agent.allowed', 'agent.blocked', 'agent.registry_removed'];
 /** Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP. */
 export type AuditEventType = (typeof AUDIT_EVENT_TYPES)[number];
 /**

package/build/src/audit/audit_sink.js

@@ -113,4 +113,10 @@ export const AUDIT_EVENT_TYPES = [
     'agent.delegation_approved',
     'agent.delegation_denied',
     'agent.grant_revoked',
+    // Console admin: um admin revogou a conexão de um usuário, ou liberou/bloqueou um
+    // agente (PACT pelo `iss`, Poppy pelo `client_id`).
+    'agent.grant_revoked_by_admin',
+    'agent.allowed',
+    'agent.blocked',
+    'agent.registry_removed',
 ];

package/build/src/define_config.d.ts

@@ -78,6 +78,18 @@ export interface MailHooks {
         email: string;
         sudoUrl: string;
     }) => Promise<void>;
+    /**
+     * Código do Mediated Sign-In pronto do Poppy (`poppyEmailCodeSignIn`): um personal
+     * agent quer entrar na conta e a pessoa precisa dar o código a ele. Sem o hook, o
+     * host-kit envia pelo mailer default, com branding e i18n.
+     */
+    onPoppySignInCode?: (data: {
+        email: string;
+        code: string;
+        /** Nome do agente (metadata dele, ou o host do `client_id`). */
+        agentName: string;
+        expiresInMinutes: number;
+    }) => Promise<void>;
     /**
      * Disparado num login bem-sucedido a partir de um dispositivo NOVO (sem cookie
      * de dispositivo confiável válido para a conta). Best-effort, fire-and-forget:

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

@@ -49,7 +49,7 @@ export declare function grantDto(grant: AdminGrant): {
 };
 export declare function auditDto(event: StoredAuditEvent): {
     id: string;
-    type: "account.deleted" | "account.expiration_warned" | "account.expired_login_blocked" | "account.exported" | "account.locked" | "account.signed_out_all" | "agent.delegation_approved" | "agent.delegation_denied" | "agent.grant_revoked" | "bot_protection.rejected" | "client.created" | "client.deleted" | "client.secret_regenerated" | "client.updated" | "email.change_requested" | "email.changed" | "email_change.cancelled" | "email_change.confirmed" | "email_change.requested" | "email_verification.consumed" | "email_verification.issued" | "grant.revoked_by_user" | "impersonation" | "impersonation.panel_viewed" | "impersonation.stopped" | "keys.rotated" | "login.failure" | "login.magic_link_sent" | "login.new_device" | "login.new_ip_notified" | "login.otp_failed" | "login.otp_invalidated" | "login.otp_sent" | "login.otp_verified" | "login.success" | "maintenance.disabled" | "maintenance.enabled" | "mfa.disabled" | "mfa.enabled" | "mfa.recovery_codes_regenerated" | "organization.created" | "organization.deactivated" | "organization.deleted" | "organization.invitation_accepted" | "organization.invitation_revoked" | "organization.invitation_sent" | "organization.member_added" | "organization.member_removed" | "organization.member_role_changed" | "organization.member_role_updated" | "organization.switched" | "organization.updated" | "otp.locked" | "otp.unlock_failed" | "otp.unlocked" | "passkey.registered" | "passkey.removed" | "password.changed" | "password.expired_change_forced" | "password.rehashed" | "password_reset.consumed" | "password_reset.issued" | "pat.issued" | "pat.revoked" | "pat.used" | "profile.updated" | "roles_catalog.updated" | "security_notice.sent" | "session.revoked" | "session.revoked_all" | "session.single_enforced" | "settings.updated" | "signup" | "sudo.confirmed" | "trusted_device.revoked" | "user.created" | "user.deleted" | "user.disabled" | "user.enabled" | "user.password_reset_sent";
+    type: "account.deleted" | "account.expiration_warned" | "account.expired_login_blocked" | "account.exported" | "account.locked" | "account.signed_out_all" | "agent.allowed" | "agent.blocked" | "agent.delegation_approved" | "agent.delegation_denied" | "agent.grant_revoked" | "agent.grant_revoked_by_admin" | "agent.registry_removed" | "bot_protection.rejected" | "client.created" | "client.deleted" | "client.secret_regenerated" | "client.updated" | "email.change_requested" | "email.changed" | "email_change.cancelled" | "email_change.confirmed" | "email_change.requested" | "email_verification.consumed" | "email_verification.issued" | "grant.revoked_by_user" | "impersonation" | "impersonation.panel_viewed" | "impersonation.stopped" | "keys.rotated" | "login.failure" | "login.magic_link_sent" | "login.new_device" | "login.new_ip_notified" | "login.otp_failed" | "login.otp_invalidated" | "login.otp_sent" | "login.otp_verified" | "login.success" | "maintenance.disabled" | "maintenance.enabled" | "mfa.disabled" | "mfa.enabled" | "mfa.recovery_codes_regenerated" | "organization.created" | "organization.deactivated" | "organization.deleted" | "organization.invitation_accepted" | "organization.invitation_revoked" | "organization.invitation_sent" | "organization.member_added" | "organization.member_removed" | "organization.member_role_changed" | "organization.member_role_updated" | "organization.switched" | "organization.updated" | "otp.locked" | "otp.unlock_failed" | "otp.unlocked" | "passkey.registered" | "passkey.removed" | "password.changed" | "password.expired_change_forced" | "password.rehashed" | "password_reset.consumed" | "password_reset.issued" | "pat.issued" | "pat.revoked" | "pat.used" | "profile.updated" | "roles_catalog.updated" | "security_notice.sent" | "session.revoked" | "session.revoked_all" | "session.single_enforced" | "settings.updated" | "signup" | "sudo.confirmed" | "trusted_device.revoked" | "user.created" | "user.deleted" | "user.disabled" | "user.enabled" | "user.password_reset_sent";
     accountId: string | null;
     email: string | null;
     clientId: string | null;

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
+import { accountPath } from '../account_paths.js';
 import { resolveAccountRoles } from '../account_roles.js';
 import { getAdminPrefix } from '../admin_prefix.js';
 // ─── Shell HTML cache ─────────────────────────────────────────────────────────
@@ -134,6 +135,12 @@ export default class AdminShellController {
             currentUser,
             endpoints: {
                 api: `${adminBase}/api`,
+                // Confirmação de identidade (sudo) das ações destrutivas.
+                confirm: accountPath('confirm'),
+            },
+            features: {
+                // A página de personal agents só aparece com `personalAgents` no config.
+                personalAgents: !!cfg.personalAgents,
             },
         };
         const { html: rawHtml } = await loadShell();

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

@@ -0,0 +1,83 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { AgentProtocolId } from '../../agents/registry_store.js';
+type ListStatus = 'allowed' | 'blocked';
+interface AgentEntry {
+    protocol: AgentProtocolId;
+    identifier: string;
+    name: string;
+    /** O que o `defineConfig` diz (só listas estáticas); `null` = nada. */
+    config: ListStatus | null;
+    /** O que o console diz; `null` = nada. */
+    console: {
+        id: string;
+        status: ListStatus;
+        updatedAt: string;
+        updatedBy: string | null;
+    } | null;
+    /** Resultado: bloqueado em qualquer lado vence; senão liberado em qualquer lado; senão `unlisted`. */
+    effective: ListStatus | 'unlisted';
+    jwksUri: string | null;
+    /** Conexões vivas (grants não revogados nem expirados). */
+    connections: number;
+}
+/**
+ * Endpoints JSON de personal agents (PACT e Poppy) do console admin React.
+ *
+ * GET    {prefix}/api/personal-agents                          → agentes (config + console + conectados)
+ * GET    {prefix}/api/personal-agents/connections?clientId=&accountId=&protocol=&page=&size=
+ * POST   {prefix}/api/personal-agents/connections/:grantId/revoke   (sudo)
+ * POST   {prefix}/api/personal-agents/registry                 → libera/bloqueia (sudo)
+ * DELETE {prefix}/api/personal-agents/registry/:id             → tira do registro do console (sudo)
+ *
+ * 404 `capability_unsupported` quando `personalAgents` não está configurado ou não há banco.
+ */
+export default class ConsolePersonalAgentsController {
+    /** GET {prefix}/api/personal-agents */
+    index(ctx: HttpContext): Promise<void | {
+        protocols: {
+            pact: {
+                open: boolean;
+                /** A lista do config é uma função do host (o console não enxerga). */
+                hostResolver: boolean;
+            } | null;
+            poppy: {
+                requireRegistration: boolean;
+                hostResolver: boolean;
+                allowInsecureClientIds: boolean;
+            } | null;
+        };
+        agents: AgentEntry[];
+    }>;
+    /** GET {prefix}/api/personal-agents/connections */
+    connections(ctx: HttpContext): Promise<void | {
+        meta: {
+            page: number;
+            size: number;
+            total: number;
+        };
+        data: {
+            id: string;
+            protocol: AgentProtocolId;
+            clientId: string;
+            agentName: string;
+            accountId: string;
+            accountEmail: string | null;
+            scopes: string[];
+            createdAt: string;
+            updatedAt: string;
+            expiresAt: string;
+        }[];
+    }>;
+    /** POST {prefix}/api/personal-agents/connections/:grantId/revoke */
+    revokeConnection(ctx: HttpContext): Promise<void | {}>;
+    /**
+     * POST {prefix}/api/personal-agents/registry
+     * body: `{ protocol, identifier, status: 'allowed'|'blocked', name?, jwksUri? }`.
+     * Bloquear também desconecta o agente de todas as contas, na hora.
+     */
+    upsert(ctx: HttpContext): Promise<void | {}>;
+    /** DELETE {prefix}/api/personal-agents/registry/:id */
+    destroy(ctx: HttpContext): Promise<void | {}>;
+}
+export {};

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

@@ -0,0 +1,337 @@
+import '../augmentations.js';
+import { displayNameFor } from '../../agents/agent_identity.js';
+import { parseScope } from '../../agents/config.js';
+import { personalAgentsFor } from '../../agents/runtime.js';
+import { parseListPage, parseListSize } from '../../pagination.js';
+import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
+import { apiError } from '../admin_api/dto.js';
+import { resolveRuntimeSettings } from '../runtime_settings.js';
+import { requireSudo } from '../sudo_mode.js';
+/** Mesmo gate de sudo das outras ações destrutivas do console (sessões, chaves). */
+async function gateSudo(ctx) {
+    const settings = await resolveRuntimeSettings(ctx);
+    const result = await requireSudo(ctx, settings);
+    if (result === true)
+        return null;
+    return ctx.response
+        .status(403)
+        .send(apiError('sudo_required', 'Identity confirmation required.'));
+}
+function notSupported(ctx) {
+    return ctx.response.notFound(apiError('capability_unsupported', 'Personal agents não estão configurados (`personalAgents` no defineConfig) ou não há banco.'));
+}
+/** O runtime com banco, ou `null` (404 honesto). */
+async function runtimeFor(ctx) {
+    const runtime = await personalAgentsFor(ctx);
+    if (!runtime?.registry || !runtime.grants)
+        return null;
+    return runtime;
+}
+function enabledProtocols(runtime) {
+    const out = [];
+    if (runtime.config.pact)
+        out.push('pact');
+    if (runtime.config.poppy)
+        out.push('poppy');
+    return out;
+}
+function isUrl(value, allowHttp) {
+    if (typeof value !== 'string' || value.length > 2048)
+        return false;
+    try {
+        const url = new URL(value);
+        return ((url.protocol === 'https:' || (allowHttp && url.protocol === 'http:')) &&
+            !url.hash &&
+            !url.username &&
+            !url.password);
+    }
+    catch {
+        return false;
+    }
+}
+async function agentName(runtime, protocol, identifier, fallback) {
+    if (fallback)
+        return fallback;
+    if (protocol === 'poppy' && runtime.poppy) {
+        return runtime.poppy.registry.displayName(identifier);
+    }
+    const registration = await runtime.config.resolveAgent(identifier);
+    return displayNameFor(registration ?? { issuer: identifier, jwksUri: '' });
+}
+/**
+ * Endpoints JSON de personal agents (PACT e Poppy) do console admin React.
+ *
+ * GET    {prefix}/api/personal-agents                          → agentes (config + console + conectados)
+ * GET    {prefix}/api/personal-agents/connections?clientId=&accountId=&protocol=&page=&size=
+ * POST   {prefix}/api/personal-agents/connections/:grantId/revoke   (sudo)
+ * POST   {prefix}/api/personal-agents/registry                 → libera/bloqueia (sudo)
+ * DELETE {prefix}/api/personal-agents/registry/:id             → tira do registro do console (sudo)
+ *
+ * 404 `capability_unsupported` quando `personalAgents` não está configurado ou não há banco.
+ */
+export default class ConsolePersonalAgentsController {
+    /** GET {prefix}/api/personal-agents */
+    async index(ctx) {
+        const runtime = await runtimeFor(ctx);
+        if (!runtime)
+            return notSupported(ctx);
+        const cfg = runtime.config;
+        const now = new Date();
+        const entries = new Map();
+        const keyOf = (p, id) => `${p} ${id}`;
+        const entry = (protocol, identifier) => {
+            const k = keyOf(protocol, identifier);
+            let e = entries.get(k);
+            if (!e) {
+                e = {
+                    protocol,
+                    identifier,
+                    name: '',
+                    config: null,
+                    console: null,
+                    effective: 'unlisted',
+                    jwksUri: null,
+                    connections: 0,
+                };
+                entries.set(k, e);
+            }
+            return e;
+        };
+        const names = new Map();
+        if (cfg.pact) {
+            for (const agent of cfg.staticAgents ?? []) {
+                const e = entry('pact', agent.issuer);
+                e.config = agent.enabled === false ? 'blocked' : 'allowed';
+                e.jwksUri = agent.jwksUri;
+                names.set(keyOf('pact', agent.issuer), agent.name ?? null);
+            }
+            for (const [clientId, count] of await runtime.grants.countLiveGrantsByClient(now, 'pact')) {
+                entry('pact', clientId).connections = count;
+            }
+        }
+        if (cfg.poppy) {
+            for (const id of cfg.poppy.clients.registeredList ?? [])
+                entry('poppy', id).config = 'allowed';
+            for (const id of cfg.poppy.clients.blockedList ?? [])
+                entry('poppy', id).config = 'blocked';
+            for (const [clientId, count] of await runtime.grants.countLiveGrantsByClient(now, 'poppy')) {
+                entry('poppy', clientId).connections = count;
+            }
+        }
+        for (const row of await runtime.registry.list()) {
+            if (!enabledProtocols(runtime).includes(row.protocol))
+                continue;
+            const e = entry(row.protocol, row.identifier);
+            e.console = {
+                id: row.id,
+                status: row.status,
+                updatedAt: row.updatedAt.toISOString(),
+                updatedBy: row.updatedBy,
+            };
+            if (row.jwksUri)
+                e.jwksUri = row.jwksUri;
+            if (row.name)
+                names.set(keyOf(row.protocol, row.identifier), row.name);
+        }
+        const agents = await Promise.all([...entries.values()].map(async (e) => {
+            const statuses = [e.config, e.console?.status];
+            e.effective = statuses.includes('blocked')
+                ? 'blocked'
+                : statuses.includes('allowed')
+                    ? 'allowed'
+                    : 'unlisted';
+            e.name = await agentName(runtime, e.protocol, e.identifier, names.get(keyOf(e.protocol, e.identifier)) ?? null);
+            return e;
+        }));
+        agents.sort((a, b) => b.connections - a.connections || a.name.localeCompare(b.name));
+        return {
+            protocols: {
+                pact: cfg.pact
+                    ? {
+                        open: cfg.open,
+                        /** A lista do config é uma função do host (o console não enxerga). */
+                        hostResolver: cfg.staticAgents === null,
+                    }
+                    : null,
+                poppy: cfg.poppy
+                    ? {
+                        requireRegistration: cfg.poppy.clients.requireRegistration,
+                        hostResolver: cfg.poppy.clients.registeredList === null || cfg.poppy.clients.blockedList === null,
+                        allowInsecureClientIds: cfg.poppy.allowInsecureClientIds,
+                    }
+                    : null,
+            },
+            agents,
+        };
+    }
+    /** GET {prefix}/api/personal-agents/connections */
+    async connections(ctx) {
+        const runtime = await runtimeFor(ctx);
+        if (!runtime)
+            return notSupported(ctx);
+        const qs = ctx.request.qs();
+        const page = parseListPage(qs.page);
+        const size = parseListSize(qs.size);
+        const protocol = qs.protocol === 'pact' || qs.protocol === 'poppy'
+            ? qs.protocol
+            : undefined;
+        const filter = {
+            protocol,
+            clientId: qs.clientId?.trim() || undefined,
+            accountId: qs.accountId?.trim() || undefined,
+        };
+        const now = new Date();
+        const [total, rows] = await Promise.all([
+            runtime.grants.countLiveGrants(now, filter),
+            runtime.grants.listLiveGrants({ ...filter, now, offset: (page - 1) * size, limit: size }),
+        ]);
+        const store = (await ctx.containerResolver.make('authkit.server')).config.accountStore;
+        const emails = new Map();
+        const nameCache = new Map();
+        const data = await Promise.all(rows.map(async (g) => {
+            const rowProtocol = g.id.startsWith('pgrant_') ? 'poppy' : 'pact';
+            if (!emails.has(g.accountId)) {
+                const account = await store.findById(g.accountId).catch(() => null);
+                emails.set(g.accountId, account?.email ?? null);
+            }
+            const k = `${rowProtocol} ${g.clientId}`;
+            if (!nameCache.has(k))
+                nameCache.set(k, agentName(runtime, rowProtocol, g.clientId, null));
+            return {
+                id: g.id,
+                protocol: rowProtocol,
+                clientId: g.clientId,
+                agentName: await nameCache.get(k),
+                accountId: g.accountId,
+                accountEmail: emails.get(g.accountId) ?? null,
+                scopes: parseScope(g.scope),
+                createdAt: g.createdAt.toISOString(),
+                updatedAt: g.updatedAt.toISOString(),
+                expiresAt: g.expiresAt.toISOString(),
+            };
+        }));
+        return { meta: { page, size, total }, data };
+    }
+    /** POST {prefix}/api/personal-agents/connections/:grantId/revoke */
+    async revokeConnection(ctx) {
+        const runtime = await runtimeFor(ctx);
+        if (!runtime)
+            return notSupported(ctx);
+        const denied = await gateSudo(ctx);
+        if (denied)
+            return denied;
+        const grantId = ctx.request.param('grantId');
+        const grant = await runtime.revokeGrantById(grantId);
+        if (!grant) {
+            return ctx.response.notFound(apiError('not_found', 'Conexão não encontrada ou já revogada.'));
+        }
+        const cfg = (await ctx.containerResolver.make('authkit.server')).config;
+        await cfg.audit?.record({
+            type: 'agent.grant_revoked_by_admin',
+            accountId: grant.accountId,
+            clientId: grant.clientId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { grantId, actor: ctx.session.get(ACCOUNT_SESSION_KEY) ?? null },
+        });
+        return { revoked: true };
+    }
+    /**
+     * POST {prefix}/api/personal-agents/registry
+     * body: `{ protocol, identifier, status: 'allowed'|'blocked', name?, jwksUri? }`.
+     * Bloquear também desconecta o agente de todas as contas, na hora.
+     */
+    async upsert(ctx) {
+        const runtime = await runtimeFor(ctx);
+        if (!runtime)
+            return notSupported(ctx);
+        const body = (ctx.request.body() ?? {});
+        const invalid = (message) => ctx.response.unprocessableEntity(apiError('invalid_request', message));
+        const protocol = body.protocol;
+        if (!enabledProtocols(runtime).includes(protocol)) {
+            return invalid('`protocol` precisa ser um protocolo ligado (`pact` ou `poppy`).');
+        }
+        const status = body.status;
+        if (status !== 'allowed' && status !== 'blocked') {
+            return invalid('`status` precisa ser `allowed` ou `blocked`.');
+        }
+        const allowHttp = protocol === 'poppy' && !!runtime.config.poppy?.allowInsecureClientIds;
+        const identifier = typeof body.identifier === 'string' ? body.identifier.trim() : '';
+        if (!isUrl(identifier, allowHttp)) {
+            return invalid(protocol === 'poppy'
+                ? '`identifier` precisa ser o `client_id` do agente (URL HTTPS do documento de metadata).'
+                : '`identifier` precisa ser o `iss` do agente (URL HTTPS).');
+        }
+        const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim().slice(0, 200) : null;
+        let jwksUri = null;
+        if (protocol === 'pact') {
+            const raw = typeof body.jwksUri === 'string' ? body.jwksUri.trim() : '';
+            if (raw && !isUrl(raw, false))
+                return invalid('`jwksUri` precisa ser uma URL HTTPS.');
+            jwksUri = raw || null;
+            if (status === 'allowed' && !jwksUri) {
+                return invalid('Liberar um agente PACT exige o `jwksUri` dele.');
+            }
+        }
+        const denied = await gateSudo(ctx);
+        if (denied)
+            return denied;
+        const actor = ctx.session.get(ACCOUNT_SESSION_KEY) ?? null;
+        const row = await runtime.registry.upsert({
+            protocol,
+            identifier,
+            status,
+            name,
+            jwksUri,
+            updatedBy: actor,
+        });
+        const disconnected = status === 'blocked' ? await runtime.disconnectAgent(protocol, identifier) : 0;
+        const cfg = (await ctx.containerResolver.make('authkit.server')).config;
+        const event = {
+            clientId: identifier,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { protocol, actor, disconnected },
+        };
+        if (status === 'blocked')
+            await cfg.audit?.record({ type: 'agent.blocked', ...event });
+        else
+            await cfg.audit?.record({ type: 'agent.allowed', ...event });
+        return {
+            entry: {
+                id: row.id,
+                protocol: row.protocol,
+                identifier: row.identifier,
+                status: row.status,
+                name: row.name,
+                jwksUri: row.jwksUri,
+                updatedAt: row.updatedAt.toISOString(),
+            },
+            disconnected,
+        };
+    }
+    /** DELETE {prefix}/api/personal-agents/registry/:id */
+    async destroy(ctx) {
+        const runtime = await runtimeFor(ctx);
+        if (!runtime)
+            return notSupported(ctx);
+        const denied = await gateSudo(ctx);
+        if (denied)
+            return denied;
+        const id = ctx.request.param('id');
+        const row = await runtime.registry.findById(id);
+        if (!row || !(await runtime.registry.delete(id))) {
+            return ctx.response.notFound(apiError('not_found', 'Entrada não encontrada.'));
+        }
+        const cfg = (await ctx.containerResolver.make('authkit.server')).config;
+        await cfg.audit?.record({
+            type: 'agent.registry_removed',
+            clientId: row.identifier,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: {
+                protocol: row.protocol,
+                status: row.status,
+                actor: ctx.session.get(ACCOUNT_SESSION_KEY) ?? null,
+            },
+        });
+        return { removed: true };
+    }
+}

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

@@ -66,6 +66,17 @@ export declare function sendMagicLinkEmail(ctx: HttpContext, data: {
     code?: string;
     channel?: 'code' | 'link';
 }): Promise<void>;
+/**
+ * Envia o código do Mediated Sign-In pronto do Poppy (`poppyEmailCodeSignIn`) pelo
+ * mailer default do host. Só código, sem link: quem digita é a pessoa, no agente.
+ * Best-effort: no fallback (sem mail) loga o código, como o magic link loga o link; nunca lança.
+ */
+export declare function sendPoppySignInCodeEmail(ctx: HttpContext, data: {
+    email: string;
+    code: string;
+    agentName: string;
+    expiresInMinutes: number;
+}): Promise<void>;
 /**
  * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo) pelo mailer default do host.
  *