agentpassport-ts 0.1.0

package/src/trust.ts

@@ -0,0 +1,91 @@
+// trust.ts
+// TrustMiddleware and ScopeError — scope enforcement before capability dispatch
+
+import { verifyAuthChain } from "./jwt.js";
+import type { RevocationRegistry } from "./revocation.js";
+
+export class ScopeError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly required: string[],
+    public readonly granted: string[]
+  ) {
+    const missing = required.filter((s) => !granted.includes(s) && !granted.includes("*"));
+    super(
+      `Scope denied for capability "${capability}": ` +
+        `requires [${required.join(", ")}], missing [${missing.join(", ")}]`
+    );
+    this.name = "ScopeError";
+  }
+}
+
+export class TrustMiddleware {
+  constructor(
+    private readonly agentDid: string,
+    private readonly knownPublicKeys: Map<string, Uint8Array>,
+    private readonly capabilityScopes: Map<string, string[]>,
+    private readonly revocationRegistry?: RevocationRegistry
+  ) {}
+
+  /**
+   * Check that the auth chain grants the required scope for a capability.
+   *
+   * - No requires declared → always passes (backward compat)
+   * - Empty auth chain + requires declared → ScopeError
+   * - Scope matching: exact string OR "*" wildcard only
+   */
+  check(authChain: string[], capabilityName: string): void {
+    const required = this.capabilityScopes.get(capabilityName);
+    if (!required || required.length === 0) return; // no scope required
+
+    // Collect granted scopes from all tokens whose sub == agentDid
+    // and whose issuer is trusted
+    const granted = new Set<string>();
+
+    for (const token of authChain) {
+      try {
+        // Quick decode without verification to check sub
+        const parts = token.split(".");
+        if (parts.length !== 3) continue;
+        const claims = JSON.parse(
+          new TextDecoder().decode(
+            (() => {
+              const s = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+              const padding = (4 - (s.length % 4)) % 4;
+              const binary = atob(s + "=".repeat(padding));
+              const bytes = new Uint8Array(binary.length);
+              for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+              return bytes;
+            })()
+          )
+        );
+
+        if (claims.sub !== this.agentDid) continue;
+        if (!this.knownPublicKeys.has(claims.iss)) continue;
+
+        // Verify this token cryptographically
+        const valid = verifyAuthChain({
+          chain: [token],
+          expectedSubject: this.agentDid,
+          knownPublicKeys: this.knownPublicKeys,
+          revocationRegistry: this.revocationRegistry,
+        });
+
+        if (valid && Array.isArray(claims.scope)) {
+          for (const s of claims.scope) granted.add(s as string);
+        }
+      } catch {
+        // malformed token — skip
+      }
+    }
+
+    // Wildcard grants everything
+    if (granted.has("*")) return;
+
+    // Check each required scope
+    const missing = required.filter((s) => !granted.has(s));
+    if (missing.length > 0) {
+      throw new ScopeError(capabilityName, required, Array.from(granted));
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+// types.ts
+// Core agentpassport types — wire-compatible with Python SDK
+
+export type TaskState =
+  | "created"
+  | "delegated"
+  | "accepted"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export interface Intent {
+  type: string;
+  params: Record<string, unknown>;
+}
+
+export interface Constraints {
+  budget_credits: number;
+  deadline_ms?: number;
+  max_delegations: number;
+  allowed_capabilities: string[];
+  denied_capabilities: string[];
+}
+
+export interface TaskEnvelope {
+  version: "1.0";
+  id: string;
+  parent_id?: string;
+  intent: Intent;
+  constraints: Constraints;
+  /** List of EdDSA JWT strings forming the delegation chain */
+  auth_chain: string[];
+  trace_id: string;
+  state: TaskState;
+}
+
+/** Convenience factory for creating a new TaskEnvelope. */
+export function createTask(
+  intent: Intent,
+  overrides: Partial<Omit<TaskEnvelope, "version" | "intent">> = {}
+): TaskEnvelope {
+  return {
+    version: "1.0",
+    id: crypto.randomUUID(),
+    intent,
+    constraints: {
+      budget_credits: 100,
+      max_delegations: 5,
+      allowed_capabilities: [],
+      denied_capabilities: [],
+      ...overrides.constraints,
+    },
+    auth_chain: [],
+    trace_id: crypto.randomUUID(),
+    state: "created",
+    ...overrides,
+  };
+}

package/tests/agent.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from "vitest";
+import { Agent, ScopeError } from "../src/agent.js";
+import { generateKeypair, didFromPublicKey } from "../src/identity.js";
+import { signDelegation } from "../src/jwt.js";
+import { createTask } from "../src/types.js";
+
+function makeParty() {
+  const kp = generateKeypair();
+  const did = didFromPublicKey(kp.publicKey);
+  return { kp, did };
+}
+
+describe("Agent", () => {
+  it("generates a DID on construction", () => {
+    const agent = new Agent("test-agent");
+    expect(agent.did).toMatch(/^did:key:z/);
+  });
+
+  it("two agents have distinct DIDs", () => {
+    const a = new Agent("agent-a");
+    const b = new Agent("agent-b");
+    expect(a.did).not.toBe(b.did);
+  });
+
+  it("handles a task with no scope requirement", async () => {
+    const agent = new Agent("agent");
+    agent.capability("echo", {}, async (task) => ({
+      echoed: task.intent.params,
+    }));
+
+    const task = createTask({ type: "echo", params: { msg: "hello" } });
+    const result = await agent.handle(task);
+    expect(result).toEqual({ echoed: { msg: "hello" } });
+  });
+
+  it("throws for unknown capability", async () => {
+    const agent = new Agent("agent");
+    const task = createTask({ type: "unknown", params: {} });
+    await expect(agent.handle(task)).rejects.toThrow("No handler for capability: unknown");
+  });
+
+  it("passes scope check when auth chain grants required scope", async () => {
+    const issuer = makeParty();
+    const agent = new Agent("agent");
+
+    agent.trustKeys({ [issuer.did]: issuer.kp.publicKey });
+
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: agent.did,
+      scope: ["read:db:customers"],
+    });
+
+    agent.capability(
+      "queryCustomers",
+      { requires: ["read:db:customers"] },
+      async () => ({ ok: true })
+    );
+
+    const task = createTask(
+      { type: "queryCustomers", params: {} },
+      { auth_chain: [token] }
+    );
+
+    const result = await agent.handle(task);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("throws ScopeError when scope is missing", async () => {
+    const agent = new Agent("agent");
+    agent.capability(
+      "queryCustomers",
+      { requires: ["read:db:customers"] },
+      async () => ({ ok: true })
+    );
+
+    const task = createTask({ type: "queryCustomers", params: {} });
+    await expect(agent.handle(task)).rejects.toThrow(ScopeError);
+  });
+
+  it("throws ScopeError for empty auth chain with required scope", async () => {
+    const agent = new Agent("agent");
+    agent.capability(
+      "queryCustomers",
+      { requires: ["read:db:customers"] },
+      async () => ({ ok: true })
+    );
+
+    const task = createTask(
+      { type: "queryCustomers", params: {} },
+      { auth_chain: [] }
+    );
+    await expect(agent.handle(task)).rejects.toThrow(ScopeError);
+  });
+
+  it("delegate appends a JWT to the auth chain", () => {
+    const agentA = new Agent("agent-a");
+    const agentB = new Agent("agent-b");
+
+    const task = createTask({ type: "echo", params: {} });
+    expect(task.auth_chain).toHaveLength(0);
+
+    const delegated = agentA.delegate(task, { targetDid: agentB.did });
+    expect(delegated.auth_chain).toHaveLength(1);
+    expect(delegated.state).toBe("delegated");
+  });
+
+  it("delegate preserves existing auth chain entries", () => {
+    const agentA = new Agent("agent-a");
+    const agentB = new Agent("agent-b");
+    const agentC = new Agent("agent-c");
+
+    const task = createTask({ type: "echo", params: {} });
+    const step1 = agentA.delegate(task, { targetDid: agentB.did });
+    const step2 = agentB.delegate(step1, { targetDid: agentC.did });
+
+    expect(step2.auth_chain).toHaveLength(2);
+  });
+
+  it("trustKeys accepts a plain object", () => {
+    const issuer = makeParty();
+    const agent = new Agent("agent");
+    // Should not throw
+    expect(() =>
+      agent.trustKeys({ [issuer.did]: issuer.kp.publicKey })
+    ).not.toThrow();
+  });
+
+  it("trustKeys accepts a Map", () => {
+    const issuer = makeParty();
+    const agent = new Agent("agent");
+    expect(() =>
+      agent.trustKeys(new Map([[issuer.did, issuer.kp.publicKey]]))
+    ).not.toThrow();
+  });
+});

package/tests/identity.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from "vitest";
+import {
+  generateKeypair,
+  keypairFromSeed,
+  didFromPublicKey,
+  parseDid,
+  base58btcEncode,
+  base58btcDecode,
+} from "../src/identity.js";
+
+describe("base58btc", () => {
+  it("round-trips arbitrary bytes", () => {
+    const data = new Uint8Array([0x00, 0x01, 0xde, 0xad, 0xbe, 0xef]);
+    expect(base58btcDecode(base58btcEncode(data))).toEqual(data);
+  });
+
+  it("preserves leading zero bytes", () => {
+    const data = new Uint8Array([0x00, 0x00, 0x01]);
+    const encoded = base58btcEncode(data);
+    expect(encoded.startsWith("11")).toBe(true);
+    expect(base58btcDecode(encoded)).toEqual(data);
+  });
+
+  it("rejects invalid character", () => {
+    expect(() => base58btcDecode("0OIl")).toThrow("Invalid base58btc character");
+  });
+});
+
+describe("generateKeypair", () => {
+  it("returns a 64-byte privateKey and 32-byte publicKey", () => {
+    const kp = generateKeypair();
+    expect(kp.privateKey).toHaveLength(64);
+    expect(kp.publicKey).toHaveLength(32);
+  });
+
+  it("privateKey[32:64] equals publicKey", () => {
+    const kp = generateKeypair();
+    expect(kp.privateKey.slice(32)).toEqual(kp.publicKey);
+  });
+
+  it("generates distinct keypairs each call", () => {
+    const a = generateKeypair();
+    const b = generateKeypair();
+    expect(a.publicKey).not.toEqual(b.publicKey);
+  });
+});
+
+describe("keypairFromSeed", () => {
+  it("derives same keypair from same seed", () => {
+    const seed = new Uint8Array(32).fill(42);
+    const a = keypairFromSeed(seed);
+    const b = keypairFromSeed(seed);
+    expect(a.publicKey).toEqual(b.publicKey);
+  });
+
+  it("rejects seed that is not 32 bytes", () => {
+    expect(() => keypairFromSeed(new Uint8Array(16))).toThrow("Seed must be 32 bytes");
+  });
+});
+
+describe("didFromPublicKey / parseDid", () => {
+  it("produces a did:key:z... string", () => {
+    const { publicKey } = generateKeypair();
+    const did = didFromPublicKey(publicKey);
+    expect(did).toMatch(/^did:key:z[1-9A-HJ-NP-Za-km-z]+$/);
+  });
+
+  it("round-trips public key through DID", () => {
+    const { publicKey } = generateKeypair();
+    const did = didFromPublicKey(publicKey);
+    expect(parseDid(did)).toEqual(publicKey);
+  });
+
+  it("parseDid rejects non-did:key strings", () => {
+    expect(() => parseDid("did:web:example.com")).toThrow("Invalid did:key DID");
+  });
+
+  it("parseDid rejects DID with wrong multicodec prefix", () => {
+    // Manually craft a DID with wrong prefix (0x1200 instead of 0xed01)
+    const fakeKey = new Uint8Array(34);
+    fakeKey[0] = 0x12;
+    fakeKey[1] = 0x00;
+    const fakeDid = `did:key:z${base58btcEncode(fakeKey)}`;
+    expect(() => parseDid(fakeDid)).toThrow("0xed01 multicodec prefix");
+  });
+
+  it("two distinct keypairs produce distinct DIDs", () => {
+    const a = generateKeypair();
+    const b = generateKeypair();
+    expect(didFromPublicKey(a.publicKey)).not.toBe(didFromPublicKey(b.publicKey));
+  });
+});

package/tests/jwt.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect } from "vitest";
+import {
+  signDelegation,
+  verifyAuthChain,
+  decodeJwtClaims,
+} from "../src/jwt.js";
+import { generateKeypair, didFromPublicKey } from "../src/identity.js";
+import { InMemoryRevocationRegistry } from "../src/revocation.js";
+
+function makeParty() {
+  const kp = generateKeypair();
+  const did = didFromPublicKey(kp.publicKey);
+  return { kp, did };
+}
+
+describe("signDelegation", () => {
+  it("returns a 3-part JWT string", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+    });
+    expect(token.split(".")).toHaveLength(3);
+  });
+
+  it("claims contain required fields", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["write:api:stripe"],
+      maxDelegations: 2,
+    });
+    const claims = decodeJwtClaims(token);
+    expect(claims["iss"]).toBe(issuer.did);
+    expect(claims["sub"]).toBe(subject.did);
+    expect(claims["scope"]).toEqual(["write:api:stripe"]);
+    expect(claims["max_delegations"]).toBe(2);
+    expect(typeof claims["jti"]).toBe("string");
+    expect(typeof claims["iat"]).toBe("number");
+    expect(typeof claims["exp"]).toBe("number");
+  });
+
+  it("exp = iat + ttlSeconds", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["*"],
+      ttlSeconds: 7200,
+    });
+    const claims = decodeJwtClaims(token);
+    expect((claims["exp"] as number) - (claims["iat"] as number)).toBe(7200);
+  });
+});
+
+describe("verifyAuthChain", () => {
+  it("returns true for a valid single-hop chain", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+    });
+    const result = verifyAuthChain({
+      chain: [token],
+      expectedSubject: subject.did,
+      knownPublicKeys: new Map([[issuer.did, issuer.kp.publicKey]]),
+    });
+    expect(result).toBe(true);
+  });
+
+  it("returns false for empty chain", () => {
+    const subject = makeParty();
+    expect(
+      verifyAuthChain({
+        chain: [],
+        expectedSubject: subject.did,
+        knownPublicKeys: new Map(),
+      })
+    ).toBe(false);
+  });
+
+  it("returns false when subject does not match", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const other = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+    });
+    expect(
+      verifyAuthChain({
+        chain: [token],
+        expectedSubject: other.did,
+        knownPublicKeys: new Map([[issuer.did, issuer.kp.publicKey]]),
+      })
+    ).toBe(false);
+  });
+
+  it("returns false when issuer is not in known keys", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+    });
+    expect(
+      verifyAuthChain({
+        chain: [token],
+        expectedSubject: subject.did,
+        knownPublicKeys: new Map(), // issuer not trusted
+      })
+    ).toBe(false);
+  });
+
+  it("returns false when signature is tampered", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+    });
+    const parts = token.split(".");
+    // Tamper the payload
+    const tampered = `${parts[0]}.${parts[1]}AAAA.${parts[2]}`;
+    expect(
+      verifyAuthChain({
+        chain: [tampered],
+        expectedSubject: subject.did,
+        knownPublicKeys: new Map([[issuer.did, issuer.kp.publicKey]]),
+      })
+    ).toBe(false);
+  });
+
+  it("returns false for an expired token", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+      ttlSeconds: -10, // already expired
+    });
+    expect(
+      verifyAuthChain({
+        chain: [token],
+        expectedSubject: subject.did,
+        knownPublicKeys: new Map([[issuer.did, issuer.kp.publicKey]]),
+      })
+    ).toBe(false);
+  });
+
+  it("returns false when jti is revoked", () => {
+    const issuer = makeParty();
+    const subject = makeParty();
+    const token = signDelegation({
+      issuerPrivateKey: issuer.kp.privateKey,
+      issuerDid: issuer.did,
+      subjectDid: subject.did,
+      scope: ["read:db:customers"],
+    });
+    const claims = decodeJwtClaims(token);
+    const registry = new InMemoryRevocationRegistry();
+    registry.revoke(claims["jti"] as string);
+
+    expect(
+      verifyAuthChain({
+        chain: [token],
+        expectedSubject: subject.did,
+        knownPublicKeys: new Map([[issuer.did, issuer.kp.publicKey]]),
+        revocationRegistry: registry,
+      })
+    ).toBe(false);
+  });
+
+  it("verifies a two-hop chain", () => {
+    const root = makeParty();
+    const middle = makeParty();
+    const leaf = makeParty();
+
+    const hop1 = signDelegation({
+      issuerPrivateKey: root.kp.privateKey,
+      issuerDid: root.did,
+      subjectDid: middle.did,
+      scope: ["read:db:customers"],
+    });
+    const hop2 = signDelegation({
+      issuerPrivateKey: middle.kp.privateKey,
+      issuerDid: middle.did,
+      subjectDid: leaf.did,
+      scope: ["read:db:customers"],
+    });
+
+    expect(
+      verifyAuthChain({
+        chain: [hop1, hop2],
+        expectedSubject: leaf.did,
+        knownPublicKeys: new Map([
+          [root.did, root.kp.publicKey],
+          [middle.did, middle.kp.publicKey],
+        ]),
+      })
+    ).toBe(true);
+  });
+});

