@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 +99 -2
- package/dist/index.js +806 -0
- package/dist/index.js.map +1 -0
- package/dist/types/packages/resolve/src/index.d.ts +42 -0
- package/dist/types/src/lib/auth.d.ts +18 -0
- package/dist/types/src/lib/binding.d.ts +116 -0
- package/dist/types/src/lib/network.d.ts +36 -0
- package/dist/types/src/lib/nostr.d.ts +95 -0
- package/dist/types/src/lib/resolve.d.ts +35 -0
- package/package.json +29 -4
package/README.md
CHANGED
|
@@ -1,3 +1,100 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @handlepay/resolve
|
|
2
2
|
|
|
3
|
-
|
|
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
|