@vorim/sdk 3.0.2 → 3.2.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -1,14 +1,147 @@
+// src/replay.ts
+var CANONICAL_TOOL_CATALOGUE_VERSION = "v1";
+function jcsCanonicalise(value) {
+  if (value === null) return "null";
+  if (value === true) return "true";
+  if (value === false) return "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("jcsCanonicalise: NaN and Infinity are not JCS-valid");
+    }
+    return value.toString();
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(jcsCanonicalise).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    const parts = keys.map((k) => {
+      return JSON.stringify(k) + ":" + jcsCanonicalise(value[k]);
+    });
+    return "{" + parts.join(",") + "}";
+  }
+  throw new Error(`jcsCanonicalise: unsupported value type: ${typeof value}`);
+}
+async function sha256Hex(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const buf = await subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  const nodeCrypto = await import("crypto");
+  return nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+}
+async function hashTool(tool) {
+  const normalised = {
+    name: tool.name,
+    description: tool.description ?? "",
+    schema: tool.schema ?? {}
+  };
+  const hex = await sha256Hex(jcsCanonicalise(normalised));
+  return `sha256:${hex}`;
+}
+async function hashToolCatalogue(tools) {
+  if (tools.length === 0) {
+    return `sha256:${await sha256Hex("[]")}`;
+  }
+  const perTool = await Promise.all(tools.map(hashTool));
+  perTool.sort();
+  const hex = await sha256Hex(perTool.join(""));
+  return `sha256:${hex}`;
+}
+async function hashSystemPrompt(prompt) {
+  const hex = await sha256Hex(prompt);
+  return `sha256:${hex}`;
+}
+async function hashPreviousEvent(canonicalBytes) {
+  const hex = await sha256Hex(canonicalBytes);
+  return `sha256:${hex}`;
+}
+async function prepareReplayContext(inputs) {
+  const ctx = {};
+  if (inputs.modelVersion) ctx.model_version = inputs.modelVersion;
+  if (inputs.tools) ctx.tool_catalogue_hash = await hashToolCatalogue(inputs.tools);
+  if (inputs.systemPrompt) ctx.system_prompt_hash = await hashSystemPrompt(inputs.systemPrompt);
+  return ctx;
+}
+
 // src/index.ts
-var SDK_VERSION = "3.0.2";
+var SDK_VERSION = true ? "3.2.0" : "0.0.0";
 var USER_AGENT = `vorim-sdk/${SDK_VERSION}`;
+function canonicalPayloadV0(event) {
+  return [
+    event.event_type,
+    event.action,
+    event.resource ?? "",
+    event.input_hash ?? "",
+    event.output_hash ?? "",
+    event.result
+  ].join("|");
+}
+function canonicalPayloadV1(event) {
+  const { signature: _sig, canonical_form: _cf, ...rest } = event;
+  return jcsCanonicalise(rest);
+}
 var VorimSDK = class {
   apiKey;
   baseUrl;
   timeout;
+  autoSign;
+  canonicalForm;
+  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.
+   */
+  agentKeys = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  lastEventHash = /* @__PURE__ */ new Map();
+  /**
+   * 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).
+   */
+  chainLocks = /* @__PURE__ */ new Map();
   constructor(config) {
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl || "https://api.vorim.ai").replace(/\/$/, "") + "/v1";
     this.timeout = config.timeout || 1e4;
+    this.autoSign = config.autoSign !== false;
+    this.canonicalForm = config.canonicalForm ?? "v0";
+    this.chainEvents = config.chainEvents ?? false;
+  }
+  /**
+   * 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, privateKeyPem) {
+    this.agentKeys.set(agentId, privateKeyPem);
+  }
+  /**
+   * 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) {
+    this.agentKeys.delete(agentId);
+    this.lastEventHash.delete(agentId);
+    this.chainLocks.delete(agentId);
   }
   // ─── Health Check ────────────────────────────────────────────────
   /**
@@ -27,9 +160,18 @@ var VorimSDK = class {
   /**
    * 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.
    */
   async register(input) {
-    return this.post("/agents", input);
+    const result = await this.post("/agents", input);
+    if (result?.agent?.agent_id && result?.private_key) {
+      this.agentKeys.set(result.agent.agent_id, result.private_key);
+    }
+    return result;
   }
   /**
    * Verify an agent's identity via the public Trust API.
@@ -91,15 +233,100 @@ var VorimSDK = class {
   // ─── Audit ────────────────────────────────────────────────────────
   /**
    * 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).
+   */
+  async emit(event, options) {
+    const prepared = await this.prepareEvent(event, options?.sign);
+    return this.post("/audit/events", { events: [prepared] });
+  }
+  /**
+   * 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.
    */
