@adastracomputing/ink 0.1.0-alpha.3 → 0.1.1

package/src/crypto/keys.ts

@@ -1,210 +0,0 @@
-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]);
-
-export interface Keypair {
-  privateKey: Uint8Array; // 32 bytes
-  publicKey: Uint8Array; // 32 bytes
-}
-
-/** Generate a new Ed25519 keypair (signing). */
-export async function generateKeypair(): Promise<Keypair> {
-  const { secretKey, publicKey } = await ed.keygenAsync();
-  return { privateKey: secretKey, publicKey };
-}
-
-/** Generate a new X25519 keypair (encryption). */
-export function generateEncryptionKeypair(): Keypair {
-  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: Uint8Array): string {
-  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: string): Uint8Array {
-  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: number[] = [];
-  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: Uint8Array): string {
-  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: Uint8Array): string {
-  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: string): Uint8Array {
-  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: string): Uint8Array {
-  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: Uint8Array): string {
-  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: string): Uint8Array {
-  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/src/crypto/multi-key-verify.ts

@@ -1,170 +0,0 @@
-import { verifyInkSignature, 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;
-}
-
-/** 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: CandidateKey, messageMs: number): boolean {
-  // 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: unknown): boolean => 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: unknown): x is string =>
-    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: InkSignInput,
-  signature: string,
-  keys: CandidateKey[],
-  hintKeyId?: string,
-): Promise<MultiKeyVerifyResult> {
-  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/src/crypto/sign.ts

@@ -1,155 +0,0 @@
-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: unknown): boolean {
-  let nodes = 0;
-  let chars = 0;
-  function walk(v: unknown, depth: number): boolean {
-    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 as Record<string, unknown>)) {
-      if (++nodes > MAX_MESSAGE_NODES) return false;
-      chars += key.length;
-      if (chars > MAX_MESSAGE_CHARS) return false;
-      if (!walk((v as Record<string, unknown>)[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: Record<string, unknown>,
-  privateKey: Uint8Array,
-): Promise<string> {
-  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: Record<string, unknown>,
-  publicKey: Uint8Array,
-): Promise<boolean> {
-  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: Uint8Array): string {
-  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: string): Uint8Array {
-  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));
-}