@adonis-agora/authkit-server 1.0.0-rc.1 → 1.0.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @adonis-agora/authkit-server
 
+## 1.0.0-rc.2
+
+### Major Changes
+
+- [#456](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/456) [`9c12ef9`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/9c12ef9c1c49db9d54a7da6d241264499ad76e18) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Poppy (the Personal Agent Protocol) moves out of `@adonis-agora/authkit-server` into the new `@adonis-agora/authkit-poppy` package, and authkit-server gains a stable extension surface for personal-agent protocols. See [Install `@adonis-agora/authkit-poppy` for Poppy](https://github.com/DavideCarvalho/adonis-agora-authkit/blob/main/apps/docs/content/docs/migrating-to-1-0.mdx#install-adonis-agoraauthkit-poppy-for-poppy).
+  
+  Breaking changes (`@adonis-agora/authkit-server`):
+  
+  - `personalAgents.poppy` is removed: install `@adonis-agora/authkit-poppy` and use `personalAgents: { extensions: [poppy({ ... })] }` with the same options. A config that still has `personalAgents.poppy` fails at boot. Routes, tables, tokens and sessions are unchanged, so no data migration is needed.
+  - Every Poppy export (`PoppyConfigInput` and the other `Poppy*` types, `poppyEmailCodeSignIn`, `verifyPoppyRequest`, `poppyAuth`, `poppyOf`, `poppyWebSession`, `poppyWebSessionOf`, `installPoppySlots`, `POPPY_AUTHENTICATE_SLOT`, `POPPY_WEB_SESSION_KEY`, `PoppyError`, `verifyDpopProof`, `accessTokenHash`, `hmacNonceSource`, `databaseReplayStore`, `memoryReplayStore`, `redisReplayStore`, `safeFetchJson`, `isBlockedAddress`, `SafeFetchError`, `maskEmail`) now comes from `@adonis-agora/authkit-poppy`.
+  - `mail.onPoppySignInCode` is removed: pass `sendCode` to `poppyEmailCodeSignIn()`.
+  - `authkitCsrfExceptions` no longer takes `poppyPrefix`; extensions' endpoints are exempted from the config (`personalAgentExtensions: false` turns that off).
+  - `ensureAuthkitSchema()` no longer creates the `auth_poppy_*` tables (the extension's tables are ensured at boot; `ensurePoppySchema()` for migrations).
+  - Admin console API: an extension's `protocols` entry is `{ label, requireRegistration, hostResolver, allowHttpIdentifiers, identifierLabel, identifierPlaceholder }`.
+  
+  New, stable for 1.x: `personalAgents.extensions` and the types `PersonalAgentExtension`, `PersonalAgentExtensionDefinition`, `PersonalAgentExtensionContext`, `PersonalAgentRouteKit`, `PersonalAgentHost`, `PersonalAgentGrantLedger`, `PersonalAgentGrant`, `PersonalAgentRefreshToken`, `PersonalAgentAccessTokens`, `PersonalAgentProtocolRuntime`, `PersonalAgentGrantSummary`, `PersonalAgentConsoleSummary`, `ResolvedPersonalAgentExtension`, `AuthkitTable`; the functions `personalAgentExtensionRuntime`, `ensureAuthkitTables`, `sendAuthkitCodeEmail`, `signInAccountSession` and `signOutAccountSession`; and the `tables` option of `ensureAuthkitSchema`.
+  
+  Breaking changes (`@adonis-agora/authkit-react`):
+  
+  - `PersonalAgentProtocol` is `'pact'` or any extension id, and `PersonalAgentsOverview.protocols` has one entry per extension (`PersonalAgentExtensionOverview`) instead of a fixed `poppy` key. `AccountAgentGrant.protocol` uses `PersonalAgentProtocol`.
+
 ## 1.0.0-rc.1
 
 ### Major Changes

package/README.md

@@ -15,11 +15,10 @@ wrapper around [`oidc-provider`](https://github.com/panva/node-oidc-provider).
   auth via `acr_values`, Dynamic Client Registration (RFC 7591/7592).
 - **Personal agents** — AI assistants acting for your users: agent identity by signed JWT
   (JWKS, no shared secrets) and user-approved, revocable delegation with scopes you define,
-  over a pluggable protocol adapter ([PACT](https://openpactprotocol.org) built in).
-  Plus the [Personal Agent Protocol ("Poppy")](https://personalagentprotocol.org/docs/spec):
-  discovery, signed `Poppy-Session` agent sessions, Direct/Device/Mediated sign-in, MCP and browser sessions.
-  ⚠️ **Experimental** — tracks the spec's Draft 0.3 and will change (possibly breaking, outside
-  semver majors) while the spec is a draft.
+  over a pluggable protocol adapter ([PACT](https://openpactprotocol.org) built in), plus
+  `personalAgents.extensions` for protocols shipped as their own packages — the
+  [Personal Agent Protocol ("Poppy")](https://personalagentprotocol.org/docs/spec) is
+  [`@adonis-agora/authkit-poppy`](https://www.npmjs.com/package/@adonis-agora/authkit-poppy).
 - **Native apps** — RFC 8252 native clients (`authkit:clients:create --native`: private-use
   scheme / claimed https / loopback redirects, always public + PKCE) and the `@adonisjs/auth`
   guards `oidcRpGuard` (session) and `oidcBearerGuard` (`Authorization: Bearer` access tokens,

package/build/index.d.ts

@@ -15,19 +15,12 @@ export type { PersonalAgentIdentity } from './src/agents/agent_identity.js';
 export { PersonalAgentVerifier } from './src/agents/agent_identity.js';
 export type { PersonalAgentDelegationConfigInput, PersonalAgentRegistration, PersonalAgentResolver, PersonalAgentsConfigInput, ResolvedPersonalAgentsConfig, } from './src/agents/config.js';
 export type { DelegationContext, DelegationGrantSummary, DelegationReceipt, } from './src/agents/delegation_service.js';
+export type { AuthkitTable, PersonalAgentAccessTokens, PersonalAgentConsoleSummary, PersonalAgentExtension, PersonalAgentExtensionContext, PersonalAgentExtensionDefinition, PersonalAgentGrant, PersonalAgentGrantLedger, PersonalAgentGrantSummary, PersonalAgentHost, PersonalAgentProtocolRuntime, PersonalAgentRefreshToken, PersonalAgentRouteKit, ResolvedPersonalAgentExtension, } from './src/agents/extension.js';
 export type { PersonalAgentAuthOptions, PersonalAgentRequestContext, } from './src/agents/middleware.js';
 export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgentSecurity, personalAgentStepUp, } from './src/agents/middleware.js';
-export type { PoppyAgentProtocolEntry, PoppyApiEntry, PoppyBrowserLogin, PoppyClientsConfigInput, PoppyConfigInput, PoppyLimiter, PoppyMediatedConfigInput, PoppyMediatedField, PoppyMediatedResult, PoppyMediatedVerifyInput, PoppyPrincipalBase, PoppyReplayStore, PoppyScopeHint, ResolvedPoppyConfig, } from './src/agents/poppy/config.js';
-export { accessTokenHash, type DpopNonceSource, type DpopResult, hmacNonceSource, type VerifyDpopInput, verifyDpopProof, } from './src/agents/poppy/dpop.js';
-export { maskEmail, type PoppyEmailCodeSignInOptions, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
-export { PoppyError, type PoppyErrorCode } from './src/agents/poppy/errors.js';
-export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
-export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, type PoppyAuthenticate, type PoppyAuthResult, type PoppyPrincipal, type PoppySlotRequest, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';
-export { isBlockedAddress, SafeFetchError, safeFetchJson, } from './src/agents/poppy/safe_fetch.js';
-export type { PoppyAuthError, PoppyGrantSummary, PoppySessionState, PoppyTokenResponse, PoppyVerifyOptions, } from './src/agents/poppy/service.js';
-export { type PoppyWebSessionMarker, poppyWebSession, poppyWebSessionOf, } from './src/agents/poppy/web_session.js';
 export type { BuiltinProtocolId, PactOptions, PersonalAgentProtocol, } from './src/agents/protocol.js';
 export { pact, pactProtocol } from './src/agents/protocol.js';
+export { type PersonalAgentRuntimeSource, personalAgentExtensionRuntime, } from './src/agents/runtime.js';
 export type { AuditEvent, AuditEventType, AuditPage, AuditSink, ListAuditParams, StoredAuditEvent, } from './src/audit/audit_sink.js';
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export type { ConsoleAuthorize, ConsoleAuthorizeResult, ConsoleAuthorizer, ConsoleAuthorizerClass, } from './src/console_authorize.js';
@@ -58,6 +51,7 @@ export type { AccountPathKey, AccountPathsOptions } from './src/host/account_pat
 export { accountPath, accountPrefix, joinAccountPath, } from './src/host/account_paths.js';
 export type { AccountConfirmMethod, AccountConfirmProps, AccountEmailConfirmedProps, AccountLoginProps, AccountMfaProps, AccountSecurityProps, } from './src/host/account_screen_props.js';
 export { ACCOUNT_SESSION_KEY } from './src/host/account_session_key.js';
+export { signInAccountSession, signOutAccountSession, } from './src/host/account_session_sign_in.js';
 export { ACTIVE_ORG_COOKIE, ACTIVE_ORG_COOKIE_TTL, decodeActiveOrgCookie, encodeActiveOrgCookie, readActiveOrgFromKoaCtx, } from './src/host/active_org_cookie.js';
 export type { AddMemberInput as AdminAddMemberInput, CreateInvitationInput as AdminCreateInvitationInput, CreateOrgInput as AdminCreateOrgInput, OrgDetail, OrgWithMemberCount, UpdateOrgInput as AdminUpdateOrgInput, } from './src/host/admin_api/admin_orgs_service.js';
 export { AdminOrgsService } from './src/host/admin_api/admin_orgs_service.js';
@@ -92,6 +86,7 @@ export type { CustomLoginIdentity, CustomLoginMethod, CustomLoginMethodBinding,
 export { authenticateCustomLogin, beginCustomLogin, completeCustomLogin, } from './src/host/custom_login.js';
 export type { CustomMfaContext, CustomMfaDescription, CustomMfaDescriptor, CustomMfaField, CustomMfaMethod, CustomMfaMethodBinding, CustomMfaMethodConstructor, CustomMfaMethods, } from './src/host/custom_mfa.js';
 export { beginCustomMfa, customMfaViewProps, verifyCustomMfa } from './src/host/custom_mfa.js';
+export { sendAuthkitCodeEmail } from './src/host/default_mailer.js';
 export { normalizeEmailIdentifier } from './src/host/email_identifier.js';
 export type { ResolveGeo } from './src/host/geo.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
@@ -111,7 +106,6 @@ export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, type OtpLoginConfigInput, type OtpVerifyOutcome, type ResolvedOtpLoginConfig, resolveOtpLoginConfig, } from './src/host/otp_login.js';
 export type { PersistentRpOptions } from './src/host/persistent_rp_session.js';
 export { endRpSession } from './src/host/persistent_rp_session.js';
-export { POPPY_WEB_SESSION_KEY } from './src/host/poppy_session_key.js';
 export type { AuthThrottles, ThrottleMiddleware } from './src/host/rate_limit.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export type { AccountScreensOptions, AuthHostOptions, AuthHostRouteMap, } from './src/host/register_auth_host.js';
@@ -163,5 +157,5 @@ export { OidcService } from './src/provider/oidc_service.js';
 export { checkClientRegistration, classifyRedirect, type RedirectUriPolicy, type RegistrationOperation, RegistrationPolicyError, type ResolvedRedirectUriPolicy, type ValidateRegistrationHook, } from './src/provider/registration_policy.js';
 export { registerOidcRoutes } from './src/register_routes.js';
 export type { EnsureSchemaOptions, EnsureSchemaReport } from './src/schema/ensure.js';
-export { ensureAuthkitSchema } from './src/schema/ensure.js';
+export { ensureAuthkitSchema, ensureAuthkitTables } from './src/schema/ensure.js';
 export { stubsRoot } from './stubs/main.js';

package/build/index.js

@@ -10,14 +10,8 @@ export { lucidStores } from './src/accounts/lucid_stores.js';
 export { ProviderIdentities, ProviderIdentitiesUnsupportedError, } from './src/accounts/provider_identities.js';
 export { PersonalAgentVerifier } from './src/agents/agent_identity.js';
 export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgentSecurity, personalAgentStepUp, } from './src/agents/middleware.js';
-export { accessTokenHash, hmacNonceSource, verifyDpopProof, } from './src/agents/poppy/dpop.js';
-export { maskEmail, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
-export { PoppyError } from './src/agents/poppy/errors.js';
-export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
-export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';
-export { isBlockedAddress, SafeFetchError, safeFetchJson, } from './src/agents/poppy/safe_fetch.js';
-export { poppyWebSession, poppyWebSessionOf, } from './src/agents/poppy/web_session.js';
 export { pact, pactProtocol } from './src/agents/protocol.js';
+export { personalAgentExtensionRuntime, } from './src/agents/runtime.js';
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export { authorizeByToken } from './src/console_authorize.js';
 export { adapters, defineConfig, resolveAdmin, resolveAdminApi, resolveAuthMethodsConfig, resolveDynamicRegistration, resolveLogin, resolveNotifications, resolveOrganizations, resolvePasswordless, resolveRateLimit, resolveRegistration, resolveWebauthn, toSeconds, } from './src/define_config.js';
@@ -39,6 +33,7 @@ export { AccountExportService } from './src/host/account_export_service.js';
  */
 export { accountPath, accountPrefix, joinAccountPath, } from './src/host/account_paths.js';
 export { ACCOUNT_SESSION_KEY } from './src/host/account_session_key.js';
+export { signInAccountSession, signOutAccountSession, } from './src/host/account_session_sign_in.js';
 // Organizations (multi-tenancy)
 export { ACTIVE_ORG_COOKIE, ACTIVE_ORG_COOKIE_TTL, decodeActiveOrgCookie, encodeActiveOrgCookie, readActiveOrgFromKoaCtx, } from './src/host/active_org_cookie.js';
 export { AdminOrgsService } from './src/host/admin_api/admin_orgs_service.js';
@@ -65,6 +60,7 @@ export { consoleLoginUrl, getAccountId, hasAccountSession, realAccountId, } from
 export { authkitCsrfExceptions } from './src/host/csrf.js';
 export { authenticateCustomLogin, beginCustomLogin, completeCustomLogin, } from './src/host/custom_login.js';
 export { beginCustomMfa, customMfaViewProps, verifyCustomMfa } from './src/host/custom_mfa.js';
+export { sendAuthkitCodeEmail } from './src/host/default_mailer.js';
 export { normalizeEmailIdentifier } from './src/host/email_identifier.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
 export { BUILTIN_MESSAGES, DEFAULT_LOCALE, DEFAULT_MESSAGES, PT_BR_MESSAGES, resolveMessages, translate, } from './src/host/i18n.js';
@@ -89,7 +85,6 @@ export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 // Login por OTP (código digitável): config + helpers puros.
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, resolveOtpLoginConfig, } from './src/host/otp_login.js';
 export { endRpSession } from './src/host/persistent_rp_session.js';
-export { POPPY_WEB_SESSION_KEY } from './src/host/poppy_session_key.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
@@ -140,5 +135,5 @@ export { generatePatToken, hashPatToken } from './src/pat/pat_tokens.js';
 export { OidcService } from './src/provider/oidc_service.js';
 export { checkClientRegistration, classifyRedirect, RegistrationPolicyError, } from './src/provider/registration_policy.js';
 export { registerOidcRoutes } from './src/register_routes.js';
-export { ensureAuthkitSchema } from './src/schema/ensure.js';
+export { ensureAuthkitSchema, ensureAuthkitTables } from './src/schema/ensure.js';
 export { stubsRoot } from './stubs/main.js';

package/build/providers/authkit_server_provider.js

@@ -134,8 +134,8 @@ export default class AuthkitServerProvider {
             personalAgents: config.personalAgents
                 ? {
                     prefix: config.personalAgents.prefix,
-                    ...(config.personalAgents.poppy
-                        ? { poppyPrefix: config.personalAgents.poppy.prefix }
+                    ...(config.personalAgents.extensions?.length
+                        ? { extensions: config.personalAgents.extensions }
                         : {}),
                 }
                 : undefined,
@@ -154,12 +154,9 @@ export default class AuthkitServerProvider {
             const logger = await this.app.container.make('logger').catch(() => null);
             warnAdminConsoleUnauthorized(logger);
         }
-        // Poppy: o slot global que o `@adonis-agora/agent` usa para autenticar o endpoint de
-        // conversas (e o MCP) sem importar este pacote — o contrato é o símbolo.
-        if (config.personalAgents?.poppy) {
-            const { installPoppySlots } = await import('../src/agents/poppy/resource.js');
-            const { poppyUrls } = await import('../src/agents/poppy/service.js');
-            installPoppySlots(poppyUrls(config.issuer, config.personalAgents.poppy.prefix).issuer);
+        // `personalAgents.extensions`: o boot de cada uma (slots globais, etc.).
+        for (const extension of config.personalAgents?.extensions ?? []) {
+            await extension.boot?.();
         }
         // Auto-montagem das rotas (`config.routes`). Chama a MESMA função exportada que o
         // `start/routes.ts` chamaria; não há segunda implementação. "As rotas não subiram" não pode
@@ -268,6 +265,7 @@ export default class AuthkitServerProvider {
             const report = await ensureAuthkitSchema(db, {
                 connection: config.schema.connection,
                 accountTable: config.accountStore?.accountTable,
+                tables: config.personalAgents?.extensions?.flatMap((e) => e.tables ?? []),
             });
             const logger = await this.app.container.make('logger').catch(() => null);
             if (report.created.length > 0) {

package/build/src/agents/config.d.ts

@@ -12,7 +12,7 @@
  * recibos) não depende de protocolo; o formato do fio vem do adapter em
  * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
  */
-import { type PoppyConfigInput, type ResolvedPoppyConfig } from './poppy/config.js';
+import { type PersonalAgentExtension, type ResolvedPersonalAgentExtension } from './extension.js';
 import { type BuiltinProtocolId, type PersonalAgentProtocol } from './protocol.js';
 /** Registro de um personal agent conhecido (PACT §3.1). */
 export interface PersonalAgentRegistration {
@@ -58,8 +58,8 @@ export interface PersonalAgentsConfigInput {
     /**
      * Valor que os personal agents põem no `aud` do JWT deles (PACT). Opaco e
      * atribuído por ESTE app no registro do agente — um valor por app, não
-     * derivado de URL. Liga o PACT; obrigatório, a não ser num app só-Poppy
-     * (`poppy` sem `audience`).
+     * derivado de URL. Liga o PACT; obrigatório, a não ser num app que só usa
+     * `extensions` (sem `audience`).
      */
     audience?: string;
     /**
@@ -79,14 +79,10 @@ export interface PersonalAgentsConfigInput {
     /** Prefixo das rotas (`{prefix}/oauth/*`, `{prefix}/consent`). Default: `/agents`. */
     prefix?: string;
     /**
-     * Personal Agent Protocol ("Poppy", https://personalagentprotocol.org) — o
-     * segundo protocolo, ao lado do PACT. Um app pode servir os dois. Ver
-     * `poppy/config.ts`.
-     *
-     * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — acompanha a spec em desenvolvimento e PODE MUDAR
-     *   de forma incompatível fora de majors enquanto ela for draft.
+     * Outros protocolos de personal agents, de pacotes à parte, ao lado do PACT
+     * (ex.: `poppy()` de `@adonis-agora/authkit-poppy`). Ver {@link PersonalAgentExtension}.
      */
-    poppy?: PoppyConfigInput;
+    extensions?: PersonalAgentExtension[];
 }
 export interface ResolvedPersonalAgentDelegationConfig {
     interfaceUrl: string;
@@ -108,11 +104,11 @@ export interface ResolvedPersonalAgentsConfig {
     open: boolean;
     delegation?: ResolvedPersonalAgentDelegationConfig;
     prefix: string;
-    /** Poppy resolvido (undefined = desligado). */
-    poppy?: ResolvedPoppyConfig;
+    /** `extensions` resolvidas, na ordem do config. */
+    extensions: ResolvedPersonalAgentExtension[];
 }
 export declare function normalizePersonalAgentsPrefix(prefix: string | undefined): string;
-export declare function resolvePersonalAgentsConfig(input: PersonalAgentsConfigInput | undefined): ResolvedPersonalAgentsConfig | undefined;
+export declare function resolvePersonalAgentsConfig(input: PersonalAgentsConfigInput | undefined, issuer?: string): ResolvedPersonalAgentsConfig | undefined;
 /** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */
 export declare function parseScope(value: string | null | undefined): string[];
 export declare function formatScope(scopes: Iterable<string>): string;

package/build/src/agents/config.js

@@ -12,7 +12,7 @@
  * recibos) não depende de protocolo; o formato do fio vem do adapter em
  * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
  */
-import { resolvePoppyConfig, } from './poppy/config.js';
+import { resolvePersonalAgentExtensions, } from './extension.js';
 import { BUILTIN_PROTOCOLS, } from './protocol.js';
 const SCOPE_ID = /^[\x21\x23-\x5B\x5D-\x7E]+$/; // RFC 6749 §3.3 scope-token
 function assertUrl(value, what) {
@@ -37,19 +37,20 @@ export function normalizePersonalAgentsPrefix(prefix) {
         return '/agents';
     return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 }
-export function resolvePersonalAgentsConfig(input) {
+export function resolvePersonalAgentsConfig(input, issuer = '') {
     if (!input)
         return undefined;
+    // 0.x → 1.0: o Poppy virou o pacote `@adonis-agora/authkit-poppy`.
+    if ('poppy' in input) {
+        throw new Error('authkit: `personalAgents.poppy` saiu do authkit-server — instale `@adonis-agora/authkit-poppy` e use `personalAgents.extensions: [poppy({ ... })]`.');
+    }
     const pact = !!input.audience?.trim();
-    if (!pact && !input.poppy) {
-        throw new Error('authkit: personalAgents.audience é obrigatório (o `aud` dos JWTs dos agentes PACT) — ou configure só `personalAgents.poppy`.');
+    if (!pact && !input.extensions?.length) {
+        throw new Error('authkit: personalAgents.audience é obrigatório (o `aud` dos JWTs dos agentes PACT) — ou configure só `personalAgents.extensions`.');
     }
     if (!pact && input.delegation) {
         throw new Error('authkit: personalAgents.delegation é do PACT e exige `personalAgents.audience`.');
     }
-    if (input.protocol === 'poppy') {
-        throw new Error('authkit: o Poppy não é um `protocol` do PACT — configure-o em `personalAgents.poppy` (os dois convivem).');
-    }
     let resolveAgent;
     let staticAgents = null;
     if (typeof input.agents === 'function') {
@@ -94,9 +95,14 @@ export function resolvePersonalAgentsConfig(input) {
         throw new Error(`authkit: personalAgents.protocol "${String(input.protocol)}" desconhecido (embutidos: ${Object.keys(BUILTIN_PROTOCOLS).join(', ')}).`);
     }
     const prefix = normalizePersonalAgentsPrefix(input.prefix);
-    const poppy = resolvePoppyConfig(input.poppy, input.delegation?.scopes);
-    if (poppy && pact && (poppy.prefix === prefix || poppy.prefix.startsWith(`${prefix}/`))) {
-        throw new Error(`authkit: personalAgents.poppy.prefix "${poppy.prefix}" não pode ficar debaixo de personalAgents.prefix ("${prefix}").`);
+    const extensions = resolvePersonalAgentExtensions(input.extensions, {
+        issuer,
+        delegationScopes: input.delegation?.scopes ? { ...input.delegation.scopes } : null,
+    });
+    for (const extension of extensions) {
+        if (pact && (extension.prefix === prefix || extension.prefix.startsWith(`${prefix}/`))) {
+            throw new Error(`authkit: o prefixo "${extension.prefix}" de personalAgents.extensions "${extension.id}" não pode ficar debaixo de personalAgents.prefix ("${prefix}").`);
+        }
     }
     return {
         pact,
@@ -107,7 +113,7 @@ export function resolvePersonalAgentsConfig(input) {
         open: input.open === true,
         delegation,
         prefix,
-        poppy,
+        extensions,
     };
 }
 /** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */

package/build/src/agents/delegation_service.js

@@ -31,11 +31,11 @@ function newUserCode() {
     return `${code.slice(0, 4)}-${code.slice(4)}`;
 }
 /**
- * A tabela de grants é compartilhada com o Poppy (refresh tokens, `pgrant_`):
- * o PACT só enxerga os dele.
+ * A tabela de grants é compartilhada com as `personalAgents.extensions` (cada uma com o seu
+ * prefixo de id): o PACT só enxerga os dele, `agrant_`.
  */
 function isPactGrant(id) {
-    return !id.startsWith('pgrant_');
+    return id.startsWith('agrant_');
 }
 /** Aceita o código como o usuário digitar: minúsculas, sem hífen, com espaços. */
 export function normalizeUserCode(input) {

package/build/src/agents/delegation_store.d.ts

@@ -38,7 +38,8 @@ export interface GrantRow {
     updatedAt: Date;
 }
 export interface LiveGrantFilter {
-    protocol?: 'pact' | 'poppy';
+    /** Só os grants com este prefixo de id (`agrant_` = PACT; o `grantIdPrefix` de uma extension). */
+    idPrefix?: string;
     clientId?: string;
     accountId?: string;
 }
@@ -88,7 +89,7 @@ export declare class DelegationStore {
     }): Promise<GrantRow[]>;
     countLiveGrants(now: Date, filter?: LiveGrantFilter): Promise<number>;
     /** Conexões vivas de um protocolo por agente: `client_id` → número de grants. */
-    countLiveGrantsByClient(now: Date, protocol: 'pact' | 'poppy'): Promise<Map<string, number>>;
+    countLiveGrantsByClient(now: Date, idPrefix: string): Promise<Map<string, number>>;
     /** Ids dos grants não revogados de um agente (vivos ou não) — para revogar todos. */
     unrevokedGrantIdsOfClient(clientId: string): Promise<string[]>;
     /** Revoga um grant sem checar a conta — reação a reuso de refresh token. */

package/build/src/agents/delegation_store.js

@@ -186,12 +186,13 @@ export class DelegationStore {
     // ─── console admin (todas as contas) ──────────────────────────────────────
     /**
      * Grants vivos (não revogados nem expirados em `now`), de todas as contas. O
-     * protocolo sai do prefixo do id: `agrant_` (PACT) ou `pgrant_` (Poppy).
+     * protocolo sai do prefixo do id: `agrant_` (PACT) ou o `grantIdPrefix` de uma extension.
      */
     #live(now, filter = {}) {
         let q = this.conn().from(GRANT_TABLE).whereNull('revoked_at').where('expires_at', '>', now);
-        if (filter.protocol)
-            q = q.where('id', 'like', filter.protocol === 'poppy' ? 'pgrant_%' : 'agrant_%');
+        // O prefixo é `[a-z0-9]+_`: o `_` do LIKE (um caractere qualquer) casa com ele mesmo.
+        if (filter.idPrefix)
+            q = q.where('id', 'like', `${filter.idPrefix}%`);
         if (filter.clientId)
             q = q.where('client_id', filter.clientId);
         if (filter.accountId)
@@ -211,8 +212,8 @@ export class DelegationStore {
         return Number(row?.total ?? 0);
     }
     /** Conexões vivas de um protocolo por agente: `client_id` → número de grants. */
-    async countLiveGrantsByClient(now, protocol) {
-        const rows = await this.#live(now, { protocol })
+    async countLiveGrantsByClient(now, idPrefix) {
+        const rows = await this.#live(now, { idPrefix })
             .select('client_id')
             .count('* as total')
             .groupBy('client_id');

package/build/src/agents/extension.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Personal-agent protocol extensions — the surface another package uses to plug a personal-agent
+ * protocol into the auth host (`personalAgents.extensions` in `config/authkit.ts`).
+ *
+ * **Stable for all of 1.x.** Everything in this file follows semver: a 1.x release only adds
+ * optional members. A protocol package (such as `@adonis-agora/authkit-poppy`) can change as fast
+ * as its spec does without forcing a major here.
+ *
+ * What an extension gets:
+ *
+ * - its own routes under the auth host, with the account guard and the rate-limit buckets of the
+ *   built-in screens ({@link PersonalAgentRouteKit});
+ * - a shared grant ledger (`auth_agent_grants` / `auth_agent_refresh_tokens`) scoped to its grant-id
+ *   prefix, so the account console ("Connected apps"), the account API, "sign out everywhere", account
+ *   deletion and the admin console list and revoke its connections with no extra code
+ *   ({@link PersonalAgentGrantLedger});
+ * - the admin console's allow/block registry (`auth_agent_registry`), keyed by its protocol id;
+ * - its own lib-owned tables, created with AuthKit's (`schema.autoManage`) — {@link AuthkitTable};
+ * - access tokens minted by the OIDC provider for MCP resources ({@link PersonalAgentAccessTokens});
+ * - message catalogs merged into AuthKit's i18n (host overrides in `i18n.messages` still win).
+ *
+ * What it gives back: a {@link PersonalAgentProtocolRuntime} — list, revoke and name its
+ * connections.
+ */
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * A lib-owned table: created when missing, new columns added with `ALTER ADD`, never dropped or
+ * altered. The builders receive a Knex `TableBuilder`.
+ */
+export interface AuthkitTable {
+    name: string;
+    /** Full builder — runs when the table does not exist. */
+    create: (table: any) => void;
+    /**
+     * One builder per column — runs (`ALTER ADD`) when the table exists but the column does not.
+     * No constraints that break on populated tables (unique/FK belong in `create`).
+     */
+    columns: Record<string, (table: any) => void>;
+    /** Indexes ensured by name, also on tables that already existed. `create` must declare them. */
+    indexes?: Array<{
+        name: string;
+        columns: string[];
+    }>;
+}
+/** A row of the shared grant ledger (`auth_agent_grants`). */
+export interface PersonalAgentGrant {
+    /** Starts with the extension's `grantIdPrefix`. */
+    id: string;
+    accountId: string;
+    /** The agent's identifier in its protocol (a PACT `iss`, a Poppy `client_id`…). */
+    clientId: string;
+    /** The agent's own user id, when the protocol has one. `''` otherwise. */
+    agentSub: string;
+    /** Space-separated scopes. */
+    scope: string;
+    expiresAt: Date;
+    revokedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** A refresh token of the ledger — only its hash is stored. */
+export interface PersonalAgentRefreshToken {
+    grantId: string;
+    expiresAt: Date;
+    usedAt: Date | null;
+}
+/**
+ * The shared grant ledger, scoped to one extension: every read and write only sees grants whose id
+ * starts with the extension's `grantIdPrefix`. Grants written here show up in the account and admin
+ * consoles and are revoked by "sign out everywhere", password reset and account deletion.
+ */
+export interface PersonalAgentGrantLedger {
+    /** Throws when `grant.id` does not start with the extension's prefix. */
+    insertGrant(grant: Omit<PersonalAgentGrant, 'revokedAt'>): Promise<void>;
+    /** `null` when missing or not this extension's. */
+    findGrant(id: string): Promise<PersonalAgentGrant | null>;
+    /** Unrevoked grants of the account (expired ones included), newest first. */
+    listGrants(accountId: string): Promise<PersonalAgentGrant[]>;
+    /** Ids of the agent's unrevoked grants, across accounts. */
+    unrevokedGrantIdsOfClient(clientId: string): Promise<string[]>;
+    /** Revokes the grant (no-op when already revoked or not this extension's). */
+    revokeGrantById(id: string, at: Date): Promise<void>;
+    insertRefreshToken(token: {
+        tokenHash: string;
+        grantId: string;
+        expiresAt: Date;
+        createdAt: Date;
+    }): Promise<void>;
+    /** `null` when unknown. The caller checks the grant through {@link findGrant}. */
+    findRefreshToken(tokenHash: string): Promise<PersonalAgentRefreshToken | null>;
+}
+/**
+ * Access tokens of the OIDC provider for MCP resources — the same tokens AuthKit's MCP integration
+ * (`mcp` in `defineConfig`, or `Symbol.for('@adonis-agora/oauth:resources')`) already accepts.
+ */
+export interface PersonalAgentAccessTokens {
+    /** `mcp` is enabled in `defineConfig`. */
+    readonly mcpEnabled: boolean;
+    /** `url` is a registered MCP resource of this app. */
+    isMcpResource(url: string): boolean;
+    /**
+     * Mints an access token bound to `resource`, under a provider grant with `grantId` (created when
+     * missing). `grantType` becomes the token's `gty`. `null` when the provider is not available.
+     */
+    mint(input: {
+        grantId: string;
+        accountId: string;
+        clientId: string;
+        scope: string;
+        resource: string;
+        /** Seconds. */
+        expiresIn: number;
+        /** When the extension's grant expires — the provider grant lives as long. */
+        grantExpiresAt: Date;
+        grantType: string;
+    }): Promise<string | null>;
+    /** Revokes the provider grant and its access tokens. */
+    revokeGrant(grantId: string): Promise<void>;
+}
+/** What the host hands to {@link PersonalAgentExtensionDefinition.setup}. */
+export interface PersonalAgentHost {
+    /** The extension's protocol id. */
+    readonly protocol: string;
+    /** The OIDC issuer (`defineConfig({ issuer })`). Derive public URLs from its origin. */
+    readonly issuer: string;
+    /** The Lucid connection AuthKit's tables live on (`schema.connection`). */
+    db(): any;
+    readonly grants: PersonalAgentGrantLedger;
+    /** The admin console's verdict on an agent of this protocol. `null` = not listed. */
+    registryStatus(identifier: string): Promise<'allowed' | 'blocked' | null>;
+    /** A stable per-app secret for `label` (HMAC of the app key). Same on every instance. */
+    deriveSecret(label: string): Buffer;
+    /** The account exists and is not disabled. */
+    isAccountActive(accountId: string): Promise<boolean>;
+    /** Resolves a container binding (`'redis'`…). Throws outside an app. */
+    make(binding: string): Promise<any>;
+    readonly accessTokens: PersonalAgentAccessTokens;
+    /** The clock (tests inject one). */
+    now(): Date;
+}
+/** One connection of an account, as the account console and API show it. */
+export interface PersonalAgentGrantSummary {
+    id: string;
+    clientId: string;
+    scopes: Array<{
+        id: string;
+        description: string;
+    }>;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+/** What the admin console shows about an extension. */
+export interface PersonalAgentConsoleSummary {
+    /** Only listed agents may connect. */
+    requireRegistration: boolean;
+    /** The config's allow/block list is a function, which the console cannot list. */
+    hostResolver: boolean;
+    /** Agent identifiers may be `http://` URLs (development only). */
+    allowHttpIdentifiers: boolean;
+    /** Agents the config lists, by identifier. */
+    configured: {
+        allowed: readonly string[];
+        blocked: readonly string[];
+    };
+    /** Label of the identifier field (`'Client ID (metadata URL)'`). */
+    identifierLabel: string;
+    /** Example identifier for the field. */
+    identifierPlaceholder?: string;
+}
+/** The running protocol, built once per app by {@link PersonalAgentExtensionDefinition.setup}. */
+export interface PersonalAgentProtocolRuntime {
+    /** Live connections of the account (account console and `GET /account/api/agents`). */
+    listAccountGrants(accountId: string): Promise<PersonalAgentGrantSummary[]>;
+    /** Revokes one connection OF THE ACCOUNT. `false` = not found, not the account's, or revoked. */
+    revokeAccountGrant(accountId: string, grantId: string): Promise<boolean>;
+    /** Revokes every connection of the account. Returns how many were live. */
+    revokeAllAccountGrants(accountId: string): Promise<number>;
+    /** Revokes a connection of any account (admin console). The host checked that it is live. */
+    revokeGrant(grantId: string): Promise<void>;
+    /** Disconnects an agent from every account (admin console block). Returns how many were live. */
+    disconnectAgent(identifier: string): Promise<number>;
+    /** The agent's display name. */
+    displayName(identifier: string): Promise<string>;
+    consoleSummary(): PersonalAgentConsoleSummary;
+}
+/** Route helpers for {@link PersonalAgentExtensionDefinition.routes}. */
+export interface PersonalAgentRouteKit {
+    /**
+     * The account-session guard of the consent screens: a signed-out visitor goes to the login and
+     * comes back, idle sessions end, and a personal agent's own browser gets 403.
+     */
+    accountGuard: (ctx: HttpContext, next: () => Promise<void>) => Promise<unknown>;
+    /** Rate-limit buckets of the built-in screens (no-op when `rateLimit` is off). */
+    throttle: {
+        /** Per IP, the login bucket — pages that write something without authentication. */
+        login<R>(route: R): R;
+        /** Per IP, the one-time-code bucket — screens that take a typed code. */
+        otp<R>(route: R): R;
+    };
+}
+/** What {@link PersonalAgentExtension.resolve} receives. */
+export interface PersonalAgentExtensionContext {
+    /** The OIDC issuer. */
+    issuer: string;
+    /** `personalAgents.delegation.scopes`, when PACT delegation is configured. */
+    delegationScopes: Readonly<Record<string, string>> | null;
+}
+/** A resolved extension. */
+export interface PersonalAgentExtensionDefinition<R extends PersonalAgentProtocolRuntime = PersonalAgentProtocolRuntime> {
+    /** Name shown in the admin console (`'Poppy'`). */
+    label: string;
+    /**
+     * Prefix of the ids of the grants it writes to the ledger (`'pgrant_'`). Ends with `_`, unique
+     * among extensions, never `agrant_` (PACT).
+     */
+    grantIdPrefix: string;
+    /**
+     * Path prefix of its routes (`'/poppy'`). Must not sit under the OIDC `mountPath` nor under
+     * `personalAgents.prefix`.
+     */
+    prefix: string;
+    /** Exact paths `authkitCsrfExceptions` exempts (server-to-server or cross-site POSTs). */
+    csrfExemptPaths?: readonly string[];
+    /** Lib-owned tables, ensured with AuthKit's own. */
+    tables?: readonly AuthkitTable[];
+    /** `locale → key → text`, merged under AuthKit's catalogs (host overrides win). */
+    messages?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     * The session belongs to a personal agent's browser: the account and admin consoles answer 403
+     * to it. Synchronous — reads the session only.
+     */
+    isAgentBrowser?(ctx: HttpContext): boolean;
+    /** Runs once when the provider boots, after the config resolved. */
+    boot?(): void | Promise<void>;
+    /** Registers its routes on the app router (from `registerAuthHost`). */
+    routes?(router: any, kit: PersonalAgentRouteKit): void;
+    /** Builds the runtime — once per app, on first use. */
+    setup(host: PersonalAgentHost): Promise<R>;
+}
+/**
+ * A personal-agent protocol packaged for `personalAgents.extensions`.
+ *
+ * ```ts
+ * // config/authkit.ts
+ * import { poppy } from '@adonis-agora/authkit-poppy'
+ * personalAgents: { extensions: [poppy({ organization: { name: 'Shop', domain: 'shop.example' } })] }
+ * ```
+ */
+export interface PersonalAgentExtension<R extends PersonalAgentProtocolRuntime = PersonalAgentProtocolRuntime> {
+    /** Protocol id: 2–16 characters of `a-z`, `0-9`, `-`. Never `pact`. */
+    readonly id: string;
+    /** Validates the extension's own config and resolves it. Runs when `defineConfig` resolves. */
+    resolve(context: PersonalAgentExtensionContext): PersonalAgentExtensionDefinition<R>;
+}
+/** A resolved extension, with its id. */
+export type ResolvedPersonalAgentExtension = PersonalAgentExtensionDefinition & {
+    readonly id: string;
+};
+/** Resolves and validates `personalAgents.extensions`. */
+export declare function resolvePersonalAgentExtensions(input: readonly PersonalAgentExtension[] | undefined, context: PersonalAgentExtensionContext): ResolvedPersonalAgentExtension[];