@agentcontextdistributionprotocol/acdp 0.5.0 → 0.7.0

package/index.d.ts

@@ -258,6 +258,33 @@ export declare class AcdpCanonicalizer {
    */
   static contentHash(jsonStr: string): string
 }
+/** RFC-ACDP-0012 §5 Merkle helpers. All methods are static. */
+export declare class AcdpMerkle {
+  /**
+   * The §5.1 leaf hash of a transparency-log leaf:
+   * `SHA-256(0x00 ‖ JCS(leaf))`, returned in the wire form
+   * `"sha256:<64-hex>"`.
+   *
+   * * `leafJson` — the closed leaf object (e.g. the output of
+   *   `AcdpVerifier.buildLogLeaf`). Shape-validated first; a
+   *   malformed leaf throws (`.code === "invalid_log_proof"`)
+   *   rather than hashing bytes no conformant log ever committed.
+   */
+  static leafHash(leafJson: string): string
+  /**
+   * The §5.1 interior-node hash `SHA-256(0x01 ‖ left ‖ right)` over
+   * the raw digests the two wire-form (`"sha256:<hex>"`) arguments
+   * encode. The 0x00/0x01 domain-separation prefixes are what stop
+   * leaf/node second-preimage forgeries — never hash without them.
+   */
+  static nodeHash(leftHash: string, rightHash: string): string
+  /**
+   * The §5.2 RFC 6962 Merkle tree hash `MTH(D[n])` over an ordered
+   * JSON array of wire-form leaf hashes (`'["sha256:...", ...]'`).
+   * An empty array yields the empty-tree root, `SHA-256("")`.
+   */
+  static rootHash(leafHashesJson: string): string
+}
 /**
  * An ACDP producer: an Ed25519 signing key and its DID identity
  * (`did:web`, or `did:key` via the `*DidKey` factories — ACDP 0.2).
@@ -634,4 +661,284 @@ export declare class AcdpVerifier {
    * message otherwise.
    */
   static verifyReceipt(receiptJson: string, registryPublicKeyB64: string, expectedCtxId: string, recomputedBodyHash: string, producerKeyFingerprint: string): boolean
