@orangecheck/sdk 1.12.0 → 1.13.0

package/README.md

@@ -148,9 +148,12 @@ Now the gate doesn't have to trust the client — the address it sees has been c
 ## Bonds: one coin backing one account
 
 An attestation publishes an address. A bond keeps it private. The holder signs
-once to pledge one unspent coin to one subject, and whoever relies on the bond
+once to back one subject with one unspent coin, and whoever relies on the bond
 sees only floors (at least N sats, at least D days) and a nullifier that is the
-same for that coin at that site and unrelated anywhere else. Spec:
+same for that coin at that site and unrelated anywhere else. The registry keys
+the nullifier with its own secret, so nobody can find the coin by hashing
+outpoints. Not to be confused with an attestation's `bond:` line (an amount at
+a public address) or `@orangecheck/pledge-core`'s `verifyBond`. Spec:
 [`BOND.md`](https://github.com/orangecheck/oc-attest-protocol/blob/main/BOND.md).
 
 ```ts
@@ -164,7 +167,9 @@ const { message } = issueBondMessage({ address, outpoint: `${txid}:${vout}`, sub
 const r = await verifyBond({ message, signature, subject: didOc, source: esploraSource() });
 if (r.ok) {
     const age = r.bond.tip.height - r.bond.confirmed_height + 1;
-    const claim = { ...bondFloors(r.bond.sats, age), nullifier: bondNullifier(audience, r.bond.outpoint) };
+    // NULLIFIER_KEY: your registry's secret, 32+ bytes, kept for good.
+    const nullifier = bondNullifier(NULLIFIER_KEY, audience, r.bond.outpoint);
+    const claim = { ...bondFloors(r.bond.sats, age), nullifier };
 }
 ```
 
@@ -281,7 +286,7 @@ verifyChallenge(options): Promise<VerifyChallengeResult>
 issueBondMessage(options): { message, nonce, expiresAt }
 verifyBond(options): Promise<BondResult>
 checkBondCoin(options): Promise<...>
-bondNullifier(audience, outpoint): string
+bondNullifier(key, audience, outpoint): string
 bondFloors(sats, ageBlocks): { sats_floor, days_floor }
 
 // Building blocks.

package/dist/index.d.mts

@@ -39,6 +39,7 @@ declare function nostrIdentifierForms(identifier: string): string[];
 declare const BOND_SATS_FLOORS: readonly [1000, 10000, 100000, 1000000, 10000000];
 declare const BOND_DAYS_FLOORS: readonly [7, 30, 90, 365];
 declare const BOND_MIN_CONFIRMATIONS = 6;
+declare const BOND_MAX_WINDOW_SECONDS = 3600;
 interface BondFields {
     address: string;
     outpoint: string;
@@ -47,7 +48,7 @@ interface BondFields {
     issued_at: string;
     expires_at: string;
 }
-type BondReason = 'bond_malformed' | 'bond_subject_mismatch' | 'bond_expired' | 'bond_not_yet_valid' | 'sig_invalid' | 'coin_not_found' | 'coin_address_mismatch' | 'coin_unconfirmed' | 'coin_too_recent' | 'coin_spent' | 'chain_unavailable';
+type BondReason = 'bond_malformed' | 'bond_subject_mismatch' | 'bond_expired' | 'bond_not_yet_valid' | 'bond_window_too_long' | 'sig_invalid' | 'coin_not_found' | 'coin_address_mismatch' | 'coin_unconfirmed' | 'coin_too_recent' | 'coin_spent' | 'chain_unavailable';
 interface BondCoin {
     sats: number;
     scriptPubKey: string;
@@ -92,7 +93,7 @@ declare function issueBondMessage(opts: {
 };
 declare function parseBondMessage(message: string): BondFields | null;
 declare function bondId(message: string): string;
-declare function bondNullifier(audience: string, outpoint: string): string;
+declare function bondNullifier(key: Uint8Array, audience: string, outpoint: string): string;
 declare function bondFloors(sats: number, ageBlocks: number): {
     sats_floor: number;
     days_floor: number;
@@ -103,6 +104,7 @@ declare function verifyBondSignature(opts: {
     subject?: string;
     now?: Date;
     skewSeconds?: number;
+    maxWindowSeconds?: number;
 }): {
     ok: true;
     fields: BondFields;
@@ -131,6 +133,7 @@ declare function verifyBond(opts: {
     source: BondChainSource;
     subject?: string;
     now?: Date;
+    maxWindowSeconds?: number;
     minConfirmations?: number;
 }): Promise<BondResult>;
 declare function esploraSource(base?: string, opts?: {
@@ -155,4 +158,4 @@ interface StatusMeta {
 }
 declare const STATUS_META: Record<StatusCode, StatusMeta>;
 
-export { BOND_DAYS_FLOORS, BOND_MIN_CONFIRMATIONS, BOND_SATS_FLOORS, type BondChainSource, type BondCoin, type BondFields, type BondReason, type BondResult, type ChainTip, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, type VerifiedBond, VerifyOptions, bondFloors, bondId, bondNullifier, buildBondMessage, check, checkBondCoin, esploraSource, getNip07Info, getNostrPublicKey, isNip07Available, issueBondMessage, nostrIdentifierForms, nostrPubkeyToHex, parseBondMessage, signNostrEvent, verifyBond, verifyBondSignature };
+export { BOND_DAYS_FLOORS, BOND_MAX_WINDOW_SECONDS, BOND_MIN_CONFIRMATIONS, BOND_SATS_FLOORS, type BondChainSource, type BondCoin, type BondFields, type BondReason, type BondResult, type ChainTip, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, type VerifiedBond, VerifyOptions, bondFloors, bondId, bondNullifier, buildBondMessage, check, checkBondCoin, esploraSource, getNip07Info, getNostrPublicKey, isNip07Available, issueBondMessage, nostrIdentifierForms, nostrPubkeyToHex, parseBondMessage, signNostrEvent, verifyBond, verifyBondSignature };

package/dist/index.d.ts

@@ -39,6 +39,7 @@ declare function nostrIdentifierForms(identifier: string): string[];
 declare const BOND_SATS_FLOORS: readonly [1000, 10000, 100000, 1000000, 10000000];
 declare const BOND_DAYS_FLOORS: readonly [7, 30, 90, 365];
 declare const BOND_MIN_CONFIRMATIONS = 6;
+declare const BOND_MAX_WINDOW_SECONDS = 3600;
 interface BondFields {
     address: string;
     outpoint: string;
@@ -47,7 +48,7 @@ interface BondFields {
     issued_at: string;
     expires_at: string;
 }
-type BondReason = 'bond_malformed' | 'bond_subject_mismatch' | 'bond_expired' | 'bond_not_yet_valid' | 'sig_invalid' | 'coin_not_found' | 'coin_address_mismatch' | 'coin_unconfirmed' | 'coin_too_recent' | 'coin_spent' | 'chain_unavailable';
+type BondReason = 'bond_malformed' | 'bond_subject_mismatch' | 'bond_expired' | 'bond_not_yet_valid' | 'bond_window_too_long' | 'sig_invalid' | 'coin_not_found' | 'coin_address_mismatch' | 'coin_unconfirmed' | 'coin_too_recent' | 'coin_spent' | 'chain_unavailable';
 interface BondCoin {
     sats: number;
     scriptPubKey: string;
@@ -92,7 +93,7 @@ declare function issueBondMessage(opts: {
 };
 declare function parseBondMessage(message: string): BondFields | null;
 declare function bondId(message: string): string;
-declare function bondNullifier(audience: string, outpoint: string): string;
+declare function bondNullifier(key: Uint8Array, audience: string, outpoint: string): string;
 declare function bondFloors(sats: number, ageBlocks: number): {
     sats_floor: number;
     days_floor: number;
@@ -103,6 +104,7 @@ declare function verifyBondSignature(opts: {
     subject?: string;
     now?: Date;
     skewSeconds?: number;
+    maxWindowSeconds?: number;
 }): {
     ok: true;
     fields: BondFields;
@@ -131,6 +133,7 @@ declare function verifyBond(opts: {
     source: BondChainSource;
     subject?: string;
     now?: Date;
+    maxWindowSeconds?: number;
     minConfirmations?: number;
 }): Promise<BondResult>;
 declare function esploraSource(base?: string, opts?: {
@@ -155,4 +158,4 @@ interface StatusMeta {
 }
 declare const STATUS_META: Record<StatusCode, StatusMeta>;
 
-export { BOND_DAYS_FLOORS, BOND_MIN_CONFIRMATIONS, BOND_SATS_FLOORS, type BondChainSource, type BondCoin, type BondFields, type BondReason, type BondResult, type ChainTip, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, type VerifiedBond, VerifyOptions, bondFloors, bondId, bondNullifier, buildBondMessage, check, checkBondCoin, esploraSource, getNip07Info, getNostrPublicKey, isNip07Available, issueBondMessage, nostrIdentifierForms, nostrPubkeyToHex, parseBondMessage, signNostrEvent, verifyBond, verifyBondSignature };
+export { BOND_DAYS_FLOORS, BOND_MAX_WINDOW_SECONDS, BOND_MIN_CONFIRMATIONS, BOND_SATS_FLOORS, type BondChainSource, type BondCoin, type BondFields, type BondReason, type BondResult, type ChainTip, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, type VerifiedBond, VerifyOptions, bondFloors, bondId, bondNullifier, buildBondMessage, check, checkBondCoin, esploraSource, getNip07Info, getNostrPublicKey, isNip07Available, issueBondMessage, nostrIdentifierForms, nostrPubkeyToHex, parseBondMessage, signNostrEvent, verifyBond, verifyBondSignature };

package/dist/index.js

@@ -3,6 +3,7 @@
 var base = require('@scure/base');
 var buffer = require('buffer');
 var bip322 = require('@orangecheck/bip322');
+var hmac_js = require('@noble/hashes/hmac.js');
 var sha2_js = require('@noble/hashes/sha2.js');
 var utils_js = require('@noble/hashes/utils.js');
 var secp256k1_js = require('@noble/curves/secp256k1.js');
@@ -1451,11 +1452,12 @@ async function verifyChallenge(opts) {
   };
 }
 var HEADER = "orangecheck-bond";
-var ACK = "I pledge this coin to back this subject. It stays in my wallet.";
+var ACK = "I back this subject with this coin. It stays in my wallet.";
 var FIELDS = ["address", "outpoint", "subject", "nonce", "issued_at", "expires_at"];
 var BOND_SATS_FLOORS = [1e3, 1e4, 1e5, 1e6, 1e7];
 var BOND_DAYS_FLOORS = [7, 30, 90, 365];
 var BOND_MIN_CONFIRMATIONS = 6;
+var BOND_MAX_WINDOW_SECONDS = 3600;
 var OUTPOINT_RE = /^[0-9a-f]{64}:(0|[1-9][0-9]{0,9})$/;
 var NONCE_RE = /^[0-9a-f]{32}$/;
 var TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
@@ -1463,13 +1465,17 @@ var SUBJECT_RE = /^[\x21-\x7e]{1,256}$/;
 function iso2(d) {
   return d.toISOString().replace(/\.\d{3}Z$/, "Z");
 }
+function instant(s) {
+  const t = Date.parse(s);
+  return TIME_RE.test(s) && Number.isFinite(t) && iso2(new Date(t)) === s;
+}
 function randomNonce2() {
   const b = new Uint8Array(16);
   globalThis.crypto.getRandomValues(b);
   return utils_js.bytesToHex(b);
 }
 function wellFormed(f) {
-  return bip322.decodeAddress(f.address) !== null && OUTPOINT_RE.test(f.outpoint) && SUBJECT_RE.test(f.subject) && NONCE_RE.test(f.nonce) && TIME_RE.test(f.issued_at) && TIME_RE.test(f.expires_at) && Date.parse(f.expires_at) > Date.parse(f.issued_at);
+  return bip322.decodeAddress(f.address) !== null && OUTPOINT_RE.test(f.outpoint) && SUBJECT_RE.test(f.subject) && NONCE_RE.test(f.nonce) && instant(f.issued_at) && instant(f.expires_at) && Date.parse(f.expires_at) > Date.parse(f.issued_at);
 }
 function buildBondMessage(fields) {
   if (!wellFormed(fields)) throw new Error("bond fields are malformed");
@@ -1507,10 +1513,12 @@ function parseBondMessage(message) {
 function bondId(message) {
   return utils_js.bytesToHex(sha2_js.sha256(utils_js.utf8ToBytes(message)));
 }
-function bondNullifier(audience, outpoint) {
-  return utils_js.bytesToHex(sha2_js.sha256(utils_js.utf8ToBytes(`orangecheck-bond-nullifier
+function bondNullifier(key, audience, outpoint) {
+  if (key.length < 32) throw new Error("bond nullifier key must be at least 32 bytes");
+  const message = utils_js.utf8ToBytes(`orangecheck-bond-nullifier
 ${audience}
-${outpoint}`)));
+${outpoint}`);
+  return utils_js.bytesToHex(hmac_js.hmac(sha2_js.sha256, key, message));
 }
 function bondFloors(sats, ageBlocks) {
   const days = Math.floor(ageBlocks / 144);
@@ -1523,6 +1531,10 @@ function verifyBondSignature(opts) {
   if (opts.subject !== void 0 && fields.subject !== opts.subject) {
     return { ok: false, reason: "bond_subject_mismatch" };
   }
+  const window2 = Date.parse(fields.expires_at) - Date.parse(fields.issued_at);
+  if (window2 > (opts.maxWindowSeconds ?? BOND_MAX_WINDOW_SECONDS) * 1e3) {
+    return { ok: false, reason: "bond_window_too_long" };
+  }
   const now = (opts.now ?? /* @__PURE__ */ new Date()).getTime();
   const skew = (opts.skewSeconds ?? 60) * 1e3;
   if (Date.parse(fields.issued_at) - skew > now) return { ok: false, reason: "bond_not_yet_valid" };
@@ -1578,22 +1590,28 @@ async function verifyBond(opts) {
   };
 }
 function esploraSource(base = "https://mempool.space/api", opts = {}) {
-  const get = async (path) => {
+  const get = async (path, missingOk = false) => {
     const r = await (opts.fetch ?? fetch)(`${base}${path}`, {
       signal: AbortSignal.timeout(opts.timeoutMs ?? 5e3)
     });
-    if (!r.ok && r.status !== 404) throw new Error(`esplora ${path}: HTTP ${r.status}`);
+    if (!r.ok && !(missingOk && r.status === 404)) {
+      throw new Error(`esplora ${path}: HTTP ${r.status}`);
+    }
     return r;
   };
   return {
     async tip() {
       const [h, hash] = await Promise.all([get("/blocks/tip/height"), get("/blocks/tip/hash")]);
-      return { height: Number(await h.text()), hash: (await hash.text()).trim() };
+      const tip = { height: Number(await h.text()), hash: (await hash.text()).trim() };
+      if (!Number.isSafeInteger(tip.height) || !/^[0-9a-f]{64}$/.test(tip.hash)) {
+        throw new Error("esplora tip: malformed");
+      }
+      return tip;
     },
     async coin(outpoint) {
       const [txid, voutStr] = outpoint.split(":");
       const vout = Number(voutStr);
-      const txr = await get(`/tx/${txid}`);
+      const txr = await get(`/tx/${txid}`, true);
       if (txr.status === 404) return null;
       const tx = await txr.json();
       const out = tx.vout[vout];
@@ -2398,6 +2416,7 @@ var STATUS_META = {
 };
 
 exports.BOND_DAYS_FLOORS = BOND_DAYS_FLOORS;
+exports.BOND_MAX_WINDOW_SECONDS = BOND_MAX_WINDOW_SECONDS;
 exports.BOND_MIN_CONFIRMATIONS = BOND_MIN_CONFIRMATIONS;
 exports.BOND_SATS_FLOORS = BOND_SATS_FLOORS;
 exports.DEFAULT_RELAYS = DEFAULT_RELAYS;