@adonis-agora/authkit-server 0.86.0 → 0.87.0

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

@@ -1,11 +1,15 @@
-/** Scopes amplos definidos pelo protocolo (§4.4). */
-export const POPPY_READ = 'poppy:read';
-export const POPPY_WRITE = 'poppy:write';
-/** Descrições default dos scopes do protocolo — o que a tela de consentimento mostra. */
-export const POPPY_SCOPE_DESCRIPTIONS = {
-    [POPPY_READ]: 'View your account information, such as orders and bookings',
-    [POPPY_WRITE]: 'Make changes on your account, such as exchanging an item or updating a booking',
-};
+/** Parâmetros que um campo do Mediated Sign-In não pode usar (extensão, §2). */
+const RESERVED_FIELDS = new Set([
+    'grant_type',
+    'scope',
+    'resource',
+    'client_id',
+    'client_secret',
+    'client_assertion',
+    'client_assertion_type',
+    'sign_in_id',
+    'one_time_code',
+]);
 const SCOPE_ID = /^[\x21\x23-\x5B\x5D-\x7E]+$/; // RFC 6749 §3.3 scope-token
 const DOMAIN = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
 function fail(message) {
@@ -30,11 +34,6 @@ function absoluteUrl(value, what) {
         fail(`${what} precisa ser http(s) (recebeu "${value}").`);
     }
 }
