@adastracomputing/ink 0.1.0-alpha.3 → 0.1.1

package/dist/crypto/keys.d.ts

@@ -0,0 +1,42 @@
+export interface Keypair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+/** Generate a new Ed25519 keypair (signing). */
+export declare function generateKeypair(): Promise<Keypair>;
+/** Generate a new X25519 keypair (encryption). */
+export declare function generateEncryptionKeypair(): Keypair;
+/** Encode bytes as base58btc (no multibase prefix). */
+export declare function encodeBase58(bytes: Uint8Array): string;
+/** Decode base58btc string to bytes. */
+export declare function decodeBase58(str: string): Uint8Array;
+/**
+ * Encode a public key as a multibase base58btc string.
+ * Format: 'z' prefix + base58btc(multicodec_prefix + public_key)
+ */
+export declare function encodePublicKeyMultibase(publicKey: Uint8Array): string;
+/**
+ * Encode an X25519 public key as a multibase base58btc string.
+ * Format: 'z' prefix + base58btc(x25519_multicodec_prefix + public_key)
+ */
+export declare function encodeEncryptionKeyMultibase(publicKey: Uint8Array): string;
+/**
+ * Decode a multibase base58btc public key string.
+ * Returns the raw 32-byte public key.
+ */
+export declare function decodePublicKeyMultibase(multibase: string): Uint8Array;
+/**
+ * Decode a multibase base58btc X25519 public key string.
+ * Returns the raw 32-byte public key.
+ */
+export declare function decodeEncryptionKeyMultibase(multibase: string): Uint8Array;
+/**
+ * Derive agent ID from a public key.
+ * Format: tulpa:<multibase-encoded-public-key>
+ */
+export declare function deriveAgentId(publicKey: Uint8Array): string;
+/**
+ * Extract the public key from an agent ID.
+ * Only used for initial key exchange — after that, always resolve via identity store.
+ */
+export declare function extractPublicKeyFromAgentId(agentId: string): Uint8Array;

package/dist/crypto/keys.js

