agentpassport-ts 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# agentpassport-ts — TypeScript SDK
+
+Wire-compatible TypeScript SDK for agentpassport. Same four primitives as the Python SDK — cross-language trust chains work out of the box.
+
+## Install
+
+```bash
+npm install
+```
+
+## Quickstart
+
+```typescript
+import { Agent, InMemoryRevocationRegistry, ScopeError } from "agentpassport-ts"
+
+const revocationRegistry = new InMemoryRevocationRegistry()
+const agent = new Agent("ts-agent", { privateKey, revocationRegistry })
+
+// Trust a Python orchestrator
+agent.trustKeys({ [orchestratorDid]: orchestratorPublicKey })
+
+// Declare required scope
+agent.capability("queryCustomers", { requires: ["read:db:customers"] }, async (task) => {
+  return { customers: [...] }
+})
+
+// Handle incoming task (verifies auth chain automatically)
+const result = await agent.handle(task)
+```
+
+## Primitives
+
+- **Identity** — Ed25519 keypair → `did:key:z<base58btc>` DID (same format as Python)
+- **Auth chain** — sign/verify EdDSA JWTs, `verifyAuthChain()` mirrors Python exactly
+- **TrustMiddleware** — scope declaration + enforcement, `ScopeError` on violation
+- **RevocationRegistry** — `InMemoryRevocationRegistry` interface
+
+## Wire Compatibility
+
+JWT format is identical to the Python SDK:
+- Header: `{"alg":"EdDSA","crv":"Ed25519"}`
+- Claims sorted alphabetically (matches Python's `sort_keys=True`)
+- `did:key:z<base58btc>` with `0xed01` multicodec prefix
+
+A Python orchestrator can sign a delegation JWT. A TypeScript agent can verify it independently.
+
+## Development
+
+```bash
+npm install
+npm test
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "agentpassport-ts",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for agentpassport — the AI passport layer",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,6 @@
+[project]
+name = "agentpassport-ts"
+version = "0.1.0"
+description = "TypeScript SDK for agentpassport (not a Python package — placeholder for uv workspace)"
+requires-python = ">=3.11"
+dependencies = []

package/src/agent.ts

@@ -0,0 +1,140 @@
+// agent.ts
+// Agent class with capability registration, trust middleware, and delegation
+
+import { didFromPublicKey, generateKeypair, keypairFromSeed } from "./identity.js";
+import { signDelegation } from "./jwt.js";
+import { ScopeError, TrustMiddleware } from "./trust.js";
+import type { RevocationRegistry } from "./revocation.js";
+import type { TaskEnvelope } from "./types.js";
+
+export type CapabilityHandler = (task: TaskEnvelope) => Promise<Record<string, unknown>>;
+
+export interface CapabilityOptions {
+  requires?: string[];
+}
+
+export interface DelegateOptions {
+  targetDid: string;
+  scope?: string[];
+  ttlSeconds?: number;
+}
+
+export class Agent {
+  readonly name: string;
+  readonly did: string;
+
+  private readonly _privateKey: Uint8Array;
+  private readonly _publicKey: Uint8Array;
+  private readonly _capabilities = new Map<string, CapabilityHandler>();
+  private readonly _capabilityScopes = new Map<string, string[]>();
+  private readonly _trustedKeys = new Map<string, Uint8Array>();
+  private readonly _trustMiddleware: TrustMiddleware;
+
+  constructor(
+    name: string,
+    opts: {
+      privateKey?: Uint8Array;
+      revocationRegistry?: RevocationRegistry;
+    } = {}
+  ) {
+    this.name = name;
+
+    if (opts.privateKey) {
+      this._privateKey = opts.privateKey;
+      // If 64-byte, last 32 are the public key; if 32-byte seed, derive it
+      if (opts.privateKey.length === 64) {
+        this._publicKey = opts.privateKey.slice(32);
+      } else {
+        this._publicKey = keypairFromSeed(opts.privateKey).publicKey;
+      }
+    } else {
+      const kp = generateKeypair();
+      this._privateKey = kp.privateKey;
+      this._publicKey = kp.publicKey;
+    }
+
+    this.did = didFromPublicKey(this._publicKey);
+
+    this._trustMiddleware = new TrustMiddleware(
+      this.did,
+      this._trustedKeys,
+      this._capabilityScopes,
+      opts.revocationRegistry
+    );
+  }
+
+  /**
+   * Register a capability handler.
+   *
+   * @param name     Capability name matched against task.intent.type
+   * @param options  Optional { requires: string[] } for scope enforcement
+   * @param handler  Async handler function
+   */
+  capability(
+    name: string,
+    options: CapabilityOptions,
+    handler: CapabilityHandler
+  ): this {
+    this._capabilities.set(name, handler);
+    if (options.requires && options.requires.length > 0) {
+      this._capabilityScopes.set(name, options.requires);
+    }
+    return this;
+  }
+
+  /** Register trusted issuer public keys for auth chain verification. */
+  trustKeys(keys: Map<string, Uint8Array> | Record<string, Uint8Array>): void {
+    const entries =
+      keys instanceof Map ? keys.entries() : Object.entries(keys);
+    for (const [did, pubKey] of entries) {
+      this._trustedKeys.set(did, pubKey);
+    }
+  }
+
+  /**
+   * Handle an incoming task.
+   * Runs scope check before dispatching to the capability handler.
+   * Throws ScopeError if the auth chain doesn't cover declared scope.
+   */
+  async handle(task: TaskEnvelope): Promise<Record<string, unknown>> {
+    const handler = this._capabilities.get(task.intent.type);
+    if (!handler) {
+      throw new Error(`No handler for capability: ${task.intent.type}`);
+    }
+
+    // Pre-execution scope check — throws ScopeError if violated
+    this._trustMiddleware.check(task.auth_chain, task.intent.type);
+
+    return handler(task);
+  }
+
+  /**
+   * Delegate a task to another agent by signing a new delegation JWT
+   * and appending it to the task's auth chain.
+   */
+  delegate(
+    task: TaskEnvelope,
+    opts: DelegateOptions
+  ): TaskEnvelope {
+    const token = signDelegation({
+      issuerPrivateKey: this._privateKey,
+      issuerDid: this.did,
+      subjectDid: opts.targetDid,
+      scope: opts.scope ?? ["*"],
+      ttlSeconds: opts.ttlSeconds ?? 3600,
+    });
+
+    return {
+      ...task,
+      auth_chain: [...task.auth_chain, token],
+      state: "delegated",
+    };
+  }
+
+  /** Expose this agent's public key (for use by others to trust this agent). */
+  get publicKey(): Uint8Array {
+    return this._publicKey;
+  }
+}
+
+export { ScopeError };

package/src/identity.ts

@@ -0,0 +1,123 @@
+// identity.ts
+// DID generation, Ed25519 keypair, base58btc — wire-compatible with Python SDK
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+// @noble/ed25519 v2+ requires an explicit SHA-512 implementation
+ed.etc.sha512Sync = (...m: Uint8Array[]) => sha512(...m);
+
+// Base58btc alphabet — identical to Python SDK
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+// Multicodec prefix for Ed25519 public key: varint-encoded 0xed01
+const ED25519_PREFIX = Uint8Array.from([0xed, 0x01]);
+
+// ---------------------------------------------------------------------------
+// Base58btc (pure — no external dep)
+// ---------------------------------------------------------------------------
+
+export function base58btcEncode(data: Uint8Array): string {
+  let leadingZeros = 0;
+  for (const b of data) {
+    if (b !== 0) break;
+    leadingZeros++;
+  }
+
+  let n = 0n;
+  for (const b of data) {
+    n = n * 256n + BigInt(b);
+  }
+
+  const digits: string[] = [];
+  while (n > 0n) {
+    const rem = Number(n % 58n);
+    n /= 58n;
+    digits.push(BASE58_ALPHABET[rem]);
+  }
+
+  return "1".repeat(leadingZeros) + digits.reverse().join("");
+}
+
+export function base58btcDecode(s: string): Uint8Array {
+  let leadingZeros = 0;
+  for (const c of s) {
+    if (c !== "1") break;
+    leadingZeros++;
+  }
+
+  let n = 0n;
+  for (const c of s) {
+    const idx = BASE58_ALPHABET.indexOf(c);
+    if (idx < 0) throw new Error(`Invalid base58btc character: ${c}`);
+    n = n * 58n + BigInt(idx);
+  }
+
+  const bytes: number[] = [];
+  while (n > 0n) {
+    bytes.push(Number(n % 256n));
+    n /= 256n;
+  }
+
+  const result = new Uint8Array(leadingZeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    result[leadingZeros + i] = bytes[bytes.length - 1 - i];
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Keypair
+// ---------------------------------------------------------------------------
+
+export interface Keypair {
+  /** 64-byte seed+pubkey — matches Python: bytes(sk) + bytes(sk.verify_key) */
+  privateKey: Uint8Array;
+  /** 32-byte Ed25519 public key */
+  publicKey: Uint8Array;
+}
+
+export function generateKeypair(): Keypair {
+  const seed = ed.utils.randomPrivateKey(); // 32-byte seed
+  const publicKey = ed.getPublicKey(seed);
+  // Mirror Python layout: 64 bytes = seed (32) + pubkey (32)
+  const privateKey = new Uint8Array(64);
+  privateKey.set(seed);
+  privateKey.set(publicKey, 32);
+  return { privateKey, publicKey };
+}
+
+/** Build a Keypair from a raw 32-byte seed (useful in tests). */
+export function keypairFromSeed(seed: Uint8Array): Keypair {
+  if (seed.length !== 32) throw new Error("Seed must be 32 bytes");
+  const publicKey = ed.getPublicKey(seed);
+  const privateKey = new Uint8Array(64);
+  privateKey.set(seed);
+  privateKey.set(publicKey, 32);
+  return { privateKey, publicKey };
+}
+
+// ---------------------------------------------------------------------------
+// DID
+// ---------------------------------------------------------------------------
+
+export function didFromPublicKey(publicKey: Uint8Array): string {
+  const prefixed = new Uint8Array(ED25519_PREFIX.length + publicKey.length);
+  prefixed.set(ED25519_PREFIX);
+  prefixed.set(publicKey, ED25519_PREFIX.length);
+  return `did:key:z${base58btcEncode(prefixed)}`;
+}
+
+export function parseDid(did: string): Uint8Array {
+  if (!did.startsWith("did:key:z")) {
+    throw new Error(`Invalid did:key DID (expected did:key:z...): ${did}`);
+  }
+  const encoded = did.slice(9); // strip "did:key:z"
+  const prefixed = base58btcDecode(encoded);
+  if (prefixed[0] !== 0xed || prefixed[1] !== 0x01) {
+    throw new Error(
+      `DID does not contain an Ed25519 key (expected 0xed01 multicodec prefix): ${did}`
+    );
+  }
+  return prefixed.slice(2); // strip 2-byte multicodec prefix
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// index.ts
+// Public exports for agentpassport-ts
+
+export {
+  // identity
+  generateKeypair,
+  keypairFromSeed,
+  didFromPublicKey,
+  parseDid,
+  base58btcEncode,
+  base58btcDecode,
+  type Keypair,
+} from "./identity.js";
+
+export {
+  // jwt
+  signDelegation,
+  verifyAuthChain,
+  decodeJwtClaims,
+  type DelegationClaims,
+  type SignDelegationOptions,
+  type VerifyAuthChainOptions,
+} from "./jwt.js";
+
+export {
+  // revocation
+  InMemoryRevocationRegistry,
+  type RevocationRegistry,
+} from "./revocation.js";
+
+export {
+  // trust
+  TrustMiddleware,
+  ScopeError,
+} from "./trust.js";
+
+export {
+  // agent
+  Agent,
+  type CapabilityHandler,
+  type CapabilityOptions,
+  type DelegateOptions,
+} from "./agent.js";
+
+export {
+  // types
+  createTask,
+  type TaskEnvelope,
+  type TaskState,
+  type Intent,
+  type Constraints,
+} from "./types.js";

package/src/jwt.ts

@@ -0,0 +1,197 @@
+// jwt.ts
+// EdDSA JWT sign/verify and auth-chain verification — wire-compatible with Python SDK
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { parseDid } from "./identity.js";
+import type { RevocationRegistry } from "./revocation.js";
+
+ed.etc.sha512Sync = (...m: Uint8Array[]) => sha512(...m);
+
+// ---------------------------------------------------------------------------
+// Base64url helpers (no external dep)
+// ---------------------------------------------------------------------------
+
+function b64urlEncode(data: Uint8Array): string {
+  // btoa works on binary strings
+  let binary = "";
+  for (let i = 0; i < data.length; i++) binary += String.fromCharCode(data[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlDecode(s: string): Uint8Array {
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = (4 - (padded.length % 4)) % 4;
+  const base64 = padded + "=".repeat(padding);
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+// ---------------------------------------------------------------------------
+// JWT header (constant — same as Python)
+// ---------------------------------------------------------------------------
+
+const JWT_HEADER_OBJ = { alg: "EdDSA", crv: "Ed25519" };
+const JWT_HEADER = b64urlEncode(
+  new TextEncoder().encode(JSON.stringify(JWT_HEADER_OBJ))
+);
+
+// ---------------------------------------------------------------------------
+// JWT claims types
+// ---------------------------------------------------------------------------
+
+export interface DelegationClaims {
+  iss: string;
+  sub: string;
+  iat: number;
+  exp: number;
+  jti: string;
+  scope: string[];
+  max_delegations: number;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function encodeJwt(claims: Record<string, unknown>, seed: Uint8Array): string {
+  // Sort keys — matches Python's sort_keys=True
+  const sorted = Object.fromEntries(
+    Object.keys(claims)
+      .sort()
+      .map((k) => [k, claims[k]])
+  );
+  const payload = b64urlEncode(
+    new TextEncoder().encode(JSON.stringify(sorted))
+  );
+  const signingInput = new TextEncoder().encode(`${JWT_HEADER}.${payload}`);
+  const sig = ed.sign(signingInput, seed);
+  return `${JWT_HEADER}.${payload}.${b64urlEncode(sig)}`;
+}
+
+function decodeJwtClaims(token: string): Record<string, unknown> {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error(`Malformed JWT: expected 3 parts, got ${parts.length}`);
+  return JSON.parse(new TextDecoder().decode(b64urlDecode(parts[1])));
+}
+
+function verifyJwtSignature(token: string, publicKeyBytes: Uint8Array): Record<string, unknown> {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error(`Malformed JWT: expected 3 parts, got ${parts.length}`);
+
+  const header = JSON.parse(new TextDecoder().decode(b64urlDecode(parts[0])));
+  if (header.alg !== "EdDSA") throw new Error(`Unsupported JWT algorithm: ${header.alg}`);
+
+  const signingInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+  const sig = b64urlDecode(parts[2]);
+
+  const valid = ed.verify(sig, signingInput, publicKeyBytes);
+  if (!valid) throw new Error("Invalid JWT signature");
+
+  return JSON.parse(new TextDecoder().decode(b64urlDecode(parts[1])));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SignDelegationOptions {
+  issuerPrivateKey: Uint8Array; // 64-byte (seed+pubkey) or 32-byte seed
+  issuerDid: string;
+  subjectDid: string;
+  scope: string[];
+  ttlSeconds?: number;
+  maxDelegations?: number;
+}
+
+export function signDelegation(opts: SignDelegationOptions): string {
+  const {
+    issuerPrivateKey,
+    issuerDid,
+    subjectDid,
+    scope,
+    ttlSeconds = 3600,
+    maxDelegations = 0,
+  } = opts;
+
+  const now = Math.floor(Date.now() / 1000);
+  const exp = now + ttlSeconds;
+  const jti = crypto.randomUUID();
+
+  const claims: Record<string, unknown> = {
+    iss: issuerDid,
+    sub: subjectDid,
+    iat: now,
+    exp,
+    jti,
+    scope,
+    max_delegations: maxDelegations,
+  };
+
+  // First 32 bytes are the seed — matches Python: seed = private_key[:32]
+  const seed = issuerPrivateKey.slice(0, 32);
+  return encodeJwt(claims, seed);
+}
+
+export interface VerifyAuthChainOptions {
+  chain: string[];
+  expectedSubject: string;
+  knownPublicKeys: Map<string, Uint8Array>;
+  revocationRegistry?: RevocationRegistry;
+}
+
+export function verifyAuthChain(opts: VerifyAuthChainOptions): boolean {
+  const { chain, expectedSubject, knownPublicKeys, revocationRegistry } = opts;
+
+  if (chain.length === 0) return false;
+
+  const nowTs = Date.now() / 1000;
+
+  for (const token of chain) {
+    // Decode unverified claims first to find the issuer
+    let unverified: Record<string, unknown>;
+    try {
+      unverified = decodeJwtClaims(token);
+    } catch {
+      return false;
+    }
+
+    const issuer = unverified["iss"] as string | undefined;
+    const pubKeyBytes = issuer ? knownPublicKeys.get(issuer) : undefined;
+    if (!pubKeyBytes) return false;
+
+    // Cryptographic verification
+    let claims: Record<string, unknown>;
+    try {
+      claims = verifyJwtSignature(token, pubKeyBytes);
+    } catch {
+      return false;
+    }
+
+    // Temporal validity
+    const iat = claims["iat"];
+    const exp = claims["exp"];
+    if (typeof iat !== "number" || typeof exp !== "number") return false;
+    if (iat > nowTs || nowTs > exp) return false;
+
+    // jti required
+    const jti = claims["jti"];
+    if (!jti || typeof jti !== "string") return false;
+
+    // Revocation check
+    if (revocationRegistry?.isRevoked(jti)) return false;
+  }
+
+  // Final subject check
+  try {
+    const lastClaims = decodeJwtClaims(chain[chain.length - 1]);
+    return lastClaims["sub"] === expectedSubject;
+  } catch {
+    return false;
+  }
+}
+
+/** Decode JWT claims without verifying (useful for inspection). */
+export { decodeJwtClaims };

package/src/revocation.ts

@@ -0,0 +1,19 @@
+// revocation.ts
+// RevocationRegistry interface + InMemoryRevocationRegistry
+
+export interface RevocationRegistry {
+  revoke(jti: string): void;
+  isRevoked(jti: string): boolean;
+}
+
+export class InMemoryRevocationRegistry implements RevocationRegistry {
+  private readonly _revoked = new Set<string>();
+
+  revoke(jti: string): void {
+    this._revoked.add(jti);
+  }
+
+  isRevoked(jti: string): boolean {
+    return this._revoked.has(jti);
+  }
+}