@adonis-agora/authkit-server 0.86.0 → 0.88.0

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

@@ -0,0 +1,30 @@
+import type { PoppyClient } from './client_registry.js';
+export declare const SESSION_JWT_TYP = "poppy-session+jwt";
+export declare const DELEGATION_TYP = "pap-delegation+jwt";
+export declare class SessionJwtError extends Error {
+}
+export interface VerifiedSessionJwt {
+    clientId: string;
+    sid: string;
+    userId: string;
+    agentId: string | null;
+    jti: string;
+    iat: number;
+}
+export interface VerifySessionJwtInput {
+    /** Valor do(s) header(s) `Poppy-Session`. */
+    header: string | string[] | undefined;
+    method: string;
+    url: string;
+    /** Access token da request, ou `null`. */
+    accessToken: string | null;
+    /** O identificador da empresa: o issuer (§3.2). */
+    audience: string;
+    /** Janela de aceitação do `iat`, em segundos. */
+    maxAge: number;
+    /** Resolve o agente pelo `iss` (client metadata + `jwks_uri`). */
+    resolveClient: (clientId: unknown) => Promise<PoppyClient>;
+    now: Date;
+}
+/** Verifica o JWT (§5.3, passos 1–3). Lança {@link SessionJwtError}. */
+export declare function verifySessionJwt(input: VerifySessionJwtInput): Promise<VerifiedSessionJwt>;

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

