@hesohq/node 0.4.3 → 0.5.0-dev.101

package/index.d.ts

@@ -72,9 +72,75 @@ export declare function verify(receiptBytes: Buffer | Uint8Array | string): Acti
 /** Verify a receipt AND report its trusted-time status separately. */
 export declare function verifyWithTime(receiptBytesInput: Buffer | Uint8Array | string): ActionVerdictWithTime
 /**
- * Verify a receipt AND re-derive its ERT classification from the embedded taxonomy.
- * Uses heso-engine's ClassifyReDeriver (embedded taxonomy). Only available
- * when the `process` feature is enabled (pulls heso-engine).
+ * The base verdict + the rendered signed metrics + the offline-recomputed cost.
+ *
+ * `verdict` / `trustLevel` are exactly what [`verify`] returns. The metric fields
+ * are the SIGNED values (the closed `status` / `token_source` enums rendered to
+ * their wire snake_case strings). `recomputedCostMicros` / `costDisplay` are
+ * RECOMPUTED from the rate card the caller passed in — `priced == false` (and
+ * both absent) when that card does not price the model; never a guessed figure.
+ * `cardIdMatches` tells the reader whether the card handed in is the one the
+ * receipt actually named.
+ */
+export interface MetricsVerdict {
+  /** The base `ActionOutcome` verdict tag (`"Valid"`, `"HashMismatch"`, …). */
+  verdict: string
+  /** The re-derived trust level (`"L0"`/`"L1"`); `""` unless `verdict == "Valid"`. */
+  trustLevel: string
+  /** Whether the receipt carried a signed `metrics` block. */
+  hasMetrics: boolean
+  /** Wall-clock duration in whole milliseconds. */
+  durationMs?: number
+  /** Execution-outcome class, wire snake_case (`"ok"`, `"server_error"`, …). */
+  status?: string
+  /** Transport status code, when one applied. */
+  statusCode?: number
+  /** Provider-reported (or estimated) input tokens. */
+  tokensIn?: number
+  /** Provider-reported (or estimated) output tokens. */
+  tokensOut?: number
+  /** Token-count source, wire snake_case (`"provider_reported"`/`"estimated"`). */
+  tokenSource?: string
+  /** Request bytes sent, when the transport exposed it. */
+  bytesIn?: number
+  /** Response bytes received, when the transport exposed it. */
+  bytesOut?: number
+  /** Transport-level retries before this outcome. */
+  retries?: number
+  /** The rate-card id AS NAMED in the signed receipt. */
+  rateCardId?: string
+  /** The `provider/model` key derived from the signed `action.fields`. */
+  modelKey?: string
+  /** Recomputed cost in micro-USD (`BigInt`); absent when not priced. */
+  recomputedCostMicros?: bigint
+  /** Recomputed cost as a 6-decimal display string; absent when not priced. */
+  costDisplay?: string
+  /** `true` iff the model is priced by the passed-in card. */
+  priced: boolean
+  /** Whether the passed-in card is the one the receipt named. */
+  cardIdMatches: boolean
+}
+/**
+ * Verify a single `ActionReceipt` AND render its signed metrics + recompute cost
+ * from the passed-in public rate card — the node mirror of the WASM
+ * `verifyActionReceiptWithRates`.
+ *
+ * Runs the EXISTING offline verify for the base outcome + trust level (so that
+ * path is unchanged), then renders the signed metrics and recomputes the cost via
+ * the SHARED `heso_action::metrics_view` glue. Never throws on a malformed receipt
+ * or card — those degrade to `has_metrics: false` / `priced: false` exactly as the
+ * WASM export does. The cost render is purely informational and NEVER masks a
+ * verify failure: a tampered metric flips the `action_hash`, so `verdict` is a
+ * non-`Valid` tag while the (meaningless) recompute still reflects whatever bytes
+ * are present — the caller branches on `verdict`, never the dollar figure.
+ *
+ * `receipt_bytes`   — the raw `ActionReceipt` JSON bytes (Buffer/Uint8Array/string).
+ * `rate_card_json`  — the public rate-card JSON the cost is recomputed from.
+ */
+export declare function verifyWithRates(receiptBytes: Buffer | Uint8Array | string, rateCardJson: string): MetricsVerdict
+/**
+ * Verify a receipt AND re-derive its ERT classification from the embedded taxonomy
+ * (heso-engine's ClassifyReDeriver). Only available when `process` is enabled.
  */
 export declare function verifyRederiving(receiptBytesInput: Buffer | Uint8Array | string): ActionVerdict
 /**
@@ -126,6 +192,74 @@ export declare function verifyApprovalToken(token: Buffer, actionCanonical: Buff
  * `now_unix_secs`       — current time as BigInt Unix seconds
  */
 export declare function verifyDelegation(wire: Buffer, registeredOperatorKey: Buffer, actionHash: Buffer, approvalToken: Buffer, requiredScope: string, requiredDecision: string, nowUnixSecs: bigint): VerifiedDelegation
