@calimero-network/mero-js 25.0.7 → 25.1.1

package/README.md

@@ -249,6 +249,31 @@ with no node of their own can be admitted by one of them. The `read` client is
 `null` until the relay's node key is attested, which is why the session is
 built in that order.
 
+## Private agents
+
+A private agent runs in a TDX VM (mero-tee's agent image) that several owners' agents share, each named by an agent id. Its gate proves which image runs and takes each agent's secrets only sealed to it, from its owner. These functions are that owner's side; whoever relays the requests (mdma included) sees only quotes and ciphertext.
+
+```ts
+import { verify as dcapVerify, getCollateral } from '@phala/dcap-qvl';
+import {
+  agentQuoteVerifier, attestAgent, generateOwnerKey, provisionAgent, releaseAgent, verifySignedAgentPolicy,
+} from '@calimero-network/mero-js';
+
+// The mero-kms release's agent allowlist, checked against its Sigstore signature.
+const policy = await verifySignedAgentPolicy(policyJson, bundleJson, { profile: 'locked-read-only' });
+const verifier = agentQuoteVerifier(policy, { dcapVerify, fetchCollateral: (quote) => getCollateral(PCCS_URL, quote) });
+
+const owner = await generateOwnerKey(); // keep owner.secret: only it can change or release the agent
+const agent = await attestAgent({ gateUrl, agentId: 'a-1f2e', verifier });
+await provisionAgent({ gateUrl, agent, ownerSecret: owner.secret, verifier, secrets: { NEAR_AI_API_KEY: key } });
+// later: await releaseAgent({ gateUrl, agent: await attestAgent({ gateUrl, agentId, verifier }), ownerSecret, verifier });
+```
+
+- `attestAgent` returns the agent's keys only once its quote verifies: genuine, from an image in the policy, not a debug TD, for your nonce, and committing to the agent id asked about and to the keys the gate names.
+- `provisionAgent` refuses an agent another key claimed before sending anything. The first bundle for an unclaimed agent claims it for your key, and a fresh quote must then name your key as owner.
+- Secrets are sealed with RFC 9180 HPKE in Auth mode (X25519, HKDF-SHA256, ChaCha20-Poly1305) to the gate's in-memory key, for that agent id only.
+- `releaseAgent` stops the agent and erases its slot; a fresh quote must name no owner.
+
 ## Lower-level HTTP client
 
 If you need raw HTTP against a node (without the `MeroJs` facade), the SDK

package/dist/agent-gate/chacha20poly1305.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ChaCha20-Poly1305 (RFC 8439), the AEAD mero-agent-gate's HPKE suite uses.
+ * WebCrypto has no ChaCha20, and the SDK takes no runtime dependencies, so it
+ * is written here from the RFC. Its tests check it against the RFC's vectors
+ * and against Node's own implementation.
+ *
+ * Only for sealing a provisioning bundle once: short messages, one key per
+ * message. Not constant-time in Poly1305's arithmetic (BigInt), which leaks
+ * nothing here: the one-time Poly1305 key is never reused.
+ */
+/** One 64-byte ChaCha20 block (RFC 8439 §2.3). */
+export declare function chacha20Block(key: Uint8Array, counter: number, nonce: Uint8Array): Uint8Array;
+/** ChaCha20 encryption from block `counter` on (RFC 8439 §2.4). */
+export declare function chacha20(key: Uint8Array, counter: number, nonce: Uint8Array, data: Uint8Array): Uint8Array;
+/** Poly1305 over `message` with the one-time `key` (RFC 8439 §2.5). */
+export declare function poly1305(key: Uint8Array, message: Uint8Array): Uint8Array;
+/** Seal: the ciphertext followed by its 16-byte tag (RFC 8439 §2.8). */
+export declare function chacha20Poly1305Seal(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+/** Open what {@link chacha20Poly1305Seal} made; throws if it was altered. */
+export declare function chacha20Poly1305Open(key: Uint8Array, nonce: Uint8Array, sealed: Uint8Array, aad?: Uint8Array): Uint8Array;

package/dist/agent-gate/chacha20poly1305.js

@@ -0,0 +1,148 @@
+/**
+ * ChaCha20-Poly1305 (RFC 8439), the AEAD mero-agent-gate's HPKE suite uses.
+ * WebCrypto has no ChaCha20, and the SDK takes no runtime dependencies, so it
+ * is written here from the RFC. Its tests check it against the RFC's vectors
+ * and against Node's own implementation.
+ *
+ * Only for sealing a provisioning bundle once: short messages, one key per
+ * message. Not constant-time in Poly1305's arithmetic (BigInt), which leaks
+ * nothing here: the one-time Poly1305 key is never reused.
+ */
+const KEY_LEN = 32;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+function rotl(value, shift) {
+    return ((value << shift) | (value >>> (32 - shift))) >>> 0;
+}
+function quarterRound(s, a, b, c, d) {
+    s[a] = (s[a] + s[b]) >>> 0;
+    s[d] = rotl(s[d] ^ s[a], 16);
+    s[c] = (s[c] + s[d]) >>> 0;
+    s[b] = rotl(s[b] ^ s[c], 12);
+    s[a] = (s[a] + s[b]) >>> 0;
+    s[d] = rotl(s[d] ^ s[a], 8);
+    s[c] = (s[c] + s[d]) >>> 0;
+    s[b] = rotl(s[b] ^ s[c], 7);
+}
+function u32le(bytes, offset) {
+    return (bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16) | (bytes[offset + 3] << 24)) >>> 0;
+}
+/** One 64-byte ChaCha20 block (RFC 8439 §2.3). */
+export function chacha20Block(key, counter, nonce) {
+    const state = new Uint32Array(16);
+    state[0] = 0x61707865;
+    state[1] = 0x3320646e;
+    state[2] = 0x79622d32;
+    state[3] = 0x6b206574;
+    for (let i = 0; i < 8; i += 1)
+        state[4 + i] = u32le(key, i * 4);
+    state[12] = counter >>> 0;
+    for (let i = 0; i < 3; i += 1)
+        state[13 + i] = u32le(nonce, i * 4);
+    const working = state.slice();
+    for (let round = 0; round < 10; round += 1) {
+        quarterRound(working, 0, 4, 8, 12);
+        quarterRound(working, 1, 5, 9, 13);
+        quarterRound(working, 2, 6, 10, 14);
+        quarterRound(working, 3, 7, 11, 15);
+        quarterRound(working, 0, 5, 10, 15);
+        quarterRound(working, 1, 6, 11, 12);
+        quarterRound(working, 2, 7, 8, 13);
+        quarterRound(working, 3, 4, 9, 14);
+    }
+    const out = new Uint8Array(64);
+    for (let i = 0; i < 16; i += 1) {
+        const word = (working[i] + state[i]) >>> 0;
+        out[i * 4] = word & 0xff;
+        out[i * 4 + 1] = (word >>> 8) & 0xff;
+        out[i * 4 + 2] = (word >>> 16) & 0xff;
+        out[i * 4 + 3] = (word >>> 24) & 0xff;
+    }
+    return out;
+}
+/** ChaCha20 encryption from block `counter` on (RFC 8439 §2.4). */
+export function chacha20(key, counter, nonce, data) {
+    const out = new Uint8Array(data.length);
+    for (let offset = 0, block = counter; offset < data.length; offset += 64, block += 1) {
+        const stream = chacha20Block(key, block, nonce);
+        const end = Math.min(offset + 64, data.length);
+        for (let i = offset; i < end; i += 1)
+            out[i] = data[i] ^ stream[i - offset];
+    }
+    return out;
+}
+function leToBigInt(bytes) {
+    let value = 0n;
+    for (let i = bytes.length - 1; i >= 0; i -= 1)
+        value = (value << 8n) | BigInt(bytes[i]);
+    return value;
+}
+const P1305 = (1n << 130n) - 5n;
+/** Poly1305 over `message` with the one-time `key` (RFC 8439 §2.5). */
+export function poly1305(key, message) {
+    const r = leToBigInt(key.subarray(0, 16)) & 0x0ffffffc0ffffffc0ffffffc0fffffffn;
+    const s = leToBigInt(key.subarray(16, 32));
+    let acc = 0n;
+    for (let offset = 0; offset < message.length; offset += 16) {
+        const block = message.subarray(offset, Math.min(offset + 16, message.length));
+        const n = leToBigInt(block) + (1n << BigInt(8 * block.length));
+        acc = ((acc + n) * r) % P1305;
+    }
+    let tag = (acc + s) & ((1n << 128n) - 1n);
+    const out = new Uint8Array(TAG_LEN);
+    for (let i = 0; i < TAG_LEN; i += 1) {
+        out[i] = Number(tag & 0xffn);
+        tag >>= 8n;
+    }
+    return out;
+}
+function pad16(length) {
+    return new Uint8Array((16 - (length % 16)) % 16);
+}
+function u64le(value) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, BigInt(value), true);
+    return out;
+}
+function macData(aad, ciphertext) {
+    const parts = [aad, pad16(aad.length), ciphertext, pad16(ciphertext.length), u64le(aad.length), u64le(ciphertext.length)];
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function check(key, nonce) {
+    if (key.length !== KEY_LEN)
+        throw new Error('ChaCha20-Poly1305 needs a 32-byte key');
+    if (nonce.length !== NONCE_LEN)
+        throw new Error('ChaCha20-Poly1305 needs a 12-byte nonce');
+}
+/** Seal: the ciphertext followed by its 16-byte tag (RFC 8439 §2.8). */
+export function chacha20Poly1305Seal(key, nonce, plaintext, aad = new Uint8Array(0)) {
+    check(key, nonce);
+    const otk = chacha20Block(key, 0, nonce).subarray(0, 32);
+    const ciphertext = chacha20(key, 1, nonce, plaintext);
+    const tag = poly1305(otk, macData(aad, ciphertext));
+    const out = new Uint8Array(ciphertext.length + TAG_LEN);
+    out.set(ciphertext);
+    out.set(tag, ciphertext.length);
+    return out;
+}
+/** Open what {@link chacha20Poly1305Seal} made; throws if it was altered. */
+export function chacha20Poly1305Open(key, nonce, sealed, aad = new Uint8Array(0)) {
+    check(key, nonce);
+    if (sealed.length < TAG_LEN)
+        throw new Error('The sealed message is shorter than its tag');
+    const ciphertext = sealed.subarray(0, sealed.length - TAG_LEN);
+    const otk = chacha20Block(key, 0, nonce).subarray(0, 32);
+    const expected = poly1305(otk, macData(aad, ciphertext));
+    let diff = 0;
+    for (let i = 0; i < TAG_LEN; i += 1)
+        diff |= expected[i] ^ sealed[ciphertext.length + i];
+    if (diff !== 0)
+        throw new Error('The sealed message did not authenticate');
+    return chacha20(key, 1, nonce, ciphertext);
+}

package/dist/agent-gate/gate.d.ts

@@ -0,0 +1,115 @@
+/**
+ * A client for mero-agent-gate, the gate in a private agent TD (mero-tee,
+ * `mero-agent-gate/`): attest an agent, claim it with your key, give it its
+ * secrets sealed to the TD, and release it. It runs where the owner is (a
+ * browser, a CLI), so whoever carries the requests, mdma included, sees only
+ * quotes and ciphertext.
+ *
+ * One agent TD hosts several owners' agents, each named by an agent id. For
+ * an agent the gate's quote binds, in its report data:
+ *
+ * `nonce ‖ SHA-256("mero-agent-gate/attest/v3" ‖ provisioning_pub ‖ len(id) ‖ id ‖ signing_pub ‖ owner_pub)`
+ *
+ * (signing and owner keys 32 zero bytes while unclaimed). {@link attestAgent}
+ * checks that and the quote itself before returning anything; every function
+ * that sends refuses an agent whose quote names another owner.
+ *
+ * ```ts
+ * import { verify as dcapVerify, getCollateral } from '@phala/dcap-qvl';
+ *
+ * const policy = await verifySignedAgentPolicy(policyJson, bundleJson, { profile: 'locked-read-only' });
+ * const verifier = agentQuoteVerifier(policy, { dcapVerify, fetchCollateral: (q) => getCollateral(PCCS, q) });
+ * const owner = await generateOwnerKey(); // keep owner.secret: it is the only key that can change the agent
+ * const agent = await attestAgent({ gateUrl, agentId: 'a-1f2e', verifier });
+ * await provisionAgent({ gateUrl, agent, ownerSecret: owner.secret, verifier, secrets: { NEAR_AI_API_KEY: key } });
+ * ```
+ */
+import type { VerifyTransportQuote } from '../sealed/sealed.js';
+export declare const AGENT_ATTEST_DOMAIN = "mero-agent-gate/attest/v3";
+export declare const AGENT_PROVISION_INFO_DOMAIN = "mero-agent-gate/provision/v2";
+/** A gate's refusal, with its `error` code (`not_the_owner`, `no_free_slot`, …) when it gave one. */
+export declare class AgentGateError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, status?: number, code?: string);
+}
+/** An agent's keys, once its quote passed {@link attestAgent}'s checks. */
+export interface VerifiedAgent {
+    agentId: string;
+    /** Base64; secrets are sealed to it. Valid until the gate restarts. */
+    provisioningPublicKey: string;
+    /** Base64 Ed25519 key the agent signs with; absent while unclaimed. */
+    signingPublicKey?: string;
+    /** Base64 X25519 key of the owner that claimed it; absent while unclaimed. */
+    ownerPublicKey?: string;
+}
+export interface OwnerKey {
+    /** 32 raw X25519 bytes. The only key that can provision or release the agent: keep it. */
+    secret: Uint8Array;
+    /** Base64 of the public half: what the gate's quote names as owner. */
+    publicKey: string;
+}
+type Fetch = typeof fetch;
+export declare function validateAgentId(agentId: string): void;
+/** The 32 bytes after the nonce in a gate's quote for `agentId` (empty: the TD alone). */
+export declare function agentKeyBinding(provisioningPublic: Uint8Array, agentId: string, signingPublic?: Uint8Array, ownerPublic?: Uint8Array): Promise<Uint8Array>;
+/** HPKE `info` for a message to `agentId` on the gate whose provisioning key is `recipientPublic`. */
+export declare function provisionInfo(recipientPublic: Uint8Array, agentId: string): Uint8Array;
+/** A fresh owner key, made here; it never needs to leave the owner. */
+export declare function generateOwnerKey(): Promise<OwnerKey>;
+/** The base64 public half of an owner's X25519 secret. */
+export declare function ownerPublicKey(secret: Uint8Array): Promise<string>;
+export interface AttestAgentOptions {
+    /** The gate's base URL, or a relay of it (mdma's): only verified quotes are trusted. */
+    gateUrl: string;
+    /** The agent to attest; omit for the TD alone (no keys, nothing to send to). */
+    agentId?: string;
+    /** Checks the quote's signature, TCB, image and report data: {@link agentQuoteVerifier}. */
+    verifier: VerifyTransportQuote;
+    fetch?: Fetch;
+}
+/**
+ * Ask the gate for a quote for `agentId` over a fresh nonce and verify it:
+ * a genuine quote from a measured agent image, for this nonce, committing to
+ * the agent id asked about and to the keys the gate names. Returns those
+ * keys only once every check has passed.
+ */
+export declare function attestAgent(options: AttestAgentOptions): Promise<VerifiedAgent>;
+/** The owner key `ownerSecret` may act on `agent`: it is unclaimed, or claimed by that key. */
+export declare function checkOwner(agent: VerifiedAgent, ownerSecret: Uint8Array): Promise<string>;
+export interface ProvisionAgentOptions {
+    gateUrl: string;
+    /** What {@link attestAgent} returned for this agent, just now. */
+    agent: VerifiedAgent;
+    ownerSecret: Uint8Array;
+    /** Name to value; a name replaces what was there, others stay. */
+    secrets: Record<string, string>;
+    /** The verifier `agent` was attested with: the claim is checked by a fresh quote. */
+    verifier: VerifyTransportQuote;
+    fetch?: Fetch;
+}
+export interface ProvisionedAgent extends Required<VerifiedAgent> {
+    written: string[];
+    /** Whether this claimed the agent for your key. */
+    claimed: boolean;
+}
+/**
+ * Seal `secrets` to the agent as its owner and send them. The first bundle for
+ * an unclaimed agent claims it for `ownerSecret`'s key. The gate's answer is
+ * not taken as proof: a fresh quote must name your key as owner, and the
+ * agent's signing key must not have changed.
+ */
+export declare function provisionAgent(options: ProvisionAgentOptions): Promise<ProvisionedAgent>;
+export interface ReleaseAgentOptions {
+    gateUrl: string;
+    agent: VerifiedAgent;
+    ownerSecret: Uint8Array;
+    verifier: VerifyTransportQuote;
+    fetch?: Fetch;
+}
+/**
+ * Release the agent as its owner: the gate stops it and erases its claim,
+ * keys, secrets and state. Checked by a fresh quote that names no owner.
+ */
+export declare function releaseAgent(options: ReleaseAgentOptions): Promise<void>;
+export {};

