agent-passport-system-mcp 3.0.0 → 3.1.1

package/README.md

@@ -12,13 +12,13 @@ Enforcement and accountability layer for AI agents. Bring your own identity. 20
 APS_PROFILE=essential npx agent-passport-system-mcp
 ```
 
-`essential` is the default profile — the 20 tools 90% of integrations need. Set `APS_PROFILE=full` for all 154 tools.
+`essential` is the default profile — the 20 tools 90% of integrations need. Set `APS_PROFILE=full` for all 150 tools.
 
 Available profiles: essential (default), identity, governance, coordination, commerce, data, gateway, comms, minimal, full.
 
 > **For AI agents:** visit [aeoess.com/llms.txt](https://aeoess.com/llms.txt) for machine-readable documentation or [llms-full.txt](https://aeoess.com/llms-full.txt) for the complete technical reference. MCP discovery: [.well-known/mcp.json](https://aeoess.com/.well-known/mcp.json).
 
-Works with any MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, and more. Full surface area under `APS_PROFILE=full`: 154 tools across 123 modules (84 core + 39 v2 constitutional governance). Independently cited by [PDR in Production (Nanook & Gerundium, UBC)](https://doi.org/10.5281/zenodo.19323172).
+Works with any MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, and more. Full surface area under `APS_PROFILE=full`: 150 tools across 127 modules (84 core + 41 v2 constitutional governance). Independently cited by [PDR in Production (Nanook & Gerundium, UBC)](https://doi.org/10.5281/zenodo.19323172).
 
 ## Quick Start
 
@@ -216,11 +216,16 @@ Layer 1 — Agent Passport Protocol (Ed25519 identity)
 
 ## Links
 
-- npm SDK: [agent-passport-system](https://www.npmjs.com/package/agent-passport-system) (v2.0.0, 2326 tests)
-- Python SDK: [agent-passport-system](https://pypi.org/project/agent-passport-system/) (v0.15.0)
-- Paper (Protocol): [doi.org/10.5281/zenodo.18749779](https://doi.org/10.5281/zenodo.18749779)
-- Paper (Faceted Narrowing): [doi.org/10.5281/zenodo.19260073](https://doi.org/10.5281/zenodo.19260073)
+- npm SDK: [agent-passport-system](https://www.npmjs.com/package/agent-passport-system) (v2.5.0-alpha, 2,479 tests)
+- Python SDK: [agent-passport-system](https://pypi.org/project/agent-passport-system/) (v2.5.0-alpha)
+- Paper (Social Contract): [doi.org/10.5281/zenodo.18749779](https://doi.org/10.5281/zenodo.18749779)
+- Paper (Monotonic Narrowing): [doi.org/10.5281/zenodo.18932404](https://doi.org/10.5281/zenodo.18932404)
+- Paper (Faceted Authority Attenuation): [doi.org/10.5281/zenodo.19260073](https://doi.org/10.5281/zenodo.19260073)
 - Paper (Behavioral Derivation Rights): [doi.org/10.5281/zenodo.19476002](https://doi.org/10.5281/zenodo.19476002)
+- Paper (Physics-Enforced Delegation): [doi.org/10.5281/zenodo.19478584](https://doi.org/10.5281/zenodo.19478584)
+- Paper (Governance in the Medium): [doi.org/10.5281/zenodo.19582550](https://doi.org/10.5281/zenodo.19582550)
+- Paper (Cognitive Attestation): [doi.org/10.5281/zenodo.19646276](https://doi.org/10.5281/zenodo.19646276)
+- IETF Internet-Draft: `draft-pidlisnyi-aps-00`
 - Docs: [aeoess.com/llms-full.txt](https://aeoess.com/llms-full.txt)
 - Agora: [aeoess.com/agora.html](https://aeoess.com/agora.html)
 

package/build/__tests__/capability-token-e2e.test.d.ts

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

package/build/__tests__/capability-token-e2e.test.js

@@ -0,0 +1,381 @@
+// End-to-end test for the v0.1 capability-token reference implementation.
+// Spec: agent-passport-system/docs/CAPABILITY-TOKEN-SPEC-DRAFT.md
+//
+// Demonstrates the closure property: any party holding (M1, M3, M4) can
+// reconstruct the attestation chain with all four signatures verifying.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPair, sign } from "agent-passport-system";
+import { issueSinkChallenge, buildEvaluationRequest, mintChallengeReceipt, signEffectReceipt, challengeHash, challengeReceiptHash, deriveDelegationChainRoot, InMemoryNullifierSet, verifySinkChallenge, verifyAuthorityEvaluationRequest, verifyChallengeReceipt, verifyEffectReceipt, reconstructAttestationChain, canonicalWithoutSignature, } from "../capabilityToken/index.js";
+// Local helper: every actor needs an Ed25519 key pair.
+function newActorKey() {
+    const k = generateKeyPair();
+    return { publicKey: k.publicKey, privateKey: k.privateKey };
+}
+function setupActors() {
+    return {
+        delegator: newActorKey(),
+        subject: newActorKey(),
+        sink: newActorKey(),
+        gateway: newActorKey(),
+    };
+}
+// Minimal valid action shape for fixture flows.
+function sampleAction() {
+    return {
+        kind: "fs.write",
+        target: "file:///tmp/aps-capability-test.txt",
+        parameters: { content_length: 42 },
+        resource_version: "v3-2026-04-22",
+    };
+}
+// In v0.1 the delegation envelope is opaque to this protocol — the SDK's v2.x
+// chain composes by reference. The reference impl commits to a JCS hash of
+// the chain. For test fixtures a stub envelope is sufficient.
+function sampleDelegationChain(actors) {
+    return [
+        {
+            issuer: actors.delegator.publicKey,
+            subject: actors.subject.publicKey,
+            scope: ["fs.write"],
+            issued_at: "2026-04-22T00:00:00Z",
+            not_after: "2026-04-29T00:00:00Z",
+            authority_token_merkle_root: "stub-root-for-v0.1",
+        },
+    ];
+}
+function sampleAuthorityToken() {
+    return {
+        token_preimage: Buffer.from("preimage-001-".padEnd(32, "x")).toString("base64url"),
+        merkle_proof: ["sibling-1", "sibling-2"],
+        scope_class: "fs.write",
+    };
+}
+function sampleFreshnessBeacon(actors) {
+    const ts = "2026-04-22T00:00:01Z";
+    // Minimal beacon: signed timestamp from the delegator. Full spec requires
+    // a richer payload; this is sufficient to exercise the flow.
+    const beaconSig = sign(`beacon:${ts}`, actors.delegator.privateKey);
+    return {
+        delegator_id: actors.delegator.publicKey,
+        beacon_timestamp: ts,
+        beacon_signature: beaconSig,
+    };
+}
+// Drives the full M1→M2→M3→M4 cycle. Returns every artifact so individual
+// tests can assert on whichever step they care about.
+function runFullCycle(actors, nullifiers) {
+    // M1: sink issues a challenge.
+    const challenge = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+    });
+    // M2: subject builds an authority-evaluation request.
+    const chain = sampleDelegationChain(actors);
+    const request = buildEvaluationRequest({
+        challenge,
+        delegation_chain: chain,
+        authority_token: sampleAuthorityToken(),
+        freshness_beacon: sampleFreshnessBeacon(actors),
+        subject_key: actors.subject,
+    });
+    // M3: gateway mints a permit ChallengeReceipt over the sink's exact
+    // challenge_hash and the subject's exact delegation_chain_root.
+    const receipt = mintChallengeReceipt({
+        request,
+        decision: "permit",
+        policy_digest: "policy-bundle-sha256-v0.1-fixture",
+        gateway_key: actors.gateway,
+    });
+    // Sink-side: verify M3 binds to the M1 the sink issued, then check the
+    // nullifier set, then consume the token.
+    const m3Verify = verifyChallengeReceipt({
+        receipt,
+        expected_challenge: challenge,
+        expected_delegation_chain_root: request.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(m3Verify.ok, true, "sink must accept M3");
+    assert.equal(nullifiers.isConsumed(receipt.authority_token_preimage), false);
+    nullifiers.consume(receipt.authority_token_preimage);
+    // M4: sink signs an effect receipt.
+    const effectReceipt = signEffectReceipt({
+        challenge_receipt: receipt,
+        effect: {
+            executed_at: "2026-04-22T00:00:02Z",
+            outcome: "success",
+            result_digest: "sha256-of-effect-result",
+        },
+        sink_key: actors.sink,
+    });
+    return { challenge, request, receipt, effectReceipt, chain };
+}
+test("M1: sink-issued challenge has a valid sink signature", () => {
+    const actors = setupActors();
+    const challenge = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+    });
+    assert.equal(challenge.type, "aps.capability.v1.SinkChallenge");
+    assert.equal(challenge.sink_id, actors.sink.publicKey);
+    assert.ok(challenge.sink_signature.length > 0, "signature populated");
+    const result = verifySinkChallenge(challenge, actors.sink.publicKey);
+    assert.equal(result.ok, true);
+    assert.equal(challengeHash(challenge).length, 64, "SHA-256 hex");
+});
+test("M2: subject-signed evaluation request verifies and carries M1 verbatim", () => {
+    const actors = setupActors();
+    const challenge = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+    });
+    const chain = sampleDelegationChain(actors);
+    const request = buildEvaluationRequest({
+        challenge,
+        delegation_chain: chain,
+        authority_token: sampleAuthorityToken(),
+        freshness_beacon: sampleFreshnessBeacon(actors),
+        subject_key: actors.subject,
+    });
+    assert.equal(request.delegation_depth, 1);
+    assert.equal(request.delegation_chain_root, deriveDelegationChainRoot(chain));
+    const result = verifyAuthorityEvaluationRequest(request, actors.subject.publicKey, actors.sink.publicKey);
+    assert.equal(result.ok, true);
+});
+test("M3: gateway permit binds challenge_hash + delegation_chain_root", () => {
+    const actors = setupActors();
+    const challenge = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+    });
+    const request = buildEvaluationRequest({
+        challenge,
+        delegation_chain: sampleDelegationChain(actors),
+        authority_token: sampleAuthorityToken(),
+        freshness_beacon: sampleFreshnessBeacon(actors),
+        subject_key: actors.subject,
+    });
+    const receipt = mintChallengeReceipt({
+        request,
+        decision: "permit",
+        policy_digest: "p-digest",
+        gateway_key: actors.gateway,
+    });
+    assert.equal(receipt.challenge_hash, challengeHash(challenge));
+    assert.equal(receipt.delegation_chain_root, request.delegation_chain_root);
+    assert.equal(receipt.epistemic_claims.policy_evaluated, "closed");
+    assert.equal(receipt.epistemic_claims.effect_occurred, "unresolved");
+    const result = verifyChallengeReceipt({
+        receipt,
+        expected_challenge: challenge,
+        expected_delegation_chain_root: request.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(result.ok, true);
+});
+test("E2E: full four-message cycle — every signature verifies, attestation chain reconstructs", () => {
+    const actors = setupActors();
+    const nullifiers = new InMemoryNullifierSet();
+    const { challenge, request, receipt, effectReceipt } = runFullCycle(actors, nullifiers);
+    // Each individual signature verifies against the right key.
+    assert.equal(verifySinkChallenge(challenge, actors.sink.publicKey).ok, true);
+    assert.equal(verifyAuthorityEvaluationRequest(request, actors.subject.publicKey, actors.sink.publicKey).ok, true);
+    assert.equal(verifyChallengeReceipt({
+        receipt,
+        expected_challenge: challenge,
+        expected_delegation_chain_root: request.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    }).ok, true);
+    assert.equal(verifyEffectReceipt({
+        receipt: effectReceipt,
+        challenge_receipt: receipt,
+        sink_public_key: actors.sink.publicKey,
+    }).ok, true);
+    // M4 binds back to M3 by gateway_receipt_hash.
+    assert.equal(effectReceipt.gateway_receipt_hash, challengeReceiptHash(receipt));
+    assert.equal(effectReceipt.epistemic_claims.effect_occurred, "closed");
+    assert.equal(effectReceipt.epistemic_claims.policy_evaluation_correct, "witnessed");
+    // Closure: a verifier holding M1, M3, M4 (no M2 needed) can reconstruct the
+    // chain. This is the spec's "(SinkChallenge, ChallengeReceipt, EffectReceipt)
+    // is the full attestation record" claim made executable.
+    const reconstructed = reconstructAttestationChain({
+        challenge,
+        receipt,
+        effect: effectReceipt,
+        sink_public_key: actors.sink.publicKey,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(reconstructed.ok, true, "attestation chain must reconstruct");
+    // Nullifier set consumed exactly one preimage.
+    assert.equal(nullifiers.size(), 1);
+});
+// ─── Negative tests ───────────────────────────────────────────────────────
+// Each models an adversarial gateway, a replay attempt, or an attempt to
+// bypass delegation-chain validation. The protocol's closure property means
+// each MUST be detected by the sink-side or any independent verifier.
+test("NEGATIVE: gateway substitutes a different challenge_hash — sink rejects M3", () => {
+    const actors = setupActors();
+    const challenge = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+    });
+    const request = buildEvaluationRequest({
+        challenge,
+        delegation_chain: sampleDelegationChain(actors),
+        authority_token: sampleAuthorityToken(),
+        freshness_beacon: sampleFreshnessBeacon(actors),
+        subject_key: actors.subject,
+    });
+    // Adversarial gateway swaps the challenge_hash to one of its own choosing.
+    const forgedReceipt = mintChallengeReceipt({
+        request,
+        decision: "permit",
+        policy_digest: "p-digest",
+        gateway_key: actors.gateway,
+        override_challenge_hash: "0".repeat(64),
+    });
+    // Gateway signature itself still verifies (gateway holds its own key).
+    // What MUST fail: the binding check between challenge_hash and the M1 the
+    // sink actually issued.
+    const result = verifyChallengeReceipt({
+        receipt: forgedReceipt,
+        expected_challenge: challenge,
+        expected_delegation_chain_root: request.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+        assert.match(result.reason, /challenge_hash does not match/);
+    }
+});
+test("NEGATIVE: subject reuses authority_token_preimage — nullifier set rejects replay", () => {
+    const actors = setupActors();
+    const nullifiers = new InMemoryNullifierSet();
+    // First cycle succeeds.
+    const first = runFullCycle(actors, nullifiers);
+    assert.ok(first.effectReceipt.sink_signature.length > 0);
+    // Second cycle: same actors, same authority_token_preimage. Even if the
+    // gateway re-mints a fresh M3 (different challenge, different evaluated_at),
+    // the sink's nullifier set MUST refuse the second consumption attempt.
+    const challenge2 = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: { ...sampleAction(), parameters: { content_length: 100 } },
+        sink_key: actors.sink,
+    });
+    const request2 = buildEvaluationRequest({
+        challenge: challenge2,
+        delegation_chain: sampleDelegationChain(actors),
+        authority_token: sampleAuthorityToken(), // same preimage as cycle #1
+        freshness_beacon: sampleFreshnessBeacon(actors),
+        subject_key: actors.subject,
+    });
+    const receipt2 = mintChallengeReceipt({
+        request: request2,
+        decision: "permit",
+        policy_digest: "p-digest",
+        gateway_key: actors.gateway,
+    });
+    // Sink-side verification of M3 still passes (it's a fresh sink-authored
+    // challenge with a valid gateway signature). The replay defense is
+    // structurally separate: it lives in the nullifier set.
+    const m3v = verifyChallengeReceipt({
+        receipt: receipt2,
+        expected_challenge: challenge2,
+        expected_delegation_chain_root: request2.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(m3v.ok, true);
+    // Replay attempt MUST throw at consume(). This is what stops the gateway
+    // from batch-consuming a leaked token.
+    assert.throws(() => nullifiers.consume(receipt2.authority_token_preimage), /nullifier replay/);
+});
+test("NEGATIVE: gateway omits or forges delegation_chain_root — verifier detects missing/invalid", () => {
+    const actors = setupActors();
+    const challenge = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+    });
+    const request = buildEvaluationRequest({
+        challenge,
+        delegation_chain: sampleDelegationChain(actors),
+        authority_token: sampleAuthorityToken(),
+        freshness_beacon: sampleFreshnessBeacon(actors),
+        subject_key: actors.subject,
+    });
+    // Variant A: gateway omits the delegation_chain_root entirely (skipped
+    // chain validation). Verifier MUST detect.
+    const omittedRoot = mintChallengeReceipt({
+        request,
+        decision: "permit",
+        policy_digest: "p-digest",
+        gateway_key: actors.gateway,
+        omit_delegation_chain_root: true,
+    });
+    const omittedResult = verifyChallengeReceipt({
+        receipt: omittedRoot,
+        expected_challenge: challenge,
+        expected_delegation_chain_root: request.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(omittedResult.ok, false);
+    if (!omittedResult.ok) {
+        assert.match(omittedResult.reason, /delegation_chain_root/);
+    }
+    // Variant B: gateway forges a different chain root than the subject
+    // committed to (e.g. trying to attest to a broader scope class).
+    const forgedRoot = mintChallengeReceipt({
+        request,
+        decision: "permit",
+        policy_digest: "p-digest",
+        gateway_key: actors.gateway,
+        override_delegation_chain_root: "deadbeef".repeat(8),
+    });
+    const forgedResult = verifyChallengeReceipt({
+        receipt: forgedRoot,
+        expected_challenge: challenge,
+        expected_delegation_chain_root: request.delegation_chain_root,
+        gateway_public_key: actors.gateway.publicKey,
+    });
+    assert.equal(forgedResult.ok, false);
+    if (!forgedResult.ok) {
+        assert.match(forgedResult.reason, /delegation_chain_root/);
+    }
+});
+test("Hash stability: re-issuing M1 with the same nonce + clock yields the same challenge_hash", () => {
+    const actors = setupActors();
+    const fixedNow = new Date("2026-04-22T12:00:00Z");
+    const fixedNonce = "deterministic-nonce-for-fixture-vector".padEnd(43, "x").slice(0, 43);
+    const a = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+        now: fixedNow,
+        nonce: fixedNonce,
+    });
+    const b = issueSinkChallenge({
+        sink_id: actors.sink.publicKey,
+        subject_id: actors.subject.publicKey,
+        action: sampleAction(),
+        sink_key: actors.sink,
+        now: fixedNow,
+        nonce: fixedNonce,
+    });
+    // Canonical JCS payload is identical → challenge_hash matches. Signatures
+    // also match because Ed25519 over identical input is deterministic.
+    assert.equal(challengeHash(a), challengeHash(b));
+    assert.equal(canonicalWithoutSignature(a, "sink_signature"), canonicalWithoutSignature(b, "sink_signature"));
+});

package/build/capabilityToken/authorityEvaluation.d.ts

@@ -0,0 +1,11 @@
+import type { AuthorityEvaluationRequest, AuthorityTokenReveal, DelegationEnvelope, FreshnessBeacon, KeyPair, SinkChallenge } from "./types.js";
+export interface BuildEvaluationRequestOptions {
+    challenge: SinkChallenge;
+    delegation_chain: DelegationEnvelope[];
+    authority_token: AuthorityTokenReveal;
+    freshness_beacon: FreshnessBeacon;
+    subject_key: KeyPair;
+    delegation_chain_root?: string;
+}
+export declare function buildEvaluationRequest(opts: BuildEvaluationRequestOptions): AuthorityEvaluationRequest;
+export declare function deriveDelegationChainRoot(chain: DelegationEnvelope[]): string;

package/build/capabilityToken/authorityEvaluation.js

@@ -0,0 +1,24 @@
+// M2: Subject builds an AuthorityEvaluationRequest carrying the sink challenge,
+// the delegation chain, and one revealed authority-token preimage.
+import { canonicalizeJCS, sign } from "agent-passport-system";
+import { canonicalWithoutSignature, sha256Hex } from "./canonical.js";
+export function buildEvaluationRequest(opts) {
+    const root = opts.delegation_chain_root ?? deriveDelegationChainRoot(opts.delegation_chain);
+    const unsigned = {
+        type: "aps.capability.v1.AuthorityEvaluationRequest",
+        challenge: opts.challenge,
+        delegation_chain: opts.delegation_chain,
+        delegation_chain_root: root,
+        delegation_depth: opts.delegation_chain.length,
+        authority_token: opts.authority_token,
+        freshness_beacon: opts.freshness_beacon,
+    };
+    const signature = sign(canonicalWithoutSignature({ ...unsigned, subject_signature: "" }, "subject_signature"), opts.subject_key.privateKey);
+    return { ...unsigned, subject_signature: signature };
+}
+// SHA-256 over the canonical serialization of the chain. v0.1: simple flat
+// commitment, sufficient to demonstrate the closure property. The wire
+// format reserves room for a richer Merkle tree in v0.2.
+export function deriveDelegationChainRoot(chain) {
+    return sha256Hex(canonicalizeJCS(chain));
+}

package/build/capabilityToken/canonical.d.ts

@@ -0,0 +1,6 @@
+declare const SIGNATURE_FIELDS: readonly ["sink_signature", "subject_signature", "gateway_signature"];
+type SignatureField = (typeof SIGNATURE_FIELDS)[number];
+export declare function canonicalWithoutSignature(obj: object, signatureField: SignatureField): string;
+export declare function sha256Hex(input: string): string;
+export declare function sha256Base64Url(input: string): string;
+export {};

package/build/capabilityToken/canonical.js

@@ -0,0 +1,19 @@
+// Helpers for canonical serialization + hashing of v0.1 capability-token
+// messages. JCS (RFC 8785) canonicalization is delegated to the SDK.
+import { canonicalizeJCS } from "agent-passport-system";
+import { createHash } from "node:crypto";
+const SIGNATURE_FIELDS = [
+    "sink_signature",
+    "subject_signature",
+    "gateway_signature",
+];
+export function canonicalWithoutSignature(obj, signatureField) {
+    const { [signatureField]: _omit, ...rest } = obj;
+    return canonicalizeJCS(rest);
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+export function sha256Base64Url(input) {
+    return createHash("sha256").update(input).digest("base64url");
+}

package/build/capabilityToken/challengeReceipt.d.ts

@@ -0,0 +1,15 @@
+import type { AuthorityEvaluationRequest, ChallengeReceipt, ChallengeReceiptEpistemicClaims, Decision, KeyPair } from "./types.js";
+export interface MintChallengeReceiptOptions {
+    request: AuthorityEvaluationRequest;
+    decision: Decision;
+    deny_reason?: string;
+    policy_digest: string;
+    gateway_key: KeyPair;
+    epistemic_claims?: ChallengeReceiptEpistemicClaims;
+    now?: Date;
+    override_challenge_hash?: string;
+    override_delegation_chain_root?: string;
+    omit_delegation_chain_root?: boolean;
+}
+export declare function mintChallengeReceipt(opts: MintChallengeReceiptOptions): ChallengeReceipt;
+export declare function challengeReceiptHash(receipt: ChallengeReceipt): string;

package/build/capabilityToken/challengeReceipt.js

@@ -0,0 +1,48 @@
+// M3: Gateway mints a ChallengeReceipt over the sink-authored challenge.
+// The gateway's signature binds to the canonical challenge_hash; it cannot
+// describe a different action without producing a hash the sink will refuse.
+import { sign } from "agent-passport-system";
+import { canonicalWithoutSignature, sha256Hex } from "./canonical.js";
+import { challengeHash } from "./sinkChallenge.js";
+const CLOSED_PERMIT_CLAIMS = {
+    policy_evaluated: "closed",
+    authority_consumed: "closed",
+    scope_within_bounds: "closed",
+    effect_occurred: "unresolved",
+};
+const CLOSED_DENY_CLAIMS = {
+    policy_evaluated: "closed",
+    authority_consumed: "closed",
+    scope_within_bounds: "closed",
+    effect_occurred: "unresolved",
+};
+export function mintChallengeReceipt(opts) {
+    const cHash = opts.override_challenge_hash ?? challengeHash(opts.request.challenge);
+    const claims = opts.epistemic_claims ??
+        (opts.decision === "permit" ? CLOSED_PERMIT_CLAIMS : CLOSED_DENY_CLAIMS);
+    const evaluatedAt = (opts.now ?? new Date()).toISOString();
+    const chainRoot = opts.omit_delegation_chain_root
+        ? ""
+        : opts.override_delegation_chain_root ?? opts.request.delegation_chain_root;
+    const unsigned = {
+        type: "aps.capability.v1.ChallengeReceipt",
+        challenge_hash: cHash,
+        decision: opts.decision,
+        ...(opts.decision === "deny" && opts.deny_reason
+            ? { deny_reason: opts.deny_reason }
+            : {}),
+        delegation_chain_root: chainRoot,
+        delegation_depth: opts.request.delegation_depth,
+        ...(opts.decision === "permit"
+            ? { authority_token_preimage: opts.request.authority_token.token_preimage }
+            : {}),
+        evaluated_at: evaluatedAt,
+        policy_digest: opts.policy_digest,
+        epistemic_claims: claims,
+    };
+    const signature = sign(canonicalWithoutSignature({ ...unsigned, gateway_signature: "" }, "gateway_signature"), opts.gateway_key.privateKey);
+    return { ...unsigned, gateway_signature: signature };
+}
+export function challengeReceiptHash(receipt) {
+    return sha256Hex(canonicalWithoutSignature(receipt, "gateway_signature"));
+}

package/build/capabilityToken/effectReceipt.d.ts

@@ -0,0 +1,8 @@
+import type { ChallengeReceipt, EffectReceipt, EffectReceiptEpistemicClaims, KeyPair, SinkEffect } from "./types.js";
+export interface SignEffectReceiptOptions {
+    challenge_receipt: ChallengeReceipt;
+    effect: SinkEffect;
+    sink_key: KeyPair;
+    epistemic_claims?: EffectReceiptEpistemicClaims;
+}
+export declare function signEffectReceipt(opts: SignEffectReceiptOptions): EffectReceipt;

package/build/capabilityToken/effectReceipt.js

@@ -0,0 +1,29 @@
+// M4: After execution, the sink signs an EffectReceipt that binds the
+// consumed authority token to the actual effect.
+import { sign } from "agent-passport-system";
+import { canonicalWithoutSignature } from "./canonical.js";
+import { challengeReceiptHash } from "./challengeReceipt.js";
+const DEFAULT_CLAIMS = {
+    effect_occurred: "closed",
+    effect_result_bound: "closed",
+    policy_evaluation_correct: "witnessed",
+};
+export function signEffectReceipt(opts) {
+    if (opts.challenge_receipt.decision !== "permit") {
+        throw new Error("EffectReceipt requires a permit ChallengeReceipt");
+    }
+    const preimage = opts.challenge_receipt.authority_token_preimage;
+    if (!preimage) {
+        throw new Error("ChallengeReceipt is missing authority_token_preimage");
+    }
+    const unsigned = {
+        type: "aps.capability.v1.EffectReceipt",
+        challenge_hash: opts.challenge_receipt.challenge_hash,
+        authority_token_preimage: preimage,
+        gateway_receipt_hash: challengeReceiptHash(opts.challenge_receipt),
+        effect: opts.effect,
+        epistemic_claims: opts.epistemic_claims ?? DEFAULT_CLAIMS,
+    };
+    const signature = sign(canonicalWithoutSignature({ ...unsigned, sink_signature: "" }, "sink_signature"), opts.sink_key.privateKey);
+    return { ...unsigned, sink_signature: signature };
+}

package/build/capabilityToken/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export { canonicalWithoutSignature, sha256Hex, sha256Base64Url } from "./canonical.js";
+export { issueSinkChallenge, challengeHash } from "./sinkChallenge.js";
+export { buildEvaluationRequest, deriveDelegationChainRoot, } from "./authorityEvaluation.js";
+export { mintChallengeReceipt, challengeReceiptHash } from "./challengeReceipt.js";
+export { signEffectReceipt } from "./effectReceipt.js";
+export { InMemoryNullifierSet } from "./nullifierSet.js";
+export type { NullifierStore } from "./nullifierSet.js";
+export { verifySinkChallenge, verifyAuthorityEvaluationRequest, verifyChallengeReceipt, verifyEffectReceipt, reconstructAttestationChain, } from "./verify.js";
+export type { VerifyResult } from "./verify.js";

package/build/capabilityToken/index.js

@@ -0,0 +1,10 @@
+// Public surface for the v0.1 capability-token reference implementation.
+// Spec: agent-passport-system/docs/CAPABILITY-TOKEN-SPEC-DRAFT.md
+export * from "./types.js";
+export { canonicalWithoutSignature, sha256Hex, sha256Base64Url } from "./canonical.js";
+export { issueSinkChallenge, challengeHash } from "./sinkChallenge.js";
+export { buildEvaluationRequest, deriveDelegationChainRoot, } from "./authorityEvaluation.js";
+export { mintChallengeReceipt, challengeReceiptHash } from "./challengeReceipt.js";
+export { signEffectReceipt } from "./effectReceipt.js";
+export { InMemoryNullifierSet } from "./nullifierSet.js";
+export { verifySinkChallenge, verifyAuthorityEvaluationRequest, verifyChallengeReceipt, verifyEffectReceipt, reconstructAttestationChain, } from "./verify.js";

package/build/capabilityToken/nullifierSet.d.ts

@@ -0,0 +1,13 @@
+export interface NullifierStore {
+    isConsumed(preimage: string): boolean;
+    consume(preimage: string): void;
+    size(): number;
+    clear(): void;
+}
+export declare class InMemoryNullifierSet implements NullifierStore {
+    private readonly seen;
+    isConsumed(preimage: string): boolean;
+    consume(preimage: string): void;
+    size(): number;
+    clear(): void;
+}

package/build/capabilityToken/nullifierSet.js

@@ -0,0 +1,20 @@
+// In-memory nullifier set. v0.1: process-local Set, no persistence. The
+// sink consults this on every M3 redemption to prevent token replay.
+export class InMemoryNullifierSet {
+    seen = new Set();
+    isConsumed(preimage) {
+        return this.seen.has(preimage);
+    }
+    consume(preimage) {
+        if (this.seen.has(preimage)) {
+            throw new Error(`nullifier replay: token preimage ${preimage.slice(0, 12)}... already consumed`);
+        }
+        this.seen.add(preimage);
+    }
+    size() {
+        return this.seen.size;
+    }
+    clear() {
+        this.seen.clear();
+    }
+}

package/build/capabilityToken/sinkChallenge.d.ts

@@ -0,0 +1,13 @@
+import type { KeyPair, PolicyFreshnessRequirement, SinkAction, SinkChallenge } from "./types.js";
+export interface IssueSinkChallengeOptions {
+    sink_id: string;
+    subject_id: string;
+    action: SinkAction;
+    validity_seconds?: number;
+    required_policy_freshness?: PolicyFreshnessRequirement;
+    sink_key: KeyPair;
+    now?: Date;
+    nonce?: string;
+}
+export declare function issueSinkChallenge(opts: IssueSinkChallengeOptions): SinkChallenge;
+export declare function challengeHash(challenge: SinkChallenge): string;

package/build/capabilityToken/sinkChallenge.js

@@ -0,0 +1,30 @@
+// M1: SinkChallenge issuance and challenge-hash computation.
+import { randomBytes } from "node:crypto";
+import { sign } from "agent-passport-system";
+import { canonicalWithoutSignature, sha256Hex } from "./canonical.js";
+const DEFAULT_VALIDITY_SECONDS = 60;
+const DEFAULT_FRESHNESS = {
+    max_age_seconds: 30,
+    beacon_hash_required: true,
+};
+export function issueSinkChallenge(opts) {
+    const issued = opts.now ?? new Date();
+    const validity = opts.validity_seconds ?? DEFAULT_VALIDITY_SECONDS;
+    const expires = new Date(issued.getTime() + validity * 1000);
+    const nonce = opts.nonce ?? randomBytes(32).toString("base64url");
+    const unsigned = {
+        type: "aps.capability.v1.SinkChallenge",
+        sink_id: opts.sink_id,
+        subject_id: opts.subject_id,
+        action: opts.action,
+        nonce,
+        issued_at: issued.toISOString(),
+        expires_at: expires.toISOString(),
+        required_policy_freshness: opts.required_policy_freshness ?? DEFAULT_FRESHNESS,
+    };
+    const signature = sign(canonicalWithoutSignature({ ...unsigned, sink_signature: "" }, "sink_signature"), opts.sink_key.privateKey);
+    return { ...unsigned, sink_signature: signature };
+}
+export function challengeHash(challenge) {
+    return sha256Hex(canonicalWithoutSignature(challenge, "sink_signature"));
+}

package/build/capabilityToken/types.d.ts

@@ -0,0 +1,89 @@
+export type EpistemicType = "closed" | "witnessed" | "unresolved" | "self-asserted" | "witnessed-by-subject" | "corroborated";
+export interface SinkAction {
+    kind: string;
+    target: string;
+    parameters: Record<string, unknown>;
+    resource_version: string;
+}
+export interface PolicyFreshnessRequirement {
+    max_age_seconds: number;
+    beacon_hash_required: boolean;
+}
+export interface SinkChallenge {
+    type: "aps.capability.v1.SinkChallenge";
+    sink_id: string;
+    subject_id: string;
+    action: SinkAction;
+    nonce: string;
+    issued_at: string;
+    expires_at: string;
+    required_policy_freshness: PolicyFreshnessRequirement;
+    sink_signature: string;
+}
+export interface DelegationEnvelope {
+    [key: string]: unknown;
+}
+export interface AuthorityTokenReveal {
+    token_preimage: string;
+    merkle_proof: string[];
+    scope_class: string;
+}
+export interface FreshnessBeacon {
+    delegator_id: string;
+    beacon_timestamp: string;
+    beacon_signature: string;
+}
+export interface AuthorityEvaluationRequest {
+    type: "aps.capability.v1.AuthorityEvaluationRequest";
+    challenge: SinkChallenge;
+    delegation_chain: DelegationEnvelope[];
+    delegation_chain_root: string;
+    delegation_depth: number;
+    authority_token: AuthorityTokenReveal;
+    freshness_beacon: FreshnessBeacon;
+    subject_signature: string;
+}
+export type Decision = "permit" | "deny";
+export interface ChallengeReceiptEpistemicClaims {
+    policy_evaluated: EpistemicType;
+    authority_consumed: EpistemicType;
+    scope_within_bounds: EpistemicType;
+    effect_occurred: EpistemicType;
+}
+export interface ChallengeReceipt {
+    type: "aps.capability.v1.ChallengeReceipt";
+    challenge_hash: string;
+    decision: Decision;
+    deny_reason?: string;
+    delegation_chain_root: string;
+    delegation_depth: number;
+    authority_token_preimage?: string;
+    evaluated_at: string;
+    policy_digest: string;
+    epistemic_claims: ChallengeReceiptEpistemicClaims;
+    gateway_signature: string;
+}
+export type EffectOutcome = "success" | "failure" | "partial";
+export interface SinkEffect {
+    executed_at: string;
+    outcome: EffectOutcome;
+    result_digest: string;
+}
+export interface EffectReceiptEpistemicClaims {
+    effect_occurred: EpistemicType;
+    effect_result_bound: EpistemicType;
+    policy_evaluation_correct: EpistemicType;
+}
+export interface EffectReceipt {
+    type: "aps.capability.v1.EffectReceipt";
+    challenge_hash: string;
+    authority_token_preimage: string;
+    gateway_receipt_hash: string;
+    effect: SinkEffect;
+    epistemic_claims: EffectReceiptEpistemicClaims;
+    sink_signature: string;
+}
+export interface KeyPair {
+    publicKey: string;
+    privateKey: string;
+}

package/build/capabilityToken/types.js

@@ -0,0 +1,3 @@
+// Wire-format types for the v0.1 capability-token protocol.
+// Source of truth: agent-passport-system/docs/CAPABILITY-TOKEN-SPEC-DRAFT.md
+export {};

package/build/capabilityToken/verify.d.ts

@@ -0,0 +1,30 @@
+import type { AuthorityEvaluationRequest, ChallengeReceipt, EffectReceipt, SinkChallenge } from "./types.js";
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function verifySinkChallenge(challenge: SinkChallenge, sinkPublicKey: string): VerifyResult;
+export declare function verifyAuthorityEvaluationRequest(request: AuthorityEvaluationRequest, subjectPublicKey: string, sinkPublicKey: string): VerifyResult;
+export interface VerifyChallengeReceiptOptions {
+    receipt: ChallengeReceipt;
+    expected_challenge: SinkChallenge;
+    expected_delegation_chain_root: string;
+    gateway_public_key: string;
+}
+export declare function verifyChallengeReceipt(opts: VerifyChallengeReceiptOptions): VerifyResult;
+export interface VerifyEffectReceiptOptions {
+    receipt: EffectReceipt;
+    challenge_receipt: ChallengeReceipt;
+    sink_public_key: string;
+}
+export declare function verifyEffectReceipt(opts: VerifyEffectReceiptOptions): VerifyResult;
+export interface ReconstructAttestationOptions {
+    challenge: SinkChallenge;
+    receipt: ChallengeReceipt;
+    effect: EffectReceipt;
+    sink_public_key: string;
+    gateway_public_key: string;
+}
+export declare function reconstructAttestationChain(opts: ReconstructAttestationOptions): VerifyResult;

package/build/capabilityToken/verify.js

@@ -0,0 +1,85 @@
+// Signature + binding verification for the four message types.
+// Verifiers are pure: they take messages and public keys, return either
+// {ok: true} or {ok: false, reason}.
+import { verify } from "agent-passport-system";
+import { canonicalWithoutSignature } from "./canonical.js";
+import { challengeHash } from "./sinkChallenge.js";
+import { challengeReceiptHash } from "./challengeReceipt.js";
+export function verifySinkChallenge(challenge, sinkPublicKey) {
+    const payload = canonicalWithoutSignature(challenge, "sink_signature");
+    return verify(payload, challenge.sink_signature, sinkPublicKey)
+        ? { ok: true }
+        : { ok: false, reason: "sink_signature invalid" };
+}
+export function verifyAuthorityEvaluationRequest(request, subjectPublicKey, sinkPublicKey) {
+    const payload = canonicalWithoutSignature(request, "subject_signature");
+    if (!verify(payload, request.subject_signature, subjectPublicKey)) {
+        return { ok: false, reason: "subject_signature invalid" };
+    }
+    return verifySinkChallenge(request.challenge, sinkPublicKey);
+}
+export function verifyChallengeReceipt(opts) {
+    const payload = canonicalWithoutSignature(opts.receipt, "gateway_signature");
+    if (!verify(payload, opts.receipt.gateway_signature, opts.gateway_public_key)) {
+        return { ok: false, reason: "gateway_signature invalid" };
+    }
+    const expectedHash = challengeHash(opts.expected_challenge);
+    if (opts.receipt.challenge_hash !== expectedHash) {
+        return {
+            ok: false,
+            reason: "challenge_hash does not match the sink-issued challenge",
+        };
+    }
+    if (!opts.receipt.delegation_chain_root ||
+        opts.receipt.delegation_chain_root !== opts.expected_delegation_chain_root) {
+        return {
+            ok: false,
+            reason: "delegation_chain_root missing or does not match the M2 commitment",
+        };
+    }
+    if (opts.receipt.decision === "permit" && !opts.receipt.authority_token_preimage) {
+        return {
+            ok: false,
+            reason: "permit ChallengeReceipt missing authority_token_preimage",
+        };
+    }
+    return { ok: true };
+}
+export function verifyEffectReceipt(opts) {
+    const payload = canonicalWithoutSignature(opts.receipt, "sink_signature");
+    if (!verify(payload, opts.receipt.sink_signature, opts.sink_public_key)) {
+        return { ok: false, reason: "sink_signature invalid" };
+    }
+    if (opts.receipt.challenge_hash !== opts.challenge_receipt.challenge_hash) {
+        return { ok: false, reason: "challenge_hash mismatch between M3 and M4" };
+    }
+    if (opts.receipt.authority_token_preimage !==
+        opts.challenge_receipt.authority_token_preimage) {
+        return { ok: false, reason: "authority_token_preimage mismatch between M3 and M4" };
+    }
+    if (opts.receipt.gateway_receipt_hash !== challengeReceiptHash(opts.challenge_receipt)) {
+        return { ok: false, reason: "gateway_receipt_hash does not match M3 canonical hash" };
+    }
+    return { ok: true };
+}
+export function reconstructAttestationChain(opts) {
+    const m1 = verifySinkChallenge(opts.challenge, opts.sink_public_key);
+    if (!m1.ok)
+        return m1;
+    const m3 = verifyChallengeReceipt({
+        receipt: opts.receipt,
+        expected_challenge: opts.challenge,
+        expected_delegation_chain_root: opts.receipt.delegation_chain_root,
+        gateway_public_key: opts.gateway_public_key,
+    });
+    if (!m3.ok)
+        return m3;
+    const m4 = verifyEffectReceipt({
+        receipt: opts.effect,
+        challenge_receipt: opts.receipt,
+        sink_public_key: opts.sink_public_key,
+    });
+    if (!m4.ok)
+        return m4;
+    return { ok: true };
+}

package/build/index.js

@@ -63,6 +63,17 @@ computeDataAxisWeights, computeComputeAxisWeights, DEFAULT_WEIGHT_PROFILE,
 // Attribution Settlement (Build C — per-period signed settlement record)
 aggregateAttributionPrimitives, buildContributorQueryResponse, signSettlementRecord, verifySettlementRecord, } from "agent-passport-system";
 // ═══════════════════════════════════════
+// Mutual Authentication v1 (SDK v2.2.0)
+// ═══════════════════════════════════════
+import { buildCertificate, signCertificate, certificateId, verifyBundle, verifyAttest, deriveSession, } from "agent-passport-system";
+// ═══════════════════════════════════════
+// Capability Token v0.1 (reference implementation)
+// Spec: agent-passport-system/docs/CAPABILITY-TOKEN-SPEC-DRAFT.md
+// ═══════════════════════════════════════
+import { issueSinkChallenge as issueCapabilitySinkChallenge, buildEvaluationRequest as buildCapabilityEvaluationRequest, mintChallengeReceipt as mintCapabilityChallengeReceipt, signEffectReceipt as signCapabilityEffectReceipt, InMemoryNullifierSet, verifyChallengeReceipt as verifyCapabilityChallengeReceipt, challengeHash as capabilityChallengeHash, } from "./capabilityToken/index.js";
+// One nullifier set per MCP process. v0.1: in-memory, no persistence.
+const capabilityNullifierSet = new InMemoryNullifierSet();
+// ═══════════════════════════════════════
 // State Management
 // ═══════════════════════════════════════
 const STORE_PATH = join(process.env.HOME || '.', '.agent-passport-tasks.json');
@@ -649,6 +660,11 @@ const TOOL_SCOPE_MAP = {
     'aps_aggregate_settlement': 'settlement',
     'aps_verify_settlement': 'settlement',
     'aps_build_contributor_query': 'settlement',
+    // Capability Token v0.1 (reference impl) — new 'capability' scope
+    'aps_capability_issue_challenge': 'capability',
+    'aps_capability_evaluate_authority': 'capability',
+    'aps_capability_mint_receipt': 'capability',
+    'aps_capability_sign_effect': 'capability',
 };
 // ═══════════════════════════════════════
 // TOOL: list_profiles
@@ -4353,6 +4369,285 @@ server.tool("aps_build_contributor_query", "Build a contributor-query response:
         return { content: [{ type: "text", text: safeError("buildContributorQuery failed", e) }], isError: true };
     }
 });
+// ═══════════════════════════════════════
+// Mutual Authentication v1 tools (SDK v2.2.0)
+// ═══════════════════════════════════════
+server.tool("mutualAuthBuildCertificate", "Build and sign a mutual-auth certificate identifying an agent or information system. Returns the signed MutualAuthCertificate object ready to carry into a handshake. The issuer's Ed25519 private key (hex) signs over the canonical (JCS) form.", {
+    role: z.enum(["agent", "information_system"]).describe("Role of the subject this cert identifies"),
+    subject_id: z.string().describe("Stable subject identifier (e.g., agent DID, IS endpoint URL)"),
+    subject_pubkey_hex: z.string().describe("Ed25519 public key (hex) of the subject"),
+    issuer_id: z.string().describe("Issuer identifier"),
+    issuer_role: z.enum(["agent", "information_system", "trust_anchor"]).describe("Role of the issuer"),
+    issuer_pubkey_hex: z.string().describe("Ed25519 public key (hex) of the issuer"),
+    issuer_privkey_hex: z.string().describe("Ed25519 private key (hex) of the issuer — used to sign"),
+    binding: z.string().describe("For an agent: the APS agent_id. For an IS: the resource domain (e.g., mcp://api.bank.com)"),
+    not_before: z.number().describe("Earliest valid time (unix ms)"),
+    not_after: z.number().describe("Latest valid time (unix ms)"),
+    supported_versions: z.array(z.string()).describe("Protocol versions supported, highest first (e.g., ['1.0'])"),
+    attestation_grade: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional().describe("For agents: APS attestation grade 0-3"),
+    capabilities: z.array(z.string()).optional().describe("Optional capability tags"),
+}, async (args) => {
+    try {
+        const unsigned = buildCertificate({
+            role: args.role,
+            subject_id: args.subject_id,
+            subject_pubkey_hex: args.subject_pubkey_hex,
+            issuer_id: args.issuer_id,
+            issuer_role: args.issuer_role,
+            binding: args.binding,
+            not_before: args.not_before,
+            not_after: args.not_after,
+            supported_versions: args.supported_versions,
+            attestation_grade: args.attestation_grade,
+            capabilities: args.capabilities,
+        }, args.issuer_pubkey_hex);
+        const cert = signCertificate(unsigned, args.issuer_privkey_hex);
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        certificate: cert,
+                        certificate_id: certificateId(cert),
+                    }, null, 2) }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("mutualAuthBuildCertificate failed", e) }], isError: true };
+    }
+});
+server.tool("mutualAuthVerifyAttest", "Verify a MutualAuthAttest against policy and trust anchors. Runs all 10 verification checks: signature, version negotiation, nonce match, timestamp freshness, certificate validity, issuer anchor check, binding constraints, downgrade detection, attestation grade policy, capability policy. Returns ok:true on success or a failure reason on rejection.", {
+    attest: z.any().describe("MutualAuthAttest to verify"),
+    expected_peer_nonce_b64: z.string().describe("The nonce the peer sent in their prior hello or attest"),
+    expected_own_nonce_b64: z.string().describe("The nonce we sent in our own prior hello or attest"),
+    policy: z.any().describe("MutualAuthPolicy (accepted_versions, min_agent_grade, required_capabilities, max_clock_skew_ms, max_session_ms)"),
+    trust_anchors: z.array(z.any()).describe("TrustAnchor[] — local trusted roots"),
+    revoked_anchor_ids: z.array(z.string()).optional().describe("IDs of anchors revoked since the bundle was issued"),
+    now_ms: z.number().optional().describe("Current unix ms — defaults to Date.now()"),
+}, async (args) => {
+    try {
+        const res = verifyAttest({
+            attest: args.attest,
+            expected_peer_nonce_b64: args.expected_peer_nonce_b64,
+            expected_own_nonce_b64: args.expected_own_nonce_b64,
+            policy: args.policy,
+            trust_anchors: args.trust_anchors,
+            revoked_anchor_ids: args.revoked_anchor_ids,
+            now_ms: args.now_ms ?? Date.now(),
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("mutualAuthVerifyAttest failed", e) }], isError: true };
+    }
+});
+server.tool("mutualAuthDeriveSession", "Derive the shared mutual-auth session record from both sides' Attests. Both parties MUST compute identical session_id given identical inputs (canonical JCS + sha256 of chosen_version, both cert ids, both nonces). Returns a MutualAuthSession with session_id + both certificates + expiry bounds, or failure reason.", {
+    agent_attest: z.any().describe("The agent's MutualAuthAttest"),
+    is_attest: z.any().describe("The information system's MutualAuthAttest"),
+    policy: z.any().describe("MutualAuthPolicy"),
+    now_ms: z.number().optional().describe("Current unix ms — defaults to Date.now()"),
+}, async (args) => {
+    try {
+        const res = deriveSession(args.agent_attest, args.is_attest, args.policy, args.now_ms ?? Date.now());
+        return {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("mutualAuthDeriveSession failed", e) }], isError: true };
+    }
+});
+server.tool("mutualAuthVerifyTrustBundle", "Verify a TrustAnchorBundle signature and freshness. Caller supplies the list of trusted publisher public keys (root configuration). Returns ok:true on success or failure reason (untrusted_publisher, signature_invalid, bundle_expired, not_yet_valid).", {
+    bundle: z.any().describe("TrustAnchorBundle to verify"),
+    trusted_publisher_pubkeys_hex: z.array(z.string()).describe("List of Ed25519 pubkeys (hex) authorized to publish bundles"),
+    now_ms: z.number().optional().describe("Current unix ms — defaults to Date.now()"),
+}, async (args) => {
+    try {
+        const res = verifyBundle(args.bundle, args.trusted_publisher_pubkeys_hex, args.now_ms ?? Date.now());
+        return {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("mutualAuthVerifyTrustBundle failed", e) }], isError: true };
+    }
+});
+// ═══════════════════════════════════════════════════════════════
+// Capability Token v0.1 — reference implementation tools
+// Spec: agent-passport-system/docs/CAPABILITY-TOKEN-SPEC-DRAFT.md
+// Namespace: aps.capability.v1.* (the protocol message type strings).
+// Tool names use snake_case per MCP convention.
+//
+// MCP is APS-aware by construction — tools are sinks. These four tools
+// expose the four protocol roles (sink, subject, gateway) so any caller
+// can drive the cycle end-to-end against this single process.
+// ═══════════════════════════════════════════════════════════════
+server.tool("aps_capability_issue_challenge", "v0.1 capability-token sink challenge (M1). Sink issues a signed canonical action statement. Returns the SinkChallenge and its challenge_hash. Used to bind the gateway's later policy evaluation to a specific action the sink authored. Search keywords: capability token, sink challenge, M1.", {
+    sink_id: z.string().describe("DID of the sink issuing the challenge"),
+    subject_id: z.string().describe("DID of the subject the challenge is addressed to"),
+    action: z.object({
+        kind: z.string(),
+        target: z.string(),
+        parameters: z.record(z.any()),
+        resource_version: z.string(),
+    }).describe("Canonical action statement"),
+    sink_private_key: z.string().describe("Sink Ed25519 private key (hex)"),
+    sink_public_key: z.string().describe("Sink Ed25519 public key (hex)"),
+    validity_seconds: z.number().int().positive().optional(),
+    required_policy_freshness: z.object({
+        max_age_seconds: z.number().int().nonnegative(),
+        beacon_hash_required: z.boolean(),
+    }).optional(),
+}, async (args) => {
+    try {
+        const sinkKey = {
+            publicKey: args.sink_public_key,
+            privateKey: args.sink_private_key,
+        };
+        const challenge = issueCapabilitySinkChallenge({
+            sink_id: args.sink_id,
+            subject_id: args.subject_id,
+            action: args.action,
+            validity_seconds: args.validity_seconds,
+            required_policy_freshness: args.required_policy_freshness,
+            sink_key: sinkKey,
+        });
+        const hash = capabilityChallengeHash(challenge);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ challenge, challenge_hash: hash }, null, 2),
+                }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("aps_capability_issue_challenge failed", e) }], isError: true };
+    }
+});
+server.tool("aps_capability_evaluate_authority", "v0.1 capability-token authority evaluation request (M2). Subject signs a request carrying the sink's M1, the delegation chain, and a revealed authority-token preimage. The gateway consumes this to decide permit/deny. Search keywords: capability token, authority evaluation, M2.", {
+    challenge: z.any().describe("SinkChallenge object from M1"),
+    delegation_chain: z.array(z.any()).describe("v2.x delegation envelopes"),
+    authority_token: z.object({
+        token_preimage: z.string(),
+        merkle_proof: z.array(z.string()),
+        scope_class: z.string(),
+    }),
+    freshness_beacon: z.object({
+        delegator_id: z.string(),
+        beacon_timestamp: z.string(),
+        beacon_signature: z.string(),
+    }),
+    subject_private_key: z.string().describe("Subject Ed25519 private key (hex)"),
+    subject_public_key: z.string().describe("Subject Ed25519 public key (hex)"),
+    delegation_chain_root: z.string().optional().describe("Override; otherwise computed from chain"),
+}, async (args) => {
+    try {
+        const subjectKey = {
+            publicKey: args.subject_public_key,
+            privateKey: args.subject_private_key,
+        };
+        const request = buildCapabilityEvaluationRequest({
+            challenge: args.challenge,
+            delegation_chain: args.delegation_chain,
+            authority_token: args.authority_token,
+            freshness_beacon: args.freshness_beacon,
+            subject_key: subjectKey,
+            delegation_chain_root: args.delegation_chain_root,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(request, null, 2) }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("aps_capability_evaluate_authority failed", e) }], isError: true };
+    }
+});
+server.tool("aps_capability_mint_receipt", "v0.1 capability-token gateway receipt (M3). Gateway signs a permit or deny over the sink's exact challenge_hash. Echoes the M2 delegation_chain_root so the sink can verify the gateway saw the same chain the subject committed to. Search keywords: capability token, challenge receipt, gateway receipt, M3.", {
+    request: z.any().describe("AuthorityEvaluationRequest from M2"),
+    decision: z.enum(["permit", "deny"]),
+    deny_reason: z.string().optional(),
+    policy_digest: z.string().describe("SHA-256 of the policy bundle used in evaluation"),
+    gateway_private_key: z.string(),
+    gateway_public_key: z.string(),
+}, async (args) => {
+    try {
+        const gatewayKey = {
+            publicKey: args.gateway_public_key,
+            privateKey: args.gateway_private_key,
+        };
+        const receipt = mintCapabilityChallengeReceipt({
+            request: args.request,
+            decision: args.decision,
+            deny_reason: args.deny_reason,
+            policy_digest: args.policy_digest,
+            gateway_key: gatewayKey,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(receipt, null, 2) }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("aps_capability_mint_receipt failed", e) }], isError: true };
+    }
+});
+server.tool("aps_capability_sign_effect", "v0.1 capability-token sink effect receipt (M4). Sink consumes the token preimage from the gateway's M3 (rejecting on nullifier replay), executes the action, and signs an EffectReceipt binding the consumed token to the result. The (M1, M3, M4) tuple is the full attestation record. Search keywords: capability token, effect receipt, M4, sink attestation.", {
+    challenge: z.any().describe("Original SinkChallenge from M1 (for binding verification)"),
+    challenge_receipt: z.any().describe("ChallengeReceipt from M3"),
+    effect: z.object({
+        executed_at: z.string(),
+        outcome: z.enum(["success", "failure", "partial"]),
+        result_digest: z.string(),
+    }),
+    sink_private_key: z.string(),
+    sink_public_key: z.string(),
+    gateway_public_key: z.string().describe("Used to verify M3 before consuming the token"),
+    expected_delegation_chain_root: z.string().optional().describe("If omitted, falls back to the receipt's own root"),
+}, async (args) => {
+    try {
+        const sinkKey = {
+            publicKey: args.sink_public_key,
+            privateKey: args.sink_private_key,
+        };
+        const challenge = args.challenge;
+        const receipt = args.challenge_receipt;
+        const verification = verifyCapabilityChallengeReceipt({
+            receipt,
+            expected_challenge: challenge,
+            expected_delegation_chain_root: args.expected_delegation_chain_root ?? receipt.delegation_chain_root,
+            gateway_public_key: args.gateway_public_key,
+        });
+        if (!verification.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "M3 verification failed", reason: verification.reason }) }],
+                isError: true,
+            };
+        }
+        if (receipt.decision !== "permit") {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "M3 is a deny — refusing to emit M4", deny_reason: receipt.deny_reason }) }],
+                isError: true,
+            };
+        }
+        const preimage = receipt.authority_token_preimage;
+        capabilityNullifierSet.consume(preimage);
+        const effectReceipt = signCapabilityEffectReceipt({
+            challenge_receipt: receipt,
+            effect: args.effect,
+            sink_key: sinkKey,
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        effect_receipt: effectReceipt,
+                        nullifier_set_size: capabilityNullifierSet.size(),
+                    }, null, 2),
+                }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: safeError("aps_capability_sign_effect failed", e) }], isError: true };
+    }
+});
 server.prompt("coordination_role", "Get instructions for your assigned coordination role", {}, async () => {
     const role = state.agentRole || 'default';
     const instructions = ROLE_PROMPTS[role] || ROLE_PROMPTS['default'];

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agent-passport-system-mcp",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "mcpName": "io.github.aeoess/agent-passport-mcp",
-  "description": "MCP server for the Agent Passport System — protocol-layer tools only. 142 tools (132 protocol + 10 gateway deprecation stubs). Identity, delegation, reputation, attestation, coordination, commerce, attribution primitive, attribution settlement. Tracks SDK v2.0.0. For gateway-runtime tools (ProxyGateway, AgentContext, DataEnforcementGate), use gateway.aeoess.com REST API or pin to v2.27.0.",
+  "description": "MCP server for the Agent Passport System — protocol-layer tools only. 150 tools (132 protocol + 10 gateway deprecation stubs). Identity, delegation, reputation, attestation, coordination, commerce, attribution primitive, attribution settlement. Tracks SDK v2.5.0-alpha (Wave 1 accountability primitives shipped in SDK; MCP exposure deferred). For gateway-runtime tools (ProxyGateway, AgentContext, DataEnforcementGate), use gateway.aeoess.com REST API or pin to v3.1.1.",
   "type": "module",
   "bin": {
     "agent-passport-system-mcp": "./build/bin.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "npx tsc && chmod 755 build/bin.js build/index.js build/setup.js",
-    "test": "node --test tests/*.test.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs build/__tests__/*.test.js",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
     "prepublishOnly": "npm run build && npm test",
@@ -50,11 +50,14 @@
   "homepage": "https://github.com/aeoess/agent-passport-mcp",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "agent-passport-system": "^2.0.0-beta.0",
+    "agent-passport-system": "^2.5.0-alpha",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",
     "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }