Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

12.9 KB
Raw Blame
// Open Inference Protocol (OIN) v0.1 verifier and signing primitives.
//
// Implements the verification rules from specs/OPEN_INFERENCE_PROTOCOL.md:
// canonical (RFC 8785 JCS) JSON, SHA-256 job digests, and Ed25519 response
// signatures over the canonical response minus its `signature` field.
// Dependency-free (Node stdlib only) so any requester, relay, or auditor can
// verify a node's signed response without trusting the transport.
//
// Exported API surface (see the named exports below):
//   canonicalize: canonical JSON string per RFC 8785
//   digestJob: lowercase hex SHA-256 of the canonical envelope
//   signResponse / signAdvertisement: fill in `signature` on the node side
//   verifyResponse: returns { ok, verdict, ... } for a job/response pair
//   verifyAdvertisement: same signature rule applied to /.well-known/oin
//   verifyOutput: spec rule 6, hash the bytes at output.url and compare
//
// Verdicts are the exact codes the spec names: bad_shape, job_digest_mismatch,
// bad_pubkey, untrusted_node, bad_signature, stale_response, future_response,
// output_digest_mismatch, verified, verified_unfetched_output.

import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';

export const OIN_SPEC = 'oin/0.1';
const MAX_FUTURE_SKEW_MS = 24 * 60 * 60 * 1000;
const MAX_OUTPUT_BYTES = 256 * 1024 * 1024;

// ── canonical JSON (RFC 8785 JCS) ────────────────────────────────────────────

function canonicalizeNumber(n) {
	if (!Number.isFinite(n)) throw new TypeError('OIN canonicalization: non-finite number');
	// JCS uses the ECMAScript Number::toString algorithm, which JSON.stringify
	// already implements for finite numbers.
	return JSON.stringify(n);
}

