@xrpl-wallet-kit/auth 0.1.12 → 0.1.14

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.
Files changed (2) hide show
  1. package/README.md +184 -184
  2. package/package.json +69 -69
package/README.md CHANGED
@@ -1,184 +1,184 @@
1
- # @xrpl-wallet-kit/auth
2
-
3
- Sign-In with Wallet helpers for XRPL Wallet Kit.
4
-
5
- This package is intentionally split from `@xrpl-wallet-kit/core`: core signs messages, while auth handles nonce, message formatting, server verification, auth state, and sign-out. The main entry is client-safe. XRPL verifier dependencies live behind the `./verifiers` subpath and should only be imported on the server.
6
-
7
- ## Install
8
-
9
- ```bash
10
- npm install @xrpl-wallet-kit/auth @xrpl-wallet-kit/core
11
- ```
12
-
13
- For server-side XRPL verification, install the optional peers in your server package:
14
-
15
- ```bash
16
- npm install ripple-keypairs verify-xrpl-signature xrpl
17
- ```
18
-
19
- ## Client Usage
20
-
21
- ```ts
22
- import { createWalletAuth, formatAuthMessage } from "@xrpl-wallet-kit/auth";
23
-
24
- const auth = createWalletAuth(manager, {
25
- async getNonce() {
26
- const res = await fetch("/api/auth/nonce", { credentials: "include" });
27
- const body = await res.json();
28
- return body.nonce;
29
- },
30
- createMessage(params) {
31
- return formatAuthMessage(params);
32
- },
33
- async verify(params) {
34
- const res = await fetch("/api/auth/verify", {
35
- method: "POST",
36
- credentials: "include",
37
- headers: { "content-type": "application/json" },
38
- body: JSON.stringify(params)
39
- });
40
- return res.ok;
41
- },
42
- async signOut() {
43
- await fetch("/api/auth/signout", { method: "POST", credentials: "include" });
44
- }
45
- }, {
46
- domain: window.location.host,
47
- uri: window.location.origin,
48
- chainId: "xrpl:0",
49
- statement: "Sign in to Example App"
50
- });
51
-
52
- auth.on("change", (state) => {
53
- console.log(state.status, state.address);
54
- });
55
-
56
- await auth.signIn();
57
- ```
58
-
59
- The dApp does not branch by wallet id. `manager.signMessage()` delegates to the active adapter and returns the normalized proof shape:
60
-
61
- ```ts
62
- {
63
- signatureKind: "signature" | "signedTx",
64
- proof: string,
65
- signature?: string,
66
- txBlob?: string,
67
- publicKey?: string
68
- }
69
- ```
70
-
71
- ## Pre-Issued Nonce
72
-
73
- If your dApp already issued a nonce before the user clicks sign-in, return that nonce from `getNonce()`. This is common in SSR pages, legacy apps, or flows where the nonce is rendered into the page by the server.
74
-
75
- ```ts
76
- import { createWalletAuth, formatAuthMessage } from "@xrpl-wallet-kit/auth";
77
-
78
- const preIssuedNonce = window.__AUTH_NONCE__;
79
-
80
- const auth = createWalletAuth(manager, {
81
- async getNonce() {
82
- return preIssuedNonce;
83
- },
84
- createMessage(params) {
85
- return formatAuthMessage(params);
86
- },
87
- async verify(params) {
88
- const res = await fetch("/api/auth/verify", {
89
- method: "POST",
90
- credentials: "include",
91
- headers: { "content-type": "application/json" },
92
- body: JSON.stringify(params)
93
- });
94
- return res.ok;
95
- }
96
- }, {
97
- domain: window.location.host,
98
- uri: window.location.origin,
99
- chainId: "xrpl:0",
100
- statement: "Sign in to Example App"
101
- });
102
-
103
- await auth.signIn();
104
- ```
105
-
106
- The server must still generate, store, validate, and invalidate the nonce. Do not treat a browser-generated nonce as trusted authentication state.
107
-
108
- ```js
109
- app.get("/login", (req, res) => {
110
- const nonce = createSecureNonce();
111
- req.session.authNonce = nonce;
112
- res.render("login", { authNonce: nonce });
113
- });
114
-
115
- app.post("/api/auth/verify", async (req, res) => {
116
- const parsed = parseAuthMessage(req.body.message);
117
-
118
- if (parsed.nonce !== req.session.authNonce) {
119
- return res.status(400).json({ ok: false, error: "Invalid nonce" });
120
- }
121
-
122
- // Verify req.body proof here, then create the app session.
123
- req.session.authNonce = null;
124
- res.json({ ok: true });
125
- });
126
- ```
127
-
128
- ## Server Verification
129
-
130
- ```ts
131
- import { createXrplSignatureVerifier } from "@xrpl-wallet-kit/auth/verifiers";
132
-
133
- const verifier = createXrplSignatureVerifier({
134
- nodeUrl: "wss://xrplcluster.com"
135
- });
136
-
137
- const ok = await verifier.verify({
138
- address: body.address,
139
- message: body.message,
140
- signatureKind: body.signatureKind,
141
- proof: body.proof,
142
- signature: body.signature,
143
- txBlob: body.txBlob,
144
- publicKey: body.publicKey
145
- });
146
- ```
147
-
148
- For `signatureKind: "signature"`, `publicKey` should be provided by the wallet/sign result. Ledger lookup via `account_info.account_data.PublicKey` is only a fallback. Do not use `RegularKey` as a public key.
149
-
150
- For `signatureKind: "signedTx"`, the verifier checks the signed transaction blob, signer address, transaction `Account`, and first memo text against the original auth message.
151
-
152
- ## Legacy HTML Pattern
153
-
154
- Legacy pages can use the same API from the browser bundle or ESM build. Keep the server verification endpoint separate:
155
-
156
- ```js
157
- async function signInWithWalletKit(manager) {
158
- const auth = XRPLWalletKitAuth.createWalletAuth(manager, {
159
- async getNonce() {
160
- return (await fetch("/api/auth/nonce", { credentials: "include" }).then((r) => r.json())).nonce;
161
- },
162
- createMessage(params) {
163
- return XRPLWalletKitAuth.formatAuthMessage(params);
164
- },
165
- async verify(params) {
166
- const response = await fetch("/api/auth/verify", {
167
- method: "POST",
168
- credentials: "include",
169
- headers: { "content-type": "application/json" },
170
- body: JSON.stringify(params)
171
- });
172
- return response.ok;
173
- }
174
- }, {
175
- domain: location.host,
176
- uri: location.origin,
177
- chainId: "xrpl:0"
178
- });
179
-
180
- return auth.signIn();
181
- }
182
- ```
183
-
184
- Do not verify signatures in browser-only legacy code. The nonce must be generated, stored, validated, and invalidated by the server.
1
+ # @xrpl-wallet-kit/auth
2
+
3
+ Sign-In with Wallet helpers for XRPL Wallet Kit.
4
+
5
+ This package is intentionally split from `@xrpl-wallet-kit/core`: core signs messages, while auth handles nonce, message formatting, server verification, auth state, and sign-out. The main entry is client-safe. XRPL verifier dependencies live behind the `./verifiers` subpath and should only be imported on the server.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @xrpl-wallet-kit/auth @xrpl-wallet-kit/core
11
+ ```
12
+
13
+ For server-side XRPL verification, install the optional peers in your server package:
14
+
15
+ ```bash
16
+ npm install ripple-keypairs verify-xrpl-signature xrpl
17
+ ```
18
+
19
+ ## Client Usage
20
+
21
+ ```ts
22
+ import { createWalletAuth, formatAuthMessage } from "@xrpl-wallet-kit/auth";
23
+
24
+ const auth = createWalletAuth(manager, {
25
+ async getNonce() {
26
+ const res = await fetch("/api/auth/nonce", { credentials: "include" });
27
+ const body = await res.json();
28
+ return body.nonce;
29
+ },
30
+ createMessage(params) {
31
+ return formatAuthMessage(params);
32
+ },
33
+ async verify(params) {
34
+ const res = await fetch("/api/auth/verify", {
35
+ method: "POST",
36
+ credentials: "include",
37
+ headers: { "content-type": "application/json" },
38
+ body: JSON.stringify(params)
39
+ });
40
+ return res.ok;
41
+ },
42
+ async signOut() {
43
+ await fetch("/api/auth/signout", { method: "POST", credentials: "include" });
44
+ }
45
+ }, {
46
+ domain: window.location.host,
47
+ uri: window.location.origin,
48
+ chainId: "xrpl:0",
49
+ statement: "Sign in to Example App"
50
+ });
51
+
52
+ auth.on("change", (state) => {
53
+ console.log(state.status, state.address);
54
+ });
55
+
56
+ await auth.signIn();
57
+ ```
58
+
59
+ The dApp does not branch by wallet id. `manager.signMessage()` delegates to the active adapter and returns the normalized proof shape:
60
+
61
+ ```ts
62
+ {
63
+ signatureKind: "signature" | "signedTx",
64
+ proof: string,
65
+ signature?: string,
66
+ txBlob?: string,
67
+ publicKey?: string
68
+ }
69
+ ```
70
+
71
+ ## Pre-Issued Nonce
72
+
73
+ If your dApp already issued a nonce before the user clicks sign-in, return that nonce from `getNonce()`. This is common in SSR pages, legacy apps, or flows where the nonce is rendered into the page by the server.
74
+
75
+ ```ts
76
+ import { createWalletAuth, formatAuthMessage } from "@xrpl-wallet-kit/auth";
77
+
78
+ const preIssuedNonce = window.__AUTH_NONCE__;
79
+
80
+ const auth = createWalletAuth(manager, {
81
+ async getNonce() {
82
+ return preIssuedNonce;
83
+ },
84
+ createMessage(params) {
85
+ return formatAuthMessage(params);
86
+ },
87
+ async verify(params) {
88
+ const res = await fetch("/api/auth/verify", {
89
+ method: "POST",
90
+ credentials: "include",
91
+ headers: { "content-type": "application/json" },
92
+ body: JSON.stringify(params)
93
+ });
94
+ return res.ok;
95
+ }
96
+ }, {
97
+ domain: window.location.host,
98
+ uri: window.location.origin,
99
+ chainId: "xrpl:0",
100
+ statement: "Sign in to Example App"
101
+ });
102
+
103
+ await auth.signIn();
104
+ ```
105
+
106
+ The server must still generate, store, validate, and invalidate the nonce. Do not treat a browser-generated nonce as trusted authentication state.
107
+
108
+ ```js
109
+ app.get("/login", (req, res) => {
110
+ const nonce = createSecureNonce();
111
+ req.session.authNonce = nonce;
112
+ res.render("login", { authNonce: nonce });
113
+ });
114
+
115
+ app.post("/api/auth/verify", async (req, res) => {
116
+ const parsed = parseAuthMessage(req.body.message);
117
+
118
+ if (parsed.nonce !== req.session.authNonce) {
119
+ return res.status(400).json({ ok: false, error: "Invalid nonce" });
120
+ }
121
+
122
+ // Verify req.body proof here, then create the app session.
123
+ req.session.authNonce = null;
124
+ res.json({ ok: true });
125
+ });
126
+ ```
127
+
128
+ ## Server Verification
129
+
130
+ ```ts
131
+ import { createXrplSignatureVerifier } from "@xrpl-wallet-kit/auth/verifiers";
132
+
133
+ const verifier = createXrplSignatureVerifier({
134
+ nodeUrl: "wss://xrplcluster.com"
135
+ });
136
+
137
+ const ok = await verifier.verify({
138
+ address: body.address,
139
+ message: body.message,
140
+ signatureKind: body.signatureKind,
141
+ proof: body.proof,
142
+ signature: body.signature,
143
+ txBlob: body.txBlob,
144
+ publicKey: body.publicKey
145
+ });
146
+ ```
147
+
148
+ For `signatureKind: "signature"`, `publicKey` should be provided by the wallet/sign result. Ledger lookup via `account_info.account_data.PublicKey` is only a fallback. Do not use `RegularKey` as a public key.
149
+
150
+ For `signatureKind: "signedTx"`, the verifier checks the signed transaction blob, signer address, transaction `Account`, and first memo text against the original auth message.
151
+
152
+ ## Legacy HTML Pattern
153
+
154
+ Legacy pages can use the same API from the browser bundle or ESM build. Keep the server verification endpoint separate:
155
+
156
+ ```js
157
+ async function signInWithWalletKit(manager) {
158
+ const auth = XRPLWalletKitAuth.createWalletAuth(manager, {
159
+ async getNonce() {
160
+ return (await fetch("/api/auth/nonce", { credentials: "include" }).then((r) => r.json())).nonce;
161
+ },
162
+ createMessage(params) {
163
+ return XRPLWalletKitAuth.formatAuthMessage(params);
164
+ },
165
+ async verify(params) {
166
+ const response = await fetch("/api/auth/verify", {
167
+ method: "POST",
168
+ credentials: "include",
169
+ headers: { "content-type": "application/json" },
170
+ body: JSON.stringify(params)
171
+ });
172
+ return response.ok;
173
+ }
174
+ }, {
175
+ domain: location.host,
176
+ uri: location.origin,
177
+ chainId: "xrpl:0"
178
+ });
179
+
180
+ return auth.signIn();
181
+ }
182
+ ```
183
+
184
+ Do not verify signatures in browser-only legacy code. The nonce must be generated, stored, validated, and invalidated by the server.
package/package.json CHANGED
@@ -1,69 +1,69 @@
1
- {
2
- "name": "@xrpl-wallet-kit/auth",
3
- "version": "0.1.12",
4
- "description": "Sign-In with Wallet helpers for XRPL Wallet Kit.",
5
- "license": "MIT",
6
- "type": "module",
7
- "sideEffects": false,
8
- "main": "./dist/index.js",
9
- "types": "./dist/index.d.ts",
10
- "exports": {
11
- ".": {
12
- "types": "./dist/index.d.ts",
13
- "import": "./dist/index.js"
14
- },
15
- "./verifiers": {
16
- "types": "./dist/verifiers/index.d.ts",
17
- "import": "./dist/verifiers/index.js"
18
- }
19
- },
20
- "files": [
21
- "dist",
22
- "README.md"
23
- ],
24
- "scripts": {
25
- "build": "tsc -p tsconfig.json"
26
- },
27
- "dependencies": {
28
- "@xrpl-wallet-kit/core": "0.1.12"
29
- },
30
- "peerDependencies": {
31
- "ripple-keypairs": "^2.0.0",
32
- "verify-xrpl-signature": "^9.2.0",
33
- "xrpl": "^4.0.0"
34
- },
35
- "peerDependenciesMeta": {
36
- "ripple-keypairs": {
37
- "optional": true
38
- },
39
- "verify-xrpl-signature": {
40
- "optional": true
41
- },
42
- "xrpl": {
43
- "optional": true
44
- }
45
- },
46
- "devDependencies": {
47
- "ripple-keypairs": "^2.0.0",
48
- "verify-xrpl-signature": "^9.2.0",
49
- "xrpl": "^4.0.0"
50
- },
51
- "publishConfig": {
52
- "access": "public"
53
- },
54
- "repository": {
55
- "type": "git",
56
- "url": "git+https://github.com/XRPDomains/xrpl-wallet-kit.git"
57
- },
58
- "homepage": "https://github.com/XRPDomains/xrpl-wallet-kit#readme",
59
- "bugs": {
60
- "url": "https://github.com/XRPDomains/xrpl-wallet-kit/issues"
61
- },
62
- "keywords": [
63
- "xrpl",
64
- "wallet",
65
- "wallet-auth",
66
- "sign-in",
67
- "web3"
68
- ]
69
- }
1
+ {
2
+ "name": "@xrpl-wallet-kit/auth",
3
+ "version": "0.1.14",
4
+ "description": "Sign-In with Wallet helpers for XRPL Wallet Kit.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "sideEffects": false,
8
+ "main": "./dist/index.js",
9
+ "types": "./dist/index.d.ts",
10
+ "exports": {
11
+ ".": {
12
+ "types": "./dist/index.d.ts",
13
+ "import": "./dist/index.js"
14
+ },
15
+ "./verifiers": {
16
+ "types": "./dist/verifiers/index.d.ts",
17
+ "import": "./dist/verifiers/index.js"
18
+ }
19
+ },
20
+ "files": [
21
+ "dist",
22
+ "README.md"
23
+ ],
24
+ "scripts": {
25
+ "build": "tsc -p tsconfig.json"
26
+ },
27
+ "dependencies": {
28
+ "@xrpl-wallet-kit/core": "0.1.14"
29
+ },
30
+ "peerDependencies": {
31
+ "ripple-keypairs": "^2.0.0",
32
+ "verify-xrpl-signature": "^9.2.0",
33
+ "xrpl": "^4.0.0 || ^5.0.0"
34
+ },
35
+ "peerDependenciesMeta": {
36
+ "ripple-keypairs": {
37
+ "optional": true
38
+ },
39
+ "verify-xrpl-signature": {
40
+ "optional": true
41
+ },
42
+ "xrpl": {
43
+ "optional": true
44
+ }
45
+ },
46
+ "devDependencies": {
47
+ "ripple-keypairs": "^2.0.0",
48
+ "verify-xrpl-signature": "^9.2.0",
49
+ "xrpl": "^4.0.0"
50
+ },
51
+ "publishConfig": {
52
+ "access": "public"
53
+ },
54
+ "repository": {
55
+ "type": "git",
56
+ "url": "git+https://github.com/XRPDomains/xrpl-wallet-kit.git"
57
+ },
58
+ "homepage": "https://github.com/XRPDomains/xrpl-wallet-kit#readme",
59
+ "bugs": {
60
+ "url": "https://github.com/XRPDomains/xrpl-wallet-kit/issues"
61
+ },
62
+ "keywords": [
63
+ "xrpl",
64
+ "wallet",
65
+ "wallet-auth",
66
+ "sign-in",
67
+ "web3"
68
+ ]
69
+ }