@hesohq/node 0.4.3 → 0.5.0

package/index.d.ts

@@ -72,9 +72,8 @@ 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).
+ * 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 +125,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 +222,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 +272,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 +323,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 +351,16 @@ 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): Buffer
+export declare function assembleQuorumFromParts(suspendedContentJson: string, threshold: number, rosterJson: string, partsJson: string, projectRoot: string, keyPassphrase?: string | undefined | null, chainHead?: string | undefined | null): Buffer
 /** 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,7 +310,7 @@ 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, 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 } = nativeBinding
 
 module.exports.OperatorKey = OperatorKey
 module.exports.verify = verify
@@ -324,6 +324,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,8 +336,11 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hesohq/node",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "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",
+    "@hesohq/node-darwin-x64": "0.5.0",
+    "@hesohq/node-linux-arm64-gnu": "0.5.0",
+    "@hesohq/node-linux-x64-gnu": "0.5.0",
+    "@hesohq/node-win32-x64-msvc": "0.5.0"
   }
 }