+/**
+ * The kind-tagged verdict of [`verify_commitment`]. `verdict` is one of
+ * `"Valid"`, `"InvalidSignature"`, `"FingerprintMismatch"`, `"WrongAlgorithm"`,
+ * `"Malformed"`; the cloud appends ONLY on `"Valid"`. `signer_fpr` carries the
+ * recomputed `blake3(pubkey)` fingerprint (only meaningful on `"Valid"`).
+ */
+export interface CommitmentVerdict {
+  verdict: string
+  signerFpr: string
+}
+/**
+ * REJECT-MORE-ONLY. Verify a detached commitment-envelope signature received by
+ * the cloud: parse the envelope JSON bytes, re-canonicalize VIA THE KERNEL,
+ * `verify_strict` the detached Ed25519 signature under
+ * `COMMITMENT_SIGNING_DOMAIN`, and confirm the recomputed commitment fingerprint
+ * (`blake3(pubkey)`) equals `claimedSignerFpr`. Produces ZERO new canonical/
+ * signed bytes. Never throws — every outcome (including malformed input) is a
+ * kind-tagged [`CommitmentVerdict`] so the caller fails closed on any
+ * non-`"Valid"`.
+ *
+ * `envelopeBytes`     — the envelope as JSON on the wire (Buffer)
+ * `operatorPubkeyB64` — the operator Ed25519 public key (base64 standard)
+ * `detachedSigB64`    — the detached Ed25519 signature (base64 standard)
+ * `claimedSignerFpr`  — the wire `signer_fpr` (`blake3(pubkey)` 64-hex)
+ */
+export declare function verifyCommitment(envelopeBytes: Buffer, operatorPubkeyB64: string, detachedSigB64: string, claimedSignerFpr: string): CommitmentVerdict
+/**
+ * PURE. Return the RFC-8785 (JCS) canonical bytes of a commitment envelope JSON
+ * string — the exact bytes the detached operator signature is computed over
+ * (after the `COMMITMENT_SIGNING_DOMAIN` prefix). Delegates to the single kernel
+ * JCS impl; never re-canonicalizes. Throws `[MALFORMED]` if the JSON does not
+ * parse as a `CommitmentEnvelope` and `[CANON]` if it cannot be canonicalized.
+ */
+export declare function commitmentEnvelopeCanonicalBytes(envelopeJson: string): Buffer
+/**
+ * The **commitment fingerprint** of an Ed25519 public key: `blake3(raw_pubkey)`,
+ * the full 32-byte digest, lowercase 64-hex, NO prefix. This is the value the
+ * producer puts in the wire `signer_fpr` and the cloud joins `approver_keys` on.
+ * It is DISTINCT from [`signer_fingerprint`] (the `heso:`-prefixed Grade-0
+ * fingerprint). Throws `[MALFORMED]` if `pubkeyB64` is not base64 of 32 bytes.
+ */
+export declare function commitmentFingerprint(pubkeyB64: string): string
+/**
+ * The `heso:`-prefixed Grade-0 **signer fingerprint** of an Ed25519 public key
+ * (`heso_verify::signer_fingerprint`). This is the identity-tier fingerprint —
+ * NOT the commitment fingerprint (see [`commitment_fingerprint`]). Exposed here
+ * because it is otherwise unexposed in every binding and other surfaces need it.
+ * Returns `null` when `pubkeyB64` is not a valid 32-byte Ed25519 key.
+ */
+export declare function signerFingerprint(pubkeyB64: string): string | null
+/**
+ * Stamp the cross-receipt chain block (`session_id`, `seq`, `prev_receipt_hash`)
+ * into an `ActionContent` BEFORE it is signed, then recompute its `action_hash`
+ * so the returned content is ready to sign — the producer-side helper that closes
+ * the JS verifiable-chain gap (CORE-WIRE design §A.4).
+ *
+ * `contentJson`     — the unstamped `ActionContent` JSON
+ * `sessionId`       — the chain/session this action is bound to
+ * `prevContentJson` — the predecessor receipt's `ActionContent` JSON, or `null`
+ *                     for genesis. The link hash + next `seq` are COMPUTED from
+ *                     it via the kernel's `link_hash` rule (matching `derive.py`).
+ *
+ * CRYPTO-SAFETY: stamping the chain block changes `action_canonical_bytes` →
+ * `action_hash` → the operator signature. This is a SUCCESS-PATH byte change. It
+ * is invoked ONLY for chained sessions; a standalone receipt (no call here) stays
+ * byte-identical to the existing standalone goldens.
+ */
+export declare function bindIntoChainJs(contentJson: string, sessionId: string, prevContentJson?: string | undefined | null): Buffer
 /**
  * Verify an ordered array of ActionReceipts as a tamper-evident chain.
  * Input: array of Buffers (one per receipt) OR a JSON string of an array.
@@ -155,6 +289,49 @@ export declare function verifyConsistencyJs(oldSize: number, oldRootHex: string,
 export declare function verifyAuditChain(bytes: Buffer | string): boolean
 /** Return the hex hash of the embedded taxonomy (golden: 9f3bbaaf…). */
 export declare function taxonomyHash(): string
