@agentmesh-p2p/sdk 0.0.0-stage → 0.1.0

package/dist/controlplane.js

@@ -0,0 +1,368 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// Client for the control plane's mesh-protocol surface: protobuf over HTTP
+// (api/agentmesh.proto). The operator plane (/admin/*, JSON) is out of scope.
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { timestampMs } from "@bufbuild/protobuf/wkt";
+import { enrollChallenge, enrollStatusChallenge, policiesChallenge, refreshChallenge, registerChallenge } from "./challenges.js";
+import { BootstrapEnrollRequestSchema, BootstrapEnrollResponseSchema, ControlPlaneInfoResponseSchema, EnrollRequestSchema, EnrollResponseSchema, EnrollmentStatus, KeysResponseSchema, PolicyConfigGetResponseSchema, TokenRefreshRequestSchema, TokenRefreshResponseSchema, } from "./gen/agentmesh_pb.js";
+import { bytesEqual, toBase64, toBase64Url } from "./bytes.js";
+import { verifyEd25519 } from "./identity.js";
+export const PROTOBUF_CONTENT_TYPE = "application/x-protobuf";
+export const HEADER_CHALLENGE_TIMESTAMP = "X-Mesh-Challenge-Ts";
+export const HEADER_CHALLENGE_SIGNATURE = "X-Mesh-Challenge-Sig";
+export const STALE_CHALLENGE_TIMESTAMP_MESSAGE = "stale or invalid challenge timestamp";
+/** The role a plain mesh member enrolls with (api.RoleNode). */
+export const ROLE_NODE = "mesh:role:node";
+/** How far a signed /keys response's timestamp may drift from our clock. */
+export const KEYS_RESPONSE_FRESHNESS_MS = 5 * 60 * 1000;
+const ED25519_PUBLIC_KEY_SIZE = 32;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+/** A non-2xx answer from the control plane. */
+export class ControlPlaneError extends Error {
+    status;
+    body;
+    constructor(path, status, body) {
+        super(`control plane ${path}: HTTP ${status}${body ? `: ${body.trim()}` : ""}`);
+        this.name = "ControlPlaneError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** The control plane answered, and the answer is a refusal. */
+export class EnrollmentRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnrollmentRejectedError";
+    }
+}
+/**
+ * The /keys answer is signed by no key this member trusts: every key it
+ * holds has left the control plane's set, so its credential cannot be
+ * verified or refreshed either.
+ */
+export class KeysNotTrustedError extends Error {
+    constructor() {
+        super("keys response is not signed by any trusted control plane key");
+        this.name = "KeysNotTrustedError";
+    }
+}
+/** Plaintext http:// to a host that is not loopback; see api.ValidateControlPlaneTransport. */
+export class InsecureControlPlaneURLError extends Error {
+    constructor(url) {
+        super(`plaintext http:// control plane URL to a non-loopback host: ${url} (use https://, or set allowInsecure for a network you trust)`);
+        this.name = "InsecureControlPlaneURLError";
+    }
+}
+function isLoopbackHost(host) {
+    const h = host.replace(/^\[|\]$/g, "");
+    return h.toLowerCase() === "localhost" || h === "127.0.0.1" || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h);
+}
+/** Mirrors api.ValidateControlPlaneTransport: https, or http to loopback only. */
+export function validateControlPlaneURL(rawUrl, allowInsecure = false) {
+    let u;
+    try {
+        u = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`invalid control plane URL ${JSON.stringify(rawUrl)}`);
+    }
+    if (u.protocol === "https:") {
+        return u;
+    }
+    if (u.protocol === "http:") {
+        if (allowInsecure || isLoopbackHost(u.hostname)) {
+            return u;
+        }
+        throw new InsecureControlPlaneURLError(rawUrl);
+    }
+    throw new Error(`control plane URL ${JSON.stringify(rawUrl)} must use http:// or https://`);
+}
+/**
+ * Returns the key set if it is fresh and at least one listed key is already
+ * trusted and its signature verifies. Mirrors api.VerifyKeysResponse.
+ */
+export function verifyKeysResponse(resp, trusted, nowMs = Date.now()) {
+    if (trusted.length === 0) {
+        throw new Error("no trusted control plane key to verify /keys against");
+    }
+    if (resp.signatures.length !== resp.publicKeys.length) {
+        throw new Error(`keys response carries ${resp.signatures.length} signatures for ${resp.publicKeys.length} keys`);
+    }
+    if (resp.signTime === undefined) {
+        throw new Error("keys response carries no sign_time");
+    }
+    const issued = timestampMs(resp.signTime);
+    if (Math.abs(nowMs - issued) > KEYS_RESPONSE_FRESHNESS_MS) {
+        throw new Error(`keys response sign_time ${new Date(issued).toISOString()} is outside the freshness window`);
+    }
+    // Each signature covers the set and the signing time, deterministically
+    // encoded with the signatures cleared.
+    const payload = toBinary(KeysResponseSchema, create(KeysResponseSchema, { publicKeys: resp.publicKeys, signTime: resp.signTime }));
+    const keys = [];
+    let verified = false;
+    resp.publicKeys.forEach((pub, i) => {
+        if (pub.length !== ED25519_PUBLIC_KEY_SIZE) {
+            throw new Error(`keys response key ${i} has invalid size ${pub.length} (expected ${ED25519_PUBLIC_KEY_SIZE})`);
+        }
+        keys.push(pub);
+        if (verified) {
+            return;
+        }
+        const sig = resp.signatures[i];
+        if (sig && trusted.some((t) => bytesEqual(t, pub)) && verifyEd25519(pub, payload, sig)) {
+            verified = true;
+        }
+    });
+    if (!verified) {
+        throw new KeysNotTrustedError();
+    }
+    return keys;
+}
+function abortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("aborted");
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export class ControlPlaneClient {
+    url;
+    #fetch;
+    #timeoutMs;
+    #now;
+    constructor(options) {
+        this.url = validateControlPlaneURL(options.url, options.allowInsecure ?? false);
+        // Unbound: a browser's fetch refuses to run as a method of anything else.
+        const f = options.fetch ?? globalThis.fetch;
+        this.#fetch = (input, init) => f(input, init);
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#now = options.now ?? (() => Date.now());
+    }
+    /** GET /info: OIDC settings, router addresses and the ban list. Unauthenticated. */
+    async info() {
+        const body = await this.#request("GET", "/info");
+        return fromBinary(ControlPlaneInfoResponseSchema, body);
+    }
+    /**
+     * GET /keys: every signing key the control plane currently trusts,
+     * verified against a key the caller already trusts (the enrollment key).
+     */
+    async keys(trusted) {
+        const body = await this.#request("GET", "/keys");
+        return verifyKeysResponse(fromBinary(KeysResponseSchema, body), trusted, this.#now());
+    }
+    /**
+     * POST /enroll with a bootstrap token, then GET /enroll/status until an
+     * operator approves the request if the mesh is not on auto-approve.
+     */
+    async enrollBootstrap(params) {
+        const { identity, signal } = params;
+        const role = params.role ?? ROLE_NODE;
+        const raw = await this.#requestWithChallenge("POST", "/enroll", (ts) => {
+            const req = create(BootstrapEnrollRequestSchema, {
+                bootstrapToken: params.bootstrapToken,
+                peerId: identity.peerId,
+                publicKey: identity.libp2pPublicKey,
+                requestedRole: role,
+                labels: params.labels ?? {},
+                challengeUnixMs: BigInt(ts),
+                challengeSignature: identity.sign(enrollChallenge(identity.peerId, ts)),
+            });
+            return { body: toBinary(BootstrapEnrollRequestSchema, req) };
+        });
+        let resp = fromBinary(BootstrapEnrollResponseSchema, raw);
+        while (resp.status === EnrollmentStatus.PENDING) {
+            const waitMs = params.pollIntervalMs ?? Math.max(1, resp.pollIntervalSeconds) * 1000;
+            await sleep(waitMs, signal);
+            resp = await this.#enrollStatus(identity);
+        }
+        return enrollmentFromBootstrapResponse(resp);
+    }
+    async #enrollStatus(identity) {
+        const body = await this.#requestWithChallenge("GET", `/enroll/status?peer_id=${encodeURIComponent(identity.peerId)}`, (ts) => {
+            const sig = identity.sign(enrollStatusChallenge(identity.peerId, ts));
+            return {
+                headers: {
+                    [HEADER_CHALLENGE_TIMESTAMP]: String(ts),
+                    [HEADER_CHALLENGE_SIGNATURE]: toBase64Url(sig),
+                },
+            };
+        });
+        return fromBinary(BootstrapEnrollResponseSchema, body);
+    }
+    /** POST /register with an OIDC ID token. */
+    async register(params) {
+        const { identity } = params;
+        const raw = await this.#requestWithChallenge("POST", "/register", (ts) => {
+            const req = create(EnrollRequestSchema, {
+                jwt: params.jwt,
+                peerId: identity.peerId,
+                publicKey: identity.libp2pPublicKey,
+                requestedRole: params.role ?? ROLE_NODE,
+                labels: params.labels ?? {},
+                challengeUnixMs: BigInt(ts),
+                challengeSignature: identity.sign(registerChallenge(identity.peerId, ts)),
+            });
+            return { body: toBinary(EnrollRequestSchema, req) };
+        });
+        const resp = fromBinary(EnrollResponseSchema, raw);
+        if (resp.errorMessage) {
+            throw new EnrollmentRejectedError(`enrollment failed: ${resp.errorMessage}`);
+        }
+        return checkedEnrollment({
+            biscuit: resp.biscuitToken,
+            controlPlanePublicKey: resp.controlPlanePublicKey,
+            routerAddresses: resp.routerAddresses,
+        }, resp.expireTime);
+    }
+    /**
+     * POST /refresh: trades the biscuit for a fresh one. The old one is
+     * spent by this call; callers must persist the result before using it.
+     */
+    async refresh(params) {
+        const { identity } = params;
+        const authHeader = `Bearer ${toBase64(params.biscuit)}`;
+        const body = await this.#requestWithChallenge("POST", "/refresh", (ts) => {
+            const req = create(TokenRefreshRequestSchema, {
+                challengeUnixMs: BigInt(ts),
+                challengeSignature: identity.sign(refreshChallenge(identity.peerId, ts)),
+                peerId: identity.peerId,
+                ...(params.jwt ? { jwt: params.jwt } : {}),
+            });
+            return {
+                body: toBinary(TokenRefreshRequestSchema, req),
+                headers: { Authorization: authHeader },
+            };
+        });
+        const resp = fromBinary(TokenRefreshResponseSchema, body);
+        if (resp.errorMessage) {
+            throw new EnrollmentRejectedError(`refresh failed: ${resp.errorMessage}`);
+        }
+        if (resp.biscuitToken.length === 0) {
+            throw new Error("refresh returned an empty biscuit");
+        }
+        return { biscuit: resp.biscuitToken, expiration: expirationSeconds(resp.expireTime, "refresh") };
+    }
+    async policyRules(identityOrParams, maybeBiscuit) {
+        const identity = "identity" in identityOrParams ? identityOrParams.identity : identityOrParams;
+        const biscuit = "identity" in identityOrParams ? identityOrParams.biscuit : maybeBiscuit;
+        const authHeader = `Bearer ${toBase64(biscuit)}`;
+        const body = await this.#requestWithChallenge("GET", "/policies", (ts) => {
+            const sig = identity.sign(policiesChallenge(identity.peerId, ts));
+            return {
+                headers: {
+                    Authorization: authHeader,
+                    [HEADER_CHALLENGE_TIMESTAMP]: String(ts),
+                    [HEADER_CHALLENGE_SIGNATURE]: toBase64Url(sig),
+                },
+            };
+        });
+        const resp = fromBinary(PolicyConfigGetResponseSchema, body);
+        if (resp.$unknown !== undefined && resp.$unknown.length > 0) {
+            throw new Error("control plane predates datalog_rules in its policy response; upgrade the control plane");
+        }
+        return resp.datalogRules;
+    }
+    async #requestWithChallenge(method, path, build) {
+        const first = build(this.#now());
+        const outcome = await this.#fetchOnce(method, path, first.body, first.headers);
+        if (outcome.ok) {
+            return outcome.buf;
+        }
+        const text = new TextDecoder().decode(outcome.buf);
+        if (outcome.status === 401 && text.includes(STALE_CHALLENGE_TIMESTAMP_MESSAGE) && outcome.dateHeader) {
+            const serverMs = Date.parse(outcome.dateHeader);
+            if (Number.isFinite(serverMs) && serverMs > 0) {
+                const retry = build(serverMs);
+                return this.#request(method, path, retry.body, retry.headers);
+            }
+        }
+        throw new ControlPlaneError(path, outcome.status, text);
+    }
+    async #fetchOnce(method, path, body, headers = {}) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error(`control plane ${path}: timed out after ${this.#timeoutMs}ms`)), this.#timeoutMs);
+        try {
+            const init = {
+                method,
+                headers: { Accept: PROTOBUF_CONTENT_TYPE, ...headers },
+                signal: controller.signal,
+            };
+            if (body !== undefined) {
+                init.body = new Uint8Array(body);
+                init.headers = { ...init.headers, "Content-Type": PROTOBUF_CONTENT_TYPE };
+            }
+            const resp = await this.#fetch(new URL(path, this.url), init);
+            const buf = new Uint8Array(await resp.arrayBuffer());
+            if (buf.length > MAX_RESPONSE_BYTES) {
+                throw new Error(`control plane ${path}: response of ${buf.length} bytes exceeds the ${MAX_RESPONSE_BYTES} byte limit`);
+            }
+            return { ok: resp.ok, status: resp.status, buf, dateHeader: resp.headers.get("date") };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async #request(method, path, body, headers = {}) {
+        const outcome = await this.#fetchOnce(method, path, body, headers);
+        if (!outcome.ok) {
+            throw new ControlPlaneError(path, outcome.status, new TextDecoder().decode(outcome.buf));
+        }
+        return outcome.buf;
+    }
+}
+function enrollmentFromBootstrapResponse(resp) {
+    switch (resp.status) {
+        case EnrollmentStatus.APPROVED:
+            return checkedEnrollment({
+                biscuit: resp.biscuitToken,
+                controlPlanePublicKey: resp.controlPlanePublicKey,
+                routerAddresses: resp.routerAddresses,
+            }, resp.expireTime);
+        case EnrollmentStatus.REJECTED:
+            throw new EnrollmentRejectedError(`enrollment rejected: ${resp.errorMessage || "no reason given"}`);
+        default:
+            throw new Error(`unexpected enrollment status ${resp.status}: ${resp.errorMessage}`);
+    }
+}
+function checkedEnrollment(e, expireTime) {
+    if (e.biscuit.length === 0) {
+        throw new Error("received empty biscuit token");
+    }
+    if (e.controlPlanePublicKey.length !== ED25519_PUBLIC_KEY_SIZE) {
+        throw new Error(`received invalid control plane public key size: ${e.controlPlanePublicKey.length} bytes (expected ${ED25519_PUBLIC_KEY_SIZE})`);
+    }
+    return { ...e, expiration: expirationSeconds(expireTime, "enrollment") };
+}
+/** A biscuit of unknown lifetime cannot be kept fresh; the control plane must say when it expires. */
+function expirationSeconds(expireTime, what) {
+    if (expireTime === undefined) {
+        throw new Error(`${what} response carries no expire_time`);
+    }
+    return Math.floor(timestampMs(expireTime) / 1000);
+}

package/dist/credential.d.ts

@@ -0,0 +1,66 @@
+import { type MessageInitShape } from "@bufbuild/protobuf";
+import { type Timestamp } from "@bufbuild/protobuf/wkt";
+import { TaskAuthorizationRuleSchema, type AuthFrame, type AuthResponse, type OIDCSession } from "./gen/agentmesh_pb.ts";
+/** What a member holds after enrolling: its biscuit and what it trusts. */
+export interface MeshCredential {
+    controlPlaneUrl: string;
+    /** The biscuit the control plane minted for this identity. */
+    biscuit: Uint8Array;
+    /** Unix seconds at which the biscuit expires. */
+    expiration: number;
+    /** Every control plane signing key currently trusted (rotation keeps several valid). */
+    controlPlaneKeys: Uint8Array[];
+    /**
+     * The trusted set when the biscuit was issued. A key trusted now that was
+     * not in this set means a rotation happened since: the biscuit is signed
+     * by a retiring key and must be refreshed before that key leaves its
+     * grace period (agentmesh-node's identityPredatesRotation).
+     */
+    issuedUnderKeys: Uint8Array[];
+    /** Router multiaddrs, `/p2p/<peer id>` suffixed, as handed out at enrollment. */
+    routerAddresses: string[];
+    /**
+     * What other implementations persist in the same file and this SDK does
+     * not use: key receipt times and agentmesh-node's OIDC session. Carried through
+     * so a state directory survives a round trip untouched.
+     */
+    extra?: {
+        receiveTime: Map<string, Timestamp>;
+        oidcSession?: OIDCSession;
+    };
+    /** Returns a new credential whose biscuit is attenuated in memory with rule. */
+    attenuate?: (rule: MessageInitShape<typeof TaskAuthorizationRuleSchema>) => Promise<MeshCredential>;
+    /** Returns a new credential whose biscuit is sealed against further attenuation. */
+    seal?: () => Promise<MeshCredential>;
+}
+/** Attaches .attenuate() and .seal() convenience methods to a MeshCredential object. */
+export declare function withCredentialMethods(c: MeshCredential): MeshCredential;
+/**
+ * Returns a new MeshCredential with a tar_block appended offline in memory.
+ * If the rule sets expire_time earlier than the credential's expiration,
+ * the returned credential's expiration is narrowed to match.
+ */
+export declare function attenuateCredential(c: MeshCredential, ruleInput: MessageInitShape<typeof TaskAuthorizationRuleSchema>): Promise<MeshCredential>;
+/** Returns a new MeshCredential whose biscuit is sealed so no further blocks can be appended. */
+export declare function sealCredential(c: MeshCredential): Promise<MeshCredential>;
+/** Whether a key trusted now was unknown when the credential was issued. */
+export declare function credentialPredatesRotation(c: MeshCredential): boolean;
+/** Seconds of validity left on the biscuit; negative once expired. */
+export declare function credentialTimeToLiveSeconds(c: MeshCredential, nowMs?: number): number;
+/**
+ * The first frame on every mesh stream (/mesh/auth/1.0.0, /mesh/mcp/1.0.0):
+ * the caller's biscuit and the service it wants.
+ * Framing (varint length prefix) is the transport's job.
+ */
+export declare function encodeAuthFrame(biscuit: Uint8Array, targetService?: string): Uint8Array;
+/** The peer's answer to an AuthResponse, carrying its own biscuit on success. */
+/** Reads back an AuthFrame this member built (encodeAuthFrame). */
+export declare function decodeAuthFrame(bytes: Uint8Array): AuthFrame;
+export declare function decodeAuthResponse(bytes: Uint8Array): AuthResponse;
+/**
+ * credential.json is the api.MemberCredential message as protojson with
+ * proto field names, the layout `agentmesh-node state export` writes and every
+ * SDK reads. An unknown field is an error, as on every Agent Mesh surface.
+ */
+export declare function credentialToJSON(c: MeshCredential): string;
+export declare function credentialFromJSON(text: string): MeshCredential;

