@agentforge-io/sdk-server 4.0.18

package/dist/resources/secrets.js

@@ -0,0 +1,71 @@
+"use strict";
+// secrets resource — gobernanza de los secrets COMPANY-scoped del tenant
+// desde una app externa (ScrappyDoc). Espeja el patrón de connectors: el
+// tenant sale SIEMPRE del ak_live_, la app hija decide qué valores custom
+// setear/rotar/borrar para su propio workspace, y el platform los guarda
+// cifrados en `af_platform_secrets` (scope 'company').
+//
+// Para qué sirve: un tenant puede sobrescribir keys o crear valores custom
+// (API keys de terceros, tokens, flags) que luego consumen sus agents/tools
+// en runtime — sin que la app hija tenga que guardarlos ella misma. La
+// plataforma madre es la única fuente de verdad y los sirve cifrados.
+//
+// Auth: SIEMPRE ak_live_ tenant-wide — estos endpoints usan `ApiKeyGuard` en
+// el server (ver ApiKeySecretsController) y rechazan ChatToken, aunque el
+// `AgentForgeClient` también tenga uno configurado (ver `requestWithApiKey`).
+//
+// SEGURIDAD: esta superficie SOLO ve/toca los secrets 'company' del tenant.
+// Los secrets 'instance' de la plataforma (ANTHROPIC_API_KEY, STRIPE_*, OAuth
+// de plataforma) NUNCA se exponen acá — el server fuerza scope 'company'.
+// Los valores en claro NUNCA viajan de vuelta: `list()` solo devuelve un hint
+// (últimos 4 chars) + metadata.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsResource = void 0;
+class SecretsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * `GET /tenant-secrets` — metadata de TODOS los secrets company-scoped que
+     * este tenant ha configurado. Nunca devuelve el valor en claro, solo
+     * `valueHint` (últimos 4 chars) y flags — suficiente para renderizar una
+     * lista "configurado / no configurado" en la UI de la app hija.
+     *
+     * @example
+     *   const { items } = await af.secrets.list();
+     *   const configured = items.filter((s) => s.configured);
+     */
+    async list() {
+        return this.client.requestWithApiKey('GET', '/tenant-secrets');
+    }
+    /**
+     * `PUT /tenant-secrets/:key` — crea o sobrescribe UN secret company-scoped
+     * para este tenant. El valor viaja cifrado al vault del platform; la
+     * respuesta trae solo metadata (nunca el valor en claro). La `key` debe
+     * matchear `/^[A-Z][A-Z0-9_]*$/` (mayúsculas, dígitos, guión bajo; empieza
+     * con letra) — el server responde 400 si no.
+     *
+     * El caller es responsable de gatear quién puede llamar esto (ej. solo
+     * admin/owner del workspace) — el server no impone rol propio más allá de
+     * la ak_live_ tenant-wide.
+     *
+     * @example
+     *   await af.secrets.set('OPENAI_API_KEY', 'sk-...');
+     */
+    async set(key, value) {
+        return this.client.requestWithApiKey('PUT', `/tenant-secrets/${encodeURIComponent(key)}`, { value });
+    }
+    /**
+     * `DELETE /tenant-secrets/:key` — borra el override company-scoped de este
+     * tenant para `key`. No toca el valor 'instance' de la plataforma (si lo
+     * hubiera): tras esto, la resolución en runtime cae al fallback de
+     * plataforma. Devuelve 204 (sin body).
+     *
+     * @example
+     *   await af.secrets.remove('OPENAI_API_KEY');
+     */
+    async remove(key) {
+        await this.client.requestWithApiKey('DELETE', `/tenant-secrets/${encodeURIComponent(key)}`);
+    }
+}
+exports.SecretsResource = SecretsResource;

package/dist/resources/tools.d.ts

