trustcard: Instructions file for Codex

trustcard — repo knowledge for agents

What this is

trustcard is cryptographic trust infrastructure for MCP servers, and the start of a protocol-neutral trust substrate for executable capabilities. v3.0.3 builds on v1 identity/provenance/v2 policy/receipts with three new layers:

1. Behavioral verification (lib/behavior.js) — sandboxed, deterministic probing that can fail a server whose static contract is unchanged.
2. Evidence substrate (lib/evidence.js, lib/evidence-store.js) — content-addressed, immutable observations.
3. HTTP/SSE transport parity (lib/client-http.js) — experimental streamable-http and SSE client.

Read docs/INDEX.md first, then docs/SECURITY-MODEL.md, docs/SPEC.md, and docs/BEHAVIOR.md.

Commands

• Test: npm test → node --test test/*.test.js (529 tests, all should pass)
  • IMPORTANT: the test/*.test.js glob is required. Bare node --test also matches test/helpers.js and the fixture servers, which hang the runner (child processes keep stdio open). Don't "simplify" the glob away.
  • The glob must be unquoted in the package.json script so the shell expands it before Node receives the paths; a quoted glob becomes a literal path.
• CLI: node bin/mcp-trustcard.js <subcommand> (keygen/manifest/sign/verify/ diff/pin/pins/fingerprint/scan/gen-manifest/inspect/auth-issue/auth-verify/ behavior/evidence)
• Also bin/mcp-proxy.js and bin/mcp-http-proxy.js for call-time enforcement.
• No runtime deps. Pure Node stdlib. Don't add dependencies.

Architecture map (lib/)

• canon.js — RFC 8785 (JCS) canonicalization. Every digest depends on this being byte-exact. Numbers use ECMAScript shortest round-trip with e+n/e-n exponents, no -0; keys sorted by UTF-16 code units. RFC test vectors in test/canon.test.js.
• hash.js — digest(value) = "sha256:"+base64url(SHA256(JCS(value))). signingPayload() excludes BOTH signature and manifestDigest.
• identity.js — semantic projection for tool/server digests. Semantic: name, description, inputSchema, outputSchema, annotations{title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint}, execution. Volatile (excluded): top-level title, icons, tags, _meta.
• diff.js — five-level taxonomy NONE<SYNTACTIC<NON_BREAKING<ANNOTATION_DOWNGRADE<PERMISSION_CHANGE<BREAKING. Compatible = ≤NON_BREAKING.
• change.js — multi-axis change vector (interface/permission/implementation/ provenance) for descriptors.
• trust.js — state machine UNKNOWN→OBSERVED→PINNED→MISMATCH/SUSPECT→REVOKED. REVOKED is sticky. trustLevel() projects onto TRUSTED/VERIFIED/OBSERVED/UNTRUSTED/REVOKED.
• provenance.js — manifest build/sign/verify. Ed25519 via node:crypto. Signed manifests carry expiresAt; verifyManifest rejects expired ones.
• manifest.js — proxy-enforcement manifest. buildManifest includes expiresAt (default 90 days); checkCall blocks all calls when expired. --allow-tool records manualOverride: true. --require-scopes adds requiredScopes per tool.
• pin.js — TOFU pin store (servers + publisher keys), atomic writes, fail-closed on corrupt file.
• session.js — live connection: negotiates protocol, verifies handshake binding, subscribes to notifications/tools/list_changed → re-diff.
• guard.js — the enforcement gate. wrapClient/session.call route every tools/call through guard.authorizeCall. Modes: enforce/audit/off. Emits signed, chained receipts when given a receiptKey.
• middleware.js — wrapClient(rawClient, {guard, session}); re-verifies toolset digest on every tools/list.
• policy.js — Gate 2 per-invocation authorization: composable rule predicates (allowTools, denyTools, constrainArg, forbidArg, restrictToolToEnvironments, requireApprovalForDestructive, requireScopes) + ScopedDecisions. Verdict precedence: deny > require-approval > allow. Rule predicates that throw fail closed. defaultVerdict defaults to allow; set to deny for default-deny.
• auth.js — Per-agent auth scope enforcement. DevIssuer (HMAC-SHA256 JWT-like tokens), IdpIntrospector (RFC 7662 OAuth 2.1 token introspection), TokenValidator (local first, then introspection), scopeSatisfies (wildcards * and prefix:*), extractToken/stripAuth.
• rotation.js — old-key-signs-new-key rotation certificates + self-signed revocation certificates.
• behavior.js — v3. Behavioral verification engine. Exports SandboxRuntime, InputGenerator, OutputComparator, BehaviorEngine, BehaviorReport, BehaviorFinding, RegressionCorpus, ReferenceObservation. Key invariant: static identity can pass while behavioral verification fails.
• evidence.js / evidence-store.js / evidence-adapters.js — v3. Content-addressed evidence records and local store. Records are immutable; corrections use supersedes. EVIDENCE_LAYERS is the predicate registry.
• evidence-predicates.js — predicate and layer vocabulary for evidence.
• existence.js — existence probes for npm and GitHub repos (evidence layer).
• observe.js, fingerprint.js, receipts.js, report.js, checks.js — scan, identity card, reproducibility, rendering.
• danger-detector.js — three-engine fusion: heuristic, semantic (TF-IDF), injection markers.
• descriptor.js — protocol-neutral capability descriptor. interfaceDigest() is byte-equal to toolDigest(). implementationIdentity is typed (npm-dist/source/unresolved). buildDescriptor/signDescriptor/ verifyDescriptor and manifest⇄descriptor adapters.
• mcp-server.js — minimal framework for well-behaved MCP servers. examples/bruce-lee/ is the reference server.
• client-http.js — v3. MCP streamable-http and SSE client. Experimental; McpHttpClient matches McpStdioClient interface.
• redact.js — auth-token and sensitive-value redaction helpers.