@vorim/sdk 3.1.0 → 3.3.0

package/dist/index.d.ts

@@ -52,6 +52,99 @@ 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';
+    /**
+     * Per-event delegation context (VAIP -02 § 6). Populated by the
+     * server when the emitting agent is acting via a delegation chain;
+     * callers may also set these manually for events recorded outside
+     * the standard delegation flow. v1 signatures cover these fields.
+     */
+    on_behalf_of?: string;
+    delegator_agent_id?: string;
+    delegation_chain_id?: string;
+    delegation_depth?: number;
+}
+/**
+ * Claims structure for one VAIP -02 § 5 delegation link.
+ *
+ * Each delegation step in a chain is one of these objects, RFC 8785 JCS
+ * canonicalised and Ed25519-signed by the delegator. Mirrors the same
+ * type in `@vorim/shared-types`; duplicated here so the SDK ships zero
+ * runtime dependencies. Byte-equivalence with the shared definition is
+ * enforced by the cross-language parity script.
+ */
+interface DelegationLinkClaims {
+    v: 0;
+    type: 'vaip-delegation-link';
+    chain_id: string;
+    depth: number;
+    delegator: string;
+    delegate: string;
+    scopes: string[];
+    max_chain_depth: number;
+    valid_from: string;
+    valid_until: string | null;
+    parent_link_hash: string | null;
+}
+/**
+ * One step in an agent-to-agent identity delegation chain (VAIP -02 § 5).
+ *
+ * Returned by {@link VorimSDK.delegateToAgent} and the listing endpoints.
+ */
+interface AgentDelegationRecord {
+    /** Internal row id. */
+    id: string;
+    /** Public chain identifier (format `chain_<32hex>`). Stamped on
+     *  every audit event in this chain. */
+    publicChainId: string;
+    /** Organisation id. */
+    orgId: string;
+    /** Internal DB id of the delegator agent. */
+    delegatorAgentId: string;
+    /** Internal DB id of the delegate agent. */
+    delegateAgentId: string;
+    /** Public agent_id of the delegator (e.g. agid_acme_abc). */
+    delegatorAgentPublicId: string;
+    /** Public agent_id of the delegate. */
+    delegateAgentPublicId: string;
+    /** Scopes the delegate may exercise. */
+    scopesDelegated: string[];
+    /** How many further hops the delegate is permitted. */
+    maxChainDepth: number;
+    /** This step's depth from the root (root delegator step = 1). */
+    currentDepth: number;
+    /** Active / suspended / revoked / expired. */
+    status: 'active' | 'suspended' | 'revoked' | 'expired';
+    /** Parent delegation row (null for the root of an identity chain). */
+    parentDelegationId: string | null;
+    /** Public agent_id of the root principal of this chain. */
+    onBehalfOf: string;
+    /** ISO8601 creation timestamp. */
+    createdAt: string;
+    /** Optional ISO8601 expiry. */
+    validUntil: string | null;
 }
 interface TrustRecord {
     agent_id: string;
@@ -68,6 +161,138 @@ 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;
@@ -80,6 +305,25 @@ interface VorimConfig {
      * {@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.
@@ -94,11 +338,25 @@ interface VorimConfig {
  * 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
@@ -106,6 +364,21 @@ declare class VorimSDK {
      * 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
@@ -117,7 +390,8 @@ declare class VorimSDK {
     /**
      * 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.
+     * 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;
     /**
@@ -188,6 +462,97 @@ declare class VorimSDK {
      * Revoke a specific permission scope from an agent.
      */
     revokePermission(agentId: string, scope: PermissionScope): Promise<any>;
+    /**
+     * Delegate the right to act on this agent's behalf to another agent
+     * in the same org, with a strict subset of this agent's scopes.
+     *
+     * Multi-hop chains are supported up to depth 32. Scope subset is
+     * enforced at every hop. Audit events emitted by the delegate carry
+     * the chain context (`on_behalf_of`, `delegator_agent_id`,
+     * `delegation_chain_id`, `delegation_depth`) so a verifier walking
+     * the bundle can reconstruct the full chain.
+     *
+     * @example
+     * ```ts
+     * const chain = await vorim.delegateToAgent('agid_parent_abc', {
+     *   delegate_agent_id: 'agid_child_xyz',
+     *   scopes_delegated: ['agent:read', 'agent:execute'],
+     *   max_chain_depth: 1,        // delegate may make ONE further hop
+     *   valid_until: '2026-12-31T00:00:00Z',
+     * });
+     * console.log(chain.public_chain_id); // chain_<hex>
+     * ```
+     */
+    delegateToAgent(delegatorAgentId: string, input: {
+        delegate_agent_id: string;
+        scopes_delegated: PermissionScope[];
+        max_chain_depth?: number;
+        valid_until?: string;
+        /**
+         * Optional Ed25519-signed delegation link (VAIP -02 § 5). When
+         * provided, the server verifies the signature against the
+         * delegator's stored public key, persists alongside the chain
+         * row, and exports it in bundle delegation_tokens so the chain
+         * is offline-verifiable by `@vorim/verify`. Compute via
+         * {@link signDelegationLink} or set manually if signing
+         * elsewhere.
+         */
+        signed_link?: {
+            claims: DelegationLinkClaims;
+            signature: string;
+        };
+    }): Promise<AgentDelegationRecord>;
+    /**
+     * Sign a delegation link with the delegator's private key. Returns
+     * the signed link in the shape accepted by `delegateToAgent`'s
+     * `signed_link` field.
+     *
+     * The signature is Ed25519 over the RFC 8785 JCS-canonical bytes of
+     * the claims object. Same algorithm the server and `@vorim/verify`
+     * use for verification.
+     *
+     * Use this when the delegator's private key is in this SDK's
+     * keyring (i.e. set via `register()` or `useAgentKey()`).
+     *
+     * @example
+     * ```ts
+     * const signed = await vorim.signDelegationLink({
+     *   v: 0,
+     *   type: 'vaip-delegation-link',
+     *   chain_id: 'chain_abc',           // server returns this on first delegation
+     *   depth: 1,
+     *   delegator: 'agid_parent',
+     *   delegate: 'agid_child',
+     *   scopes: ['agent:read', 'agent:execute'],
+     *   max_chain_depth: 1,
+     *   valid_from: new Date().toISOString(),
+     *   valid_until: null,
+     *   parent_link_hash: null,
+     * });
+     * ```
+     */
+    signDelegationLink(claims: DelegationLinkClaims): Promise<{
+        claims: DelegationLinkClaims;
+        signature: string;
+    }>;
+    /**
+     * List active identity-chain entries this agent participates in
+     * (either as delegator or delegate). Useful for showing the current
+     * delegation graph in an admin UI.
+     */
+    listAgentDelegations(agentId: string): Promise<AgentDelegationRecord[]>;
+    /**
+     * Walk a delegation chain by its public id. Returns the full chain
+     * in depth order.
+     */
+    getDelegationChain(agentId: string, chainId: string): Promise<AgentDelegationRecord[]>;
+    /**
+     * Revoke this agent's delegation in a given chain. Cascades to all
+     * descendants beneath this agent's depth in the chain.
+     */
+    revokeAgentDelegation(agentId: string, chainId: string): Promise<{
+        revoked: number;
+    }>;
     /**
      * Emit an audit event for an agent action.
      *
@@ -220,8 +585,28 @@ declare class VorimSDK {
      * 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.
      */
@@ -344,4 +729,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, canonicalPayloadV0, createVorim as default };
+export { type Agent, type AgentDelegationRecord, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type DelegationLinkClaims, 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 };