-  async emit(event) {
-    return this.post("/audit/events", { events: [event] });
+  async emitBatch(events, options) {
+    const prepared = await Promise.all(events.map((e) => this.prepareEvent(e, options?.sign)));
+    return this.post("/audit/events", { events: prepared });
   }
   /**
-   * Emit a batch of audit events (up to 1,000).
+   * 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.
    */
-  async emitBatch(events) {
-    return this.post("/audit/events", { events });
+  async prepareEvent(event, signOverride) {
+    const shouldSign = signOverride ?? this.autoSign;
+    if (!shouldSign && !this.chainEvents) return event;
+    if (this.chainEvents) {
+      return this.prepareEventChained(event, shouldSign);
+    }
+    if (!shouldSign) return event;
+    if (event.signature) return event;
+    return this.signEventNow(event, shouldSign);
+  }
+  /** Serialise per-agent and apply chain hash + sign. */
+  async prepareEventChained(event, shouldSign) {
+    const agentId = event.agent_id;
+    const prior = this.chainLocks.get(agentId) ?? Promise.resolve();
+    let release;
+    const next = new Promise((r) => {
+      release = r;
+    });
+    this.chainLocks.set(agentId, prior.then(() => next));
+    await prior;
+    try {
+      const prev = this.lastEventHash.get(agentId);
+      const eventWithPrev = prev ? { ...event, prev_event_hash: prev } : event;
+      const prepared = shouldSign && !eventWithPrev.signature ? await this.signEventNow(eventWithPrev, shouldSign) : eventWithPrev;
+      const wireForm = prepared.canonical_form ?? "v0";
+      const bytes = wireForm === "v1" ? canonicalPayloadV1(prepared) : canonicalPayloadV0(prepared);
+      try {
+        this.lastEventHash.set(agentId, await hashPreviousEvent(bytes));
+      } catch {
+        this.lastEventHash.delete(agentId);
+      }
+      return prepared;
+    } finally {
+      release();
+    }
+  }
+  /** Sign an event right now, no chain handling. */
+  async signEventNow(event, _shouldSign) {
+    const key = this.agentKeys.get(event.agent_id);
+    if (!key) return event;
+    const form = event.canonical_form ?? this.canonicalForm;
+    try {
+      const withForm = form === "v0" ? event : { ...event, canonical_form: "v1" };
+      const payload = form === "v1" ? canonicalPayloadV1(withForm) : canonicalPayloadV0(withForm);
+      const signature = await this.sign(payload, key);
+      return { ...withForm, signature };
+    } catch {
+      return event;
+    }
   }
   /**
    * Export a signed audit bundle for a date range.
@@ -130,9 +357,17 @@ var VorimSDK = class {
   /**
    * 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()).
    */
   async registerEphemeral(input) {
-    return this.post("/agents/ephemeral", input);
+    const result = await this.post("/agents/ephemeral", input);
+    const agentId = result?.agent?.agent_id ?? result?.did_key;
+    if (agentId && result?.private_key) {
+      this.agentKeys.set(agentId, result.private_key);
+    }
+    return result;
   }
   // ─── Credential Delegation ──────────────────────────────────────────
   /**
@@ -283,13 +518,25 @@ var VorimError = class extends Error {
     this.details = details;
     this.name = "VorimError";
   }
+  status;
+  code;
+  details;
 };
 function createVorim(config) {
   return new VorimSDK(config);
 }
 export {
+  CANONICAL_TOOL_CATALOGUE_VERSION,
   VorimError,
   VorimSDK,
-  createVorim as default
+  canonicalPayloadV0,
+  canonicalPayloadV1,
+  createVorim as default,
+  hashPreviousEvent,
+  hashSystemPrompt,
+  hashTool,
+  hashToolCatalogue,
+  jcsCanonicalise,
+  prepareReplayContext
 };
 //# sourceMappingURL=index.js.map