@orangecheck/sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,5 +1,9 @@
 # `@orangecheck/sdk`
 
+> **Full reference:** [docs.ochk.io/sdk/sdk](https://docs.ochk.io/sdk/sdk) — auto-generated from the TypeScript source on every release.
+> Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.
+
+
 **Proof of Bitcoin stake for the open web.**
 
 A sybil-resistance primitive for forums, Nostr relays, airdrop gates, DAO votes, and any open platform that needs to filter bots without KYC. Bitcoin UTXOs are the only credible signal of commitment: honest users pay nothing, attackers pay real opportunity cost.

package/dist/index.d.mts

@@ -33,6 +33,50 @@ interface CheckResult {
 }
 declare function check(params: CheckParams): Promise<CheckResult>;
 
+interface BindingInput {
+    principal: string;
+    btc: string;
+    nostr: string;
+    nonce: string;
+    issued_at: string;
+    extensions?: Record<string, string>;
+}
+interface BindingNostrEvent {
+    id: string;
+    pubkey: string;
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+interface BindingEnvelope {
+    binding_id?: string;
+    v?: number;
+    principal?: string;
+    btc?: string;
+    nostr?: string;
+    message: string;
+    btc_signature?: string;
+    btc_scheme?: 'bip322' | 'legacy';
+    nostr_event?: BindingNostrEvent;
+}
+type BindingStatus = 'binding_ok' | 'malformed' | 'bad_header' | 'bad_ack' | 'bad_principal' | 'ext_unsorted' | 'id_mismatch' | 'field_mismatch' | 'expired' | 'network' | 'bad_scheme' | 'btc_sig_invalid' | 'nostr_id_invalid' | 'nostr_sig_invalid' | 'nostr_key_mismatch' | 'message_mismatch';
+type BindingVerifyResult = {
+    valid: true;
+    status: 'binding_ok';
+    binding_id: string;
+    principal: string;
+    btc: string;
+    nostr: string;
+} | {
+    valid: false;
+    status: Exclude<BindingStatus, 'binding_ok'>;
+};
+declare function buildBindingMessage(input: BindingInput): string;
+declare function bindingId(message: string): string;
+declare function verifyBinding(envelope: BindingEnvelope): BindingVerifyResult;
+
 declare function isNip07Available(): boolean;
 declare function getNostrPublicKey(): Promise<string | null>;
 declare function signNostrEvent(event: Omit<NostrEvent, 'id' | 'sig'>): Promise<NostrEvent | null>;
@@ -50,4 +94,4 @@ interface StatusMeta {
 }
 declare const STATUS_META: Record<StatusCode, StatusMeta>;
 
-export { type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, VerifyOptions, check, getNip07Info, getNostrPublicKey, isNip07Available, signNostrEvent };
+export { type BindingEnvelope, type BindingInput, type BindingNostrEvent, type BindingStatus, type BindingVerifyResult, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, VerifyOptions, bindingId, buildBindingMessage, check, getNip07Info, getNostrPublicKey, isNip07Available, signNostrEvent, verifyBinding };

package/dist/index.d.ts

@@ -33,6 +33,50 @@ interface CheckResult {
 }
 declare function check(params: CheckParams): Promise<CheckResult>;
 
+interface BindingInput {
+    principal: string;
+    btc: string;
+    nostr: string;
+    nonce: string;
+    issued_at: string;
+    extensions?: Record<string, string>;
+}
+interface BindingNostrEvent {
+    id: string;
+    pubkey: string;
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+interface BindingEnvelope {
+    binding_id?: string;
+    v?: number;
+    principal?: string;
+    btc?: string;
+    nostr?: string;
+    message: string;
+    btc_signature?: string;
+    btc_scheme?: 'bip322' | 'legacy';
+    nostr_event?: BindingNostrEvent;
+}
+type BindingStatus = 'binding_ok' | 'malformed' | 'bad_header' | 'bad_ack' | 'bad_principal' | 'ext_unsorted' | 'id_mismatch' | 'field_mismatch' | 'expired' | 'network' | 'bad_scheme' | 'btc_sig_invalid' | 'nostr_id_invalid' | 'nostr_sig_invalid' | 'nostr_key_mismatch' | 'message_mismatch';
+type BindingVerifyResult = {
+    valid: true;
+    status: 'binding_ok';
+    binding_id: string;
+    principal: string;
+    btc: string;
+    nostr: string;
+} | {
+    valid: false;
+    status: Exclude<BindingStatus, 'binding_ok'>;
+};
+declare function buildBindingMessage(input: BindingInput): string;
+declare function bindingId(message: string): string;
+declare function verifyBinding(envelope: BindingEnvelope): BindingVerifyResult;
+
 declare function isNip07Available(): boolean;
 declare function getNostrPublicKey(): Promise<string | null>;
 declare function signNostrEvent(event: Omit<NostrEvent, 'id' | 'sig'>): Promise<NostrEvent | null>;
@@ -50,4 +94,4 @@ interface StatusMeta {
 }
 declare const STATUS_META: Record<StatusCode, StatusMeta>;
 
-export { type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, VerifyOptions, check, getNip07Info, getNostrPublicKey, isNip07Available, signNostrEvent };
+export { type BindingEnvelope, type BindingInput, type BindingNostrEvent, type BindingStatus, type BindingVerifyResult, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, VerifyOptions, bindingId, buildBindingMessage, check, getNip07Info, getNostrPublicKey, isNip07Available, signNostrEvent, verifyBinding };

package/dist/index.js

@@ -1177,6 +1177,189 @@ async function check(params) {
     ...reasons.length ? { reasons } : {}
   };
 }
+var HEADER = "orangecheck-binding";
+var ACK = "I attest the keys named in this message are one principal.";
+var BINDING_KIND = 30079;
+function toHex(bytes) {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function fromHex(hex) {
+  const clean = hex.toLowerCase();
+  if (clean.length % 2 !== 0 || /[^0-9a-f]/.test(clean)) {
+    throw new Error("invalid hex");
+  }
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function assertPrintableAscii(field, value) {
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i);
+    if (c < 32 || c > 126) {
+      throw new Error(
+        `binding ${field} contains an unsafe character (0x${c.toString(16)}) \u2014 line-smuggling defense (SPEC-BINDING \xA73.5)`
+      );
+    }
+  }
+}
+function buildBindingMessage(input) {
+  assertPrintableAscii("principal", input.principal);
+  assertPrintableAscii("btc", input.btc);
+  assertPrintableAscii("nostr", input.nostr);
+  assertPrintableAscii("nonce", input.nonce);
+  assertPrintableAscii("issued_at", input.issued_at);
+  const core = [
+    HEADER,
+    "v: 1",
+    `principal: ${input.principal}`,
+    `btc: ${input.btc}`,
+    `nostr: ${input.nostr}`,
+    `nonce: ${input.nonce}`,
+    `issued_at: ${input.issued_at}`,
+    `ack: ${ACK}`
+  ];
+  const ext = [];
+  if (input.extensions) {
+    for (const key of Object.keys(input.extensions).sort()) {
+      const value = input.extensions[key];
+      if (value == null) continue;
+      if (!/^[a-z]+$/.test(key)) {
+        throw new Error(`binding extension key "${key}" must be lowercase ASCII`);
+      }
+      assertPrintableAscii(`extension ${key}`, value);
+      ext.push(`${key}: ${value}`);
+    }
+  }
+  return [...core, ...ext].join("\n") + "\n";
+}
+function bindingId(message) {
+  return toHex(sha2_js.sha256(new TextEncoder().encode(message)));
+}
+function linePrefix(line, prefix) {
+  if (typeof line !== "string" || !line.startsWith(prefix)) return null;
+  return line.slice(prefix.length);
+}
+function nostrEventId(ev) {
+  const serialized = JSON.stringify([
+    0,
+    ev.pubkey,
+    ev.created_at,
+    ev.kind,
+    ev.tags,
+    ev.content
+  ]);
+  return toHex(sha2_js.sha256(new TextEncoder().encode(serialized)));
+}
+function npubToXOnlyHex(npub) {
+  const decoded = base.bech32.decode(npub, 90);
+  if (decoded.prefix !== "npub") throw new Error("not an npub");
+  const bytes = Uint8Array.from(base.bech32.fromWords(decoded.words));
+  if (bytes.length !== 32) throw new Error("npub payload is not 32 bytes");
+  return toHex(bytes);
+}
+function verifyBinding(envelope) {
+  const fail = (status) => ({
+    valid: false,
+    status
+  });
+  try {
+    const msg = envelope.message;
+    if (typeof msg !== "string" || msg.length === 0) return fail("malformed");
+    const lines = msg.split("\n");
+    if ((lines[0] ?? "") !== HEADER) return fail("bad_header");
+    if (lines.length < 9 || lines[lines.length - 1] !== "") return fail("malformed");
+    const body = lines.slice(0, -1);
+    if (body.length < 8) return fail("malformed");
+    if (body[1] !== "v: 1") return fail("malformed");
+    if (body[7] !== `ack: ${ACK}`) return fail("bad_ack");
+    const principal = linePrefix(body[2], "principal: ");
+    const btc = linePrefix(body[3], "btc: ");
+    const nostr = linePrefix(body[4], "nostr: ");
+    const nonce = linePrefix(body[5], "nonce: ");
+    const issuedAt = linePrefix(body[6], "issued_at: ");
+    if (principal == null || btc == null || nostr == null || nonce == null || issuedAt == null) {
+      return fail("malformed");
+    }
+    for (const value of [principal, btc, nostr, nonce, issuedAt]) {
+      for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (c < 32 || c > 126) return fail("malformed");
+      }
+    }
+    if (!/^did:oc:[0-9a-f]{32}$/.test(principal)) return fail("bad_principal");
+    if (!/^[0-9a-f]{32}$/.test(nonce)) return fail("malformed");
+    const ext = {};
+    let prevKey = "";
+    for (const line of body.slice(8)) {
+      const idx = line.indexOf(": ");
+      if (idx <= 0) return fail("malformed");
+      const key = line.slice(0, idx);
+      const value = line.slice(idx + 2);
+      if (!/^[a-z]+$/.test(key)) return fail("malformed");
+      if (key <= prevKey) return fail("ext_unsorted");
+      prevKey = key;
+      ext[key] = value;
+    }
+    const bid = bindingId(msg);
+    if (envelope.binding_id && envelope.binding_id.toLowerCase() !== bid) {
+      return fail("id_mismatch");
+    }
+    if (envelope.btc && envelope.btc !== btc) return fail("field_mismatch");
+    if (envelope.nostr && envelope.nostr !== nostr) return fail("field_mismatch");
+    if (envelope.principal && envelope.principal !== principal) return fail("field_mismatch");
+    if (ext.expires) {
+      const t = Date.parse(ext.expires);
+      if (!Number.isNaN(t) && Date.now() > t) return fail("expired");
+    }
+    if (typeof envelope.btc_signature !== "string" || !envelope.btc_signature) {
+      return fail("btc_sig_invalid");
+    }
+    const scheme = envelope.btc_scheme ?? "bip322";
+    let btcOk = false;
+    try {
+      if (scheme === "bip322") {
+        btcOk = bip322Js.Verifier.verifySignature(btc, msg, envelope.btc_signature);
+      } else if (scheme === "legacy") {
+        btcOk = bitcoinMessage__namespace.verify(msg, btc, envelope.btc_signature);
+      } else {
+        return fail("bad_scheme");
+      }
+    } catch {
+      btcOk = false;
+    }
+    if (!btcOk) return fail("btc_sig_invalid");
+    const ev = envelope.nostr_event;
+    if (!ev || ev.kind !== BINDING_KIND || typeof ev.id !== "string") return fail("malformed");
+    if (nostrEventId(ev) !== ev.id.toLowerCase()) return fail("nostr_id_invalid");
+    let nostrSigOk = false;
+    try {
+      nostrSigOk = secp256k1_js.schnorr.verify(fromHex(ev.sig), fromHex(ev.id), fromHex(ev.pubkey));
+    } catch {
+      nostrSigOk = false;
+    }
+    if (!nostrSigOk) return fail("nostr_sig_invalid");
+    let nostrXOnly;
+    try {
+      nostrXOnly = npubToXOnlyHex(nostr);
+    } catch {
+      return fail("nostr_key_mismatch");
+    }
+    if (nostrXOnly !== ev.pubkey.toLowerCase()) return fail("nostr_key_mismatch");
+    let content;
+    try {
+      content = JSON.parse(ev.content);
+    } catch {
+      return fail("message_mismatch");
+    }
+    if (content.message !== msg) return fail("message_mismatch");
+    if (content.btc_signature !== envelope.btc_signature) return fail("message_mismatch");
+    return { valid: true, status: "binding_ok", binding_id: bid, principal, btc, nostr };
+  } catch {
+    return fail("malformed");
+  }
+}
 var AUTH_HEADER = "orangecheck-auth";
 var AUTH_ACK = "I authorize this session under the OrangeCheck auth challenge.";
 function randomNonce() {
@@ -1632,12 +1815,12 @@ function getGistCreationUrl() {
 }
 var log7 = createLogger("identity-verification/nostr");
 var HEX_64_RE = /^[0-9a-f]{64}$/;
-function toHex(bytes) {
+function toHex2(bytes) {
   let out = "";
   for (const b of bytes) out += b.toString(16).padStart(2, "0");
   return out;
 }
-function fromHex(hex) {
+function fromHex2(hex) {
   if (hex.length % 2 !== 0) throw new Error("odd-length hex");
   const out = new Uint8Array(hex.length / 2);
   for (let i = 0; i < out.length; i++) {
@@ -1661,7 +1844,7 @@ function npubToHex(npub) {
   if (bytes.length !== 32) {
     throw new Error(`invalid npub payload length: ${bytes.length}`);
   }
-  return toHex(Uint8Array.from(bytes));
+  return toHex2(Uint8Array.from(bytes));
 }
 async function queryNostrEvents(options) {
   const { authors, kinds, search, relays = DEFAULT_RELAYS, limit = 100 } = options;
@@ -1744,7 +1927,7 @@ async function verifyNostrEventSignature(event) {
       event.tags ?? [],
       event.content ?? ""
     ]);
-    const computedId = toHex(sha2_js.sha256(new TextEncoder().encode(preimage)));
+    const computedId = toHex2(sha2_js.sha256(new TextEncoder().encode(preimage)));
     if (computedId !== event.id.toLowerCase()) {
       log7.warn(
         { eventId: event.id, computedId },
@@ -1752,7 +1935,7 @@ async function verifyNostrEventSignature(event) {
       );
       return false;
     }
-    return secp256k1_js.schnorr.verify(fromHex(event.sig), fromHex(event.id), fromHex(event.pubkey));
+    return secp256k1_js.schnorr.verify(fromHex2(event.sig), fromHex2(event.id), fromHex2(event.pubkey));
   } catch (err) {
     log7.warn({ err }, "schnorr verify threw");
     return false;
@@ -2114,6 +2297,8 @@ var STATUS_META = {
 
 exports.DEFAULT_RELAYS = DEFAULT_RELAYS;
 exports.STATUS_META = STATUS_META;
+exports.bindingId = bindingId;
+exports.buildBindingMessage = buildBindingMessage;
 exports.buildCanonicalMessage = buildCanonicalMessage;
 exports.check = check;
 exports.computeAllScores = computeAllScores;
@@ -2165,6 +2350,7 @@ exports.supportsAutomaticVerification = supportsAutomaticVerification;
 exports.verify = verify2;
 exports.verifyAllIdentities = verifyAllIdentities;
 exports.verifyAttestationById = verifyAttestationById;
+exports.verifyBinding = verifyBinding;
 exports.verifyChallenge = verifyChallenge;
 exports.verifyDnsIdentity = verifyDnsIdentity;
 exports.verifyGitHubIdentity = verifyGitHubIdentity;