package/dist/agent-gate/gate.js

@@ -0,0 +1,232 @@
+/**
+ * A client for mero-agent-gate, the gate in a private agent TD (mero-tee,
+ * `mero-agent-gate/`): attest an agent, claim it with your key, give it its
+ * secrets sealed to the TD, and release it. It runs where the owner is (a
+ * browser, a CLI), so whoever carries the requests, mdma included, sees only
+ * quotes and ciphertext.
+ *
+ * One agent TD hosts several owners' agents, each named by an agent id. For
+ * an agent the gate's quote binds, in its report data:
+ *
+ * `nonce ‖ SHA-256("mero-agent-gate/attest/v3" ‖ provisioning_pub ‖ len(id) ‖ id ‖ signing_pub ‖ owner_pub)`
+ *
+ * (signing and owner keys 32 zero bytes while unclaimed). {@link attestAgent}
+ * checks that and the quote itself before returning anything; every function
+ * that sends refuses an agent whose quote names another owner.
+ *
+ * ```ts
+ * import { verify as dcapVerify, getCollateral } from '@phala/dcap-qvl';
+ *
+ * const policy = await verifySignedAgentPolicy(policyJson, bundleJson, { profile: 'locked-read-only' });
+ * const verifier = agentQuoteVerifier(policy, { dcapVerify, fetchCollateral: (q) => getCollateral(PCCS, q) });
+ * const owner = await generateOwnerKey(); // keep owner.secret: it is the only key that can change the agent
+ * const agent = await attestAgent({ gateUrl, agentId: 'a-1f2e', verifier });
+ * await provisionAgent({ gateUrl, agent, ownerSecret: owner.secret, verifier, secrets: { NEAR_AI_API_KEY: key } });
+ * ```
+ */
+import { concat, hex } from '../crypto/internal.js';
+import { x25519KeyPair } from '../sealed/noise.js';
+import { hpkeSealAuth } from './hpke.js';
+export const AGENT_ATTEST_DOMAIN = 'mero-agent-gate/attest/v3';
+export const AGENT_PROVISION_INFO_DOMAIN = 'mero-agent-gate/provision/v2';
+const AGENT_ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const SECRET_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+const MAX_SECRETS = 64;
+const MAX_SECRET_LEN = 64 * 1024;
+/** A gate's refusal, with its `error` code (`not_the_owner`, `no_free_slot`, …) when it gave one. */
+export class AgentGateError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'AgentGateError';
+    }
+}
+export function validateAgentId(agentId) {
+    if (!AGENT_ID.test(agentId)) {
+        throw new Error(`Agent id ${JSON.stringify(agentId)} must match [a-z0-9][a-z0-9-]{0,62}`);
+    }
+}
+function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+function lengthPrefixed(agentId) {
+    const id = utf8(agentId);
+    return concat(new Uint8Array([id.length]), id);
+}
+function toBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function fromBase64(value, label, length) {
+    let bytes;
+    try {
+        bytes = Uint8Array.from(atob(value.trim()), (c) => c.charCodeAt(0));
+    }
+    catch {
+        throw new Error(`${label} is not base64`);
+    }
+    if (length !== undefined && bytes.length !== length)
+        throw new Error(`${label} is not ${length} bytes`);
+    return bytes;
+}
+/** The 32 bytes after the nonce in a gate's quote for `agentId` (empty: the TD alone). */
+export async function agentKeyBinding(provisioningPublic, agentId, signingPublic, ownerPublic) {
+    const zero = new Uint8Array(32);
+    const data = concat(utf8(AGENT_ATTEST_DOMAIN), provisioningPublic, lengthPrefixed(agentId), signingPublic ?? zero, ownerPublic ?? zero);
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', data));
+}
+/** HPKE `info` for a message to `agentId` on the gate whose provisioning key is `recipientPublic`. */
+export function provisionInfo(recipientPublic, agentId) {
+    return concat(utf8(AGENT_PROVISION_INFO_DOMAIN), recipientPublic, lengthPrefixed(agentId));
+}
+/** A fresh owner key, made here; it never needs to leave the owner. */
+export async function generateOwnerKey() {
+    const secret = crypto.getRandomValues(new Uint8Array(32));
+    return { secret, publicKey: await ownerPublicKey(secret) };
+}
+/** The base64 public half of an owner's X25519 secret. */
+export async function ownerPublicKey(secret) {
+    if (secret.length !== 32)
+        throw new Error('An owner key is 32 bytes');
+    return toBase64((await x25519KeyPair(secret)).publicKey);
+}
+function url(gateUrl, path) {
+    return `${gateUrl.replace(/\/+$/, '')}${path}`;
+}
+async function postJson(fetchImpl, target, body) {
+    const response = await fetchImpl(target, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    let parsed = undefined;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        // Not JSON: reported below with the status.
+    }
+    if (!response.ok) {
+        const error = parsed;
+        throw new AgentGateError(`The gate answered ${response.status}${error?.error ? ` ${error.error}` : ''}: ${error?.details ?? text.slice(0, 200)}`, response.status, error?.error);
+    }
+    return parsed;
+}
+/**
+ * Ask the gate for a quote for `agentId` over a fresh nonce and verify it:
+ * a genuine quote from a measured agent image, for this nonce, committing to
+ * the agent id asked about and to the keys the gate names. Returns those
+ * keys only once every check has passed.
+ */
+export async function attestAgent(options) {
+    const agentId = options.agentId ?? '';
+    if (agentId)
+        validateAgentId(agentId);
+    const nonce = crypto.getRandomValues(new Uint8Array(32));
+    const body = (await postJson(options.fetch ?? fetch, url(options.gateUrl, '/attest'), {
+        nonceB64: toBase64(nonce),
+        ...(agentId ? { agentId } : {}),
+    }));
+    if ((body?.agentId ?? '') !== agentId) {
+        throw new Error(`Asked about agent ${JSON.stringify(agentId)}, the gate answered for ${JSON.stringify(body?.agentId)}`);
+    }
+    const provisioning = fromBase64(body.provisioningPublicKeyB64 ?? '', 'provisioningPublicKeyB64', 32);
+    const signing = body.signingPublicKeyB64 ? fromBase64(body.signingPublicKeyB64, 'signingPublicKeyB64', 32) : undefined;
+    const owner = body.ownerPublicKeyB64 ? fromBase64(body.ownerPublicKeyB64, 'ownerPublicKeyB64', 32) : undefined;
+    if (!signing !== !owner) {
+        throw new Error('A claimed agent has both a signing key and an owner; the gate named one');
+    }
+    // The id asked about, not the one answered: a quote for another agent fails here.
+    const binding = await agentKeyBinding(provisioning, agentId, signing, owner);
+    await options.verifier({ quoteB64: body.quoteB64, nonce: hex(nonce), reportDataSuffix: hex(binding) });
+    return {
+        agentId,
+        provisioningPublicKey: toBase64(provisioning),
+        ...(signing ? { signingPublicKey: toBase64(signing) } : {}),
+        ...(owner ? { ownerPublicKey: toBase64(owner) } : {}),
+    };
+}
+/** The owner key `ownerSecret` may act on `agent`: it is unclaimed, or claimed by that key. */
+export async function checkOwner(agent, ownerSecret) {
+    const mine = await ownerPublicKey(ownerSecret);
+    if (agent.ownerPublicKey && agent.ownerPublicKey !== mine) {
+        throw new AgentGateError(`This agent is claimed by another key (${agent.ownerPublicKey}); it is not yours. Send it nothing and do not authorize its signing key`, undefined, 'not_yours');
+    }
+    return mine;
+}
+function validateSecrets(secrets) {
+    const names = Object.keys(secrets);
+    if (names.length === 0)
+        throw new Error('There are no secrets to provision');
+    if (names.length > MAX_SECRETS)
+        throw new Error(`At most ${MAX_SECRETS} secrets at once`);
+    for (const name of names) {
+        if (!SECRET_NAME.test(name))
+            throw new Error(`Secret name ${JSON.stringify(name)} must match [A-Za-z0-9][A-Za-z0-9_.-]{0,63}`);
+        if (typeof secrets[name] !== 'string')
+            throw new Error(`Secret ${name} is not a string`);
+        if (utf8(secrets[name]).length > MAX_SECRET_LEN)
+            throw new Error(`Secret ${name} is over ${MAX_SECRET_LEN} bytes`);
+    }
+}
+async function sendSealed(fetchImpl, gateUrl, path, agent, ownerSecret, message) {
+    if (!agent.agentId)
+        throw new Error('This quote names no agent; attest with the agent id');
+    const mine = await checkOwner(agent, ownerSecret);
+    const recipient = fromBase64(agent.provisioningPublicKey, 'provisioningPublicKey', 32);
+    const sealed = await hpkeSealAuth(recipient, ownerSecret, provisionInfo(recipient, agent.agentId), utf8(JSON.stringify(message)));
+    return postJson(fetchImpl, url(gateUrl, path), {
+        agentId: agent.agentId,
+        provisioningPublicKeyB64: agent.provisioningPublicKey,
+        senderPublicKeyB64: mine,
+        encappedKeyB64: toBase64(sealed.enc),
+        ciphertextB64: toBase64(sealed.ciphertext),
+    });
+}
+/**
+ * Seal `secrets` to the agent as its owner and send them. The first bundle for
+ * an unclaimed agent claims it for `ownerSecret`'s key. The gate's answer is
+ * not taken as proof: a fresh quote must name your key as owner, and the
+ * agent's signing key must not have changed.
+ */
+export async function provisionAgent(options) {
+    validateSecrets(options.secrets);
+    const fetchImpl = options.fetch ?? fetch;
+    const answer = (await sendSealed(fetchImpl, options.gateUrl, '/provision', options.agent, options.ownerSecret, {
+        secrets: options.secrets,
+    }));
+    const after = await attestAgent({ gateUrl: options.gateUrl, agentId: options.agent.agentId, verifier: options.verifier, fetch: fetchImpl });
+    const mine = await ownerPublicKey(options.ownerSecret);
+    if (after.ownerPublicKey !== mine || !after.signingPublicKey) {
+        throw new AgentGateError('The gate accepted the secrets, but its quote does not name your key as owner');
+    }
+    if (options.agent.signingPublicKey && options.agent.signingPublicKey !== after.signingPublicKey) {
+        throw new AgentGateError("The agent's signing key changed while provisioning");
+    }
+    return {
+        agentId: after.agentId,
+        provisioningPublicKey: after.provisioningPublicKey,
+        signingPublicKey: after.signingPublicKey,
+        ownerPublicKey: mine,
+        written: answer?.written ?? [],
+        claimed: answer?.claimed === true,
+    };
+}
+/**
+ * Release the agent as its owner: the gate stops it and erases its claim,
+ * keys, secrets and state. Checked by a fresh quote that names no owner.
+ */
+export async function releaseAgent(options) {
+    if (!options.agent.ownerPublicKey)
+        throw new Error('This agent is not claimed; there is nothing to release');
+    const fetchImpl = options.fetch ?? fetch;
+    await sendSealed(fetchImpl, options.gateUrl, '/release', options.agent, options.ownerSecret, { release: true });
+    const after = await attestAgent({ gateUrl: options.gateUrl, agentId: options.agent.agentId, verifier: options.verifier, fetch: fetchImpl });
+    if (after.ownerPublicKey) {
+        throw new AgentGateError('The gate says it released the agent, but its quote still names an owner');
+    }
+}

