DEV Community

discernible-io
discernible-io

Posted on

Verify before execute: HOLA recipes for agent verifiers

#agents #identity #security

If your agent receives work from another agent — via OpenClaw sessions_send, A2A, email, or webhooks — you need one rule above all others:

Verify before execute. HOLA first, tools second.

This article is for demand-side verifiers: services and agents that receive HOLA lines or identyclaw.collaboration.v1 envelopes and must decide whether to run task.payload, share secrets, or call tools.

Full verifier recipes live in the IdentyClaw docs (verify-hola-recipes); this is the operator-friendly version.

If you have not onboarded OpenClaw with Passport yet, start with the OpenClaw onboarding guide — then come back here for the verifier side.

The problem

Multi-agent stacks often trust:

  • Display names or session keys
  • A static webhook HMAC that never expires
  • "This JWT came from a URL we configured last month"

None of those prove which Passport holder delegated the current task. A compromised channel credential or look-alike endpoint can forge sender identity.

Wire auth vs task trust (two layers)

On inter-agent messages you need both layers — and you must not conflate them.

Layer Proves Typical mechanism
Wire auth Who may send on the channel A2A P2P JWT, webhook HMAC, TLS client cert
Task trust Which Passport delegated task.payload HOLA line inside the message body

Wire auth answers: "Is this connection allowed?"

Task trust answers: "Did Passport X actually delegate this work?"

A valid wire JWT does not prove task identity. Always verify HOLA before executing delegated payloads.

The rule (six steps)

On every inbound agent message that carries work:

1. Parse payload (plain HOLA string or identyclaw.collaboration.v1 envelope)
2. Verify HOLA independently — IdentyClaw API or direct NEAR RPC (full proof bar)
3. Match peerTokenId ↔ envelope.from.tokenId (if envelope)
4. Impersonation guard — peerTokenId matches principal's published tokenId
5. Subagent only — POST /api/isauthorizedsigner when delegation format
6. Execute task — ONLY after steps 2–5 pass
Enter fullscreen mode Exit fullscreen mode

Language for runbooks and agent prompts: "Verify before execute — HOLA first, tools second."

Collaboration envelope (shape)

Most channels carry work inside identyclaw.collaboration.v1:

{
  "schema": "identyclaw.collaboration.v1",
  "messageId": "01HXABCDEFGHJKMNPQRSTVWXYZ0",
  "timestamp": "2026-06-06T12:00:00.000Z",
  "from": { "tokenId": "bkbvehbdcrgm" },
  "to": { "tokenId": "lncnsfsnskzr" },
  "hola": "HOLA/1.0/bkbvehbdcrgm/MUNDO/...",
  "task": {
    "type": "TASK_REQUEST",
    "payload": { "summary": "Run benchmark X and return JSON metrics" }
  }
}
Enter fullscreen mode Exit fullscreen mode

Verify the hola field before touching task.payload. Full schema: collaboration-envelope.

Two verify paths (peer chooses)

Path When
IdentyClaw HTTP API POST /api/identity/verify — hosted helper; JWT recommended on protected deployments
Direct NEAR RPC @rodit/rodit-auth-be + your RPC endpoint

HOLA exchange is offline P2P on whatever channel you already use. Neither path brokers the handshake — each peer validates independently.

Local checksum or bare Ed25519 checks alone are not sufficient. See identity-verification-policy.

Recipe: Node.js verifier (~20 lines) 

const BASE = "https://api.identyclaw.com";

async function verifyBeforeExecute(hola, { jwt, fromTokenId, canonicalPublishedId } = {}) {
  const res = await fetch(`${BASE}/api/identity/verify`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...(jwt ? { Authorization: `Bearer ${jwt}` } : {}),
    },
    body: JSON.stringify({ hola }),
  });
  const result = await res.json();
  if (!result.verified) {
    throw new Error(`HOLA rejected: ${(result.failureReasons || []).join(", ")}`);
  }
  if (fromTokenId && result.peerTokenId !== fromTokenId) {
    throw new Error(`from.tokenId mismatch: ${fromTokenId} vs ${result.peerTokenId}`);
  }
  if (canonicalPublishedId && result.peerTokenId !== canonicalPublishedId) {
    throw new Error(`impersonation guard failed for ${canonicalPublishedId}`);
  }
  return result; // safe to execute task.payload
}
Enter fullscreen mode Exit fullscreen mode

Runnable scripts (plain HOLA and full envelope): examples/verify-before-execute/.

Subagent delegation

When the inbound HOLA uses a subagent delegation format, steps 2–4 still apply. Add step 5:

POST /api/isauthorizedsigner — confirm the signer is authorized for the principal
Enter fullscreen mode Exit fullscreen mode

Only after HOLA and authorization pass should you execute. See hola-subagent-authentication.

Publish your Passport ID

Legitimate operators post their 12-letter tokenId on website, GitHub, ClawHub, or verified social. Verifiers compare verified peerTokenId to that canonical ID before treating the sender as that brand or human principal.

See finding-agents §5.

OpenClaw integration

Install the trust skill and use collaboration envelopes on inter-agent messages:

openclaw skills install clawhub:identyclaw/identyclaw-a2a-trust
Enter fullscreen mode Exit fullscreen mode

Wire auth (A2A JWT) proves who may send on the channel. Task trust (HOLA in the envelope body) proves which Passport delegated the payload. Never conflate the two.

When this matters most

  • Cross-org agent collaboration
  • First contact with unknown peers (no pre-shared secrets)
  • Supervisor → specialist delegation
  • Any channel where display names are spoofable

Skip if you run a single internal agent with no delegated work from external peers.

Resources

Questions? Drop them in the comments — especially if you have a verifier stack we should document.

Top comments (0)