@orangecheck/sdk 1.0.0 → 1.2.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,73 @@ interface CheckResult {
 }
 declare function check(params: CheckParams): Promise<CheckResult>;
 
+declare const BINDING_KIND = 30079;
+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;
+    message_b64url?: 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 xOnlyHexToNpub(hex: string): string;
+interface BindingEventTemplate {
+    kind: typeof BINDING_KIND;
+    pubkey: string;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+declare function buildBindingEventTemplate(params: {
+    message: string;
+    btcSignature: string;
+    nostrPubkeyHex: string;
+    btc: string;
+    createdAt?: number;
+}): BindingEventTemplate;
+declare function assembleBindingEnvelope(params: {
+    message: string;
+    btcSignature: string;
+    btcScheme?: 'bip322' | 'legacy';
+    nostrEvent: BindingNostrEvent;
+}): BindingEnvelope;
+
 declare function isNip07Available(): boolean;
 declare function getNostrPublicKey(): Promise<string | null>;
 declare function signNostrEvent(event: Omit<NostrEvent, 'id' | 'sig'>): Promise<NostrEvent | null>;
@@ -50,4 +117,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 BindingEventTemplate, type BindingInput, type BindingNostrEvent, type BindingStatus, type BindingVerifyResult, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, VerifyOptions, assembleBindingEnvelope, bindingId, buildBindingEventTemplate, buildBindingMessage, check, getNip07Info, getNostrPublicKey, isNip07Available, signNostrEvent, verifyBinding, xOnlyHexToNpub };

package/dist/index.d.ts

@@ -33,6 +33,73 @@ interface CheckResult {
 }
 declare function check(params: CheckParams): Promise<CheckResult>;
 
+declare const BINDING_KIND = 30079;
+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;
+    message_b64url?: 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 xOnlyHexToNpub(hex: string): string;
+interface BindingEventTemplate {
+    kind: typeof BINDING_KIND;
+    pubkey: string;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+declare function buildBindingEventTemplate(params: {
+    message: string;
+    btcSignature: string;
+    nostrPubkeyHex: string;
+    btc: string;
+    createdAt?: number;
+}): BindingEventTemplate;
+declare function assembleBindingEnvelope(params: {
+    message: string;
+    btcSignature: string;
+    btcScheme?: 'bip322' | 'legacy';
+    nostrEvent: BindingNostrEvent;
+}): BindingEnvelope;
+
 declare function isNip07Available(): boolean;
 declare function getNostrPublicKey(): Promise<string | null>;
 declare function signNostrEvent(event: Omit<NostrEvent, 'id' | 'sig'>): Promise<NostrEvent | null>;
@@ -50,4 +117,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 BindingEventTemplate, type BindingInput, type BindingNostrEvent, type BindingStatus, type BindingVerifyResult, type CheckParams, type CheckResult, IdentityBinding, Network, NostrEvent, STATUS_META, type Severity, StatusCode, type StatusMeta, VerifyOptions, assembleBindingEnvelope, bindingId, buildBindingEventTemplate, buildBindingMessage, check, getNip07Info, getNostrPublicKey, isNip07Available, signNostrEvent, verifyBinding, xOnlyHexToNpub };

package/dist/index.js

@@ -1177,6 +1177,246 @@ 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");
+  }
+}
+function xOnlyHexToNpub(hex) {
+  const bytes = fromHex(hex);
+  if (bytes.length !== 32) throw new Error("x-only Nostr key must be 32 bytes");
+  return base.bech32.encode("npub", base.bech32.toWords(bytes), 90);
+}
+function buildBindingEventTemplate(params) {
+  const id = bindingId(params.message);
+  return {
+    kind: BINDING_KIND,
+    pubkey: params.nostrPubkeyHex.toLowerCase(),
+    created_at: params.createdAt ?? Math.floor(Date.now() / 1e3),
+    tags: [
+      ["d", `oc-attest-binding:${id}`],
+      ["btc", params.btc],
+      ["oc", "binding-attestation"],
+      ["v", "1"]
+    ],
+    content: JSON.stringify({ message: params.message, btc_signature: params.btcSignature })
+  };
+}
+function parseBindingFields(message) {
+  const body = message.split("\n");
+  const at = (i, prefix) => {
+    const line = body[i];
+    if (typeof line !== "string" || !line.startsWith(prefix)) {
+      throw new Error(`binding message line ${i + 1} is malformed`);
+    }
+    return line.slice(prefix.length);
+  };
+  return {
+    principal: at(2, "principal: "),
+    btc: at(3, "btc: "),
+    nostr: at(4, "nostr: ")
+  };
+}
+function toBase64Url(s) {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  const b64 = typeof btoa !== "undefined" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function assembleBindingEnvelope(params) {
+  const { principal, btc, nostr } = parseBindingFields(params.message);
+  return {
+    binding_id: bindingId(params.message),
+    v: 1,
+    principal,
+    btc,
+    nostr,
+    message: params.message,
+    message_b64url: toBase64Url(params.message),
+    btc_signature: params.btcSignature,
+    btc_scheme: params.btcScheme ?? "bip322",
+    nostr_event: params.nostrEvent
+  };
+}
 var AUTH_HEADER = "orangecheck-auth";
 var AUTH_ACK = "I authorize this session under the OrangeCheck auth challenge.";
 function randomNonce() {
@@ -1632,12 +1872,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 +1901,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 +1984,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 +1992,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 +2354,10 @@ var STATUS_META = {
 
 exports.DEFAULT_RELAYS = DEFAULT_RELAYS;
 exports.STATUS_META = STATUS_META;
+exports.assembleBindingEnvelope = assembleBindingEnvelope;
+exports.bindingId = bindingId;
+exports.buildBindingEventTemplate = buildBindingEventTemplate;
+exports.buildBindingMessage = buildBindingMessage;
 exports.buildCanonicalMessage = buildCanonicalMessage;
 exports.check = check;
 exports.computeAllScores = computeAllScores;
@@ -2165,11 +2409,13 @@ exports.supportsAutomaticVerification = supportsAutomaticVerification;
 exports.verify = verify2;
 exports.verifyAllIdentities = verifyAllIdentities;
 exports.verifyAttestationById = verifyAttestationById;
+exports.verifyBinding = verifyBinding;
 exports.verifyChallenge = verifyChallenge;
 exports.verifyDnsIdentity = verifyDnsIdentity;
 exports.verifyGitHubIdentity = verifyGitHubIdentity;
 exports.verifyIdentity = verifyIdentity;
 exports.verifyNostrIdentity = verifyNostrIdentity;
 exports.verifyTwitterIdentity = verifyTwitterIdentity;
+exports.xOnlyHexToNpub = xOnlyHexToNpub;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map