did-beta-bch 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `cashlet-did` will be documented here.
 
+## [1.2.0] — 2026-07-31
+
+### Fixed
+- **Breaking:** Bitcoin signed message hash now uses correct compact-size (varint) length prefix.
+  Previously used a single truncated byte, making all published bindings unverifiable for payloads
+  ≥256 bytes. Bindings published with ≤1.1.0 must be re-published.
+
+### Added
+- `PROTOCOL.md` — standalone normative spec; third parties can implement compatible verifiers
+  without depending on this library.
+
+### Changed
+- Package published as `did-beta-bch` (placeholder name until stable release).
+
 ## [Unreleased]
 
 ### Added

package/PROTOCOL.md

@@ -0,0 +1,214 @@
+# Cashlet DID Protocol Specification
+
+Version: `1.0.0`  
+Status: Draft
+
+This document is the normative protocol specification. Any BCH wallet or Nostr
+client can implement compatibility by following this spec — no dependency on the
+`cashlet-did` library is required.
+
+---
+
+## 1. Identifiers
+
+| Constant | Value |
+|---|---|
+| Protocol ID | `cashlet-did` |
+| Protocol version | `1.0.0` |
+| Binding event kind | `30078` (NIP-78 addressable data) |
+| Credential event kind | `30085` |
+| Revocation event kind | `5` (NIP-09) |
+| Nostr derivation path | `m/44'/1237'/<account>'/0/0` (NIP-06) |
+
+---
+
+## 2. Canonical binding record
+
+A binding record is a JSON object with **sorted keys** (no whitespace) used as
+the input to the binding ID hash. Undefined/absent fields are omitted.
+
+```json
+{
+  "bch": {
+    "address": "<cashaddr>",
+    "network": "mainnet" | "testnet" | "chipnet",
+    "paymentCode": "<BIP47 payment code>"   // optional
+  },
+  "createdAt": <unix seconds>,
+  "nostr": { "pubkey": "<32-byte hex>" },
+  "nonce": "<64 hex chars of random bytes>",
+  "previousBindingId": "<hex>",             // optional, key rotation
+  "protocol": "cashlet-did",
+  "purpose": "identity-binding-v1",
+  "version": "1.0.0"
+}
+```
+
+**Binding ID** = `SHA-256(canonicalize(record_without_bindingId))` as lowercase hex.
+
+`canonicalize` means: recursively sort object keys alphabetically, no spaces,
+omit keys whose value is `undefined`. Arrays preserve order.
+
+---
+
+## 3. BCH signing payload
+
+```
+cashlet-did/bch-proof/v1.0.0\n<canonicalized subset>
+```
+
+The canonicalized subset contains exactly these keys (sorted):
+
+```json
+{
+  "bchAddress": "<cashaddr>",
+  "bchNetwork": "mainnet" | "testnet" | "chipnet",
+  "bindingId": "<hex>",
+  "createdAt": <unix seconds>,
+  "nonce": "<hex>",
+  "nostrPubkey": "<hex>",
+  "purpose": "identity-binding-v1"
+}
+```
+
+### BCH signature format
+
+Bitcoin signed message format:
+
+```
+SHA256d( "\x18Bitcoin Signed Message:\n" + varint(len(payload_bytes)) + payload_bytes )
+```
+
+`varint` is Bitcoin compact-size encoding:
+- `n < 0xfd` → 1 byte `[n]`
+- `0xfd ≤ n ≤ 0xffff` → 3 bytes `[0xfd, n & 0xff, n >> 8]`
+
+The signature is a **65-byte recoverable compact signature**:
+`[recovery_id_byte (0–3)] + [64-byte compact sig]`, hex-encoded.
+
+> ⚠️ Signing payloads are typically ~400 bytes. A single-byte length prefix
+> (truncating to `n & 0xff`) is **wrong** and will produce unverifiable signatures.
+
+---
+
+## 4. Nostr event (kind 30078)
+
+```json
+{
+  "kind": 30078,
+  "pubkey": "<nostr pubkey hex>",
+  "created_at": <unix seconds>,
+  "tags": [
+    ["d",              "<bindingId>"],
+    ["bch",            "<cashaddr>", "<network>"],
+    ["bch-proof",      "<signing payload>", "<65-byte sig hex>"],
+    ["protocol",       "cashlet-did", "1.0.0"],
+    ["t",              "cashlet-did"],
+    ["bch-payment-code", "<BIP47 code>"],   // optional
+    ["supersedes",     "<previous bindingId>"],  // optional, key rotation
+    ["bch-anchor",     "<txid>", "<block timestamp unix>"]  // optional
+  ],
+  "content": "<canonicalized binding JSON>",
+  "id": "<NIP-01 event id>",
+  "sig": "<Schnorr sig>"
+}
+```
+
+---
+
+## 5. Discovery (NIP-01 filter)
+
+```json
+{ "kinds": [30078], "authors": ["<pubkey hex>"], "#t": ["cashlet-did"] }
+```
+
+Query any public Nostr relay. Default relays: `wss://nos.lol`,
+`wss://relay.damus.io`, `wss://relay.nostr.band`.
+
+Revocations are kind `5` events from the same author with `["e", "<event id>"]`
+tags. Filter revoked events before selecting the latest binding.
+
+---
+
+## 6. Verification algorithm
+
+1. Fetch binding event(s) via NIP-01 filter above.
+2. Fetch kind `5` revocations from the same author; discard revoked events.
+3. Select the event with the highest `created_at` among non-revoked results.
+4. Verify the **Nostr event signature** (NIP-01 Schnorr).
+5. Reconstruct the signing payload from the `bch-proof` tag (index 1).
+6. Compute `SHA256d` of the Bitcoin signed message over that payload (§3).
+7. Recover the BCH public key from the 65-byte signature + hash.
+8. Derive the P2PKH address from the recovered key; compare to the `bch` tag.
+9. Status is `verified` iff both signatures are valid.
+
+---
+
+## 7. Challenge-response authentication
+
+Payload format:
+
+```
+cashlet-did/challenge\n<nonce>\n<audience>
+```
+
+- `nonce`: random hex string issued by the verifier
+- `audience`: verifier's URL or identifier (optional but recommended)
+
+The wallet signs this payload using the same Bitcoin signed message format (§3).
+The verifier recovers the BCH address and checks it matches the binding.
+
+Implementations **should** enforce a 5-minute TTL on issued challenges.
+
+---
+
+## 8. Key rotation
+
+Set `previousBindingId` in the new binding record and add a
+`["supersedes", "<previousBindingId>"]` tag to the Nostr event.
+
+Resolvers can reconstruct the full rotation chain by following `supersedes` tags
+backwards. The newest non-revoked binding is the authoritative identity.
+
+---
+
+## 9. Selective disclosure
+
+Each attribute is committed as:
+
+```
+SHA-256( "cashlet-did/attr/<key>:<value>" )
+```
+
+Commitments are published in the binding (e.g. as extra tags or in content).
+To verify a revealed attribute, recompute the hash and compare to the commitment.
+
+---
+
+## 10. On-chain commitment (OP_RETURN)
+
+Embed the binding ID in a BCH transaction output:
+
+```
+OP_RETURN <"cashlet-did:" + bindingId>
+```
+
+The confirmed block's `time` field provides a consensus-enforced timestamp
+accurate to ~1 block (~10 minutes). It cannot be significantly backdated
+(median-time-past rule) and can drift at most 2 hours forward (miner clock
+skew allowance). Prefer `anchoredAt` over the self-reported `createdAt`.
+
+---
+
+## 11. NIP-05 handle resolution
+
+`user@domain` → `GET https://domain/.well-known/nostr.json?name=user`  
+→ extract `pubkey` → resolve binding via §5.
+
+---
+
+## 12. NIP-98 HTTP Auth
+
+Build a kind `27235` event per NIP-98. The `verifyBch: true` option on the
+server additionally resolves the signer's cashlet-did binding, proving BCH
+address ownership in the same request.

