@agentcontextdistributionprotocol/acdp 0.4.0 → 0.6.0

package/index.d.ts

@@ -19,6 +19,25 @@ export interface ResolvedDidKey {
    */
   publicKeyB64: string
 }
+/**
+ * [`ResolvedDidKey`] plus the RFC-ACDP-0010 §9 lifecycle signal for
+ * registry receipt keys.
+ */
+export interface ResolvedReceiptKey {
+  /** Verification-method id (full DID URL with `#fragment`). */
+  keyId: string
+  /** `ed25519` or `ecdsa-p256`. */
+  algorithm: string
+  /** Standard base64 of the raw key bytes (see [`ResolvedDidKey`]). */
+  publicKeyB64: string
+  /**
+   * `true` when the key is retained in `verificationMethod` but no
+   * longer referenced by `assertionMethod` — a retired receipt key.
+   * Verify the receipt, but report it with the distinguishable
+   * *historically authorized* status (RFC-ACDP-0010 §9).
+   */
+  historical: boolean
+}
 /**
  * Options for `buildPublishRequest`. Field names map directly to the
  * PublishRequest wire schema (camelCase on the JS side).
@@ -193,6 +212,26 @@ export declare class AcdpDidDocument {
    * is the full DID URL from the signature's `key_id`.
    */
   keyForAlgorithm(requestedKeyId: string, requestedAlg: string): ResolvedDidKey
+  /**
+   * Resolve a **registry receipt** signing key, applying the
+   * RFC-ACDP-0010 §9 lifecycle instead of the `assertionMethod` gate:
+   * retired receipt keys MUST remain in `verificationMethod`
+   * indefinitely and MUST still verify historical receipts even after
+   * rotation removes them from `assertionMethod`. A key absent from
+   * `verificationMethod` entirely still fails
+   * (`.code === "key_not_found"`) — full removal is the registry's
+   * compromise-revocation signal.
+   *
+   * `historical` on the result is `true` when the key is no longer in
+   * `assertionMethod`: verify the receipt, but report it with the
+   * distinguishable *historically authorized* status. The
+   * algorithm-downgrade defense (RFC-ACDP-0008 §3.9) and key decoding
+   * are enforced identically to `keyForAlgorithm`.
+   *
+   * Use `keyForAlgorithm` for producer keys and auth challenges —
+   * publish-time authorization still requires `assertionMethod`.
+   */
+  receiptKeyForAlgorithm(requestedKeyId: string, requestedAlg: string): ResolvedReceiptKey
 }
 /** RFC 8785 canonicalization utilities. All methods are static. */
 export declare class AcdpCanonicalizer {
@@ -219,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).
@@ -595,4 +661,200 @@ 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
 }

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.4.0",
+  "version": "0.6.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.4.0",
-    "@agentcontextdistributionprotocol/acdp-darwin-arm64": "0.4.0",
-    "@agentcontextdistributionprotocol/acdp-linux-x64-gnu": "0.4.0",
-    "@agentcontextdistributionprotocol/acdp-linux-arm64-gnu": "0.4.0"
+    "@agentcontextdistributionprotocol/acdp-darwin-x64": "0.6.0",
+    "@agentcontextdistributionprotocol/acdp-darwin-arm64": "0.6.0",
+    "@agentcontextdistributionprotocol/acdp-linux-x64-gnu": "0.6.0",
+    "@agentcontextdistributionprotocol/acdp-linux-arm64-gnu": "0.6.0"
   }
 }