+/**
+ * The derived ERT a `classify` probe returns — the structural classification of
+ * observed facts against the taxonomy. Read-only and advisory: it signs/mints
+ * nothing and touches NO canonical/signed bytes (the same role as the PyO3
+ * `classify`). The string fields are the `snake_case` wire spellings.
+ */
+export interface ClassifyErt {
+  /** The matched taxonomy resource class id (e.g. `payment_endpoint`). */
+  resourceClass: string
+  /** The resource effect (`read_only`/`mutating`/`destructive`/…). */
+  effect: string
+  /** The egress lane (`none`/`internal`/`external`/…). */
+  egress: string
+  /** The observability lane. */
+  observability: string
+  /** The coarse verb wire spelling (`delete`/`payment`/`account_change`/…). */
+  coarseVerb: string
+}
+/**
+ * Classify observed facts against the taxonomy and return the derived ERT.
+ *
+ * `signal_hints_json`: JSON-encoded `SignalHints` (Buffer, Uint8Array, or string)
+ * — the same wire shape as the `signal` field in `ProcessInput`. The target host
+ * is read out-of-band from a custom top-level `host` JSON key (SignalHints itself
+ * has no host field), exactly as the PyO3 `classify` twin does.
+ * `taxonomy_src`: pass `null` for the embedded taxonomy (the pinned
+ * `9f3bbaaf…` anchor), or TOML bytes to classify against a custom taxonomy.
+ *
+ * PURE READ-ONLY: this is an advisory probe — it signs/mints nothing and touches
+ * no canonical/signed bytes. It mirrors the fixed PyO3 `classify` byte-for-byte:
+ * the recorded enum hints (`effect`/`origin`/`observed_via`) are lowered via the
+ * SAME `Effect::parse`/`Origin::parse`/`ObservedVia::parse` the engine uses, so an
+ * unrecognized value parses to `None` (never an invented/relaxed lane). Only
+ * available with the `process` feature (it links `heso-engine`).
+ */
+export declare function classify(signalHintsJson: Buffer | Uint8Array | string, taxonomySrc?: Buffer | undefined | null): ClassifyErt
+/**
+ * True when a coarse verb wire spelling trips the credential floor's
+ * "destructive" lane — the LOCKED set `{delete, payment, account_change}`. The
+ * single source of this mapping for JS callers, mirroring the PyO3 helper so the
+ * two bindings agree. Pure read-only.
+ */
+export declare function isDestructive(coarseVerb: string): boolean
 /** Destructively redact fields and return the modified fields JSON. */
 export declare function redactDestructiveJs(fieldsJson: string, fieldPaths: Array<string>): string
 /**
@@ -162,6 +339,17 @@ export declare function redactDestructiveJs(fieldsJson: string, fieldPaths: Arra
  * `salts` is an array of 32-byte Buffers (one per field, in order).
  */
 export declare function redactCommitJs(fieldsJson: string, fieldPaths: Array<string>, salts: Array<Buffer>): RedactCommitResult