@@ -0,0 +1,58 @@
+import type { AgentForgeClient } from '../client';
+import type { ToolCallbackPayload } from '../types';
+export interface VerifyCallbackInput {
+    /** El body EXACTO tal como llegó por la red (antes de cualquier
+     *  JSON.parse) — HMAC es sensible a cualquier diferencia de bytes. */
+    rawBody: string;
+    /** Valor crudo del header `X-AgentForge-Signature`. */
+    signatureHeader: string;
+    /** El secret `whsec_...` que recibiste al registrar esta tool. */
+    secretPlaintext: string;
+}
+export interface RespondToCallbackInput {
+    /** El `resultUrl` que trajo el `ToolCallbackPayload` — path relativo,
+     *  se resuelve contra el mismo `baseURL` del client. */
+    resultUrl: string;
+    tenantId: string;
+    /** El mismo secret `whsec_...` usado para verificar el callback entrante. */
+    secret: string;
+    /** Texto que el LLM verá como tool_result. Ignorado si `errorMessage` viene. */
+    result?: string;
+    /** Si la ejecución falló, el platform marca la ToolCall como failed y el
+     *  LLM ve este mensaje como el resultado. */
+    errorMessage?: string;
+}
+export declare class ToolsResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /**
+     * Verifica la firma HMAC de un callback ENTRANTE del platform y devuelve
+     * el payload ya parseado. Tira `ToolCallbackSignatureError` (código
+     * 'malformed' | 'stale' | 'mismatch') si la firma no es válida — tu
+     * endpoint debería responder 401 en ese caso, nunca ejecutar la tool.
+     *
+     * @example
+     *   const payload = af.tools.verifyCallback({
+     *     rawBody: req.rawBody!.toString('utf8'),
+     *     signatureHeader: req.headers['x-agentforge-signature'] as string,
+     *     secretPlaintext: process.env.MY_TOOL_SECRET!,
+     *   });
+     *   // payload.toolName, payload.input, payload.resultUrl…
+     */
+    verifyCallback(input: VerifyCallbackInput): ToolCallbackPayload;
+    /**
+     * Responde el resultado de una tool 'remote' ejecutada localmente —
+     * firma el body y lo POSTea a `resultUrl`. El platform reanuda el turno
+     * del LLM con ese resultado (o lo marca failed si mandaste
+     * `errorMessage`). 204 en éxito — no hay nada que leer del response.
+     *
+     * @example
+     *   await af.tools.respondToCallback({
+     *     resultUrl: payload.resultUrl,
+     *     tenantId: payload.tenantId,
+     *     secret: process.env.MY_TOOL_SECRET!,
+     *     result: JSON.stringify({ ok: true }),
+     *   });
+     */
+    respondToCallback(input: RespondToCallbackInput): Promise<void>;
+}

package/dist/resources/tools.js