package/dist/credential.js

@@ -0,0 +1,124 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { create, fromBinary, fromJson, toBinary, toJson } from "@bufbuild/protobuf";
+import { timestampDate, timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { attenuateBiscuit, sealBiscuit } from "./biscuit.js";
+import { toHex } from "./bytes.js";
+import { AuthFrameSchema, AuthResponseSchema, MemberCredentialSchema, TaskAuthorizationRuleSchema, } from "./gen/agentmesh_pb.js";
+/** Attaches .attenuate() and .seal() convenience methods to a MeshCredential object. */
+export function withCredentialMethods(c) {
+    const out = {
+        ...c,
+        attenuate: (rule) => attenuateCredential(out, rule),
+        seal: () => sealCredential(out),
+    };
+    return out;
+}
+/**
+ * Returns a new MeshCredential with a tar_block appended offline in memory.
+ * If the rule sets expire_time earlier than the credential's expiration,
+ * the returned credential's expiration is narrowed to match.
+ */
+export async function attenuateCredential(c, ruleInput) {
+    const rule = create(TaskAuthorizationRuleSchema, ruleInput);
+    const biscuit = await attenuateBiscuit(c.biscuit, rule, c.controlPlaneKeys);
+    let expiration = c.expiration;
+    if (rule.expireTime !== undefined) {
+        const ruleExp = Math.floor(timestampDate(rule.expireTime).getTime() / 1000);
+        if (ruleExp < expiration) {
+            expiration = ruleExp;
+        }
+    }
+    return withCredentialMethods({
+        ...c,
+        biscuit,
+        expiration,
+    });
+}
+/** Returns a new MeshCredential whose biscuit is sealed so no further blocks can be appended. */
+export async function sealCredential(c) {
+    const biscuit = await sealBiscuit(c.biscuit, c.controlPlaneKeys);
+    return withCredentialMethods({
+        ...c,
+        biscuit,
+    });
+}
+/** Whether a key trusted now was unknown when the credential was issued. */
+export function credentialPredatesRotation(c) {
+    const issued = new Set(c.issuedUnderKeys.map((k) => toHex(k)));
+    return c.controlPlaneKeys.some((k) => !issued.has(toHex(k)));
+}
+/** Seconds of validity left on the biscuit; negative once expired. */
+export function credentialTimeToLiveSeconds(c, nowMs = Date.now()) {
+    return c.expiration - Math.floor(nowMs / 1000);
+}
+/**
+ * The first frame on every mesh stream (/mesh/auth/1.0.0, /mesh/mcp/1.0.0):
+ * the caller's biscuit and the service it wants.
+ * Framing (varint length prefix) is the transport's job.
+ */
+export function encodeAuthFrame(biscuit, targetService = "") {
+    return toBinary(AuthFrameSchema, create(AuthFrameSchema, { biscuit, targetService }));
+}
+/** The peer's answer to an AuthResponse, carrying its own biscuit on success. */
+/** Reads back an AuthFrame this member built (encodeAuthFrame). */
+export function decodeAuthFrame(bytes) {
+    return fromBinary(AuthFrameSchema, bytes);
+}
+export function decodeAuthResponse(bytes) {
+    return fromBinary(AuthResponseSchema, bytes);
+}
+/**
+ * credential.json is the api.MemberCredential message as protojson with
+ * proto field names, the layout `agentmesh-node state export` writes and every
+ * SDK reads. An unknown field is an error, as on every Agent Mesh surface.
+ */
+export function credentialToJSON(c) {
+    const message = create(MemberCredentialSchema, {
+        controlPlaneUrl: c.controlPlaneUrl,
+        biscuit: c.biscuit,
+        expireTime: timestampFromDate(new Date(c.expiration * 1000)),
+        trustedKeys: c.controlPlaneKeys.map((k) => {
+            const receiveTime = c.extra?.receiveTime.get(toHex(k));
+            return receiveTime !== undefined ? { publicKey: k, receiveTime } : { publicKey: k };
+        }),
+        issuedUnderKeys: c.issuedUnderKeys,
+        routerAddresses: c.routerAddresses,
+        ...(c.extra?.oidcSession !== undefined ? { oidcSession: c.extra.oidcSession } : {}),
+    });
+    return JSON.stringify(toJson(MemberCredentialSchema, message, { useProtoFieldName: true }), null, 2) + "\n";
+}
+export function credentialFromJSON(text) {
+    const message = fromJson(MemberCredentialSchema, JSON.parse(text));
+    if (message.controlPlaneUrl === "" || message.biscuit.length === 0 || message.expireTime === undefined) {
+        throw new Error("malformed credential file: control_plane_url, biscuit and expire_time are required");
+    }
+    const controlPlaneKeys = message.trustedKeys.map((k) => k.publicKey);
+    const receiveTime = new Map();
+    for (const k of message.trustedKeys) {
+        if (k.receiveTime !== undefined) {
+            receiveTime.set(toHex(k.publicKey), k.receiveTime);
+        }
+    }
+    return withCredentialMethods({
+        controlPlaneUrl: message.controlPlaneUrl,
+        biscuit: message.biscuit,
+        expiration: Math.floor(timestampDate(message.expireTime).getTime() / 1000),
+        controlPlaneKeys,
+        // A file that recorded no issuance set: the keys trusted then are the best answer.
+        issuedUnderKeys: message.issuedUnderKeys.length > 0 ? message.issuedUnderKeys : controlPlaneKeys,
+        routerAddresses: message.routerAddresses,
+        extra: { receiveTime, ...(message.oidcSession !== undefined ? { oidcSession: message.oidcSession } : {}) },
+    });
+}

package/dist/discovery.d.ts

@@ -0,0 +1,50 @@
+import type { Connection } from "@libp2p/interface";
+import { type DirectoryRequest, type DirectoryResponse, type PeerRecord } from "./gen/agentmesh_pb.ts";
+/** api.DirectoryProtocolID. */
+export declare const DIRECTORY_PROTOCOL = "/mesh/directory/1.0.0";
+export declare const DEFAULT_LIMIT = 20;
+export type ServiceType = "mcp" | "inference" | "a2a" | "egress";
+export declare function isServiceType(value: unknown): value is ServiceType;
+/** The directory key of a service type, or of one named service of that type (api.ServiceKey). */
+export declare function serviceKey(type: ServiceType, name?: string): Promise<Uint8Array>;
+/** The directory key a member announces where it is reached under (api.PeerKey). */
+export declare function peerKey(peerId: string): Promise<Uint8Array>;
+/** Splits "mcp://calculator" into its type and name; "" is the node's own catalog. */
+export declare function parseServiceTarget(target: string): {
+    type: ServiceType | "";
+    name: string;
+};
+/** No held router answered a directory request. */
+export declare class DirectoryError extends Error {
+    constructor(message: string);
+}
+/** A router connection a request goes over. */
+export interface DirectoryRouter {
+    peerId: string;
+    connection(): Connection | undefined;
+}
+/**
+ * Sends req to the held routers in turn until one answers. A router that
+ * is restarting costs the request a timeout, not an answer. A lookup one
+ * router answers with nothing is put to the next as well: a router cut
+ * off from the routers closest to the key answers from what it can reach.
+ */
+export declare function request(routers: DirectoryRouter[], req: DirectoryRequest, signal?: AbortSignal): Promise<DirectoryResponse>;
+/**
+ * Announces this member as a provider of key, reached at addrs, to a held
+ * router; the router keeps the record and places it on the routers closest
+ * to the key.
+ */
+export declare function provide(routers: DirectoryRouter[], key: Uint8Array, addrs: string[], signal?: AbortSignal): Promise<void>;
+/**
+ * Removes this member's record under key from the held router and from the
+ * routers it was placed on.
+ */
+export declare function withdraw(routers: DirectoryRouter[], key: Uint8Array, signal?: AbortSignal): Promise<void>;
+/** Who provides key, up to limit, with their addresses; empty when nobody does. */
+export declare function findProviders(routers: DirectoryRouter[], key: Uint8Array, limit?: number, signal?: AbortSignal): Promise<PeerRecord[]>;
+/**
+ * Where a peer is reached: its addresses, each ending in its peer ID,
+ * relayed ones included. Undefined when nobody knows the peer.
+ */
+export declare function findPeer(routers: DirectoryRouter[], peerId: string, signal?: AbortSignal): Promise<PeerRecord | undefined>;