@adonis-agora/authkit-server 0.76.0 → 0.78.0

package/build/src/agents/config.js

@@ -12,6 +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 { BUILTIN_PROTOCOLS, } from './protocol.js';
 const SCOPE_ID = /^[\x21\x23-\x5B\x5D-\x7E]+$/; // RFC 6749 §3.3 scope-token
 function assertUrl(value, what) {
@@ -39,8 +40,15 @@ export function normalizePersonalAgentsPrefix(prefix) {
 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).');
+    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.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;
     if (typeof input.agents === 'function') {
@@ -83,13 +91,20 @@ export function resolvePersonalAgentsConfig(input) {
     if (!protocol) {
         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}").`);
+    }
     return {
+        pact,
         protocol,
-        audience: input.audience,
+        audience: pact ? input.audience : '',
         resolveAgent,
         open: input.open === true,
         delegation,
-        prefix: normalizePersonalAgentsPrefix(input.prefix),
+        prefix,
+        poppy,
     };
 }
 /** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */

package/build/src/agents/delegation_service.js

@@ -30,6 +30,13 @@ function newUserCode() {
         code += USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)];
     return `${code.slice(0, 4)}-${code.slice(4)}`;
 }
+/**
+ * A tabela de grants é compartilhada com o Poppy (Account Tokens, `pgrant_`):
+ * o PACT só enxerga os dele.
+ */
+function isPactGrant(id) {
+    return !id.startsWith('pgrant_');
+}
 /** Aceita o código como o usuário digitar: minúsculas, sem hífen, com espaços. */
 export function normalizeUserCode(input) {
     if (typeof input !== 'string')
@@ -183,7 +190,7 @@ export class PersonalAgentDelegation {
         if (!userCode)
             return null;
         const row = await this.#store.findDeviceByUserCode(userCode);
-        if (!row || row.status !== 'pending' || row.expiresAt <= this.#now())
+        if (row?.status !== 'pending' || row.expiresAt <= this.#now())
             return null;
         return {
             userCode: row.userCode,
@@ -201,7 +208,7 @@ export class PersonalAgentDelegation {
         const userCode = normalizeUserCode(input.userCode);
         const row = userCode ? await this.#store.findDeviceByUserCode(userCode) : null;
         const now = this.#now();
-        if (!row || row.status !== 'pending' || row.expiresAt <= now)
+        if (row?.status !== 'pending' || row.expiresAt <= now)
             return null;
         const requested = parseScope(row.requestedScope);
         const granted = requested.filter((id) => input.scopes.includes(id));
@@ -217,7 +224,7 @@ export class PersonalAgentDelegation {
             return null;
         const expiresAt = new Date(now.getTime() + this.#cfg.grantTtl * 1000);
         const existing = (await this.#store.findGrantsFor(input.accountId, row.clientId, row.agentSub))
-            .filter((g) => g.expiresAt > now)
+            .filter((g) => isPactGrant(g.id) && g.expiresAt > now)
             .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime())[0];
         let result = null;
         if (existing) {
@@ -248,7 +255,7 @@ export class PersonalAgentDelegation {
     async deny(input) {
         const userCode = normalizeUserCode(input.userCode);
         const row = userCode ? await this.#store.findDeviceByUserCode(userCode) : null;
-        if (!row || row.status !== 'pending')
+        if (row?.status !== 'pending')
             return false;
         return this.#store.transitionDevice(row.id, 'pending', {
             status: 'denied',
@@ -259,7 +266,7 @@ export class PersonalAgentDelegation {
     async listGrants(accountId) {
         const now = this.#now();
         return (await this.#store.listGrants(accountId))
-            .filter((g) => g.expiresAt > now)
+            .filter((g) => isPactGrant(g.id) && g.expiresAt > now)
             .map((g) => ({
             id: g.id,
             clientId: g.clientId,
@@ -270,7 +277,9 @@ export class PersonalAgentDelegation {
         }));
     }
     /** Revoga na hora: tokens já emitidos param de valer na próxima request. */
-    revokeGrant(accountId, grantId) {
+    async revokeGrant(accountId, grantId) {
+        if (!isPactGrant(grantId))
+            return false;
         return this.#store.revokeGrant(accountId, grantId, this.#now());
     }
     /** Revoga TODAS as delegações da conta. Devolve quantas estavam vivas. */
@@ -340,7 +349,7 @@ export class PersonalAgentDelegation {
      */
     async #converge(accountId, clientId, agentSub, now) {
         const live = (await this.#store.findGrantsFor(accountId, clientId, agentSub))
-            .filter((g) => g.expiresAt > now)
+            .filter((g) => isPactGrant(g.id) && g.expiresAt > now)
             .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
         const [survivor, ...extras] = live;
         if (!survivor)
@@ -355,7 +364,8 @@ export class PersonalAgentDelegation {
         return { grantId: survivor.id, scopes: parseScope(scope) };
     }
     async #grantUsable(grant, agent, now) {
-        return (grant.revokedAt === null &&
+        return (isPactGrant(grant.id) &&
+            grant.revokedAt === null &&
             grant.expiresAt > now &&
             grant.clientId === agent.issuer &&
             grant.agentSub === agent.sub &&

package/build/src/agents/middleware.js

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

package/build/src/agents/poppy/client_registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Identidade do personal agent no Poppy (§4.1): o `client_id` é uma URL HTTPS
+ * que devolve o documento de metadata do agente (OAuth Client ID Metadata
+ * Document). Buscamos (à prova de SSRF), validamos, guardamos em cache e
+ * importamos as chaves públicas do `jwks_uri`.
+ */
+import { type JWTVerifyGetKey } from 'jose';
+import type { ResolvedPoppyConfig } from './config.js';
+import { type JsonFetcher } from './safe_fetch.js';
+export interface PoppyClient {
+    clientId: string;
+    /** `client_name`, ou o host do `client_id`. */
+    name: string;
+    logoUri: string | null;
+    jwksUri: string;
+    redirectUris: string[];
+    extensions: Record<string, unknown>;
+    /** Chaves públicas do `jwks_uri`. */
+    keys: JWTVerifyGetKey;
+}
+/** Valida um documento de metadata e devolve os campos usados. Lança `invalid_client`. */
+export declare function validateClientMetadata(fetchedFrom: string, doc: unknown, options?: {
+    allowHttp?: boolean;
+}): Omit<PoppyClient, 'keys'>;
+export interface PoppyClientRegistryOptions {
+    /** Busca de JSON. Default: {@link safeFetchJson}. */
+    fetchJson?: JsonFetcher;
+    now?: () => number;
+}
+/**
+ * Resolve e valida agentes pelo `client_id`, com cache (respeita `max-age`,
+ * entre 1 min e 24 h; falhas ficam 1 min em cache para que o mesmo `client_id`
+ * não vire uma busca de saída por request).
+ */
+export declare class PoppyClientRegistry {
+    #private;
+    constructor(cfg: ResolvedPoppyConfig, options?: PoppyClientRegistryOptions);
+    /**
+     * O agente, ou `invalid_client`: `client_id` não é HTTPS, bloqueado, não
+     * registrado (quando o app exige registro), metadata inválida/inalcançável.
+     */
+    resolve(clientId: unknown): Promise<PoppyClient>;
+    /** Nome de exibição sem falhar (console de conta): metadata em cache/buscada, ou o host. */
+    displayName(clientId: string): Promise<string>;
+}

package/build/src/agents/poppy/client_registry.js

@@ -0,0 +1,226 @@
+/**
+ * Identidade do personal agent no Poppy (§4.1): o `client_id` é uma URL HTTPS
+ * que devolve o documento de metadata do agente (OAuth Client ID Metadata
+ * Document). Buscamos (à prova de SSRF), validamos, guardamos em cache e
+ * importamos as chaves públicas do `jwks_uri`.
+ */
+import { createLocalJWKSet } from 'jose';
+import { PoppyError } from './errors.js';
+import { insecureDevFetchJson, SafeFetchError, safeFetchJson, } from './safe_fetch.js';
+const MIN_TTL_MS = 60 * 1000;
+const MAX_TTL_MS = 24 * 3600 * 1000;
+const DEFAULT_TTL_MS = 3600 * 1000;
+const FAILURE_TTL_MS = 60 * 1000;
+const MAX_CACHED = 1000;
+/** Releitura do JWKS quando o `kid` não está no conjunto em cache — no máximo a cada 30 s. */
+const JWKS_REFRESH_COOLDOWN_MS = 30 * 1000;
+function hostOf(url) {
+    try {
+        return new URL(url).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function isHttpsUrl(value, allowHttp = false) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const url = new URL(value);
+        const schemeOk = url.protocol === 'https:' || (allowHttp && url.protocol === 'http:');
+        return schemeOk && !url.username && !url.password && !url.hash;
+    }
+    catch {
+        return false;
+    }
+}
+function ttlFrom(maxAge) {
+    if (maxAge === null)
+        return DEFAULT_TTL_MS;
+    return Math.min(MAX_TTL_MS, Math.max(MIN_TTL_MS, maxAge * 1000));
+}
+function setBounded(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_CACHED)
+        map.delete(map.keys().next().value);
+}
+/** Valida um documento de metadata e devolve os campos usados. Lança `invalid_client`. */
+export function validateClientMetadata(fetchedFrom, doc, options = {}) {
+    const allowHttp = options.allowHttp === true;
+    const bad = (why) => new PoppyError('invalid_client', `client metadata: ${why}`);
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        throw bad('not a JSON object');
+    const d = doc;
+    if (d.client_id !== fetchedFrom)
+        throw bad('client_id must equal the URL it was fetched from');
+    const host = hostOf(fetchedFrom);
+    if (!isHttpsUrl(d.jwks_uri, allowHttp) || hostOf(d.jwks_uri) !== host) {
+        throw bad('jwks_uri must be an HTTPS URL on the same domain as client_id');
+    }
+    const redirects = d.redirect_uris ?? [];
+    if (!Array.isArray(redirects))
+        throw bad('redirect_uris must be an array');
+    for (const uri of redirects) {
+        if (!isHttpsUrl(uri, allowHttp) || hostOf(uri) !== host) {
+            throw bad('every redirect_uri must be an HTTPS URL on the same domain as client_id');
+        }
+    }
+    if (d.token_endpoint_auth_method !== 'private_key_jwt') {
+        throw bad('token_endpoint_auth_method must be private_key_jwt');
+    }
+    if (d.jwks !== undefined)
+        throw bad('keys are published at jwks_uri only');
+    const name = typeof d.client_name === 'string' && d.client_name.trim() ? d.client_name : host;
+    const extensions = d.extensions && typeof d.extensions === 'object' && !Array.isArray(d.extensions)
+        ? d.extensions
+        : {};
+    return {
+        clientId: fetchedFrom,
+        name: name.slice(0, 200),
+        logoUri: isHttpsUrl(d.logo_uri, allowHttp) ? d.logo_uri : null,
+        jwksUri: d.jwks_uri,
+        redirectUris: redirects,
+        extensions,
+    };
+}
+/** Só chaves públicas (§4.1) e pelo menos uma. */
+function validateJwks(doc) {
+    const keys = doc?.keys;
+    if (!Array.isArray(keys) || keys.length === 0) {
+        throw new PoppyError('invalid_client', 'jwks_uri must serve a non-empty JWK set');
+    }
+    for (const key of keys) {
+        if (!key || typeof key !== 'object')
+            throw new PoppyError('invalid_client', 'invalid JWK');
+        const k = key;
+        if ('d' in k || 'p' in k || 'q' in k || k.kty === 'oct') {
+            throw new PoppyError('invalid_client', 'jwks_uri must contain only public keys');
+        }
+    }
+    return { keys: keys };
+}
+/**
+ * Resolve e valida agentes pelo `client_id`, com cache (respeita `max-age`,
+ * entre 1 min e 24 h; falhas ficam 1 min em cache para que o mesmo `client_id`
+ * não vire uma busca de saída por request).
+ */
+export class PoppyClientRegistry {
+    #cfg;
+    #fetch;
+    #now;
+    #clients = new Map();
+    #jwks = new Map();
+    constructor(cfg, options = {}) {
+        this.#cfg = cfg;
+        this.#fetch =
+            options.fetchJson ??
+                (cfg.allowInsecureClientIds
+                    ? (url) => insecureDevFetchJson(url)
+                    : (url) => safeFetchJson(url));
+        this.#now = options.now ?? Date.now;
+    }
+    /**
+     * O agente, ou `invalid_client`: `client_id` não é HTTPS, bloqueado, não
+     * registrado (quando o app exige registro), metadata inválida/inalcançável.
+     */
+    async resolve(clientId) {
+        if (!isHttpsUrl(clientId, this.#cfg.allowInsecureClientIds)) {
+            throw new PoppyError('invalid_client', 'client_id must be an HTTPS URL');
+        }
+        if (await this.#cfg.clients.isBlocked(clientId)) {
+            throw new PoppyError('invalid_client', 'client_id is blocked');
+        }
+        if (this.#cfg.clients.requireRegistration &&
+            !(await this.#cfg.clients.isRegistered(clientId))) {
+            throw new PoppyError('invalid_client', 'client_id is not registered');
+        }
+        const meta = await this.#metadata(clientId);
+        return { ...meta, keys: this.#keySet(meta.jwksUri) };
+    }
+    /** Nome de exibição sem falhar (console de conta): metadata em cache/buscada, ou o host. */
+    async displayName(clientId) {
+        try {
+            return (await this.#metadata(clientId)).name;
+        }
+        catch {
+            return hostOf(clientId) ?? clientId;
+        }
+    }
+    #metadata(clientId) {
+        const now = this.#now();
+        const cached = this.#clients.get(clientId);
+        if (cached && cached.expiresAt > now)
+            return cached.value;
+        const entry = {
+            value: Promise.resolve(null),
+            expiresAt: now + FAILURE_TTL_MS,
+        };
+        entry.value = (async () => {
+            let fetched;
+            try {
+                fetched = await this.#fetch(clientId);
+            }
+            catch (error) {
+                const why = error instanceof SafeFetchError ? error.message : 'unreachable';
+                throw new PoppyError('invalid_client', `client metadata: ${why}`);
+            }
+            const meta = validateClientMetadata(clientId, fetched.body, {
+                allowHttp: this.#cfg.allowInsecureClientIds,
+            });
+            entry.expiresAt = this.#now() + ttlFrom(fetched.maxAge);
+            return meta;
+        })();
+        entry.value.catch(() => {
+            entry.expiresAt = this.#now() + FAILURE_TTL_MS;
+        });
+        setBounded(this.#clients, clientId, entry);
+        return entry.value;
+    }
+    #fetchJwks(jwksUri, force) {
+        const now = this.#now();
+        const cached = this.#jwks.get(jwksUri);
+        if (cached && cached.expiresAt > now && !force)
+            return cached.value;
+        if (cached && force && now - cached.fetchedAt < JWKS_REFRESH_COOLDOWN_MS)
+            return cached.value;
+        const entry = {
+            value: Promise.resolve({ keys: [] }),
+            expiresAt: now + FAILURE_TTL_MS,
+            fetchedAt: now,
+        };
+        entry.value = (async () => {
+            let fetched;
+            try {
+                fetched = await this.#fetch(jwksUri);
+            }
+            catch (error) {
+                const why = error instanceof SafeFetchError ? error.message : 'unreachable';
+                throw new PoppyError('invalid_client', `jwks_uri: ${why}`);
+            }
+            const jwks = validateJwks(fetched.body);
+            entry.expiresAt = this.#now() + ttlFrom(fetched.maxAge);
+            return jwks;
+        })();
+        entry.value.catch(() => {
+            entry.expiresAt = this.#now() + FAILURE_TTL_MS;
+        });
+        setBounded(this.#jwks, jwksUri, entry);
+        return entry.value;
+    }
+    /** `JWTVerifyGetKey` que relê o JWKS uma vez quando o `kid` é desconhecido (rotação). */
+    #keySet(jwksUri) {
+        return async (header, token) => {
+            const jwks = await this.#fetchJwks(jwksUri, false);
+            try {
+                return await createLocalJWKSet(jwks)(header, token);
+            }
+            catch (error) {
+                const refreshed = await this.#fetchJwks(jwksUri, true);
+                if (refreshed === jwks)
+                    throw error;
+                return createLocalJWKSet(refreshed)(header, token);
+            }
+        };
+    }
+}