package/README.md

@@ -1,21 +1,31 @@
 # cashlet-did
 
-A standalone, framework-agnostic library implementing the **Cashlet DID protocol** — a decentralised identity layer that binds Bitcoin Cash (BCH) addresses to Nostr public keys.
+A standalone, framework-agnostic library implementing the **Cashlet DID protocol** — a decentralised identity layer that cryptographically binds Bitcoin Cash (BCH) addresses to Nostr public keys.
 
 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.
 
+## Real-world use cases
+
+**BCH wallet** — call `buildBinding` + `publishToRelays` once when a user sets up their identity. Anyone can then pay them by Nostr handle (`resolveAddress('npub1...')`) instead of exchanging addresses. Users never see the protocol.
+
+**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. No QR codes, no address copy-paste. When the merchant rotates keys, all payers automatically resolve the new address.
+
+**Passwordless login** — drop `verifyHttpAuth` into any web server. A NIP-07 browser extension (Alby, nos2x) signs the request transparently. The server gets a verified Nostr pubkey + BCH address — no OAuth, no email, no password database.
+
 ## Install
 
 ```sh
-npm install cashlet-did
+npm install did-beta-bch
 ```
 
-## Usage
+## Core usage
 
 ### Pay by handle — one call
 
 ```ts
-import { resolveAddress } from 'cashlet-did'
+import { resolveAddress } from 'did-beta-bch'
 
 const address = await resolveAddress('npub1...')
 // Returns a token-aware bitcoincash:z... address
@@ -25,55 +35,164 @@ if (address) wallet.sendTo(address, amount)
 
 ### Resolve + verify
 
+```ts
+import { resolveIdentity, verifyIdentity } from 'did-beta-bch'
+
 const identity = await resolveIdentity('npub1...')
 if (identity) {
-  console.log(identity.bchAddress) // bitcoincash:z...
   const result = await verifyIdentity(identity)
   console.log(result.status) // "verified"
+  console.log(identity.bchAddress) // bitcoincash:z...
 }
 ```
 
 ### Build and publish a binding (wallet integration)
 
 ```ts
-import { buildBinding, bchSigningPayload, nostrEventTemplate, publishToRelays, DEFAULT_RELAYS } from 'cashlet-did'
+import { buildBinding, bchSigningPayload, nostrEventTemplate, publishToRelays, DEFAULT_RELAYS } from 'did-beta-bch'
 import { finalizeEvent } from 'nostr-tools'
 
 const binding = await buildBinding(bchAddress, 'mainnet', nostrPubkeyHex)
 const message = bchSigningPayload(binding)
 
-// Sign message with BCH private key (recoverable compact sig)
+// Sign with BCH private key (recoverable compact sig)
 const bchSig = signWithBchKey(message) // your wallet's signing function
 
