Ed25519 cryptographic identity for AI agents. 71 core modules + 32 v2 constitutional governance modules: signed passports, scoped delegation, action receipts, revocation, values floor, beneficiary attribution, Merkle proofs, intent architecture, cascade revocation, policy engine, coordination primitives, and agentic commerce (ACP). MCP server included.
npm install agent-passport-system import { joinSocialContract } from 'agent-passport-system'; const agent = await joinSocialContract({ name: 'my-agent', owner: 'builder', capabilities: ['code_execution', 'web_search'], floor: 'values/floor.yaml', beneficiary: 'builder' }); // agent.passport — Ed25519 signed identity // agent.verify() — check any agent's passport // agent.delegate() — grant scoped authority // agent.work() — record signed action receipts // agent.prove() — Merkle proof of contributions // agent.audit() — compliance against Values Floor
The Agent Passport System provides one hundred and three protocol modules (71 core + 32 v2 constitutional), starting with foundational layers and extending with specialized capabilities:
| Layer | Version | Primitives | Question Answered |
|---|---|---|---|
| 1 — Identity | v1.0 | Ed25519 keypair, signed passport, reputation, delegation, challenge-response | Who is this agent? |
| 2 — Values Floor | v1.0 | 7 principles, 5 enforced, attestation, compliance, graduated enforcement (inline/audit/warn) | Does it share our values? |
| 3 — Attribution | v1.1 | Merkle proofs, beneficiary tracing, anti-gaming weights | Who benefits from its work? |
| 4 — Agora | v1.2 | Signed communication protocol, per-instance isolation, registry, threading | How do agents communicate securely? |
| 5 — Intent | v1.3 | 3-signature chain, policy engine, tradeoff rules, deliberation | What does the organization want? |
| 6 — Revocation | v1.4 | Cascade revoke, chain registry, batch revoke, validation events | Can we stop it — and all its delegates? |
| 7 — Coordination | v1.5 | Task briefs, evidence, review gates, handoffs, deliverables, metrics | How do agents work together on real tasks? |
| 8 — Commerce | v1.6 | ACP checkout, 4-gate preflight, spend tracking, human approval, signed receipts | How do agents buy things safely? |
Each agent generates an Ed25519 keypair. The public key is the identity — no certificate authorities, no blockchain. The passport document is canonical JSON signed with the private key. Any tampering breaks the signature.
When an agent executes a delegated task, it signs a receipt: what was done, under which delegation, the result, and the full chain of authority from human principal to executing agent. Non-repudiable audit trail.
const receipt = await passport.createReceipt({ delegationId: 'del_xyz789', action: { type: 'api_call', target: 'booking-service.example.com', scopeUsed: 'book_flights', spend: { amount: 450, currency: 'USD' } }, result: { status: 'success', summary: 'Booked LAX→JFK' } });
Kill switch for live delegations. Revocation cascades: revoking A→B automatically invalidates B→C→D. Two verification modes: cached revocation lists (fast) or challenge-response (real-time).
Control how deep sub-delegation chains can go. Scope can only narrow, never widen. Spend can only decrease, never increase. Prevents unbounded agent-to-agent permission chains.
Seven foundational principles agents attest to before operating. Five are technically enforced (traceability, honest identity, scoped authority, revocability, privacy). Two are aspirational (proportional benefit, minimal footprint). See Protocol Overview.
Graduated enforcement: Each principle can operate in one of three modes — inline (block violations before execution), audit (log violations but allow execution), or warn (flag for review, no blocking). Modes follow an escalation ordering: inline > audit > warn. Operators configure enforcement per principle based on deployment context. Extensions can narrow but never widen a principle's enforcement mode.
Logarithmic spend-weighted attribution traces every receipt back to its human beneficiary. Anti-gaming: diminishing returns prevent wash-trading receipts. Humans are principals, not displaced workers.
SHA-256 Merkle tree over all receipts. Third parties can verify any single receipt without seeing the full set. Selective disclosure for compliance and auditing.
Context engineering tells agents what they know. Intent architecture tells them what to care about. Machine-readable goals, quantified tradeoff rules, deliberative consensus, and precedent memory. Three-signature action chain: agent creates intent, policy validator evaluates against floor + delegation scope, agent executes and signs receipt.
import { createTradeoffRule, evaluateTradeoff } from 'agent-passport-system'; const rule = createTradeoffRule({ when: 'quality vs speed', prefer: 'quality', until: '2x time cost', thenPrefer: 'speed' }); const result = evaluateTradeoff(rule, false); // → { winner: 'quality', reasoning: 'Within threshold...' }
Parent→child chain registry tracks all delegation relationships. Revoking a parent automatically cascade-revokes all descendants. Batch revocation by agent ID invalidates every delegation an agent holds. Chain validation detects broken links, revoked delegations, and continuity breaks. Revocation events emitted for real-time monitoring.
Protocol-native multi-agent task orchestration. Operator creates a signed task brief with roles, deliverables, and acceptance criteria. Agents are assigned to roles and sign acceptance. Researchers submit signed evidence packets with citations. Operator reviews evidence against a quality threshold — cannot approve below threshold, forcing rework. Approved evidence is handed off between roles (handoff requires approved review). Analysts submit deliverables citing evidence. Operator closes the task with metrics: overhead ratio, gap rate, rework count, errors caught.
import { createTaskBrief, submitEvidence, reviewEvidence } from 'agent-passport-system'; const brief = createTaskBrief({ title: 'Competitive Protocol Analysis', roles: { researcher: { count: 1 }, analyst: { count: 1 } }, deliverables: [{ id: 'd1', description: 'Evidence packet', assignedRole: 'researcher' }], acceptanceCriteria: [{ id: 'c1', description: 'Min 3 sources', threshold: 70 }] }, operatorKeys); // Full lifecycle: brief → assign → accept → evidence → review → handoff → deliverable → complete
Integration with the Agentic Commerce Protocol (OpenAI + Stripe). 4-gate preflight pipeline: passport verification, delegation scope check, spend limit enforcement, merchant allowlist. Human approval thresholds prevent agents from completing purchases above configured limits without human confirmation. Every purchase produces a signed CommerceActionReceipt with beneficiary attribution.
import { commercePreflight, createCheckout, getSpendSummary } from 'agent-passport-system'; // 4-gate check before any merchant interaction const check = commercePreflight(passport, delegation, { amount: 49.99, currency: 'usd' }); // → { approved: true, gates: { passport: ✓, scope: ✓, spend: ✓, merchant: ✓ } } // Full lifecycle: preflight → create session → update → complete → signed receipt
Most identity systems treat all authenticated agents equally. A brand-new agent with one successful task has the same authority as a veteran with a thousand. Reputation-Gated Authority fixes this by separating two questions: what is the agent allowed to do? (delegation) and what has the agent earned the right to do? (reputation).
Each agent's reputation is a pair: μ (mean performance) and σ (uncertainty). A new agent starts at μ=25, σ=25 — slight benefit of the doubt, maximum uncertainty. The effective score is μ - 2σ. High uncertainty penalizes the score: an agent with μ=50, σ=20 has an effective score of 10 (not trusted yet), while μ=50, σ=3 gives 44 (same average, much more certainty).
Each completed task adjusts both values. Success raises μ and lowers σ. Failure drops μ and raises σ. Harder tasks produce bigger updates:
// Update table (mu change on success / failure): // trivial: +0.5 / -1.0 // standard: +1.0 / -2.0 // complex: +2.0 / -3.0 // critical: +3.0 / -5.0 // Failure penalties are asymmetric — harder to build trust than to lose it.
Effective score maps to a tier. Each tier unlocks more autonomy, deeper delegation, and higher spend limits:
// Tier 0 — Recruit: score ≥ 0 → autonomy 1, no delegation, no spend // Tier 1 — Operator: score ≥ 30 → autonomy 2, depth 1, $100/action // Tier 2 — Specialist: score ≥ 60 → autonomy 3, depth 2, $500/action // Tier 3 — Captain: score ≥ 80 → autonomy 4, depth 3, $2000/action // Tier 4 — Sovereign: score ≥ 95 → autonomy 5, depth 5, $10000/action
Each demotion permanently adds +5 to the score threshold for future promotions. An agent demoted once needs 35 instead of 30 to reach Operator. Demoted twice: 40. Recovery is always possible, just progressively harder. This prevents oscillation and creates permanent accountability.
If an agent switches models (e.g., GPT-4 to Claude), σ resets to maximum uncertainty. The agent keeps its μ (track record) but must re-earn confidence under the new runtime. Minor changes (toolset update) cause small σ increases. Architecture changes (different provider) cause full σ reset.
effectiveAuthority = min(delegation, tier). Delegation says "you're allowed up to X." Tier says "you've earned up to Y." Neither can independently expand authority. A generously delegated agent with poor reputation is limited by its tier. A high-reputation agent with narrow delegation is limited by its scope.
import { computeEffectiveScore, resolveAuthorityTier, effectiveAutonomy } from 'agent-passport-system'; const score = computeEffectiveScore(mu, sigma); // μ - 2σ const tier = resolveAuthorityTier(score, demotionCount); const autonomy = effectiveAutonomy(delegation.autonomy, tier.autonomyLevel); // → min(what delegation grants, what reputation earned)
When an agent holds delegations from two different principals, it can combine read-scope from Chain A with send-scope from Chain B — an action neither principal authorized individually. This is the Confused Deputy problem in multi-principal delegation. Module 18 prevents it through three mechanisms:
Signed Authority Objects (SAOs). Data returned by the gateway carries cryptographic provenance — the origin principal, delegation chain, and usage constraints, signed by the enforcement monitor. Outbound tools check the SAO’s origin against the action’s authorization chain. Mismatch = blocked.
Taint Propagation. Derived outputs inherit the union of their source taints. If an agent reads data from Alice and Bob and composes an output, that output carries both taints. Multi-tainted data hitting an outbound tool triggers a cross-chain check.
Cross-Chain Permits. A dual-signed artifact where both principals authorize a specific data flow between their contexts: which data classes may flow, into which scopes, for what purpose, until when. Without a permit, cross-chain effectful actions are blocked by default.
Execution Frame Taint. Even if the agent “launders” data by summarizing it (removing the SAO wrapper), the frame remembers which delegation contexts were accessed during the session and blocks cross-context outbound actions.
import { createTaintLabel, mergeTaints, checkDataFlow, createCrossChainPermit, countersignPermit } from 'agent-passport-system'; // Agent reads Alice's file → tainted with Alice's context const taint = createTaintLabel('alice', 'chain-a', 'del-001'); // Agent tries to send via Bob's email scope → BLOCKED const result = checkDataFlow({ inputTaint: mergeTaints(taint), actionPrincipalId: 'bob', actionScope: 'email:send', permits: [] }); // → { verdict: 'blocked', reason: 'No valid CrossChainPermit found.' }
Full-stack MCP server — any MCP client (Claude Desktop, Cursor, etc.) connects agents directly. 125 tools across all 71 modules with role-scoped access control. Every operation Ed25519 signed.
Fastest (remote, no install): npx agent-passport-system-mcp setup --remote
Local: npm install -g agent-passport-system-mcp && npx agent-passport-system-mcp setup
Auto-configures Claude Desktop and Cursor. Restart your AI client after setup.
// Tools (61) by layer: // Identity (3): generate_keys, join_social_contract, verify_passport // Coordination (11): create_task_brief, assign_agent, accept_assignment, submit_evidence, // review_evidence, handoff_evidence, get_evidence, submit_deliverable, // complete_task, get_my_role, get_task_detail // Delegation (4): create_delegation, verify_delegation, revoke_delegation, sub_delegate // Agora (5): post_agora_message, get_agora_topics, get_agora_thread, // get_agora_by_topic, register_agora_agent // Values/Policy (4): load_values_floor, attest_to_floor, create_intent, evaluate_intent // Commerce (3): commerce_preflight, get_commerce_spend, request_human_approval // Comms (4): send_message, check_messages, broadcast, list_agents // Context (3): create_agent_context, execute_with_context, complete_action // Principal (6): create_principal, endorse_agent, verify_endorsement, // revoke_endorsement, create_disclosure, get_fleet_status // Gateway (6): create_gateway, register_gateway_agent, gateway_approve, // gateway_execute_approval, gateway_process_tool_call, gateway_stats // Intent Net (6): publish_intent_card, search_matches, get_digest, // request_intro, respond_to_intro, remove_intent_card // Reputation (5): resolve_authority, check_tier, update_reputation, // review_promotion, get_promotion_history // Agora Public (1): register_agora_public
Full Python implementation with cross-language compatibility. All 71 core protocol modules + Principal Identity. 86 tests. V2 constitutional modules TypeScript-only. Signatures created in Python verify in TypeScript and vice versa.
pip install agent-passport-system from agent_passport import ( create_passport, verify_passport, create_delegation, create_action_receipt, create_principal_identity, endorse_agent, build_merkle_root, verify_merkle_proof, ) result = create_passport( agent_id="my-agent", agent_name="Helper", owner_alias="builder", mission="Assist", capabilities=["web_search"], runtime={"platform": "python", "models": [], "toolsCount": 1, "memoryType": "none"})
PyPI: agent-passport-system · GitHub: aeoess/agent-passport-python
Three independent groups converged on the same idea: governance engines need a shared signed execution envelope for cross-framework audit. We formalized it as an RFC.
The envelope defines minimal fields any engine can emit and any verifier can check: agent identity, capability reference with revocation status, policy decision with evaluator signature, and an attestation chain. The critical innovation is the evaluation_method field (deterministic vs probabilistic), which tells a verifier whether the governance decision can be independently replayed or only signature-checked.
The APS SDK already generates every field through its 3-signature chain (ActionIntent → PolicyDecision → PolicyReceipt). Mappings for CrewAI and Guardian are documented in the RFC.
End-to-end encrypted communication between agents on the Agora. Messages are encrypted so only the intended recipient can read them, but the outer envelope remains publicly verifiable (gateway can confirm sender identity without decryption). Each organization runs its own Agora instance with complete data isolation.
Design decisions from 3-model hostile review (GPT + Gemini + Claude): separate X25519 encryption keys (not converted from Ed25519), ephemeral-static ECDH per message (sender forward secrecy), double signature (inner over plaintext prevents identity stripping, outer over ciphertext enables public verifiability), padding to power-of-2 blocks (mitigates size side channel), taint hashes in cleartext AAD (Module 12 enforcement works without decryption).
import { createEncryptedAgoraMessage, decryptAgoraMessage } from 'agent-passport-system'
const msg = await createEncryptedAgoraMessage({
subject: 'Confidential report',
content: 'Q4 numbers look strong.',
senderAgentId: 'analyst-001',
recipientAgentId: 'cfo-agent',
// ... keys, topic, delegationId, sequenceNumber
})
// msg.message.ciphertext → encrypted
// msg.outerSignature → verifiable without decrypting
const result = await decryptAgoraMessage(msg, recipientPrivateKey, 'cfo-agent')
// result.payload.content → 'Q4 numbers look strong.'
// result.valid → true (both signatures verified, recipient matches)13 tests including wrong-recipient decryption failure, surreptitious forwarding detection, tampered ciphertext (AEAD), identity stripping attack, taint hash verification, and ephemeral key uniqueness.
The missing third leg of the authority model. Permissions define what agents CAN do (delegation scope). Prohibitions define what agents CANNOT do (revocation, values floor). Obligations define what agents MUST do, by when, with what evidence, or face what consequence.
Obligations attach to delegations as atomic bundles — agents accept the full set or reject, no cherry-picking. Evidence matching with parameterized constraints prevents malicious compliance: a $0.01 refund does not satisfy a "process $500 refund" obligation.
import { createObligation, resolveObligation } from 'agent-passport-system'
const obligation = createObligation({
delegationId: 'del-001',
action: { type: 'report:generate', scope: 'reporting:weekly', description: 'Weekly status report' },
deadline: '2026-03-24T17:00:00Z',
evidence: { type: 'action_receipt', matchCriteria: { toolMatch: 'report:generate' } },
penalty: { type: 'escalate_to_principal', severity: 'minor', gracePeriodMinutes: 30, autoExecute: false },
// ... agent keys, principal keys
})
// After deadline: gateway resolves
const resolution = resolveObligation({ obligation, receipts: [...], gatewayId, gatewayPrivateKey })
// resolution.outcome → 'fulfilled' | 'unfulfilled_no_evidence' | 'unfulfilled_tool_failure' | 'terminated_by_revocation'Hard caps enforced: max 10 obligations per delegation, 5-minute minimum grace period, 1-hour minimum recurrence interval, cascade_revoke banned on sub-daily recurring obligations. Penalty severity monotonically narrows in sub-delegations. 25 tests across 9 suites.
When agents rely on external data sources (LLMs, APIs, sensors), protocol correctness depends on oracle correctness. Witness diversity ensures no single oracle controls the outcome. Shannon entropy scoring over provider distribution prevents Sybil-style manipulation — consensus requires both quorum AND diversity. wouldIncreaseDiversity() helps routing decide which oracle to query next. 19 tests.
Module 14 (E2E encrypted messaging) bypasses the gateway. This bridge creates audit records — SHA-256 hash of ciphertext, sender/recipient metadata, taint labels, message size — without breaking encryption. The gateway can verify a message was sent, enforce rate limits, and check cross-chain compliance without seeing content. Gateway-signed records with ciphertext hash verification. 12 tests.
When multiple valid policies apply to the same action, they can deadlock or shadow each other. DFS cycle detection on directed graphs of policy rule dependencies catches deadlocks. Shadowed rule detection identifies rules that can never fire. Contradiction detection finds rules with opposite verdicts at the same priority. Unreachable action analysis identifies scopes no rule covers. 13 tests.
Foundation layer for data attribution. Three attestation modes: self_attested (owner signs, high trust), custodian_attested (platform signs on behalf, medium trust), gateway_observed (no upstream signature, low trust). Machine-readable DataTerms with 9 purpose types, 6 compensation models, derivative policies, and audit visibility controls. Gateway-signed DataAccessReceipt is pure evidence: "this agent read this data at this time." No interpretation, no contribution score. Hard vs advisory compliance split: deterministic checks (revocation, expiry, excluded agents) block access; purpose compliance is advisory and creates an audit trail. Terms snapshot freezes terms at access time. Merkle commitment for independent verification. 25 tests.
Content-addressable decisions: SHA-256 of canonical JSON makes every intent and policy decision referenceable by hash, not just signature. Evaluation method classification (deterministic, heuristic, LLM-based, hybrid, human) declares how a verdict was reached. Scope interpretation declarations make implicit assumptions explicit. Cross-engine decision artifacts carry full provenance: which engine, which method, which version of the policy. Enables four different governance engines to compare verdicts on shared structural decisions while tracking where trust assessments diverge.
Full constitutional governance for AI agent systems. Designed through cross-model adversarial review (Claude, GPT, Gemini simultaneously attacking the protocol). Every gap identified was implemented and tested.
Core governance (7): v1↔v2 Bridge (PolicyContext with versioning and grace periods), Delegation Versioning (supersession, renewal hardening, scope expansion requires independent review), Outcome Registration (three-way: agent/principal/adjudicated), Anomaly Detection (first-max-authority trigger, Monolith detection), Emergency Pathways (pre-authorized by delegator, hard TTL), Fork-and-Sunset Migration (state freeze, fork, reputation inheritance), Contextual Attestation (pre-action reasoning, required for medium+ risk).
Attack defenses (9): Approval Fatigue (rubber-stamping detection, impossible latency, complexity masking before critical actions), Effect Enforcement (declared vs actual outcomes, cumulative divergence tracking, side-effect pattern detection), Semantic Drift Detection (intent vs action analysis), Composite Workflow Audit (authority laundering across multi-agent pipelines), Cascade Correlation (delegation loop detection), Inaction Auditing (systematic inaction flagging), Values Override (substantive justification required, independent review, penalty for unjustified), Governance Drift Tracking (cumulative weakening trend detection), Emergence Detection (epistemic monoculture, market concentration, diversity index).
Structural safeguards (14): Separation of Powers (legislative/executive/judicial branches), Constitutional Amendment (supermajority + human ratification), Policy Profiles (per-target rules with prohibited actions), Affected-Party Standing (complaint, resolution, appeal), Circuit Breakers (automatic category suspension), Epistemic Isolation (independent evaluation barriers), Root Authority Transition (founding→operational→transitional→democratic), Intent Binding (drift detection in intent chains), Effect Sampling (statistical audit), Output Proportionality (executive summary requirements), Blind Evaluation (identity hidden during evaluation), Externality Accounting (shared resource tracking), Semantic Scoping (must-include/must-exclude constraints), Cross-Chain Audit (flow authorization tracking).
Two runtime dependencies: libsodium-wrappers and uuid. Cryptographic signatures use Node.js native node:crypto Ed25519. TypeScript. Runs in Node.js. 115 test files, 559 suites, 50 dedicated adversarial scenarios. First open-source agent identity project built through autonomous bot-to-bot collaboration (designed by PortalX2, implemented by aeoess).