@vorim/sdk 3.0.2 → 3.2.0

package/dist/index.d.cts

@@ -52,6 +52,29 @@ interface AuditEventInput {
     error_code?: string;
     signature?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Replayable agent decision evidence (VAIP -02 schema fields).
+     *
+     * Stored and exported but NOT covered by the v0 canonical signature
+     * form. They will enter canonical bytes in v1 (RFC 8785 JCS) in a
+     * follow-up release. Until then, advisory.
+     *
+     * Use the helpers from this package to compute the hashes:
+     *   - {@link hashToolCatalogue}
+     *   - {@link hashSystemPrompt}
+     */
+    model_version?: string;
+    tool_catalogue_hash?: string;
+    system_prompt_hash?: string;
+    prev_event_hash?: string;
+    /**
+     * Canonical-form recipe the `signature` was computed over.
+     * Absent/null ↔ 'v0' (pipe-joined six-field form). Set to 'v1' for
+     * RFC 8785 JCS over the full event minus signature and canonical_form.
+     * The SDK sets this automatically when {@link VorimConfig.canonicalForm}
+     * is `"v1"`; you can also pass it on a per-event basis.
+     */
+    canonical_form?: 'v0' | 'v1';
 }
 interface TrustRecord {
     agent_id: string;
@@ -68,16 +91,239 @@ interface TrustRecord {
     last_active?: string;
 }
 
+/**
+ * Replayable agent decision evidence helpers.
+ *
+ * Canonical-form hashing for the VAIP -02 schema fields that the SDK
+ * attaches to audit events. The hashes recorded in audit_events.tool_catalogue_hash
+ * and audit_events.system_prompt_hash use these functions, so the bytes
+ * an auditor or counterparty reconstructs must match what the SDK produced.
+ *
+ * These helpers are intentionally separate from the signing path. The
+ * v0 canonical signature form (event_type|action|resource|input_hash|
+ * output_hash|result) does NOT cover model_version, tool_catalogue_hash,
+ * or system_prompt_hash. They will enter the canonical bytes in v1
+ * (RFC 8785 JCS) in a follow-up release.
+ *
+ * Stable across SDK versions: the canonical-form version is documented
+ * in CANONICAL_TOOL_CATALOGUE_VERSION. Future changes get a v2 etc;
+ * never edit the existing v1 logic, or already-recorded hashes lose
+ * their meaning.
+ */
+/**
+ * Canonical-form version for tool catalogue hashes produced by this SDK.
+ * Recorded in tool_catalogue_canon_version on the event metadata (when
+ * the metadata field is used) so verifiers know which hash recipe to
+ * reproduce. Increment ONLY if the algorithm changes in a way that
+ * would change the hash for the same logical catalogue.
+ */
+declare const CANONICAL_TOOL_CATALOGUE_VERSION: "v1";
+/**
+ * Minimum shape a tool needs for catalogue hashing. The framework
+ * integrations adapt their native tool objects to this shape before
+ * calling hashToolCatalogue.
+ */
+interface CatalogueTool {
+    /** The name the model sees and calls. Required. */
+    name: string;
+    /** Human-readable description shown to the model. Optional; absent ↔ empty string. */
+    description?: string;
+    /**
+     * JSON Schema describing the tool's input parameters. Optional;
+     * absent ↔ empty object `{}`. The schema gets RFC 8785 JCS-canonicalised
+     * before hashing so semantically-equivalent variations (key order,
+     * whitespace) produce the same hash.
+     */
+    schema?: Record<string, unknown> | null;
+}
+/**
+ * RFC 8785 JSON Canonicalization Scheme, sufficient subset for tool
+ * catalogue values.
+ *
+ * Rules:
+ *  - Object keys sorted lexicographically by UTF-16 code units (which
+ *    is what JS string comparison does naturally).
+ *  - No whitespace between tokens.
+ *  - Numbers: integers as integers, finite floats per ECMAScript
+ *    Number.prototype.toString. JCS forbids NaN and Infinity.
+ *  - Strings: JSON-escape using minimal set per RFC 8259 § 7.
+ *  - null, true, false, arrays: as JSON.stringify produces them, since
+ *    JSON.stringify already produces the canonical form for these.
+ *
+ * Not vendoring a full library because tool schemas don't carry
+ * non-integer numbers in practice and the JS spec for Number.toString
+ * happens to coincide with JCS § 3.2.2.2 for the integer case.
+ */
+declare function jcsCanonicalise(value: unknown): string;
+/**
+ * Hash a single tool definition. Returns `sha256:<hex>`.
+ *
+ * Canonical form (v1):
+ *   JCS-canonicalised JSON of `{name, description, schema}` where
+ *   absent fields substitute `description: ""` and `schema: {}`.
+ */
+declare function hashTool(tool: CatalogueTool): Promise<string>;
+/**
+ * Hash an entire tool catalogue. Returns `sha256:<hex>`.
+ *
+ * Reordering tools does NOT change the hash (tool hashes sorted
+ * lexicographically before concatenation). Adding, removing, or
+ * modifying a tool DOES change the hash.
+ *
+ * Per-tool hashing first means a verifier comparing two catalogue
+ * hashes that differ can also be given the per-tool hashes to
+ * identify which specific tool changed.
+ */
+declare function hashToolCatalogue(tools: CatalogueTool[]): Promise<string>;
+/**
+ * Hash a system prompt. Returns `sha256:<hex>`.
+ *
+ * The prompt is UTF-8 encoded and hashed verbatim — no normalisation.
+ * If a caller wants to ignore whitespace or comment differences, they
+ * should normalise before calling. The intent here is deterministic
+ * reproducibility, not semantic equivalence.
+ */
+declare function hashSystemPrompt(prompt: string): Promise<string>;
+/**
+ * Convenience: hash the previous event's canonical bytes for use in
+ * the prev_event_hash field of hash-chained ingest. Caller provides
+ * the canonical bytes (use canonicalPayloadV0 from the main module).
+ */
+declare function hashPreviousEvent(canonicalBytes: string): Promise<string>;
+/**
+ * Raw inputs the integration captures from the framework. Set by the
+ * integration's config; turned into hashes by {@link prepareReplayContext}.
+ */
+interface ReplayInputs {
+    /** Stable identifier for the model. E.g. `"anthropic:claude-opus-4-8"`. */
+    modelVersion?: string;
+    /** Tools available to the agent at call time. Hashed via {@link hashToolCatalogue}. */
+    tools?: CatalogueTool[];
+    /** System prompt active at call time. Hashed via {@link hashSystemPrompt}. */
+    systemPrompt?: string;
+}
+/**
+ * Pre-computed hashes ready to attach to audit events. The three keys
+ * match the audit_events column names.
+ */
+interface ReplayContext {
+    model_version?: string;
+    tool_catalogue_hash?: string;
+    system_prompt_hash?: string;
+}
+/**
+ * Compute replay context once from raw inputs. Use at integration
+ * setup time so each emit can attach the hashes without re-hashing.
+ *
+ * Returns an object suitable for spreading into an AuditEventInput:
+ *   `await vorim.emit({ ...event, ...replayContext })`
+ *
+ * If a field is absent in the inputs, it is absent in the result
+ * (not the empty string). That keeps the event lean.
+ */
+declare function prepareReplayContext(inputs: ReplayInputs): Promise<ReplayContext>;
+
 interface VorimConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
+    /**
+     * Auto-sign audit events with the agent's private key at emit time.
+     * Default true in v3.1+. Set to false to opt out globally.
+     * When enabled, the SDK signs the event using whichever private key was
+     * stored via {@link VorimSDK.useAgentKey} or returned by
+     * {@link VorimSDK.register}. Events for unknown agents pass through unsigned.
+     */
+    autoSign?: boolean;
+    /**
+     * Canonical form to use when signing. Default `"v0"` for backward-compat
+     * with `@vorim/sdk` 3.1.x. Set to `"v1"` to sign the full event object
+     * via RFC 8785 JCS, covering replayable-evidence fields (model_version,
+     * tool_catalogue_hash, system_prompt_hash, prev_event_hash). v1 events
+     * carry `canonical_form: "v1"` on the wire so the server can dispatch
+     * verification correctly.
+     */
+    canonicalForm?: 'v0' | 'v1';
+    /**
+     * Hash-chain events per agent so deletion of a single audit row
+     * becomes detectable. Default `false` (no chaining). When enabled,
+     * the SDK sets `prev_event_hash` on each event to SHA-256 of the
+     * previous event's canonical bytes for the same agent. The first
+     * event after enable / process restart has `prev_event_hash = null`,
+     * which the verifier reports as `chain_restart` (informational, not
+     * a failure). Chain integrity is checked by `@vorim/verify`.
+     */
+    chainEvents?: boolean;
 }
