@agentmesh-p2p/sdk 0.0.0-stage → 0.1.0

package/dist/base58.js

@@ -0,0 +1,57 @@
+// 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.
+// base58btc, the alphabet libp2p peer IDs are written in.
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const BASE = BigInt(ALPHABET.length);
+const INDEX = new Map();
+for (let i = 0; i < ALPHABET.length; i++) {
+    INDEX.set(ALPHABET.charAt(i), i);
+}
+export function encodeBase58(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0) {
+        zeros++;
+    }
+    let n = 0n;
+    for (const b of bytes) {
+        n = (n << 8n) | BigInt(b);
+    }
+    let out = "";
+    while (n > 0n) {
+        const digit = Number(n % BASE);
+        out = ALPHABET.charAt(digit) + out;
+        n /= BASE;
+    }
+    return "1".repeat(zeros) + out;
+}
+export function decodeBase58(text) {
+    let zeros = 0;
+    while (zeros < text.length && text.charAt(zeros) === "1") {
+        zeros++;
+    }
+    let n = 0n;
+    for (const ch of text) {
+        const digit = INDEX.get(ch);
+        if (digit === undefined) {
+            throw new Error(`invalid base58 character ${JSON.stringify(ch)}`);
+        }
+        n = n * BASE + BigInt(digit);
+    }
+    const body = [];
+    while (n > 0n) {
+        body.unshift(Number(n & 0xffn));
+        n >>= 8n;
+    }
+    return new Uint8Array([...new Array(zeros).fill(0), ...body]);
+}

package/dist/biscuit.d.ts

@@ -0,0 +1,75 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { TaskAuthorizationRuleSchema, type TaskAuthorizationRule } from "./gen/agentmesh_pb.ts";
+import { type BiscuitWasm } from "./platform/wasm.ts";
+/** The biscuit-wasm module, loaded once, the way the runtime loads it. */
+export declare function loadBiscuit(): Promise<BiscuitWasm>;
+/** Datalog evaluation budget, as in internal/identity.AuthorizerOptions. */
+export declare const AUTHORIZER_LIMITS: {
+    max_facts: number;
+    max_iterations: number;
+    max_time_micro: number;
+};
+/**
+ * Runs an authorize or query call under AUTHORIZER_LIMITS. biscuit-wasm
+ * applies the limits it is passed to the checks and policies only; the
+ * fact-generation pass runs under the builder's own limits, 1 ms of wall
+ * clock, which it does not let a caller change. A paused event loop or a
+ * throttled CPU then answers a valid request with RunLimit Timeout. The
+ * facts derived before that deadline stay in the authorizer and the next
+ * call resumes from them, so the pass is driven to completion here until
+ * the budget above is spent.
+ */
+export declare function withinLimits<T>(run: () => T): T;
+export declare const ROLE_ROUTER = "mesh:role:router";
+export declare class BiscuitVerificationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** What a verified peer biscuit says about its holder. */
+export interface VerifiedBiscuit {
+    /** The peer the token is bound to (its node() or actor_node()/client_peer_id() fact). */
+    peerId: string;
+    /** The origin node channel when the token is a delegated session biscuit (actor_node()). */
+    actorNode?: string;
+    /** When the token lapses; the minimum of authority expiration() and any tar_block expire_time. */
+    expiration: Date;
+    /** The trusted key that verified the signature. */
+    verifyingKey: Uint8Array;
+    roles: string[];
+    labels: Record<string, string>;
+    /** Verified TaskAuthorizationRule chain from blocks 1..N (empty for unattenuated tokens). */
+    taskRules: TaskAuthorizationRule[];
+    /** The token as received, for what is decided over its facts after verification (requirePublish). */
+    token: Uint8Array;
+}
+/**
+ * Verifies a biscuit received from expectedPeerId over an authenticated
+ * connection. Every trusted key is tried, so a token minted under a
+ * retiring key still verifies during rotation.
+ *
+ * By default (peer handshakes on /mesh/auth/1.0.0), the authority block must
+ * carry node(expectedPeerId). When allowDelegated is true (request tokens in
+ * authorizeCaller), the authority block may alternatively carry both
+ * actor_node(expectedPeerId) and client_peer_id(expectedPeerId) without node().
+ */
+export declare function verifyPeerBiscuit(biscuitBytes: Uint8Array, expectedPeerId: string, trustedKeys: Uint8Array[], now?: Date, options?: {
+    allowDelegated?: boolean;
+}): Promise<VerifiedBiscuit>;
+/**
+ * Appends a non-authority block carrying a single tar_block("<base64url-proto>")
+ * fact to an existing Biscuit token in memory without contacting the control plane.
+ */
+export declare function attenuateBiscuit(biscuitBytes: Uint8Array, ruleInput: MessageInitShape<typeof TaskAuthorizationRuleSchema>, trustedKeys: Uint8Array[]): Promise<Uint8Array>;
+/**
+ * Seals a Biscuit token so no further blocks can be appended by downstream holders.
+ */
+export declare function sealBiscuit(biscuitBytes: Uint8Array, trustedKeys: Uint8Array[]): Promise<Uint8Array>;
+/** Requires role(<role>) on an already verified token, as identity.RequireRole. */
+export declare function requireRole(verified: VerifiedBiscuit, role: string): void;
+/**
+ * Requires that an already verified provider credential grants serving
+ * targetService ("<type>://<name>"), as identity.RequirePublish: the
+ * directory names whoever announced the service, only the credential says
+ * who may serve it. The provider's own catalog names no service and needs
+ * no grant; so does an empty target.
+ */
+export declare function requirePublish(verified: VerifiedBiscuit, targetService: string, policyRules?: readonly string[]): Promise<void>;

