@rodit/verify-hola 0.1.3

package/README.md

@@ -0,0 +1,93 @@
+# @rodit/verify-hola
+
+Part of the [Discernible IO SDK monorepo](../README.md).
+
+Verify-before-execute tooling for IdentyClaw HOLA lines.
+
+For NEAR account enrollment, see [gennearaccount](https://github.com/discernible-io/gennearaccount). For in-gateway HOLA tools, see [openclaw-identyclaw-plugin](https://github.com/discernible-io/openclaw-identyclaw-plugin).
+
+## Recommended: direct NEAR RPC (`--rpc`)
+
+No IdentyClaw API in the verify path — your machine reads chain state via FastNear (or any NEAR RPC).
+
+```bash
+export NEAR_RPC_URL="https://rpc.mainnet.fastnear.com"
+export NEAR_CONTRACT_ID="genaaaa-identyclaw-com.near"
+
+npx @rodit/verify-hola report "HOLA/MUNDO/..." --rpc \
+  --canonical-peer <lemuel-gulliver-lobby-tokenId>
+```
+
+From this monorepo (no npm publish required):
+
+```bash
+export NEAR_RPC_URL="https://rpc.mainnet.fastnear.com"
+export NEAR_CONTRACT_ID="genaaaa-identyclaw-com.near"
+node bin/verify-hola.js report "HOLA/..." --rpc \
+  --canonical-peer <lemuel-gulliver-lobby-tokenId>
+```
+
+## Alternative: IdentyClaw API path
+
+JWT is optional — `POST /api/identity/verify` is public.
+
+```bash
+npx @rodit/verify-hola report "HOLA/MUNDO/..."
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `verify-hola verify "HOLA/..." --rpc` | Cryptographic outcome via NEAR RPC |
+| `verify-hola report "HOLA/..." --rpc` | Verify + on-chain passport profile (DN) |
+| `verify-hola report "HOLA/..."` | Verify + profile via API (`includeProfile`) |
+
+## Environment
+
+| Variable | `--rpc` | API (default) |
+| --- | --- | --- |
+| `NEAR_RPC_URL` | **Required** | — |
+| `NEAR_CONTRACT_ID` | **Required** | — |
+| `IDENTYCLAW_BASE_URL` | — | default `https://api.identyclaw.com` |
+| `IDENTYCLAW_JWT` | — | optional |
+| `IDENTYCLAW_CANONICAL_PEER_ID` | optional impersonation guard | optional |
+| `IDENTYCLAW_EXPECTED_RECIPIENT` | — | optional |
+
+## Concierge demo (Lemuel Gulliver)
+
+1. Message **Lemuel Gulliver** via A2A at [identyclaw-concierge.identyclaw.com:7443](https://identyclaw-concierge.identyclaw.com:7443) (or email / Discord / Telegram) and ask for a HOLA.
+2. Verify with RPC (recommended):
+
+```bash
+export NEAR_RPC_URL="https://rpc.mainnet.fastnear.com"
+export NEAR_CONTRACT_ID="genaaaa-identyclaw-com.near"
+export IDENTYCLAW_CANONICAL_PEER_ID="<lobby-tokenId-from-agent-card>"
+npx @rodit/verify-hola report "HOLA/..." --rpc
+```
+
+Registry: [com.identyclaw.lemuel_gulliver](https://www.a2a-registry.org/agent/com.identyclaw.lemuel_gulliver)
+
+Web UI (API path): https://verify.identyclaw.com
+
+## API
+
+```javascript
+const { buildHolaReportViaRpc } = require("@rodit/verify-hola/lib/verify-rpc");
+
+const report = await buildHolaReportViaRpc(hola, {
+  nearRpcUrl: process.env.NEAR_RPC_URL,
+  nearContractId: process.env.NEAR_CONTRACT_ID,
+  canonicalPeerId: "abcdefghijkl"
+});
+```
+
+## Related
+
+- [`references/verify-hola-recipes.md`](../references/verify-hola-recipes.md)
+- [`references/identity-verification-policy.md`](../references/identity-verification-policy.md) §1
+- MCP `doc:reference:verify-hola-recipes`
+
+---
+
+[discernible.io](https://www.discernible.io) · [identyclaw-agents](https://github.com/discernible-io/identyclaw-agents) · [discernible-io](https://github.com/discernible-io)

package/bin/verify-hola.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+"use strict";
+
+const { buildHolaReport, verifyHola } = require("../lib/report");
+const { buildHolaReportViaRpc, verifyHolaViaRpc } = require("../lib/verify-rpc");
+
+function usage() {
+  process.stderr.write(`Usage:
+  verify-hola verify <hola-string> [--rpc] [--expected-recipient <tokenId>]
+  verify-hola report <hola-string> [--rpc] [--expected-recipient <tokenId>] [--canonical-peer <tokenId>]
+  echo "HOLA/..." | verify-hola report - --rpc
+
+Verify paths:
+  --rpc     Direct NEAR RPC via @rodit/rodit-auth-be (recommended — no IdentyClaw API)
+  default   POST /api/identity/verify on IDENTYCLAW_BASE_URL
+
+RPC env (required with --rpc):
+  NEAR_RPC_URL          e.g. https://rpc.mainnet.fastnear.com
+  NEAR_CONTRACT_ID      e.g. genaaaa-identyclaw-com.near
+  NEAR_RPC_TIMEOUT      optional milliseconds (default from rodit-auth-be)
+
+API env (default path):
+  IDENTYCLAW_BASE_URL   default https://api.identyclaw.com
+  IDENTYCLAW_JWT        optional
+  IDENTYCLAW_CANONICAL_PEER_ID
+  IDENTYCLAW_EXPECTED_RECIPIENT
+`);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const command = args.shift();
+  let hola = args[0];
+  const options = {
+    useRpc: false,
+    expectedRecipient: process.env.IDENTYCLAW_EXPECTED_RECIPIENT,
+    canonicalPeerId: process.env.IDENTYCLAW_CANONICAL_PEER_ID,
+    baseUrl: process.env.IDENTYCLAW_BASE_URL,
+    jwt: process.env.IDENTYCLAW_JWT,
+    nearRpcUrl: process.env.NEAR_RPC_URL,
+    nearContractId: process.env.NEAR_CONTRACT_ID
+  };
+
+  if (hola === "-") hola = null;
+
+  for (let i = 1; i < args.length; i += 1) {
+    const flag = args[i];
+    if (flag === "--rpc") {
+      options.useRpc = true;
+    } else if (flag === "--expected-recipient") {
+      options.expectedRecipient = args[++i];
+    } else if (flag === "--canonical-peer") {
+      options.canonicalPeerId = args[++i];
+    } else if (flag === "--base-url") {
+      options.baseUrl = args[++i];
+    } else if (flag === "--near-rpc-url") {
+      options.nearRpcUrl = args[++i];
+    } else if (flag === "--near-contract-id") {
+      options.nearContractId = args[++i];
+    }
+  }
+
+  return { command, hola, options };
+}
+
+async function readHolaFromStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const hola = Buffer.concat(chunks).toString("utf8").trim();
+  if (!hola) throw new Error("empty HOLA on stdin");
+  return hola;
+}
+
+async function main() {
+  const { command, hola: holaArg, options } = parseArgs(process.argv.slice(2));
+  if (!command || !["verify", "report"].includes(command)) {
+    usage();
+    process.exit(1);
+  }
+
+  const hola = holaArg ? holaArg : await readHolaFromStdin();
+
+  if (command === "verify") {
+    const result = options.useRpc
+      ? await verifyHolaViaRpc(hola, options)
+      : await verifyHola(hola, options);
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    process.exit(result.verified ? 0 : 1);
+    return;
+  }
+
+  const report = options.useRpc
+    ? await buildHolaReportViaRpc(hola, options)
+    : await buildHolaReport(hola, { ...options, includeProfile: true });
+
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  process.exit(report.verified ? 0 : 1);
+}
+
+main().catch((err) => {
+  process.stderr.write(JSON.stringify({ verified: false, error: err.message }) + "\n");
+  process.exit(1);
+});

package/lib/hola-validate.js

@@ -0,0 +1,178 @@
+const { validateHexNonce, computeHolaChecksum } = require("./nonce-encoding");
+
+function validateTokenIdFormat(value) {
+  return /^[A-Z]{12}$/.test(String(value || ""));
+}
+
+function validateHolaMessage(hola) {
+  const result = {
+    valid: false,
+    isSubagentFormat: false,
+    recipient: "MUNDO",
+    tokenId: null,
+    delegateId: null,
+    issuerTokenId: null,
+    subagentPublicKey: null,
+    isoTimestamp: null,
+    noncetsHex: null,
+    signatureB32: null,
+    checksumChar: null,
+    reason: null,
+    checks: {
+      formatValid: false,
+      checksumValid: false,
+      timestampValid: false,
+      noncetsValid: false
+    }
+  };
+
+  if (!hola || typeof hola !== "string") {
+    result.reason = "Missing or invalid hola parameter (must be a string)";
+    return result;
+  }
+
+  const MAX_HOLA_LENGTH = 512;
+  if (hola.length > MAX_HOLA_LENGTH) {
+    result.reason = `Hola string exceeds maximum length of ${MAX_HOLA_LENGTH} characters`;
+    return result;
+  }
+
+  const prefixLiteral = "HOLA/";
+  const normalizedHola = hola.toUpperCase();
+  if (!normalizedHola.startsWith(prefixLiteral)) {
+    result.reason = "Unsupported protocol; expected HOLA prefix";
+    return result;
+  }
+
+  result.checks.formatValid = true;
+  const withoutPrefix = normalizedHola.slice(prefixLiteral.length);
+  const recipientSeparatorIndex = withoutPrefix.indexOf("/");
+  if (recipientSeparatorIndex === -1) {
+    result.reason = "Invalid HOLA format: missing destinatary separator";
+    return result;
+  }
+
+  const recipientRaw = withoutPrefix.slice(0, recipientSeparatorIndex);
+  result.recipient = recipientRaw.length > 0 ? recipientRaw : "MUNDO";
+  const afterRecipient = withoutPrefix.slice(recipientSeparatorIndex + 1);
+
+  const lastSeparatorIndex = afterRecipient.lastIndexOf("/");
+  if (lastSeparatorIndex === -1) {
+    result.reason = "Invalid HOLA format: missing checksum separator";
+    return result;
+  }
+
+  const checksumCharRaw = afterRecipient.slice(lastSeparatorIndex + 1);
+  const beforeChecksum = afterRecipient.slice(0, lastSeparatorIndex);
+  if (!checksumCharRaw) {
+    result.reason = "Missing checksum";
+    return result;
+  }
+  result.checksumChar = checksumCharRaw.toUpperCase();
+
+  const signatureSeparatorIndex = beforeChecksum.lastIndexOf("/");
+  if (signatureSeparatorIndex === -1) {
+    result.reason = "Invalid HOLA format: missing signature separator";
+    return result;
+  }
+
+  result.signatureB32 = beforeChecksum.slice(signatureSeparatorIndex + 1);
+  const beforeSignature = beforeChecksum.slice(0, signatureSeparatorIndex);
+  if (!result.signatureB32) {
+    result.reason = "Missing signature";
+    return result;
+  }
+
+  const protocolSeparatorIndex = beforeSignature.lastIndexOf("/");
+  if (protocolSeparatorIndex === -1) {
+    result.reason = "Invalid HOLA format: missing protocol marker separator";
+    return result;
+  }
+
+  const protocolMarker = beforeSignature.slice(protocolSeparatorIndex + 1);
+  if (protocolMarker !== "API.IDENTYCLAW.COM") {
+    result.reason = `Invalid protocol marker: expected API.IDENTYCLAW.COM, got ${protocolMarker}`;
+    return result;
+  }
+
+  const beforeProtocol = beforeSignature.slice(0, protocolSeparatorIndex);
+  const noncetsHexSeparatorIndex = beforeProtocol.lastIndexOf("/");
+  if (noncetsHexSeparatorIndex === -1) {
+    result.reason = "Invalid HOLA format: missing noncets separator";
+    return result;
+  }
+
+  const noncetsHexRaw = beforeProtocol.slice(noncetsHexSeparatorIndex + 1);
+  const tokenAndTimestamp = beforeProtocol.slice(0, noncetsHexSeparatorIndex);
+  if (!noncetsHexRaw) {
+    result.reason = "Missing noncets";
+    return result;
+  }
+
+  const noncetsCheck = validateHexNonce(noncetsHexRaw);
+  if (!noncetsCheck.valid) {
+    result.reason = noncetsCheck.reason;
+    return result;
+  }
+
+  result.noncetsHex = noncetsCheck.original ?? noncetsCheck.value;
+  result.checks.noncetsValid = true;
+
+  const senderFields = tokenAndTimestamp.split("/");
+  if (senderFields.length === 2) {
+    result.tokenId = senderFields[0];
+    result.isoTimestamp = senderFields[1];
+  } else if (senderFields.length === 4) {
+    result.isSubagentFormat = true;
+    result.delegateId = senderFields[0];
+    result.issuerTokenId = senderFields[1];
+    result.subagentPublicKey = senderFields[2];
+    result.isoTimestamp = senderFields[3];
+    result.tokenId = result.issuerTokenId;
+  } else {
+    result.reason = "Invalid HOLA format: expected standard or subagent sender fields";
+    return result;
+  }
+
+  if (!result.tokenId) {
+    result.reason = result.isSubagentFormat ? "Missing issuerTokenId" : "Missing tokenId";
+    return result;
+  }
+
+  if (!validateTokenIdFormat(result.tokenId)) {
+    result.reason = result.isSubagentFormat
+      ? "Invalid issuerTokenId: must be exactly 12 letters"
+      : "Invalid tokenId: must be exactly 12 letters";
+    return result;
+  }
+
+  if (!result.isoTimestamp) {
+    result.reason = "Missing timestamp";
+    return result;
+  }
+
+  const tsMs = Date.parse(result.isoTimestamp);
+  if (Number.isNaN(tsMs)) {
+    result.reason = "Invalid timestamp: must be a valid ISO-8601 string";
+    return result;
+  }
+  result.checks.timestampValid = true;
+
+  const signedMessage = result.isSubagentFormat
+    ? `HOLA/${result.recipient}/${result.delegateId}/${result.issuerTokenId}/${result.subagentPublicKey}/${result.isoTimestamp}/${result.noncetsHex}/API.IDENTYCLAW.COM/`
+    : `HOLA/${result.recipient}/${result.tokenId}/${result.isoTimestamp}/${result.noncetsHex}/API.IDENTYCLAW.COM/`;
+  const canonicalSignedMessage = signedMessage.toUpperCase();
+  const checksumPrefix = `${canonicalSignedMessage}${result.signatureB32}/`;
+  const expectedChecksum = computeHolaChecksum(checksumPrefix);
+
+  if (result.checksumChar !== expectedChecksum) {
+    result.reason = `Invalid checksum: expected ${expectedChecksum}, got ${result.checksumChar}`;
+    return result;
+  }
+
+  result.checks.checksumValid = true;
+  result.valid = true;
+  return result;
+}
+
+module.exports = { validateHolaMessage };

package/lib/nonce-encoding.js

@@ -0,0 +1,26 @@
+const HOLA_CHECKSUM_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ";
+const HOLA_CHECKSUM_MOD = HOLA_CHECKSUM_ALPHABET.length;
+
+function validateHexNonce(nonce) {
+  if (typeof nonce !== "string") {
+    return { valid: false, value: null, reason: "nonce must be a string" };
+  }
+  const upper = nonce.toUpperCase();
+  if (upper.length === 0) {
+    return { valid: false, value: null, reason: "nonce must not be empty" };
+  }
+  if (!/^[0-9A-F]+$/.test(upper)) {
+    return { valid: false, value: null, reason: "nonce must contain only [0-9A-F] characters" };
+  }
+  return { valid: true, value: upper, original: nonce, reason: null };
+}
+
+function computeHolaChecksum(prefix) {
+  let sum = 0;
+  for (let i = 0; i < prefix.length; i += 1) {
+    sum += prefix.charCodeAt(i);
+  }
+  return HOLA_CHECKSUM_ALPHABET[sum % HOLA_CHECKSUM_MOD];
+}
+
+module.exports = { validateHexNonce, computeHolaChecksum };

package/lib/parse-dn.js

@@ -0,0 +1,89 @@
+/**
+ * Parse userselected_dn comma-separated key=value pairs (public subset for verify report).
+ */
+function splitDistinguishedName(rawDn) {
+  const parts = [];
+  let current = "";
+  let inQuotes = false;
+
+  for (let i = 0; i < rawDn.length; i += 1) {
+    const ch = rawDn[i];
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current += ch;
+      continue;
+    }
+    if (ch === "," && !inQuotes) {
+      if (current.trim()) parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+function parseDnComponent(part) {
+  const eq = part.indexOf("=");
+  if (eq <= 0) return null;
+  const attribute = part.slice(0, eq).trim();
+  let value = part.slice(eq + 1).trim();
+  if (value.startsWith('"') && value.endsWith('"')) {
+    value = value.slice(1, -1);
+  }
+  return { attribute, value };
+}
+
+function parseUserSelectedDn(rawDn) {
+  if (typeof rawDn !== "string" || rawDn.trim().length === 0) {
+    return {
+      displayName: null,
+      creature: null,
+      contactUris: [],
+      webhookUrl: null,
+      raw: rawDn || null
+    };
+  }
+
+  const components = splitDistinguishedName(rawDn.trim())
+    .map(parseDnComponent)
+    .filter(Boolean);
+
+  const attributes = {};
+  for (const component of components) {
+    const key = component.attribute;
+    if (Object.prototype.hasOwnProperty.call(attributes, key)) {
+      const existing = attributes[key];
+      attributes[key] = Array.isArray(existing)
+        ? [...existing, component.value]
+        : [existing, component.value];
+    } else {
+      attributes[key] = component.value;
+    }
+  }
+
+  const find = (name) =>
+    components.find((c) => c.attribute.toUpperCase() === name.toUpperCase()) || null;
+
+  const nnswf = find("NNSWF");
+  const nswf = find("NSWF");
+  const displayNameParts = [];
+  if (nnswf?.value) displayNameParts.push(nnswf.value);
+  if (nswf?.value) displayNameParts.push(nswf.value);
+
+  const contactUris = components
+    .filter((c) => c.attribute.toUpperCase() === "CONTACTURI")
+    .map((c) => c.value);
+
+  return {
+    displayName: displayNameParts.length > 0 ? displayNameParts.join(" ").trim() : null,
+    creature: attributes.Creature || attributes.creature || null,
+    contactUris,
+    webhookUrl: attributes.webhook_url || null,
+    raw: rawDn.trim(),
+    attributes
+  };
+}
+
+module.exports = { parseUserSelectedDn };

package/lib/report.js

@@ -0,0 +1,133 @@
+const { parseUserSelectedDn } = require("./parse-dn");
+
+const DEFAULT_BASE = "https://api.identyclaw.com";
+
+async function verifyHola(hola, { baseUrl = DEFAULT_BASE, jwt, expectedRecipient, includeProfile = false } = {}) {
+  const body = { hola };
+  if (expectedRecipient) body.expectedRecipient = expectedRecipient;
+  if (includeProfile) body.includeProfile = true;
+
+  const headers = { "Content-Type": "application/json", Accept: "application/json" };
+  if (jwt) headers.Authorization = `Bearer ${jwt}`;
+
+  const res = await fetch(`${baseUrl.replace(/\/$/, "")}/api/identity/verify`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+
+  const result = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message =
+      result?.error?.message || result?.message || `HTTP ${res.status}`;
+    throw new Error(message);
+  }
+  return result;
+}
+
+async function resolveDid(tokenId, { baseUrl = DEFAULT_BASE } = {}) {
+  const normalized = String(tokenId || "").trim().toLowerCase();
+  if (!/^[a-z]{12}$/.test(normalized)) {
+    throw new Error("tokenId must be 12 lowercase letters");
+  }
+
+  const res = await fetch(
+    `${baseUrl.replace(/\/$/, "")}/api/mcp/resource/did:resolve:${normalized}`,
+    { headers: { Accept: "application/json" } }
+  );
+
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(payload?.error?.message || `DID resolve HTTP ${res.status}`);
+  }
+
+  const content = payload?.content ?? payload;
+  return typeof content === "string" ? JSON.parse(content) : content;
+}
+
+function extractProfileFromDid(didDocument) {
+  const metadataService = (didDocument?.service || []).find(
+    (s) => s.type === "RoditTokenMetadata"
+  );
+  const metadata = metadataService?.serviceEndpoint?.metadata || {};
+  const rawDn = metadata.userselected_dn || null;
+  const parsed = parseUserSelectedDn(rawDn);
+
+  return {
+    tokenId: metadataService?.serviceEndpoint?.tokenId || didDocument?.id?.split(":").pop() || null,
+    ownerAccountId: metadataService?.serviceEndpoint?.ownerAccountId || didDocument?.controller || null,
+    did: didDocument?.id || null,
+    displayName: parsed.displayName,
+    creature: parsed.creature,
+    contactUris: parsed.contactUris,
+    webhookUrl: metadata.webhook_url || parsed.webhookUrl || null,
+    dn: parsed
+  };
+}
+
+async function buildHolaReport(hola, options = {}) {
+  const {
+    baseUrl = DEFAULT_BASE,
+    jwt,
+    expectedRecipient,
+    canonicalPeerId,
+    includeProfile = true
+  } = options;
+
+  const verifyResult = await verifyHola(hola, {
+    baseUrl,
+    jwt,
+    expectedRecipient,
+    includeProfile
+  });
+
+  const report = {
+    verified: Boolean(verifyResult.verified),
+    peerTokenId: verifyResult.peerTokenId || null,
+    destinatary: verifyResult.destinatary || null,
+    checks: verifyResult.checks || {},
+    failureReasons: verifyResult.failureReasons || [],
+    failureDetails: verifyResult.failureDetails || [],
+    warnings: verifyResult.warnings || [],
+    requestId: verifyResult.requestId || null,
+    impersonationGuard: null,
+    profile: null
+  };
+
+  if (canonicalPeerId && report.verified) {
+    const expected = String(canonicalPeerId).trim().toLowerCase();
+    const matched = report.peerTokenId === expected;
+    report.impersonationGuard = {
+      expectedTokenId: expected,
+      matched,
+      passed: matched
+    };
+    if (!matched) {
+      report.verified = false;
+      report.failureReasons = [...(report.failureReasons || []), "impersonation_guard_failed"];
+    }
+  }
+
+  if (includeProfile && report.peerTokenId && !verifyResult.profile) {
+    try {
+      const didDocument = await resolveDid(report.peerTokenId, { baseUrl });
+      report.profile = extractProfileFromDid(didDocument);
+    } catch (error) {
+      report.profile = { error: error.message };
+    }
+  }
+
+  if (verifyResult.profile) {
+    report.profile = { ...report.profile, ...verifyResult.profile };
+  }
+
+  return report;
+}
+
+module.exports = {
+  DEFAULT_BASE,
+  verifyHola,
+  resolveDid,
+  extractProfileFromDid,
+  buildHolaReport
+};

package/lib/verify-rpc.js

@@ -0,0 +1,250 @@
+const base32 = require("hi-base32");
+const nacl = require("tweetnacl");
+const { validateHolaMessage } = require("./hola-validate");
+const { parseUserSelectedDn } = require("./parse-dn");
+
+const DEFAULT_MAX_HOLA_AGE_MS = 5 * 60 * 1000;
+const nonceReplayCache = new Map();
+
+function decodeBase32ToBytes(value) {
+  const raw = String(value).toUpperCase().replace(/=+$/g, "");
+  if (!/^[A-Z2-7]+$/.test(raw)) {
+    throw new Error("Invalid base32 input");
+  }
+  const padded = raw.padEnd(Math.ceil(raw.length / 8) * 8, "=");
+  return new Uint8Array(base32.decode.asBytes(padded));
+}
+
+function isRoditTokenExpired(token) {
+  const notAfter = token?.metadata?.not_after;
+  if (!notAfter || String(notAfter).startsWith("1970-01-01")) {
+    return false;
+  }
+  const notAfterMs = Date.parse(String(notAfter));
+  if (Number.isNaN(notAfterMs)) {
+    return false;
+  }
+  return Date.now() > notAfterMs;
+}
+
+function cleanupExpiredVerifyNonceEntries() {
+  const now = Date.now();
+  for (const [key, entry] of nonceReplayCache.entries()) {
+    if (!entry || entry.expiresAtMs <= now) {
+      nonceReplayCache.delete(key);
+    }
+  }
+}
+
+function buildProfileFromToken(token, tokenId) {
+  const metadata = token?.metadata || {};
+  const parsed = parseUserSelectedDn(metadata.userselected_dn || "");
+  return {
+    tokenId: String(tokenId).toLowerCase(),
+    did: `did:rodit:${String(tokenId).toLowerCase()}`,
+    ownerAccountId: token?.owner_id || null,
+    displayName: parsed.displayName,
+    creature: parsed.creature,
+    contactUris: parsed.contactUris,
+    webhookUrl: metadata.webhook_url || parsed.webhookUrl || null
+  };
+}
+
+function ensureNearEnv({ nearRpcUrl, nearContractId } = {}) {
+  if (nearRpcUrl) process.env.NEAR_RPC_URL = nearRpcUrl;
+  if (nearContractId) process.env.NEAR_CONTRACT_ID = nearContractId;
+
+  const rpc = process.env.NEAR_RPC_URL;
+  const contract = process.env.NEAR_CONTRACT_ID;
+  if (!rpc) {
+    throw new Error("NEAR_RPC_URL is required for --rpc verification (e.g. https://rpc.mainnet.fastnear.com)");
+  }
+  if (!contract) {
+    throw new Error("NEAR_CONTRACT_ID is required for --rpc verification (e.g. genaaaa-identyclaw-com.near)");
+  }
+  return { rpc, contract };
+}
+
+async function verifyHolaViaRpc(hola, options = {}) {
+  const {
+    maxAgeMs = DEFAULT_MAX_HOLA_AGE_MS,
+    nearRpcUrl,
+    nearContractId
+  } = options;
+
+  ensureNearEnv({ nearRpcUrl, nearContractId });
+
+  const validation = validateHolaMessage(hola);
+  if (!validation.valid) {
+    return {
+      verified: false,
+      verifyPath: "near-rpc",
+      peerTokenId: validation.tokenId ? String(validation.tokenId).toLowerCase() : null,
+      destinatary: validation.recipient,
+      checks: {
+        tokenExists: false,
+        tokenActive: false,
+        signatureValid: false,
+        timestampFresh: false,
+        checksumValid: Boolean(validation.checks?.checksumValid),
+        nonceReplaySafe: true
+      },
+      failureReasons: ["hola_format_invalid"],
+      failureDetails: [{ reasonCode: "hola_format_invalid", message: validation.reason }],
+      profile: null
+    };
+  }
+
+  const lookupTokenId = String(validation.tokenId).toLowerCase();
+  const checks = {
+    tokenExists: false,
+    tokenActive: false,
+    signatureValid: false,
+    timestampFresh: false,
+    checksumValid: true,
+    nonceReplaySafe: true
+  };
+  const failureReasons = [];
+
+  const tsMs = Date.parse(validation.isoTimestamp);
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const tsSeconds = Math.floor(tsMs / 1000);
+  const ageSeconds = nowSeconds - tsSeconds;
+  const maxAgeSeconds = Math.floor(maxAgeMs / 1000);
+  if (ageSeconds >= 0 && ageSeconds <= maxAgeSeconds) {
+    checks.timestampFresh = true;
+  } else {
+    failureReasons.push("timestamp_stale_or_future");
+  }
+
+  cleanupExpiredVerifyNonceEntries();
+  const nonceReplayKey = `${lookupTokenId}|${String(validation.noncetsHex).toUpperCase()}`;
+  if (nonceReplayCache.has(nonceReplayKey)) {
+    checks.nonceReplaySafe = false;
+    failureReasons.push("nonce_replay");
+  }
+
+  const { blockchainService } = require("@rodit/rodit-auth-be");
+  let token = null;
+  let profile = null;
+
+  try {
+    token = await blockchainService.nearorg_rpc_tokenfromroditid(lookupTokenId);
+    if (token && token.token_id) {
+      checks.tokenExists = true;
+      checks.tokenActive = !isRoditTokenExpired(token);
+      profile = buildProfileFromToken(token, lookupTokenId);
+      if (!checks.tokenActive) {
+        failureReasons.push("token_expired");
+      }
+    } else {
+      failureReasons.push("token_missing");
+    }
+
+    if (token && token.owner_id) {
+      let publicKeyBytes;
+      if (validation.isSubagentFormat) {
+        try {
+          publicKeyBytes = decodeBase32ToBytes(validation.subagentPublicKey);
+          if (publicKeyBytes.length !== 32) {
+            failureReasons.push("subagent_public_key_invalid_length");
+            publicKeyBytes = null;
+          }
+        } catch {
+          failureReasons.push("subagent_public_key_decode_failed");
+          publicKeyBytes = null;
+        }
+      } else {
+        publicKeyBytes = await blockchainService.nearorg_rpc_fetchpublickeybytes(token.owner_id);
+      }
+
+      if (publicKeyBytes && publicKeyBytes.length === 32) {
+        const message = validation.isSubagentFormat
+          ? `HOLA/${validation.recipient}/${validation.delegateId}/${validation.issuerTokenId}/${validation.subagentPublicKey}/${validation.isoTimestamp}/${validation.noncetsHex}/API.IDENTYCLAW.COM/`
+          : `HOLA/${validation.recipient}/${validation.tokenId}/${validation.isoTimestamp}/${validation.noncetsHex}/API.IDENTYCLAW.COM/`;
+        const canonicalMessage = message.toUpperCase();
+        const messageBytes = new TextEncoder().encode(canonicalMessage);
+        const signatureBytes = decodeBase32ToBytes(validation.signatureB32);
+        if (nacl.sign.detached.verify(messageBytes, signatureBytes, publicKeyBytes)) {
+          checks.signatureValid = true;
+        } else {
+          failureReasons.push("signature_invalid");
+        }
+      } else if (!validation.isSubagentFormat) {
+        failureReasons.push("public_key_unavailable");
+      }
+    }
+  } catch (error) {
+    failureReasons.push("public_key_error");
+    return {
+      verified: false,
+      verifyPath: "near-rpc",
+      peerTokenId: lookupTokenId,
+      destinatary: validation.recipient,
+      checks,
+      failureReasons,
+      failureDetails: [{ reasonCode: "public_key_error", message: error.message }],
+      profile
+    };
+  }
+
+  const verified =
+    checks.tokenExists &&
+    checks.tokenActive &&
+    checks.timestampFresh &&
+    checks.nonceReplaySafe &&
+    checks.signatureValid &&
+    checks.checksumValid;
+
+  if (verified) {
+    nonceReplayCache.set(nonceReplayKey, {
+      expiresAtMs: tsMs + maxAgeMs,
+      firstSeenAtMs: Date.now()
+    });
+  }
+
+  const response = {
+    verified,
+    verifyPath: "near-rpc",
+    nearRpcUrl: process.env.NEAR_RPC_URL,
+    nearContractId: process.env.NEAR_CONTRACT_ID,
+    peerTokenId: lookupTokenId,
+    destinatary: validation.recipient,
+    checks,
+    failureReasons,
+    profile
+  };
+
+  if (validation.isSubagentFormat) {
+    response.isSubagentFormat = true;
+    response.delegateId = validation.delegateId;
+    response.issuerTokenId = validation.issuerTokenId;
+    response.subagentNote =
+      "Subagent delegation requires POST /api/isauthorizedsigner — not checked on --rpc path";
+  }
+
+  return response;
+}
+
+async function buildHolaReportViaRpc(hola, options = {}) {
+  const { canonicalPeerId, ...rpcOptions } = options;
+  const report = await verifyHolaViaRpc(hola, rpcOptions);
+
+  if (canonicalPeerId && report.verified) {
+    const expected = String(canonicalPeerId).trim().toLowerCase();
+    const matched = report.peerTokenId === expected;
+    report.impersonationGuard = { expectedTokenId: expected, matched, passed: matched };
+    if (!matched) {
+      report.verified = false;
+      report.failureReasons = [...(report.failureReasons || []), "impersonation_guard_failed"];
+    }
+  }
+
+  return report;
+}
+
+module.exports = {
+  verifyHolaViaRpc,
+  buildHolaReportViaRpc,
+  ensureNearEnv
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rodit/verify-hola",
+  "version": "0.1.3",
+  "description": "Verify HOLA lines and build passport reports via api.identyclaw.com (no JWT required for verify)",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "lib/report.js",
+  "bin": {
+    "verify-hola": "bin/verify-hola.js"
+  },
+  "dependencies": {
+    "@rodit/rodit-auth-be": "9.17.4",
+    "hi-base32": "^0.5.1",
+    "tweetnacl": "^1.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "identyclaw",
+    "hola",
+    "agent-identity",
+    "verification",
+    "near",
+    "rodit"
+  ],
+  "author": "Discernible IO",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/discernible-io/rodit-sdk.git",
+    "directory": "verify-hola"
+  },
+  "bugs": {
+    "url": "https://github.com/discernible-io/rodit-sdk/issues"
+  },
+  "homepage": "https://github.com/discernible-io/rodit-sdk/tree/main/verify-hola#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/report.test.js"
+  }
+}