@@ -0,0 +1,133 @@
+/**
+ * O header `Poppy-Session` (Draft 0.3, §5.2–§5.3): um JWT que o personal agent assina para uma
+ * request, com uma chave delegada. Uma chave do `jwks_uri` assina a delegação
+ * (`pap-delegation+jwt`), que vai no header `pap_dlg` do JWT e atesta a chave delegada em `cnf.jwk`.
+ *
+ * Só as checagens do JWT em si: o `client_id` do token, a Session e o replay ficam no `PoppyService`.
+ */
+import { calculateJwkThumbprint, decodeJwt, decodeProtectedHeader, importJWK, jwtVerify, } from 'jose';
+import { accessTokenHash, normalizeHtu } from './dpop.js';
+export const SESSION_JWT_TYP = 'poppy-session+jwt';
+export const DELEGATION_TYP = 'pap-delegation+jwt';
+/** Delegação: `ES256` obrigatório; `PS384` permite a assinatura cega (§5.2, §10.7). */
+const DELEGATION_ALGS = ['ES256', 'PS384'];
+const DELEGATION_MAX_LIFETIME_S = 24 * 3600;
+const CLOCK_SKEW_S = 5;
+/** Mesmos caracteres dos Conversation IDs (§8.2). */
+const SESSION_ID = /^[A-Za-z0-9_-]{1,256}$/;
+/** Tamanho da coluna `user_id`/`agent_id`. */
+const MAX_ID_LENGTH = 255;
+export class SessionJwtError extends Error {
+}
+const fail = (why) => new SessionJwtError(why);
+/** Passos 1–4 de "Delegated keys" (§5.2): devolve a chave delegada, já conferida. */
+async function verifyDelegation(delegation, client, now) {
+    if (typeof delegation !== 'string' || !delegation)
+        throw fail('pap_dlg is required');
+    let payload;
+    try {
+        ({ payload } = await jwtVerify(delegation, client.keys, {
+            algorithms: DELEGATION_ALGS,
+            typ: DELEGATION_TYP,
+            issuer: client.clientId,
+            currentDate: now,
+            clockTolerance: CLOCK_SKEW_S,
+            requiredClaims: ['iat', 'exp', 'jti'],
+        }));
+    }
+    catch {
+        throw fail('delegation verification failed');
+    }
+    if (payload.exp - payload.iat > DELEGATION_MAX_LIFETIME_S) {
+        throw fail('delegation lasts more than 24 hours');
+    }
+    const jwk = payload.cnf?.jwk;
+    if (!jwk || jwk.kty !== 'EC' || jwk.crv !== 'P-256' || 'd' in jwk) {
+        throw fail('cnf.jwk must be a public P-256 key');
+    }
+    return { jwk: jwk, exp: payload.exp };
+}
+/** Verifica o JWT (§5.3, passos 1–3). Lança {@link SessionJwtError}. */
+export async function verifySessionJwt(input) {
+    const token = input.header;
+    if (typeof token !== 'string' || !token)
+        throw fail('exactly one Poppy-Session header required');
+    let header;
+    let iss;
+    try {
+        header = decodeProtectedHeader(token);
+        iss = decodeJwt(token).iss;
+    }
+    catch {
+        throw fail('malformed Session JWT');
+    }
+    if (header.typ !== SESSION_JWT_TYP)
+        throw fail(`typ must be ${SESSION_JWT_TYP}`);
+    if (header.alg !== 'ES256')
+        throw fail('alg must be ES256');
+    let client;
+    try {
+        client = await input.resolveClient(iss);
+    }
+    catch {
+        throw fail('the client_id was refused');
+    }
+    const delegation = await verifyDelegation(header.pap_dlg, client, input.now);
+    if (header.kid !== (await calculateJwkThumbprint(delegation.jwk, 'sha256'))) {
+        throw fail('kid must be the thumbprint of the delegated key');
+    }
+    let claims;
+    try {
+        const key = await importJWK(delegation.jwk, 'ES256');
+        ({ payload: claims } = await jwtVerify(token, key, {
+            algorithms: ['ES256'],
+            typ: SESSION_JWT_TYP,
+            issuer: client.clientId,
+            currentDate: input.now,
+        }));
+    }
+    catch {
+        throw fail('Session JWT signature verification failed');
+    }
+    if (typeof claims.aud !== 'string' || claims.aud !== input.audience) {
+        throw fail('aud must be the Company identifier, as a single string');
+    }
+    if (claims.htm !== input.method.toUpperCase())
+        throw fail('htm does not match the request');
+    const htu = typeof claims.htu === 'string' ? normalizeHtu(claims.htu) : null;
+    if (htu === null || htu !== normalizeHtu(input.url))
+        throw fail('htu does not match the request');
+    const nowS = Math.floor(input.now.getTime() / 1000);
+    if (typeof claims.iat !== 'number' || Math.abs(nowS - claims.iat) > input.maxAge) {
+        throw fail('iat is outside the acceptance window');
+    }
+    if (claims.iat > delegation.exp)
+        throw fail('signed after the delegation expired');
+    if (typeof claims.jti !== 'string' || !claims.jti)
+        throw fail('jti is required');
+    if (typeof claims.sid !== 'string' || !SESSION_ID.test(claims.sid))
+        throw fail('invalid sid');
+    if (typeof claims.sub !== 'string' || !claims.sub || claims.sub.length > MAX_ID_LENGTH) {
+        throw fail('sub (the User ID) is required');
+    }
+    const agentId = claims.agent_id;
+    if (agentId !== undefined &&
+        (typeof agentId !== 'string' || !agentId || agentId.length > MAX_ID_LENGTH)) {
+        throw fail('invalid agent_id');
+    }
+    if (input.accessToken === null) {
+        if (claims.ath !== undefined)
+            throw fail('ath must be absent without an access token');
+    }
+    else if (claims.ath !== accessTokenHash(input.accessToken)) {
+        throw fail('ath does not match the access token');
+    }
+    return {
+        clientId: client.clientId,
+        sid: claims.sid,
+        userId: claims.sub,
+        agentId: agentId ?? null,
+        jti: claims.jti,
+        iat: claims.iat,
+    };
+}

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

@@ -1,8 +1,7 @@
 /**
- * Persistência do Poppy — tabelas LIB-OWNED (ver `schema/ensure.ts`): Sessions,
- * Session Tokens (só o hash), pedidos de sign-in (autorização Direct, códigos,
- * device codes, Mediated) e `jti` vistos. Os Account Tokens reaproveitam
- * `auth_agent_grants` + `auth_agent_refresh_tokens` (ver `DelegationStore`).
+ * Persistência do Poppy — tabelas LIB-OWNED (ver `schema/ensure.ts`): Sessions, access tokens (só o
+ * hash), pedidos de sign-in e de entrada de navegador, e `jti` vistos. Os refresh tokens
+ * reaproveitam `auth_agent_grants` + `auth_agent_refresh_tokens` (ver `DelegationStore`).
  *
  * Mesmas regras do `DelegationStore`: query builder puro, datas comparadas em JS
  * depois de buscar a linha pela chave, transições de estado atômicas por
@@ -12,12 +11,14 @@ export declare const SESSION_TABLE = "auth_poppy_sessions";
 export declare const TOKEN_TABLE = "auth_poppy_tokens";
 export declare const REQUEST_TABLE = "auth_poppy_requests";
 export interface SessionRow {
+    /** Derivado de `client_id` + `sid` (§5.3). */
     id: string;
     clientId: string;
     userId: string;
-    /** Conta a que a Session está PRESA (uma vez logada, não troca — §4.4). */
+    agentId: string | null;
+    /** Conta que a Session já usou: recusamos outra com `invalid_session` (§5.4). */
     accountId: string | null;
-    /** Grant (Account Token) com que está logada agora; `null` = deslogada. */
+    /** Colunas da Draft 0.1, sem uso: o acesso à conta não passa pela Session. */
     grantId: string | null;
     scope: string;
     expiresAt: Date;
@@ -25,21 +26,20 @@ export interface SessionRow {
     createdAt: Date;
     updatedAt: Date;
 }
+/** Access token (§4.5). */
 export interface TokenRow {
     tokenHash: string;
-    sessionId: string;
     clientId: string;
-    userId: string;
     accountId: string | null;
     grantId: string | null;
     scope: string;
     resource: string | null;
-    /** Thumbprint da chave DPoP; `null` = Bearer (só MCP). */
+    /** Thumbprint da chave DPoP; `null` = Bearer. */
     jkt: string | null;
     expiresAt: Date;
     createdAt: Date;
 }
-export type RequestKind = 'authorize' | 'device' | 'mediated';
+export type RequestKind = 'authorize' | 'device' | 'mediated' | 'browser';
 export type RequestStatus = 'pending' | 'approved' | 'denied' | 'consumed' | 'failed';
 export interface RequestRow {
     id: string;
@@ -70,19 +70,11 @@ export declare class PoppyStore {
     /** Estende a vida da Session (uso). */
     touchSession(id: string, expiresAt: Date, at: Date): Promise<void>;
     /**
-     * Loga a Session numa conta. Atômico: só se ainda estiver deslogada ou presa
-     * à MESMA conta. `false` = presa a outra conta (ou terminou) nesse meio-tempo.
+     * Registra a conta que a Session usa (§5.4). Atômico: só se nenhuma foi registrada ou é a MESMA.
+     * `false` = outra conta chegou nesse meio-tempo.
      */
-    signInSession(id: string, patch: {
-        accountId: string;
-        grantId: string;
-        scope: string;
-        expiresAt: Date;
-        at: Date;
-    }): Promise<boolean>;
-    /** Sign-out (§4.9): as Sessions logadas com o grant continuam, deslogadas. */
-    signOutSessionsOfGrant(grantId: string, at: Date): Promise<number>;
-    /** Encerra todas as Sessions de um agente (bloqueio no console): os tokens param na hora. */
+    bindSessionAccount(id: string, accountId: string, at: Date): Promise<boolean>;
+    /** Encerra todas as Sessions de um agente (bloqueio no console): param na hora. */
     endSessionsOfClient(clientId: string, at: Date): Promise<number>;
     insertToken(row: TokenRow): Promise<void>;
     findToken(hash: string): Promise<TokenRow | null>;
@@ -102,6 +94,9 @@ export declare class PoppyStore {
         codeHash?: string;
         attempts?: number;
         expiresAt?: Date;
+        clientId?: string;
+        sessionId?: string;
+        data?: Record<string, unknown>;
     }): Promise<boolean>;
     /** Conta uma tentativa errada (atômico sobre o valor lido). */
     bumpAttempts(id: string, from: number): Promise<boolean>;

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

@@ -1,8 +1,7 @@
 /**
- * Persistência do Poppy — tabelas LIB-OWNED (ver `schema/ensure.ts`): Sessions,
- * Session Tokens (só o hash), pedidos de sign-in (autorização Direct, códigos,
- * device codes, Mediated) e `jti` vistos. Os Account Tokens reaproveitam
- * `auth_agent_grants` + `auth_agent_refresh_tokens` (ver `DelegationStore`).
+ * Persistência do Poppy — tabelas LIB-OWNED (ver `schema/ensure.ts`): Sessions, access tokens (só o
+ * hash), pedidos de sign-in e de entrada de navegador, e `jti` vistos. Os refresh tokens
+ * reaproveitam `auth_agent_grants` + `auth_agent_refresh_tokens` (ver `DelegationStore`).
  *
  * Mesmas regras do `DelegationStore`: query builder puro, datas comparadas em JS
  * depois de buscar a linha pela chave, transições de estado atômicas por
@@ -35,6 +34,7 @@ function toSession(row) {
         id: row.id,
         clientId: row.client_id,
         userId: row.user_id,
+        agentId: row.agent_id ?? null,
         accountId: row.account_id ?? null,
         grantId: row.grant_id ?? null,
         scope: row.scope ?? '',
@@ -47,9 +47,7 @@ function toSession(row) {
 function toToken(row) {
     return {
         tokenHash: row.token_hash,
-        sessionId: row.session_id,
         clientId: row.client_id,
-        userId: row.user_id,
         accountId: row.account_id ?? null,
         grantId: row.grant_id ?? null,
         scope: row.scope ?? '',
@@ -103,6 +101,7 @@ export class PoppyStore {
             id: row.id,
             client_id: row.clientId,
             user_id: row.userId,
+            agent_id: row.agentId,
             account_id: row.accountId,
             grant_id: row.grantId,
             scope: row.scope,
@@ -126,33 +125,18 @@ export class PoppyStore {
             .update({ expires_at: expiresAt, updated_at: at });
     }
     /**
-     * Loga a Session numa conta. Atômico: só se ainda estiver deslogada ou presa
-     * à MESMA conta. `false` = presa a outra conta (ou terminou) nesse meio-tempo.
+     * Registra a conta que a Session usa (§5.4). Atômico: só se nenhuma foi registrada ou é a MESMA.
+     * `false` = outra conta chegou nesse meio-tempo.
      */
-    async signInSession(id, patch) {
+    async bindSessionAccount(id, accountId, at) {
         const result = await this.conn()
             .from(SESSION_TABLE)
             .where('id', id)
-            .whereNull('ended_at')
-            .where((q) => q.whereNull('account_id').orWhere('account_id', patch.accountId))
-            .update({
-            account_id: patch.accountId,
-            grant_id: patch.grantId,
-            scope: patch.scope,
-            expires_at: patch.expiresAt,
-            updated_at: patch.at,
-        });
+            .where((q) => q.whereNull('account_id').orWhere('account_id', accountId))
+            .update({ account_id: accountId, updated_at: at });
         return affected(result) > 0;
     }
-    /** Sign-out (§4.9): as Sessions logadas com o grant continuam, deslogadas. */
-    async signOutSessionsOfGrant(grantId, at) {
-        const result = await this.conn()
-            .from(SESSION_TABLE)
-            .where('grant_id', grantId)
-            .update({ grant_id: null, scope: '', updated_at: at });
-        return affected(result);
-    }
-    /** Encerra todas as Sessions de um agente (bloqueio no console): os tokens param na hora. */
+    /** Encerra todas as Sessions de um agente (bloqueio no console): param na hora. */
     async endSessionsOfClient(clientId, at) {
         const result = await this.conn()
             .from(SESSION_TABLE)
@@ -161,13 +145,15 @@ export class PoppyStore {
             .update({ ended_at: at, grant_id: null, scope: '', updated_at: at });
         return affected(result);
     }
-    // ─── session tokens ───────────────────────────────────────────────────────
+    // ─── access tokens ────────────────────────────────────────────────────────
     async insertToken(row) {
         await this.conn().table(TOKEN_TABLE).insert({
             token_hash: row.tokenHash,
-            session_id: row.sessionId,
+            // `session_id`/`user_id` são NOT NULL desde a Draft 0.1 e o schema só é aditivo; o sign-in
+            // não conhece a Session nem o User ID (§4.4).
+            session_id: '',
             client_id: row.clientId,
-            user_id: row.userId,
+            user_id: '',
             account_id: row.accountId,
             grant_id: row.grantId,
             scope: row.scope,
@@ -238,6 +224,12 @@ export class PoppyStore {
             update.attempts = patch.attempts;
         if (patch.expiresAt !== undefined)
             update.expires_at = patch.expiresAt;
+        if (patch.clientId !== undefined)
+            update.client_id = patch.clientId;
+        if (patch.sessionId !== undefined)
+            update.session_id = patch.sessionId;
+        if (patch.data !== undefined)
+            update.data = JSON.stringify(patch.data);
         const result = await this.conn()
             .from(REQUEST_TABLE)
             .where('id', id)

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

@@ -1,32 +1,39 @@
 /**
- * O cookie do site para o navegador de um personal agent (§5): login pela
- * asserção de navegador, e o acompanhamento do estado da Session a cada request.
+ * O cookie do site para o navegador de um personal agent (§6): a entrada na Session, e o
+ * acompanhamento do acesso à conta autorizado nela a cada request.
  */
 import type { HttpContext } from '@adonisjs/core/http';
-import type { PoppyBrowserSessionResult, PoppySessionState } from './service.js';
+import type { PoppyBrowserJoin, PoppySessionState } from './service.js';
 export interface PoppyWebSessionMarker {
     sessionId: string;
     clientId: string;
     userId: string;
+    /** Conta, grant e scopes autorizados na entrada (§6, passo 2); `null` = entrada deslogada. */
+    accountId: string | null;
+    grantId: string | null;
+    scopes: string[];
 }
 /**
- * Liga o navegador à Session: regenera a sessão do app (session fixation),
- * marca-a como do agente e, se a Session está logada, faz o login com o
- * mecanismo do app — o hook `web.login`, ou a sessão de conta do authkit +
- * `adonisAuth.guard`.
+ * Liga o navegador à Session (§6, passo 3): regenera a sessão do app (session fixation) e a marca
+ * como do agente. Uma entrada com access token faz o login na conta autorizada, no lugar de qualquer
+ * outro, com o mecanismo do app — o hook `web.login`, ou a sessão de conta do authkit +
+ * `adonisAuth.guard`. Uma entrada sem access token não mexe no login do navegador — a não ser que
+ * uma entrada anterior o tenha logado: aí o sign-in dela termina aqui.
+ */
+export declare function loginPoppyBrowser(httpCtx: HttpContext, result: PoppyBrowserJoin): Promise<void>;
+/**
+ * Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}).
+ *
+ * @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 loginPoppyBrowser(httpCtx: HttpContext, result: PoppyBrowserSessionResult): Promise<void>;
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). *
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). *   de forma incompatível fora de majors enquanto ela for draft.
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). */
 export declare function poppyWebSessionOf(ctx: HttpContext): PoppySessionState | null;
 /**
- * Middleware do site: um navegador de agente segue o estado ATUAL da Session
- * (§5 — logou/deslogou/mudou de scopes, o próximo request reflete; o cookie não
- * sobrevive à Session). Coloque-o depois do middleware de sessão.
+ * Middleware do site: o cookie age pela conta e pelos scopes autorizados na entrada e deixa de agir
+ * quando o sign-in termina (sign-out, agente desconectado); não sobrevive à Session (§6). Um login
+ * antigo não volta. Coloque-o depois do middleware de sessão.
  *
- * @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 poppyWebSession(): (httpCtx: HttpContext, next: () => Promise<void>) => Promise<void>;

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

@@ -3,10 +3,11 @@ import { syncAdonisAuthLogin, syncAdonisAuthLogout } from '../../host/adonis_aut
 import { POPPY_WEB_SESSION_KEY } from '../../host/poppy_session_key.js';
 import { personalAgentsFor } from '../runtime.js';
 /**
- * Liga o navegador à Session: regenera a sessão do app (session fixation),
- * marca-a como do agente e, se a Session está logada, faz o login com o
- * mecanismo do app — o hook `web.login`, ou a sessão de conta do authkit +
- * `adonisAuth.guard`.
+ * Liga o navegador à Session (§6, passo 3): regenera a sessão do app (session fixation) e a marca
+ * como do agente. Uma entrada com access token faz o login na conta autorizada, no lugar de qualquer
+ * outro, com o mecanismo do app — o hook `web.login`, ou a sessão de conta do authkit +
+ * `adonisAuth.guard`. Uma entrada sem access token não mexe no login do navegador — a não ser que
+ * uma entrada anterior o tenha logado: aí o sign-in dela termina aqui.
  */
 export async function loginPoppyBrowser(httpCtx, result) {
     // Sem augmentation no barrel (ver `augmentation_isolation.spec.ts`): a sessão é lida sem tipo.
@@ -14,12 +15,15 @@ export async function loginPoppyBrowser(httpCtx, result) {
     const service = await ctx.containerResolver.make('authkit.server');
     const cfg = service.config;
     const login = cfg.personalAgents?.poppy?.web?.login;
+    const previous = ctx.session.get(POPPY_WEB_SESSION_KEY);
     await ctx.session.regenerate();
-    ctx.session.forget(ACCOUNT_SESSION_KEY);
     const marker = {
         sessionId: result.sessionId,
         clientId: result.clientId,
         userId: result.userId,
+        accountId: result.accountId,
+        grantId: result.grantId,
+        scopes: result.scopes,
     };
     ctx.session.put(POPPY_WEB_SESSION_KEY, marker);
     if (login) {
@@ -38,24 +42,27 @@ export async function loginPoppyBrowser(httpCtx, result) {
         if (account)
             await syncAdonisAuthLogin(ctx, cfg, account);
     }
-    else {
+    else if (previous?.accountId) {
+        ctx.session.forget(ACCOUNT_SESSION_KEY);
         await syncAdonisAuthLogout(ctx, cfg);
     }
 }
 const states = new WeakMap();
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). *
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). *   de forma incompatível fora de majors enquanto ela for draft.
-/** Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}). */
+/**
+ * Estado da Session Poppy deste navegador (preenchido por {@link poppyWebSession}).
+ *
+ * @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 poppyWebSessionOf(ctx) {
     return states.get(ctx) ?? null;
 }
 /**
- * Middleware do site: um navegador de agente segue o estado ATUAL da Session
- * (§5 — logou/deslogou/mudou de scopes, o próximo request reflete; o cookie não
- * sobrevive à Session). Coloque-o depois do middleware de sessão.
+ * Middleware do site: o cookie age pela conta e pelos scopes autorizados na entrada e deixa de agir
+ * quando o sign-in termina (sign-out, agente desconectado); não sobrevive à Session (§6). Um login
+ * antigo não volta. Coloque-o depois do middleware de sessão.
  *
- * @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 poppyWebSession() {
@@ -65,16 +72,18 @@ export function poppyWebSession() {
         if (!marker?.sessionId)
             return next();
         const runtime = await personalAgentsFor(ctx);
-        const state = runtime?.poppy ? await runtime.poppy.sessionState(marker.sessionId) : null;
+        const state = runtime?.poppy ? await runtime.poppy.browserState(marker) : null;
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
         const login = cfg.personalAgents?.poppy?.web?.login;
         if (!state?.active || state.clientId !== marker.clientId) {
-            // A Session terminou: o cookie também.
+            // A Session terminou: o cookie também — e o login dela, não o do próprio navegador.
             ctx.session.forget(POPPY_WEB_SESSION_KEY);
-            ctx.session.forget(ACCOUNT_SESSION_KEY);
+            if (marker.accountId) {
+                ctx.session.forget(ACCOUNT_SESSION_KEY);
+                await syncAdonisAuthLogout(ctx, cfg);
+            }
             await ctx.session.regenerate();
-            await syncAdonisAuthLogout(ctx, cfg);
             return next();
         }
         states.set(ctx, state);
@@ -89,13 +98,22 @@ export function poppyWebSession() {
             return next();
         }
         const current = ctx.session.get(ACCOUNT_SESSION_KEY);
-        if (state.signedIn && state.accountId && current !== state.accountId) {
-            ctx.session.put(ACCOUNT_SESSION_KEY, state.accountId);
-            const account = await cfg.accountStore.findById(state.accountId);
-            if (account)
-                await syncAdonisAuthLogin(ctx, cfg, account);
+        if (state.signedIn && state.accountId) {
+            if (current !== state.accountId) {
+                ctx.session.put(ACCOUNT_SESSION_KEY, state.accountId);
+                const account = await cfg.accountStore.findById(state.accountId);
+                if (account)
+                    await syncAdonisAuthLogin(ctx, cfg, account);
+            }
         }
-        else if (!state.signedIn && current) {
+        else if (marker.accountId) {
+            // O sign-in da entrada terminou: o navegador sai, e a Session segue deslogada.
+            ctx.session.put(POPPY_WEB_SESSION_KEY, {
+                ...marker,
+                accountId: null,
+                grantId: null,
+                scopes: [],
+            });
             ctx.session.forget(ACCOUNT_SESSION_KEY);
             await syncAdonisAuthLogout(ctx, cfg);
         }

package/build/src/define_config.d.ts

@@ -76,8 +76,8 @@ export interface MailHooks {
         magicUrl: string;
         token: string;
         /**
-         * Código OTP de login, presente APENAS quando `login.otp.enabled` está
-         * ligado. O host pode montar o próprio e-mail com link E código. Ausente no
+         * Código OTP, de login ou de cadastro (`kind: 'signup'`), presente APENAS quando
+         * `login.otp.enabled` está ligado. O host pode montar o próprio e-mail com link E código. Ausente no
          * fluxo só-magic-link (back-compat).
          */
         code?: string;
@@ -90,7 +90,7 @@ export interface MailHooks {
         channel?: 'code' | 'link';
         /**
          * `'signup'`: link de confirmação do cadastro passwordless (a conta é criada
-         * ao abri-lo). Ausente = login por magic link. O host pode trocar o texto do
+         * ao abri-lo, ou ao confirmar o `code`). Ausente = login por magic link. O host pode trocar o texto do
          * e-mail ("confirme seu cadastro"); ignorar o campo continua funcionando.
          */
         kind?: 'signup';
@@ -523,7 +523,9 @@ export interface PasswordlessConfigInput {
      * senha) e envia um link de confirmação (`onMagicLink` com `kind: 'signup'`).
      * A conta só é criada quando o dono do e-mail abre o link: nasce com o e-mail
      * verificado e uma senha aleatória inutilizável, e o login segue pelo magic
-     * link. E-mail que já tem conta recebe um magic link de login. Default: false.
+     * link. E-mail que já tem conta recebe um magic link de login. Com `login.otp`
+     * ligado, os dois casos também levam um código para concluir no mesmo navegador.
+     * Default: false.
      * Exige que o accountStore implemente {@link MagicLinkCapability} e o serviço de
      * encryption do app (APP_KEY), que assina o link; sem a capacidade o cadastro
      * passwordless fica indisponível e o fluxo de senha segue valendo.

package/build/src/host/admin_sessions_service.js

@@ -87,7 +87,7 @@ export class AdminSessionsService {
     /**
      * Revogação total também corta os personal agents: "sair de todas as sessões",
      * reset de senha, a ação do admin e a exclusão de conta não podem deixar um
-     * agente agindo na conta (delegações do PACT e Account Tokens do Poppy). Sem
+     * agente agindo na conta (delegações do PACT e refresh tokens do Poppy). Sem
      * `personalAgents` é no-op — e aí nem resolve o banco. Diferente do
      * `recordSubRevocation`, uma falha AQUI propaga: não há outra camada que corte
      * esses tokens.
@@ -142,9 +142,9 @@ export class AdminSessionsService {
             return [];
         return (await adapter.list()).filter((r) => grantIds.has(r.payload.grantId));
     }
-    /** Grants da conta, exceto os espelhos `pgrant_` de Account Tokens do Poppy. */
+    /** Grants da conta, exceto os espelhos `pgrant_` de refresh tokens do Poppy. */
     async #accountGrants(accountId) {
-        // Os grants `pgrant_` são o espelho de um Account Token do Poppy (Bearer de MCP) — aparecem e
+        // Os grants `pgrant_` são o espelho de um refresh token do Poppy (Bearer de MCP) — aparecem e
         // são revogados como personal agent, não como app OIDC.
         return (await this.#listModelOfAccount('Grant', accountId)).filter((r) => !r.id.startsWith('pgrant_'));
     }

package/build/src/host/controllers/account_apps_controller.js

@@ -38,7 +38,7 @@ export default class AccountAppsController {
                 scopes: g.scopes,
             })))
             : null;
-        // Account Tokens do Poppy: o agente é desconectado pela mesma lista (§4.9).
+        // Refresh tokens do Poppy: o agente é desconectado pela mesma lista (§5.5).
         const poppy = agentsRuntime?.poppy;
         const poppyAgents = poppy
             ? await Promise.all((await poppy.listGrants(accountId)).map(async (g) => ({