package/tests/revocation.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { InMemoryRevocationRegistry } from "../src/revocation.js";
+
+describe("InMemoryRevocationRegistry", () => {
+  it("isRevoked returns false for unknown jti", () => {
+    const reg = new InMemoryRevocationRegistry();
+    expect(reg.isRevoked("some-jti")).toBe(false);
+  });
+
+  it("isRevoked returns true after revoke()", () => {
+    const reg = new InMemoryRevocationRegistry();
+    reg.revoke("jti-abc");
+    expect(reg.isRevoked("jti-abc")).toBe(true);
+  });
+
+  it("revoking one jti does not affect others", () => {
+    const reg = new InMemoryRevocationRegistry();
+    reg.revoke("jti-1");
+    expect(reg.isRevoked("jti-2")).toBe(false);
+  });
+
+  it("revoking same jti twice is idempotent", () => {
+    const reg = new InMemoryRevocationRegistry();
+    reg.revoke("jti-x");
+    reg.revoke("jti-x");
+    expect(reg.isRevoked("jti-x")).toBe(true);
+  });
+
+  it("each instance has independent state", () => {
+    const a = new InMemoryRevocationRegistry();
+    const b = new InMemoryRevocationRegistry();
+    a.revoke("shared-jti");
+    expect(b.isRevoked("shared-jti")).toBe(false);
+  });
+});