-const template = nostrEventTemplate(binding, { message, signature: bchSig })
-const event = finalizeEvent(template, nostrPrivkey)
+const event = finalizeEvent(nostrEventTemplate(binding, { message, signature: bchSig }), nostrPrivkey)
 await publishToRelays(DEFAULT_RELAYS, event)
 ```
 
-### Verify a challenge-response proof
+### Key derivation (NIP-06)
+
+```ts
+import { deriveNostrKeypair } from 'did-beta-bch'
+
+const { privkey, pubkey, npub, nsec } = deriveNostrKeypair(mnemonic)
+// account index for multiple independent identities from one seed
+const social = deriveNostrKeypair(mnemonic, 1)
+```
+
+### Challenge-response authentication
 
 ```ts
-import { verifyChallengeProof } from 'cashlet-did'
+import { verifyChallengeProof } from 'did-beta-bch'
 
+// Payload format: `cashlet-did/challenge\n<nonce>\n<audience>`
+// issuedAt enforces 5-minute TTL
 const valid = verifyChallengeProof(
   { signature, payload, address },
-  nonce
+  nonce,
+  audience,
+  issuedAt, // unix seconds — optional, rejects if > 5 min old
+)
+```
+
+### Key rotation
+
+```ts
+import { buildBinding, resolveIdentityChain } from 'did-beta-bch'
+
+// Rotate: reference the old binding
+const newBinding = await buildBinding(newAddress, 'mainnet', newNostrPub, undefined, oldBindingId)
+
+// Resolve full rotation history, newest first
+const chain = await resolveIdentityChain('npub1...')
+```
+
+### Verifiable credentials + reputation
+
+```ts
+import { issueCredential, resolveCredentials, issueRating, scoreReputation } from 'did-beta-bch'
+
+// Issue a credential (issuer signs with their Nostr key)
+const { credential } = await issueCredential(subjectNpub, 'merchant', issuerPrivkey, { since: '2024' })
+
+// Fetch + score reputation for an npub
+const creds = await resolveCredentials('npub1...')
+const score = await scoreReputation('npub1...')
+```
+
+### Selective disclosure
+
+```ts
+import { buildDisclosure, verifyDisclosure } from 'did-beta-bch'
+
+// Commit to attributes — publish commitments in binding
+const d = await buildDisclosure({ merchant: 'true', country: 'AU', kyc: 'passed' })
+
+// Later: reveal only what's needed
+const revealed = d.reveal(['merchant'])
+const { verified, failed } = await verifyDisclosure(revealed, d.commitments)
+```
+
+### BCH-anchored identity commitment
+
+```ts
+import { buildAnchorTx } 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 })
+```
+
+### NIP-05 handle resolution
+
+```ts
+import { resolveByNip05 } from 'did-beta-bch'
+
+// alice@cashlet.com → npub → verified BCH address
+const address = await resolveByNip05('alice@cashlet.com')
+if (address) wallet.sendTo(address, amount)
+```
+
+### NIP-98 HTTP Auth (server-side)
+
+```ts
+import { buildHttpAuthEventAsync, verifyHttpAuth } from 'did-beta-bch'
+import { finalizeEvent } from 'nostr-tools'
+
+// Client: build + sign auth event
+const template = await buildHttpAuthEventAsync('https://api.example.com/me', 'GET')
+const event = finalizeEvent(template, nostrPrivkey)
+const header = 'Nostr ' + btoa(JSON.stringify(event))
+// → send as Authorization header
+
+// Server: verify — proves Nostr identity + optionally BCH address ownership
+const result = await verifyHttpAuth(header, 'https://api.example.com/me', 'GET', { verifyBch: true })
+if (result.valid) {
+  console.log(result.pubkey)     // verified Nostr pubkey
+  console.log(result.bchAddress) // verified BCH address (if verifyBch: true)
+}
+```
+
+### NIP-89 App handler (advertise cashlet-did support)
+
+```ts
+import { buildAppHandlerEvent, publishToRelays, DEFAULT_RELAYS } from 'did-beta-bch'
+import { finalizeEvent } from 'nostr-tools'
+
+// Advertise that your app handles cashlet-did (kind 30078) events
+const event = finalizeEvent(
+  buildAppHandlerEvent('My App', 'https://myapp.com', 'BCH + Nostr identity'),
+  nostrPrivkey,
 )