-/** `www.example.com` → `example.com`, minúsculo. */
-export function stripWww(host) {
-    const lower = host.toLowerCase().replace(/\.$/, '');
-    return lower.startsWith('www.') ? lower.slice(4) : lower;
-}
 export function normalizePoppyPrefix(prefix) {
     const trimmed = (prefix ?? '/poppy').trim().replace(/\/+$/, '');
     if (!trimmed)
@@ -70,30 +69,27 @@ export function resolvePoppyConfig(input, fallbackScopes) {
     const org = input.organization;
     if (!org?.name?.trim())
         fail('organization.name é obrigatório.');
-    const domains = [org.domain, ...(org.aliases ?? [])].map((d) => stripWww(d ?? ''));
+    // Domínios comparados só ignorando caixa, sem nenhuma outra normalização (§3.1).
+    const domains = [org.domain, ...(org.aliases ?? [])].map((d) => (d ?? '').toLowerCase().replace(/\.$/, ''));
     for (const d of domains) {
         if (!DOMAIN.test(d))
             fail(`organization — domínio inválido "${d}" (só o host, sem esquema).`);
     }
-    const customScopes = { ...(input.scopes ?? fallbackScopes ?? {}) };
-    for (const id of Object.keys(customScopes)) {
+    const scopes = { ...(input.scopes ?? fallbackScopes ?? {}) };
+    for (const id of Object.keys(scopes)) {
         if (!SCOPE_ID.test(id))
             fail(`scopes — id inválido "${id}" (sem espaços/aspas).`);
-        if (id.startsWith('poppy:')) {
-            fail(`scopes — "${id}": nomes com "poppy:" são reservados ao protocolo (§4.4).`);
-        }
     }
-    const broad = input.broadScopes !== false;
-    const scopes = {
-        ...(broad
-            ? {
-                [POPPY_READ]: input.broadScopeDescriptions?.[POPPY_READ] ?? POPPY_SCOPE_DESCRIPTIONS[POPPY_READ],
-                [POPPY_WRITE]: input.broadScopeDescriptions?.[POPPY_WRITE] ?? POPPY_SCOPE_DESCRIPTIONS[POPPY_WRITE],
-            }
-            : {}),
-        ...customScopes,
-    };
     const all = Object.keys(scopes);
+    const scopeHints = { ...(input.scopeHints ?? {}) };
+    for (const [id, hint] of Object.entries(scopeHints)) {
+        if (!['none', 'reversible', 'irreversible'].includes(hint?.changes)) {
+            fail(`scopeHints.${id}.changes precisa ser none, reversible ou irreversible.`);
+        }
+        if (typeof hint.personal_data !== 'boolean') {
+            fail(`scopeHints.${id}.personal_data é obrigatório (boolean).`);
+        }
+    }
     const signInInput = input.signIn ?? {};
     let mediated = null;
     if (signInInput.mediated) {
@@ -106,13 +102,18 @@ export function resolvePoppyConfig(input, fallbackScopes) {
             if (!f?.name || !f.label || typeof f.secret !== 'boolean') {
                 fail('signIn.mediated.fields — cada campo precisa de name, label e secret.');
             }
+            if (RESERVED_FIELDS.has(f.name)) {
+                fail(`signIn.mediated.fields — "${f.name}" é um parâmetro reservado.`);
+            }
             if (names.has(f.name))
                 fail(`signIn.mediated.fields — campo duplicado "${f.name}".`);
             names.add(f.name);
         }
         if (typeof m.verify !== 'function')
             fail('signIn.mediated.verify é obrigatório.');
-        const mediatedScopes = typeScopes({ scopes: m.scopes ?? (broad ? [POPPY_READ] : all) }, all, 'mediated').scopes;
+        if (!Array.isArray(m.scopes))
+            fail('signIn.mediated.scopes é obrigatório.');
+        const mediatedScopes = typeScopes({ scopes: m.scopes }, all, 'mediated').scopes;
         mediated = {
             fields: m.fields.map((f) => ({ name: f.name, label: f.label, secret: f.secret })),
             scopes: mediatedScopes,
@@ -123,7 +124,7 @@ export function resolvePoppyConfig(input, fallbackScopes) {
         };
     }
     if (all.length === 0 && (signInInput.direct !== false || signInInput.device !== false)) {
-        fail('nenhum scope: com broadScopes: false, declare `scopes`.');
+        fail('nenhum scope: declare `scopes` ou desligue signIn.direct e signIn.device.');
     }
     for (const entry of input.agent?.protocols ?? []) {
         if (!entry.type)
@@ -131,6 +132,9 @@ export function resolvePoppyConfig(input, fallbackScopes) {
         absoluteUrl(entry.endpoint, 'agent.protocols[].endpoint');
         if (entry.resource)
             absoluteUrl(entry.resource, 'agent.protocols[].resource');
+        if (entry.access && entry.access !== 'session' && entry.access !== 'signed_in') {
+            fail('agent.protocols[].access precisa ser session ou signed_in.');
+        }
     }
     for (const api of input.apis ?? []) {
         if (!api.type)
@@ -141,6 +145,14 @@ export function resolvePoppyConfig(input, fallbackScopes) {
         if (typeof api.description !== 'string')
             fail('apis[].description é obrigatório.');
     }
+    if (input.feedback)
+        absoluteUrl(input.feedback.endpoint, 'feedback.endpoint');
+    if (input.excludedTasks)
+        absoluteUrl(input.excludedTasks.url, 'excludedTasks.url');
+    const redirectTo = input.web ? (input.web.redirectTo ?? '/') : '/';
+    if (!redirectTo.startsWith('/') || redirectTo.startsWith('//')) {
+        fail('web.redirectTo precisa ser um path do site.');
+    }
     for (const name of Object.keys(input.extensions ?? {})) {
         if (typeof input.extensions[name]?.version !== 'string') {
             fail(`extensions.${name}.version é obrigatório (string).`);
@@ -169,7 +181,7 @@ export function resolvePoppyConfig(input, fallbackScopes) {
         organization: { name: org.name, domain: domains[0], aliases: domains.slice(1) },
         prefix: normalizePoppyPrefix(input.prefix),
         scopes,
-        customScopes,
+        scopeHints,
         signIn: {
             direct: typeScopes(signInInput.direct, all, 'direct'),
             device: typeScopes(signInInput.device, all, 'device'),
@@ -177,9 +189,15 @@ export function resolvePoppyConfig(input, fallbackScopes) {
         },
         agent: input.agent?.protocols?.length ? { protocols: [...input.agent.protocols] } : null,
         apis: [...(input.apis ?? [])],
+        feedback: input.feedback ?? null,
+        excludedTasks: input.excludedTasks ?? null,
         web: input.web === false
             ? null
-            : { browserSession: input.web?.browserSession !== false, login: input.web?.login },
+            : {
+                browserSession: input.web?.browserSession !== false,
+                login: input.web?.login,
+                redirectTo,
+            },
         extensions: { ...(input.extensions ?? {}) },
         clients: {
             requireRegistration: input.clients?.requireRegistration === true,
@@ -189,14 +207,16 @@ export function resolvePoppyConfig(input, fallbackScopes) {
             blockedList: listOf(input.clients?.blocked),
         },
         allowInsecureClientIds,
-        sessionTokenTtl: positive(input.sessionTokenTtl, 3600, 'sessionTokenTtl'),
-        accountTokenTtl: positive(input.accountTokenTtl, 30 * 24 * 3600, 'accountTokenTtl'),
+        accessTokenTtl: positive(input.accessTokenTtl, 3600, 'accessTokenTtl'),
+        refreshTokenTtl: positive(input.refreshTokenTtl, 30 * 24 * 3600, 'refreshTokenTtl'),
         sessionTtl: positive(input.sessionTtl, 30 * 24 * 3600, 'sessionTtl'),
         authorizationCodeTtl: positive(input.authorizationCodeTtl, 60, 'authorizationCodeTtl'),
         deviceCodeTtl: positive(input.deviceCodeTtl, 600, 'deviceCodeTtl'),
         pollInterval: positive(input.pollInterval, 5, 'pollInterval'),
         assertionMaxLifetime: positive(input.assertionMaxLifetime, 300, 'assertionMaxLifetime'),
+        sessionJwt: { maxAge: positive(input.sessionJwt?.maxAge, 60, 'sessionJwt.maxAge') },
         dpop: {
+            required: input.dpop?.required === true,
             requireNonce: input.dpop?.requireNonce === true,
             maxAge: positive(input.dpop?.maxAge, 60, 'dpop.maxAge'),
             algorithms: [...dpopAlgs],

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

@@ -19,7 +19,7 @@ export interface DpopNonceSource {
  * Nonces sem estado: `base64url(ts).base64url(hmac(ts))`, válidos por
  * `ttlSeconds` (default 300). Qualquer instância com o mesmo segredo valida.
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export declare function hmacNonceSource(secret: Buffer | string, options?: {
@@ -56,6 +56,6 @@ export interface VerifyDpopInput {
     now?: () => number;
 }
 /**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
  */
 export declare function verifyDpopProof(input: VerifyDpopInput): Promise<DpopResult>;

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

@@ -1,6 +1,6 @@
 /**
  * Verificação de provas DPoP (RFC 9449) — utilitário genérico para o token
- * endpoint e para resource servers (§4.3 do Poppy).
+ * endpoint e para resource servers (§4.5 do Poppy).
  *
  * Confere: um único header `DPoP`; `typ` `dpop+jwt`; algoritmo permitido; `jwk`
  * público no header e a assinatura com ele; `jti`, `htm`, `htu` (sem query nem
@@ -15,7 +15,7 @@ import { replayKey } from './replay.js';
  * Nonces sem estado: `base64url(ts).base64url(hmac(ts))`, válidos por
  * `ttlSeconds` (default 300). Qualquer instância com o mesmo segredo valida.
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export function hmacNonceSource(secret, options = {}) {
@@ -66,7 +66,7 @@ function failure(error, description) {
     return { ok: false, error, description };
 }
 /**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
  */
 export async function verifyDpopProof(input) {
     const raw = input.proof;

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

@@ -1,11 +1,11 @@
 import { type AuthAccount } from '../../accounts/account_store.js';
 import type { PoppyMediatedConfigInput } from './config.js';
 export interface PoppyEmailCodeSignInOptions {
-    /** Scopes que este sign-in pode conceder. Default: `['poppy:read']` (o default do Mediated). */
-    scopes?: string[];
+    /** Scopes que este sign-in pode conceder. */
+    scopes: string[];
     /** Validade do código, em segundos. Default: 600. */
     codeTtl?: number;
-    /** Tentativas de código antes de `failed`. Default: 5. */
+    /** Tentativas de código antes de `invalid_grant`. Default: 5. */
     maxCodeAttempts?: number;
     /**
      * Quem pode entrar por aqui (ex.: só pacientes, não profissionais). `false` = recebe a
@@ -24,4 +24,4 @@ export interface PoppyEmailCodeSignInOptions {
 }
 /** `ana.souza@gmail.com` → `a***@gmail.com`: o bastante para a pessoa reconhecer. */
 export declare function maskEmail(email: string): string;
-export declare function poppyEmailCodeSignIn(options?: PoppyEmailCodeSignInOptions): PoppyMediatedConfigInput;
+export declare function poppyEmailCodeSignIn(options: PoppyEmailCodeSignInOptions): PoppyMediatedConfigInput;

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

@@ -1,14 +1,14 @@
 /**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
  *
- * Mediated Sign-In pronto (§4.7): o agente pede o e-mail da conta, o authkit manda
+ * Mediated Sign-In pronto (extensão `mediated-sign-in`): o agente pede o e-mail da conta, o authkit manda
  * um código de 6 dígitos para ele e o agente devolve o código. Usa as contas
  * (`accountStore`) e o e-mail (hook `mail.onPoppySignInCode` ou o mailer default)
  * do próprio authkit — o app só liga:
  *
  * ```ts
  * personalAgents: {
- *   poppy: { signIn: { mediated: poppyEmailCodeSignIn() } },
+ *   poppy: { signIn: { mediated: poppyEmailCodeSignIn({ scopes: ['orders:read'] }) } },
  * }
  * ```
  *
@@ -33,7 +33,7 @@ export function maskEmail(email) {
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const HOUR_MS = 3600 * 1000;
 const MAX_TRACKED = 10_000;
-export function poppyEmailCodeSignIn(options = {}) {
+export function poppyEmailCodeSignIn(options) {
     const positive = (value, fallback, what) => {
         if (value === undefined)
             return fallback;
@@ -85,7 +85,7 @@ export function poppyEmailCodeSignIn(options = {}) {
     };
     return {
         fields: [{ name: 'email', label: options.label ?? 'Email address', secret: false }],
-        ...(options.scopes ? { scopes: options.scopes } : {}),
+        scopes: options.scopes,
         codeTtl,
         maxCodeAttempts,
         async verify({ credentials, clientId, ctx }) {

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

@@ -1,17 +1,22 @@
 /**
- * Erros OAuth do Poppy (§4.2, §4.4, §4.6, RFC 6749 §5.2, RFC 8628 §3.5, RFC 9449)
+ * Erros OAuth do Poppy (§4.7, RFC 6749 §5.2, RFC 8628 §3.5, RFC 9449, extensão Mediated Sign-In)
  * — viram `{ error, error_description }` com o status da spec.
  */
-export type PoppyErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_session' | 'account_mismatch' | 'invalid_dpop_proof' | 'use_dpop_nonce' | 'rate_limited' | 'invalid_scope' | 'invalid_target' | 'unsupported_grant_type' | 'unsupported_token_type' | 'unauthorized_client' | 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
+export type PoppyErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_session' | 'invalid_dpop_proof' | 'use_dpop_nonce'
+/** Interno: HTTP 429 com `Retry-After`, sem corpo (§5.6). */
+ | 'too_many_requests' | 'code_required' | 'invalid_scope' | 'invalid_target' | 'unsupported_grant_type' | 'unsupported_token_type' | 'unauthorized_client' | 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
 export declare class PoppyError extends Error {
     readonly code: PoppyErrorCode;
     readonly description: string;
     readonly status: number;
     /** Headers extras da resposta (`DPoP-Nonce`, `Retry-After`). */
     readonly headers: Record<string, string>;
+    /** Campos extras do corpo (`sign_in_id`, `sent_to`, `expires_in` do `code_required`). */
+    readonly extra: Record<string, unknown>;
     constructor(code: PoppyErrorCode, description: string, options?: {
         status?: number;
         headers?: Record<string, string>;
+        extra?: Record<string, unknown>;
     });
     toJSON(): {
         error: PoppyErrorCode;

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

@@ -1,6 +1,6 @@
 const STATUS = {
     invalid_client: 401,
-    rate_limited: 429,
+    too_many_requests: 429,
 };
 export class PoppyError extends Error {
     code;
@@ -8,6 +8,8 @@ export class PoppyError extends Error {
     status;
     /** Headers extras da resposta (`DPoP-Nonce`, `Retry-After`). */
     headers;
+    /** Campos extras do corpo (`sign_in_id`, `sent_to`, `expires_in` do `code_required`). */
+    extra;
     constructor(code, description, options = {}) {
         super(description);
         this.code = code;
@@ -15,8 +17,9 @@ export class PoppyError extends Error {
         this.name = 'PoppyError';
         this.status = options.status ?? STATUS[code] ?? 400;
         this.headers = options.headers ?? {};
+        this.extra = options.extra ?? {};
     }
     toJSON() {
-        return { error: this.code, error_description: this.description };
+        return { error: this.code, error_description: this.description, ...this.extra };
     }
 }

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

@@ -1,7 +1,7 @@
 /**
- * Lado resource server do Poppy (§4.3, §6): verificar o Session Token de uma
- * request às APIs/conversas do app — e o slot GLOBAL que o `@adonis-agora/agent`
- * usa para autenticar o endpoint de conversas sem importar este pacote.
+ * Lado resource server do Poppy (§4.5, §5.3, §7): verificar o header `Poppy-Session` e o access
+ * token de uma request às APIs/conversas do app — e o slot GLOBAL que o `@adonis-agora/agent` usa
+ * para autenticar o endpoint de conversas sem importar este pacote.
  *
  * Contrato do slot (o mesmo padrão do `Symbol.for('@adonis-agora/oauth:resources')`):
  *
@@ -16,31 +16,34 @@ import type { PoppyPrincipalBase } from './config.js';
 import type { PoppyAuthError, PoppyService, PoppyVerifyOptions } from './service.js';
 /** Símbolo do slot global de autenticação Poppy. */
 export declare const POPPY_AUTHENTICATE_SLOT: unique symbol;
-/** O principal de um Session Token válido. *
-/** O principal de um Session Token válido. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
-/** O principal de um Session Token válido. *   de forma incompatível fora de majors enquanto ela for draft.
-/** O principal de um Session Token válido. */
+/**
+ * O principal de uma request verificada.
+ *
+ * @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.
+ */
 export interface PoppyPrincipal extends PoppyPrincipalBase {
     /** O que `personalAgents.poppy.toActor` devolveu, quando configurado. */
     actor?: unknown;
 }
 /**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
  */
 export type PoppyAuthResult = {
     ok: true;
     principal: PoppyPrincipal;
 } | {
     ok: false;
-    status: 401 | 403;
-    error: PoppyAuthError;
-    /** Scopes exigidos (`insufficient_scope`). */
+    status: 400 | 401 | 403 | 429;
+    /** `null`: challenge sem código (falta o access token, §7) ou limite de taxa (§5.6). */
+    error: PoppyAuthError | null;
+    /** Scopes exigidos (challenge e `insufficient_scope`). */
     scope?: string;
-    /** Valor pronto do header `WWW-Authenticate`. */
-    wwwAuthenticate: string;
+    /** Valor pronto do header `WWW-Authenticate`; `null` em `invalid_session` e no 429. */
+    wwwAuthenticate: string | null;
     /** Texto para logs/corpo — nunca contém o token. */
     description: string;
-    /** Headers extras a devolver (`DPoP-Nonce`). */
+    /** Headers extras a devolver (`DPoP-Nonce`, `Retry-After`). */
     headers: Record<string, string>;
 };
 /** Request no formato do slot (sem `HttpContext`). */
@@ -54,10 +57,10 @@ export type PoppyAuthenticate = (request: PoppySlotRequest, options?: PoppyVerif
 /** URL pública da request: atrás de proxy TLS, o esquema segue o do issuer. */
 export declare function publicRequestUrl(ctx: HttpContext, poppy: PoppyService): string;
 /**
- * Verifica o Session Token de uma request (DPoP; Bearer só no MCP para o qual
- * foi emitido). Aceita o `HttpContext` ou `{ method, url, headers }`.
+ * Verifica o header `Poppy-Session` de uma request e, se houver, o access token. Aceita o
+ * `HttpContext` ou `{ method, url, headers }`.
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export declare function verifyPoppyRequest(input: HttpContext | PoppySlotRequest, options?: PoppyVerifyOptions): Promise<PoppyAuthResult>;
@@ -65,22 +68,24 @@ export declare function verifyPoppyRequest(input: HttpContext | PoppySlotRequest
 export declare function writePoppyAuthError(ctx: HttpContext, result: Extract<PoppyAuthResult, {
     ok: false;
 }>): void;
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. *
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. *   de forma incompatível fora de majors enquanto ela for draft.
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. */
+/**
+ * O principal Poppy da request — preenchido por {@link poppyAuth}.
+ *
+ * @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.
+ */
 export declare function poppyOf(ctx: HttpContext): PoppyPrincipal | null;
 /**
- * Middleware das APIs/rotas que aceitam Session Tokens Poppy.
+ * Middleware das APIs/rotas que usam a Session Poppy.
  *
  * ```ts
  * router.post('/orders/:id/exchanges', [Orders, 'exchange'])
- *   .use(poppyAuth({ scopes: ['poppy:write'] }))
+ *   .use(poppyAuth({ scopes: ['orders:write'] }))
  * ```
  *
  * Isente essas rotas do CSRF (são chamadas por agentes, sem navegador).
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export declare function poppyAuth(options?: PoppyVerifyOptions): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
@@ -89,7 +94,7 @@ export declare function poppyAuth(options?: PoppyVerifyOptions): (ctx: HttpConte
  * `Symbol.for('@adonis-agora/poppy:issuer')`). Chamado no boot do provider
  * quando `personalAgents.poppy` está no config.
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export declare function installPoppySlots(issuer: string): void;

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

@@ -19,10 +19,10 @@ function requestFromCtx(ctx, poppy) {
 }
 const NOT_ENABLED = {
     ok: false,
-    status: 401,
-    error: 'invalid_token',
+    status: 400,
+    error: 'invalid_session',
     description: 'Poppy is not enabled',
-    wwwAuthenticate: 'DPoP error="invalid_token"',
+    wwwAuthenticate: null,
     headers: {},
 };
 async function verifyWith(poppy, input, options) {
@@ -43,10 +43,10 @@ async function poppyFromBootedApp() {
     return runtime?.poppy ?? null;
 }
 /**
- * Verifica o Session Token de uma request (DPoP; Bearer só no MCP para o qual
- * foi emitido). Aceita o `HttpContext` ou `{ method, url, headers }`.
+ * Verifica o header `Poppy-Session` de uma request e, se houver, o access token. Aceita o
+ * `HttpContext` ou `{ method, url, headers }`.
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export async function verifyPoppyRequest(input, options = {}) {
@@ -64,36 +64,40 @@ export async function verifyPoppyRequest(input, options = {}) {
 }
 /** Escreve a resposta de erro de um {@link PoppyAuthResult} recusado. */
 export function writePoppyAuthError(ctx, result) {
-    ctx.response.header('WWW-Authenticate', result.wwwAuthenticate);
+    if (result.wwwAuthenticate)
+        ctx.response.header('WWW-Authenticate', result.wwwAuthenticate);
     for (const [k, v] of Object.entries(result.headers))
         ctx.response.header(k, v);
     ctx.response.header('Cache-Control', 'no-store');
-    return ctx.response.status(result.status).json({
-        error: result.error,
-        error_description: result.description,
-        ...(result.scope ? { scope: result.scope } : {}),
-    });
+    // Erros do access token vão no header, como no OAuth; `invalid_session` vai no corpo (§7).
+    if (result.error !== 'invalid_session')
+        return ctx.response.status(result.status).send('');
+    return ctx.response
+        .status(result.status)
+        .json({ error: result.error, error_description: result.description });
 }
 /** Guardado fora do `HttpContext` (sem augmentation — ver `augmentation_isolation.spec.ts`). */
 const principals = new WeakMap();
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. *
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. *   de forma incompatível fora de majors enquanto ela for draft.
-/** O principal Poppy da request — preenchido por {@link poppyAuth}. */
+/**
+ * O principal Poppy da request — preenchido por {@link poppyAuth}.
+ *
+ * @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.
+ */
 export function poppyOf(ctx) {
     return principals.get(ctx) ?? null;
 }
 /**
- * Middleware das APIs/rotas que aceitam Session Tokens Poppy.
+ * Middleware das APIs/rotas que usam a Session Poppy.
  *
  * ```ts
  * router.post('/orders/:id/exchanges', [Orders, 'exchange'])
- *   .use(poppyAuth({ scopes: ['poppy:write'] }))
+ *   .use(poppyAuth({ scopes: ['orders:write'] }))
  * ```
  *
  * Isente essas rotas do CSRF (são chamadas por agentes, sem navegador).
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export function poppyAuth(options = {}) {
@@ -110,7 +114,7 @@ export function poppyAuth(options = {}) {
  * `Symbol.for('@adonis-agora/poppy:issuer')`). Chamado no boot do provider
  * quando `personalAgents.poppy` está no config.
  *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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.
  */
 export function installPoppySlots(issuer) {

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

@@ -77,6 +77,12 @@ export function isBlockedAddress(ip) {
         return true; // ::
     if (g.slice(0, 7).every((x) => x === 0) && g[7] === 1)
         return true; // ::1
+    // IPv4-translated (::ffff:0:a.b.c.d) e NAT64 (64:ff9b::a.b.c.d) também chegam a um IPv4.
+    const translated = g.slice(0, 4).every((x) => x === 0) && g[4] === 0xffff && g[5] === 0;
+    const nat64 = g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((x) => x === 0);
+    if (translated || nat64) {
+        return isBlockedAddress(`${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`);
+    }
     // IPv4-mapped (::ffff:a.b.c.d) e IPv4-compatible: decide pelo IPv4.
     if (g.slice(0, 5).every((x) => x === 0) && (g[5] === 0xffff || g[5] === 0)) {
         const v4 = `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
@@ -160,7 +166,7 @@ export function safeFetchJson(url, options = {}) {
         };
         const req = httpsRequest(parsed, {
             method: 'GET',
-            headers: { accept: 'application/json', 'user-agent': 'authkit-poppy/0.1' },
+            headers: { accept: 'application/json', 'user-agent': 'authkit-poppy/0.3' },
             lookup: guardedLookup,
             // IP literal: o `lookup` não roda — já conferido acima.
         }, (res) => {
@@ -229,7 +235,7 @@ export async function insecureDevFetchJson(url, options = {}) {
     try {
         res = await fetch(parsed, {
             redirect: 'manual',
-            headers: { accept: 'application/json', 'user-agent': 'authkit-poppy/0.1 (insecure-dev)' },
+            headers: { accept: 'application/json', 'user-agent': 'authkit-poppy/0.3 (insecure-dev)' },
             signal: AbortSignal.timeout(timeoutMs),
         });
     }