@handlepay/resolve 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,100 @@
1
- # Temporary Holding Version
1
+ # @handlepay/resolve
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Turn a name like `sani@lycanforge.com.ng` into the Bitcoin Cash address it has **proven** it
4
+ controls, or into the reason it hasn't.
5
+
6
+ This is the verification code behind [HandlePay](https://handlepay.lycanforge.com.ng),
7
+ packaged so any wallet, shop or app can pay people by name. There's no HandlePay server in
8
+ the loop: it reads the name's domain, public Nostr relays, and the BCH chain directly.
9
+
10
+ ```bash
11
+ npm install @handlepay/resolve
12
+ ```
13
+
14
+ ## Use it
15
+
16
+ ```ts
17
+ import { resolve } from "@handlepay/resolve";
18
+
19
+ const r = await resolve("sani@lycanforge.com.ng", { network: "mainnet" });
20
+
21
+ switch (r.status) {
22
+ case "verified": // every check passed: safe to pay r.address
23
+ console.log("Pay", r.address);
24
+ break;
25
+ case "claimed": // signed claim, but control of the address isn't proven
26
+ case "changed": // verified, but different from what you pinned last time
27
+ console.log("Ask the user first:", r.reason, r.address);
28
+ break;
29
+ case "not_found": // no such name, no binding, or revoked
30
+ console.log("Can't pay:", r.reason);
31
+ }
32
+ ```
33
+
34
+ `r.checks` lists every check in order with `ok`, a plain-language `label`, and a `detail`
35
+ explaining any failure. It's ready to show to users as "how we checked".
36
+
37
+ Works in browsers and in Node 22 or later, which has built-in `fetch` and `WebSocket`.
38
+ In a browser, some domains block cross-origin NIP-05 requests; pass a proxy through
39
+ `fetchNip05`, or set `VITE_NIP05_PROXY` in a Vite app.
40
+
41
+ ## When it can't check
42
+
43
+ `resolve` returns `not_found` only when the name really has no identity. If it can't find out,
44
+ because no Nostr relay could be reached or the BCH server didn't answer, it **rejects** instead,
45
+ so a dead connection is never shown as "this name doesn't exist":
46
+
47
+ ```ts
48
+ import { resolve, RelaysUnreachableError } from "@handlepay/resolve";
49
+
50
+ try {
51
+ const r = await resolve(name);
52
+ // ...handle r.status as above
53
+ } catch (e) {
54
+ // Not "this name doesn't exist": offer "Try again".
55
+ if (e instanceof RelaysUnreachableError) console.log("No Nostr relay answered. Try again.");
56
+ else console.log("Couldn't check this name:", (e as Error).message); // e.g. the BCH server didn't answer
57
+ }
58
+ ```
59
+
60
+ ## What "verified" means
61
+
62
+ Three facts that point at each other:
63
+
64
+ 1. `https://domain/.well-known/nostr.json` lists the name's Nostr key (NIP-05).
65
+ 2. That key signed a binding event naming the BCH address and a proof transaction.
66
+ 3. The proof transaction was **spent from that address**, and its `OP_RETURN` names the same
67
+ Nostr key. It has at least 1 confirmation.
68
+
69
+ Someone who copies your address into their own profile can't make fact 3, so their claim
70
+ stays `claimed`. The proof and its parent transactions are re-hashed from raw bytes, so a
71
+ chain server can withhold data but can't fake it. Full protocol:
72
+ [HPAY-BIND v1](https://github.com/Lycan-Xx/handlepay/blob/main/docs/SPEC.md). Threat model:
73
+ [THREAT-MODEL.md](https://github.com/Lycan-Xx/handlepay/blob/main/docs/THREAT-MODEL.md).
74
+
75
+ ## Remember what you saw (trust on first use)
76
+
77
+ ```ts
78
+ const pinned = loadFromYourStorage(name); // { pubkey, address } | null
79
+ const r = await resolve(name, { network: "mainnet", pinned });
80
+ if (r.status === "verified") saveToYourStorage(name, { pubkey: r.pubkey!, address: r.address! });
81
+ if (r.status === "changed") warnUser(r.previous, r.address);
82
+ ```
83
+
84
+ ## Other exports
85
+
86
+ | Export | What it does |
87
+ |---|---|
88
+ | `resolveHandle(name, network, deps, pinned?)` | The same as `resolve`, with every network lookup injectable, for tests or your own servers |
89
+ | `liveDeps(network)` | The default lookups: NIP-05, relays, and Fulcrum (via CashScript) |
90
+ | `paymentGate(result)` | `"allowed"`, `"confirm_unverified"`, `"acknowledge_change"` or `"blocked"` |
91
+ | `checkProof(input)` | The four BCH checks on a proof transaction, from raw bytes |
92
+ | `parseBindingEvent`, `buildBindingEvent`, `buildRevokeEvent`, `buildPaytoEvent` | Read and write the Nostr events |
93
+ | `proofOpReturnChunks`, `parseProofOutput` | Write and read the `OP_RETURN "HPAY" 01 <pubkey>` proof output |
94
+ | `createChallenge`, `buildAuthTemplate`, `verifyAuthEvent` | Sign-in with a name (challenge–response, kind 22242) |
95
+ | `parseHandle`, `fetchNip05`, `queryIdentityEvents` | The lower-level lookups |
96
+ | `RelaysUnreachableError` | Thrown when no Nostr relay can be reached (since 0.2.0) |
97
+
98
+ ## License
99
+
100
+ MIT