+await publishToRelays(DEFAULT_RELAYS, event)
 ```
 
 ## Protocol
 
-Bindings are published as Nostr events of kind `30078` with the following tags:
+Bindings are published as Nostr events of kind `30078` (NIP-78 addressable data):
 
 | Tag | Value |
 |---|---|
 | `d` | binding ID (SHA-256 of canonical binding JSON) |
 | `bch` | BCH address, network |
-| `bch-proof` | signing payload, recoverable compact signature |
+| `bch-proof` | signing payload, 65-byte recoverable compact signature |
+| `bch-payment-code` | BIP47 payment code (optional, enables fresh address per payment) |
 | `protocol` | `cashlet-did`, version |
+| `supersedes` | previous binding ID (key rotation) |
 | `t` | `cashlet-did` |
 
-The BCH signature uses Bitcoin signed message format (`\x18Bitcoin Signed Message:\n`) with a 65-byte recoverable compact signature (recovery ID byte + 64-byte compact sig).
+The BCH signature uses Bitcoin signed message format (`\x18Bitcoin Signed Message:\n`) with a 65-byte recoverable compact signature (recovery ID byte + 64-byte compact sig). Revocation uses NIP-09 kind `5` deletion events.
 
 ## Relays
 

package/dist/anchor.js

@@ -8,6 +8,8 @@ const DUST_SATS = 1000; // anchor output value (burned)
 const FEE_SATS = 500;
 /** Build an OP_RETURN tx anchoring a bindingId to the BCH chain */
 export async function buildAnchorTx(bindingId, utxo) {
+    if (utxo.valueSats <= FEE_SATS)
+        throw new Error(`UTXO value ${utxo.valueSats} sats too small to cover fee ${FEE_SATS} sats`);
     const { encodeTransaction, generateTransaction, hexToBin, binToHex, walletTemplateP2pkhNonHd, importWalletTemplate, walletTemplateToCompilerBch } = await import("@bitauth/libauth");
     const data = ANCHOR_PREFIX + bindingId;
     const dataBytes = new TextEncoder().encode(data);

package/dist/binding.js

@@ -52,6 +52,7 @@ export function nostrEventTemplate(binding, bchProof) {
         tags: [
             ["d", binding.bindingId],
             ["bch", binding.bch.address, binding.bch.network],
+            ...(binding.bch.paymentCode ? [["bch-payment-code", binding.bch.paymentCode]] : []),
             ["protocol", PROTOCOL_ID, PROTOCOL_VERSION],
             ["t", PROTOCOL_ID],
             ...(binding.previousBindingId ? [["supersedes", binding.previousBindingId]] : []),

package/dist/credentials.d.ts

@@ -4,7 +4,7 @@
  * Subject's binding event links to received credentials via ["credential", eventId, issuerPubkey, type] tag.
  */
 import type { RelayResult } from "./relay.js";
-export declare const CREDENTIAL_KIND = 30079;
+export declare const CREDENTIAL_KIND = 30085;
 export interface CredentialPayload {
     subject: string;
     type: string;

package/dist/credentials.js

@@ -3,9 +3,9 @@
  * Issuer signs a Nostr event (kind 30079) attesting a claim about a subject npub.
  * Subject's binding event links to received credentials via ["credential", eventId, issuerPubkey, type] tag.
  */
-import { finalizeEvent, nip19 } from "nostr-tools";
+import { finalizeEvent, nip19, getPublicKey } from "nostr-tools";
 import { queryRelays, publishToRelays, DEFAULT_RELAYS } from "./relay.js";
-export const CREDENTIAL_KIND = 30079;
+export const CREDENTIAL_KIND = 30085; // kind 30079 is reserved for revocation (DID-PLAN)
 /** Issue a credential — issuer signs a Nostr event attesting a claim about subjectNpub */
 export async function issueCredential(subjectNpub, type, issuerPrivkey, claims, relays = DEFAULT_RELAYS) {
     const decoded = nip19.decode(subjectNpub);
@@ -30,7 +30,6 @@ export async function issueCredential(subjectNpub, type, issuerPrivkey, claims,
     };
     const signed = finalizeEvent(template, issuerPrivkey);
     const results = await publishToRelays(relays, signed);
-    const { getPublicKey } = await import("nostr-tools");
     const issuerPubkey = getPublicKey(issuerPrivkey);
     return {
         credential: { id: signed.id, issuer: issuerPubkey, payload, rawEvent: signed },
@@ -100,7 +99,6 @@ export async function issueRating(subjectNpub, rating, issuerPrivkey, opts = {},
     };
     const signed = finalizeEvent(template, issuerPrivkey);
     const results = await publishToRelays(relays, signed);
-    const { getPublicKey } = await import("nostr-tools");
     return {
         credential: { id: signed.id, issuer: getPublicKey(issuerPrivkey), payload, rawEvent: signed },
         results,

package/dist/index.d.ts

@@ -5,3 +5,6 @@ export { PROTOCOL_ID, PROTOCOL_VERSION, BINDING_KIND, type Network, type Canonic
 export { publishToRelay, publishToRelays, queryRelay, queryRelays, DEFAULT_RELAYS, type RelayResult, } from "./relay.js";
 export { resolveIdentity, resolveAddress, resolveByNip05, verifyIdentity, verifyChallengeProof, resolveIdentityChain, type VerifyResult, type VerifyStatus, type ResolvedIdentity, } 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";
+export { buildAppHandlerEvent, type AppHandlerEventTemplate, } from "./nip89.js";

package/dist/index.js

@@ -13,3 +13,6 @@ export {
 // Verification
 resolveIdentity, resolveAddress, resolveByNip05, verifyIdentity, verifyChallengeProof, resolveIdentityChain, } from "./verify.js";
 export { CashletDidError } from "./errors.js";
+export { deriveNostrKeypair, } from "./keygen.js";
+export { buildHttpAuthEventAsync, verifyHttpAuth, } from "./nip98.js";
+export { buildAppHandlerEvent, } from "./nip89.js";

package/dist/keygen.d.ts

@@ -0,0 +1,13 @@
+export interface NostrKeypair {
+    privkey: Uint8Array;
+    pubkey: string;
+    npub: string;
+    nsec: string;
+    account: number;
+}
+/**
+ * Derive a Nostr keypair from a BIP39 mnemonic using NIP-06 path.
+ * Path: m/44'/1237'/<account>'/0/0
+ * account=0 is the default identity; higher indices produce independent keypairs.
+ */
+export declare function deriveNostrKeypair(mnemonic: string, account?: number): NostrKeypair;

package/dist/keygen.js

@@ -0,0 +1,17 @@
+import { HDKey } from "@scure/bip32";
+import { mnemonicToSeedSync } from "@scure/bip39";
+import { getPublicKey, nip19 } from "nostr-tools";
+/**
+ * Derive a Nostr keypair from a BIP39 mnemonic using NIP-06 path.
+ * Path: m/44'/1237'/<account>'/0/0
+ * account=0 is the default identity; higher indices produce independent keypairs.
+ */
+export function deriveNostrKeypair(mnemonic, account = 0) {
+    const seed = mnemonicToSeedSync(mnemonic.trim());
+    const child = HDKey.fromMasterSeed(seed).derive(`m/44'/1237'/${account}'/0/0`);
+    if (!child.privateKey)
+        throw new Error("Nostr key derivation failed");
+    const privkey = child.privateKey;
+    const pubkey = getPublicKey(privkey);
+    return { privkey, pubkey, npub: nip19.npubEncode(pubkey), nsec: nip19.nsecEncode(privkey), account };
+}