package/dist/agent-gate/hpke.d.ts

@@ -0,0 +1,23 @@
+/**
+ * RFC 9180 HPKE, the one suite and mode mero-agent-gate takes: Auth mode,
+ * DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305, single-shot
+ * (one message per context, sequence number 0). Auth mode proves the sender:
+ * the gate opens a bundle only under the X25519 key it names, so nobody can
+ * seal in an owner's name.
+ *
+ * X25519 and HMAC are WebCrypto; ChaCha20-Poly1305 is ./chacha20poly1305.
+ * The tests open what mero-agent-gate (Rust, the `hpke` crate) sealed, and the
+ * gate opens what this seals.
+ */
+export interface HpkeSealed {
+    /** The encapsulated key: the sender's ephemeral X25519 public key. */
+    enc: Uint8Array;
+    ciphertext: Uint8Array;
+}
+/**
+ * Seal `plaintext` to `recipientPublic` in Auth mode as the holder of
+ * `senderSecret` (32 raw X25519 bytes). `ephemeralSecret` is for tests.
+ */
+export declare function hpkeSealAuth(recipientPublic: Uint8Array, senderSecret: Uint8Array, info: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array, ephemeralSecret?: Uint8Array): Promise<HpkeSealed>;
+/** Open what {@link hpkeSealAuth} (or the gate's own sealer) made, as the recipient. */
+export declare function hpkeOpenAuth(recipientSecret: Uint8Array, senderPublic: Uint8Array, info: Uint8Array, sealed: HpkeSealed, aad?: Uint8Array): Promise<Uint8Array>;

