did-beta-bch 2.0.1 → 3.0.0

package/PROTOCOL.md

@@ -1,75 +1,55 @@
 # Cashlet DID Protocol Specification
 
-Version: `2.0.0`
+Version: `3.0.0`  
 Status: Draft
 
-This is the normative specification for Cashlet DID v2. V2 is a breaking
-signature-format update: conforming verifiers MUST reject v1 proof tags and
-signatures. Existing v1 bindings must be re-created and re-published.
-
----
+Cashlet DID v3 is a breaking protocol update. Conforming verifiers MUST reject
+v1 and v2 binding records. Existing identities must be rebound and republished.
 
 ## 1. Identifiers
 
 | Constant | Value |
 |---|---|
 | Protocol ID | `cashlet-did` |
-| Protocol version | `2.0.0` |
-| Binding event kind | `30078` (NIP-78 addressable data) |
+| Protocol version | `3.0.0` |
+| Binding event kind | `30078` |
+| Rotation authorization kind | `30080` |
 | Credential event kind | `30085` |
 | Revocation event kind | `5` (NIP-09) |
+| Dual-key challenge kind | `27235` (NIP-98 event format) |
 | Nostr derivation path | `m/44'/1237'/<account>'/0/0` (NIP-06) |
 
-## 2. Canonical binding record
+## 2. Binding and BCH ownership proof
 
 A binding record has recursively sorted object keys, no whitespace, and omits
 undefined/absent fields:
 
 ```json
 {
-  "bch": {
-    "address": "<prefixed-cashaddr>",
-    "network": "mainnet" | "testnet" | "chipnet",
-    "paymentCode": "<BIP47 payment code>"   // optional
-  },
-  "createdAt": <unix seconds>,
+  "bch": { "address": "<prefixed-cashaddr>", "network": "mainnet|testnet|chipnet" },
+  "createdAt": 0,
   "nostr": { "pubkey": "<32-byte lowercase hex>" },
   "nonce": "<64 lowercase hex chars>",
-  "previousBindingId": "<64 lowercase hex chars>", // optional
   "protocol": "cashlet-did",
-  "purpose": "identity-binding-v2",
-  "version": "2.0.0"
+  "purpose": "identity-binding-v3",
+  "version": "3.0.0"
 }
 ```
 
-**Binding ID** = lowercase hex `SHA-256(canonicalize(record_without_bindingId))`.
-Arrays preserve order. `mainnet` addresses use the `bitcoincash:` prefix;
-`testnet` and `chipnet` use `bchtest:`.
-
-## 3. BCH signing payload and wallet contract
+Optional fields are `bch.paymentCode` and `previousBindingId`. The binding ID
+is lowercase hex `SHA-256(canonicalize(record_without_bindingId))`. Arrays
+preserve order. Mainnet addresses use `bitcoincash:`; testnet and chipnet use
+`bchtest:`.
 
-The exact UTF-8 message text supplied to a wallet is:
+The exact UTF-8 message supplied to the BCH wallet is:
 
 ```text
-cashlet-did/bch-proof/v2.0.0\n<canonicalized subset>
-```
-
-The subset contains exactly these keys:
-
-```json
-{
-  "bchAddress": "<prefixed-cashaddr>",
-  "bchNetwork": "mainnet" | "testnet" | "chipnet",
-  "bindingId": "<64 lowercase hex chars>",
-  "createdAt": <unix seconds>,
-  "nonce": "<64 lowercase hex chars>",
-  "nostrPubkey": "<32-byte lowercase hex>",
-  "purpose": "identity-binding-v2"
-}
+cashlet-did/bch-proof/v3.0.0\n<canonicalized subset>
 ```
 
-Pass this exact message string to the wallet's message-signing method. Do not
-pre-hash, add a Bitcoin prefix, or otherwise transform it in the adapter. The
+The subset contains exactly `bindingId`, `bchAddress`, `bchNetwork`,
+`nostrPubkey`, `nonce`, `purpose`, and `createdAt`. Pass this exact text to the
+wallet; do not pre-hash, add a Bitcoin prefix, or otherwise transform it. The
 wallet computes:
 
 ```text
@@ -77,168 +57,150 @@ SHA256d(0x18 || "Bitcoin Signed Message:\n" ||
        CompactSize(UTF8(message).length) || UTF8(message))
 ```
 
-`CompactSize` uses Bitcoin's little-endian encodings: one byte below `0xfd`,
-`fd` plus 2 bytes through `0xffff`, `fe` plus 4 bytes through `0xffffffff`,
-then `ff` plus 8 bytes.
+The response MUST be canonical padded Base64 for exactly 65 bytes:
+`[header 31–34] || [32-byte r] || [32-byte s]`. The header selects a compressed
+public key and recovery ID 0–3. Raw hex, 64-byte signatures, uncompressed
+headers, non-canonical Base64, and v1/v2 proof formats are rejected.
 
-The wallet response is standard padded Base64 encoding of exactly 65 bytes:
+## 3. Binding Nostr event
 
