agent-passport-system 1.26.0 → 1.28.0

package/README.md

@@ -2,14 +2,14 @@
 
 [![npm version](https://img.shields.io/npm/v/agent-passport-system)](https://www.npmjs.com/package/agent-passport-system)
 [![license](https://img.shields.io/npm/l/agent-passport-system)](https://github.com/aeoess/agent-passport-system/blob/main/LICENSE)
-[![tests](https://img.shields.io/badge/tests-1507%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
+[![tests](https://img.shields.io/badge/tests-1656%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18749779.svg)](https://doi.org/10.5281/zenodo.18749779)
 
 > **For AI agents:** visit [aeoess.com/llms.txt](https://aeoess.com/llms.txt) for machine-readable docs or [llms-full.txt](https://aeoess.com/llms-full.txt) for the complete reference.
 
-**Governance, trust, and enforcement for AI agents. Not just identity.**
+**Governance infrastructure for the agent economy.** Identity, delegation, reputation, enforcement, commerce, institutional governance. Not just identity — the full stack.
 
-When an AI agent acts on your behalf, APS answers: what is it allowed to do? How much can it spend? Is it trustworthy? What happens when it violates a constraint? And can you prove all of this cryptographically?
+AI agents represent companies and people. They spend real money, access sensitive data, negotiate contracts, and talk to other agents. APS answers: what is this agent allowed to do? How much can it spend? Is it trustworthy? What happens when it violates a constraint? And can you prove all of this cryptographically?
 
 ```bash
 npm install agent-passport-system
@@ -70,6 +70,40 @@ const result = await gateway.processToolCall({
 
 **What just happened:** The gateway verified the agent's identity, checked delegation scope, enforced spend limits, evaluated values floor compliance, verified reputation tier, checked revocation status, executed the tool, generated a signed receipt, and updated reputation. All in one call. The agent never touched the tool directly.
 
+## Framework Integration: CrewAI
+
+Add governance to any CrewAI crew in 10 lines. Works the same way with LangChain, ADK, A2A, or any custom framework.
+
+```typescript
+import { generateKeyPair, createCrewAIGovernance } from 'agent-passport-system'
+
+const keys = generateKeyPair()
+const gov = createCrewAIGovernance({
+  agentId: 'research-agent',
+  ...keys,
+  delegationId: 'del_research_2026',
+  allowedScopes: ['tool:web_search', 'tool:read_file', 'task:execute'],
+  spendLimitPerAction: 5.00,
+})
+
+// Wrap any tool call — permitted actions execute, denied ones don't
+const result = await gov.governedToolCall(
+  'web_search',
+  { query: 'AI governance standards' },
+  () => mySearchTool('AI governance standards'),
+  0.01  // estimated cost
+)
+// result.governance.verdict → 'permit' or 'deny'
+// result.receipt → signed proof of the action (or denial)
+
+// Use as CrewAI task callback
+const receipt = gov.taskCallback({ description: '...', result: '...', agent: 'research-agent' })
+```
+
+**What you get:** scope enforcement (agent can only use allowed tools), spend controls ($5/action limit), signed receipts for every action (permit or deny), and a verifiable audit trail. The agent never bypasses governance because the wrapper executes the action, not the agent.
+
+See [`examples/crewai-governance.ts`](examples/crewai-governance.ts) for the full working example. Adapters also available for [LangChain](src/adapters/langchain.ts), [Google ADK](src/adapters/adk.ts), and [A2A](src/adapters/a2a.ts).
+
 ## Identity Is the Foundation, Not the Product
 
 Everything above is built on Ed25519 cryptographic identity. But identity is the plumbing, not the value proposition.
@@ -90,7 +124,7 @@ const agent = joinSocialContract({ name: 'my-agent', owner: 'alice', floor: floo
 
 ## The Stack
 
-42 core modules + 32 v2 constitutional modules. 1507 tests. Zero heavy dependencies.
+56 core modules + 32 v2 constitutional modules. 1707 tests. Zero heavy dependencies.
 
 | Layer | What it does | Key primitive |
 |-------|-------------|---------------|
@@ -109,7 +143,7 @@ const agent = joinSocialContract({ name: 'my-agent', owner: 'alice', floor: floo
 
 ## MCP Server
 
-108 tools across all modules. Any MCP client connects agents directly.
+121 tools across all modules. Any MCP client connects agents directly.
 
 ```bash
 npm install -g agent-passport-system-mcp
@@ -144,7 +178,7 @@ npx agent-passport audit --floor values/floor.yaml
 
 ```bash
 npm test
-# 1507 tests across 79 files, 392 suites, 0 failures
+# 1707 tests across 86 files, 443 suites, 0 failures
 ```
 
 50 adversarial tests: Merkle tampering, attribution gaming, compliance violations, floor negotiation attacks, cross-chain confused deputy, taint laundering, authority probing.
@@ -162,7 +196,7 @@ npm test
 | Signed receipts | 3-sig chain | Proposed | Logs | General | — |
 | Values enforcement | 8 principles, graduated | — | Rules | — | — |
 | Coordination | Task lifecycle + MCP | — | — | — | — |
-| Tests | 1507 (50 adversarial) | None | Limited | None | None |
+| Tests | 1656 (50 adversarial) | None | Limited | None | None |
 
 ## Recognition
 
@@ -177,6 +211,10 @@ npm test
 
 **"Monotonic Narrowing for Agent Authority"** — Published on [Zenodo](https://doi.org/10.5281/zenodo.18749779). [Read →](papers/agent-social-contract.md)
 
+**"Faceted Authority Attenuation: A Product Lattice Model for AI Agent Governance"** — Published on [Zenodo](https://doi.org/10.5281/zenodo.19260073). Seven-dimensional product lattice formalization with authorization witnesses, constraint vectors, and institutional governance composition.
+
+**Cited by:** Nanook & Gerundium, "PDR in Production: Empirical Validation of Behavioral Trust Scoring in Multi-Agent Systems" ([DOI:10.5281/zenodo.19323172](https://doi.org/10.5281/zenodo.19323172)) — Section 7.6 independently validates the APS Bayesian reputation model, sigma dynamics, and structuralVerdict/trustVerdict separation using production data from UBC.
+
 ## Authorship
 
 Designed and built by **Tymofii Pidlisnyi** with AI assistance from **Claude** (Anthropic).

package/dist/src/core/charter.d.ts

@@ -0,0 +1,91 @@
+import type { CharterCore, CharterSignature, Office, OfficeRegistry, OfficeTransfer, CharterAmendment, CharterVerification, AmendmentVerification, DelegationSurvival, DissolutionPolicy, DisputeVenue, SuccessionRule, SuccessionTrigger, QuorumFailurePolicy } from '../types/charter.js';
+import type { MultiClassThresholdPolicy, ApprovalRequest, ApprovalSignature, ApprovalSubjectType, ApprovalEvaluation, ApprovalPolicy } from '../types/approval.js';
+export interface CreateCharterOptions {
+    name: string;
+    offices: Office[];
+    amendmentPolicy: MultiClassThresholdPolicy;
+    dissolutionPolicy: DissolutionPolicy;
+    delegationSurvival: DelegationSurvival;
+    disputeVenue?: DisputeVenue;
+    founderPrivateKey: string;
+    founderPublicKey: string;
+    founderRole: string;
+    version?: string;
+}
+/** Create a new charter. The founder signs it as the first founding signatory.
+ *  Additional signatories can be added with signCharter() until the
+ *  amendment policy threshold is met. */
+export declare function createCharter(opts: CreateCharterOptions): CharterCore;
+/** Add a founding signature to a charter. Returns a new charter
+ *  with the additional signature and a re-signed outer signature. */
+export declare function signCharter(charter: CharterCore, signerPrivateKey: string, signerPublicKey: string, signerRole: string, resignerPrivateKey: string): CharterCore;
+/** Verify a charter's integrity: content hash, signatures, office consistency. */
+export declare function verifyCharter(charter: CharterCore): CharterVerification;
+/** Evaluate whether a set of signatures satisfies a multi-class threshold policy.
+ *  All class requirements must be met (conjunction). Consilium Q5. */
+export declare function evaluateThreshold(policy: MultiClassThresholdPolicy, signatures: ApprovalSignature[]): ApprovalEvaluation;
+export interface CreateAmendmentOptions {
+    charter: CharterCore;
+    proposedCharter: CharterCore;
+    description: string;
+    proposerPrivateKey: string;
+    proposerPublicKey: string;
+    effectiveAt?: string;
+}
+/** Create a charter amendment proposal. Does NOT apply it —
+ *  signatures must be collected and threshold evaluated first. */
+export declare function createAmendment(opts: CreateAmendmentOptions): CharterAmendment;
+/** Add a signature to a charter amendment. */
+export declare function signAmendment(amendment: CharterAmendment, signerPrivateKey: string, signerPublicKey: string, signerRole: string): CharterAmendment;
+/** Verify a charter amendment against the charter's amendment policy. */
+export declare function verifyAmendment(amendment: CharterAmendment, charter: CharterCore): AmendmentVerification;
+/** Create an OfficeRegistry from a charter's offices. */
+export declare function createOfficeRegistry(charter: CharterCore, successionRules: SuccessionRule[], quorumFailurePolicies: QuorumFailurePolicy[], signerPrivateKey: string): OfficeRegistry;
+export interface CreateOfficeTransferOptions {
+    charter: CharterCore;
+    officeId: string;
+    fromHolder: string | null;
+    toHolder: string | null;
+    trigger: SuccessionTrigger | 'appointment' | 'resignation';
+    delegationHandling: 'frozen' | 'transferred' | 'revoked';
+    approvalSignatures: CharterSignature[];
+    signerPrivateKey: string;
+}
+/** Record an office holder change. */
+export declare function createOfficeTransfer(opts: CreateOfficeTransferOptions): OfficeTransfer;
+/** Create an approval request for a multi-party action. */
+export declare function createApprovalRequest(policyId: string, subject: string, subjectType: ApprovalSubjectType, requestedBy: string, timeoutSeconds: number): ApprovalRequest;
+/** Add a signature to an approval request. Validates the signer
+ *  is not a duplicate and the request hasn't expired. */
+export declare function addApprovalSignature(request: ApprovalRequest, signerPrivateKey: string, signerPublicKey: string, keyClass: string, officeId?: string): ApprovalRequest;
+/** Evaluate an approval request against its policy. For 'threshold'
+ *  type, delegates to evaluateThreshold. For simpler types, does
+ *  direct checks. Returns the updated request with status. */
+export declare function evaluateApprovalRequest(request: ApprovalRequest, policy: ApprovalPolicy): {
+    request: ApprovalRequest;
+    evaluation: ApprovalEvaluation;
+};
+/** Find an office by ID within a charter. */
+export declare function findOffice(charter: CharterCore, officeId: string): Office | undefined;
+/** Find which office(s) a public key holds. */
+export declare function findOfficesByHolder(charter: CharterCore, publicKey: string): Office[];
+/** Resolve the successor office for a vacant office. Walks the
+ *  succession order and returns the first non-vacant office. */
+export declare function resolveSuccessor(charter: CharterCore, officeId: string): Office | null;
+/** Check if a holder can take an office without violating
+ *  incompatibility constraints (GPT #20). */
+export declare function checkIncompatibility(charter: CharterCore, officeId: string, holderPublicKey: string): {
+    compatible: boolean;
+    conflicts: string[];
+};
+/** Check if an office has quorum per its QuorumFailurePolicy. */
+export declare function checkQuorum(office: Office, policy: QuorumFailurePolicy | undefined): {
+    hasQuorum: boolean;
+    holders: number;
+    required: number;
+};
+/** Check if a charter is in dissolution grace period. */
+export declare function isInDissolutionGrace(charter: CharterCore): boolean;
+/** Verify an office transfer signature. */
+export declare function verifyOfficeTransfer(transfer: OfficeTransfer): boolean;
+//# sourceMappingURL=charter.d.ts.map

package/dist/src/core/charter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charter.d.ts","sourceRoot":"","sources":["../../../src/core/charter.ts"],"names":[],"mappings":"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"}