+/**
+ * Verify a single commit-and-reveal field reveal against its signed redaction
+ * marker: recompute `BLAKE3(salt ++ field_path ++ value)` and check it equals
+ * `marker.commitment`. Pure (no OsRng, no filesystem); returns a bool, never
+ * throws on a mismatch. The Node half of "reveal-and-prove a redacted field".
+ *
+ * `reveal_json` — a `FieldReveal`: `{ field_path, salt_hex, value_json }`.
+ * `marker_json` — the matching `RedactionMarker` from the signed receipt's
+ *                 `content.redaction.markers`.
+ */
+export declare function verifyRevealJs(revealJson: string, markerJson: string): boolean
 /**
  * Construct an OperatorKey from a 32-byte seed (OsRng-free, deterministic).
  * The preferred/documented entry point.
@@ -202,10 +390,16 @@ export declare function processAction(processInputJson: Buffer | Uint8Array | st
  * returned ONLY if it opens `Valid(L1)`; any other verdict is surfaced as an
  * error rather than handing back a receipt the offline verifier would reject.
  *
- * Returns the serialized ActionReceipt JSON bytes. Only available with `process`
- * (loads a key from the filesystem; never wasm-reachable).
+ * Returns the serialized ActionReceipt JSON bytes WITH the kernel-signed
+ * commitment block spliced in as a top-level `commitment` sibling (the same shape
+ * the engine `process` path emits, and the shape the SDK finalize consumer lifts
+ * via `receipt.get("commitment")`). The commitment is signed over the FINAL L1
+ * body by the SAME operator key — the SDK never holds the key (CORE-WIRE design
+ * §0.2). `chainHead` is the prior chain head this commitment links to (the SDK
+ * reads it off its local chain); absent/empty defaults to genesis. Only available
+ * with `process` (loads a key from the filesystem; never wasm-reachable).
  */
-export declare function assembleL1FromParts(suspendedContentJson: string, approverRecordJson: string, approverPubkeyB64: string, coSigB64: string, projectRoot: string, keyPassphrase?: string | undefined | null, relayedAnchorJson?: string | undefined | null): Buffer
+export declare function assembleL1FromParts(suspendedContentJson: string, approverRecordJson: string, approverPubkeyB64: string, coSigB64: string, projectRoot: string, keyPassphrase?: string | undefined | null, relayedAnchorJson?: string | undefined | null, chainHead?: string | undefined | null): Buffer
 /**
  * Assemble a complete multi-approver k-of-n QUORUM ActionReceipt from a suspended
  * L0 body, the gate's `threshold` + `roster`, and the per-approver detached
@@ -224,10 +418,54 @@ export declare function assembleL1FromParts(suspendedContentJson: string, approv
  * `parts_json` is a JSON array of `{ record, approverPubkeyB64, coSigB64 }`
  * objects. `roster_json` is a JSON array of base64 approver public keys.
  *
- * Returns the serialized ActionReceipt JSON bytes. Only available with `process`
- * (loads a key from the filesystem; never wasm-reachable).
+ * Returns the serialized ActionReceipt JSON bytes WITH the kernel-signed commitment
+ * block spliced in as a top-level `commitment` sibling (the same shape the engine
+ * `process` path emits, and the shape the SDK finalize consumer lifts via
+ * `receipt.get("commitment")`). The commitment is signed over the FINAL quorum L1
+ * body by the SAME operator key — the SDK never holds the key (§0.2). `chainHead`
+ * is the prior chain head this commitment links to; absent/empty defaults to
+ * genesis. Only available with `process` (loads a key from the filesystem; never
+ * wasm-reachable).
+ */
+export declare function assembleQuorumFromParts(suspendedContentJson: string, threshold: number, rosterJson: string, partsJson: string, projectRoot: string, keyPassphrase?: string | undefined | null, chainHead?: string | undefined | null): Buffer
+/**
+ * Suspend a gated action: mint the signed `suspended` chain link and return the
+ * raw resume token (returned ONCE) plus the action spec hash. Mirrors the PyO3
+ * `process_suspend` body 1:1 — the ProcessInput MUST carry `reclassify=false` so
+ * the descriptor is signed verbatim and stays byte-stable across the lifecycle.
+ *
+ * Returns JSON bytes:
+ * `{"session_id": str, "resume_token": str, "action_spec": str, "chain_path": str}`.
+ */
+export declare function processSuspend(processInputJson: Buffer | Uint8Array | string, projectRoot: string, sessionId: string, sla: string, expiresAt: string, onTimeout: string, contextScheme: string, contextBlob: Buffer, toolVersionHash?: string | undefined | null): Buffer
+/**
+ * Resume a suspended session: re-read the chain, apply the decision, fire-or-replay.
+ * Mirrors the PyO3 `process_resume` body 1:1. On `Fire` it mints + appends the
+ * `completed` link under `ACTION_SIGNING_DOMAIN` and advances the cursor.
+ *
+ * Returns JSON bytes `{"decision": str, "committed": bool, "kind"?: str,
+ * "reason"?: str}` where `decision` is one of
+ * `fire`/`replay`/`pending`/`terminal`/`uncertain`/`refused`.
+ */
+export declare function processResume(processInputJson: Buffer | Uint8Array | string, projectRoot: string, sessionId: string, presentedToken: string, contextBlob: Buffer): Buffer
+/**
+ * Append an approver/ledger-signed decision link to a session's chain. Mirrors the
+ * PyO3 `process_append_decision` body 1:1.
+ *
+ * `kind`: one of `"approved"` / `"denied"` / `"escalated"` / `"expired"`. **Fails
+ * closed** without a `decision.key` unless [`INSECURE_DECISION_KEY_ENV`] is set
+ * (see `load_decision_signer`) — the approver key is cloud-custodied in prod.
+ */
+export declare function processAppendDecision(projectRoot: string, sessionId: string, kind: string, reason?: string | undefined | null, decidedAt?: string | undefined | null): void
+/**
+ * Read the current lifecycle state of a session chain (the head link's kind).
+ * Mirrors the PyO3 `process_read_chain_head` body 1:1.
+ *
+ * Returns the head kind as a lowercase string (`"suspended"` / `"approved"` /
+ * `"denied"` / `"expired"` / `"completed"` / `"escalated"`), or `None` if no chain
+ * exists yet.
  */