package/dist/agent-gate/hpke.js

@@ -0,0 +1,84 @@
+/**
+ * RFC 9180 HPKE, the one suite and mode mero-agent-gate takes: Auth mode,
+ * DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305, single-shot
+ * (one message per context, sequence number 0). Auth mode proves the sender:
+ * the gate opens a bundle only under the X25519 key it names, so nobody can
+ * seal in an owner's name.
+ *
+ * X25519 and HMAC are WebCrypto; ChaCha20-Poly1305 is ./chacha20poly1305.
+ * The tests open what mero-agent-gate (Rust, the `hpke` crate) sealed, and the
+ * gate opens what this seals.
+ */
+import { concat } from '../crypto/internal.js';
+import { dh, x25519KeyPair } from '../sealed/noise.js';
+import { chacha20Poly1305Open, chacha20Poly1305Seal } from './chacha20poly1305.js';
+const KEM_ID = 0x0020; // DHKEM(X25519, HKDF-SHA256)
+const KDF_ID = 0x0001; // HKDF-SHA256
+const AEAD_ID = 0x0003; // ChaCha20-Poly1305
+const MODE_AUTH = 0x02;
+const N_SECRET = 32;
+const N_KEY = 32;
+const N_NONCE = 12;
+const utf8 = (s) => new TextEncoder().encode(s);
+const i2osp2 = (n) => new Uint8Array([(n >> 8) & 0xff, n & 0xff]);
+const KEM_SUITE = concat(utf8('KEM'), i2osp2(KEM_ID));
+const HPKE_SUITE = concat(utf8('HPKE'), i2osp2(KEM_ID), i2osp2(KDF_ID), i2osp2(AEAD_ID));
+async function hmac(key, data) {
+    // An empty salt is HashLen zeros (RFC 5869); WebCrypto refuses a zero-length HMAC key.
+    const raw = key.length === 0 ? new Uint8Array(32) : key;
+    const k = await crypto.subtle.importKey('raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return new Uint8Array(await crypto.subtle.sign('HMAC', k, data));
+}
+async function expand(prk, info, length) {
+    const out = new Uint8Array(length);
+    let previous = new Uint8Array(0);
+    for (let i = 1, offset = 0; offset < length; i += 1) {
+        previous = await hmac(prk, concat(previous, info, new Uint8Array([i])));
+        out.set(previous.subarray(0, Math.min(previous.length, length - offset)), offset);
+        offset += previous.length;
+    }
+    return out;
+}
+function labeledExtract(suite, salt, label, ikm) {
+    return hmac(salt, concat(utf8('HPKE-v1'), suite, utf8(label), ikm));
+}
+function labeledExpand(suite, prk, label, info, length) {
+    return expand(prk, concat(i2osp2(length), utf8('HPKE-v1'), suite, utf8(label), info), length);
+}
+async function extractAndExpand(dhValue, kemContext) {
+    const prk = await labeledExtract(KEM_SUITE, new Uint8Array(0), 'eae_prk', dhValue);
+    return labeledExpand(KEM_SUITE, prk, 'shared_secret', kemContext, N_SECRET);
+}
+async function keySchedule(sharedSecret, info) {
+    const empty = new Uint8Array(0);
+    const pskIdHash = await labeledExtract(HPKE_SUITE, empty, 'psk_id_hash', empty);
+    const infoHash = await labeledExtract(HPKE_SUITE, empty, 'info_hash', info);
+    const context = concat(new Uint8Array([MODE_AUTH]), pskIdHash, infoHash);
+    const secret = await labeledExtract(HPKE_SUITE, sharedSecret, 'secret', empty);
+    return {
+        key: await labeledExpand(HPKE_SUITE, secret, 'key', context, N_KEY),
+        nonce: await labeledExpand(HPKE_SUITE, secret, 'base_nonce', context, N_NONCE),
+    };
+}
+/**
+ * Seal `plaintext` to `recipientPublic` in Auth mode as the holder of
+ * `senderSecret` (32 raw X25519 bytes). `ephemeralSecret` is for tests.
+ */
+export async function hpkeSealAuth(recipientPublic, senderSecret, info, plaintext, aad = new Uint8Array(0), ephemeralSecret) {
+    if (recipientPublic.length !== 32)
+        throw new Error('The recipient key is not 32 bytes of X25519');
+    const ephemeral = await x25519KeyPair(ephemeralSecret);
+    const sender = await x25519KeyPair(senderSecret);
+    const dhValue = concat(await dh(ephemeral.privateKey, recipientPublic), await dh(sender.privateKey, recipientPublic));
+    const shared = await extractAndExpand(dhValue, concat(ephemeral.publicKey, recipientPublic, sender.publicKey));
+    const { key, nonce } = await keySchedule(shared, info);
+    return { enc: ephemeral.publicKey, ciphertext: chacha20Poly1305Seal(key, nonce, plaintext, aad) };
+}
+/** Open what {@link hpkeSealAuth} (or the gate's own sealer) made, as the recipient. */
+export async function hpkeOpenAuth(recipientSecret, senderPublic, info, sealed, aad = new Uint8Array(0)) {
+    const recipient = await x25519KeyPair(recipientSecret);
+    const dhValue = concat(await dh(recipient.privateKey, sealed.enc), await dh(recipient.privateKey, senderPublic));
+    const shared = await extractAndExpand(dhValue, concat(sealed.enc, recipient.publicKey, senderPublic));
+    const { key, nonce } = await keySchedule(shared, info);
+    return chacha20Poly1305Open(key, nonce, sealed.ciphertext, aad);
+}

package/dist/agent-gate/index.d.ts

@@ -0,0 +1,4 @@
+export { AGENT_ATTEST_DOMAIN, AGENT_PROVISION_INFO_DOMAIN, AgentGateError, agentKeyBinding, attestAgent, checkOwner, generateOwnerKey, ownerPublicKey, provisionAgent, provisionInfo, releaseAgent, validateAgentId, } from './gate.js';
+export type { AttestAgentOptions, OwnerKey, ProvisionAgentOptions, ProvisionedAgent, ReleaseAgentOptions, VerifiedAgent, } from './gate.js';
+export { KMS_RELEASE_SIGNER, agentQuoteVerifier, verifySignedAgentPolicy } from './policy.js';
+export type { AgentPolicy, AgentQuoteVerifierOptions, VerifySignedAgentPolicyOptions } from './policy.js';

package/dist/agent-gate/index.js

@@ -0,0 +1,2 @@
+export { AGENT_ATTEST_DOMAIN, AGENT_PROVISION_INFO_DOMAIN, AgentGateError, agentKeyBinding, attestAgent, checkOwner, generateOwnerKey, ownerPublicKey, provisionAgent, provisionInfo, releaseAgent, validateAgentId, } from './gate.js';
+export { KMS_RELEASE_SIGNER, agentQuoteVerifier, verifySignedAgentPolicy } from './policy.js';