+  /**
+   * Verify a lineage-head receipt offline per RFC-ACDP-0011 §7:
+   * closed parse, registry/lineage/head bindings, `as_of` clock
+   * skew, and the registry signature over the RAW wire preimage —
+   * against the registry key extracted from the caller-supplied DID
+   * document (RFC-ACDP-0010 §9 receipt-key lifecycle: retired keys
+   * verify with `historical: true`; fully removed keys fail closed).
+   *
+   * * `receiptJson` — the `lineage_head_receipt` object as received
+   *   on the wire.
+   * * `expectedJson` — the consumer's own expectations:
+   *   `{"authority" and/or "registry_did", "lineage_id",
+   *   "head_ctx_id", "head_version", "head_status",
+   *   "on_current_endpoint"?}`. `authority` is the authority the
+   *   response was *actually fetched from* (compare your HTTP
+   *   client's URL, not any response field); `registry_did` is
+   *   `capabilities.registry_did`; either derives the other.
+   *   `on_current_endpoint` defaults to `true` (`GET /current` — §7
+   *   step 5 byte-match); pass `false` for a full retrieval, where
+   *   the §7 step 5b stale-consistency rule applies.
+   * * `registryDidDocJson` — the registry's resolved DID document
+   *   (resolution stays in JS land: `AcdpDid.webToUrl` + `fetch`).
+   * * `nowRfc3339` — the consumer clock (defaults to now).
+   * * `maxSkewSecs` — §7 step 6 allowance (default 120).
+   * * `maxAgeSecs` — §6 freshness policy (default 300).
+   *
+   * Returns a JSON verdict: `{"valid": true, "stale": bool,
+   * "age_secs": int, "historical": bool}` — staleness is policy,
+   * not verification failure — or `{"valid": false, "code":
+   * "invalid_receipt"|..., "error": ...}`. Throws only on malformed
+   * host input.
+   */
+  static verifyLineageHeadReceipt(receiptJson: string, expectedJson: string, registryDidDocJson: string, nowRfc3339?: string | undefined | null, maxSkewSecs?: number | undefined | null, maxAgeSecs?: number | undefined | null): string
+  /**
+   * Verify a transparency-log checkpoint (signed tree head) offline
+   * per RFC-ACDP-0012 §9.3: closed parse, optional `logId` pin
+   * (§7.4 — a new `log_id` is an explicit history reset), timestamp
+   * form + clock skew, and the registry signature over the RAW wire
+   * preimage against the receipt key from the caller-supplied DID
+   * document (retired keys verify with `historical: true`).
+   *
+   * The HOST still owns the §9.3 step 3 serving-authority half:
+   * confirm the `log_id`'s registry DID matches the authority the
+   * checkpoint was actually fetched from and
+   * `capabilities.registry_did`.
+   *
+   * Returns `{"valid": true, "log_id", "tree_size", "root_hash",
+   * "age_secs", "historical"}` (retain `tree_size`/`root_hash` for
+   * future §9.2 consistency checks) or `{"valid": false, "code":
+   * "invalid_log_proof", "error": ...}`.
+   */
+  static verifyLogCheckpoint(checkpointJson: string, registryDidDocJson: string, expectedLogId?: string | undefined | null, nowRfc3339?: string | undefined | null, maxSkewSecs?: number | undefined | null): string
+  /**
+   * Verify a transparency-log inclusion proof offline —
+   * RFC-ACDP-0012 §9.1 steps 2 and 4–6: hash the RECONSTRUCTED
+   * leaf, check the proof ↔ checkpoint bindings, fold the audit
+   * path, compare against the checkpoint root.
+   *
+   * * `inclusionJson` — the proof (`log_id`, `leaf_index`,
+   *   `tree_size`, `inclusion_path`, optionally an embedded
+   *   `log_checkpoint`).
+   * * `checkpointJson` — the checkpoint the proof verifies against.
+   *   Inserted when the proof carries none; when the proof embeds
+   *   one, the two MUST be byte-equal (a proof quietly carrying a
+   *   different checkpoint is the substitution §9.1 step 3 exists
+   *   to stop). Verify its signature separately with
+   *   `verifyLogCheckpoint` — the verdicts are independent.
+   * * `reconstructedLeafJson` — the leaf built from *verified* body
+   *   + receipt material via `buildLogLeaf` (§9.1 step 1). NEVER
+   *   pass a leaf echoed by the registry — the whole point is that
+   *   the verifier vouches for the leaf bytes itself.
+   *
+   * Returns `{"valid": true, "leaf_hash": "sha256:..."}` or
+   * `{"valid": false, "code": "invalid_log_proof", "error": ...}`.
+   */
+  static verifyLogInclusion(inclusionJson: string, checkpointJson: string, reconstructedLeafJson: string): string
+  /**
+   * Verify a transparency-log consistency proof offline —
+   * RFC-ACDP-0012 §9.2, the history-rewrite detector: prove the
+   * tree the verifier RETAINED a root for (`firstRootHash`, at
+   * `first_tree_size`) is a prefix of the checkpointed later tree.
+   *
+   * * `consistencyJson` — the proof (`log_id`, `first_tree_size`,
+   *   `second_tree_size`, `consistency_path`, optionally an
+   *   embedded `log_checkpoint`).
+   * * `checkpointJson` — the later checkpoint (merged/byte-checked
+   *   exactly as in `verifyLogInclusion`; verify its signature
+   *   separately with `verifyLogCheckpoint`).
+   * * `firstRootHash` — the verifier's own retained root
+   *   (`"sha256:<hex>"`) — retaining it is the whole point.
+   *
+   * Returns `{"valid": true}` or `{"valid": false, "code":
+   * "invalid_log_proof", "error": ...}`. A fold failure between two
+   * signature-valid checkpoints of one `log_id` is cryptographic
+   * evidence of a logged-history rewrite — retain both checkpoints
+   * and the failing path (§9.2, §15).
+   */
+  static verifyLogConsistency(consistencyJson: string, checkpointJson: string, firstRootHash: string): string
+  /**
+   * Build the canonical RFC-ACDP-0012 §4 log leaf from a VERIFIED
+   * RFC-ACDP-0010 receipt (§9.1 step 1) — every leaf field other
+   * than `receipt_hash` duplicates a receipt field, and
+   * `receipt_hash` is the receipt's §5 preimage hash, computed here
+   * over the RAW wire JSON as received. Returns the leaf as a JSON
+   * string, ready for `verifyLogInclusion` / `AcdpMerkle.leafHash`.
+   *
+   * Run `verifyReceipt` on the receipt FIRST: a leaf reconstructed
+   * from an unverified receipt proves membership of a claim nobody
+   * has checked. Throws on a malformed receipt
+   * (`.code === "invalid_receipt"`).
+   */
+  static buildLogLeaf(receiptJson: string): string
+  /**
+   * Verify one `registry_state.lifecycle_events` entry offline per
+   * RFC-ACDP-0013 §5: closed §4 parse, binding to `expectedCtxId`
+   * (a signed event cannot be replayed against another context),
+   * the §5 actor binding (`signature.key_id` DID = `actor`), and
+   * the signature over the RAW wire preimage.
+   *
+   * * `eventJson` — the event object as received.
+   * * `actorDidDocJson` — the ACTOR's resolved DID document, or
+   *   `null` for a `did:key` actor (self-certifying — verified
+   *   natively with no document). For `did:web` actors the key must
+   *   pass the `assertionMethod` gate, like a body signature.
+   * * `expectedCtxId` — the ctx_id of the context whose registry
+   *   state carries the event.
+   *
+   * The HOST still owns the §4/§12 authorization check that `actor`
+   * equals the context's `body.agent_id` (producer-initiated) or
+   * the registry's `capabilities.registry_did` (registry-initiated)
+   * — this binding sees neither document. Retraction state itself
+   * is derived from array order, last `retracted`/`republished`
+   * event wins; unknown event types are inert (§7.1, §7.3).
+   *
+   * Returns `{"valid": true, "event_id", "event_type", "actor"}` or
+   * `{"valid": false, "code": ..., "error": ...}` (an unsigned
+   * event fails — producer-initiated events MUST be signed).
+   */
+  static verifyLifecycleEvent(eventJson: string, actorDidDocJson: string | undefined | null, expectedCtxId: string): string
+  /**
+   * Parse and shape-validate a `key-revocation` context body
+   * (RFC-ACDP-0014 §4) and derive its §5/§6 trust class. Returns
+   * the typed revocation as JSON: `{"revoked_key_fingerprint",
+   * "compromised_since", "reason"?, "revoked_key_id"?,
+   * "revoked_key_controller", "publisher", "trust_class":
+   * "producer_signed"|"registry_attested"}`. The fingerprint is
+   * authoritative; `compromised_since` is the compromise boundary
+   * T. Never collapse the two trust classes when reporting (§6).
+   *
+   * * `bodyJson` — the retrieved context `body` (the §5.7 layout
+   *   including registry-assigned fields).
+   * * `signerFingerprint` — the RFC-ACDP-0010 §6 fingerprint of the
+   *   RESOLVED key that signed the body, for the §5 step 2
+   *   not-self-signed rule. For `did:key` signers the check runs
+   *   natively from the body itself; for `did:web` signers resolve
+   *   the key in JS land (`AcdpDidDocument.keyForAlgorithm` +
+   *   `fingerprintEd25519B64`) and pass its fingerprint here — a
+   *   revocation signed by the very key it revokes proves only
+   *   possession of the attacker-held key and throws
+   *   (`.code === "key_not_authorized"`).
+   *
+   * Parsing does NOT verify the body: run the ordinary hash +
+   * signature pipeline (`verifyContentHash` + `verifySignature`, or
+   * `verifyBodyOffline` for did:key) before trusting the result.
+   * Throws with `.code === "schema_violation"` on §4 shape
+   * violations.
+   */
+  static parseKeyRevocation(bodyJson: string, signerFingerprint?: string | undefined | null): string
+  /**
+   * Apply the RFC-ACDP-0014 §7 compromise-boundary rule — the
+   * fail-closed classification the Rust client uses, over the
+   * earliest `compromised_since` among the supplied revocations
+   * naming the key (§4 monotonicity: a superseding revocation can
+   * widen, never quietly shrink, the window — feed the whole
+   * lineage through, superseded revocations included).
+   *
+   * * `revocationsJson` — JSON array of VERIFIED revocations (the
+   *   shapes `parseKeyRevocation` returns). Which trust classes to
+   *   act on is the caller's §6 policy.
+   * * `signerFingerprint` — fingerprint of the key that signed the
+   *   context under verification.
+   * * `receiptCreatedAtRfc3339` — `created_at` from a registry
+   *   receipt VERIFIED per RFC-ACDP-0010 §8, or `null` when there
+   *   is no verified receipt. NEVER the bare body `created_at` — it
+   *   is registry-assigned, producer-unsigned, and
+   *   attacker-backdatable (§7 step 1).
+   *
+   * Returns `{"authorization": "none"}` (no revocation names the
+   * key — ordinary rules apply), `{"authorization":
+   * "historically_authorized_pre_compromise", "boundary": ...}` (§7
+   * step 2 — still verify the signature itself, under the
+   * RFC-ACDP-0010 §10 historical rule), or `{"authorization":
+   * "none", "boundary": ..., "error": ...}` — fail closed (§7
+   * steps 3–4).
+   */
+  static classifyUnderRevocation(revocationsJson: string, signerFingerprint: string, receiptCreatedAtRfc3339?: string | undefined | null): string
+  /**
+   * Mint a signed transparency-log witness cosignature
+   * (RFC-ACDP-0015 §5) — the MINT surface a host-language witness
+   * service uses. The witness observes a checkpoint and cosigns it
+   * with its OWN Ed25519 key (a witness key, distinct from the
+   * registry receipt key); the returned `log_cosignature` uses the
+   * RFC-ACDP-0010 §5 construction verbatim (the witness signs the
+   * ASCII bytes of the `"sha256:<hex>"` cosignature-hash string).
+   *
+   * * `witnessedCheckpointJson` — the identity-bearing subset of the
+   *   checkpoint the witness observed: `{"log_id", "tree_size",
+   *   "root_hash", "timestamp"}` (closed schema).
+   * * `witnessDid` — the witness's own DID (`did:web` or `did:key`).
+   *   The signing-key DID URL is derived as
+   *   `"<witnessDid>#witness-key-1"` (the §5/§9 witness-key
+   *   convention).
+   * * `witnessSeedHex` — the witness Ed25519 signing seed, hex-
+   *   encoded (64 hex chars → 32 bytes). The same seed produces
+   *   byte-identical cosignatures across bindings.
+   * * `witnessedAtRfc3339` — the witness-clock observation time
+   *   (canonical millisecond RFC 3339 UTC; truncated to ms).
+   *
+   * Returns the signed `log_cosignature` as a JSON string. This is
+   * the RAW mint (no §7 obligation — the checkpoint's own signature
+   * and consistency against a retained head are the host's job).
+   * Throws on malformed input (bad seed / timestamp / witness DID /
+   * witnessed_checkpoint).
+   */
+  static buildWitnessCosignature(witnessedCheckpointJson: string, witnessDid: string, witnessSeedHex: string, witnessedAtRfc3339: string): string
+  /**
+   * Verify one witness cosignature against a checkpoint the consumer
+   * has itself verified, offline per RFC-ACDP-0015 §8 (steps 1–5):
+   * closed parse + witness binding, checkpoint binding, the witness
+   * signature over the RAW wire preimage against the key resolved
+   * from the caller-supplied witness DID document (§9: looked up in
+   * `verificationMethod`, retired keys stay verifiable), and the
+   * `witnessed_at` well-formedness + forward-skew check.
+   *
+   * * `cosigJson` — the `log_cosignature` object as received.
+   * * `witnessDidDocJson` — the WITNESS's resolved DID document
+   *   (resolution stays in JS land). Its `id` MUST equal the
+   *   cosignature's `witness_id`.
+   * * `expectedCheckpointJson` — the RFC-ACDP-0012 checkpoint the
+   *   consumer independently holds and verified; the cosignature's
+   *   `{log_id, tree_size, root_hash}` MUST match it (§8 step 4).
+   * * `nowRfc3339` — the consumer clock (defaults to now).
+   * * `maxClockSkewSecs` — §8 step 5 forward allowance (default 120).
+   *
+   * Returns a JSON verdict: `{"valid": true, "witness_id": ...,
+   * "age_secs": int, "stale": bool}` — staleness (§8.1) is policy,
+   * not a verification failure — or `{"valid": false, "code":
+   * "invalid_witness_cosignature"|..., "error": ...}`. Throws only
+   * on malformed host input.
+   */
+  static verifyWitnessCosignature(cosigJson: string, witnessDidDocJson: string, expectedCheckpointJson: string, nowRfc3339?: string | undefined | null, maxClockSkewSecs?: number | undefined | null): string
+  /**
+   * Compute the RFC-ACDP-0015 §8 N-witnessed report over a set of
+   * cosignatures for a checkpoint the consumer has itself verified.
+   * A cosignature counts toward N iff it names a TRUSTED witness,
+   * covers the checkpoint's `(log_id, tree_size, root_hash)` tuple,
+   * and passes every §8 step; DISTINCT `witness_id` values are
+   * counted. A cosignature that fails a step does not fail the
+   * checkpoint — it is recorded in `failures` and simply does not
+   * count.
+   *
+   * * `cosignaturesJson` — a JSON array of `log_cosignature` objects.
+   * * `expectedCheckpointJson` — the verified checkpoint the quorum
+   *   is over.
+   * * `trustedWitnessDidsJson` — a JSON array of the witness DIDs the
+   *   consumer trusts; only these can count.
+   * * `witnessDidDocsJson` — a JSON object mapping each `witness_id`
+   *   to its resolved DID document.
+   * * `policyJson` — `{"min_witnesses"?, "max_age_secs"?,
+   *   "max_clock_skew_secs"?}`. Defaults mirror the Rust
+   *   `WitnessPolicy`: `min_witnesses=1`, `max_age_secs=300` (an
+   *   explicit `null` disables the freshness split),
+   *   `max_clock_skew_secs=120`.
+   * * `nowRfc3339` — the consumer clock (defaults to now).
+   *
+   * Returns a JSON report: `{"witnessed_count", "witnesses",
+   * "meets_quorum", "fresh_witnessed_count", "meets_fresh_quorum",
+   * "failures"}`. Throws on malformed host input.
+   */
+  static evaluateWitnessQuorum(cosignaturesJson: string, expectedCheckpointJson: string, trustedWitnessDidsJson: string, witnessDidDocsJson: string, policyJson: string, nowRfc3339?: string | undefined | null): string
 }