+/**
+ * VAIP v0 canonical bytes used by Vorim's per-event signing.
+ *
+ * Pipe-joined content fields with empty-string substitution for missing values.
+ * This is intentionally duplicated from `@vorim/shared-types` so the published
+ * SDK ships with zero runtime dependencies. A parity test in this package
+ * imports both definitions and asserts byte-exact equality across a fixture
+ * matrix, so they cannot drift silently.
+ *
+ * To upgrade the format, version the function (`canonicalPayloadV1`) — never
+ * edit this one. Old signatures must remain verifiable.
+ */
+declare function canonicalPayloadV0(event: AuditEventInput): string;
+/**
+ * VAIP v1 canonical bytes for audit-event signing (RFC 8785 JCS).
+ *
+ * Signs the full event object excluding `signature` (the field being
+ * computed) and `canonical_form` (metadata about the recipe). Unlike v0,
+ * v1 covers the replayable-evidence fields and the metadata field.
+ *
+ * Re-exports `jcsCanonicalise` from `./replay.js` which is the byte-exact
+ * twin of `@vorim/shared-types`' implementation. The cross-language parity
+ * script enforces equivalence with the Python SDK.
+ */
+declare function canonicalPayloadV1(event: AuditEventInput): string;
 declare class VorimSDK {
     private apiKey;
     private baseUrl;
     private timeout;
+    private autoSign;
+    private canonicalForm;
+    private chainEvents;
+    /**
+     * In-memory keyring mapping agent_id -> PEM-encoded Ed25519 private key.
+     * Populated automatically by register() and registerEphemeral(), or
+     * explicitly via useAgentKey(). Lost on process restart by design; the
+     * caller is responsible for durable key storage.
+     */
+    private agentKeys;
+    /**
+     * Per-agent hash of the last emitted event's canonical bytes. Used to
+     * populate prev_event_hash on the next emit when chainEvents is on.
+     * Empty string ↔ no previous event (chain restart). Reset by
+     * forgetAgentKey() so reusing an agent_id after revocation doesn't
+     * link to the old chain.
+     */
+    private lastEventHash;
+    /**
+     * Per-agent emit promise. Each new emit awaits the previous one so
+     * the chain is constructed in order. Concurrent emits to the same
+     * agent are serialised (correct); concurrent emits to different
+     * agents remain parallel (fast).
+     */
+    private chainLocks;
     constructor(config: VorimConfig);
+    /**
+     * Register a previously-issued agent keypair so this SDK instance can
+     * auto-sign events for it on emit. Use this when restoring an agent across
+     * process restarts: read the agent's private_key from durable storage,
+     * call useAgentKey(agentId, privateKey), and emit() will sign automatically.
+     */
+    useAgentKey(agentId: string, privateKeyPem: string): void;
+    /**
+     * Forget an agent's signing key (e.g. after revocation). Subsequent emit()
+     * calls for that agent will pass through unsigned unless a key is provided
+     * inline. Also clears the per-agent chain state — re-using the same
+     * agent_id after revocation does NOT link to the old chain.
+     */
+    forgetAgentKey(agentId: string): void;
     /**
      * Ping the Vorim API to verify connectivity and API key validity.
      * Returns { status, timestamp } on success, throws VorimError on failure.
@@ -89,6 +335,11 @@ declare class VorimSDK {
     /**
      * Register a new agent with Vorim AI.
      * Returns the agent identity and a private key (shown once).
+     *
+     * Side effect: the returned private_key is cached in this SDK instance's
+     * in-memory keyring so subsequent emit() calls for this agent auto-sign.
+     * The keyring is process-local; the caller is responsible for persisting
+     * the private_key to durable storage if the agent should survive restarts.
      */
     register(input: AgentRegistrationInput): Promise<AgentRegistrationResult>;
     /**
@@ -143,16 +394,58 @@ declare class VorimSDK {
     revokePermission(agentId: string, scope: PermissionScope): Promise<any>;
     /**
      * Emit an audit event for an agent action.
+     *
+     * By default (autoSign=true on the SDK), the event is signed with the
+     * agent's private key before it leaves the process. Set options.sign=false
+     * to skip signing (e.g. for testing). If the SDK has no private key for the
+     * event's agent_id, the event is sent unsigned and a warning is not
+     * raised — callers that require signing should check event.signature on
+     * the returned event after a round-trip, or use a server-side enforcement
+     * flag (VORIM_VERIFY_AUDIT_SIGNATURES).
      */
-    emit(event: AuditEventInput): Promise<{
+    emit(event: AuditEventInput, options?: {
+        sign?: boolean;
+    }): Promise<{
         ingested: number;
     }>;
     /**
-     * Emit a batch of audit events (up to 1,000).
+     * Emit a batch of audit events (up to 1,000). Each event is signed
+     * independently using its agent_id to look up the signing key. See
+     * {@link VorimSDK.emit} for signing behaviour and opt-out.
      */
-    emitBatch(events: AuditEventInput[]): Promise<{
+    emitBatch(events: AuditEventInput[], options?: {
+        sign?: boolean;
+    }): Promise<{
         ingested: number;
     }>;
+    /**
+     * Internal: prepare an event for transmission. Auto-signs if the SDK has a
+     * key for this agent and signing isn't explicitly opted out. Pre-existing
+     * signatures on the event are respected (caller-signed events are not
+     * re-signed). Per-agent failure is non-fatal: if signing throws, the event
+     * still sends unsigned so a single bad key doesn't break a batch.
+     *
+     * Canonical-form dispatch:
+     *   - If the event already carries `canonical_form`, that wins (caller
+     *     opted in/out for this specific event).
+     *   - Otherwise the SDK-level `canonicalForm` (config) applies.
+     *   - v0 signs the pipe-joined 6 fields. v1 signs the RFC 8785 JCS
+     *     bytes over the full event minus signature and canonical_form,
+     *     and the event goes on the wire with `canonical_form: "v1"`.
+     *
+     * Chain construction:
+     *   - When chainEvents is on, the event gets `prev_event_hash` set to
+     *     the SHA-256 of the previous event's canonical bytes for the
+     *     same agent, set BEFORE the signature is computed (so v1
+     *     signatures cover the chain link).
+     *   - Chain ops are serialised per-agent via `chainLocks` so
+     *     concurrent emits to the same agent build a deterministic chain.
+     */
+    private prepareEvent;
+    /** Serialise per-agent and apply chain hash + sign. */
+    private prepareEventChained;
+    /** Sign an event right now, no chain handling. */
+    private signEventNow;
     /**
      * Export a signed audit bundle for a date range.
      */
@@ -177,6 +470,9 @@ declare class VorimSDK {
     /**
      * Register an ephemeral agent with W3C did:key identity.
      * The agent auto-expires after the specified TTL.
+     *
+     * Side effect: the returned private_key is cached in this SDK instance's
+     * in-memory keyring (matching register()).
      */
     registerEphemeral(input: {
         capabilities: string[];
@@ -272,4 +568,4 @@ declare class VorimError extends Error {
 }
 declare function createVorim(config: VorimConfig): VorimSDK;
 
-export { type Agent, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, type PermissionCheckResult, type PermissionScope, type TrustRecord, type VorimConfig, VorimError, VorimSDK, createVorim as default };
+export { type Agent, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type TrustRecord, type VorimConfig, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };