@adonis-agora/authkit-server 0.77.0 → 0.79.0

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

@@ -0,0 +1,111 @@
+/**
+ * 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`).
+ *
+ * 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
+ * `where status = from`.
+ */
+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 {
+    id: string;
+    clientId: string;
+    userId: string;
+    /** Conta a que a Session está PRESA (uma vez logada, não troca — §4.4). */
+    accountId: string | null;
+    /** Grant (Account Token) com que está logada agora; `null` = deslogada. */
+    grantId: string | null;
+    scope: string;
+    expiresAt: Date;
+    endedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+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). */
+    jkt: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+export type RequestKind = 'authorize' | 'device' | 'mediated';
+export type RequestStatus = 'pending' | 'approved' | 'denied' | 'consumed' | 'failed';
+export interface RequestRow {
+    id: string;
+    kind: RequestKind;
+    /** Hash do código de autorização / device code. */
+    codeHash: string | null;
+    userCode: string | null;
+    clientId: string;
+    sessionId: string | null;
+    accountId: string | null;
+    requestedScope: string;
+    grantedScope: string | null;
+    redirectUri: string | null;
+    codeChallenge: string | null;
+    status: RequestStatus;
+    attempts: number;
+    intervalSeconds: number | null;
+    lastPolledAt: Date | null;
+    data: Record<string, unknown> | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+export declare class PoppyStore {
+    private conn;
+    constructor(conn: () => any);
+    insertSession(row: Omit<SessionRow, 'endedAt'>): Promise<void>;
+    findSession(id: string): Promise<SessionRow | null>;
+    /** 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.
+     */
+    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. */
+    endSessionsOfClient(clientId: string, at: Date): Promise<number>;
+    insertToken(row: TokenRow): Promise<void>;
+    findToken(hash: string): Promise<TokenRow | null>;
+    deleteToken(hash: string): Promise<boolean>;
+    deleteTokensExpiredBefore(before: Date): Promise<void>;
+    insertRequest(row: Omit<RequestRow, 'attempts' | 'lastPolledAt' | 'grantedScope'> & {
+        grantedScope?: string | null;
+    }): Promise<void>;
+    findRequest(id: string): Promise<RequestRow | null>;
+    findRequestByCodeHash(hash: string): Promise<RequestRow | null>;
+    findRequestByUserCode(userCode: string): Promise<RequestRow | null>;
+    /** Transição atômica — só se o pedido ainda está em `from`. */
+    transitionRequest(id: string, from: RequestStatus, patch: {
+        status: RequestStatus;
+        accountId?: string;
+        grantedScope?: string;
+        codeHash?: string;
+        attempts?: number;
+        expiresAt?: Date;
+    }): Promise<boolean>;
+    /** Conta uma tentativa errada (atômico sobre o valor lido). */
+    bumpAttempts(id: string, from: number): Promise<boolean>;
+    setRequestData(id: string, data: Record<string, unknown>): Promise<void>;
+    markPolled(id: string, at: Date): Promise<void>;
+    deleteRequestsExpiredBefore(before: Date): Promise<void>;
+}

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

@@ -0,0 +1,269 @@
+/**
+ * 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`).
+ *
+ * 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
+ * `where status = from`.
+ */
+export const SESSION_TABLE = 'auth_poppy_sessions';
+export const TOKEN_TABLE = 'auth_poppy_tokens';
+export const REQUEST_TABLE = 'auth_poppy_requests';
+function toDate(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'number')
+        return new Date(value);
+    if (typeof value === 'string' && /^\d+$/.test(value))
+        return new Date(Number(value));
+    return new Date(String(value));
+}
+function toDateOrNull(value) {
+    return value === null || value === undefined ? null : toDate(value);
+}
+function affected(result) {
+    if (typeof result === 'number')
+        return result;
+    if (Array.isArray(result))
+        return result.length;
+    return 0;
+}
+function toSession(row) {
+    return {
+        id: row.id,
+        clientId: row.client_id,
+        userId: row.user_id,
+        accountId: row.account_id ?? null,
+        grantId: row.grant_id ?? null,
+        scope: row.scope ?? '',
+        expiresAt: toDate(row.expires_at),
+        endedAt: toDateOrNull(row.ended_at),
+        createdAt: toDate(row.created_at),
+        updatedAt: toDate(row.updated_at),
+    };
+}
+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 ?? '',
+        resource: row.resource ?? null,
+        jkt: row.jkt ?? null,
+        expiresAt: toDate(row.expires_at),
+        createdAt: toDate(row.created_at),
+    };
+}
+function toRequest(row) {
+    let data = null;
+    if (row.data) {
+        try {
+            data = JSON.parse(row.data);
+        }
+        catch {
+            data = null;
+        }
+    }
+    return {
+        id: row.id,
+        kind: row.kind,
+        codeHash: row.code_hash ?? null,
+        userCode: row.user_code ?? null,
+        clientId: row.client_id,
+        sessionId: row.session_id ?? null,
+        accountId: row.account_id ?? null,
+        requestedScope: row.requested_scope ?? '',
+        grantedScope: row.granted_scope ?? null,
+        redirectUri: row.redirect_uri ?? null,
+        codeChallenge: row.code_challenge ?? null,
+        status: row.status,
+        attempts: Number(row.attempts ?? 0),
+        intervalSeconds: row.interval_seconds === null || row.interval_seconds === undefined
+            ? null
+            : Number(row.interval_seconds),
+        lastPolledAt: toDateOrNull(row.last_polled_at),
+        data,
+        expiresAt: toDate(row.expires_at),
+        createdAt: toDate(row.created_at),
+    };
+}
+export class PoppyStore {
+    conn;
+    constructor(conn) {
+        this.conn = conn;
+    }
+    // ─── sessions ─────────────────────────────────────────────────────────────
+    async insertSession(row) {
+        await this.conn().table(SESSION_TABLE).insert({
+            id: row.id,
+            client_id: row.clientId,
+            user_id: row.userId,
+            account_id: row.accountId,
+            grant_id: row.grantId,
+            scope: row.scope,
+            expires_at: row.expiresAt,
+            created_at: row.createdAt,
+            updated_at: row.updatedAt,
+        });
+    }
+    async findSession(id) {
+        if (typeof id !== 'string' || !id)
+            return null;
+        const row = await this.conn().from(SESSION_TABLE).where('id', id).first();
+        return row ? toSession(row) : null;
+    }
+    /** Estende a vida da Session (uso). */
+    async touchSession(id, expiresAt, at) {
+        await this.conn()
+            .from(SESSION_TABLE)
+            .where('id', id)
+            .whereNull('ended_at')
+            .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.
+     */
+    async signInSession(id, patch) {
+        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,
+        });
+        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. */
+    async endSessionsOfClient(clientId, at) {
+        const result = await this.conn()
+            .from(SESSION_TABLE)
+            .where('client_id', clientId)
+            .whereNull('ended_at')
+            .update({ ended_at: at, grant_id: null, scope: '', updated_at: at });
+        return affected(result);
+    }
+    // ─── session tokens ───────────────────────────────────────────────────────
+    async insertToken(row) {
+        await this.conn().table(TOKEN_TABLE).insert({
+            token_hash: row.tokenHash,
+            session_id: row.sessionId,
+            client_id: row.clientId,
+            user_id: row.userId,
+            account_id: row.accountId,
+            grant_id: row.grantId,
+            scope: row.scope,
+            resource: row.resource,
+            jkt: row.jkt,
+            expires_at: row.expiresAt,
+            created_at: row.createdAt,
+        });
+    }
+    async findToken(hash) {
+        const row = await this.conn().from(TOKEN_TABLE).where('token_hash', hash).first();
+        return row ? toToken(row) : null;
+    }
+    async deleteToken(hash) {
+        return affected(await this.conn().from(TOKEN_TABLE).where('token_hash', hash).delete()) > 0;
+    }
+    async deleteTokensExpiredBefore(before) {
+        await this.conn().from(TOKEN_TABLE).where('expires_at', '<', before).delete();
+    }
+    // ─── sign-in requests ─────────────────────────────────────────────────────
+    async insertRequest(row) {
+        await this.conn()
+            .table(REQUEST_TABLE)
+            .insert({
+            id: row.id,
+            kind: row.kind,
+            code_hash: row.codeHash,
+            user_code: row.userCode,
+            client_id: row.clientId,
+            session_id: row.sessionId,
+            account_id: row.accountId,
+            requested_scope: row.requestedScope,
+            granted_scope: row.grantedScope ?? null,
+            redirect_uri: row.redirectUri,
+            code_challenge: row.codeChallenge,
+            status: row.status,
+            attempts: 0,
+            interval_seconds: row.intervalSeconds,
+            data: row.data ? JSON.stringify(row.data) : null,
+            expires_at: row.expiresAt,
+            created_at: row.createdAt,
+        });
+    }
+    async findRequest(id) {
+        if (typeof id !== 'string' || !id)
+            return null;
+        const row = await this.conn().from(REQUEST_TABLE).where('id', id).first();
+        return row ? toRequest(row) : null;
+    }
+    async findRequestByCodeHash(hash) {
+        const row = await this.conn().from(REQUEST_TABLE).where('code_hash', hash).first();
+        return row ? toRequest(row) : null;
+    }
+    async findRequestByUserCode(userCode) {
+        const row = await this.conn().from(REQUEST_TABLE).where('user_code', userCode).first();
+        return row ? toRequest(row) : null;
+    }
+    /** Transição atômica — só se o pedido ainda está em `from`. */
+    async transitionRequest(id, from, patch) {
+        const update = { status: patch.status };
+        if (patch.accountId !== undefined)
+            update.account_id = patch.accountId;
+        if (patch.grantedScope !== undefined)
+            update.granted_scope = patch.grantedScope;
+        if (patch.codeHash !== undefined)
+            update.code_hash = patch.codeHash;
+        if (patch.attempts !== undefined)
+            update.attempts = patch.attempts;
+        if (patch.expiresAt !== undefined)
+            update.expires_at = patch.expiresAt;
+        const result = await this.conn()
+            .from(REQUEST_TABLE)
+            .where('id', id)
+            .where('status', from)
+            .update(update);
+        return affected(result) > 0;
+    }
+    /** Conta uma tentativa errada (atômico sobre o valor lido). */
+    async bumpAttempts(id, from) {
+        const result = await this.conn()
+            .from(REQUEST_TABLE)
+            .where('id', id)
+            .where('attempts', from)
+            .update({ attempts: from + 1 });
+        return affected(result) > 0;
+    }
+    async setRequestData(id, data) {
+        await this.conn()
+            .from(REQUEST_TABLE)
+            .where('id', id)
+            .update({ data: JSON.stringify(data) });
+    }
+    async markPolled(id, at) {
+        await this.conn().from(REQUEST_TABLE).where('id', id).update({ last_polled_at: at });
+    }
+    async deleteRequestsExpiredBefore(before) {
+        await this.conn().from(REQUEST_TABLE).where('expires_at', '<', before).delete();
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+import type { HttpContext } from '@adonisjs/core/http';
+import type { PoppyBrowserSessionResult, PoppySessionState } from './service.js';
+export interface PoppyWebSessionMarker {
+    sessionId: string;
+    clientId: string;
+    userId: 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`.
+ */
+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.
+ *
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — 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

@@ -0,0 +1,104 @@
+import { ACCOUNT_SESSION_KEY } from '../../host/account_session_key.js';
+import { syncAdonisAuthLogin, syncAdonisAuthLogout } from '../../host/adonis_auth_sync.js';
+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`.
+ */
+export async function loginPoppyBrowser(httpCtx, result) {
+    // Sem augmentation no barrel (ver `augmentation_isolation.spec.ts`): a sessão é lida sem tipo.
+    const ctx = httpCtx;
+    const service = await ctx.containerResolver.make('authkit.server');
+    const cfg = service.config;
+    const login = cfg.personalAgents?.poppy?.web?.login;
+    await ctx.session.regenerate();
+    ctx.session.forget(ACCOUNT_SESSION_KEY);
+    const marker = {
+        sessionId: result.sessionId,
+        clientId: result.clientId,
+        userId: result.userId,
+    };
+    ctx.session.put(POPPY_WEB_SESSION_KEY, marker);
+    if (login) {
+        await login(ctx, {
+            sessionId: result.sessionId,
+            clientId: result.clientId,
+            userId: result.userId,
+            accountId: result.accountId,
+            scopes: result.scopes,
+        });
+        return;
+    }
+    if (result.accountId) {
+        ctx.session.put(ACCOUNT_SESSION_KEY, result.accountId);
+        const account = await cfg.accountStore.findById(result.accountId);
+        if (account)
+            await syncAdonisAuthLogin(ctx, cfg, account);
+    }
+    else {
+        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}). */
+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.
+ *
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ *   de forma incompatível fora de majors enquanto ela for draft.
+ */
+export function poppyWebSession() {
+    return async (httpCtx, next) => {
+        const ctx = httpCtx;
+        const marker = ctx.session?.get(POPPY_WEB_SESSION_KEY);
+        if (!marker?.sessionId)
+            return next();
+        const runtime = await personalAgentsFor(ctx);
+        const state = runtime?.poppy ? await runtime.poppy.sessionState(marker.sessionId) : 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.
+            ctx.session.forget(POPPY_WEB_SESSION_KEY);
+            ctx.session.forget(ACCOUNT_SESSION_KEY);
+            await ctx.session.regenerate();
+            await syncAdonisAuthLogout(ctx, cfg);
+            return next();
+        }
+        states.set(ctx, state);
+        if (login) {
+            await login(ctx, {
+                sessionId: state.sessionId,
+                clientId: state.clientId,
+                userId: state.userId,
+                accountId: state.accountId,
+                scopes: state.scopes,
+            });
+            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);
+        }
+        else if (!state.signedIn && current) {
+            ctx.session.forget(ACCOUNT_SESSION_KEY);
+            await syncAdonisAuthLogout(ctx, cfg);
+        }
+        return next();
+    };
+}

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

@@ -6,10 +6,14 @@ import type { DelegationReceipt } from './delegation_service.js';
  * header de delegação, challenge do 401, bloco de descoberta, formato do
  * step-up e do recibo.
  *
- * Embutido hoje: `'pact'` (https://openpactprotocol.org, v1.0). Outro protocolo
- * (ex.: o Personal Agent Protocol da Sierra, quando sair a spec) entra como
- * mais um objeto desta interface — passado direto em `personalAgents.protocol`
- * enquanto não for embutido.
+ * Embutido hoje: `'pact'` (https://openpactprotocol.org, v1.0). Um protocolo da
+ * MESMA família (JWT do agente + token de delegação) entra como mais um objeto
+ * desta interface, passado direto em `personalAgents.protocol`.
+ *
+ * O Personal Agent Protocol ("Poppy", Sierra/Meta) tem outro modelo — um
+ * authorization server OAuth com Sessions e tokens DPoP — e por isso não é um
+ * adapter daqui: liga-se em `personalAgents.poppy` (ver `poppy/`), ao lado do
+ * PACT, reaproveitando o núcleo de grants.
  */
 export interface PersonalAgentProtocol {
     /** Identificador estável (`'pact'`). */

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

@@ -0,0 +1,41 @@
+export declare const REGISTRY_TABLE = "auth_agent_registry";
+export type AgentProtocolId = 'pact' | 'poppy';
+export type AgentRegistryStatus = 'allowed' | 'blocked';
+export interface AgentRegistryRow {
+    id: string;
+    protocol: AgentProtocolId;
+    /** PACT: o `iss` do agente. Poppy: o `client_id` (URL do documento de metadata). */
+    identifier: string;
+    status: AgentRegistryStatus;
+    name: string | null;
+    /** JWKS do agente PACT (obrigatório num `allowed` PACT). */
+    jwksUri: string | null;
+    /** Conta do admin que fez a mudança. */
+    updatedBy: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Quanto tempo o snapshot vale antes de reler a tabela. */
+export declare const SNAPSHOT_TTL_MS: number;
+export declare class AgentRegistryStore {
+    #private;
+    constructor(conn: () => any, options?: {
+        now?: () => number;
+    });
+    /** Todas as linhas, mais recentes primeiro. Lê do banco (console). */
+    list(): Promise<AgentRegistryRow[]>;
+    /** A linha do agente, pelo snapshot. `null` = o console não diz nada sobre ele. */
+    find(protocol: AgentProtocolId, identifier: string): Promise<AgentRegistryRow | null>;
+    findById(id: string): Promise<AgentRegistryRow | null>;
+    /** Cria ou troca a linha de (protocolo, identificador). */
+    upsert(input: {
+        protocol: AgentProtocolId;
+        identifier: string;
+        status: AgentRegistryStatus;
+        name?: string | null;
+        jwksUri?: string | null;
+        updatedBy?: string | null;
+    }): Promise<AgentRegistryRow>;
+    delete(id: string): Promise<boolean>;
+    invalidate(): void;
+}