package/dist/biscuit.js

@@ -0,0 +1,250 @@
+// 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 { BASELINE_DATALOG } from "./gen/datalog.js";
+import { TaskAuthorizationRuleSchema } from "./gen/agentmesh_pb.js";
+import { loadBiscuitWasm } from "./platform/wasm.js";
+import { effectiveTARExpiration, encodeTARBlockFact, parseTARBlockSource } from "./tar.js";
+let loading;
+/** The biscuit-wasm module, loaded once, the way the runtime loads it. */
+export function loadBiscuit() {
+    loading ??= loadBiscuitWasm();
+    return loading;
+}
+/** Datalog evaluation budget, as in internal/identity.AuthorizerOptions. */
+export const AUTHORIZER_LIMITS = { max_facts: 1000, max_iterations: 100, max_time_micro: 1_000_000 };
+/**
+ * Runs an authorize or query call under AUTHORIZER_LIMITS. biscuit-wasm
+ * applies the limits it is passed to the checks and policies only; the
+ * fact-generation pass runs under the builder's own limits, 1 ms of wall
+ * clock, which it does not let a caller change. A paused event loop or a
+ * throttled CPU then answers a valid request with RunLimit Timeout. The
+ * facts derived before that deadline stay in the authorizer and the next
+ * call resumes from them, so the pass is driven to completion here until
+ * the budget above is spent.
+ */
+export function withinLimits(run) {
+    const deadline = performance.now() + AUTHORIZER_LIMITS.max_time_micro / 1000;
+    for (;;) {
+        try {
+            return run();
+        }
+        catch (err) {
+            if (!isTimeout(err) || performance.now() >= deadline) {
+                throw err;
+            }
+        }
+    }
+}
+function isTimeout(err) {
+    return typeof err === "object" && err !== null && err.RunLimit === "Timeout";
+}
+export const ROLE_ROUTER = "mesh:role:router";
+export class BiscuitVerificationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "BiscuitVerificationError";
+    }
+}
+function describe(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+function parseWithTrustedKeys(wasm, biscuitBytes, trustedKeys) {
+    if (trustedKeys.length === 0) {
+        throw new BiscuitVerificationError("no trusted control plane key to verify against");
+    }
+    let token;
+    let verifyingKey;
+    let lastErr;
+    for (const key of trustedKeys) {
+        try {
+            token = wasm.Biscuit.fromBytes(biscuitBytes, wasm.PublicKey.fromBytes(key, wasm.SignatureAlgorithm.Ed25519));
+            verifyingKey = key;
+            break;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    if (!token || !verifyingKey) {
+        throw new BiscuitVerificationError(`biscuit is not signed by a trusted control plane key: ${describe(lastErr)}`);
+    }
+    return { token, verifyingKey };
+}
+function extractTARChain(token) {
+    const appendedCount = token.countBlocks() - 1;
+    if (appendedCount > BASELINE_DATALOG.max_attenuation_blocks) {
+        throw new BiscuitVerificationError(`biscuit carries ${appendedCount} appended blocks; maximum is ${BASELINE_DATALOG.max_attenuation_blocks}`);
+    }
+    const taskRules = [];
+    for (let i = 1; i <= appendedCount; i++) {
+        try {
+            taskRules.push(parseTARBlockSource(token.getBlockSource(i)));
+        }
+        catch (err) {
+            throw new BiscuitVerificationError(`biscuit block ${i}: ${describe(err)}`);
+        }
+    }
+    return taskRules;
+}
+/**
+ * Verifies a biscuit received from expectedPeerId over an authenticated
+ * connection. Every trusted key is tried, so a token minted under a
+ * retiring key still verifies during rotation.
+ *
+ * By default (peer handshakes on /mesh/auth/1.0.0), the authority block must
+ * carry node(expectedPeerId). When allowDelegated is true (request tokens in
+ * authorizeCaller), the authority block may alternatively carry both
+ * actor_node(expectedPeerId) and client_peer_id(expectedPeerId) without node().
+ */
+export async function verifyPeerBiscuit(biscuitBytes, expectedPeerId, trustedKeys, now = new Date(), options) {
+    const wasm = await loadBiscuit();
+    const { token, verifyingKey } = parseWithTrustedKeys(wasm, biscuitBytes, trustedKeys);
+    const taskRules = extractTARChain(token);
+    const builder = new wasm.AuthorizerBuilder();
+    builder.addFact(wasm.Fact.fromString(`time(${now.toISOString().replace(/\.\d{3}Z$/, "Z")})`));
+    builder.addCheck(wasm.Check.fromString("check if time($t), expiration($e), $t <= $e"));
+    builder.addPolicy(wasm.Policy.fromString("allow if true"));
+    const authorizer = builder.buildAuthenticated(token);
+    try {
+        withinLimits(() => authorizer.authorizeWithLimits(AUTHORIZER_LIMITS));
+    }
+    catch (err) {
+        throw new BiscuitVerificationError(`biscuit is expired or fails its checks: ${describe(err)}`);
+    }
+    const query = (rule) => withinLimits(() => authorizer.queryWithLimits(wasm.Rule.fromString(rule), AUTHORIZER_LIMITS));
+    const strings = (facts) => facts.map((f) => f.terms()[0]).filter((t) => typeof t === "string");
+    const bound = strings(query("p($p) <- node($p)"));
+    const actorNodes = strings(query("a($a) <- actor_node($a)"));
+    const clientPeers = strings(query("c($c) <- client_peer_id($c)"));
+    const isBoundNode = bound.includes(expectedPeerId);
+    const isBoundDelegated = options?.allowDelegated === true &&
+        actorNodes.includes(expectedPeerId) &&
+        clientPeers.includes(expectedPeerId);
+    if (!isBoundNode && !isBoundDelegated) {
+        throw new BiscuitVerificationError(`biscuit is not bound to peer ${expectedPeerId}`);
+    }
+    const expirations = query("e($e) <- expiration($e)")
+        .map((f) => f.terms()[0])
+        .filter((t) => t instanceof Date && !Number.isNaN(t.getTime()));
+    if (expirations.length === 0) {
+        throw new BiscuitVerificationError("biscuit carries no expiration fact");
+    }
+    const authorityExpiration = new Date(Math.min(...expirations.map((d) => d.getTime())));
+    const expiration = effectiveTARExpiration(authorityExpiration, taskRules);
+    if (now.getTime() > expiration.getTime()) {
+        throw new BiscuitVerificationError(`biscuit is expired at ${now.toISOString()} (effective expiration ${expiration.toISOString()})`);
+    }
+    const labels = {};
+    for (const f of query("l($k, $v) <- label($k, $v)")) {
+        const [k, v] = f.terms();
+        if (typeof k === "string" && typeof v === "string") {
+            labels[k] = v;
+        }
+    }
+    return {
+        peerId: expectedPeerId,
+        ...(actorNodes[0] !== undefined ? { actorNode: actorNodes[0] } : {}),
+        expiration,
+        verifyingKey,
+        roles: strings(query("r($r) <- role($r)")),
+        labels,
+        taskRules,
+        token: biscuitBytes,
+    };
+}
+/**
+ * Appends a non-authority block carrying a single tar_block("<base64url-proto>")
+ * fact to an existing Biscuit token in memory without contacting the control plane.
+ */
+export async function attenuateBiscuit(biscuitBytes, ruleInput, trustedKeys) {
+    const wasm = await loadBiscuit();
+    const { token } = parseWithTrustedKeys(wasm, biscuitBytes, trustedKeys);
+    const appendedCount = token.countBlocks() - 1;
+    if (appendedCount >= BASELINE_DATALOG.max_attenuation_blocks) {
+        throw new BiscuitVerificationError(`biscuit already has ${appendedCount} appended blocks (maximum ${BASELINE_DATALOG.max_attenuation_blocks})`);
+    }
+    extractTARChain(token);
+    const factStr = encodeTARBlockFact(ruleInput);
+    const block = wasm.Biscuit.block_builder();
+    block.addFact(wasm.Fact.fromString(factStr));
+    try {
+        return token.appendBlock(block).toBytes();
+    }
+    catch (err) {
+        throw new BiscuitVerificationError(`failed to append tar_block to biscuit: ${describe(err)}`);
+    }
+}
+/**
+ * Seals a Biscuit token so no further blocks can be appended by downstream holders.
+ */
+export async function sealBiscuit(biscuitBytes, trustedKeys) {
+    const wasm = await loadBiscuit();
+    const { token } = parseWithTrustedKeys(wasm, biscuitBytes, trustedKeys);
+    extractTARChain(token);
+    try {
+        return token.sealToken().toBytes();
+    }
+    catch (err) {
+        throw new BiscuitVerificationError(`failed to seal biscuit: ${describe(err)}`);
+    }
+}
+/** Requires role(<role>) on an already verified token, as identity.RequireRole. */
+export function requireRole(verified, role) {
+    if (!verified.roles.includes(role)) {
+        throw new BiscuitVerificationError(`biscuit lacks expected role ${JSON.stringify(role)}`);
+    }
+}
+/**
+ * Requires that an already verified provider credential grants serving
+ * targetService ("<type>://<name>"), as identity.RequirePublish: the
+ * directory names whoever announced the service, only the credential says
+ * who may serve it. The provider's own catalog names no service and needs
+ * no grant; so does an empty target.
+ */
+export async function requirePublish(verified, targetService, policyRules = []) {
+    if (targetService === "" || targetService === `system://${BASELINE_DATALOG.catalog_target}`) {
+        return;
+    }
+    const m = /^([a-z0-9]+):\/\/(.+)$/.exec(targetService);
+    if (m === null) {
+        throw new BiscuitVerificationError(`service ${JSON.stringify(targetService)} must be <type>://<name>`);
+    }
+    const wasm = await loadBiscuit();
+    const token = wasm.Biscuit.fromBytes(verified.token, wasm.PublicKey.fromBytes(verified.verifyingKey, wasm.SignatureAlgorithm.Ed25519));
+    const builder = new wasm.AuthorizerBuilder();
+    builder.addFact(wasm.Fact.fromString(`${BASELINE_DATALOG.fact_publish}(${JSON.stringify(m[1])}, ${JSON.stringify(m[2])})`));
+    // The mesh policy derives grants from the credential's role() and label()
+    // facts, so a policy change reaches this check before the provider's
+    // credential is minted again.
+    for (const r of policyRules) {
+        builder.addRule(wasm.Rule.fromString(r));
+    }
+    for (const policy of BASELINE_DATALOG.publish_policies) {
+        builder.addPolicy(wasm.Policy.fromString(policy));
+    }
+    try {
+        withinLimits(() => builder.buildAuthenticated(token).authorizeWithLimits(AUTHORIZER_LIMITS));
+    }
+    catch {
+        throw new BiscuitVerificationError(`peer ${verified.peerId} is not granted serving ${targetService}`);
+    }
+}

package/dist/bytes.d.ts

@@ -0,0 +1,10 @@
+export declare function toHex(bytes: Uint8Array): string;
+export declare function fromHex(text: string): Uint8Array;
+/** Padded standard base64 (RFC 4648 section 4), what Go base64.StdEncoding decodes. */
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(text: string): Uint8Array;
+/** Unpadded base64url (RFC 4648 section 5), what Go base64.RawURLEncoding decodes. */
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(text: string): Uint8Array;
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+export declare function concatBytes(...parts: Uint8Array[]): Uint8Array<ArrayBuffer>;

package/dist/bytes.js

@@ -0,0 +1,51 @@
+// 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.
+// Text encodings of bytes as the Go side reads them, for any JavaScript
+// runtime. The names say which alphabet and whether the text is padded:
+// a biscuit travels as padded standard base64 (Go base64.StdEncoding), a
+// challenge signature as unpadded base64url (Go base64.RawURLEncoding).
+import { fromString } from "uint8arrays/from-string";
+import { toString } from "uint8arrays/to-string";
+export function toHex(bytes) {
+    return toString(bytes, "hex");
+}
+export function fromHex(text) {
+    return fromString(text, "hex");
+}
+/** Padded standard base64 (RFC 4648 section 4), what Go base64.StdEncoding decodes. */
+export function toBase64(bytes) {
+    return toString(bytes, "base64pad");
+}
+export function fromBase64(text) {
+    return fromString(text, "base64pad");
+}
+/** Unpadded base64url (RFC 4648 section 5), what Go base64.RawURLEncoding decodes. */
+export function toBase64Url(bytes) {
+    return toString(bytes, "base64url");
+}
+export function fromBase64Url(text) {
+    return fromString(text, "base64url");
+}
+export function bytesEqual(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+export function concatBytes(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.length;
+    }
+    return out;
+}

package/dist/challenges.d.ts

@@ -0,0 +1,16 @@
+/** Signed at POST /enroll (bootstrap token enrollment). */
+export declare function enrollChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at GET /enroll/status while a bootstrap enrollment is pending. */
+export declare function enrollStatusChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at POST /register (OIDC enrollment). */
+export declare function registerChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at POST /refresh. */
+export declare function refreshChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at GET /policies. */
+export declare function policiesChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at GET /egress. */
+export declare function egressChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at GET /revocations. */
+export declare function revocationsChallenge(peerId: string, ts: number): Uint8Array;
+/** Signed at POST /nodes/catalog. */
+export declare function nodesCatalogChallenge(peerId: string, ts: number): Uint8Array;

package/dist/challenges.js

@@ -0,0 +1,55 @@
+// 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.
+// Proof-of-possession challenges on the control plane's mesh surface.
+// Each payload names the peer and the endpoint, so a captured signature
+// verifies nowhere else. Mirrors api/network.go; ts is unix milliseconds.
+const encoder = new TextEncoder();
+function challenge(domain, peerId, ts) {
+    if (!Number.isSafeInteger(ts) || ts <= 0) {
+        throw new Error(`challenge timestamp must be a positive integer, got ${ts}`);
+    }
+    return encoder.encode(`mesh:${domain}:${peerId}:${ts}`);
+}
+/** Signed at POST /enroll (bootstrap token enrollment). */
+export function enrollChallenge(peerId, ts) {
+    return challenge("enroll", peerId, ts);
+}
+/** Signed at GET /enroll/status while a bootstrap enrollment is pending. */
+export function enrollStatusChallenge(peerId, ts) {
+    return challenge("enroll-status", peerId, ts);
+}
+/** Signed at POST /register (OIDC enrollment). */
+export function registerChallenge(peerId, ts) {
+    return challenge("register", peerId, ts);
+}
+/** Signed at POST /refresh. */
+export function refreshChallenge(peerId, ts) {
+    return challenge("refresh", peerId, ts);
+}
+/** Signed at GET /policies. */
+export function policiesChallenge(peerId, ts) {
+    return challenge("policies", peerId, ts);
+}
+/** Signed at GET /egress. */
+export function egressChallenge(peerId, ts) {
+    return challenge("egress", peerId, ts);
+}
+/** Signed at GET /revocations. */
+export function revocationsChallenge(peerId, ts) {
+    return challenge("revocations", peerId, ts);
+}
+/** Signed at POST /nodes/catalog. */
+export function nodesCatalogChallenge(peerId, ts) {
+    return challenge("nodes-catalog", peerId, ts);
+}

package/dist/conformance-join.d.ts

@@ -0,0 +1 @@
+export {};