@@ -0,0 +1,179 @@
+import * as ed from "@noble/ed25519";
+import { x25519 } from "@noble/curves/ed25519.js";
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/** Ed25519 multicodec prefix: 0xed01 */
+const ED25519_MULTICODEC = new Uint8Array([0xed, 0x01]);
+/** X25519 multicodec prefix: 0xec01 */
+const X25519_MULTICODEC = new Uint8Array([0xec, 0x01]);
+/** Generate a new Ed25519 keypair (signing). */
+export async function generateKeypair() {
+    const { secretKey, publicKey } = await ed.keygenAsync();
+    return { privateKey: secretKey, publicKey };
+}
+/** Generate a new X25519 keypair (encryption). */
+export function generateEncryptionKeypair() {
+    const privateKey = crypto.getRandomValues(new Uint8Array(32));
+    const publicKey = x25519.getPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/** Encode bytes as base58btc (no multibase prefix). */
+export function encodeBase58(bytes) {
+    if (bytes.length === 0)
+        return "";
+    // Count leading zeros
+    let zeros = 0;
+    for (const b of bytes) {
+        if (b !== 0)
+            break;
+        zeros++;
+    }
+    // Convert to bigint
+    let num = 0n;
+    for (const b of bytes) {
+        num = num * 256n + BigInt(b);
+    }
+    let result = "";
+    while (num > 0n) {
+        const remainder = Number(num % 58n);
+        num = num / 58n;
+        result = BASE58_ALPHABET[remainder] + result;
+    }
+    // Add leading '1's for zero bytes
+    return "1".repeat(zeros) + result;
+}
+/** Cap base58 input length BEFORE the BigInt accumulation loop. A poisoned
+ *  Agent Card with a multi-KB `publicKeyMultibase` would otherwise force
+ *  O(n^2) BigInt arithmetic — large `num * 58n + BigInt(idx)` per char — for
+ *  every input byte before any trailing length check fires.
+ *
+ *  1024 is well above any legitimate multibase-encoded public key (Ed25519
+ *  is ~50 chars, even multi-codec wrappers are well under 100).
+ */
+const MAX_BASE58_INPUT_LEN = 1024;
+/** Decode base58btc string to bytes. */
+export function decodeBase58(str) {
+    if (str.length === 0)
+        return new Uint8Array(0);
+    if (str.length > MAX_BASE58_INPUT_LEN) {
+        throw new Error(`base58 input exceeds maximum length of ${MAX_BASE58_INPUT_LEN}`);
+    }
+    let num = 0n;
+    for (const ch of str) {
+        const idx = BASE58_ALPHABET.indexOf(ch);
+        if (idx === -1)
+            throw new Error(`Invalid base58 character: ${ch}`);
+        num = num * 58n + BigInt(idx);
+    }
+    // Convert bigint to bytes
+    const hex = num.toString(16).padStart(2, "0");
+    const padded = hex.length % 2 ? "0" + hex : hex;
+    const bytes = [];
+    for (let i = 0; i < padded.length; i += 2) {
+        bytes.push(parseInt(padded.slice(i, i + 2), 16));
+    }
+    // Add leading zero bytes
+    let zeros = 0;
+    for (const ch of str) {
+        if (ch !== "1")
+            break;
+        zeros++;
+    }
+    return new Uint8Array([...new Uint8Array(zeros), ...bytes]);
+}
+/**
+ * Encode a public key as a multibase base58btc string.
+ * Format: 'z' prefix + base58btc(multicodec_prefix + public_key)
+ */
+export function encodePublicKeyMultibase(publicKey) {
+    if (!(publicKey instanceof Uint8Array)) {
+        throw new Error("publicKey must be a Uint8Array");
+    }
+    if (publicKey.length !== 32) {
+        throw new Error(`publicKey must be 32 bytes, got ${publicKey.length}`);
+    }
+    const prefixed = new Uint8Array(ED25519_MULTICODEC.length + publicKey.length);
+    prefixed.set(ED25519_MULTICODEC);
+    prefixed.set(publicKey, ED25519_MULTICODEC.length);
+    return "z" + encodeBase58(prefixed);
+}
+/**
+ * Encode an X25519 public key as a multibase base58btc string.
+ * Format: 'z' prefix + base58btc(x25519_multicodec_prefix + public_key)
+ */
+export function encodeEncryptionKeyMultibase(publicKey) {
+    if (!(publicKey instanceof Uint8Array)) {
+        throw new Error("publicKey must be a Uint8Array");
+    }
+    if (publicKey.length !== 32) {
+        throw new Error(`publicKey must be 32 bytes, got ${publicKey.length}`);
+    }
+    const prefixed = new Uint8Array(X25519_MULTICODEC.length + publicKey.length);
+    prefixed.set(X25519_MULTICODEC);
+    prefixed.set(publicKey, X25519_MULTICODEC.length);
+    return "z" + encodeBase58(prefixed);
+}
+/**
+ * Decode a multibase base58btc public key string.
+ * Returns the raw 32-byte public key.
+ */
+export function decodePublicKeyMultibase(multibase) {
+    if (typeof multibase !== "string" || multibase.length === 0 || multibase.length > 1024) {
+        throw new Error("multibase must be a non-empty string under 1024 chars");
+    }
+    if (!multibase.startsWith("z")) {
+        throw new Error("Expected multibase base58btc prefix 'z'");
+    }
+    const decoded = decodeBase58(multibase.slice(1));
+    if (decoded[0] !== ED25519_MULTICODEC[0] ||
+        decoded[1] !== ED25519_MULTICODEC[1]) {
+        throw new Error("Invalid Ed25519 multicodec prefix");
+    }
+    const key = decoded.slice(2);
+    if (key.length !== 32) {
+        throw new Error(`Invalid Ed25519 public key length: expected 32, got ${key.length}`);
+    }
+    return key;
+}
+/**
+ * Decode a multibase base58btc X25519 public key string.
+ * Returns the raw 32-byte public key.
+ */
+export function decodeEncryptionKeyMultibase(multibase) {
+    if (typeof multibase !== "string" || multibase.length === 0 || multibase.length > 1024) {
+        throw new Error("multibase must be a non-empty string under 1024 chars");
+    }
+    if (!multibase.startsWith("z")) {
+        throw new Error("Expected multibase base58btc prefix 'z'");
+    }
+    const decoded = decodeBase58(multibase.slice(1));
+    if (decoded[0] !== X25519_MULTICODEC[0] ||
+        decoded[1] !== X25519_MULTICODEC[1]) {
+        throw new Error("Invalid X25519 multicodec prefix");
+    }
+    const key = decoded.slice(2);
+    if (key.length !== 32) {
+        throw new Error(`Invalid X25519 public key length: expected 32, got ${key.length}`);
+    }
+    return key;
+}
+/**
+ * Derive agent ID from a public key.
+ * Format: tulpa:<multibase-encoded-public-key>
+ */
+export function deriveAgentId(publicKey) {
+    return `tulpa:${encodePublicKeyMultibase(publicKey)}`;
+}
+/**
+ * Extract the public key from an agent ID.
+ * Only used for initial key exchange — after that, always resolve via identity store.
+ */
+export function extractPublicKeyFromAgentId(agentId) {
+    if (typeof agentId !== "string" || agentId.length === 0 || agentId.length > 512) {
+        throw new Error("Invalid agent ID");
+    }
+    const prefix = "tulpa:";
+    if (!agentId.startsWith(prefix)) {
+        throw new Error("Invalid agent ID format");
+    }
+    return decodePublicKeyMultibase(agentId.slice(prefix.length));
+}

package/dist/crypto/multi-key-verify.d.ts

@@ -0,0 +1,29 @@
+import { type InkSignInput } from "./ink.js";
+import type { CandidateKey, KeyStatus } from "../models/key-entry.js";
+export interface MultiKeyVerifyResult {
+    verified: boolean;
+    keyId?: string;
+    /** Status of the key that verified the signature (for observability). */
+    keyStatus?: KeyStatus;
+    /** True when the signature was verified using a retired key. Callers should track this for key rotation observability. */
+    usedRetiredKey?: boolean;
+}
+/**
+ * Verify an INK signature against a set of candidate keys.
+ *
+ * Verification order per spec §6.4:
+ *   1. Hinted key (if provided and found) — optimization for keyId header
+ *   2. Active keys first
+ *   3. Retired keys second
+ *   4. Revoked keys are always skipped
+ *
+ * In all three cases the key's `[validFrom, validUntil]` window MUST
+ * contain the message timestamp. A key that has expired (validUntil in
+ * the past) or is not yet valid (validFrom in the future) is skipped
+ * even if its status would otherwise admit it. This closes the window
+ * where an attacker who steals an expired key — even one still listed
+ * as "retired" for historical verification — could sign fresh messages.
+ *
+ * Returns the matching keyId and keyStatus on success.
+ */
+export declare function verifyInkSignatureWithKeys(input: InkSignInput, signature: string, keys: CandidateKey[], hintKeyId?: string): Promise<MultiKeyVerifyResult>;

package/dist/crypto/multi-key-verify.js

@@ -0,0 +1,153 @@
+import { verifyInkSignature } from "./ink.js";
+/** Maximum number of candidate keys tried during multi-key verification.
+ * Prevents a poisoned Agent Card from forcing O(n) Ed25519 verifications. */
+const MAX_CANDIDATE_KEYS = 20;
+/**
+ * Check whether a candidate key's validity window contains a given
+ * message timestamp. Returns true when the key is usable. Both window
+ * endpoints are optional; missing endpoints are treated as open (so a
+ * key with no validFrom is usable arbitrarily far back, and a key with
+ * no validUntil is usable arbitrarily far forward — preserving the
+ * legacy behaviour for callers that don't track windows).
+ *
+ * Defense in depth at the verifier:
+ *   - status === "revoked" is already filtered upstream; this function
+ *     ALSO refuses any key whose `revokedAt` field is present, in case
+ *     a caller forgot to set status.
+ *   - Non-string OR empty-string window fields are treated as malformed
+ *     and fail closed. An integrator that maps a NULL/blank database
+ *     column to "" must not get the same behaviour as "field absent" —
+ *     that would let an expired key slip through under the legacy
+ *     "no window = open" rule. The matching boundary check lives in
+ *     extractCandidateKeys; this guard catches custom resolveKeySet
+ *     implementations that bypass that boundary.
+ *   - Malformed timestamp strings (Date.parse returns NaN) also fail
+ *     closed for the same reason.
+ */
+function isKeyValidAtTime(key, messageMs) {
+    // Any field that is PRESENT but not a non-empty parseable datetime
+    // string is treated as malformed and fails closed. "Present" means
+    // !== undefined, so a `null`, number, object, or empty string here
+    // is a misuse — refusing it stops a custom resolveKeySet that maps a
+    // DB NULL to "" (or to literal null) from looking like "no window".
+    const isPresent = (x) => x !== undefined;
+    // Cap length BEFORE Date.parse — a multi-megabyte string would
+    // otherwise burn CPU in the date parser before the parse failure.
+    // 64 chars matches the cap used everywhere else in INK (ISO 8601
+    // with subsecond + timezone fits in ~30; 64 leaves headroom).
+    const isValidDatetimeString = (x) => typeof x === "string" && x.length > 0 && x.length <= 64 && Number.isFinite(Date.parse(x));
+    if (isPresent(key.revokedAt)) {
+        // revokedAt present at all is a "do not verify" signal regardless
+        // of whether the value parses. A revoked key with an unparseable
+        // revokedAt is still revoked.
+        return false;
+    }
+    if (isPresent(key.validFrom)) {
+        if (!isValidDatetimeString(key.validFrom))
+            return false;
+        if (messageMs < Date.parse(key.validFrom))
+            return false;
+    }
+    if (isPresent(key.validUntil)) {
+        if (!isValidDatetimeString(key.validUntil))
+            return false;
+        if (messageMs > Date.parse(key.validUntil))
+            return false;
+    }
+    return true;
+}
+/**
+ * Verify an INK signature against a set of candidate keys.
+ *
+ * Verification order per spec §6.4:
+ *   1. Hinted key (if provided and found) — optimization for keyId header
+ *   2. Active keys first
+ *   3. Retired keys second
+ *   4. Revoked keys are always skipped
+ *
+ * In all three cases the key's `[validFrom, validUntil]` window MUST
+ * contain the message timestamp. A key that has expired (validUntil in
+ * the past) or is not yet valid (validFrom in the future) is skipped
+ * even if its status would otherwise admit it. This closes the window
+ * where an attacker who steals an expired key — even one still listed
+ * as "retired" for historical verification — could sign fresh messages.
+ *
+ * Returns the matching keyId and keyStatus on success.
+ */
+export async function verifyInkSignatureWithKeys(input, signature, keys, hintKeyId) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        return { verified: false };
+    }
+    if (!Array.isArray(keys) || keys.length === 0) {
+        return { verified: false };
+    }
+    if (typeof signature !== "string") {
+        return { verified: false };
+    }
+    // Parse the message timestamp once so window checks are O(1) per key.
+    // verifyInkAuth caps timestamp length upstream, but this helper is
+    // exported, so guard locally too: a non-string, empty, oversized, or
+    // non-parseable timestamp all fail closed. The 64-char cap stops a
+    // multi-megabyte string from reaching Date.parse.
+    if (typeof input.timestamp !== "string" || input.timestamp.length === 0 || input.timestamp.length > 64) {
+        return { verified: false };
+    }
+    const messageMs = Date.parse(input.timestamp);
+    if (!Number.isFinite(messageMs)) {
+        return { verified: false };
+    }
+    // Enforce an upper bound on key set size to prevent DoS via poisoned Agent Cards
+    // that contain hundreds of keys, forcing that many Ed25519 operations per request.
+    const bounded = keys.slice(0, MAX_CANDIDATE_KEYS);
+    // Try hinted key first if provided.
+    // Allowlist of acceptable statuses. A deny-list (k.status !== "revoked") would
+    // accept entries with malformed/unrecognised status — e.g. case-mismatched
+    // "Revoked" or empty string would slip past here while being skipped by the
+    // active/retired partition iteration below.
+    if (hintKeyId) {
+        const hinted = bounded.find((k) => k.keyId === hintKeyId && (k.status === "active" || k.status === "retired"));
+        if (hinted && isKeyValidAtTime(hinted, messageMs)) {
+            try {
+                const valid = await verifyInkSignature(input, signature, hinted.publicKey);
+                if (valid)
+                    return { verified: true, keyId: hinted.keyId, keyStatus: hinted.status, usedRetiredKey: hinted.status === "retired" };
+            }
+            catch {
+                // Fall through to normal iteration
+            }
+        }
+    }
+    // Partition by status: active first, then retired. Skip revoked.
+    // Drop any candidate whose validity window doesn't contain the
+    // message timestamp before reaching the verify loop.
+    const active = bounded.filter((k) => k.status === "active" && isKeyValidAtTime(k, messageMs));
+    const retired = bounded.filter((k) => k.status === "retired" && isKeyValidAtTime(k, messageMs));
+    // Try active keys first
+    for (const key of active) {
+        // Skip if already tried as hint
+        if (hintKeyId && key.keyId === hintKeyId)
+            continue;
+        try {
+            const valid = await verifyInkSignature(input, signature, key.publicKey);
+            if (valid)
+                return { verified: true, keyId: key.keyId, keyStatus: key.status, usedRetiredKey: false };
+        }
+        catch {
+            // Key failed verification, try next
+        }
+    }
+    // Try retired keys
+    for (const key of retired) {
+        if (hintKeyId && key.keyId === hintKeyId)
+            continue;
+        try {
+            const valid = await verifyInkSignature(input, signature, key.publicKey);
+            if (valid)
+                return { verified: true, keyId: key.keyId, keyStatus: key.status, usedRetiredKey: true };
+        }
+        catch {
+            // Key failed verification, try next
+        }
+    }
+    return { verified: false };
+}

