@adonis-agora/authkit-server 0.75.0 → 0.77.0

package/build/providers/authkit_server_provider.js

@@ -47,58 +47,36 @@ export default class AuthkitServerProvider {
         if (this.app.config.get('authkit')) {
             resolveAppKey(this.app);
         }
-        // Config locks: trava as settings definidas explicitamente no defineConfig
-        // (config vence em runtime; a UI/Admin API não pode alterá-las). Fail-safe:
-        // qualquer erro → sem locks (comportamento legado).
-        let resolvedConfig = null;
-        try {
-            const value = this.app.config.get('authkit');
-            if (value) {
-                const config = (await configProvider.resolve(this.app, value));
-                if (config) {
-                    resolvedConfig = config;
-                    if (config.lockedSettingKeys?.length) {
-                        const { setLockedSettingKeys } = await import('../src/host/config_locks.js');
-                        setLockedSettingKeys(config.lockedSettingKeys);
+        // Config locks + stash dos bits de routing + auto-montagem: tudo sai do config RESOLVIDO.
+        //
+        // A resolução pode falhar AQUI e dar certo um instante depois: o `jwks` de um keystore
+        // criptografado precisa do serviço de encryption, que nem sempre está pronto durante o boot
+        // dos providers. Antes, o catch engolia a falha e nada derivado do config valia — locks,
+        // `sudo.methods`, headless, personal agents — sem um aviso. Agora a falha aqui é tentada de
+        // novo no `booted` (todos os providers prontos, ANTES do preload `start/routes.ts`), e só a
+        // segunda falha desiste, com warning.
+        if (this.app.config.get('authkit')) {
+            let config;
+            try {
+                config = await this.#resolveConfig();
+            }
+            catch {
+                this.app.booted(async () => {
+                    let late;
+                    try {
+                        late = await this.#resolveConfig();
                     }
-                    // Stash dos bits de routing p/ o registerAuthHost ler do config (dedup).
-                    // boot() roda antes do preload start/routes.ts, então estará disponível lá.
-                    const { setAuthHostConfig } = await import('../src/host/auth_host_config.js');
-                    setAuthHostConfig({
-                        mountPath: config.mountPath,
-                        social: config.social,
-                        rateLimit: config.rateLimit,
-                        adminEnabled: config.admin.enabled,
-                        adminApiEnabled: config.adminApi.enabled,
-                        // `config.sudo.methods` passa a decidir também o que é MONTADO — sem
-                        // isto o host teria de repetir a lista no `registerAuthHost`, e as
-                        // duas divergiriam (tela oferecendo endpoint que dá 404).
-                        sudoMethods: config.sudo?.methods,
-                        // Defaults estruturais de `config.routes` (o argumento ainda vence).
-                        routes: typeof config.routes === 'object' ? config.routes : undefined,
-                        lockedRouteOptions: config.lockedRouteOptions,
-                        // API headless — repassa pro registerAuthHost montar as rotas.
-                        headless: config.headless
-                            ? {
-                                baseUrl: config.headless.baseUrl,
-                                resolveAccountId: config.headless.resolveAccountId,
-                            }
-                            : undefined,
-                    });
-                }
+                    catch (error) {
+                        const logger = await this.app.container.make('logger');
+                        logger.warn({ err: error }, 'authkit: config não resolveu no boot — locks, stash de rotas (registerAuthHost) e config.routes não foram aplicados');
+                        return;
+                    }
+                    if (late)
+                        await this.#applyResolvedConfig(late);
+                });
             }
-        }
-        catch {
-            /* sem locks / sem stash → registerAuthHost cai em opts/defaults */
-        }
-        // Auto-montagem das rotas (`config.routes`). FORA do try/catch fail-safe
-        // acima de propósito: "as rotas não subiram" não pode degradar em silêncio —
-        // seria um app inteiro em 404 sem nenhuma pista. Chama a MESMA função
-        // exportada que o `start/routes.ts` chamaria; não há segunda implementação.
-        if (resolvedConfig?.routes) {
-            const router = await this.app.container.make('router');
-            const { autoMountAuthHost } = await import('../src/host/register_auth_host.js');
-            autoMountAuthHost(router);
+            if (config)
+                await this.#applyResolvedConfig(config);
         }
         // Registra o disco "authkit" no edge.js para que os templates sejam referenciados
         // como `authkit::login`, `authkit::account/tokens`, etc.
@@ -123,6 +101,53 @@ export default class AuthkitServerProvider {
             // edge.js ausente (host headless/Inertia-only que não usa edgeRenderer) — ignora.
         }
     }
+    async #resolveConfig() {
+        const value = this.app.config.get('authkit');
+        return (await configProvider.resolve(this.app, value));
+    }
+    /**
+     * Aplica o que o boot deriva do config resolvido: os locks de settings, o stash que o
+     * `registerAuthHost` lê e a auto-montagem de `config.routes` (cuja falha propaga).
+     */
+    async #applyResolvedConfig(config) {
+        if (config.lockedSettingKeys?.length) {
+            const { setLockedSettingKeys } = await import('../src/host/config_locks.js');
+            setLockedSettingKeys(config.lockedSettingKeys);
+        }
+        // Stash dos bits de routing p/ o registerAuthHost ler do config (dedup). Roda antes do
+        // preload start/routes.ts (no boot, ou no `booted` quando o boot não conseguiu resolver).
+        const { setAuthHostConfig } = await import('../src/host/auth_host_config.js');
+        setAuthHostConfig({
+            mountPath: config.mountPath,
+            social: config.social,
+            rateLimit: config.rateLimit,
+            adminEnabled: config.admin.enabled,
+            adminApiEnabled: config.adminApi.enabled,
+            // `config.sudo.methods` passa a decidir também o que é MONTADO — sem isto o host teria de
+            // repetir a lista no `registerAuthHost`, e as duas divergiriam (tela oferecendo endpoint
+            // que dá 404).
+            sudoMethods: config.sudo?.methods,
+            // Defaults estruturais de `config.routes` (o argumento ainda vence).
+            routes: typeof config.routes === 'object' ? config.routes : undefined,
+            lockedRouteOptions: config.lockedRouteOptions,
+            personalAgents: config.personalAgents ? { prefix: config.personalAgents.prefix } : undefined,
+            // API headless — repassa pro registerAuthHost montar as rotas.
+            headless: config.headless
+                ? {
+                    baseUrl: config.headless.baseUrl,
+                    resolveAccountId: config.headless.resolveAccountId,
+                }
+                : undefined,
+        });
+        // 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
+        // degradar em silêncio: uma falha aqui propaga.
+        if (config.routes) {
+            const router = await this.app.container.make('router');
+            const { autoMountAuthHost } = await import('../src/host/register_auth_host.js');
+            autoMountAuthHost(router);
+        }
+    }
     register() {
         // Entrega o app BOOTADO ao singleton de `services/main` (e ao
         // `recordSubRevocation` do AdminSessionsService) para que nunca precisem

package/build/src/accounts/account_store.d.ts

@@ -3,6 +3,8 @@ import type { UserLoginMethods } from '../host/user_login_methods.js';
 export interface AuthAccount {
     id: string;
     email: string;
+    /** Host-verified phone identity. Omit until possession has been verified. */
+    phone?: string;
     globalRoles?: string[];
     name?: string;
     avatarUrl?: string;

package/build/src/accounts/lucid_account_store.js

@@ -182,6 +182,7 @@ export function lucidAccountStore(Model, options = {}) {
             // token (e para todo call-site tipado como string).
             id: String(row.id),
             email: row.email,
+            ...(row.phone && row.phoneVerifiedAt ? { phone: row.phone } : {}),
             globalRoles: row.globalRoles ?? [],
             name: row.fullName ?? undefined,
             avatarUrl: row.avatarUrl ?? undefined,
@@ -328,6 +329,7 @@ export async function lucidAccountStoreAsync(Model, options = {}) {
                     // Ver a nota em `toAccount` acima: `sub` precisa ser string.
                     id: String(row.id),
                     email: row.email,
+                    ...(row.phone && row.phoneVerifiedAt ? { phone: row.phone } : {}),
                     globalRoles: row.globalRoles ?? [],
                     name: row.fullName ?? undefined,
                     avatarUrl: row.avatarUrl ?? undefined,

package/build/src/adapters/adapter_contract.d.ts

@@ -24,6 +24,8 @@ export interface OidcAdapter {
     findByUid(uid: string): Promise<OidcPayload | undefined>;
     consume(id: string): Promise<void>;
     destroy(id: string): Promise<void>;
+    /** Extend an existing remembered Session atomically; never recreate revoked records. */
+    renewSession?(id: string, expiresIn: number): Promise<boolean>;
     revokeByGrantId(grantId: string): Promise<void>;
     /**
      * Enumeração GENÉRICA dos artefatos do model deste adapter (id + payload). Usada

package/build/src/adapters/database_adapter.d.ts

@@ -6,6 +6,7 @@ export declare class DatabaseAdapter implements OidcAdapter {
     private db;
     constructor(name: string, db: Database);
     upsert(id: string, payload: OidcPayload, expiresIn: number): Promise<void>;
+    renewSession(id: string, expiresIn: number): Promise<boolean>;
     find(id: string): Promise<OidcPayload | undefined>;
     findByUid(uid: string): Promise<OidcPayload | undefined>;
     findByUserCode(userCode: string): Promise<OidcPayload | undefined>;

package/build/src/adapters/database_adapter.js

@@ -38,6 +38,32 @@ export class DatabaseAdapter {
         }
         return JSON.parse(record.payload);
     }
+    async renewSession(id, expiresIn) {
+        if (this.name !== 'Session' || !Number.isSafeInteger(expiresIn) || expiresIn < 1)
+            return false;
+        const row = await this.#query().where('id', id).first();
+        const payload = await this.#parse(row);
+        const now = Date.now();
+        if (!payload ||
+            payload.transient ||
+            typeof payload.exp !== 'number' ||
+            payload.exp <= now / 1000)
+            return false;
+        // Compare-and-set: concurrent logout or mutation cannot be undone by renewal.
+        const changed = await this.#query()
+            .where('id', id)
+            .where('payload', row.payload)
+            .where('expires_at', '>', new Date(now).toISOString())
+            .update({
+            payload: JSON.stringify({ ...payload, exp: Math.floor(now / 1000) + expiresIn }),
+            expires_at: new Date(now + expiresIn * 1000).toISOString(),
+        });
+        if (Number(changed) > 0)
+            return true;
+        // A parallel renewal is harmless; a deletion must remain deleted.
+        const current = await this.find(id);
+        return Boolean(current && !current.transient && typeof current.exp === 'number' && current.exp > now / 1000);
+    }
     async find(id) {
         return this.#parse(await this.#query().where('id', id).first());
     }

package/build/src/adapters/redis_adapter.d.ts

@@ -7,6 +7,7 @@ export declare class RedisAdapter implements OidcAdapter {
     private prefix;
     constructor(name: string, redis: Redis, prefix: string);
     upsert(id: string, payload: OidcPayload, expiresIn: number): Promise<void>;
+    renewSession(id: string, expiresIn: number): Promise<boolean>;
     find(id: string): Promise<OidcPayload | undefined>;
     findByUid(uid: string): Promise<OidcPayload | undefined>;
     findByUserCode(userCode: string): Promise<OidcPayload | undefined>;

package/build/src/adapters/redis_adapter.js

@@ -52,6 +52,36 @@ export class RedisAdapter {
             multi.expire(key, expiresIn);
         await multi.exec();
     }
+    async renewSession(id, expiresIn) {
+        if (this.name !== 'Session' || !Number.isSafeInteger(expiresIn) || expiresIn < 1)
+            return false;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const raw = await this.redis.get(this.#key(id));
+            if (!raw)
+                return false;
+            const payload = JSON.parse(raw);
+            const now = Math.floor(Date.now() / 1000);
+            if (payload.transient || typeof payload.exp !== 'number' || payload.exp <= now)
+                return false;
+            const updated = JSON.stringify({ ...payload, exp: now + expiresIn });
+            const result = await this.redis.eval(`
+        local raw = redis.call('GET', KEYS[1])
+        if not raw then return 0 end
+        if raw ~= ARGV[1] then return 2 end
+        redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
+        if ARGV[4] ~= '' then redis.call('SET', KEYS[2], ARGV[4], 'EX', ARGV[3]) end
+        return 1
+      `, 2, this.#key(id), payload.uid ? this.#uidKey(payload.uid) : this.#key(id), raw, updated, expiresIn, payload.uid ? id : '');
+            if (result !== 2)
+                return result === 1;
+        }
+        // Another request may have renewed while we were comparing the payload.
+        const current = await this.find(id);
+        return Boolean(current &&
+            !current.transient &&
+            typeof current.exp === 'number' &&
+            current.exp > Date.now() / 1000);
+    }
     async find(id) {
         const data = await this.redis.get(this.#key(id));
         if (!data)

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

@@ -0,0 +1,33 @@
+import { type JWTPayload, type JWTVerifyGetKey } from 'jose';
+import type { PersonalAgentRegistration, ResolvedPersonalAgentsConfig } from './config.js';
+/** Quem está chamando: o agente e o usuário DELE (`sub`, opaco). */
+export interface PersonalAgentIdentity {
+    /** `iss` do JWT — identifica o agente; também é o `client_id` OAuth dele. */
+    issuer: string;
+    /** Usuário do agente. Opaco e estável; NÃO é a conta neste app. */
+    sub: string;
+    /** Nome de exibição do agente (registro ou host do issuer). */
+    name: string;
+    claims: JWTPayload;
+}
+export interface PersonalAgentVerifierOptions {
+    /** Fonte das chaves por `jwksUri`. Default: `createRemoteJWKSet` com cache. */
+    getKey?: (jwksUri: string) => JWTVerifyGetKey;
+    /** `fetch` da descoberta OIDC no modo `open`. Default: o global. */
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+/** Extrai o token de um header `Authorization: Bearer <token>`. */
+export declare function bearerToken(header: string | null | undefined): string | null;
+export declare function displayNameFor(registration: PersonalAgentRegistration): string;
+/**
+ * Verifica o JWT que um personal agent manda em `Authorization: Bearer`, com
+ * as regras do protocolo configurado (PACT §3.2: ES256/RS256, vida ≤ 300 s,
+ * 30 s de relógio). Devolve `null` para QUALQUER falha — o chamador responde
+ * 401 sem detalhe.
+ */
+export declare class PersonalAgentVerifier {
+    #private;
+    constructor(cfg: ResolvedPersonalAgentsConfig, options?: PersonalAgentVerifierOptions);
+    verify(authorization: string | null | undefined): Promise<PersonalAgentIdentity | null>;
+}

package/build/src/agents/agent_identity.js

@@ -0,0 +1,156 @@
+import { createRemoteJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify, } from 'jose';
+/** Descoberta do modo `open`: quanto tempo um resultado vale, e quantos guardar. */
+const DISCOVERY_TTL_MS = 60 * 60 * 1000;
+const DISCOVERY_FAILURE_TTL_MS = 60 * 1000;
+const MAX_CACHED_ISSUERS = 1000;
+/** Map com teto: passando do limite, sai a entrada mais antiga (ordem de inserção). */
+function setBounded(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_CACHED_ISSUERS)
+        map.delete(map.keys().next().value);
+}
+/** Extrai o token de um header `Authorization: Bearer <token>`. */
+export function bearerToken(header) {
+    if (!header)
+        return null;
+    const match = /^Bearer\s+(\S+)\s*$/i.exec(header);
+    return match ? match[1] : null;
+}
+export function displayNameFor(registration) {
+    if (registration.name)
+        return registration.name;
+    try {
+        return new URL(registration.issuer).host;
+    }
+    catch {
+        return registration.issuer;
+    }
+}
+/**
+ * Verifica o JWT que um personal agent manda em `Authorization: Bearer`, com
+ * as regras do protocolo configurado (PACT §3.2: ES256/RS256, vida ≤ 300 s,
+ * 30 s de relógio). Devolve `null` para QUALQUER falha — o chamador responde
+ * 401 sem detalhe.
+ */
+export class PersonalAgentVerifier {
+    #cfg;
+    #getKey;
+    #fetch;
+    #now;
+    #remoteSets = new Map();
+    #discovered = new Map();
+    constructor(cfg, options = {}) {
+        this.#cfg = cfg;
+        this.#getKey = options.getKey ?? ((uri) => this.#remoteSet(uri));
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#now = options.now ?? (() => new Date());
+    }
+    async verify(authorization) {
+        const token = bearerToken(authorization);
+        if (!token)
+            return null;
+        const rules = this.#cfg.protocol.identity;
+        let issuer;
+        try {
+            if (!rules.algorithms.includes(decodeProtectedHeader(token).alg ?? ''))
+                return null;
+            issuer = decodeJwt(token).iss;
+        }
+        catch {
+            return null;
+        }
+        if (typeof issuer !== 'string' || !issuer)
+            return null;
+        const registration = await this.#registrationFor(issuer);
+        if (!registration || registration.enabled === false)
+            return null;
+        const now = this.#now();
+        let payload;
+        try {
+            ({ payload } = await jwtVerify(token, this.#getKey(registration.jwksUri), {
+                algorithms: rules.algorithms,
+                issuer: registration.issuer,
+                audience: this.#cfg.audience,
+                clockTolerance: rules.clockSkewSeconds,
+                currentDate: now,
+                requiredClaims: ['sub', 'iat', 'exp'],
+            }));
+        }
+        catch {
+            return null;
+        }
+        // O que o `jwtVerify` não cobre: `aud` é UMA string, `iat` não está no
+        // futuro além da tolerância, e a vida do token é curta.
+        const nowSeconds = Math.floor(now.getTime() / 1000);
+        if (typeof payload.aud !== 'string')
+            return null;
+        if (typeof payload.sub !== 'string' || !payload.sub)
+            return null;
+        if (payload.iat > nowSeconds + rules.clockSkewSeconds)
+            return null;
+        if (payload.exp - payload.iat > rules.maxLifetimeSeconds)
+            return null;
+        return {
+            issuer: registration.issuer,
+            sub: payload.sub,
+            name: displayNameFor(registration),
+            claims: payload,
+        };
+    }
+    async #registrationFor(issuer) {
+        const registered = await this.#cfg.resolveAgent(issuer);
+        if (registered)
+            return registered;
+        if (!this.#cfg.open)
+            return null;
+        const jwksUri = await this.#discover(issuer);
+        return jwksUri ? { issuer, jwksUri } : null;
+    }
+    /**
+     * Modo `open`: `jwks_uri` via `{iss}/.well-known/openid-configuration`, só
+     * HTTPS. O `iss` vem de um JWT ainda NÃO verificado, então tudo é limitado:
+     * falhas também ficam em cache (um minuto — o mesmo `iss` não vira uma
+     * requisição de saída por request), acertos expiram (o `jwks_uri` pode
+     * mudar) e o cache tem teto de entradas.
+     */
+    #discover(issuer) {
+        const now = this.#now().getTime();
+        const cached = this.#discovered.get(issuer);
+        if (cached && cached.expiresAt > now)
+            return cached.result;
+        const result = this.#fetchJwksUri(issuer);
+        const entry = { result, expiresAt: now + DISCOVERY_TTL_MS };
+        setBounded(this.#discovered, issuer, entry);
+        result.then((uri) => {
+            if (!uri)
+                entry.expiresAt = now + DISCOVERY_FAILURE_TTL_MS;
+        });
+        return result;
+    }
+    async #fetchJwksUri(issuer) {
+        try {
+            const url = new URL(issuer);
+            if (url.protocol !== 'https:')
+                return null;
+            const res = await this.#fetch(`${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(5000), redirect: 'error' });
+            if (!res.ok)
+                return null;
+            const meta = (await res.json());
+            if (meta.issuer !== issuer || typeof meta.jwks_uri !== 'string')
+                return null;
+            return new URL(meta.jwks_uri).protocol === 'https:' ? meta.jwks_uri : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    #remoteSet(jwksUri) {
+        let set = this.#remoteSets.get(jwksUri);
+        if (!set) {
+            set = createRemoteJWKSet(new URL(jwksUri));
+            setBounded(this.#remoteSets, jwksUri, set);
+        }
+        return set;
+    }
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Personal agents — config.
+ *
+ * Um PERSONAL AGENT é uma plataforma de agente (ChatGPT, Meta AI, um assistente
+ * próprio…) que fala com este app EM NOME de um usuário. Ele se identifica com um
+ * JWT assinado pela própria chave (publicada num JWKS) — sem segredo
+ * compartilhado — e, opcionalmente, recebe do usuário uma DELEGAÇÃO: o usuário
+ * loga aqui, aprova scopes definidos pelo app, e o agente passa a agir na conta
+ * dele só dentro desses scopes.
+ *
+ * O núcleo (identidade do agente, device flow, grants, tokens de delegação,
+ * 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 BuiltinProtocolId, type PersonalAgentProtocol } from './protocol.js';
+/** Registro de um personal agent conhecido (PACT §3.1). */
+export interface PersonalAgentRegistration {
+    /** Valor exato que o agente põe no `iss` do JWT. Também é o `client_id` OAuth dele. */
+    issuer: string;
+    /** URL HTTPS do JWKS do agente. Estável — a rotação acontece dentro do JWKS. */
+    jwksUri: string;
+    /** Nome exibido na tela de consentimento. Default: o host do `issuer`. */
+    name?: string;
+    /** `false` desabilita o agente: as requests dele passam a receber 401. Default: true. */
+    enabled?: boolean;
+}
+/** Resolve um agente pelo `iss`. `null` = desconhecido (401). */
+export type PersonalAgentResolver = (issuer: string) => PersonalAgentRegistration | null | Promise<PersonalAgentRegistration | null>;
+export interface PersonalAgentDelegationConfigInput {
+    /**
+     * URL do endpoint do agente DESTE app que os personal agents chamam (a
+     * "interface URL" do Agent Card). Vira o `aud` dos tokens de delegação — um
+     * token só vale para ela.
+     */
+    interfaceUrl: string;
+    /**
+     * Scopes que o app oferece, `id → descrição`. A descrição aparece VERBATIM na
+     * tela de consentimento, então escreva para o usuário final
+     * (`{ 'orders:read': 'Ver seus pedidos e o status deles' }`).
+     */
+    scopes: Record<string, string>;
+    /** TTL do token de delegação, em segundos. Default: 3600 (o PACT recomenda ≤ 1h). */
+    accessTokenTtl?: number;
+    /** Validade do grant (e dos refresh tokens dele), em segundos. Default: 30 dias. */
+    grantTtl?: number;
+    /** Validade do `device_code`/`user_code`, em segundos. Default: 600. */
+    deviceCodeTtl?: number;
+    /** Intervalo mínimo de polling do token endpoint, em segundos. Default: 5. */
+    pollInterval?: number;
+}
+export interface PersonalAgentsConfigInput {
+    /**
+     * Protocolo do fio: um embutido pelo id (`'pact'`) ou um adapter próprio
+     * (ver {@link PersonalAgentProtocol}). Default: `'pact'`.
+     */
+    protocol?: BuiltinProtocolId | PersonalAgentProtocol;
+    /**
+     * Valor que os personal agents põem no `aud` do JWT deles. Opaco e atribuído
+     * por ESTE app no registro do agente — um valor por app, não derivado de URL.
+     */
+    audience: string;
+    /**
+     * Agentes aceitos: uma lista estática, ou uma função que resolve pelo `iss`
+     * (para quem guarda o registro no banco). Default: nenhum.
+     */
+    agents?: PersonalAgentRegistration[] | PersonalAgentResolver;
+    /**
+     * `true` aceita QUALQUER agente cujo `iss` publique um JWKS via OIDC discovery
+     * (`{iss}/.well-known/openid-configuration`), além dos registrados. A
+     * verificação do JWT continua completa; só a lista de permitidos some.
+     * Default: false.
+     */
+    open?: boolean;
+    /** Delegação (PACT §5). Ausente = só identidade (o agente fala, mas não age na conta). */
+    delegation?: PersonalAgentDelegationConfigInput;
+    /** Prefixo das rotas (`{prefix}/oauth/*`, `{prefix}/consent`). Default: `/agents`. */
+    prefix?: string;
+}
+export interface ResolvedPersonalAgentDelegationConfig {
+    interfaceUrl: string;
+    scopes: Record<string, string>;
+    accessTokenTtl: number;
+    grantTtl: number;
+    deviceCodeTtl: number;
+    pollInterval: number;
+}
+export interface ResolvedPersonalAgentsConfig {
+    protocol: PersonalAgentProtocol;
+    audience: string;
+    resolveAgent: PersonalAgentResolver;
+    open: boolean;
+    delegation?: ResolvedPersonalAgentDelegationConfig;
+    prefix: string;
+}
+export declare function normalizePersonalAgentsPrefix(prefix: string | undefined): string;
+export declare function resolvePersonalAgentsConfig(input: PersonalAgentsConfigInput | undefined): 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

@@ -0,0 +1,101 @@
+/**
+ * Personal agents — config.
+ *
+ * Um PERSONAL AGENT é uma plataforma de agente (ChatGPT, Meta AI, um assistente
+ * próprio…) que fala com este app EM NOME de um usuário. Ele se identifica com um
+ * JWT assinado pela própria chave (publicada num JWKS) — sem segredo
+ * compartilhado — e, opcionalmente, recebe do usuário uma DELEGAÇÃO: o usuário
+ * loga aqui, aprova scopes definidos pelo app, e o agente passa a agir na conta
+ * dele só dentro desses scopes.
+ *
+ * O núcleo (identidade do agente, device flow, grants, tokens de delegação,
+ * recibos) não depende de protocolo; o formato do fio vem do adapter em
+ * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
+ */
+import { BUILTIN_PROTOCOLS, } from './protocol.js';
+const SCOPE_ID = /^[\x21\x23-\x5B\x5D-\x7E]+$/; // RFC 6749 §3.3 scope-token
+function assertUrl(value, what) {
+    try {
+        new URL(value);
+    }
+    catch {
+        throw new Error(`authkit: personalAgents.${what} precisa ser uma URL absoluta (recebeu "${value}").`);
+    }
+}
+function positive(value, fallback, what) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`authkit: personalAgents.delegation.${what} precisa ser > 0.`);
+    }
+    return Math.floor(value);
+}
+export function normalizePersonalAgentsPrefix(prefix) {
+    const trimmed = (prefix ?? '/agents').trim().replace(/\/+$/, '');
+    if (!trimmed)
+        return '/agents';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function resolvePersonalAgentsConfig(input) {
+    if (!input)
+        return undefined;
+    if (!input.audience?.trim()) {
+        throw new Error('authkit: personalAgents.audience é obrigatório (o `aud` dos JWTs dos agentes).');
+    }
+    let resolveAgent;
+    if (typeof input.agents === 'function') {
+        resolveAgent = input.agents;
+    }
+    else {
+        const byIssuer = new Map();
+        for (const agent of input.agents ?? []) {
+            assertUrl(agent.issuer, `agents[].issuer`);
+            assertUrl(agent.jwksUri, `agents[].jwksUri`);
+            byIssuer.set(agent.issuer, agent);
+        }
+        resolveAgent = (issuer) => byIssuer.get(issuer) ?? null;
+    }
+    let delegation;
+    if (input.delegation) {
+        const d = input.delegation;
+        assertUrl(d.interfaceUrl, 'delegation.interfaceUrl');
+        const ids = Object.keys(d.scopes ?? {});
+        if (ids.length === 0) {
+            throw new Error('authkit: personalAgents.delegation.scopes precisa de pelo menos um scope.');
+        }
+        for (const id of ids) {
+            if (!SCOPE_ID.test(id)) {
+                throw new Error(`authkit: personalAgents.delegation.scopes — id inválido "${id}" (sem espaços/aspas).`);
+            }
+        }
+        delegation = {
+            interfaceUrl: d.interfaceUrl,
+            scopes: { ...d.scopes },
+            accessTokenTtl: positive(d.accessTokenTtl, 3600, 'accessTokenTtl'),
+            grantTtl: positive(d.grantTtl, 30 * 24 * 3600, 'grantTtl'),
+            deviceCodeTtl: positive(d.deviceCodeTtl, 600, 'deviceCodeTtl'),
+            pollInterval: positive(d.pollInterval, 5, 'pollInterval'),
+        };
+    }
+    const protocol = typeof input.protocol === 'object'
+        ? input.protocol
+        : BUILTIN_PROTOCOLS[input.protocol ?? 'pact'];
+    if (!protocol) {
+        throw new Error(`authkit: personalAgents.protocol "${String(input.protocol)}" desconhecido (embutidos: ${Object.keys(BUILTIN_PROTOCOLS).join(', ')}).`);
+    }
+    return {
+        protocol,
+        audience: input.audience,
+        resolveAgent,
+        open: input.open === true,
+        delegation,
+        prefix: normalizePersonalAgentsPrefix(input.prefix),
+    };
+}
+/** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */
+export function parseScope(value) {
+    return [...new Set((value ?? '').split(' ').filter(Boolean))];
+}
+export function formatScope(scopes) {
+    return [...scopes].join(' ');
+}