package/index.js

@@ -310,11 +310,12 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { AcdpDid, AcdpDidDocument, AcdpCanonicalizer, AcdpProducer, AcdpP256Producer, AcdpSsrfPolicy, AcdpVerifier } = nativeBinding
+const { AcdpDid, AcdpDidDocument, AcdpCanonicalizer, AcdpMerkle, AcdpProducer, AcdpP256Producer, AcdpSsrfPolicy, AcdpVerifier } = nativeBinding
 
 module.exports.AcdpDid = AcdpDid
 module.exports.AcdpDidDocument = AcdpDidDocument
 module.exports.AcdpCanonicalizer = AcdpCanonicalizer
+module.exports.AcdpMerkle = AcdpMerkle
 module.exports.AcdpProducer = AcdpProducer
 module.exports.AcdpP256Producer = AcdpP256Producer
 module.exports.AcdpSsrfPolicy = AcdpSsrfPolicy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcontextdistributionprotocol/acdp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Agent Context Distribution Protocol — Node.js SDK",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -47,9 +47,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@agentcontextdistributionprotocol/acdp-darwin-x64": "0.5.0",
-    "@agentcontextdistributionprotocol/acdp-darwin-arm64": "0.5.0",
-    "@agentcontextdistributionprotocol/acdp-linux-x64-gnu": "0.5.0",
-    "@agentcontextdistributionprotocol/acdp-linux-arm64-gnu": "0.5.0"
+    "@agentcontextdistributionprotocol/acdp-darwin-x64": "0.7.0",
+    "@agentcontextdistributionprotocol/acdp-darwin-arm64": "0.7.0",
+    "@agentcontextdistributionprotocol/acdp-linux-x64-gnu": "0.7.0",
+    "@agentcontextdistributionprotocol/acdp-linux-arm64-gnu": "0.7.0"
   }
 }