@brightbeamai/chap-coordinator 0.2.8

package/dist/index.d.cts

@@ -0,0 +1,175 @@
+import { C as CoordinatorOptions, a as Coordinator } from './api-C3nkEk-B.cjs';
+export { b as CoordinatorApi, c as CoordinatorError, d as CredentialVerifier, E as EscalationPolicyFn, H as Handler, I as IdFactory, P as PRIVILEGED_METHODS, R as ReviewDepthPolicyFn, e as RoutingPolicyFn, S as ScittReceiptVerifier, f as ScittSubmitter, T as TokenVerifier, g as call, m as makeApi } from './api-C3nkEk-B.cjs';
+export { MethodName, MethodParams, MethodResult, MethodTable } from './methods.cjs';
+export { MemoryStore, Store, WorkspaceRecord } from './storage/store.cjs';
+export { ArtefactId, ArtefactRoutingHints, AuditEntry, AuditListener, Deliberation, DeliberationVote, Envelope, Handoff, HandoffTaskItem, JsonPatchOp, Jwk, KeyRecord, Member, Mode, OverrideArtefact, ParticipantType, ParticipantUri, PauseScope, ReviewDecision, RouteDecisionArtefact, SnapshotArtefact, Task, TaskId, TaskRoutingHints, TaskState, WhisperPrompt, Workspace, WorkspaceId, WorkspaceState, modeLE } from './types.cjs';
+export { E, isValidEnvelope, rpcError } from './jsonrpc.cjs';
+export { PatchError, applyJsonPatch, diffJsonPatch } from './patch.cjs';
+import { KeyObject } from 'node:crypto';
+
+/**
+ * @brightbeamai/chap-coordinator/canonical
+ *
+ * Deterministic JSON canonicalisation for CHAP. CHAP signs and hashes the
+ * canonicalisation of envelopes.
+ *
+ * Follows RFC 8785 (JCS) for objects, arrays, strings, booleans, and null,
+ * with one deliberate restriction on numbers. RFC 8785 mandates the
+ * ECMAScript number-to-string algorithm, which is hard to reproduce
+ * byte-identically across languages; a subtle mismatch would make a chain
+ * written by one implementation fail verification against another. To make
+ * cross-implementation agreement provable rather than approximate, a CHAP
+ * canonical number MUST be an integer within the safe-integer range
+ * (abs value <= Number.MAX_SAFE_INTEGER). Non-integers and larger
+ * magnitudes are rejected: represent them as strings. The Python reference
+ * enforces the identical rule.
+ */
+declare const ZERO_HASH: string;
+/** Return the JCS canonical UTF-8 bytes for a JSON-compatible value. */
+declare function canonicalize(value: unknown): Buffer;
+/** Return ``sha256:<64-hex>`` digest of bytes. */
+declare function sha256Hex(data: Buffer | string): string;
+/** Convenience: content hash for an artefact payload via JCS. */
+declare function contentHash(content: unknown): string;
+
+/**
+ * @brightbeamai/chap-coordinator/crypto
+ *
+ * Ed25519 signing/verification for the security-signed/1.0 profile.
+ *
+ * Uses Node's built-in crypto (no external dependencies). Keys are
+ * represented as RFC 7517 JWKs with kty=OKP, crv=Ed25519.
+ */
+
+interface Jwk {
+    kty: "OKP";
+    crv: "Ed25519";
+    kid: string;
+    x: string;
+    d?: string;
+    use?: string;
+    alg?: string;
+}
+/**
+ * Deterministically derive a 32-byte Ed25519 seed from a participant URI.
+ * Demo / test only. production deployments supply real keys.
+ */
+declare function deriveSeed(uri: string): Buffer;
+/** Public key bytes (32 bytes) from a private key. */
+declare function publicKeyBytes(privateKey: KeyObject): Buffer;
+/** Public KeyObject from raw 32-byte Ed25519 public key. */
+declare function publicKeyFromRaw(raw: Buffer): KeyObject;
+/** Render a JWK from a Node private KeyObject. */
+declare function jwkFromPrivateKey(uri: string, key: KeyObject): Jwk;
+/** Sign canonical bytes; return ``ed25519:<kid>:<base64>``. */
+declare function signEnvelope(canonical: Buffer, privateKey: KeyObject, kid: string): string;
+/** Verify a CHAP sig string against canonical bytes and a public key. */
+declare function verifyEnvelope(canonical: Buffer, sigTag: string, publicKey: KeyObject): boolean;
+/** Parse a JWK x (base64url) into a Node public KeyObject. */
+declare function publicKeyFromJwk(jwk: Jwk): KeyObject;
+/** Demo helper: build a deterministic keypair + JWK for a URI. */
+declare function deriveKeypair(uri: string): {
+    privateKey: KeyObject;
+    jwk: Jwk;
+};
+
+/**
+ * Default routing policy factory.
+ *
+ * Returns a partial CoordinatorOptions configured with the three
+ * routing hooks (routingPolicy, reviewDepthPolicy, escalationPolicy)
+ * that the playground and demo use out of the box. Operators can
+ * override individual hooks by passing their own functions in
+ * CoordinatorOptions.
+ *
+ * The defaults shipped with the Coordinator (in profiles/routing.ts)
+ * implement the same logic; this factory exists so that the legacy
+ * call site can keep using:
+ *
+ *   new Coordinator({ ...makeDefaultPolicy(SENIOR_URI), ... })
+ *
+ * The seniorTarget argument is the URI auto-escalation routes to
+ * when no other target is supplied.
+ */
+
+declare function makeDefaultPolicy(seniorTarget: string): Pick<CoordinatorOptions, "routingPolicy" | "reviewDepthPolicy" | "escalationPolicy">;
+
+/**
+ * @brightbeamai/chap-coordinator/transports/wrap
+ *
+ * Inward integration helpers: turn an external tool/agent event into
+ * a CHAP envelope landing in a workspace's audit log. Library
+ * counterpart to the patterns described in
+ * ``integrations/CHAP-with-MCP.md`` and ``integrations/CHAP-with-A2A.md``.
+ *
+ * The outward transports let external clients drive a CHAP workspace.
+ * These helpers go the other direction: when work has already
+ * happened outside CHAP, wrap it so the audit log carries a faithful,
+ * citable record.
+ *
+ * Spec target: CHAP 0.2. MCP 2025-11-25. A2A 1.0.
+ */
+
+interface WrapMcpToolCallOptions {
+    /** Participant URI making the call. Must already be a workspace member. */
+    caller: string;
+    /** MCP tool name, e.g. ``"github.create_issue"``. */
+    tool: string;
+    /** Arguments passed to the MCP tool. */
+    args: Record<string, unknown>;
+    /** Return value from the MCP tool. */
+    result: unknown;
+    /** Optional MCP server identifier, e.g. "github". */
+    server?: string;
+    /** Override the default task kind ``"mcp_call:<tool>"``. */
+    taskKind?: string;
+    /** Optional routing hints attached to the CHAP task. */
+    routingHints?: Record<string, unknown>;
+    /** Optional confidence value attached to task.complete. */
+    confidence?: number | string;
+}
+interface WrapResult {
+    task_id: string;
+    input_hash: string;
+    output_hash: string;
+}
+/**
+ * Wrap a completed MCP tool call as a CHAP task pair.
+ *
+ * Emits ``task.create`` + ``task.complete`` envelopes into the
+ * workspace so the MCP call shows up as a first-class audit entry.
+ * The result artefact is the MCP tool's return value, plus a
+ * ``citations[]`` entry with the input/output hashes per
+ * ``integrations/CHAP-with-MCP.md`` §2.
+ */
+declare function wrapMcpToolCall(coord: Coordinator, workspace: string, options: WrapMcpToolCallOptions): WrapResult;
+interface WrapA2aExchangeOptions {
+    /** URI of the local bridge participant. Must be a workspace member. */
+    bridgeUri: string;
+    /** Identifier of the remote A2A agent. Recorded in the citation. */
+    remoteAgent: string;
+    /** The A2A message body sent outbound. */
+    sent: Record<string, unknown>;
+    /** The A2A message body received in response. */
+    received: Record<string, unknown>;
+    /** CHAP task kind. Default ``"a2a_exchange"``. */
+    taskKind?: string;
+    /** Optional routing hints attached to the task. */
+    routingHints?: Record<string, unknown>;
+    /** Optional confidence value attached to task.complete. */
+    confidence?: number | string;
+}
+interface WrapA2aResult {
+    task_id: string;
+    sent_hash: string;
+    received_hash: string;
+}
+/**
+ * Wrap a completed A2A message exchange as a CHAP task pair.
+ *
+ * Implements the bridge-participant pattern from
+ * ``integrations/CHAP-with-A2A.md`` §3 as a library helper.
+ */
+declare function wrapA2aMessageExchange(coord: Coordinator, workspace: string, options: WrapA2aExchangeOptions): WrapA2aResult;
+
+export { Coordinator, CoordinatorOptions, type Jwk as CryptoJwk, type WrapA2aExchangeOptions, type WrapA2aResult, type WrapMcpToolCallOptions, type WrapResult, ZERO_HASH, canonicalize, contentHash, deriveKeypair, deriveSeed, jwkFromPrivateKey, makeDefaultPolicy, publicKeyBytes, publicKeyFromJwk, publicKeyFromRaw, sha256Hex, signEnvelope, verifyEnvelope, wrapA2aMessageExchange, wrapMcpToolCall };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import { C as CoordinatorOptions, a as Coordinator } from './api-CmSvlIqO.js';
+export { b as CoordinatorApi, c as CoordinatorError, d as CredentialVerifier, E as EscalationPolicyFn, H as Handler, I as IdFactory, P as PRIVILEGED_METHODS, R as ReviewDepthPolicyFn, e as RoutingPolicyFn, S as ScittReceiptVerifier, f as ScittSubmitter, T as TokenVerifier, g as call, m as makeApi } from './api-CmSvlIqO.js';
+export { MethodName, MethodParams, MethodResult, MethodTable } from './methods.js';
+export { MemoryStore, Store, WorkspaceRecord } from './storage/store.js';
+export { ArtefactId, ArtefactRoutingHints, AuditEntry, AuditListener, Deliberation, DeliberationVote, Envelope, Handoff, HandoffTaskItem, JsonPatchOp, Jwk, KeyRecord, Member, Mode, OverrideArtefact, ParticipantType, ParticipantUri, PauseScope, ReviewDecision, RouteDecisionArtefact, SnapshotArtefact, Task, TaskId, TaskRoutingHints, TaskState, WhisperPrompt, Workspace, WorkspaceId, WorkspaceState, modeLE } from './types.js';
+export { E, isValidEnvelope, rpcError } from './jsonrpc.js';
+export { PatchError, applyJsonPatch, diffJsonPatch } from './patch.js';
+import { KeyObject } from 'node:crypto';
+
+/**
+ * @brightbeamai/chap-coordinator/canonical
+ *
+ * Deterministic JSON canonicalisation for CHAP. CHAP signs and hashes the
+ * canonicalisation of envelopes.
+ *
+ * Follows RFC 8785 (JCS) for objects, arrays, strings, booleans, and null,
+ * with one deliberate restriction on numbers. RFC 8785 mandates the
+ * ECMAScript number-to-string algorithm, which is hard to reproduce
+ * byte-identically across languages; a subtle mismatch would make a chain
+ * written by one implementation fail verification against another. To make
+ * cross-implementation agreement provable rather than approximate, a CHAP
+ * canonical number MUST be an integer within the safe-integer range
+ * (abs value <= Number.MAX_SAFE_INTEGER). Non-integers and larger
+ * magnitudes are rejected: represent them as strings. The Python reference
+ * enforces the identical rule.
+ */
+declare const ZERO_HASH: string;
+/** Return the JCS canonical UTF-8 bytes for a JSON-compatible value. */
+declare function canonicalize(value: unknown): Buffer;
+/** Return ``sha256:<64-hex>`` digest of bytes. */
+declare function sha256Hex(data: Buffer | string): string;
+/** Convenience: content hash for an artefact payload via JCS. */
+declare function contentHash(content: unknown): string;
+
+/**
+ * @brightbeamai/chap-coordinator/crypto
+ *
+ * Ed25519 signing/verification for the security-signed/1.0 profile.
+ *
+ * Uses Node's built-in crypto (no external dependencies). Keys are
+ * represented as RFC 7517 JWKs with kty=OKP, crv=Ed25519.
+ */
+
+interface Jwk {
+    kty: "OKP";
+    crv: "Ed25519";
+    kid: string;
+    x: string;
+    d?: string;
+    use?: string;
+    alg?: string;
+}
+/**
+ * Deterministically derive a 32-byte Ed25519 seed from a participant URI.
+ * Demo / test only. production deployments supply real keys.
+ */
+declare function deriveSeed(uri: string): Buffer;
+/** Public key bytes (32 bytes) from a private key. */
+declare function publicKeyBytes(privateKey: KeyObject): Buffer;
+/** Public KeyObject from raw 32-byte Ed25519 public key. */
+declare function publicKeyFromRaw(raw: Buffer): KeyObject;
+/** Render a JWK from a Node private KeyObject. */
+declare function jwkFromPrivateKey(uri: string, key: KeyObject): Jwk;
+/** Sign canonical bytes; return ``ed25519:<kid>:<base64>``. */
+declare function signEnvelope(canonical: Buffer, privateKey: KeyObject, kid: string): string;
+/** Verify a CHAP sig string against canonical bytes and a public key. */
+declare function verifyEnvelope(canonical: Buffer, sigTag: string, publicKey: KeyObject): boolean;
+/** Parse a JWK x (base64url) into a Node public KeyObject. */
+declare function publicKeyFromJwk(jwk: Jwk): KeyObject;
+/** Demo helper: build a deterministic keypair + JWK for a URI. */
+declare function deriveKeypair(uri: string): {
+    privateKey: KeyObject;
+    jwk: Jwk;
+};
+
+/**
+ * Default routing policy factory.
+ *
+ * Returns a partial CoordinatorOptions configured with the three
+ * routing hooks (routingPolicy, reviewDepthPolicy, escalationPolicy)
+ * that the playground and demo use out of the box. Operators can
+ * override individual hooks by passing their own functions in
+ * CoordinatorOptions.
+ *
+ * The defaults shipped with the Coordinator (in profiles/routing.ts)
+ * implement the same logic; this factory exists so that the legacy
+ * call site can keep using:
+ *
+ *   new Coordinator({ ...makeDefaultPolicy(SENIOR_URI), ... })
+ *
+ * The seniorTarget argument is the URI auto-escalation routes to
+ * when no other target is supplied.
+ */
+
+declare function makeDefaultPolicy(seniorTarget: string): Pick<CoordinatorOptions, "routingPolicy" | "reviewDepthPolicy" | "escalationPolicy">;
+
+/**
+ * @brightbeamai/chap-coordinator/transports/wrap
+ *
+ * Inward integration helpers: turn an external tool/agent event into
+ * a CHAP envelope landing in a workspace's audit log. Library
+ * counterpart to the patterns described in
+ * ``integrations/CHAP-with-MCP.md`` and ``integrations/CHAP-with-A2A.md``.
+ *
+ * The outward transports let external clients drive a CHAP workspace.
+ * These helpers go the other direction: when work has already
+ * happened outside CHAP, wrap it so the audit log carries a faithful,
+ * citable record.
+ *
+ * Spec target: CHAP 0.2. MCP 2025-11-25. A2A 1.0.
+ */
+
+interface WrapMcpToolCallOptions {
+    /** Participant URI making the call. Must already be a workspace member. */
+    caller: string;
+    /** MCP tool name, e.g. ``"github.create_issue"``. */
+    tool: string;
+    /** Arguments passed to the MCP tool. */
+    args: Record<string, unknown>;
+    /** Return value from the MCP tool. */
+    result: unknown;
+    /** Optional MCP server identifier, e.g. "github". */
+    server?: string;
+    /** Override the default task kind ``"mcp_call:<tool>"``. */
+    taskKind?: string;
+    /** Optional routing hints attached to the CHAP task. */
+    routingHints?: Record<string, unknown>;
+    /** Optional confidence value attached to task.complete. */
+    confidence?: number | string;
+}
+interface WrapResult {
+    task_id: string;
+    input_hash: string;
+    output_hash: string;
+}
+/**
+ * Wrap a completed MCP tool call as a CHAP task pair.
+ *
+ * Emits ``task.create`` + ``task.complete`` envelopes into the
+ * workspace so the MCP call shows up as a first-class audit entry.
+ * The result artefact is the MCP tool's return value, plus a
+ * ``citations[]`` entry with the input/output hashes per
+ * ``integrations/CHAP-with-MCP.md`` §2.
+ */
+declare function wrapMcpToolCall(coord: Coordinator, workspace: string, options: WrapMcpToolCallOptions): WrapResult;
+interface WrapA2aExchangeOptions {
+    /** URI of the local bridge participant. Must be a workspace member. */
+    bridgeUri: string;
+    /** Identifier of the remote A2A agent. Recorded in the citation. */
+    remoteAgent: string;
+    /** The A2A message body sent outbound. */
+    sent: Record<string, unknown>;
+    /** The A2A message body received in response. */
+    received: Record<string, unknown>;
+    /** CHAP task kind. Default ``"a2a_exchange"``. */
+    taskKind?: string;
+    /** Optional routing hints attached to the task. */
+    routingHints?: Record<string, unknown>;
+    /** Optional confidence value attached to task.complete. */
+    confidence?: number | string;
+}
+interface WrapA2aResult {
+    task_id: string;
+    sent_hash: string;
+    received_hash: string;
+}
+/**
+ * Wrap a completed A2A message exchange as a CHAP task pair.
+ *
+ * Implements the bridge-participant pattern from
+ * ``integrations/CHAP-with-A2A.md`` §3 as a library helper.
+ */
+declare function wrapA2aMessageExchange(coord: Coordinator, workspace: string, options: WrapA2aExchangeOptions): WrapA2aResult;
+
+export { Coordinator, CoordinatorOptions, type Jwk as CryptoJwk, type WrapA2aExchangeOptions, type WrapA2aResult, type WrapMcpToolCallOptions, type WrapResult, ZERO_HASH, canonicalize, contentHash, deriveKeypair, deriveSeed, jwkFromPrivateKey, makeDefaultPolicy, publicKeyBytes, publicKeyFromJwk, publicKeyFromRaw, sha256Hex, signEnvelope, verifyEnvelope, wrapA2aMessageExchange, wrapMcpToolCall };