package/dist/nip89.d.ts

@@ -0,0 +1,12 @@
+export interface AppHandlerEventTemplate {
+    kind: 31990;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+/**
+ * Build a NIP-89 App Handler event template advertising support for cashlet-did (kind 30078).
+ * Nostr clients use this to route users to compatible apps.
+ * Caller must finalizeEvent(template, nostrPrivkey) then publishToRelays.
+ */
+export declare function buildAppHandlerEvent(appName: string, appUrl: string, about?: string): AppHandlerEventTemplate;

package/dist/nip89.js

@@ -0,0 +1,18 @@
+import { BINDING_KIND, PROTOCOL_ID } from "./binding.js";
+const APP_HANDLER_KIND = 31990;
+/**
+ * Build a NIP-89 App Handler event template advertising support for cashlet-did (kind 30078).
+ * Nostr clients use this to route users to compatible apps.
+ * Caller must finalizeEvent(template, nostrPrivkey) then publishToRelays.
+ */
+export function buildAppHandlerEvent(appName, appUrl, about) {
+    return {
+        kind: APP_HANDLER_KIND,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [
+            ["k", String(BINDING_KIND)],
+            ["d", PROTOCOL_ID],
+        ],
+        content: JSON.stringify({ name: appName, url: appUrl, ...(about ? { about } : {}) }),
+    };
+}

package/dist/nip98.d.ts

@@ -0,0 +1,33 @@
+export interface HttpAuthEventTemplate {
+    kind: 27235;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+/**
+ * Build a NIP-98 HTTP Auth event template.
+ * Pass a body Uint8Array to include its SHA-256 hash as a `payload` tag.
+ * Caller must finalizeEvent(template, nostrPrivkey) before sending.
+ * Send as: Authorization: Nostr <base64(JSON.stringify(signedEvent))>
+ */
+export declare function buildHttpAuthEventAsync(url: string, method: string, body?: Uint8Array): Promise<HttpAuthEventTemplate>;
+export interface HttpAuthResult {
+    valid: boolean;
+    pubkey?: string;
+    bchAddress?: string;
+    error?: string;
+}
+/**
+ * Verify a NIP-98 Authorization header on the server side.
+ * Optionally resolves the signer's BCH binding — proving both Nostr + BCH ownership.
+ *
+ * @param authHeader - value of the Authorization header (e.g. "Nostr <base64>")
+ * @param url        - the full request URL (must match event tag exactly)
+ * @param method     - HTTP method (must match event tag exactly)
+ * @param opts.verifyBch - if true, resolve + verify the signer's BCH binding
+ * @param opts.relays    - relay list for BCH binding resolution
+ */
+export declare function verifyHttpAuth(authHeader: string, url: string, method: string, opts?: {
+    verifyBch?: boolean;
+    relays?: string[];
+}): Promise<HttpAuthResult>;

package/dist/nip98.js

@@ -0,0 +1,74 @@
+import { verifyEvent } from "nostr-tools";
+import { resolveIdentity, verifyIdentity } from "./verify.js";
+const HTTP_AUTH_KIND = 27235;
+const HTTP_AUTH_TTL = 60; // seconds — NIP-98 spec
+/**
+ * Build a NIP-98 HTTP Auth event template.
+ * Pass a body Uint8Array to include its SHA-256 hash as a `payload` tag.
+ * Caller must finalizeEvent(template, nostrPrivkey) before sending.
+ * Send as: Authorization: Nostr <base64(JSON.stringify(signedEvent))>
+ */
+export async function buildHttpAuthEventAsync(url, method, body) {
+    const tags = [
+        ["u", url],
+        ["method", method.toUpperCase()],
+    ];
+    if (body) {
+        const hashBuf = await crypto.subtle.digest("SHA-256", body);
+        const hash = Array.from(new Uint8Array(hashBuf)).map(b => b.toString(16).padStart(2, "0")).join("");
+        tags.push(["payload", hash]);
+    }
+    return { kind: HTTP_AUTH_KIND, created_at: Math.floor(Date.now() / 1000), tags, content: "" };
+}
+/**
+ * Verify a NIP-98 Authorization header on the server side.
+ * Optionally resolves the signer's BCH binding — proving both Nostr + BCH ownership.
+ *
+ * @param authHeader - value of the Authorization header (e.g. "Nostr <base64>")
+ * @param url        - the full request URL (must match event tag exactly)
+ * @param method     - HTTP method (must match event tag exactly)
+ * @param opts.verifyBch - if true, resolve + verify the signer's BCH binding
+ * @param opts.relays    - relay list for BCH binding resolution
+ */
+export async function verifyHttpAuth(authHeader, url, method, opts = {}) {
+    if (!authHeader.startsWith("Nostr "))
+        return { valid: false, error: "Missing Nostr auth header" };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let event;
+    try {
+        event = JSON.parse(atob(authHeader.slice(6)));
+    }
+    catch {
+        return { valid: false, error: "Invalid base64 event" };
+    }
+    // 1. Nostr event signature
+    if (!verifyEvent(event))
+        return { valid: false, error: "Invalid Nostr signature" };
+    // 2. Kind
+    if (event.kind !== HTTP_AUTH_KIND)
+        return { valid: false, error: "Wrong event kind" };
+    // 3. TTL
+    if (Math.floor(Date.now() / 1000) - event.created_at > HTTP_AUTH_TTL)
+        return { valid: false, error: "Event expired" };
+    // 4. URL + method tags
+    const uTag = event.tags.find((t) => t[0] === "u");
+    const mTag = event.tags.find((t) => t[0] === "method");
+    if (uTag?.[1] !== url)
+        return { valid: false, error: "URL mismatch" };
+    if (mTag?.[1] !== method.toUpperCase())
+        return { valid: false, error: "Method mismatch" };
+    const result = { valid: true, pubkey: event.pubkey };
+    // 5. Optionally resolve + verify BCH binding
+    if (opts.verifyBch) {
+        const { nip19 } = await import("nostr-tools");
+        const npub = nip19.npubEncode(event.pubkey);
+        const identity = await resolveIdentity(npub, opts.relays);
+        if (!identity)
+            return { valid: false, error: "No BCH binding found for pubkey" };
+        const verify = await verifyIdentity(identity);
+        if (verify.status !== "verified")
+            return { valid: false, error: `BCH binding ${verify.status}` };
+        result.bchAddress = identity.bchAddress;
+    }
+    return result;
+}

package/dist/verify.d.ts

@@ -1,10 +1,15 @@
 import { canonicalize, sha256hex, bchSigningPayload, type CanonicalBinding, type IdentityBinding, type NostrEvent } from "./binding.js";
-export type VerifyStatus = "verified" | "invalid_bch_sig" | "invalid_nostr_sig" | "id_mismatch" | "malformed";
+export type VerifyStatus = "verified" | "invalid_bch_sig" | "invalid_nostr_sig" | "id_mismatch" | "malformed" | "expired";
 export interface VerifyResult {
     status: VerifyStatus;
     bchValid: boolean;
     nostrValid: boolean;
     details: string;
+    /** BCH block timestamp (unix seconds) from the bch-anchor tag, if present.
+     *  Accurate to ~1 block (~10 min): must exceed median of last 11 blocks so
+     *  it cannot be significantly backdated, and can be at most 2 hours ahead of
+     *  network time. Use this instead of the self-reported `createdAt`. */
+    anchoredAt?: number;
 }
 export interface ResolvedIdentity {
     npub: string;
@@ -15,20 +20,29 @@ export interface ResolvedIdentity {
     createdAt: number;
     bchProofTag: string[];
     rawEvent: NostrEvent;
+    /** BCH block timestamp (unix seconds) from the bch-anchor tag, if present.
+     *  More trustworthy than `createdAt` — accurate to ~1 block (~10 min),
+     *  cannot be significantly backdated (median-time-past rule). */
+    anchoredAt?: number;
 }
 /** Resolve a BCH address from an npub via Nostr relays */
 export declare function resolveIdentity(npub: string, relays?: string[]): Promise<ResolvedIdentity | null>;
 /** Verify the BCH + Nostr signatures on a resolved identity */
 export declare function verifyIdentity(resolved: ResolvedIdentity): Promise<VerifyResult>;
-/** Verify a challenge-response proof */
+/** Verify a challenge-response proof.
+ * Payload must be: `cashlet-did/challenge\n<nonce>\n<audience>`
+ * Matches the SIGN_CHALLENGE format used by the Cashlet extension and any conforming client.
+ * @param issuedAt - unix timestamp when the challenge was issued; if provided, rejects proofs older than 5 minutes.
+ */
 export declare function verifyChallengeProof(proof: {
     signature: string;
     payload: string;
     address: string;
-}, nonce: string): boolean;
+}, nonce: string, audience?: string, issuedAt?: number): boolean;
 /**
  * Resolve a BCH address from an npub — the primary pay-by-handle entry point.
- * Returns the verified BCH address string, or null if not found.
+ * Verifies both BCH and Nostr signatures before returning the address.
+ * Returns null if not found or if either signature is invalid.
  *
  * @example
  * const address = await resolveAddress('npub1...')

package/dist/verify.js

@@ -4,38 +4,48 @@ import { canonicalize, sha256hex, bchSigningPayload, BINDING_KIND, PROTOCOL_ID,
 import { queryRelays, DEFAULT_RELAYS } from "./relay.js";
 import { CashletDidError } from "./errors.js";
 import { nip19 } from "nostr-tools";
+/** Encode n as a Bitcoin-style varint (compact size). */
+function varint(n) {
+    if (n < 0xfd)
+        return new Uint8Array([n]);
+    if (n <= 0xffff)
+        return new Uint8Array([0xfd, n & 0xff, (n >> 8) & 0xff]);
+    return new Uint8Array([0xfe, n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >> 24) & 0xff]);
+}
+/**
+ * Compute the double-SHA256 hash used by Bitcoin signed messages.
+ * Format: SHA256d("\x18Bitcoin Signed Message:\n" + varint(len) + message)
+ * Uses proper varint encoding — required for messages longer than 252 bytes.
+ */
 function bitcoinMsgHash(message) {
     const enc = new TextEncoder();
     const msgBytes = enc.encode(message);
     const prefix = enc.encode("\x18Bitcoin Signed Message:\n");
-    const lenByte = new Uint8Array([msgBytes.length]);
-    return hash256(new Uint8Array([...prefix, ...lenByte, ...msgBytes]));
+    return hash256(new Uint8Array([...prefix, ...varint(msgBytes.length), ...msgBytes]));
 }
 function recoverBchAddress(sigHex, msgHash, expectedAddress) {
     const sig = Uint8Array.from(sigHex.match(/.{2}/g).map(b => parseInt(b, 16)));
+    const addrPrefix = (expectedAddress?.split(":")[0] ?? "bitcoincash");
     const tryRecover = (compact, id) => {
         try {
             const pub = secp256k1.recoverPublicKeyCompressed(compact, id, msgHash);
             if (!(pub instanceof Uint8Array))
                 return null;
-            const addrPrefix = (expectedAddress?.split(":")[0] ?? "bitcoincash");
-            for (const type of ["p2pkhWithTokens", "p2pkh"]) {
+            for (const type of ["p2pkh", "p2pkhWithTokens"]) {
                 const r = encodeCashAddress({ prefix: addrPrefix, type, payload: hash160(pub) });
-                if (r?.address)
-                    return r.address;
-                if (typeof r === "string")
-                    return r;
+                const addr = r?.address ?? (typeof r === "string" ? r : null);
+                if (addr && (!expectedAddress || addr === expectedAddress))
+                    return addr;
             }
         }
         catch { /* try next */ }
         return null;
     };
+    // 65-byte: recovery ID is encoded in byte 0 — use it directly, no brute-force
     if (sig.length === 65) {
-        const recoveryId = (sig[0] & 0x03);
-        const addr = tryRecover(sig.slice(1), recoveryId);
-        if (addr)
-            return addr;
+        return tryRecover(sig.slice(1), (sig[0] & 0x03));
     }
+    // 64-byte raw compact: try all recovery IDs
     for (const id of [0, 1, 2, 3]) {
         const addr = tryRecover(sig, id);
         if (addr)
@@ -49,16 +59,19 @@ export async function resolveIdentity(npub, relays = DEFAULT_RELAYS) {
     if (decoded.type !== "npub")
         return null;
     const pubkey = decoded.data;
-    const events = await queryRelays(relays, {
-        kinds: [BINDING_KIND],
-        authors: [pubkey],
-        "#t": [PROTOCOL_ID],
-        limit: 10,
-    });
+    const [events, revocations] = await Promise.all([
+        queryRelays(relays, { kinds: [BINDING_KIND], authors: [pubkey], "#t": [PROTOCOL_ID], limit: 10 }),
+        queryRelays(relays, { kinds: [5], authors: [pubkey], limit: 50 }),
+    ]);
     if (!events.length)
         return null;
-    // Pick latest
-    const event = events.sort((a, b) => b.created_at - a.created_at)[0];
+    const revokedIds = new Set(revocations.flatMap(e => e.tags.filter(t => t[0] === "e").map(t => t[1])));
+    // Pick latest non-revoked event
+    const event = events
+        .filter(e => !revokedIds.has(e.id))
+        .sort((a, b) => b.created_at - a.created_at)[0];
+    if (!event)
+        return null;
     const bchTag = event.tags.find(t => t[0] === "bch");
     const dTag = event.tags.find(t => t[0] === "d");
     const bchProofTag = event.tags.find(t => t[0] === "bch-proof");
@@ -69,6 +82,8 @@ export async function resolveIdentity(npub, relays = DEFAULT_RELAYS) {
         createdAt = JSON.parse(event.content).createdAt ?? createdAt;
     }
     catch { /* use event ts */ }
+    const anchorTag = event.tags.find(t => t[0] === "bch-anchor");
+    const anchoredAt = anchorTag?.[2] ? Number(anchorTag[2]) : undefined;
     return {
         npub,
         pubkey,
@@ -78,6 +93,7 @@ export async function resolveIdentity(npub, relays = DEFAULT_RELAYS) {
         createdAt,
         bchProofTag,
         rawEvent: event,
+        ...(anchoredAt !== undefined ? { anchoredAt } : {}),
     };
 }
 /** Verify the BCH + Nostr signatures on a resolved identity */
@@ -107,24 +123,33 @@ export async function verifyIdentity(resolved) {
         return { status: "malformed", bchValid: false, nostrValid, details: "Unexpected proof payload format" };
     }
     if (bchValid && nostrValid)
-        return { status: "verified", bchValid, nostrValid, details: "Both proofs valid" };
+        return { status: "verified", bchValid, nostrValid, details: "Both proofs valid", ...(resolved.anchoredAt !== undefined ? { anchoredAt: resolved.anchoredAt } : {}) };
     if (!bchValid)
         return { status: "invalid_bch_sig", bchValid, nostrValid, details: "BCH signature invalid" };
     return { status: "invalid_nostr_sig", bchValid, nostrValid, details: "Nostr signature invalid" };
 }
-/** Verify a challenge-response proof */
-export function verifyChallengeProof(proof, nonce) {
+const CHALLENGE_TTL_SECS = 300; // 5 minutes
+/** Verify a challenge-response proof.
+ * Payload must be: `cashlet-did/challenge\n<nonce>\n<audience>`
+ * Matches the SIGN_CHALLENGE format used by the Cashlet extension and any conforming client.
+ * @param issuedAt - unix timestamp when the challenge was issued; if provided, rejects proofs older than 5 minutes.
+ */
+export function verifyChallengeProof(proof, nonce, audience, issuedAt) {
+    if (issuedAt !== undefined && Math.floor(Date.now() / 1000) - issuedAt > CHALLENGE_TTL_SECS)
+        return false;
+    if (!proof.payload.startsWith(`${PROTOCOL_ID}/challenge\n`))
+        return false;
     if (!proof.payload.includes(nonce))
         return false;
-    if (!proof.payload.startsWith(`${PROTOCOL_ID}/challenge`))
+    if (audience !== undefined && !proof.payload.includes(audience))
         return false;
     const msgHash = bitcoinMsgHash(proof.payload);
-    const recovered = recoverBchAddress(proof.signature, msgHash, proof.address);
-    return recovered === proof.address;
+    return recoverBchAddress(proof.signature, msgHash, proof.address) === proof.address;
 }
 /**
  * Resolve a BCH address from an npub — the primary pay-by-handle entry point.
- * Returns the verified BCH address string, or null if not found.
+ * Verifies both BCH and Nostr signatures before returning the address.
+ * Returns null if not found or if either signature is invalid.
  *
  * @example
  * const address = await resolveAddress('npub1...')
@@ -132,7 +157,10 @@ export function verifyChallengeProof(proof, nonce) {
  */
 export async function resolveAddress(npub, relays = DEFAULT_RELAYS) {
     const identity = await resolveIdentity(npub, relays);
-    return identity?.bchAddress ?? null;
+    if (!identity)
+        return null;
+    const result = await verifyIdentity(identity);
+    return result.status === "verified" ? identity.bchAddress : null;
 }
 /** Returns full binding history for an npub, newest first, with cryptographic supersedes validation */
 export async function resolveIdentityChain(npub, relays = DEFAULT_RELAYS) {
@@ -158,28 +186,21 @@ export async function resolveIdentityChain(npub, relays = DEFAULT_RELAYS) {
             createdAt = JSON.parse(event.content).createdAt ?? createdAt;
         }
         catch { /* use event ts */ }
-        // Validate supersedes tag cryptographically
+        // Validate supersedes tag: the referenced event must exist and its d-tag must match claimedId
         const supersedesTag = event.tags.find(t => t[0] === "supersedes");
         if (supersedesTag) {
             const claimedId = supersedesTag[1];
-            // Fetch the referenced event and verify its bindingId matches
-            const [prev] = await queryRelays(relays, { ids: [claimedId], limit: 1 });
+            const [prev] = await queryRelays(relays, { "#d": [claimedId], kinds: [BINDING_KIND], limit: 1 });
             if (prev) {
-                try {
-                    const prevContent = JSON.parse(prev.content);
-                    const actualId = await sha256hex(canonicalize(prevContent));
-                    if (actualId !== claimedId) {
-                        throw new CashletDidError("CHAIN_BROKEN", `supersedes tag ${claimedId} does not match referenced event content hash`);
-                    }
-                }
-                catch (e) {
-                    if (e instanceof CashletDidError)
-                        throw e;
-                    // content not canonical JSON — skip validation but keep event
+                const prevDTag = prev.tags.find(t => t[0] === "d");
+                if (prevDTag?.[1] !== claimedId) {
+                    throw new CashletDidError("CHAIN_BROKEN", `supersedes tag ${claimedId} does not match referenced event d-tag`);
                 }
             }
         }
-        results.push({ npub, pubkey, bchAddress: bchTag[1], network: bchTag[2] ?? "mainnet", bindingId: dTag[1], createdAt, bchProofTag, rawEvent: event });
+        const anchorTag = event.tags.find(t => t[0] === "bch-anchor");
+        const anchoredAt = anchorTag?.[2] ? Number(anchorTag[2]) : undefined;
+        results.push({ npub, pubkey, bchAddress: bchTag[1], network: bchTag[2] ?? "mainnet", bindingId: dTag[1], createdAt, bchProofTag, rawEvent: event, ...(anchoredAt !== undefined ? { anchoredAt } : {}) });
     }
     return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "did-beta-bch",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Decentralised identity protocol binding BCH addresses to Nostr public keys",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,18 +11,37 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "PROTOCOL.md"
+  ],
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
+    "test": "node --test test/cashlet-did.test.mjs",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["bch", "bitcoin-cash", "nostr", "did", "decentralised-identity", "cashaddr", "nip-06", "nip-07"],
+  "keywords": [
+    "bch",
+    "bitcoin-cash",
+    "nostr",
+    "did",
+    "decentralised-identity",
+    "cashaddr",
+    "nip-06",
+    "nip-07"
+  ],
   "author": "",
   "license": "MIT",
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@bitauth/libauth": "^3.1.0-next.8",
+    "@scure/bip32": "^2.4.0",
+    "@scure/bip39": "^2.4.0",
     "nostr-tools": "^2.0.0"
   },
   "devDependencies": {