Docs para desarrolladores / SDK v1.0.3 / HMAC

Agrega identidad responsable
a tu agente.

Zero vincula un agente de IA o servidor MCP con la cuenta humana que lo creó. Llama al SDK antes de una acción real: Zero valida el runtime, firma la solicitud, devuelve un token corto y registra la acción para auditoría.

00

El contrato

Tu app sigue ejecutando el trabajo. Zero responde antes: ¿este agente, creado por esta persona, puede realizar esta acción ahora?
  • Un humano crea un agente desde el dashboard de Zero.
  • El runtime recibe ZERO_AGENT_ID y un secreto o clave privada.
  • Tu código llama zero.run() antes de side effects como mensajes, writes, compras, tool calls o mutaciones de API.
  • Zero valida la prueba del runtime, la plataforma y el estado del agente.
  • Si las credenciales no coinciden o el agente fue deshabilitado, allowed será false.
01

Instala

npm
npm install @zero-gate/sdk@1.0.3

Instalación local: npm install ../sdk/zero-gate-sdk-1.0.3.tgz
Si no está en npm: npm install https://github.com/platanus-hack/platanus-hack-26-ar-team-17/raw/main/sdk/zero-gate-sdk-1.0.3.tgz

02

Crea un agente

Crea un agente por cada runtime que quieras identificar. En el dashboard, abre /agents, entra en credenciales y copia el ID del agente junto con su API secret.

dashboard / agents / credenciales
ZERO_AGENT_ID=f47ac10b-58cc-4372-a567-0e02b2c3d479
ZERO_API_SECRET=hQv7...(long base64url string)...2k

# Headers for an MCP wrapper:
#   X-Zero-Agent-Id:    f47ac10b-58cc-4372-a567-0e02b2c3d479
#   X-Zero-Api-Secret:  hQv7...2k
Para integraciones nuevas usa ZERO_AGENT_ID + ZERO_API_SECRET. El flujo viejo con ZERO_API_KEY + ZERO_USER_HASH queda solo por compatibilidad.
03

Configura el runtime

.env
ZERO_AGENT_ID=0f6f7f64-8c7f-4a8f-bcf1-8d33d624f2a1
ZERO_API_SECRET=zgs_...

# Optional
ZERO_PLATFORM=mcp
ZERO_PLATFORM_API_URL=http://localhost:3000

Si ZERO_PLATFORM no está definido, el SDK detecta MCP cuando @modelcontextprotocol/sdk está instalado. Si no, reporta custom.

initialize
import { ZeroGateSDK } from '@zero-gate/sdk';

const zero = new ZeroGateSDK();
// reads ZERO_AGENT_ID + ZERO_API_SECRET from process.env
04

Protege acciones reales

Crea el SDK una vez y llama run() justo antes de un side effect. Usa funciones con nombre para que el audit log sea legible.

usage
import { ZeroGateSDK } from '@zero-gate/sdk';

const zero = new ZeroGateSDK();

export async function sendMessage(text: string) {
  const auth = await zero.run();

  if (!auth.allowed) {
    return { ok: false, reason: 'blocked_by_zero' };
  }

  await deliverMessage(text);
  return { ok: true };
}
05

Patrón para MCP

Cuando @modelcontextprotocol/sdk está instalado, el SDK reporta mcp automáticamente.
mcp-server.ts
import { ZeroGateSDK } from '@zero-gate/sdk';

const zero = new ZeroGateSDK();

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const auth = await zero.run();

  if (!auth.allowed) {
    return {
      content: [{ type: 'text', text: 'Zero blocked this action.' }],
      isError: true,
    };
  }

  return executeTool(request.params);
});
06

Modo con keypair

Si no quieres un secreto HMAC compartido dentro del runtime, registra una clave pública Ed25519 y ejecuta el SDK con la clave privada. La clave privada nunca sale del proceso del agente.

env
ZERO_AGENT_ID=0f6f7f64-8c7f-4a8f-bcf1-8d33d624f2a1
ZERO_PRIVATE_KEY=64_hex_chars

# Optional
ZERO_PRIVATE_KEY_PQC=...
07

Prompt para un asistente de IA

Pega esto en Claude, Cursor, Copilot Chat o cualquier asistente que pueda editar tu repo. Incluye el contrato para que no invente campos.

copiar / pegar en tu asistente
You are integrating @zero-gate/sdk@1.0.3 into an existing AI agent or MCP server.
ZeroGate adds identity and auditability: it signs each action with HMAC-SHA256,
validates it against the Platform API, and returns { allowed, token? } before the action runs.

Integration contract:

1. Install: npm install @zero-gate/sdk@1.0.3
   If the package is not available from npm, install from:
   https://github.com/platanus-hack/platanus-hack-26-ar-team-17/raw/main/sdk/zero-gate-sdk-1.0.3.tgz

2. Ask the developer for only two dashboard values:
   - ZERO_AGENT_ID: the agent UUID
   - ZERO_API_SECRET: the agent HMAC secret

3. Initialize once:
   import { ZeroGateSDK } from '@zero-gate/sdk';
   const zero = new ZeroGateSDK();

4. Wrap every real action with zero.run(). Do not invent fields:
   action and platform are detected automatically.

5. If result.allowed is false, do not run the side effect.

Report back: files changed, protected actions, and env vars added.

Notas de seguridad

  • El secreto HMAC no viaja en claro. El SDK firma agentId|timestamp|nonce|action|platform y el backend lo verifica.
  • El transporte exige HTTPS para producción.
  • Los nonces son de un solo uso y reducen riesgo de replay.
  • Los tokens del SDK expiran en minutos, no en días.
  • Cada llamada a run(), permitida o bloqueada, queda en el audit log.

Construye agentes que puedan responder por lo que hacen.

Crear primer agente ->