@adonis-agora/authkit-server 1.0.0-rc.0 → 1.0.0-rc.10

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[];

package/build/src/agents/extension.js

@@ -0,0 +1,40 @@
+const EXTENSION_ID = /^[a-z0-9-]{2,16}$/;
+const GRANT_PREFIX = /^[a-z0-9]+_$/;
+function normalizePrefix(prefix, id) {
+    const trimmed = (prefix ?? '').trim().replace(/\/+$/, '');
+    if (!trimmed || trimmed === '/') {
+        throw new Error(`authkit: personalAgents.extensions "${id}" — prefix is required.`);
+    }
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+/** Resolves and validates `personalAgents.extensions`. */
+export function resolvePersonalAgentExtensions(input, context) {
+    const out = [];
+    for (const extension of input ?? []) {
+        const id = extension?.id;
+        if (typeof id !== 'string' || !EXTENSION_ID.test(id) || id === 'pact') {
+            throw new Error(`authkit: personalAgents.extensions — invalid id "${String(id)}" (2–16 of a-z, 0-9, -; not "pact").`);
+        }
+        if (out.some((e) => e.id === id)) {
+            throw new Error(`authkit: personalAgents.extensions — "${id}" is listed twice.`);
+        }
+        const definition = extension.resolve(context);
+        if (!GRANT_PREFIX.test(definition.grantIdPrefix) || definition.grantIdPrefix === 'agrant_') {
+            throw new Error(`authkit: personalAgents.extensions "${id}" — invalid grantIdPrefix "${definition.grantIdPrefix}".`);
+        }
+        if (out.some((e) => e.grantIdPrefix === definition.grantIdPrefix)) {
+            throw new Error(`authkit: personalAgents.extensions "${id}" — grantIdPrefix "${definition.grantIdPrefix}" is already taken.`);
+        }
+        const prefix = normalizePrefix(definition.prefix, id);
+        for (const other of out) {
+            if (other.prefix === prefix ||
+                other.prefix.startsWith(`${prefix}/`) ||
+                prefix.startsWith(`${other.prefix}/`)) {
+                throw new Error(`authkit: personalAgents.extensions "${id}" — prefix "${prefix}" overlaps "${other.id}" ("${other.prefix}").`);
+            }
+        }
+        // A plain object literal: its own members are the definition.
+        out.push({ ...definition, id, prefix });
+    }
+    return out;
+}

package/build/src/agents/middleware.js

@@ -40,7 +40,7 @@ export function personalAgentAuth(options = {}) {
     const mode = options.delegation ?? 'optional';
     return async (ctx, next) => {
         const runtime = await personalAgentsFor(ctx);
-        // Sem PACT (app só-Poppy) não há JWT de agente para verificar.
+        // Sem PACT (app só com extensions) não há JWT de agente para verificar.
         if (!runtime?.config.pact)
             return ctx.response.notFound();
         const { protocol } = runtime.config;

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

@@ -10,10 +10,10 @@ import type { DelegationReceipt } from './delegation_service.js';
  * MESMA família (JWT do agente + token de delegação) entra como mais um objeto
  * desta interface, passado direto em `personalAgents.protocol`.
  *
- * O Personal Agent Protocol ("Poppy", Sierra/Meta) tem outro modelo — um
- * authorization server OAuth com Sessions e tokens DPoP — e por isso não é um
- * adapter daqui: liga-se em `personalAgents.poppy` (ver `poppy/`), ao lado do
- * PACT, reaproveitando o núcleo de grants.
+ * Um protocolo de outro modelo (ex.: um authorization server OAuth próprio, como o
+ * Personal Agent Protocol de `@adonis-agora/authkit-poppy`) não é um adapter daqui:
+ * liga-se em `personalAgents.extensions` (ver `extension.ts`), ao lado do PACT,
+ * reaproveitando o núcleo de grants.
  */
 export interface PersonalAgentProtocol {
     /** Identificador estável (`'pact'`). */

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

@@ -1,10 +1,11 @@
 export declare const REGISTRY_TABLE = "auth_agent_registry";
-export type AgentProtocolId = 'pact' | 'poppy';
+/** `'pact'` ou o id de uma extension (`personalAgents.extensions`). */
+export type AgentProtocolId = 'pact' | (string & {});
 export type AgentRegistryStatus = 'allowed' | 'blocked';
 export interface AgentRegistryRow {
     id: string;
     protocol: AgentProtocolId;
-    /** PACT: o `iss` do agente. Poppy: o `client_id` (URL do documento de metadata). */
+    /** PACT: o `iss` do agente. Extensions: o identificador do agente no protocolo delas. */
     identifier: string;
     status: AgentRegistryStatus;
     name: string | null;

package/build/src/agents/registry_store.js

@@ -3,7 +3,7 @@
  * `auth_agent_registry` (ver `schema/ensure.ts`). SOMA ao `defineConfig`:
  *
  * - `allowed`: o agente entra mesmo fora da lista do config (PACT: issuer + JWKS;
- *   Poppy: `client_id` registrado quando `clients.requireRegistration`).
+ *   extensions: o identificador do agente no protocolo delas).
  * - `blocked`: o agente é recusado mesmo que o config o liste — bloquear é a
  *   ação de emergência, e precisa valer sem deploy.
  *

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

@@ -4,8 +4,7 @@ import { PersonalAgentVerifier } from './agent_identity.js';
 import type { ResolvedPersonalAgentsConfig } from './config.js';
 import { PersonalAgentDelegation } from './delegation_service.js';
 import { DelegationStore, type GrantRow } from './delegation_store.js';
-import type { JsonFetcher } from './poppy/safe_fetch.js';
-import { PoppyService } from './poppy/service.js';
+import type { PersonalAgentProtocolRuntime, ResolvedPersonalAgentExtension } from './extension.js';
 import { type AgentProtocolId, AgentRegistryStore } from './registry_store.js';
 /** URLs públicas do authorization server de delegação. */
 export interface PersonalAgentUrls {
@@ -31,9 +30,15 @@ export interface PersonalAgentsRuntime {
     verifier: PersonalAgentVerifier;
     /** `null` quando o app não configurou `personalAgents.delegation`. */
     delegation: PersonalAgentDelegation | null;
-    /** `null` quando o app não configurou `personalAgents.poppy`. */
-    poppy: PoppyService | null;
-    /** Revoga um grant de personal agent DA CONTA (PACT ou Poppy). */
+    /**
+     * Runtimes de `personalAgents.extensions`, por id do protocolo. Vazio sem extensions ou sem
+     * banco.
+     */
+    extensions: Map<string, {
+        extension: ResolvedPersonalAgentExtension;
+        runtime: PersonalAgentProtocolRuntime;
+    }>;
+    /** Revoga um grant de personal agent DA CONTA (PACT ou de uma extension). */
     revokeAgentGrant(accountId: string, grantId: string): Promise<boolean>;
     /** Revoga todos os grants de personal agents da conta. Devolve quantos estavam vivos. */
     revokeAllAgentGrants(accountId: string): Promise<number>;
@@ -52,8 +57,6 @@ export interface PersonalAgentsRuntime {
 export interface BuildPersonalAgentsOptions {
     /** Resolve serviços do container (redis do replay store). */
     make?: (binding: string) => Promise<any>;
-    /** Busca de JSON (metadata/JWKS dos agentes Poppy) — injetável nos testes. */
-    fetchJson?: JsonFetcher;
     now?: () => Date;
 }
 /**
@@ -63,3 +66,19 @@ export interface BuildPersonalAgentsOptions {
 export declare function buildPersonalAgentsRuntime(service: OidcService, makeDb: () => Promise<any>, options?: BuildPersonalAgentsOptions): Promise<PersonalAgentsRuntime | null>;
 /** Runtime a partir de uma request. */
 export declare function personalAgentsFor(ctx: HttpContext): Promise<PersonalAgentsRuntime | null>;
+/** Where {@link personalAgentExtensionRuntime} builds the runtime from, outside a request. */
+export interface PersonalAgentRuntimeSource {
+    service: OidcService;
+    /** The Lucid `Database` (the `lucid.db` binding). */
+    db(): Promise<unknown>;
+    make?(binding: string): Promise<unknown>;
+    now?(): Date;
+}
+/**
+ * The runtime an extension's `setup` built (`personalAgents.extensions`), by protocol id. `null`
+ * when the extension is not configured (or there is no database). Takes the request, an explicit
+ * source (tests, scripts) or nothing (the booted app).
+ *
+ * Stable for 1.x — see `extension.ts`.
+ */
+export declare function personalAgentExtensionRuntime<R extends PersonalAgentProtocolRuntime = PersonalAgentProtocolRuntime>(id: string, from?: HttpContext | PersonalAgentRuntimeSource): Promise<R | null>;