function canonicalize(value) {
	if (value === null) return 'null';
	const t = typeof value;
	if (t === 'boolean') return value ? 'true' : 'false';
	if (t === 'number') return canonicalizeNumber(value);
	if (t === 'string') return JSON.stringify(value);
	if (Array.isArray(value)) return `[${value.map((v) => canonicalize(v)).join(',')}]`;
	if (t === 'object') {
		// JCS sorts object keys by UTF-16 code units, which is Array.prototype.sort's default.
		const keys = Object.keys(value).filter((k) => value[k] !== undefined && typeof value[k] !== 'function').sort();
		return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(',')}}`;
	}
	throw new TypeError(`OIN canonicalization: unsupported type ${t}`);
}

// ── digests and keys ─────────────────────────────────────────────────────────

function sha256hex(bytes) {
	return createHash('sha256').update(bytes).digest('hex');
}

function digestJob(envelope) {
	return sha256hex(Buffer.from(canonicalize(envelope), 'utf8'));
}

function keyObjectFromSecret(keyB64) {
	const raw = Buffer.from(String(keyB64), 'base64');
	if (raw.length !== 32 && raw.length !== 64) {
		throw new Error('OIN signing key must be 32-byte seed or 64-byte expanded key, base64');
	}
	// PKCS#8 DER wrapper for a raw Ed25519 seed: 302e020100300506032b657004220420 || seed
	const seed = raw.length === 64 ? raw.subarray(0, 32) : raw;
	const der = Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), seed]);
	return createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
}

function pubkeyB64FromSecret(keyB64) {
	const priv = keyObjectFromSecret(keyB64);
	const der = createPublicKey(priv).export({ format: 'der', type: 'spki' });
	// SPKI for Ed25519 is 12 bytes of header + the 32-byte key.
	return Buffer.from(der).subarray(-32).toString('base64');
}

function pubKeyObjectFromField(nodePubkey) {
	if (typeof nodePubkey !== 'string' || !nodePubkey.startsWith('ed25519:')) return null;
	const raw = Buffer.from(nodePubkey.slice('ed25519:'.length), 'base64');
	if (raw.length !== 32) return null;
	// SPKI DER wrapper for a raw Ed25519 public key: 302a300506032b6570032100 || key
	const der = Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), raw]);
	try {
		return createPublicKey({ key: der, format: 'der', type: 'spki' });
	} catch {
		return null;
	}
}

// ── signing (node side) ──────────────────────────────────────────────────────

function signPayload(payload, keyB64) {
	const priv = keyObjectFromSecret(keyB64);
	const bytes = Buffer.from(canonicalize(payload), 'utf8');
	// Ed25519 is deterministic pure signing: null algorithm, message in one shot.
	return cryptoSign(null, bytes, priv).toString('base64');
}

function signResponse(response, keyB64) {
	const { signature: _drop, ...unsigned } = response;
	return { ...unsigned, signature: signPayload(unsigned, keyB64) };
}

function signAdvertisement(advertisement, keyB64) {
	const { signature: _drop, ...unsigned } = advertisement;
	return { ...unsigned, signature: signPayload(unsigned, keyB64) };
}

// ── verification (rules 1-5 of the spec) ─────────────────────────────────────

function fail(verdict, detail) {
	return { ok: false, verified: false, verdict, detail };
}

// The one signature rule both a response and an advertisement obey: drop
// `signature`, canonicalize what remains, verify Ed25519 over those bytes.
// Returns null on success, or a fail() result naming the verdict.
function checkDetachedSignature(signed, pub) {
	const { signature, ...unsigned } = signed;
	let sigBytes;
	try {
		sigBytes = Buffer.from(signature, 'base64');
	} catch {
		return fail('bad_signature', 'signature is not valid base64');
	}
	if (sigBytes.length !== 64) return fail('bad_signature', 'Ed25519 signature must be 64 bytes');
	let sigOk = false;
	try {
		sigOk = cryptoVerify(null, Buffer.from(canonicalize(unsigned), 'utf8'), pub, sigBytes);
	} catch {
		sigOk = false;
	}
	return sigOk ? null : fail('bad_signature', 'Ed25519 verification failed');
}

function verifyResponse(job, response, opts = {}) {
	// Rule 1: shape.
	if (!response || typeof response !== 'object' || Array.isArray(response)) {
		return fail('bad_shape', 'response is not an object');
	}
	if (response.spec !== OIN_SPEC) return fail('bad_shape', `spec must be ${OIN_SPEC}`);
	for (const field of ['job_digest', 'node_pubkey', 'completed_at', 'status', 'signature']) {
		if (typeof response[field] !== 'string' || !response[field]) {
			return fail('bad_shape', `missing field: ${field}`);
		}
	}
	if (response.status !== 'done' && response.status !== 'failed') {
		return fail('bad_shape', `status must be done|failed, got ${response.status}`);
	}
	if (response.status === 'done' && (!response.output || typeof response.output !== 'object')) {
		return fail('bad_shape', 'done response must carry output');
	}
	if (response.status === 'failed' && (!response.error || typeof response.error !== 'object')) {
		return fail('bad_shape', 'failed response must carry error');
	}
	if (response.status === 'done') {
		const { url, sha256, bytes } = response.output;
		if (typeof url !== 'string' || typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256) || !Number.isInteger(bytes) || bytes < 0) {
			return fail('bad_shape', 'output needs url, sha256 (64 lowercase hex), bytes (non-negative int)');
		}
	}
	if (!/^[0-9a-f]{64}$/.test(response.job_digest)) {
		return fail('bad_shape', 'job_digest must be 64 lowercase hex chars');
	}

	// Rule 2: job binding.
	const expectedDigest = digestJob(job);
	if (response.job_digest !== expectedDigest) {
		return fail('job_digest_mismatch', `expected ${expectedDigest}, got ${response.job_digest}`);
	}

	// Rule 3: key parses and (when pinned/advertised) matches.
	const pub = pubKeyObjectFromField(response.node_pubkey);
	if (!pub) return fail('bad_pubkey', 'node_pubkey must be ed25519:<base64 32-byte key>');
	if (opts.expectedPubkey && response.node_pubkey !== opts.expectedPubkey) {
		return fail('untrusted_node', `response key does not match pinned/advertised ${opts.expectedPubkey}`);
	}

	// Rule 4: signature over the canonical response minus `signature`.
	const sigFailure = checkDetachedSignature(response, pub);
	if (sigFailure) return sigFailure;

	// Rule 5: freshness against the job deadline and the verifier clock.
	const completedMs = Date.parse(response.completed_at);
	if (!Number.isFinite(completedMs)) return fail('bad_shape', 'completed_at must parse as ISO 8601');
	const now = opts.now instanceof Date ? opts.now.getTime() : Date.now();
	if (completedMs > now + MAX_FUTURE_SKEW_MS) {
		return fail('future_response', 'completed_at is more than 24h in the future');
	}
	const createdMs = Date.parse(job?.created_at);
	const deadlineS = Number(job?.deadline);
	if (Number.isFinite(createdMs) && Number.isFinite(deadlineS) && deadlineS > 0) {
		if (completedMs > createdMs + deadlineS * 1000) {
			return fail('stale_response', 'completed after the job deadline');
		}
	}

	return {
		ok: true,
		verified: true,
		verdict: 'verified',
		nodePubkey: response.node_pubkey,
		status: response.status,
	};
}

// A capability advertisement is verified by the same signature rule as a
// response, minus the job binding and freshness checks (there is no job, and an
// advertisement is regenerated per request). A requester runs this before it
// trusts what a node claims it can do, and a directory service runs it on every
// crawl. `opts.expectedPubkey` pins a key the caller already knows.
function verifyAdvertisement(advertisement, opts = {}) {
	if (!advertisement || typeof advertisement !== 'object' || Array.isArray(advertisement)) {
		return fail('bad_shape', 'advertisement is not an object');
	}
	if (advertisement.spec !== OIN_SPEC) return fail('bad_shape', `spec must be ${OIN_SPEC}`);
	for (const field of ['node_id', 'node_pubkey', 'generated_at', 'signature']) {
		if (typeof advertisement[field] !== 'string' || !advertisement[field]) {
			return fail('bad_shape', `missing field: ${field}`);
		}
	}
	if (!Array.isArray(advertisement.capabilities) || advertisement.capabilities.length === 0) {
		return fail('bad_shape', 'capabilities must be a non-empty array');
	}
	for (const cap of advertisement.capabilities) {
		if (!cap || typeof cap !== 'object' || typeof cap.key !== 'string' || !cap.key) {
			return fail('bad_shape', 'every capability needs a string key');
		}
	}
	if (!advertisement.endpoints || typeof advertisement.endpoints !== 'object') {
		return fail('bad_shape', 'endpoints must be an object');
	}
	if (advertisement.auth !== 'bearer' && advertisement.auth !== 'none') {
		return fail('bad_shape', `auth must be bearer|none, got ${advertisement.auth}`);
	}

	const pub = pubKeyObjectFromField(advertisement.node_pubkey);
	if (!pub) return fail('bad_pubkey', 'node_pubkey must be ed25519:<base64 32-byte key>');
	if (opts.expectedPubkey && advertisement.node_pubkey !== opts.expectedPubkey) {
		return fail('untrusted_node', `advertised key does not match pinned ${opts.expectedPubkey}`);
	}

	const sigFailure = checkDetachedSignature(advertisement, pub);
	if (sigFailure) return sigFailure;

	return {
		ok: true,
		verified: true,
		verdict: 'verified',
		nodeId: advertisement.node_id,
		nodePubkey: advertisement.node_pubkey,
		capabilities: advertisement.capabilities.map((c) => c.key),
	};
}

// Rule 6 (optional): fetch output.url and check bytes + sha256. The caller
// supplies the fetch implementation in tests; in production it must apply the
// SSRF guards the spec requires (https-only, private-IP rejection, size cap).
async function verifyOutput(response, fetchImpl) {
	if (!response?.output?.url) return fail('bad_shape', 'no output to verify');
	const doFetch = fetchImpl || globalThis.fetch;
	if (typeof doFetch !== 'function') return fail('output_digest_mismatch', 'no fetch implementation available');
	let bytes;
	try {
		const res = await doFetch(response.output.url);
		if (!res.ok) return fail('output_digest_mismatch', `fetch failed: HTTP ${res.status}`);
		const len = Number(res.headers?.get?.('content-length'));
		if (Number.isFinite(len) && len > MAX_OUTPUT_BYTES) {
			return fail('output_digest_mismatch', `output exceeds ${MAX_OUTPUT_BYTES} bytes`);
		}
		bytes = Buffer.from(await res.arrayBuffer());
	} catch (err) {
		return fail('output_digest_mismatch', `fetch failed: ${err?.message || err}`);
	}
	if (bytes.length > MAX_OUTPUT_BYTES) {
		return fail('output_digest_mismatch', `output exceeds ${MAX_OUTPUT_BYTES} bytes`);
	}
	if (bytes.length !== response.output.bytes) {
		return fail('output_digest_mismatch', `bytes ${bytes.length} != declared ${response.output.bytes}`);
	}
	const digest = sha256hex(bytes);
	if (digest !== response.output.sha256) {
		return fail('output_digest_mismatch', `sha256 ${digest} != declared ${response.output.sha256}`);
	}
	return { ok: true, verified: true, verdict: 'verified_with_output', bytes: bytes.length };
}

export {
	canonicalize,
	digestJob,
	pubkeyB64FromSecret,
	signAdvertisement,
	signResponse,
	verifyAdvertisement,
	verifyOutput,
	verifyResponse,
};