package/dist/crypto/sign.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Sign a message object using Ed25519.
+ *
+ * 1. Remove `signature` field if present
+ * 2. JCS canonicalize (RFC 8785) via `canonicalize` library
+ * 3. Sign canonical bytes directly with Ed25519
+ * 4. Return base64url-encoded signature (no padding)
+ */
+export declare function signMessage(message: Record<string, unknown>, privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify a message signature.
+ *
+ * 1. Extract and remove `signature`
+ * 2. JCS canonicalize the rest
+ * 3. Verify Ed25519 signature against canonical bytes
+ */
+export declare function verifyMessage(message: Record<string, unknown>, publicKey: Uint8Array): Promise<boolean>;

package/dist/crypto/sign.js

@@ -0,0 +1,152 @@
+import * as ed from "@noble/ed25519";
+import canonicalize from "canonicalize";
+/** Same bounds used by the ink.ts verify paths. Kept in sync so a peer
+ * cannot pick the "softer" sign.ts path to bypass the cap. */
+const MAX_MESSAGE_NODES = 10_000;
+const MAX_MESSAGE_DEPTH = 32;
+const MAX_MESSAGE_CHARS = 1_200_000;
+/** Upper limit on the canonicalized message length, matching
+ * MAX_SIGBASE_BODY_BYTES in ink.ts. Defense in depth alongside the node
+ * walk: a message can be small in node count but still expand to huge
+ * canonical bytes via long string values. */
+const MAX_MESSAGE_CANONICAL_BYTES = 1_048_576;
+/**
+ * Cheap depth/node/byte walk over a value before it is handed to
+ * `canonicalize`. Bails before the recursive sort+serialize runs, so an
+ * attacker who supplies a syntactically valid-shape signature with a
+ * pathological message body cannot burn CPU/memory inside the verify
+ * path. Mirrors src/crypto/ink.ts:isWithinCanonicalizeBounds, including
+ * the byte counter that stops a single huge string from sneaking past
+ * the node check.
+ */
+function isWithinBounds(value) {
+    let nodes = 0;
+    let chars = 0;
+    function walk(v, depth) {
+        if (depth > MAX_MESSAGE_DEPTH)
+            return false;
+        if (++nodes > MAX_MESSAGE_NODES)
+            return false;
+        if (v === null || typeof v !== "object") {
+            if (typeof v === "string") {
+                chars += v.length;
+                if (chars > MAX_MESSAGE_CHARS)
+                    return false;
+            }
+            return true;
+        }
+        if (Array.isArray(v)) {
+            for (const item of v)
+                if (!walk(item, depth + 1))
+                    return false;
+            return true;
+        }
+        for (const key of Object.keys(v)) {
+            if (++nodes > MAX_MESSAGE_NODES)
+                return false;
+            chars += key.length;
+            if (chars > MAX_MESSAGE_CHARS)
+                return false;
+            if (!walk(v[key], depth + 1))
+                return false;
+        }
+        return true;
+    }
+    return walk(value, 0);
+}
+/**
+ * Sign a message object using Ed25519.
+ *
+ * 1. Remove `signature` field if present
+ * 2. JCS canonicalize (RFC 8785) via `canonicalize` library
+ * 3. Sign canonical bytes directly with Ed25519
+ * 4. Return base64url-encoded signature (no padding)
+ */
+export async function signMessage(message, privateKey) {
+    if (message === null || typeof message !== "object" || Array.isArray(message)) {
+        throw new Error("message must be a non-null object");
+    }
+    if (!(privateKey instanceof Uint8Array) || privateKey.length !== 32) {
+        throw new Error("privateKey must be a 32-byte Uint8Array");
+    }
+    const { signature: _, ...unsigned } = message;
+    // Refuse oversized inputs at sign time so the sign side cannot mint
+    // signatures over payloads larger than any conformant verifier will
+    // accept. Mirrors the matching guard in verifyMessage().
+    if (!isWithinBounds(unsigned)) {
+        throw new Error("Message exceeds maximum allowed complexity");
+    }
+    const canonical = canonicalize(unsigned);
+    if (canonical === undefined) {
+        throw new Error("Failed to canonicalize message");
+    }
+    if (canonical.length > MAX_MESSAGE_CANONICAL_BYTES) {
+        throw new Error("Canonicalized message exceeds maximum allowed size");
+    }
+    // Domain-separated signing to prevent cross-protocol signature replay
+    const prefixed = `tulpa/sign\n${canonical}`;
+    const bytes = new TextEncoder().encode(prefixed);
+    const sig = await ed.signAsync(bytes, privateKey);
+    return base64urlEncode(sig);
+}
+/**
+ * Verify a message signature.
+ *
+ * 1. Extract and remove `signature`
+ * 2. JCS canonicalize the rest
+ * 3. Verify Ed25519 signature against canonical bytes
+ */
+export async function verifyMessage(message, publicKey) {
+    if (message === null || typeof message !== "object" || Array.isArray(message))
+        return false;
+    if (!(publicKey instanceof Uint8Array))
+        return false;
+    const { signature, ...unsigned } = message;
+    if (typeof signature !== "string") {
+        return false;
+    }
+    // Ed25519 signatures are 64 bytes = 86 base64url chars (no padding).
+    // Strict format check before decoding rejects non-canonical encodings outright.
+    if (!/^[A-Za-z0-9_-]{86}$/.test(signature)) {
+        return false;
+    }
+    // Pre-canonicalize complexity cap: bail before `canonicalize()` walks
+    // an attacker-supplied object that would only be rejected later by
+    // signature verification. Mirrors the guard in verifyInkSignature so
+    // a peer can't pick whichever entrypoint is softer.
+    if (!isWithinBounds(unsigned)) {
+        return false;
+    }
+    const canonical = canonicalize(unsigned);
+    if (canonical === undefined) {
+        return false;
+    }
+    if (canonical.length > MAX_MESSAGE_CANONICAL_BYTES) {
+        return false;
+    }
+    // Domain-prefixed verification only — legacy unprefixed signatures are no longer accepted.
+    // signMessage() has always used `tulpa/sign\n` prefix; no callers produce unprefixed signatures.
+    const prefixed = `tulpa/sign\n${canonical}`;
+    const prefixedBytes = new TextEncoder().encode(prefixed);
+    try {
+        const sig = base64urlDecode(signature);
+        return await ed.verifyAsync(sig, prefixedBytes, publicKey);
+    }
+    catch {
+        // Malformed signature (invalid base64url, wrong byte length, bad key) — treat as invalid
+        return false;
+    }
+}
+/** Encode Uint8Array as base64url (no padding). */
+function base64urlEncode(bytes) {
+    const binString = Array.from(bytes, (b) => String.fromCharCode(b)).join("");
+    const base64 = btoa(binString);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decode base64url string to Uint8Array. */
+function base64urlDecode(str) {
+    const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const binString = atob(padded);
+    return Uint8Array.from(binString, (c) => c.charCodeAt(0));
+}

package/dist/crypto/verify.js

@@ -0,0 +1 @@
+export { verifyMessage } from "./sign.js";

package/dist/discovery/agent-card.d.ts

@@ -0,0 +1,83 @@
+import type { AgentCard } from "../models/agent-card.js";
+import type { CandidateKey } from "../models/key-entry.js";
+/** Reject hostnames that resolve (statically) to loopback, private, or
+ * link-local addresses. This is an SSRF defense for integrators that may
+ * pass user-controlled baseUrl values. Returns true if the hostname is
+ * a literal IP in a reserved range, a loopback name, or an IPv6 unique
+ * local / link-local address.
+ *
+ * Note: this does NOT defend against DNS rebinding — a public hostname
+ * that resolves to 127.0.0.1 at fetch time will still hit loopback.
+ * That defense lives at the runtime / platform layer. */
+export declare function isPrivateHostname(hostname: string): boolean;
+export interface FetchAgentCardOptions {
+    /** Allow baseUrls whose hostname is a literal loopback / private /
+     * link-local / IANA special-use address. Off by default — flip on for
+     * unit tests or for an INK integrator running against an intentional
+     * intranet endpoint. */
+    allowPrivateHosts?: boolean;
+    /** Override the fetch implementation used to retrieve the card. This is
+     * the integrator's hook for connect-time SSRF defense (DNS rebinding):
+     * a public hostname can resolve to a private IP at fetch time and
+     * bypass the literal-hostname allowlist below. Wrap your platform's
+     * fetch with one that resolves + pins the IP and rejects private
+     * connect targets (e.g. undici with a custom dispatcher on Node, or
+     * `cf: { resolveOverride: validatedIp }` on Cloudflare Workers). */
+    fetch?: typeof fetch;
+    /** Strict mode: require that the caller supply `options.fetch`. When
+     * true, the default global `fetch` is refused for non-literal hostnames
+     * because the default cannot perform connect-time IP filtering and is
+     * therefore vulnerable to DNS rebinding. Off by default for backwards
+     * compatibility; on by default for any production integration where
+     * `baseUrl` is taken from untrusted input. Returns null without
+     * fetching when the condition fails. */
+    requireSafeFetch?: boolean;
+}
+/**
+ * Fetch an Agent Card from a remote INK endpoint.
+ * Convention: GET /ink/v1/:agentId/agent.json
+ *
+ * SECURITY: this function applies several SSRF defenses by default —
+ * https-only baseUrl, no userinfo, literal-hostname allowlist excluding
+ * loopback / private / link-local / IANA special-use blocks (both v4 and
+ * v4-mapped v6), no redirect following, body-size cap, identity binding.
+ *
+ * It does NOT defend against DNS rebinding: a public hostname that
+ * resolves to a private IP at fetch time will still be reached. The
+ * runtime-agnostic library cannot solve this on its own — pass
+ * `options.fetch` with a connect-time IP-filtering implementation
+ * (undici dispatcher on Node, `cf.resolveOverride` on Cloudflare
+ * Workers, an egress proxy, etc.) when the baseUrl is not fully trusted.
+ */
+export declare function fetchAgentCard(agentId: string, baseUrl: string, options?: FetchAgentCardOptions): Promise<AgentCard | null>;
+/**
+ * Extract candidate signing keys from an Agent Card.
+ *
+ * Authority rule: presence of `keys.signing` (even when empty) is
+ * authoritative. Callers MUST treat the returned set as the complete list
+ * of acceptable signers — including the empty set, which means "key set
+ * published, no usable keys" and forbids any legacy bootstrap fallback.
+ *
+ *   - `keys.signing` absent  → fall back to legacy `publicKeyMultibase`
+ *   - `keys.signing: []`     → return [] (authoritative empty)
+ *   - `keys.signing: [k..]`  → parse each entry independently; malformed
+ *                              entries are skipped so a single bad entry
+ *                              cannot collapse the whole set to "legacy"
+ *                              and let a rotated-away bootstrap key pass.
+ */
+export declare function extractCandidateKeys(card: AgentCard): CandidateKey[];
+/**
+ * Resolve a well-known discovery base URL for an agent handle.
+ *
+ * INK does not mandate a single discovery origin — handle → base URL
+ * resolution is integrator-specific. Implementations typically use one of:
+ *
+ *   - DNS TXT record at `_ink.<handle>` (planned)
+ *   - HTTPS .well-known lookup at `https://<handle>/.well-known/ink/agent.json`
+ *   - A platform-specific registry maintained by a host service
+ *
+ * Pass a `resolveBase` callback at integration time. Returning null defers
+ * to the caller's fallback (e.g. an explicit endpoint in the Agent Card
+ * itself).
+ */
+export declare function resolveBaseUrl(handle: string, resolveBase?: (handle: string) => string | null): string | null;