@@ -0,0 +1,72 @@
+"use strict";
+// tools resource — el lado CLIENTE del ciclo de vida de una tool 'remote'
+// registrada vía `agents.registerTools({ tools: [{ executionMode: 'remote', ... }] })`:
+//
+//   1. El LLM invoca la tool → el platform POSTea (firmado) tu propio
+//      `callbackUrl` público con un `ToolCallbackPayload`.
+//   2. Tu endpoint verifica la firma (`verifyCallback`) y ejecuta la tool
+//      localmente — nunca corre en el platform.
+//   3. Devolvés el resultado con `respondToCallback()`, firmado con el MISMO
+//      secret — el platform reanuda el turno del LLM con ese resultado.
+//
+// Este resource NO expone un servidor HTTP (eso lo monta tu framework — Nest,
+// Express, lo que sea); solo la verificación/firma/POST del protocolo.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolsResource = void 0;
+const webhooks_1 = require("../webhooks");
+class ToolsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Verifica la firma HMAC de un callback ENTRANTE del platform y devuelve
+     * el payload ya parseado. Tira `ToolCallbackSignatureError` (código
+     * 'malformed' | 'stale' | 'mismatch') si la firma no es válida — tu
+     * endpoint debería responder 401 en ese caso, nunca ejecutar la tool.
+     *
+     * @example
+     *   const payload = af.tools.verifyCallback({
+     *     rawBody: req.rawBody!.toString('utf8'),
+     *     signatureHeader: req.headers['x-agentforge-signature'] as string,
+     *     secretPlaintext: process.env.MY_TOOL_SECRET!,
+     *   });
+     *   // payload.toolName, payload.input, payload.resultUrl…
+     */
+    verifyCallback(input) {
+        (0, webhooks_1.verifyToolCallbackSignature)({
+            rawBody: input.rawBody,
+            signatureHeader: input.signatureHeader,
+            secretPlaintext: input.secretPlaintext,
+        });
+        return JSON.parse(input.rawBody);
+    }
+    /**
+     * Responde el resultado de una tool 'remote' ejecutada localmente —
+     * firma el body y lo POSTea a `resultUrl`. El platform reanuda el turno
+     * del LLM con ese resultado (o lo marca failed si mandaste
+     * `errorMessage`). 204 en éxito — no hay nada que leer del response.
+     *
+     * @example
+     *   await af.tools.respondToCallback({
+     *     resultUrl: payload.resultUrl,
+     *     tenantId: payload.tenantId,
+     *     secret: process.env.MY_TOOL_SECRET!,
+     *     result: JSON.stringify({ ok: true }),
+     *   });
+     */
+    async respondToCallback(input) {
+        const rawBody = JSON.stringify(input.errorMessage
+            ? { result: '', errorMessage: input.errorMessage }
+            : { result: input.result ?? '' });
+        const signature = (0, webhooks_1.signToolCallbackPayload)(input.secret, rawBody);
+        await this.client.requestRaw('POST', input.resultUrl, {
+            rawBody,
+            headers: {
+                [webhooks_1.TOOL_CALLBACK_HEADERS.signature]: signature,
+                [webhooks_1.TOOL_CALLBACK_HEADERS.tenant]: input.tenantId,
+            },
+            timeoutMs: 10000,
+        });
+    }
+}
+exports.ToolsResource = ToolsResource;

package/dist/types.d.ts