-export declare function assembleQuorumFromParts(suspendedContentJson: string, threshold: number, rosterJson: string, partsJson: string, projectRoot: string, keyPassphrase?: string | undefined | null): Buffer
+export declare function processReadChainHead(projectRoot: string, sessionId: string): string | null
 /** A loaded operator key, exposing just the public-key surface. */
 export declare class OperatorKey {
   /** Return the base64 standard-alphabet public key. */

package/index.js

@@ -310,11 +310,12 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { OperatorKey, verify, verifyWithTime, verifyRederiving, actionCanonicalBytesJs, l1ContentCanonicalBytesJs, contentHash, anchoredContentHashJs, shortHash, chainHashHex, verifyApprovalToken, verifyDelegation, verifyChain, verifySessionChainJs, verifySessionChainWithRotationJs, verifyInclusionJs, verifyConsistencyJs, verifyAuditChain, taxonomyHash, redactDestructiveJs, redactCommitJs, keyFromSeed, generateKey, blake3Hex, processAction, assembleL1FromParts, assembleQuorumFromParts } = nativeBinding
+const { OperatorKey, verify, verifyWithTime, verifyWithRates, verifyRederiving, actionCanonicalBytesJs, l1ContentCanonicalBytesJs, contentHash, anchoredContentHashJs, shortHash, chainHashHex, verifyApprovalToken, verifyDelegation, verifyCommitment, commitmentEnvelopeCanonicalBytes, commitmentFingerprint, signerFingerprint, bindIntoChainJs, verifyChain, verifySessionChainJs, verifySessionChainWithRotationJs, verifyInclusionJs, verifyConsistencyJs, verifyAuditChain, taxonomyHash, classify, isDestructive, redactDestructiveJs, redactCommitJs, verifyRevealJs, keyFromSeed, generateKey, blake3Hex, processAction, assembleL1FromParts, assembleQuorumFromParts, processSuspend, processResume, processAppendDecision, processReadChainHead } = nativeBinding
 
 module.exports.OperatorKey = OperatorKey
 module.exports.verify = verify
 module.exports.verifyWithTime = verifyWithTime
+module.exports.verifyWithRates = verifyWithRates
 module.exports.verifyRederiving = verifyRederiving
 module.exports.actionCanonicalBytesJs = actionCanonicalBytesJs
 module.exports.l1ContentCanonicalBytesJs = l1ContentCanonicalBytesJs
@@ -324,6 +325,11 @@ module.exports.shortHash = shortHash
 module.exports.chainHashHex = chainHashHex
 module.exports.verifyApprovalToken = verifyApprovalToken
 module.exports.verifyDelegation = verifyDelegation
+module.exports.verifyCommitment = verifyCommitment
+module.exports.commitmentEnvelopeCanonicalBytes = commitmentEnvelopeCanonicalBytes
+module.exports.commitmentFingerprint = commitmentFingerprint
+module.exports.signerFingerprint = signerFingerprint
+module.exports.bindIntoChainJs = bindIntoChainJs
 module.exports.verifyChain = verifyChain
 module.exports.verifySessionChainJs = verifySessionChainJs
 module.exports.verifySessionChainWithRotationJs = verifySessionChainWithRotationJs
@@ -331,11 +337,18 @@ module.exports.verifyInclusionJs = verifyInclusionJs
 module.exports.verifyConsistencyJs = verifyConsistencyJs
 module.exports.verifyAuditChain = verifyAuditChain
 module.exports.taxonomyHash = taxonomyHash
+module.exports.classify = classify
+module.exports.isDestructive = isDestructive
 module.exports.redactDestructiveJs = redactDestructiveJs
 module.exports.redactCommitJs = redactCommitJs
+module.exports.verifyRevealJs = verifyRevealJs
 module.exports.keyFromSeed = keyFromSeed
 module.exports.generateKey = generateKey
 module.exports.blake3Hex = blake3Hex
 module.exports.processAction = processAction
 module.exports.assembleL1FromParts = assembleL1FromParts
 module.exports.assembleQuorumFromParts = assembleQuorumFromParts
+module.exports.processSuspend = processSuspend
+module.exports.processResume = processResume
+module.exports.processAppendDecision = processAppendDecision
+module.exports.processReadChainHead = processReadChainHead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hesohq/node",
-  "version": "0.4.3",
+  "version": "0.5.0-dev.101",
   "description": "napi-rs native Node.js addon for the HESO Enterprise trust layer",
   "main": "index.js",
   "types": "index.d.ts",
@@ -34,10 +34,10 @@
   },
   "license": "LicenseRef-Proprietary",
   "optionalDependencies": {
-    "@hesohq/node-darwin-arm64": "0.4.3",
-    "@hesohq/node-darwin-x64": "0.4.3",
-    "@hesohq/node-linux-arm64-gnu": "0.4.3",
-    "@hesohq/node-linux-x64-gnu": "0.4.3",
-    "@hesohq/node-win32-x64-msvc": "0.4.3"
+    "@hesohq/node-darwin-arm64": "0.5.0-dev.101",
+    "@hesohq/node-darwin-x64": "0.5.0-dev.101",
+    "@hesohq/node-linux-arm64-gnu": "0.5.0-dev.101",
+    "@hesohq/node-linux-x64-gnu": "0.5.0-dev.101",
+    "@hesohq/node-win32-x64-msvc": "0.5.0-dev.101"
   }
 }