CXP Protocol - TypeScript SDK

Context lifecycle, provenance, and governance for AI agent ecosystems.

Install

npm install cxp-protocol

Quick Start

import { CXPStore, Sensitivity, Fidelity } from 'cxp-protocol';

const store = new CXPStore();

// Register a governed document
const { co } = store.register({
  content: 'Patient: Maria Santos. Dx: NSTEMI.',
  type: 'document',
  sensitivity: Sensitivity.REGULATED,
  aclRead: ['clinician'],
  aclDerive: ['clinician'],
  regulatory: ['hipaa'],
  producer: 'ehr',
});

// Access control
store.fetch(co.uri, 'clinician');  // { granted: true, content: '...' }
store.fetch(co.uri, 'billing');    // { granted: false, error: 'GOV_DENIED' }

// Derive with governance composition
const { co: summary } = store.derive({
  sources: [co.uri],
  content: 'Summary: NSTEMI diagnosis, troponin elevated.',
  type: 'summary',
  producer: 'summarizer',
  method: 'llm',
  actorRole: 'clinician',
});
// summary inherits: REGULATED sensitivity, clinician ACL, HIPAA tag

// Verify provenance
const attest = store.attest(summary.uri);
// { valid: true, chainLength: 2, chain: [...] }

// Privacy scoping
store.scope(co.uri, Fidelity.REDACTED, 'clinician');
// Returns content with SSN/names redacted

With OAuth / JWT Authentication

import { CXPStore, CXPAuthStore } from 'cxp-protocol';

const store = new CXPStore();
const auth = new CXPAuthStore(store, {
  jwtSecret: process.env.JWT_SECRET!,
  issuer: 'cxp-server',
  audience: 'cxp-agents',
});

// Issue tokens for agents
const clinicianToken = auth.issueToken('agent-1', ['clinician'], 'hospital-a');
const billingToken = auth.issueToken('agent-2', ['billing'], 'hospital-a');

// Authenticated operations
const { co } = auth.register(clinicianToken, {
  content: 'Patient note with PHI',
  type: 'document',
  sensitivity: Sensitivity.REGULATED,
  aclRead: ['clinician'],
  regulatory: ['hipaa'],
  producer: 'ehr',
});

auth.fetch(clinicianToken, co.uri);  // granted
auth.fetch(billingToken, co.uri);    // GOV_DENIED

MCP Proxy (zero code changes)

import { CXPStore, CXPMCPProxy, Sensitivity } from 'cxp-protocol';

const store = new CXPStore();
const proxy = new CXPMCPProxy(store, {
  sensitivity: Sensitivity.REGULATED,
  regulatory: ['hipaa'],
  aclRead: ['clinician'],
  aclDerive: ['clinician'],
  actorRole: 'clinician',
});

// Intercept MCP traffic
const { registered } = proxy.interceptRequest(mcpRequest);
const { registered: response } = proxy.interceptResponse(mcpResponse, registered);
// Governance added transparently

OpenTelemetry Export

import { CXPStore, auditToSpans, OTLPHttpExporter } from 'cxp-protocol';

const store = new CXPStore();
// ... operations ...

const spans = auditToSpans(store.getAuditLog());
const exporter = new OTLPHttpExporter('http://localhost:4318/v1/traces');
await exporter.export(spans);

API Reference

CXPStore

| Method | Description | |--------|-------------| | register(opts) | Create governed context object | | fetch(uri, role) | Retrieve with access control | | derive(opts) | Create from sources with governance composition | | scope(uri, fidelity, role) | Privacy-scoped view (full/summary/redacted/aggregated/opaque) | | govern(uri, updates, actor) | Update governance policies | | attest(uri) | Verify provenance chain integrity | | discover(filters) | Find context objects | | invoke(target, handler, uri, role) | Execute tool/agent with governance | | revoke(uri, actor) | Revoke a context object |

Governance Composition (Theorem 1)

For DERIVE from sources {s1, ..., sn}:

• Sensitivity: max (never decreases)
• ACL: intersection (never widens)
• Regulatory: union (never drops obligations)

License

Apache 2.0