@@ -0,0 +1,355 @@
+export type ToolPermissionMode = 'allow' | 'approval' | 'blocked';
+export interface ToolPermission {
+    name: string;
+    mode: ToolPermissionMode;
+}
+export interface ExternalToolSummary {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    executionMode: 'client' | 'remote';
+    /** Solo presente cuando `executionMode === 'remote'`. */
+    callbackUrl?: string | null;
+    /** Prefijo del whsec_ — útil para identificar qué secret tiene el cliente
+     *  en su .env. El plaintext nunca se devuelve en el endpoint. */
+    secretPrefix?: string | null;
+    source: 'client-registered';
+    lastUpsertedAt: string | Date;
+}
+export interface McpServerConfig {
+    name: string;
+    transport: 'http' | 'sse';
+    url: string;
+    headers?: Record<string, string>;
+    tenantId?: string;
+}
+export interface AgentMe {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    model: string | null;
+    systemPrompt: string;
+    context: string | null;
+    temperature: number | null;
+    topP: number | null;
+    maxTokens: number | null;
+    tools: ToolPermission[];
+    mcpServers: McpServerConfig[];
+    skills: string[];
+    timezone: string | null;
+    isActive: boolean;
+    updatedAt: string | Date;
+    externalTools: ExternalToolSummary[];
+}
+export interface RegisterToolInput {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** 'client' (default) = la app cliente ejecuta la tool in-process, solo
+     *  declara el shape para visibilidad/auditoría. 'remote' = el platform
+     *  invoca `callbackUrl` cuando el LLM la usa y espera el resultado en
+     *  POST /api/v1/agents/me/tool-results/:toolUseId (ver ToolsResource). */
+    executionMode?: 'client' | 'remote';
+    /** Requerido cuando `executionMode === 'remote'`. */
+    callbackUrl?: string;
+}
+export interface RegisterToolsInput {
+    tools: RegisterToolInput[];
+}
+export interface RegisterToolsResult {
+    agentId: string;
+    count: number;
+    tools: Array<{
+        name: string;
+        lastUpsertedAt: string | Date;
+        /** Solo presente cuando esta tool (o su callbackUrl-group entero, ver
+         *  ExternalToolsRepository) acaba de rotar su secret HMAC — el
+         *  plaintext SOLO se muestra esta vez, guárdalo. Ausente si el secret
+         *  no cambió respecto al registro anterior. */
+        secret?: string;
+    }>;
+}
+export interface AgentSummary {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    model: string | null;
+    systemPrompt: string;
+    context: string | null;
+    temperature: number | null;
+    topP: number | null;
+    maxTokens: number | null;
+    timezone: string | null;
+    isActive: boolean;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+}
+export interface CreateAgentInput {
+    slug: string;
+    name: string;
+    systemPrompt?: string;
+    description?: string;
+    model?: string;
+    context?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    timezone?: string;
+    isActive?: boolean;
+    metadata?: Record<string, unknown>;
+    tools?: Array<string | {
+        name: string;
+        mode: ToolPermissionMode;
+    }>;
+}
+export interface UpdateAgentInput {
+    name?: string;
+    description?: string;
+    model?: string;
+    systemPrompt?: string;
+    context?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    timezone?: string;
+    isActive?: boolean;
+    metadata?: Record<string, unknown>;
+    /** Set completo de permisos de tool. Pass-through al backend — cada item
+     *  es `{name, mode}` (a diferencia de `CreateAgentInput.tools`, que además
+     *  acepta strings sueltos con mode='allow' implícito). */
+    tools?: Array<string | {
+        name: string;
+        mode: ToolPermissionMode;
+    }>;
+}
+export interface ListAgentsResult {
+    items: AgentSummary[];
+    total: number;
+}
+export interface ChatTokenRecord {
+    token: string;
+    tenantId: string;
+    agentId: string;
+    name: string;
+    allowedOrigins?: string[];
+    isActive: boolean;
+    createdByUserId?: string;
+    lastUsedAt?: string | Date;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+}
+export type MessageRole = 'user' | 'assistant' | 'system';
+export type ConversationStatus = 'active' | 'completed' | 'error' | 'paused';
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+export interface ToolCallRecord {
+    toolName: string;
+    toolUseId: string;
+    input: Record<string, unknown>;
+    output?: string;
+    error?: string;
+    durationMs?: number;
+}
+export interface MessageRecord {
+    id: string;
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallRecord[];
+    usage?: TokenUsage;
+    metadata?: Record<string, unknown>;
+    createdAt: string | Date;
+}
+export interface ConversationHistory {
+    conversationId: string;
+    agentId: string;
+    userId: string;
+    title?: string;
+    status: ConversationStatus;
+    messages: MessageRecord[];
+    createdAt: string | Date;
+    updatedAt: string | Date;
+}
+export interface ApprovalCopyBundle {
+    title: string;
+    body: string;
+    approveLabel: string;
+    approveBusyLabel: string;
+    denyLabel: string;
+    denyBusyLabel: string;
+    approvedPill: string;
+    deniedPill: string;
+    readOnlyHint: string;
+    blockedTitle: string;
+    blockedBody: string;
+    expiresPrefix: string;
+}
+interface ActingAgentTag {
+    /** Presente cuando un team orchestrator delegó el turno a un miembro —
+     *  el id de quién habla. Ausente = el agent primario de la sesión. */
+    actingAgentId?: string;
+}
+/** Unión completa de chunks que puede traer un turno de chat-stream. */
+export type ChatStreamChunk = ({
+    type: 'text_delta';
+    delta: string;
+} & ActingAgentTag) | ({
+    type: 'tool_use_start';
+    toolName: string;
+    toolUseId: string;
+    input?: Record<string, unknown>;
+} & ActingAgentTag) | ({
+    type: 'tool_result';
+    toolName: string;
+    result: string;
+} & ActingAgentTag) | ({
+    type: 'respond_data';
+    internalData?: unknown;
+} & ActingAgentTag) | {
+    type: 'delegation_start';
+    subAgentId: string;
+    task: string;
+    subAgentName?: string;
+    subAgentAvatarUrl?: string;
+} | {
+    type: 'delegation_result';
+    subAgentId: string;
+    result: string;
+} | ({
+    type: 'usage';
+    usage: TokenUsage;
+} & ActingAgentTag) | {
+    type: 'awaiting_approval';
+    approvalId: string;
+    toolName: string;
+    expiresAt: string;
+    connectorName?: string;
+    toolDescription?: string;
+    copy?: ApprovalCopyBundle;
+} | {
+    type: 'tool_blocked';
+    toolName: string;
+    reason?: string;
+    connectorName?: string;
+    toolDescription?: string;
+    copy?: ApprovalCopyBundle;
+} | {
+    type: 'done';
+    messageId: string;
+};
+/**
+ * Evento tipado que `ChatResource.streamMessage()` yieldea — envuelve el
+ * frame crudo SSE (`event:`/`data:`) que emite chat-stream.controller.ts:
+ *   - `conversation`: primer frame, siempre. Trae el conversationId (nuevo o
+ *     el que pasaste) para poder persistirlo (ej. en la URL) desde el turno 1.
+ *   - `chunk`: cualquier StreamChunk del turno del agente (incluye su propio
+ *     `{type:'done', messageId}` cuando el agente terminó su respuesta).
+ *   - `stream_end`: el frame `{ok:true}` que cierra la conexión HTTP —
+ *     DISTINTO del `chunk` de tipo 'done' de arriba (el wire manda AMBOS,
+ *     con el mismo `event: done` pero shapes distintos — se discriminan acá
+ *     por la presencia de `.type` en el JSON).
+ *   - `error`: el turno falló server-side (tool remota caída, LLM error, etc).
+ */
+export type ChatStreamEvent = {
+    kind: 'conversation';
+    conversationId: string;
+} | {
+    kind: 'chunk';
+    chunk: ChatStreamChunk;
+} | {
+    kind: 'stream_end';
+    ok: boolean;
+} | {
+    kind: 'error';
+    message: string;
+};
+export interface ConnectorStatus {
+    connectorId: string;
+    /** ¿El tenant ya completó el OAuth/API-key setup de este connector? */
+    connected: boolean;
+    /** ¿Tiene selector de recursos real implementado (nivel 2 del picker)?
+     *  false = se puede conectar pero `listResources()` devuelve `unsupported`. */
+    browsable: boolean;
+}
+export interface ConnectorResourceItem {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface ListConnectorResourcesResult {
+    items: ConnectorResourceItem[];
+    /** true cuando el connector está conectado pero `browsable` es false —
+     *  no es un error, la UI debe mostrar un estado "sin selector todavía". */
+    unsupported?: true;
+}
+export interface CreateClickupTaskInput {
+    /** Id de la lista de ClickUp (`ConnectorResourceItem.id` del picker). */
+    listId: string;
+    name: string;
+    description?: string;
+}
+export interface CreateClickupTaskResult {
+    id: string;
+    /** URL de la tarea en la app de ClickUp, para enlazar desde el caller. */
+    url: string;
+    name: string;
+}
+/** De dónde viene el valor resuelto: override guardado por el tenant,
+ *  template del autor del connector, o fallback allow-all implícito. */
+export type ConnectorDefaultsSource = 'tenant' | 'template' | 'fallback';
+export interface ConnectorToolInfo {
+    name: string;
+    description?: string;
+}
+export interface ConnectorDefaultsResult {
+    tools: ConnectorToolInfo[];
+    permissions: ToolPermission[];
+    source: ConnectorDefaultsSource;
+}
+/** Body que el platform POSTea al `callbackUrl` de una tool 'remote' cuando
+ *  el LLM la invoca. Firmado con HMAC (ver webhooks.ts) — usa
+ *  `ToolsResource.verifyCallback()` para verificar + parsear en un paso. */
+export interface ToolCallbackPayload {
+    toolUseId: string;
+    tenantId: string;
+    agentId: string;
+    conversationId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    /** ISO timestamp — el platform deja de esperar la respuesta después de
+     *  esto (default 30s desde que se disparó el callback). */
+    expiresAt: string;
+    /** Path relativo (no absoluto) — pasalo tal cual a
+     *  `ToolsResource.respondToCallback({ resultUrl, ... })`. */
+    resultUrl: string;
+}
+export interface IssueChatTokenInput {
+    /** Etiqueta humana. Si se omite, el server asigna un default con fecha. */
+    name?: string;
+    /** Si se omite, el token acepta cualquier Origin (útil en dev). */
+    allowedOrigins?: string[];
+}
+/** Metadata pública de un secret company-scoped del tenant, tal como la
+ *  devuelve `af.secrets.list()` / `af.secrets.set()`. NUNCA incluye el valor
+ *  en claro ni el ciphertext — solo un hint (últimos 4 chars) + flags. */
+export interface TenantSecretEntry {
+    /** Nombre de la key (ej. `OPENAI_API_KEY`). */
+    key: string;
+    /** Descripción libre; el server pone un placeholder si no se dio ninguna. */
+    description: string;
+    /** `true` cuando el tenant tiene un valor guardado para esta key. */
+    configured: boolean;
+    /** Últimos 4 chars del valor (o `••••` si es muy corto). Ausente si no hay
+     *  valor persistido. Nunca el valor completo. */
+    valueHint?: string;
+    /** ISO timestamp de la última escritura (serializado por el JSON transport).
+     *  Ausente si nunca se configuró. */
+    updatedAt?: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+// Tipos compartidos del SDK. Espejan los shapes que devuelven los endpoints
+// públicos del platform (ProxyPublicController). NO importamos del server
+// para mantener el SDK desacoplado del runtime de NestJS.
+//
+// Cuando el server cambia un shape público, esto debe actualizarse. Eventual
+// migración a generación automática desde OpenAPI queda como follow-up.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/webhooks.d.ts

@@ -0,0 +1,22 @@
+export declare const TOOL_CALLBACK_HEADERS: {
+    readonly signature: "x-agentforge-signature";
+    readonly tenant: "x-agentforge-tenant";
+};
+export declare class ToolCallbackSignatureError extends Error {
+    readonly code: 'malformed' | 'stale' | 'mismatch';
+    constructor(code: 'malformed' | 'stale' | 'mismatch', message: string);
+}
+/** Firma un body para enviar al peer. Devuelve el valor del header
+ *  `X-AgentForge-Signature`. */
+export declare function signToolCallbackPayload(secretPlaintext: string, rawBody: string): string;
+/** Verifica una firma contra el secret plaintext + raw body. Constant-time.
+ *  Tira `ToolCallbackSignatureError` si la firma es inválida, vieja, o
+ *  malformed. El `rawBody` debe ser EXACTAMENTE el string que llegó por la
+ *  red (no un objeto re-serializado) — HMAC es sensible a cualquier byte de
+ *  diferencia (orden de keys, espacios, etc). */
+export declare function verifyToolCallbackSignature(input: {
+    rawBody: string;
+    signatureHeader: string;
+    secretPlaintext: string;
+    nowSeconds?: number;
+}): void;

package/dist/webhooks.js

@@ -0,0 +1,90 @@
+"use strict";
+// Helpers de HMAC para autenticación de callbacks Platform ↔ Cliente — MISMO
+// algoritmo exacto que agentforge-platform/apps/server/src/modules/proxy/
+// hmac.ts (portado acá, no importado, por la misma razón de desacople del
+// resto del SDK: esta app cliente firma/verifica en AMBAS direcciones y
+// necesita el algoritmo disponible sin arrastrar el runtime del server).
+//
+// Modelo (estilo Stripe webhook):
+//   - Cliente y platform comparten un secret HMAC `whsec_*` — el cliente lo
+//     recibe plaintext en `RegisterToolsResult.tools[].secret` (solo la
+//     primera vez, o cuando rota — ver AgentsResource.registerTools).
+//   - Cada mensaje firmado lleva header:
+//       X-AgentForge-Signature: t=<timestamp>,v1=<hex>
+//     donde:
+//       timestamp = unix segundos
+//       v1        = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)
+//   - El receptor: extrae timestamp + v1, recomputa, compara constant-time.
+//   - Defensa contra replay: timestamp debe estar dentro de ±5 min (300 s).
+//
+// Direcciones de uso:
+//   - El platform FIRMA cuando POSTea el callback de una tool 'remote' al
+//     cliente — el cliente VERIFICA con `verifyToolCallbackSignature`.
+//   - El cliente FIRMA cuando responde con el resultado — ver
+//     `ToolsResource.respondToCallback`, que llama `signToolCallbackPayload`
+//     internamente (no hace falta invocarlo a mano).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolCallbackSignatureError = exports.TOOL_CALLBACK_HEADERS = void 0;
+exports.signToolCallbackPayload = signToolCallbackPayload;
+exports.verifyToolCallbackSignature = verifyToolCallbackSignature;
+const node_crypto_1 = require("node:crypto");
+const MAX_AGE_SECONDS = 300;
+exports.TOOL_CALLBACK_HEADERS = {
+    signature: 'x-agentforge-signature',
+    tenant: 'x-agentforge-tenant',
+};
+class ToolCallbackSignatureError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'ToolCallbackSignatureError';
+        this.code = code;
+    }
+}
+exports.ToolCallbackSignatureError = ToolCallbackSignatureError;
+/** Firma un body para enviar al peer. Devuelve el valor del header
+ *  `X-AgentForge-Signature`. */
+function signToolCallbackPayload(secretPlaintext, rawBody) {
+    const ts = Math.floor(Date.now() / 1000);
+    return `t=${ts},v1=${computeHmac(secretPlaintext, ts, rawBody)}`;
+}
+/** Verifica una firma contra el secret plaintext + raw body. Constant-time.
+ *  Tira `ToolCallbackSignatureError` si la firma es inválida, vieja, o
+ *  malformed. El `rawBody` debe ser EXACTAMENTE el string que llegó por la
+ *  red (no un objeto re-serializado) — HMAC es sensible a cualquier byte de
+ *  diferencia (orden de keys, espacios, etc). */
+function verifyToolCallbackSignature(input) {
+    const parsed = parseSignatureHeader(input.signatureHeader);
+    if (!parsed) {
+        throw new ToolCallbackSignatureError('malformed', 'Signature header is malformed');
+    }
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - parsed.timestamp) > MAX_AGE_SECONDS) {
+        throw new ToolCallbackSignatureError('stale', `Signature timestamp is more than ${MAX_AGE_SECONDS}s old or in the future`);
+    }
+    const expected = computeHmac(input.secretPlaintext, parsed.timestamp, input.rawBody);
+    const a = Buffer.from(parsed.v1, 'hex');
+    const b = Buffer.from(expected, 'hex');
+    if (a.length !== b.length || !(0, node_crypto_1.timingSafeEqual)(a, b)) {
+        throw new ToolCallbackSignatureError('mismatch', 'Signature does not match');
+    }
+}
+function parseSignatureHeader(raw) {
+    if (!raw)
+        return null;
+    let timestamp;
+    let v1;
+    for (const part of raw.split(',').map((p) => p.trim())) {
+        if (part.startsWith('t='))
+            timestamp = Number(part.slice(2));
+        else if (part.startsWith('v1='))
+            v1 = part.slice(3);
+    }
+    if (!timestamp || !v1 || Number.isNaN(timestamp))
+        return null;
+    return { timestamp, v1 };
+}
+function computeHmac(secretPlaintext, timestamp, rawBody) {
+    return (0, node_crypto_1.createHmac)('sha256', secretPlaintext)
+        .update(`${timestamp}.${rawBody}`)
+        .digest('hex');
+}