@handlepay/resolve 0.0.0-stage → 0.1.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 +79 -2
- package/dist/index.js +781 -0
- package/dist/index.js.map +1 -0
- package/dist/types/packages/resolve/src/index.d.ts +38 -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 +79 -0
- package/dist/types/src/lib/resolve.d.ts +35 -0
- package/package.json +29 -4
package/README.md
CHANGED
|
@@ -1,3 +1,80 @@
|
|
|
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
|
+
## What "verified" means
|
|
42
|
+
|
|
43
|
+
Three facts that point at each other:
|
|
44
|
+
|
|
45
|
+
1. `https://domain/.well-known/nostr.json` lists the name's Nostr key (NIP-05).
|
|
46
|
+
2. That key signed a binding event naming the BCH address and a proof transaction.
|
|
47
|
+
3. The proof transaction was **spent from that address**, and its `OP_RETURN` names the same
|
|
48
|
+
Nostr key. It has at least 1 confirmation.
|
|
49
|
+
|
|
50
|
+
Someone who copies your address into their own profile can't make fact 3, so their claim
|
|
51
|
+
stays `claimed`. The proof and its parent transactions are re-hashed from raw bytes, so a
|
|
52
|
+
chain server can withhold data but can't fake it. Full protocol:
|
|
53
|
+
[HPAY-BIND v1](https://github.com/Lycan-Xx/handlepay/blob/main/docs/SPEC.md). Threat model:
|
|
54
|
+
[THREAT-MODEL.md](https://github.com/Lycan-Xx/handlepay/blob/main/docs/THREAT-MODEL.md).
|
|
55
|
+
|
|
56
|
+
## Remember what you saw (trust on first use)
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
const pinned = loadFromYourStorage(name); // { pubkey, address } | null
|
|
60
|
+
const r = await resolve(name, { network: "mainnet", pinned });
|
|
61
|
+
if (r.status === "verified") saveToYourStorage(name, { pubkey: r.pubkey!, address: r.address! });
|
|
62
|
+
if (r.status === "changed") warnUser(r.previous, r.address);
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Other exports
|
|
66
|
+
|
|
67
|
+
| Export | What it does |
|
|
68
|
+
|---|---|
|
|
69
|
+
| `resolveHandle(name, network, deps, pinned?)` | The same as `resolve`, with every network lookup injectable, for tests or your own servers |
|
|
70
|
+
| `liveDeps(network)` | The default lookups: NIP-05, relays, and Fulcrum (via CashScript) |
|
|
71
|
+
| `paymentGate(result)` | `"allowed"`, `"confirm_unverified"`, `"acknowledge_change"` or `"blocked"` |
|
|
72
|
+
| `checkProof(input)` | The four BCH checks on a proof transaction, from raw bytes |
|
|
73
|
+
| `parseBindingEvent`, `buildBindingEvent`, `buildRevokeEvent`, `buildPaytoEvent` | Read and write the Nostr events |
|
|
74
|
+
| `proofOpReturnChunks`, `parseProofOutput` | Write and read the `OP_RETURN "HPAY" 01 <pubkey>` proof output |
|
|
75
|
+
| `createChallenge`, `buildAuthTemplate`, `verifyAuthEvent` | Sign-in with a name (challenge–response, kind 22242) |
|
|
76
|
+
| `parseHandle`, `fetchNip05`, `queryIdentityEvents` | The lower-level lookups |
|
|
77
|
+
|
|
78
|
+
## License
|
|
79
|
+
|
|
80
|
+
MIT
|