@fluxpointstudios/orynq-sdk-tool-receipts 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import { ToolReceiptEvent, Visibility, TraceRun, TraceVerificationResult, TraceBundle } from '@fluxpointstudios/orynq-sdk-process-trace';
+import { KeyObject } from 'node:crypto';
+
+/**
+ * @fileoverview Helpers to record `tool-receipt` events into a trace (issue #60).
+ */
+
+/**
+ * Deterministically hash a request/response payload for the `request.hash` /
+ * `response.hash` commitments (canonical JSON, SHA-256 hex). Strings are hashed
+ * as-is; everything else is canonicalized first.
+ */
+declare function hashToolPayload(value: unknown): Promise<string>;
+interface AddToolReceiptOptions {
+    toolId: string;
+    /** Commitment to the request (use {@link hashToolPayload}). */
+    request: {
+        hash: string;
+    };
+    /** Commitment to the response, with an optional retained payload. */
+    response: {
+        hash: string;
+        payload?: unknown;
+    };
+    /** The independently-verifiable signed receipt. */
+    receipt: ToolReceiptEvent["receipt"];
+    /** Event visibility (default "private" — responses may carry PII). */
+    visibility?: Visibility;
+}
+/**
+ * Append a `tool-receipt` event to a span.
+ *
+ * @returns the recorded {@link ToolReceiptEvent} (with runtime fields).
+ */
+declare function addToolReceipt(run: TraceRun, spanId: string, opts: AddToolReceiptOptions): Promise<ToolReceiptEvent>;
+
+/**
+ * @fileoverview Signature-scheme verifiers for tool-call receipts (issue #60).
+ *
+ * Each verifier checks that `receipt.signature` is a valid signature over
+ * `receipt.signedPayload` for `receipt.signer`, per its scheme:
+ *
+ * - `http-message-signatures` — RFC 9421 (signature base provided as signedPayload)
+ * - `stripe-webhook` — Stripe `Stripe-Signature` HMAC-SHA256 (timestamped; freshness-checked)
+ * - `github-webhook` — GitHub `X-Hub-Signature-256` HMAC-SHA256 (no signed
+ *   timestamp; freshness-checked only when `params.timestamp` is recorded,
+ *   otherwise anti-replay rests on the bundle Merkle commitment)
+ * - `jws` — compact JWS / JWT (HS*, RS*, PS*, ES*, EdDSA)
+ *
+ * Symmetric secrets (webhooks, HS*) MUST be supplied out-of-band via the
+ * {@link ToolReceiptVerifyContext} — never embedded in the trace. Asymmetric
+ * *public* keys may be embedded in `receipt.params.publicKey`.
+ */
+
+type MaybePromise<T> = T | Promise<T>;
+/** Key/secret resolution + policy context for receipt verification. */
+interface ToolReceiptVerifyContext {
+    /** Verification keys/secrets keyed by `receipt.signer`. */
+    keys?: Record<string, string>;
+    /** Dynamic key/secret resolver (takes precedence over `keys`). */
+    resolveKey?: (event: ToolReceiptEvent) => MaybePromise<string | Uint8Array | undefined>;
+    /** Max age (seconds) for replay-protected schemes (Stripe). Default 300. */
+    toleranceSec?: number;
+    /** Epoch-seconds clock override (testing). */
+    nowSec?: number;
+    /**
+     * Optional per-signer expected-algorithm allow-list (defense-in-depth against
+     * algorithm confusion). When present for a signer, any receipt whose resolved
+     * `alg` is not listed is rejected — e.g. `{ "tee://oracle": ["EdDSA"] }` pins
+     * that signer to EdDSA so an attacker-set `alg:HS256` is refused.
+     */
+    keyAlgs?: Record<string, string[]>;
+    /**
+     * Accept a public key embedded in `receipt.params.publicKey` when no
+     * out-of-band key is configured. This is a CONVENIENCE for internal
+     * consistency checks only — it is NOT an authenticity guarantee, because the
+     * trace (and therefore the embedded key) is attacker-controlled. Default
+     * false; supply the signer's key via `keys`/`resolveKey` for a trustworthy
+     * verdict.
+     */
+    trustEmbeddedKeys?: boolean;
+}
+declare function verifyStripeReceipt(event: ToolReceiptEvent, ctx?: ToolReceiptVerifyContext): Promise<boolean>;
+declare function verifyGitHubReceipt(event: ToolReceiptEvent, ctx?: ToolReceiptVerifyContext): Promise<boolean>;
+declare function verifyJwsReceipt(event: ToolReceiptEvent, ctx?: ToolReceiptVerifyContext): Promise<boolean>;
+declare function verifyHttpMessageReceipt(event: ToolReceiptEvent, ctx?: ToolReceiptVerifyContext): Promise<boolean>;
+/**
+ * Read the signed call-binding context ({runId, requestHash}) from a self-signed
+ * JWS receipt's header, or `null` when the receipt is not a bound JWS. Because
+ * the header is part of the JWS signing input, these values are covered by the
+ * signature — lifting the receipt into another trace/request breaks the match.
+ */
+declare function jwsBindingContext(event: ToolReceiptEvent): {
+    runId: string;
+    requestHash?: string;
+} | null;
+
+/**
+ * @fileoverview Verification dispatch for tool-call receipts (issue #60).
+ *
+ * `verifyToolReceipts(bundle, ctx)` verifies every `tool-receipt` event in a
+ * bundle; `verifyTrace(bundle, ctx)` additionally runs the full process-trace
+ * `verifyBundle()` and folds the receipt result into its `checks` so a single
+ * call gives auditors "did the trace verify AND did every tool actually return
+ * what the wrapper claims".
+ */
+
+/** A verifier for a single receipt scheme. */
+type ToolReceiptSchemeVerifier = (event: ToolReceiptEvent, ctx?: ToolReceiptVerifyContext) => Promise<boolean>;
+/** Built-in verifiers keyed by `receipt.scheme`. */
+declare const BUILTIN_TOOL_RECEIPT_VERIFIERS: Record<string, ToolReceiptSchemeVerifier>;
+/** Per-receipt verification result. */
+interface ToolReceiptVerificationResult {
+    eventId: string;
+    toolId: string;
+    scheme: string;
+    signer: string;
+    verified: boolean;
+    /**
+     * True ONLY when the signature cryptographically binds this receipt to THIS
+     * trace's runId AND the recorded request hash (self-signed JWS anti-lie path,
+     * with a signed `orynqBinding.{runId,requestHash}` that both matched). A JWS
+     * with no binding, or one that binds only the runId, is `false` — the request
+     * is not authenticated. Always `false` for external webhook schemes
+     * (stripe/github/rfc9421): those prove authenticity of the response body but
+     * cannot cover our runId/request, so call-binding is not provable by the
+     * signature and request-attribution must not be inferred — anti-replay for them
+     * relies on the bundle Merkle commitment + the scheme's own timestamp window.
+     */
+    callBound: boolean;
+    /** When not verified, a short machine-readable reason. */
+    reason?: string;
+    error?: string;
+}
+/** Context for {@link verifyToolReceipts}; extends key resolution with custom schemes. */
+interface VerifyToolReceiptsContext extends ToolReceiptVerifyContext {
+    /** Register or override scheme verifiers (e.g. a custom/internal scheme). */
+    verifiers?: Record<string, ToolReceiptSchemeVerifier>;
+    /**
+     * The enclosing trace's run id. Self-signed JWS receipts commit to it (and to
+     * the request hash) so a genuine receipt cannot be lifted into another trace.
+     * {@link verifyToolReceipts} supplies it automatically from the bundle.
+     */
+    runId?: string;
+    /**
+     * When true, a receipt whose signature does not provably bind THIS call
+     * (runId + request hash) is `verified: false` with reason `call-binding-required`.
+     * Use this when request-attribution must be cryptographic: it rejects unbound
+     * JWS receipts and all webhook schemes (whose external signatures cannot cover
+     * our request). Default false — call-binding is reported via `callBound` but not
+     * required.
+     */
+    requireCallBinding?: boolean;
+}
+/** Extract all `tool-receipt` events from a bundle (ordered by seq). */
+declare function extractToolReceipts(bundle: TraceBundle): ToolReceiptEvent[];
+/** Verify a single tool-receipt event. Never throws — failures land in `error`. */
+declare function verifyToolReceipt(event: ToolReceiptEvent, ctx?: VerifyToolReceiptsContext): Promise<ToolReceiptVerificationResult>;
+/** Aggregate outcome over all tool receipts in a bundle. */
+interface ToolReceiptsVerifyOutcome {
+    valid: boolean;
+    errors: string[];
+    results: ToolReceiptVerificationResult[];
+}
+/** Verify every tool-receipt in a bundle. A trace with no receipts is `valid: true`. */
+declare function verifyToolReceipts(bundle: TraceBundle, ctx?: VerifyToolReceiptsContext): Promise<ToolReceiptsVerifyOutcome>;
+/** Combined result of {@link verifyTrace}. */
+interface VerifyTraceResult extends TraceVerificationResult {
+    toolReceipts: ToolReceiptsVerifyOutcome;
+}
+/**
+ * Verify the whole trace AND its tool receipts in one call. The receipt outcome
+ * is folded into `checks.toolReceiptsValid` (so `valid` reflects receipts too)
+ * and also returned in full under `toolReceipts`.
+ */
+declare function verifyTrace(bundle: TraceBundle, ctx?: VerifyToolReceiptsContext): Promise<VerifyTraceResult>;
+
+/**
+ * @fileoverview Signing-proxy helper — the "anti-lie" pattern (issue #60).
+ *
+ * Tools that do not sign their responses natively can be wrapped in a TEE/HSM-
+ * signed envelope so the wrapper's claim ("the tool returned X") becomes
+ * independently verifiable. This helper produces a JWS-signed
+ * {@link ToolReceiptEvent.receipt} from a tool response; pair it with
+ * `addToolReceipt` to record the receipt, and `verifyToolReceipts` to check it.
+ *
+ * @example
+ * ```typescript
+ * import { generateKeyPairSync } from "node:crypto";
+ * const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+ * const proxy = createSigningProxy({
+ *   signer: "tee://pricing-proxy",
+ *   alg: "EdDSA",
+ *   privateKey,
+ *   publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+ * });
+ * const receipt = proxy.sign({ price: 4200, currency: "usd" });
+ * await addToolReceipt(run, span.id, { toolId, request, response, receipt });
+ * ```
+ */
+
+/** JWS algorithms supported by the signing proxy. */
+type JwsAlg = "EdDSA" | "ES256" | "ES384" | "RS256" | "RS512" | "PS256" | "PS512" | "HS256";
+interface SigningProxyOptions {
+    /** Verifier-resolvable identity recorded as `receipt.signer` (URL / DID / keyId). */
+    signer: string;
+    alg: JwsAlg;
+    /** Private key (PEM or KeyObject) for asymmetric algorithms. */
+    privateKey?: string | KeyObject;
+    /** Shared secret for HS256. */
+    secret?: string;
+    /**
+     * Public key (PEM or JWK string) to embed in `receipt.params.publicKey` so a
+     * verifier can resolve it without out-of-band material. Safe to embed
+     * (public keys only).
+     */
+    publicKey?: string;
+    /**
+     * Call-binding context signed into the receipt header so a genuine receipt
+     * cannot be lifted into a different trace/request. Any signed value that
+     * disagrees with the enclosing trace is a hard verification failure. To make a
+     * receipt `callBound` (request cryptographically attributed), sign BOTH `runId`
+     * AND `requestHash` — binding only the runId scopes the trace but leaves the
+     * request unauthenticated, so the receipt verifies but is NOT `callBound`.
+     */
+    binding?: {
+        runId: string;
+        requestHash?: string;
+    };
+}
+interface SigningProxy {
+    /** Wrap a tool response in a JWS-signed receipt ready for `addToolReceipt`. */
+    sign(payload: unknown): ToolReceiptEvent["receipt"];
+}
+/**
+ * Create a signing proxy that turns unsigned tool responses into verifiable
+ * JWS receipts. Use a TEE/HSM-held key in production.
+ */
+declare function createSigningProxy(opts: SigningProxyOptions): SigningProxy;
+
+/**
+ * @summary Main entry point for @fluxpointstudios/orynq-sdk-tool-receipts.
+ *
+ * Verifiable tool-call receipts for the Orynq process-trace SDK (issue #60).
+ * Proves "the tool actually returned this response" — not just "the agent says
+ * the tool returned this response" — by independently verifying signed receipts
+ * recorded as `tool-receipt` events.
+ *
+ * Supported schemes: RFC 9421 HTTP Message Signatures, Stripe/GitHub webhook
+ * signatures, and generic JWS. Plus a signing-proxy helper to wrap tools that
+ * don't sign their responses natively (the "anti-lie" pattern).
+ *
+ * @example
+ * ```typescript
+ * import { addToolReceipt, hashToolPayload, verifyTrace } from "@fluxpointstudios/orynq-sdk-tool-receipts";
+ *
+ * await addToolReceipt(run, span.id, {
+ *   toolId: "stripe.charges.create",
+ *   request: { hash: await hashToolPayload(req) },
+ *   response: { hash: await hashToolPayload(res), payload: res },
+ *   receipt: { scheme: "stripe-webhook", signer: "acct_123", signature: sigHeader, signedPayload: rawBody },
+ * });
+ *
+ * const result = await verifyTrace(bundle, { keys: { acct_123: process.env.STRIPE_WEBHOOK_SECRET! } });
+ * // result.valid && result.toolReceipts.results[0].verified
+ * ```
+ */
+
+/** Package version. */
+declare const VERSION = "0.1.0";
+
+export { type AddToolReceiptOptions, BUILTIN_TOOL_RECEIPT_VERIFIERS, type JwsAlg, type SigningProxy, type SigningProxyOptions, type ToolReceiptSchemeVerifier, type ToolReceiptVerificationResult, type ToolReceiptVerifyContext, type ToolReceiptsVerifyOutcome, VERSION, type VerifyToolReceiptsContext, type VerifyTraceResult, addToolReceipt, createSigningProxy, extractToolReceipts, hashToolPayload, jwsBindingContext, verifyGitHubReceipt, verifyHttpMessageReceipt, verifyJwsReceipt, verifyStripeReceipt, verifyToolReceipt, verifyToolReceipts, verifyTrace };