-```text
-[header byte 31–34] || [32-byte r] || [32-byte s]
-```
-
-The header is `27 + 4 + recovery_id`; recovery IDs are `0–3`, and `+4`
-specifies a compressed public key. V2 accepts only this compressed-key form.
-Verifiers decode Base64, subtract 31 from the header, recover the compressed
-public key, and derive its prefixed BCH CashAddr. Raw hex, 64-byte signatures,
-uncompressed headers, non-canonical Base64, and v1 signatures are rejected.
-
-### Wallet interoperability evidence
-
-Paytaca's WalletConnect implementation signs the supplied message with the
-Bitcoin message prefix, `bigIntToCompactUint`, double-SHA256, and recoverable
-compact ECDSA; it adds `31` for compressed keys and returns Base64:
-[Paytaca source](https://github.com/Paytaca/paytaca-app/blob/41c785b9f48dee337d2da3f33e082e5210d462d0/src/wallet/walletconnect2/index.js).
-The BCH WalletConnect BCR also specifies Electron Cash-compatible signed
-messages: [BCR](https://github.com/mainnet-pat/wc2-bch-bcr/blob/55e3e37142ddc7b30ad63c7330ef8df252fec715/README.md).
-The library keeps this contract transport-neutral; validate each wallet
-release's response in integration tests before advertising support.
-
-## 4. Nostr event (kind 30078)
-
-The event timestamp MUST equal the binding's `createdAt`. Required tags:
+Publish a kind `30078` event whose timestamp equals `binding.createdAt`.
+Required tags:
 
 ```json
 [
   ["d", "<bindingId>"],
   ["bch", "<cashaddr>", "<network>"],
-  ["protocol", "cashlet-did", "2.0.0"],
+  ["protocol", "cashlet-did", "3.0.0"],
   ["t", "cashlet-did"],
   ["bch-proof", "bitcoin-message/compact-base64", "<exact message>", "<signature Base64>"]
 ]
 ```
 
-Optional tags:
-
-```json
-["bch-payment-code", "<BIP47 code>"]       // must equal content.bch.paymentCode
-["supersedes", "<previous bindingId>"]     // must equal content.previousBindingId
-["bch-anchor", "<txid>", "<claimed height>"] // unverified chain claim
-```
+Optional tags are `bch-payment-code`, `supersedes`, `rotation-proof`, and
+`bch-anchor`. Content is canonical JSON with `protocol`, `version`,
+`bindingId`, `bch`, `nonce`, and `createdAt`, plus optional `previousBindingId`
+and embedded `rotationAuthorization`. The Nostr event signature covers all
+tags and content. A `bch-anchor` tag is an untrusted claim until independently
+verified under §8.
 
-`content` is the canonicalized JSON object containing `protocol`, `version`,
-`bindingId`, `bch`, `nonce`, `createdAt`, and optional `previousBindingId`.
-`bch` contains `address`, `network`, and optional `paymentCode`. Nostr event
-signatures protect all event tags and content.
+## 4. Discovery, revocation, and verification
 
-## 5. Discovery and revocation
-
-Discover v2 records with this NIP-01 filter:
+Discover v3 bindings with:
 
 ```json
 { "kinds": [30078], "authors": ["<pubkey hex>"], "#t": ["cashlet-did"] }
 ```
 
 Revocations are kind `5` events from the same author with `["e", "<event id>"]`
-tags. Filter revoked records before selecting the newest v2 binding.
+tags. Filter revoked records before selecting the newest binding.
 
-## 6. Verification algorithm
+A verifier MUST:
 
 1. Verify the NIP-01 event signature and require kind `30078`.
 2. Require exactly one correctly shaped `d`, `bch`, `protocol`, `t`, and
-   `bch-proof` tag. The proof tag MUST have exactly four elements and the v2
-   format marker. Check optional payment-code and supersedes tags against
-   content; reject duplicate or malformed known tags.
-3. Parse content and require its canonical serialization, exact v2 fields,
-   event timestamp, `d`, `bch`, protocol/version tags, and resolved identity
-   (`npub`, Nostr pubkey, address, network, and binding ID) to agree.
-4. Recompute the binding ID and reconstruct the exact v2 BCH signing payload.
-   The proof tag's message must be byte-for-byte identical.
-5. Decode the canonical 65-byte Base64 compact signature, recover the
-   compressed public key from the Bitcoin signed-message hash, and derive
-   the network-appropriate BCH CashAddr. It must equal the bound address.
+   `bch-proof` tag; validate all known optional tags and reject duplicates.
+3. Require canonical content with the exact v3 fields, timestamp, binding ID,
+   event tags, and resolved identity to agree.
+4. Recompute the binding ID and exact v3 BCH signing payload.
+5. Recover the compressed BCH public key from the canonical compact signature
+   and require its CashAddr to equal the bound address.
 6. Report `verified` only when both the Nostr and BCH signatures are valid.
 
-V1 tags do not satisfy the v2 proof-tag structure and MUST NOT be accepted as
-fallbacks.
+V1 and v2 bindings MUST NOT be accepted as fallbacks.
 
-## 7. Challenge-response authentication
+## 5. Cross-key rotation
 
-The exact v2 message is either:
+A successor sets `previousBindingId` and includes the matching `supersedes`
+tag. Resolvers MUST verify every event in the chain and fail closed if a
+predecessor is missing, revoked, or invalid.
 
-```text
-cashlet-did/challenge/v2.0.0\n<nonce>
-```
+When the Nostr key changes, the successor MUST embed a kind `30080`
+authorization event signed by the previous Nostr key. Its canonical content
+names the previous binding ID/key and the exact successor binding ID/key,
+BCH address/network, and creation time. The successor includes
+`["rotation-proof", "<authorization event id>", "<old pubkey>"]`. A resolver
+MUST verify the old-key event signature and match every field and tag to the
+successor. Same-key succession does not need this extra signature. Lost-key
+recovery is out of scope; without old-key authorization, cross-key rotation is
+rejected.
 
-or, with an audience:
+## 6. Dual-key challenge-response authentication
+
+The BCH-signed payload is either:
 
 ```text
-cashlet-did/challenge/v2.0.0\n<nonce>\n<audience>
+cashlet-did/challenge/v3.0.0\n<nonce>
+cashlet-did/challenge/v3.0.0\n<nonce>\n<audience>
 ```
 
-The no-audience form has exactly two lines; the audience form has exactly three.
-No extra lines or trailing newline are allowed. The nonce and optional audience
-are single-line strings. The BCH wallet signs the exact text using §3's Bitcoin
-signed-message hash and 65-byte Base64 signature.
-`bchChallengePayload(nonce, audience?)` constructs the payload;
-`verifyChallengeProof` checks exact equality, signature, address, and—when
-`issuedAt` is provided—a 5-minute TTL. Applications must issue and consume
-one-time challenges and separately verify Nostr control if required.
-
-## 8. Key rotation
+The audience form has exactly three lines; no extra line or trailing newline
+is allowed. The Nostr key also signs a kind `27235` event with exactly one each
+of these tags: `u` (verification endpoint), `method` (`POST`), `audience`,
+`challenge`, and `expiration`. Its content is the exact BCH payload above.
+Both proofs MUST match the same verified binding's BCH address and Nostr
+pubkey, nonce, audience, endpoint, issue time, and expiration.
 
-Set `previousBindingId` in the new binding and add the matching
-`["supersedes", "<previousBindingId>"]` tag. Resolvers can follow references
-backwards, but must independently verify each referenced binding and fail
-closed if a predecessor is unavailable or invalid. A supersedes tag authored
-by the new key does not prove that the previous Nostr key authorized rotation.
+The server MUST issue an unpredictable, one-time challenge, persist it, and
+atomically consume it only after validating both signatures. Browser-local
+challenge state alone is not server-enforced authentication.
+`verifyDualChallengeProof` checks cryptographic and context binding; the
+application is responsible for durable single-use challenge state.
 
-## 9. Selective disclosure
+## 7. NIP-05 and NIP-98
 
-The library's selective-disclosure helper commits each attribute using an
-independent random 32-byte salt:
-
-```text
-SHA-256("cashlet-did/attr/v2\n" + JSON([key, value, salt]))
-```
+NIP-05 resolution is `user@domain` → `GET
+https://domain/.well-known/nostr.json?name=user` → extract pubkey → resolve
+and verify the v3 binding. A registration endpoint MUST verify the candidate
+event's Nostr signature and BCH ownership proof before reserving a handle.
 
-Keep salts private until revealing their associated values; include the value
-and salt in each reveal so a verifier can recompute the commitment. The helper
-does not publish commitments or attach them to a binding event automatically.
+NIP-98 uses kind `27235`. The `verifyBch: true` option additionally resolves
+the signer's v3 Cashlet DID binding. The server verifier must receive the
+actual request body (`null` when absent), compare its SHA-256 hash with the
+`payload` tag, reject missing/duplicate/mismatched hashes, and enforce the
+documented 60-second event window.
 
-## 10. On-chain commitment (OP_RETURN)
+## 8. BCH transaction anchor
 
-Embed the binding ID in a BCH transaction output:
+The OP_RETURN output commits to:
 
 ```text
 OP_RETURN <"cashlet-did:" + bindingId>
 ```
 
-The library can construct an anchor transaction, but it does not broadcast the
-transaction or verify its inclusion in a confirmed block. A `bch-anchor` event
-tag is only an issuer-provided claim; applications that need confirmed
-anchoring must independently verify the transaction and block inclusion.
+`buildAnchorTx` constructs a transaction but does not broadcast it. A binding's
+`anchor` field and `bch-anchor` tag only identify a claimed transaction and
+height; they do not prove inclusion. `verifyBchAnchorProof` checks the exact
+zero-value commitment, txid, Merkle inclusion, BCH ASERT difficulty, proof of
+work, median-time-past, future-time bound, and confirmation depth for a header
+chain extending from an application-trusted checkpoint.
 
-## 11. NIP-05 handle resolution
+The exported `BCH_MAINNET_CHECKPOINT` is a fixed mainnet trust root. The result
+is **checkpointed SPV**, not full-node validation: proof sources are untrusted,
+the checkpoint must not be fetched from the same endpoint, and the proof does
+not establish that a supplied branch is the globally highest-work branch.
+There is no chipnet checkpoint or proof-fetch adapter in this package, so
+chipnet anchors remain unverifiable unless an application supplies an
+independently reviewed checkpoint and consensus configuration.
 
-`user@domain` → `GET https://domain/.well-known/nostr.json?name=user` →
-extract `pubkey` → resolve the v2 binding via §5.
+## 9. Other helpers
 
-## 12. NIP-98 HTTP Auth
+Selective disclosure commits each attribute using an independent random
+32-byte salt:
 
-Build a kind `27235` event per NIP-98. The `verifyBch: true` option on the
-server additionally resolves the signer's v2 Cashlet DID binding. The verifier
-must receive the actual request body (`null` when absent) and compare its
-SHA-256 hash with the event's `payload` tag. Reject missing, duplicate, or
-mismatched payload hashes and enforce the documented 60-second event window.
+```text
+SHA-256("cashlet-did/attr/v2\n" + JSON([key, value, salt]))
+```
 
-## 13. Credentials
+Keep salts private until revealing their associated values; include the value
+and salt in each reveal so a verifier can recompute the commitment. The helper
+does not publish commitments or attach them to a binding event automatically.
 
-Credential events use kind `30085`. A resolver must verify the Nostr event
+Credential events use kind `30085`. A resolver must verify the issuer's Nostr
 signature, require the event's `p` tag and credential payload subject to match
 the requested pubkey, and require the `credential-type` tag to match the
-payload type. `issuedAt` must match the event timestamp. If `expiry` is present,
-reject the credential once that Unix timestamp has passed. A revocation is
-effective only when a valid kind `5` event from the credential's issuer
-references that credential event ID. Cryptographic validity does not establish
-that an issuer is trusted; trust policy is application-specific.
+payload type. `issuedAt` must match the event timestamp. If `expiry` is
+present, reject the credential once that Unix timestamp has passed. A
+revocation is effective only when a valid kind `5` event from the issuer
+references that credential event. Cryptographic validity does not establish
+issuer trust; that policy is application-specific.

package/README.md

@@ -4,8 +4,9 @@ A standalone, framework-agnostic library implementing the **Cashlet DID protocol
 
 Any BCH wallet or Nostr client can use this library to publish, resolve, and verify BCH–Nostr identity bindings without depending on the Cashlet extension.
 
-This release is Cashlet DID v2.0.0, a breaking proof-format update. V2 verifiers
-do not accept v1 bindings; existing identities must be rebound and republished.
+This release is Cashlet DID v3.0.0, a breaking protocol update. V3 verifiers
+do not accept v1 or v2 bindings; existing identities must be rebound and
+republished.
 
 ## Real-world use cases
 
@@ -13,9 +14,9 @@ do not accept v1 bindings; existing identities must be rebound and republished.
 
 **Nostr client** — call `verifyIdentity` when rendering a profile to show a cryptographically-proven "verified BCH address" badge. No issuing authority — the proof is in the signature.
 
-**Merchant checkout** — call `resolveByNip05('alice@shop.com')` at payment time to resolve the current NIP-05 pubkey and its verified binding. Cross-key rotation continuity is not established by this library, so merchants must update their NIP-05 record and clients must not assume a new key is authorized by the old one.
+**Merchant checkout** — call `resolveByNip05('alice@shop.com')` at payment time to resolve the current NIP-05 pubkey and its verified binding. The v3 resolver checks old-key authorization when following a cross-key rotation.
 
-**Passwordless login** — use `verifyHttpAuth` in a server with a NIP-07 signer. The server verifies the signed Nostr request and can optionally resolve the signer's BCH binding; it still needs application-specific authorization and replay policy.
+**Passwordless login** — issue a server-side one-time challenge, collect BCH and Nostr signatures, and verify them with `verifyDualChallengeProof`. The application must atomically consume challenges and apply its own authorization policy. `verifyHttpAuth` remains available for NIP-98 requests.
 
 ## Install
 
@@ -110,35 +111,53 @@ const social = deriveNostrKeypair(mnemonic, 1)
 ### Challenge-response authentication
 
 ```ts
-import { bchChallengePayload, signBchMessage, verifyChallengeProof } from 'did-beta-bch'
+import {
+  bchChallengePayload, nostrChallengeTemplate, verifyDualChallengeProof,
+} from 'did-beta-bch'
 
 const payload = bchChallengePayload(nonce, audience)
-const signature = await signBchMessage(walletSigner, payload)
-// issuedAt enforces 5-minute TTL
-const valid = verifyChallengeProof(
-  { signature, payload, address },
-  nonce,
-  audience,
-  issuedAt, // unix seconds — optional, rejects if > 5 min old
+const nostrTemplate = nostrChallengeTemplate(
+  nonce, audience, 'https://app.example/api/auth/verify', issuedAt,
+)
+// Collect the BCH signature over `payload` and Nostr signature over `nostrTemplate`.
+const valid = verifyDualChallengeProof(
+  { signature, payload, address, nostrEvent },
+  {
+    nonce,
+    audience,
+    endpoint: 'https://app.example/api/auth/verify',
+    issuedAt,
+    address,
+    pubkey,
+  },
 )
 ```
 
+Challenge issuance and one-time consumption belong on a server with durable,
+atomic storage. Do not treat browser-only challenge state as authentication.
+
 ### Key rotation
 
 ```ts
-import { buildBinding, resolveIdentityChain } from 'did-beta-bch'
+import {
+  buildBinding, rotationAuthorizationTemplate, nostrEventTemplate,
+  resolveIdentityChain,
+} from 'did-beta-bch'
 
-// Rotate: reference the old binding
+// For a changed Nostr key, have the old key sign this authorization event.
 const newBinding = await buildBinding(newAddress, 'mainnet', newNostrPub, undefined, oldBindingId)
+const authorizationTemplate = rotationAuthorizationTemplate(oldBinding, newBinding)
+const oldKeyAuthorization = finalizeEvent(authorizationTemplate, oldNostrPrivkey)
+// Publish the successor with its BCH proof and the old-key authorization.
+const successorTemplate = nostrEventTemplate(newBinding, bchProof, oldKeyAuthorization)
 
 // Resolve linked, individually verified binding events, newest first
 const chain = await resolveIdentityChain('npub1...')
 ```
 
-The resolver verifies each event and requires every `supersedes` target to be
-present, unrevoked, and valid. A reference signed only by the new key does not
-prove that the previous Nostr key authorized the rotation; do not treat this
-chain alone as proof of cross-key continuity.
+For cross-key rotation, the resolver verifies the old-key authorization and
+requires every `supersedes` target to be present, unrevoked, and valid. Lost-key
+recovery is not supported.
 
 ### Verifiable credentials + reputation
 
@@ -178,16 +197,26 @@ commitments or attach them to a binding event automatically.
 ### BCH-anchored identity commitment
 
 ```ts
-import { buildAnchorTx } from 'did-beta-bch'
+import {
+  buildAnchorTx, verifyBchAnchorProof,
+  BCH_MAINNET_CHECKPOINT, BCH_MAINNET_ASERT_PARAMETERS,
+} from 'did-beta-bch'
 
 // Embed bindingId in an OP_RETURN transaction for on-chain commitment
 const { txHex } = await buildAnchorTx(bindingId, { txid, vout, valueSats, lockingBytecode, privateKey })
+// Independently verify transaction, Merkle proof, headers, and depth
+const result = verifyBchAnchorProof(proof, bindingId, {
+  checkpoint: BCH_MAINNET_CHECKPOINT,
+  asert: BCH_MAINNET_ASERT_PARAMETERS,
+  minConfirmations: 6,
+})
 ```
 
-This builds transaction hex from the supplied UTXO; it
-does not broadcast the transaction or verify its confirmation. A `bch-anchor`
-tag is only a claim until an application independently verifies the transaction
-and its block inclusion.
+The library does not broadcast the transaction or fetch proofs. Mainnet
+verification uses a fixed checkpoint and is checkpointed SPV, not full-node
+validation; a supplied chain does not prove it is the globally highest-work
+branch. There is no built-in chipnet checkpoint, so chipnet anchors must not
+be presented as verified.
 
 ### NIP-05 handle resolution
 
@@ -246,17 +275,15 @@ Bindings are published as Nostr events of kind `30078` (NIP-78 addressable data)
 | `supersedes` | previous binding ID (key rotation) |
 | `t` | `cashlet-did` |
 
-The wallet receives the exact UTF-8 v2 message text and applies the Bitcoin
+The wallet receives the exact UTF-8 v3 message text and applies the Bitcoin
 Signed Message prefix, CompactSize byte length, and double-SHA256. Its response
 is standard padded Base64 for a 65-byte compact signature: header 31–34
-(compressed key plus recovery ID 0–3), followed by 64-byte `r || s`. V2
-verifiers strictly reject v1 hex/raw signature encodings. Revocation uses
+(compressed key plus recovery ID 0–3), followed by 64-byte `r || s`. V3
+verifiers strictly reject v1/v2 and hex/raw signature encodings. Revocation uses
 NIP-09 kind `5` deletion events.
 
 The local demo previews and verifies a binding but does **not** publish or query
-Nostr relays. Its separate HTTP verifier demo demonstrates challenge issue,
-verification, and replay rejection locally; `/resolve` needs a published
-binding and relay access.
+Nostr relays; `/resolve` needs a published binding and relay access.
 
 ## Relays
 

package/dist/anchor-verification.d.ts

@@ -0,0 +1,44 @@
+export interface BchSpvCheckpoint {
+    height: number;
+    headerHex: string;
+    hash: string;
+    recentTimestamps: number[];
+}
+export interface BchAsertParameters {
+    anchorHeight: number;
+    anchorBits: number;
+    anchorPreviousBlockTime: number;
+    powLimitBits: number;
+    allowMinDifficultyBlocks?: boolean;
+}
+export interface BchAnchorProof {
+    transactionHex: string;
+    blockHeight: number;
+    transactionIndex: number;
+    merkleBranch: string[];
+    headers: string[];
+}
+export interface BchAnchorVerificationOptions {
+    checkpoint: BchSpvCheckpoint;
+    asert: BchAsertParameters;
+    minConfirmations?: number;
+    maxHeaders?: number;
+    now?: number;
+}
+export interface BchAnchorVerificationResult {
+    status: "confirmed" | "pending" | "invalid" | "unverifiable";
+    txid?: string;
+    blockHeight?: number;
+    tipHeight?: number;
+    confirmations?: number;
+    error?: string;
+    trustModel: "checkpointed-spv";
+}
+/**
+ * Verify a BCH transaction commitment, Merkle inclusion, and an ASERT header
+ * chain extending from an application-trusted checkpoint. The proof source is
+ * untrusted; checkpoint selection remains the caller's explicit trust root.
+ */
+export declare function verifyBchAnchorProof(proof: BchAnchorProof, bindingId: string, options: BchAnchorVerificationOptions): BchAnchorVerificationResult;
+export declare const BCH_MAINNET_ASERT_PARAMETERS: BchAsertParameters;
+export declare const BCH_MAINNET_CHECKPOINT: BchSpvCheckpoint;

package/dist/anchor-verification.js

@@ -0,0 +1,250 @@
+import { decodeTransaction, hash256, hexToBin } from "@bitauth/libauth";
+import { ANCHOR_PREFIX } from "./anchor.js";
+const HEADER_BYTES = 80;
+const MAX_PROOF_HEADERS = 2048;
+const TARGET_SPACING_SECS = 600n;
+const ASERT_HALF_LIFE_SECS = 172800n;
+const ASERT_RADIX = 1n << 16n;
+function bytesToHex(bytes) {
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+}
+function reverse(bytes) {
+    return Uint8Array.from(bytes).reverse();
+}
+function parseHex(value, byteLength) {
+    if (!/^(?:[0-9a-f]{2})+$/i.test(value))
+        throw new Error("Expected even-length hexadecimal data");
+    const bytes = hexToBin(value);
+    if (typeof bytes === "string" || (byteLength !== undefined && bytes.length !== byteLength))
+        throw new Error("Invalid hexadecimal data length");
+    return bytes;
+}
+function parseHeader(headerHex) {
+    const raw = parseHex(headerHex, HEADER_BYTES);
+    const hash = hash256(raw);
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    return {
+        raw,
+        hash,
+        hashHex: bytesToHex(reverse(hash)),
+        previousHash: raw.slice(4, 36),
+        merkleRoot: raw.slice(36, 68),
+        timestamp: view.getUint32(68, true),
+        bits: view.getUint32(72, true),
+    };
+}
+function compactToTarget(bits) {
+    const exponent = bits >>> 24;
+    const mantissa = bits & 0x007fffff;
+    const negative = (bits & 0x00800000) !== 0;
+    const overflow = mantissa !== 0 && (exponent > 34 ||
+        (mantissa > 0xff && exponent > 33) ||
+        (mantissa > 0xffff && exponent > 32));
+    if (negative || overflow || mantissa === 0)
+        throw new Error("Invalid compact difficulty target");
+    const target = exponent <= 3
+        ? BigInt(mantissa) >> (8n * BigInt(3 - exponent))
+        : BigInt(mantissa) << (8n * BigInt(exponent - 3));
+    if (target <= 0n || target >= (1n << 256n))
+        throw new Error("Difficulty target is out of range");
+    if (targetToCompact(target) !== bits)
+        throw new Error("Non-canonical compact difficulty target");
+    return target;
+}
+function targetToCompact(target) {
+    let size = Math.ceil(target.toString(16).length / 2);
+    let compact = size <= 3
+        ? Number(target << (8n * BigInt(3 - size)))
+        : Number(target >> (8n * BigInt(size - 3)));
+    if (compact & 0x00800000) {
+        compact >>>= 8;
+        size++;
+    }
+    return ((size << 24) | compact) >>> 0;
+}
+function asertTarget(parameters, previousHeight, previousTime) {
+    const anchorTarget = compactToTarget(parameters.anchorBits);
+    const timeDifference = BigInt(previousTime - parameters.anchorPreviousBlockTime);
+    const heightDifference = BigInt(previousHeight - parameters.anchorHeight);
+    if (heightDifference < 0n)
+        throw new Error("Checkpoint predates the ASERT anchor");
+    const exponent = ((timeDifference - TARGET_SPACING_SECS * heightDifference) * ASERT_RADIX) /
+        ASERT_HALF_LIFE_SECS;
+    const shifts = exponent >> 16n;
+    const fraction = exponent & 0xffffn;
+    const factor = ASERT_RADIX + ((195766423245049n * fraction +
+        971821376n * fraction * fraction +
+        5127n * fraction * fraction * fraction +
+        (1n << 47n)) >> 48n);
+    let target = anchorTarget * factor;
+    const shift = shifts - 16n;
+    target = shift <= 0n ? target >> -shift : target << shift;
+    const powLimit = compactToTarget(parameters.powLimitBits);
+    if (target <= 0n)
+        return 1n;
+    return target > powLimit ? powLimit : target;
+}
+function expectedBits(parameters, previousHeight, previous, candidateTime) {
+    if (parameters.allowMinDifficultyBlocks &&
+        candidateTime > previous.timestamp + Number(2n * TARGET_SPACING_SECS))
+        return parameters.powLimitBits;
+    return targetToCompact(asertTarget(parameters, previousHeight, previous.timestamp));
+}
+function assertProofOfWork(header, powLimit) {
+    const target = compactToTarget(header.bits);
+    if (target > powLimit)
+        throw new Error("Header target exceeds the network proof-of-work limit");
+    const hashValue = BigInt(`0x${header.hashHex}`);
+    if (hashValue > target)
+        throw new Error("Header does not satisfy proof of work");
+    return target;
+}
+function transactionId(transactionHex) {
+    const raw = parseHex(transactionHex);
+    const decoded = decodeTransaction(raw);
+    if (typeof decoded === "string")
+        throw new Error(`Invalid transaction: ${decoded}`);
+    return { txid: bytesToHex(reverse(hash256(raw))), outputs: decoded.outputs };
+}
+function hasBindingCommitment(outputs, bindingId) {
+    const data = new TextEncoder().encode(`${ANCHOR_PREFIX}${bindingId}`);
+    const expected = new Uint8Array([0x6a, 0x4c, data.length, ...data]);
+    return outputs.filter(output => output.valueSatoshis === 0n &&
+        output.lockingBytecode.length === expected.length &&
+        output.lockingBytecode.every((byte, index) => byte === expected[index])).length === 1;
+}
+function verifyMerkleBranch(txid, transactionIndex, branch, merkleRoot) {
+    if (!Number.isSafeInteger(transactionIndex) || transactionIndex < 0 || branch.length > 32)
+        return false;
+    let index = transactionIndex;
+    let hash = reverse(parseHex(txid, 32));
+    for (const siblingHex of branch) {
+        const sibling = reverse(parseHex(siblingHex, 32));
+        hash = index & 1
+            ? hash256(new Uint8Array([...sibling, ...hash]))
+            : hash256(new Uint8Array([...hash, ...sibling]));
+        index = Math.floor(index / 2);
+    }
+    return index === 0 && hash.every((byte, position) => byte === merkleRoot[position]);
+}
+function result(status, error, details = {}) {
+    return {
+        status,
+        trustModel: "checkpointed-spv",
+        ...(error ? { error } : {}),
+        ...details,
+    };
+}
+/**
+ * Verify a BCH transaction commitment, Merkle inclusion, and an ASERT header
+ * chain extending from an application-trusted checkpoint. The proof source is
+ * untrusted; checkpoint selection remains the caller's explicit trust root.
+ */
+export function verifyBchAnchorProof(proof, bindingId, options) {
+    try {
+        if (!/^[0-9a-f]{64}$/.test(bindingId))
+            return result("invalid", "Invalid binding ID");
+        const minConfirmations = options.minConfirmations ?? 6;
+        const maxHeaders = options.maxHeaders ?? MAX_PROOF_HEADERS;
+        if (!Number.isSafeInteger(minConfirmations) || minConfirmations < 1)
+            return result("invalid", "Minimum confirmations must be a positive integer");
+        if (!Number.isSafeInteger(maxHeaders) || maxHeaders < 1)
+            return result("invalid", "Maximum header count must be a positive integer");
+        if (!proof || !Array.isArray(proof.headers) || proof.headers.length === 0)
+            return result("unverifiable", "Header chain proof is missing");
+        if (proof.headers.length > maxHeaders)
+            return result("unverifiable", "Header chain exceeds the configured verification limit");
+        const checkpoint = options.checkpoint;
+        const checkpointHeader = parseHeader(checkpoint.headerHex);
+        if (!Number.isSafeInteger(checkpoint.height) ||
+            checkpoint.height < options.asert.anchorHeight ||
+            !Number.isSafeInteger(options.asert.anchorHeight) ||
+            !Number.isSafeInteger(options.asert.anchorPreviousBlockTime) ||
+            !Number.isSafeInteger(options.asert.powLimitBits) ||
+            checkpointHeader.hashHex !== checkpoint.hash.toLowerCase() ||
+            !Array.isArray(checkpoint.recentTimestamps) ||
+            checkpoint.recentTimestamps.length !== 11 ||
+            checkpoint.recentTimestamps[checkpoint.recentTimestamps.length - 1] !== checkpointHeader.timestamp)
+            return result("unverifiable", "Invalid or unsupported trusted checkpoint");
+        if (!Number.isSafeInteger(proof.blockHeight) || proof.blockHeight <= checkpoint.height)
+            return result("unverifiable", "Anchor predates the configured trusted checkpoint");
+        if (!Number.isSafeInteger(proof.blockHeight) ||
+            !Number.isSafeInteger(proof.transactionIndex) ||
+            !Array.isArray(proof.merkleBranch))
+            return result("invalid", "Malformed Merkle proof");
+        const transaction = transactionId(proof.transactionHex);
+        if (!hasBindingCommitment(transaction.outputs, bindingId))
+            return result("invalid", "Transaction does not contain the exact binding commitment", { txid: transaction.txid });
+        let previous = checkpointHeader;
+        let previousHeight = checkpoint.height;
+        let timestamps = checkpoint.recentTimestamps.slice(-11);
+        let inclusionHeader;
+        const powLimit = compactToTarget(options.asert.powLimitBits);
+        const now = options.now ?? Math.floor(Date.now() / 1000);
+        for (let offset = 0; offset < proof.headers.length; offset++) {
+            const height = checkpoint.height + offset + 1;
+            const header = parseHeader(proof.headers[offset]);
+            if (!header.previousHash.every((byte, index) => byte === previous.hash[index]))
+                return result("invalid", `Header chain link failed at height ${height}`);
+            if (header.timestamp <= [...timestamps].sort((a, b) => a - b)[Math.floor(timestamps.length / 2)])
+                return result("invalid", `Header timestamp violates median-time-past at height ${height}`);
+            if (header.timestamp > now + 2 * 60 * 60)
+                return result("invalid", `Header timestamp is too far in the future at height ${height}`);
+            const requiredBits = expectedBits(options.asert, previousHeight, previous, header.timestamp);
+            if (header.bits !== requiredBits)
+                return result("invalid", `Unexpected difficulty target at height ${height}`);
+            assertProofOfWork(header, powLimit);
+            if (height === proof.blockHeight)
+                inclusionHeader = header;
+            timestamps = [...timestamps, header.timestamp].slice(-11);
+            previous = header;
+            previousHeight = height;
+        }
+        const tipHeight = checkpoint.height + proof.headers.length;
+        if (!inclusionHeader)
+            return result("invalid", "Inclusion block is not present in the supplied header chain", { txid: transaction.txid, tipHeight });
+        if (!verifyMerkleBranch(transaction.txid, proof.transactionIndex, proof.merkleBranch, inclusionHeader.merkleRoot))
+            return result("invalid", "Transaction Merkle proof does not match the inclusion block", {
+                txid: transaction.txid,
+                blockHeight: proof.blockHeight,
+                tipHeight,
+            });
+        const confirmations = tipHeight - proof.blockHeight + 1;
+        return result(confirmations >= minConfirmations ? "confirmed" : "pending", undefined, {
+            txid: transaction.txid,
+            blockHeight: proof.blockHeight,
+            tipHeight,
+            confirmations,
+        });
+    }
+    catch (error) {
+        return result("invalid", error instanceof Error ? error.message : String(error));
+    }
+}
+export const BCH_MAINNET_ASERT_PARAMETERS = {
+    anchorHeight: 661647,
+    anchorBits: 0x1804dafe,
+    anchorPreviousBlockTime: 1605447844,
+    powLimitBits: 0x1d00ffff,
+};
+// Fixed trust root, cross-checked against two independent BCH mainnet Electrum
+// servers. Refresh in a reviewed release as it ages; never fetch trust roots
+// from the same untrusted endpoint that supplies a proof.
+export const BCH_MAINNET_CHECKPOINT = {
+    height: 975752,
+    hash: "0000000000000000010a200fe779aa3c313c7fc1b355b13560ef105709d153fd",
+    headerHex: "000000248509713afafd1db2ec77ef48baf6522757a8b2cd8cb315000000000000000000d70ca4e92d1bc9485441fb6626766cc8a350e59cc44b6a15ddc36dae072f9b60eaa7e96a680f02181a62ef3c",
+    recentTimestamps: [
+        1793688001,
+        1793688081,
+        1793688330,
+        1793692665,
+        1793693308,
+        1793694029,
+        1793694650,
+        1793696313,
+        1793696954,
+        1793697100,
+        1793697770,
+    ],
+};

package/dist/binding.d.ts

@@ -1,7 +1,8 @@
 import { type BchMessageProof } from "./signing.js";
 export declare const PROTOCOL_ID = "cashlet-did";
-export declare const PROTOCOL_VERSION = "2.0.0";
+export declare const PROTOCOL_VERSION = "3.0.0";
 export declare const BINDING_KIND = 30078;
+export declare const ROTATION_AUTH_KIND = 30080;
 export type Network = "mainnet" | "testnet" | "chipnet";
 export interface CanonicalBinding {
     protocol: typeof PROTOCOL_ID;
@@ -17,7 +18,7 @@ export interface CanonicalBinding {
     };
     createdAt: number;
     nonce: string;
-    purpose: "identity-binding-v2";
+    purpose: "identity-binding-v3";
     previousBindingId?: string;
     anchor?: {
         txid: string;
@@ -30,6 +31,7 @@ export interface IdentityBinding {
     nostrProof: {
         event: NostrEvent;
     };
+    rotationAuthorization?: NostrEvent;
     publishedAt?: number;
 }
 export interface NostrEvent {
@@ -45,7 +47,14 @@ export declare function canonicalize(v: unknown): string;
 export declare function sha256hex(s: string): Promise<string>;
 export declare function buildBinding(bchAddress: string, network: Network, nostrPubkey: string, paymentCode?: string, previousBindingId?: string): Promise<CanonicalBinding>;
 export declare function bchSigningPayload(binding: CanonicalBinding): string;
-export declare function nostrEventTemplate(binding: CanonicalBinding, bchProof?: BchMessageProof): {
+export declare function rotationAuthorizationTemplate(previous: CanonicalBinding, successor: CanonicalBinding): {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+};
+export declare function verifyRotationAuthorization(authorization: NostrEvent, previous: CanonicalBinding, successor: CanonicalBinding): boolean;
+export declare function nostrEventTemplate(binding: CanonicalBinding, bchProof?: BchMessageProof, rotationAuthorization?: NostrEvent): {
     kind: number;
     created_at: number;
     tags: string[][];

package/dist/binding.js

@@ -1,7 +1,9 @@
 import { BCH_PROOF_FORMAT, normalizeBchMessageSignature, } from "./signing.js";
+import { verifyEvent } from "nostr-tools";
 export const PROTOCOL_ID = "cashlet-did";
-export const PROTOCOL_VERSION = "2.0.0";
+export const PROTOCOL_VERSION = "3.0.0";
 export const BINDING_KIND = 30078;
+export const ROTATION_AUTH_KIND = 30080;
 export function canonicalize(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v);
@@ -38,7 +40,7 @@ export async function buildBinding(bchAddress, network, nostrPubkey, paymentCode
         nostr: { pubkey: nostrPubkey },
         createdAt: Math.floor(Date.now() / 1000),
         nonce: randomHex(32),
-        purpose: "identity-binding-v2",
+        purpose: "identity-binding-v3",
         ...(previousBindingId ? { previousBindingId } : {}),
     };
     const bindingId = await sha256hex(canonicalize(partial));
@@ -55,12 +57,56 @@ export function bchSigningPayload(binding) {
         createdAt: binding.createdAt,
     });
 }
-export function nostrEventTemplate(binding, bchProof) {
+export function rotationAuthorizationTemplate(previous, successor) {
+    if (successor.previousBindingId !== previous.bindingId)
+        throw new Error("Successor must reference the previous binding");
+    if (successor.nostr.pubkey === previous.nostr.pubkey)
+        throw new Error("Rotation authorization is only required when the Nostr key changes");
+    return {
+        kind: ROTATION_AUTH_KIND,
+        created_at: successor.createdAt,
+        tags: [
+            ["d", successor.bindingId],
+            ["protocol", PROTOCOL_ID, PROTOCOL_VERSION],
+            ["t", `${PROTOCOL_ID}-rotation`],
+        ],
+        content: canonicalize({
+            protocol: PROTOCOL_ID,
+            version: PROTOCOL_VERSION,
+            purpose: "key-rotation-authorization-v3",
+            previousBindingId: previous.bindingId,
+            previousPubkey: previous.nostr.pubkey,
+            successorBindingId: successor.bindingId,
+            successorPubkey: successor.nostr.pubkey,
+            successorBch: successor.bch,
+            createdAt: successor.createdAt,
+        }),
+    };
+}
+export function verifyRotationAuthorization(authorization, previous, successor) {
+    if (!authorization ||
+        authorization.kind !== ROTATION_AUTH_KIND ||
+        authorization.pubkey !== previous.nostr.pubkey ||
+        authorization.created_at !== successor.createdAt ||
+        !Array.isArray(authorization.tags) ||
+        !verifyEvent(authorization))
+        return false;
+    const expected = rotationAuthorizationTemplate(previous, successor);
+    return authorization.content === expected.content &&
+        JSON.stringify(authorization.tags) === JSON.stringify(expected.tags);
+}
+export function nostrEventTemplate(binding, bchProof, rotationAuthorization) {
     if (bchProof) {
         if (bchProof.message !== bchSigningPayload(binding))
             throw new Error("BCH proof message does not match the binding");
         normalizeBchMessageSignature(bchProof.signatureBase64);
     }
+    if (!binding.previousBindingId && rotationAuthorization)
+        throw new Error("Unexpected rotation authorization without a predecessor");
+    if (rotationAuthorization && (rotationAuthorization.kind !== ROTATION_AUTH_KIND ||
+        !Array.isArray(rotationAuthorization.tags) ||
+        rotationAuthorization.tags.find(tag => tag[0] === "d")?.[1] !== binding.bindingId))
+        throw new Error("Rotation authorization does not match the successor binding");
     return {
         kind: BINDING_KIND,
         created_at: binding.createdAt,
@@ -71,6 +117,7 @@ export function nostrEventTemplate(binding, bchProof) {
             ["protocol", PROTOCOL_ID, PROTOCOL_VERSION],
             ["t", PROTOCOL_ID],
             ...(binding.previousBindingId ? [["supersedes", binding.previousBindingId]] : []),
+            ...(rotationAuthorization ? [["rotation-proof", rotationAuthorization.id, rotationAuthorization.pubkey]] : []),
             ...(binding.anchor ? [["bch-anchor", binding.anchor.txid, ...(binding.anchor.blockHeight ? [String(binding.anchor.blockHeight)] : [])]] : []),
             ...(bchProof ? [["bch-proof", BCH_PROOF_FORMAT, bchProof.message, bchProof.signatureBase64]] : []),
         ],
@@ -82,6 +129,7 @@ export function nostrEventTemplate(binding, bchProof) {
             nonce: binding.nonce,
             createdAt: binding.createdAt,
             ...(binding.previousBindingId ? { previousBindingId: binding.previousBindingId } : {}),
+            ...(rotationAuthorization ? { rotationAuthorization } : {}),
         }),
     };
 }

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { buildDisclosure, verifyDisclosure, type Disclosure, type DisclosureReveal, } from "./disclosure.js";
 export { buildAnchorTx, ANCHOR_PREFIX, type AnchorUtxo, type AnchorResult, } from "./anchor.js";
+export { verifyBchAnchorProof, BCH_MAINNET_ASERT_PARAMETERS, BCH_MAINNET_CHECKPOINT, type BchSpvCheckpoint, type BchAsertParameters, type BchAnchorProof, type BchAnchorVerificationOptions, type BchAnchorVerificationResult, } from "./anchor-verification.js";
 export { issueCredential, issueRating, revokeCredential, resolveCredentials, scoreReputation, CREDENTIAL_KIND, type CredentialPayload, type IssuedCredential, } from "./credentials.js";
-export { PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, type Network, type CanonicalBinding, type IdentityBinding, type NostrEvent, buildBinding, bchSigningPayload, nostrEventTemplate, canonicalize, sha256hex, } from "./binding.js";
+export { PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, ROTATION_AUTH_KIND, type Network, type CanonicalBinding, type IdentityBinding, type NostrEvent, buildBinding, bchSigningPayload, nostrEventTemplate, rotationAuthorizationTemplate, verifyRotationAuthorization, canonicalize, sha256hex, } from "./binding.js";
 export { BCH_PROOF_FORMAT, normalizeBchMessageSignature, signBchMessage, type BchMessageProof, type BchMessageSigner, type BchProofTag, } from "./signing.js";
 export { publishToRelay, publishToRelays, queryRelay, queryRelays, DEFAULT_RELAYS, type RelayResult, } from "./relay.js";
-export { resolveIdentity, resolveAddress, resolveByNip05, verifyIdentity, bchChallengePayload, verifyChallengeProof, resolveIdentityChain, type VerifyResult, type VerifyStatus, type ResolvedIdentity, type BCHAnchorClaim, } from "./verify.js";
+export { resolveIdentity, resolveAddress, resolveByNip05, verifyIdentity, bchChallengePayload, nostrChallengeTemplate, verifyDualChallengeProof, NOSTR_CHALLENGE_KIND, type DualChallengeProof, verifyChallengeProof, resolveIdentityChain, type VerifyResult, type VerifyStatus, type ResolvedIdentity, type BCHAnchorClaim, } from "./verify.js";
 export { CashletDidError, type CashletDidErrorCode } from "./errors.js";
 export { deriveNostrKeypair, type NostrKeypair, } from "./keygen.js";
 export { buildHttpAuthEventAsync, verifyHttpAuth, type HttpAuthEventTemplate, type HttpAuthResult, } from "./nip98.js";

package/dist/index.js

@@ -1,18 +1,19 @@
 export { buildDisclosure, verifyDisclosure, } from "./disclosure.js";
 export { buildAnchorTx, ANCHOR_PREFIX, } from "./anchor.js";
+export { verifyBchAnchorProof, BCH_MAINNET_ASERT_PARAMETERS, BCH_MAINNET_CHECKPOINT, } from "./anchor-verification.js";
 export { issueCredential, issueRating, revokeCredential, resolveCredentials, scoreReputation, CREDENTIAL_KIND, } from "./credentials.js";
 export { 
 // Protocol constants
-PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, 
+PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, ROTATION_AUTH_KIND, 
 // Binding construction
-buildBinding, bchSigningPayload, nostrEventTemplate, canonicalize, sha256hex, } from "./binding.js";
+buildBinding, bchSigningPayload, nostrEventTemplate, rotationAuthorizationTemplate, verifyRotationAuthorization, canonicalize, sha256hex, } from "./binding.js";
 export { BCH_PROOF_FORMAT, normalizeBchMessageSignature, signBchMessage, } from "./signing.js";
 export { 
 // Relay communication
 publishToRelay, publishToRelays, queryRelay, queryRelays, DEFAULT_RELAYS, } from "./relay.js";
 export { 
 // Verification
-resolveIdentity, resolveAddress, resolveByNip05, verifyIdentity, bchChallengePayload, verifyChallengeProof, resolveIdentityChain, } from "./verify.js";
+resolveIdentity, resolveAddress, resolveByNip05, verifyIdentity, bchChallengePayload, nostrChallengeTemplate, verifyDualChallengeProof, NOSTR_CHALLENGE_KIND, verifyChallengeProof, resolveIdentityChain, } from "./verify.js";
 export { CashletDidError } from "./errors.js";
 export { deriveNostrKeypair, } from "./keygen.js";
 export { buildHttpAuthEventAsync, verifyHttpAuth, } from "./nip98.js";

package/dist/verify.d.ts

@@ -1,6 +1,6 @@
 import { canonicalize, sha256hex, bchSigningPayload, type CanonicalBinding, type IdentityBinding, type NostrEvent } from "./binding.js";
 import { type BchProofTag } from "./signing.js";
-export type VerifyStatus = "verified" | "invalid_bch_sig" | "invalid_nostr_sig" | "id_mismatch" | "malformed" | "expired";
+export type VerifyStatus = "verified" | "invalid_bch_sig" | "invalid_nostr_sig" | "id_mismatch" | "invalid_rotation" | "malformed" | "expired";
 export interface VerifyResult {
     status: VerifyStatus;
     bchValid: boolean;
@@ -11,6 +11,13 @@ export interface BCHAnchorClaim {
     txid: string;
     blockHeight?: number;
 }
+export declare const NOSTR_CHALLENGE_KIND = 27235;
+export interface DualChallengeProof {
+    signature: string;
+    payload: string;
+    address: string;
+    nostrEvent: NostrEvent;
+}
 export interface ResolvedIdentity {
     npub: string;
     pubkey: string;
@@ -20,6 +27,7 @@ export interface ResolvedIdentity {
     createdAt: number;
     bchProofTag: BchProofTag;
     rawEvent: NostrEvent;
+    rotationAuthorization?: NostrEvent;
     /** Unverified metadata claimed by the event; this library does not verify chain inclusion. */
     anchorClaim?: BCHAnchorClaim;
 }
@@ -29,6 +37,20 @@ export declare function resolveIdentity(npub: string, relays?: string[]): Promis
 export declare function verifyIdentity(resolved: ResolvedIdentity): Promise<VerifyResult>;
 /** Build the exact versioned challenge message that a BCH wallet must sign. */
 export declare function bchChallengePayload(nonce: string, audience?: string): string;
+export declare function nostrChallengeTemplate(nonce: string, audience: string, endpoint: string, issuedAt: number): {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+};
+export declare function verifyDualChallengeProof(proof: DualChallengeProof, expected: {
+    nonce: string;
+    audience: string;
+    endpoint: string;
+    issuedAt: number;
+    address: string;
+    pubkey: string;
+}): boolean;
 /** Verify a challenge-response proof.
  * The wallet signs the exact text produced by `bchChallengePayload`.
  * @param issuedAt - unix timestamp when the challenge was issued; if provided, rejects proofs older than 5 minutes.

package/dist/verify.js

@@ -1,10 +1,11 @@
 import { verifyEvent, nip05 } from "nostr-tools";
 import { secp256k1, hash256, encodeCashAddress, hash160 } from "@bitauth/libauth";
-import { canonicalize, sha256hex, bchSigningPayload, BINDING_KIND, PROTOCOL_ID, PROTOCOL_VERSION, } from "./binding.js";
+import { canonicalize, sha256hex, bchSigningPayload, BINDING_KIND, PROTOCOL_ID, PROTOCOL_VERSION, verifyRotationAuthorization, } from "./binding.js";
 import { queryRelays, DEFAULT_RELAYS } from "./relay.js";
 import { CashletDidError } from "./errors.js";
 import { nip19 } from "nostr-tools";
 import { BCH_PROOF_FORMAT, normalizeBchMessageSignature, } from "./signing.js";
+export const NOSTR_CHALLENGE_KIND = 27235;
 /** Encode n as a Bitcoin CompactSize integer. */
 function varint(n) {
     if (n < 0xfd)
@@ -164,10 +165,12 @@ export async function verifyIdentity(resolved) {
         const proofTag = exactlyOne("bch-proof");
         const paymentCodeTag = optionalTag("bch-payment-code");
         const supersedesTag = optionalTag("supersedes");
+        const rotationTag = optionalTag("rotation-proof");
         const anchorTag = optionalTag("bch-anchor");
+        const rotationAuthorization = content.rotationAuthorization;
         const previousBindingId = content.previousBindingId;
         const contentKeys = Object.keys(content).sort().join(",");
-        const allowedContentKeys = ["bch", "bindingId", "createdAt", "nonce", "previousBindingId", "protocol", "version"]
+        const allowedContentKeys = ["bch", "bindingId", "createdAt", "nonce", "previousBindingId", "protocol", "rotationAuthorization", "version"]
             .filter(key => content[key] !== undefined).sort().join(",");
         const bchKeys = bch && typeof bch === "object" && !Array.isArray(bch)
             ? Object.keys(bch).sort().join(",")
@@ -197,7 +200,16 @@ export async function verifyIdentity(resolved) {
             (bch.paymentCode === undefined ? paymentCodeTag !== undefined : (!paymentCodeTag || paymentCodeTag.length !== 2 || paymentCodeTag[1] !== bch.paymentCode)) ||
             getTags("bch-payment-code").length > 1 ||
             (previousBindingId === undefined ? supersedesTag !== undefined : (!supersedesTag || supersedesTag.length !== 2 || supersedesTag[1] !== previousBindingId)) ||
+            (rotationAuthorization === undefined ? rotationTag !== undefined : (!rotationAuthorization ||
+                typeof rotationAuthorization !== "object" ||
+                !rotationTag ||
+                rotationTag.length !== 3 ||
+                rotationTag[1] !== rotationAuthorization.id ||
+                rotationTag[2] !== rotationAuthorization.pubkey ||
+                !verifyEvent(rotationAuthorization))) ||
+            (rotationAuthorization !== undefined && previousBindingId === undefined) ||
             getTags("supersedes").length > 1 ||
+            getTags("rotation-proof").length > 1 ||
             getTags("bch-anchor").length > 1 ||
             (anchorTag !== undefined && ((anchorTag.length !== 2 && anchorTag.length !== 3) ||
                 !/^[0-9a-f]{64}$/.test(anchorTag[1]) ||
@@ -232,7 +244,7 @@ export async function verifyIdentity(resolved) {
             nostr: { pubkey: rawEvent.pubkey },
             createdAt: content.createdAt,
             nonce: content.nonce,
-            purpose: "identity-binding-v2",
+            purpose: "identity-binding-v3",
             ...(previousBindingId !== undefined ? { previousBindingId } : {}),
         };
         const expectedBindingId = await sha256hex(canonicalize(partial));
@@ -263,6 +275,61 @@ export function bchChallengePayload(nonce, audience) {
         throw new TypeError("Challenge audience must be a non-empty single-line string");
     return `${PROTOCOL_ID}/challenge/v${PROTOCOL_VERSION}\n${nonce}${audience === undefined ? "" : `\n${audience}`}`;
 }
+export function nostrChallengeTemplate(nonce, audience, endpoint, issuedAt) {
+    const payload = bchChallengePayload(nonce, audience);
+    if (!Number.isSafeInteger(issuedAt) || issuedAt <= 0)
+        throw new TypeError("Challenge issue time must be a positive Unix timestamp");
+    if (typeof endpoint !== "string" || endpoint.length === 0 || /[\r\n]/.test(endpoint))
+        throw new TypeError("Challenge endpoint must be a non-empty single-line URL");
+    return {
+        kind: NOSTR_CHALLENGE_KIND,
+        created_at: issuedAt,
+        tags: [
+            ["u", endpoint],
+            ["method", "POST"],
+            ["audience", audience],
+            ["challenge", nonce],
+            ["expiration", String(issuedAt + CHALLENGE_TTL_SECS)],
+        ],
+        content: payload,
+    };
+}
+export function verifyDualChallengeProof(proof, expected) {
+    if (!proof ||
+        proof.address !== expected.address ||
+        !verifyChallengeProof(proof, expected.nonce, expected.audience, expected.issuedAt))
+        return false;
+    const event = proof.nostrEvent;
+    if (!event ||
+        event.kind !== NOSTR_CHALLENGE_KIND ||
+        event.pubkey !== expected.pubkey ||
+        event.created_at !== expected.issuedAt ||
+        event.content !== bchChallengePayload(expected.nonce, expected.audience) ||
+        !Array.isArray(event.tags))
+        return false;
+    const uniqueTag = (name) => {
+        const matches = event.tags.filter(tag => Array.isArray(tag) && tag[0] === name);
+        return matches.length === 1 ? matches[0] : undefined;
+    };
+    const endpointTag = uniqueTag("u");
+    const methodTag = uniqueTag("method");
+    const audienceTag = uniqueTag("audience");
+    const challengeTag = uniqueTag("challenge");
+    const expirationTag = uniqueTag("expiration");
+    const expectedTags = nostrChallengeTemplate(expected.nonce, expected.audience, expected.endpoint, expected.issuedAt).tags;
+    try {
+        return endpointTag?.[1] === expected.endpoint &&
+            methodTag?.[1] === "POST" &&
+            audienceTag?.[1] === expected.audience &&
+            challengeTag?.[1] === expected.nonce &&
+            expirationTag?.[1] === String(expected.issuedAt + CHALLENGE_TTL_SECS) &&
+            event.tags.length === expectedTags.length &&
+            verifyEvent(event);
+    }
+    catch {
+        return false;
+    }
+}
 /** Verify a challenge-response proof.
  * The wallet signs the exact text produced by `bchChallengePayload`.
  * @param issuedAt - unix timestamp when the challenge was issued; if provided, rejects proofs older than 5 minutes.
@@ -275,7 +342,9 @@ export function verifyChallengeProof(proof, nonce, audience, issuedAt) {
         typeof nonce !== "string")
         return false;
     if (issuedAt !== undefined &&
-        (!Number.isSafeInteger(issuedAt) || Math.floor(Date.now() / 1000) - issuedAt > CHALLENGE_TTL_SECS))
+        (!Number.isSafeInteger(issuedAt) ||
+            issuedAt > Math.floor(Date.now() / 1000) + 60 ||
+            Math.floor(Date.now() / 1000) - issuedAt > CHALLENGE_TTL_SECS))
         return false;
     let expectedPayload;
     try {
@@ -365,10 +434,53 @@ export async function resolveIdentityChain(npub, relays = DEFAULT_RELAYS) {
         }
         if (!predecessor)
             return [];
+        const predecessorBinding = canonicalBindingFromResolved(predecessor);
+        const successorBinding = canonicalBindingFromResolved(current);
+        if (!predecessorBinding || !successorBinding)
+            return [];
+        if (predecessor.pubkey !== current.pubkey) {
+            if (!current.rotationAuthorization ||
+                !verifyRotationAuthorization(current.rotationAuthorization, predecessorBinding, successorBinding))
+                return [];
+        }
+        else if (current.rotationAuthorization &&
+            !verifyRotationAuthorization(current.rotationAuthorization, predecessorBinding, successorBinding)) {
+            return [];
+        }
         current = predecessor;
     }
     return chain;
 }
+function canonicalBindingFromResolved(identity) {
+    try {
+        const content = JSON.parse(identity.rawEvent.content);
+        const bch = content.bch;
+        if (typeof content.nonce !== "string" ||
+            typeof content.createdAt !== "number" ||
+            typeof bch.address !== "string" ||
+            typeof bch.network !== "string" ||
+            !["mainnet", "testnet", "chipnet"].includes(bch.network))
+            return null;
+        return {
+            protocol: PROTOCOL_ID,
+            version: PROTOCOL_VERSION,
+            bindingId: identity.bindingId,
+            bch: {
+                address: bch.address,
+                network: bch.network,
+                ...(typeof bch.paymentCode === "string" ? { paymentCode: bch.paymentCode } : {}),
+            },
+            nostr: { pubkey: identity.pubkey },
+            createdAt: content.createdAt,
+            nonce: content.nonce,
+            purpose: "identity-binding-v3",
+            ...(typeof content.previousBindingId === "string" ? { previousBindingId: content.previousBindingId } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
 function resolvedIdentityFromEvent(event) {
     if (event.kind !== BINDING_KIND ||
         !/^[0-9a-f]{64}$/.test(event.pubkey) ||
@@ -408,6 +520,9 @@ function resolvedIdentityFromEvent(event) {
         createdAt,
         bchProofTag: bchProofTag,
         rawEvent: event,
+        ...(content.rotationAuthorization && typeof content.rotationAuthorization === "object"
+            ? { rotationAuthorization: content.rotationAuthorization }
+            : {}),
         ...(anchorTag?.[1] ? {
             anchorClaim: {
                 txid: anchorTag[1],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "did-beta-bch",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Decentralised identity protocol binding BCH addresses to Nostr public keys",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,4 +49,4 @@
     "esbuild": "^0.28.2",
     "typescript": "^5.4.0"
   }
-}
+}