@neuraiproject/neurai-sign-esp32 0.5.6 → 0.5.8
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 +116 -0
- package/dist/NeuraiSignESP32.global.js +167 -0
- package/dist/browser.js +167 -0
- package/dist/index.cjs +167 -0
- package/dist/index.d.ts +184 -2
- package/dist/index.js +167 -0
- package/dist/react-native.d.ts +184 -2
- package/dist/react-native.js +167 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -202,6 +202,103 @@ console.log(bip32.master_fingerprint); // "a1b2c3d4"
|
|
|
202
202
|
console.log(bip32.path); // "m/44'/1900'/0'"
|
|
203
203
|
```
|
|
204
204
|
|
|
205
|
+
### DePIN chat identity (sign/decrypt on the device)
|
|
206
|
+
|
|
207
|
+
The device holds a **dedicated DePIN chat identity** on BIP44 account `100'`
|
|
208
|
+
(`m/44'/<coin>'/100'/0/0`), separate from the funds account, so a wallet can
|
|
209
|
+
chat over Neurai DePIN messaging without ever exposing its mnemonic. Signing and
|
|
210
|
+
decryption happen **on the chip**.
|
|
211
|
+
|
|
212
|
+
Feature-detect first — `ping()` advertises `capabilities`: `"depin_identity"`
|
|
213
|
+
(identity + session) and `"depin_message"` (on-device `depinSign`/`depinDecrypt`).
|
|
214
|
+
|
|
215
|
+
```javascript
|
|
216
|
+
const { capabilities = [] } = await device.ping();
|
|
217
|
+
if (!capabilities.includes("depin_identity")) throw new Error("update firmware");
|
|
218
|
+
|
|
219
|
+
// 1) Open a session on the channel token — ONE physical approval on the device.
|
|
220
|
+
// While active the device reveals its identity and auto-signs/decrypts on
|
|
221
|
+
// this channel (bounded by an idle timeout, a hard cap, and a rate limit).
|
|
222
|
+
const session = await device.depinSessionBegin("&NEURAI.CHAT", {
|
|
223
|
+
ttlMinutes: 15, // idle window (1–60, default 15)
|
|
224
|
+
ratePerMin: 100, // in-session sign/decrypt cap (default 100)
|
|
225
|
+
});
|
|
226
|
+
console.log(session.expires_in_s, session.max_session_s, session.rate_per_min);
|
|
227
|
+
|
|
228
|
+
// 2) Read the chat identity (no per-call prompt while the session is open).
|
|
229
|
+
// This is what a hardware wallet uses instead of deriving from a mnemonic.
|
|
230
|
+
const id = await device.getDepinIdentity();
|
|
231
|
+
console.log(id.address, id.pubkey, id.path, id.network); // "xna" | "xna-test"
|
|
232
|
+
|
|
233
|
+
// 3) Sign an outgoing message. The host does the recipient-pubkey ECIES
|
|
234
|
+
// encryption and passes the fields; the device builds the canonical
|
|
235
|
+
// CDepinMessage preimage and returns the DER signature.
|
|
236
|
+
const { signature, op_count } = await device.depinSign({
|
|
237
|
+
token: "&NEURAI.CHAT",
|
|
238
|
+
sender: id.address, // must equal the device's DePIN address
|
|
239
|
+
timestamp: Math.floor(Date.now() / 1000),
|
|
240
|
+
messageType: 1, // 1 = direct (DATA), 2 = group (BROADCAST)
|
|
241
|
+
encryptedPayload: eciesPayloadHex, // built host-side
|
|
242
|
+
});
|
|
243
|
+
|
|
244
|
+
// 4) Decrypt an incoming CDepinMessage addressed to this identity.
|
|
245
|
+
// GCM-authenticated; the sender's signature is verified host-side.
|
|
246
|
+
const { plaintext_b64 } = await device.depinDecrypt(cdepinMessageHex);
|
|
247
|
+
|
|
248
|
+
// 5) End the session when done (also revoked on lock / USB disconnect / timeout).
|
|
249
|
+
await device.depinSessionEnd();
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
> **Note on time:** the device has no real-time clock, so it does **not** check
|
|
253
|
+
> the freshness of `timestamp` — the host supplies it and the chip only validates
|
|
254
|
+
> the message structure and channel/sender scope.
|
|
255
|
+
|
|
256
|
+
### Provision an unconfigured device (`setup_seed`)
|
|
257
|
+
|
|
258
|
+
Firmware with the security layer boots **unconfigured** until a seed is stored
|
|
259
|
+
(and **locked** at every boot after that, until the owner enters the PIN on the
|
|
260
|
+
device). Instead of typing 12/24 words with two buttons, a host that holds the
|
|
261
|
+
mnemonic (e.g. it just generated the wallet) can push it over USB:
|
|
262
|
+
|
|
263
|
+
```javascript
|
|
264
|
+
// 1) Where is the device at?
|
|
265
|
+
const state = await device.getDeviceState(); // "ready" | "locked" | "unconfigured"
|
|
266
|
+
|
|
267
|
+
if (state === "unconfigured") {
|
|
268
|
+
// 2) Send the seed. The owner must physically approve a SUMMARY on the
|
|
269
|
+
// device within 60 s (word count + network + key type — never the words).
|
|
270
|
+
const res = await device.setupSeed({
|
|
271
|
+
mnemonic: "word1 word2 ... word12", // 12 or 24 BIP39 words
|
|
272
|
+
network: "testnet", // REQUIRED: "mainnet" | "testnet"
|
|
273
|
+
keyType: "pq", // REQUIRED: "pq" | "legacy" (pq = testnet-only)
|
|
274
|
+
});
|
|
275
|
+
console.log(res.state); // "pin_required"
|
|
276
|
+
|
|
277
|
+
// 3) The owner now creates the PIN ON THE DEVICE (it never travels over
|
|
278
|
+
// USB). Poll until the seed is encrypted and the keys are derived:
|
|
279
|
+
await device.waitUntilReady(); // default: every 2 s, up to 5 min
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// 4) Normal operation from here.
|
|
283
|
+
const info = await device.getInfo();
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Notes:
|
|
287
|
+
|
|
288
|
+
- `setup_seed` is **only accepted while no encrypted seed is stored** (first
|
|
289
|
+
boot, dev-fallback firmware, or after an on-device wipe). On a configured
|
|
290
|
+
device it throws `"Device already configured: wipe it on-device first"`
|
|
291
|
+
without prompting — it can never overwrite an existing wallet.
|
|
292
|
+
- If the owner rejects (or the 60 s pass) you get `"User cancelled"`; if they
|
|
293
|
+
cancel during PIN entry the device stays unconfigured and you can simply call
|
|
294
|
+
`setupSeed` again.
|
|
295
|
+
- `getDeviceState()` distinguishes `locked` (ask the user to enter the PIN on
|
|
296
|
+
the device) from `unconfigured` (provisioning applies) by parsing the
|
|
297
|
+
firmware's gate errors; it never prompts and is safe to poll.
|
|
298
|
+
- **Security:** the mnemonic transits the host OS and the USB link in
|
|
299
|
+
plaintext — acceptable when this host generated the seed, but entering the
|
|
300
|
+
words directly on the device remains the more private path.
|
|
301
|
+
|
|
205
302
|
## Post-Quantum (PQ / ML-DSA-44) support
|
|
206
303
|
|
|
207
304
|
The device operates in one mode at a time, declared via `info` on two
|
|
@@ -474,16 +571,27 @@ using JSON messages. Supported commands:
|
|
|
474
571
|
| Command | Confirmation | Timeout |
|
|
475
572
|
|---|---|---|
|
|
476
573
|
| `info` | None | 5s |
|
|
574
|
+
| `setup_seed` | Physical button (summary on screen) | 60s approval + on-device PIN entry |
|
|
477
575
|
| `get_address` | Physical button | 30s |
|
|
478
576
|
| `get_bip32_pubkey` | Physical button | 30s |
|
|
479
577
|
| `sign_psbt` | Physical button + TX review | 60s |
|
|
480
578
|
| `sign_tx` (PQ) | Physical button + TX review | per-heartbeat (ML-DSA is slow) |
|
|
481
579
|
| `sign_message` | Physical button | 30s |
|
|
580
|
+
| `depin_session_begin` | Physical button (channel token on screen) | 30s |
|
|
581
|
+
| `get_depin_identity` | None (session-gated) | 10s |
|
|
582
|
+
| `depin_sign` | None (session-gated, rate-limited) | 30s |
|
|
583
|
+
| `depin_decrypt` | None (session-gated, rate-limited) | 30s |
|
|
584
|
+
| `depin_session_end` | None | 10s |
|
|
482
585
|
|
|
483
586
|
`info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
|
|
484
587
|
returns only the public key (the library derives the address) and signing uses
|
|
485
588
|
`sign_tx` (raw transaction) instead of `sign_psbt`.
|
|
486
589
|
|
|
590
|
+
While the device is **locked** (encrypted seed stored, PIN pending) or
|
|
591
|
+
**unconfigured** (no seed), the firmware rejects every command except
|
|
592
|
+
`setup_seed` with a distinct error message; `getDeviceState()` parses those
|
|
593
|
+
into `"locked"` / `"unconfigured"`.
|
|
594
|
+
|
|
487
595
|
## API
|
|
488
596
|
|
|
489
597
|
### `NeuraiESP32`
|
|
@@ -495,12 +603,20 @@ Main class for device interaction.
|
|
|
495
603
|
| `connect()` | Open USB Serial connection (browser dialog) |
|
|
496
604
|
| `disconnect()` | Close connection |
|
|
497
605
|
| `ping()` | Detect/handshake the device (no confirmation, no wallet-identifying data) — use this to enumerate devices |
|
|
606
|
+
| `getDeviceState()` | `"ready"` \| `"locked"` \| `"unconfigured"` — safe to poll, no confirmation |
|
|
607
|
+
| `setupSeed({ mnemonic, network, keyType })` | Provision an unconfigured device with a host-held seed (owner approves on device, then sets the PIN there) |
|
|
608
|
+
| `waitUntilReady(opts?)` | Poll until the device is operational (after `setupSeed` PIN entry or unlock) |
|
|
498
609
|
| `getInfo()` | Get device info incl. `key_type` (**requires confirmation** on consent-model firmware) |
|
|
499
610
|
| `getAddress()` | Get address + pubkey (requires confirmation); derives the address from the pubkey + mode (legacy or PQ) |
|
|
500
611
|
| `getBip32Pubkey()` | Get account xpub (requires confirmation) |
|
|
501
612
|
| `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
|
|
502
613
|
| `signPsbt(base64, display?)` | Sign a PSBT and optionally send display metadata |
|
|
503
614
|
| `signMessage(message)` | Sign a message to prove address ownership (requires confirmation) |
|
|
615
|
+
| `depinSessionBegin(token, opts?)` | Open a DePIN chat session on a channel token (one approval); enables identity read + auto sign/decrypt |
|
|
616
|
+
| `getDepinIdentity()` | Read the DePIN chat identity (address + pubkey + path); session-gated, no per-call prompt |
|
|
617
|
+
| `depinSign(params)` | Sign a DePIN message on-device (DER over the canonical CDepinMessage); session-gated, rate-limited |
|
|
618
|
+
| `depinDecrypt(depinMessageHex)` | Decrypt a CDepinMessage addressed to this identity → `plaintext_b64`; session-gated |
|
|
619
|
+
| `depinSessionEnd()` | End the DePIN session (also revoked on lock / disconnect / timeout) |
|
|
504
620
|
| `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
|
|
505
621
|
| `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |
|
|
506
622
|
|
|
@@ -12950,6 +12950,85 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
12950
12950
|
this.assertSuccess(response);
|
|
12951
12951
|
return response;
|
|
12952
12952
|
}
|
|
12953
|
+
/**
|
|
12954
|
+
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
12955
|
+
* `ready` (keys derived, normal commands work), `locked` (encrypted seed
|
|
12956
|
+
* stored, PIN not entered yet — ask the user to unlock on the device) or
|
|
12957
|
+
* `unconfigured` (no seed stored — {@link setupSeed} or the on-device wizard
|
|
12958
|
+
* applies). Safe to poll; never prompts on the device.
|
|
12959
|
+
*
|
|
12960
|
+
* Firmware predating the security layer answers `ping` successfully in every
|
|
12961
|
+
* state, so it reports `ready`.
|
|
12962
|
+
*/
|
|
12963
|
+
async getDeviceState() {
|
|
12964
|
+
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12965
|
+
if (response.status !== "error") {
|
|
12966
|
+
return "ready";
|
|
12967
|
+
}
|
|
12968
|
+
const message = (response.message ?? "").toLowerCase();
|
|
12969
|
+
if (message.includes("locked"))
|
|
12970
|
+
return "locked";
|
|
12971
|
+
if (message.includes("not configured"))
|
|
12972
|
+
return "unconfigured";
|
|
12973
|
+
throw new Error(`Device error: ${response.message}`);
|
|
12974
|
+
}
|
|
12975
|
+
/**
|
|
12976
|
+
* Provision an UNCONFIGURED device with a host-held mnemonic (`setup_seed`).
|
|
12977
|
+
*
|
|
12978
|
+
* The firmware only accepts this while **no encrypted seed is stored** (first
|
|
12979
|
+
* boot, dev-fallback mode, or after a wipe + reboot); on a configured device
|
|
12980
|
+
* it errors without prompting. The owner must physically approve a summary on
|
|
12981
|
+
* the device (word count + network + key type — the words are NEVER shown)
|
|
12982
|
+
* within 60 s, and then creates the PIN **on the device**: the PIN never
|
|
12983
|
+
* travels over USB. The seed transits the host and the USB link in plaintext
|
|
12984
|
+
* by design (this host generated it) — on-device entry remains the more
|
|
12985
|
+
* private path.
|
|
12986
|
+
*
|
|
12987
|
+
* Resolves with `{ state: "pin_required" }` once the owner approves. The
|
|
12988
|
+
* protocol has no push events, so detect completion by polling — see
|
|
12989
|
+
* {@link waitUntilReady}. If the owner cancels the PIN entry afterwards, the
|
|
12990
|
+
* device stays unconfigured and `setupSeed` can simply be called again.
|
|
12991
|
+
*/
|
|
12992
|
+
async setupSeed(options) {
|
|
12993
|
+
// Client-side pre-checks for fast feedback; the device re-validates
|
|
12994
|
+
// everything (including the BIP39 checksum) authoritatively.
|
|
12995
|
+
const words = options.mnemonic.trim().split(/\s+/).filter(Boolean);
|
|
12996
|
+
if (words.length !== 12 && words.length !== 24) {
|
|
12997
|
+
throw new Error("Mnemonic must be 12 or 24 words");
|
|
12998
|
+
}
|
|
12999
|
+
if (options.keyType === "pq" && options.network !== "testnet") {
|
|
13000
|
+
throw new Error("PQ key type requires testnet");
|
|
13001
|
+
}
|
|
13002
|
+
// 60 s on-device approval window + margin.
|
|
13003
|
+
const response = await this.serial.sendCommand({
|
|
13004
|
+
action: "setup_seed",
|
|
13005
|
+
mnemonic: words.join(" "),
|
|
13006
|
+
network: options.network,
|
|
13007
|
+
key_type: options.keyType,
|
|
13008
|
+
}, 70000);
|
|
13009
|
+
this.assertSuccess(response);
|
|
13010
|
+
return response;
|
|
13011
|
+
}
|
|
13012
|
+
/**
|
|
13013
|
+
* Poll {@link getDeviceState} until the device reports `ready` — i.e. the
|
|
13014
|
+
* owner finished creating the PIN after {@link setupSeed} (or unlocked the
|
|
13015
|
+
* device) and the keys are derived. Resolves with the final state; throws on
|
|
13016
|
+
* timeout.
|
|
13017
|
+
*/
|
|
13018
|
+
async waitUntilReady(options) {
|
|
13019
|
+
const pollMs = options?.pollMs ?? 2000;
|
|
13020
|
+
const timeoutMs = options?.timeoutMs ?? 300000;
|
|
13021
|
+
const start = Date.now();
|
|
13022
|
+
for (;;) {
|
|
13023
|
+
const state = await this.getDeviceState();
|
|
13024
|
+
if (state === "ready")
|
|
13025
|
+
return state;
|
|
13026
|
+
if (Date.now() - start > timeoutMs) {
|
|
13027
|
+
throw new Error(`Timed out waiting for device (last state: ${state})`);
|
|
13028
|
+
}
|
|
13029
|
+
await new Promise((resolve) => setTimeout(resolve, pollMs));
|
|
13030
|
+
}
|
|
13031
|
+
}
|
|
12953
13032
|
/**
|
|
12954
13033
|
* Read the device's wallet info (network, key_type, master fingerprint, address,
|
|
12955
13034
|
* pubkey). As of the consent-model firmware this REQUIRES on-device approval and
|
|
@@ -13006,6 +13085,94 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
13006
13085
|
this.assertSuccess(response);
|
|
13007
13086
|
return response;
|
|
13008
13087
|
}
|
|
13088
|
+
// ─── DePIN chat identity (hw-depin-protocol) ───────────────────────────────
|
|
13089
|
+
// The device holds a dedicated DePIN chat identity (BIP44 account 100') so a
|
|
13090
|
+
// wallet can chat over DePIN without ever exposing its mnemonic. All calls
|
|
13091
|
+
// below require the device unlocked (PIN entered on-device) and, except the
|
|
13092
|
+
// session opener, an active session. Feature-detect with `ping().capabilities`
|
|
13093
|
+
// ("depin_identity" for identity+session, "depin_message" for sign/decrypt).
|
|
13094
|
+
/**
|
|
13095
|
+
* Open a DePIN chat session on a channel token. Prompts the owner for ONE
|
|
13096
|
+
* physical approval; while active the device reveals its DePIN identity and
|
|
13097
|
+
* auto-signs/decrypts on that channel without a per-message prompt, bounded by
|
|
13098
|
+
* an idle timeout, a hard cap, and a per-minute rate limit. The session is
|
|
13099
|
+
* revoked on timeout, device lock, or USB disconnect.
|
|
13100
|
+
*
|
|
13101
|
+
* @param token Channel token (soulbound `&…` asset name) to scope the session.
|
|
13102
|
+
* @param options `ttlMinutes` idle window (1–60, default 15); `ratePerMin`
|
|
13103
|
+
* in-session sign/decrypt cap (default 100).
|
|
13104
|
+
*/
|
|
13105
|
+
async depinSessionBegin(token, options) {
|
|
13106
|
+
const command = {
|
|
13107
|
+
action: "depin_session_begin",
|
|
13108
|
+
token,
|
|
13109
|
+
};
|
|
13110
|
+
if (options?.ttlMinutes !== undefined)
|
|
13111
|
+
command.ttl_minutes = options.ttlMinutes;
|
|
13112
|
+
if (options?.ratePerMin !== undefined)
|
|
13113
|
+
command.rate_per_min = options.ratePerMin;
|
|
13114
|
+
// Waits on a physical approval (up to ~30 s), like getInfo/getAddress.
|
|
13115
|
+
const response = await this.serial.sendCommand(command, 35000);
|
|
13116
|
+
this.assertSuccess(response);
|
|
13117
|
+
return response;
|
|
13118
|
+
}
|
|
13119
|
+
/**
|
|
13120
|
+
* Read the device's DePIN chat identity (address + compressed pubkey + BIP44
|
|
13121
|
+
* path). Requires an active session; no per-call prompt. This is the fix for
|
|
13122
|
+
* the hardware-wallet DePIN spinner: instead of deriving the identity from a
|
|
13123
|
+
* mnemonic the device doesn't expose, the wallet obtains it from the device.
|
|
13124
|
+
*/
|
|
13125
|
+
async getDepinIdentity() {
|
|
13126
|
+
const response = await this.serial.sendCommand({ action: "get_depin_identity" }, 10000);
|
|
13127
|
+
this.assertSuccess(response);
|
|
13128
|
+
return response;
|
|
13129
|
+
}
|
|
13130
|
+
/**
|
|
13131
|
+
* Sign a DePIN chat message on the device. The host performs the recipient
|
|
13132
|
+
* public-key ECIES encryption and passes the resulting fields; the device
|
|
13133
|
+
* assembles the canonical CDepinMessage preimage and returns the DER
|
|
13134
|
+
* signature. `sender` MUST equal the device's DePIN address and `token` the
|
|
13135
|
+
* active session channel (the device rejects otherwise). Requires an active
|
|
13136
|
+
* session and the `depin_message` capability.
|
|
13137
|
+
*
|
|
13138
|
+
* @param params.messageType 1 = direct (DATA), 2 = group (BROADCAST).
|
|
13139
|
+
* @param params.encryptedPayload Hex ECIES payload built host-side.
|
|
13140
|
+
*/
|
|
13141
|
+
async depinSign(params) {
|
|
13142
|
+
const response = await this.serial.sendCommand({
|
|
13143
|
+
action: "depin_sign",
|
|
13144
|
+
token: params.token,
|
|
13145
|
+
sender: params.sender,
|
|
13146
|
+
timestamp: params.timestamp,
|
|
13147
|
+
message_type: params.messageType,
|
|
13148
|
+
encrypted_payload: params.encryptedPayload,
|
|
13149
|
+
}, 35000);
|
|
13150
|
+
this.assertSuccess(response);
|
|
13151
|
+
return response;
|
|
13152
|
+
}
|
|
13153
|
+
/**
|
|
13154
|
+
* Decrypt a full serialized CDepinMessage addressed to this device, returning
|
|
13155
|
+
* the plaintext base64-encoded. GCM-authenticated; the sender's signature is
|
|
13156
|
+
* verified host-side (it needs the sender's on-chain pubkey). Returns a
|
|
13157
|
+
* `not_for_us` device error if this identity is not among the recipients.
|
|
13158
|
+
* Requires an active session and the `depin_message` capability.
|
|
13159
|
+
*
|
|
13160
|
+
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13161
|
+
*/
|
|
13162
|
+
async depinDecrypt(depinMessageHex) {
|
|
13163
|
+
const response = await this.serial.sendCommand({ action: "depin_decrypt", depin_message: depinMessageHex }, 35000);
|
|
13164
|
+
this.assertSuccess(response);
|
|
13165
|
+
return response;
|
|
13166
|
+
}
|
|
13167
|
+
/**
|
|
13168
|
+
* End the current DePIN session: auto-sign/decrypt stops and the identity is
|
|
13169
|
+
* no longer revealed until a new {@link depinSessionBegin} approval. Safe to
|
|
13170
|
+
* call with no active session.
|
|
13171
|
+
*/
|
|
13172
|
+
async depinSessionEnd() {
|
|
13173
|
+
const response = await this.serial.sendCommand({ action: "depin_session_end" }, 10000);
|
|
13174
|
+
this.assertSuccess(response);
|
|
13175
|
+
}
|
|
13009
13176
|
async signPsbt(psbtBase64, display) {
|
|
13010
13177
|
const response = await this.serial.sendCommandFinal({
|
|
13011
13178
|
action: "sign_psbt",
|
package/dist/browser.js
CHANGED
|
@@ -12947,6 +12947,85 @@ class NeuraiESP32 {
|
|
|
12947
12947
|
this.assertSuccess(response);
|
|
12948
12948
|
return response;
|
|
12949
12949
|
}
|
|
12950
|
+
/**
|
|
12951
|
+
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
12952
|
+
* `ready` (keys derived, normal commands work), `locked` (encrypted seed
|
|
12953
|
+
* stored, PIN not entered yet — ask the user to unlock on the device) or
|
|
12954
|
+
* `unconfigured` (no seed stored — {@link setupSeed} or the on-device wizard
|
|
12955
|
+
* applies). Safe to poll; never prompts on the device.
|
|
12956
|
+
*
|
|
12957
|
+
* Firmware predating the security layer answers `ping` successfully in every
|
|
12958
|
+
* state, so it reports `ready`.
|
|
12959
|
+
*/
|
|
12960
|
+
async getDeviceState() {
|
|
12961
|
+
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12962
|
+
if (response.status !== "error") {
|
|
12963
|
+
return "ready";
|
|
12964
|
+
}
|
|
12965
|
+
const message = (response.message ?? "").toLowerCase();
|
|
12966
|
+
if (message.includes("locked"))
|
|
12967
|
+
return "locked";
|
|
12968
|
+
if (message.includes("not configured"))
|
|
12969
|
+
return "unconfigured";
|
|
12970
|
+
throw new Error(`Device error: ${response.message}`);
|
|
12971
|
+
}
|
|
12972
|
+
/**
|
|
12973
|
+
* Provision an UNCONFIGURED device with a host-held mnemonic (`setup_seed`).
|
|
12974
|
+
*
|
|
12975
|
+
* The firmware only accepts this while **no encrypted seed is stored** (first
|
|
12976
|
+
* boot, dev-fallback mode, or after a wipe + reboot); on a configured device
|
|
12977
|
+
* it errors without prompting. The owner must physically approve a summary on
|
|
12978
|
+
* the device (word count + network + key type — the words are NEVER shown)
|
|
12979
|
+
* within 60 s, and then creates the PIN **on the device**: the PIN never
|
|
12980
|
+
* travels over USB. The seed transits the host and the USB link in plaintext
|
|
12981
|
+
* by design (this host generated it) — on-device entry remains the more
|
|
12982
|
+
* private path.
|
|
12983
|
+
*
|
|
12984
|
+
* Resolves with `{ state: "pin_required" }` once the owner approves. The
|
|
12985
|
+
* protocol has no push events, so detect completion by polling — see
|
|
12986
|
+
* {@link waitUntilReady}. If the owner cancels the PIN entry afterwards, the
|
|
12987
|
+
* device stays unconfigured and `setupSeed` can simply be called again.
|
|
12988
|
+
*/
|
|
12989
|
+
async setupSeed(options) {
|
|
12990
|
+
// Client-side pre-checks for fast feedback; the device re-validates
|
|
12991
|
+
// everything (including the BIP39 checksum) authoritatively.
|
|
12992
|
+
const words = options.mnemonic.trim().split(/\s+/).filter(Boolean);
|
|
12993
|
+
if (words.length !== 12 && words.length !== 24) {
|
|
12994
|
+
throw new Error("Mnemonic must be 12 or 24 words");
|
|
12995
|
+
}
|
|
12996
|
+
if (options.keyType === "pq" && options.network !== "testnet") {
|
|
12997
|
+
throw new Error("PQ key type requires testnet");
|
|
12998
|
+
}
|
|
12999
|
+
// 60 s on-device approval window + margin.
|
|
13000
|
+
const response = await this.serial.sendCommand({
|
|
13001
|
+
action: "setup_seed",
|
|
13002
|
+
mnemonic: words.join(" "),
|
|
13003
|
+
network: options.network,
|
|
13004
|
+
key_type: options.keyType,
|
|
13005
|
+
}, 70000);
|
|
13006
|
+
this.assertSuccess(response);
|
|
13007
|
+
return response;
|
|
13008
|
+
}
|
|
13009
|
+
/**
|
|
13010
|
+
* Poll {@link getDeviceState} until the device reports `ready` — i.e. the
|
|
13011
|
+
* owner finished creating the PIN after {@link setupSeed} (or unlocked the
|
|
13012
|
+
* device) and the keys are derived. Resolves with the final state; throws on
|
|
13013
|
+
* timeout.
|
|
13014
|
+
*/
|
|
13015
|
+
async waitUntilReady(options) {
|
|
13016
|
+
const pollMs = options?.pollMs ?? 2000;
|
|
13017
|
+
const timeoutMs = options?.timeoutMs ?? 300000;
|
|
13018
|
+
const start = Date.now();
|
|
13019
|
+
for (;;) {
|
|
13020
|
+
const state = await this.getDeviceState();
|
|
13021
|
+
if (state === "ready")
|
|
13022
|
+
return state;
|
|
13023
|
+
if (Date.now() - start > timeoutMs) {
|
|
13024
|
+
throw new Error(`Timed out waiting for device (last state: ${state})`);
|
|
13025
|
+
}
|
|
13026
|
+
await new Promise((resolve) => setTimeout(resolve, pollMs));
|
|
13027
|
+
}
|
|
13028
|
+
}
|
|
12950
13029
|
/**
|
|
12951
13030
|
* Read the device's wallet info (network, key_type, master fingerprint, address,
|
|
12952
13031
|
* pubkey). As of the consent-model firmware this REQUIRES on-device approval and
|
|
@@ -13003,6 +13082,94 @@ class NeuraiESP32 {
|
|
|
13003
13082
|
this.assertSuccess(response);
|
|
13004
13083
|
return response;
|
|
13005
13084
|
}
|
|
13085
|
+
// ─── DePIN chat identity (hw-depin-protocol) ───────────────────────────────
|
|
13086
|
+
// The device holds a dedicated DePIN chat identity (BIP44 account 100') so a
|
|
13087
|
+
// wallet can chat over DePIN without ever exposing its mnemonic. All calls
|
|
13088
|
+
// below require the device unlocked (PIN entered on-device) and, except the
|
|
13089
|
+
// session opener, an active session. Feature-detect with `ping().capabilities`
|
|
13090
|
+
// ("depin_identity" for identity+session, "depin_message" for sign/decrypt).
|
|
13091
|
+
/**
|
|
13092
|
+
* Open a DePIN chat session on a channel token. Prompts the owner for ONE
|
|
13093
|
+
* physical approval; while active the device reveals its DePIN identity and
|
|
13094
|
+
* auto-signs/decrypts on that channel without a per-message prompt, bounded by
|
|
13095
|
+
* an idle timeout, a hard cap, and a per-minute rate limit. The session is
|
|
13096
|
+
* revoked on timeout, device lock, or USB disconnect.
|
|
13097
|
+
*
|
|
13098
|
+
* @param token Channel token (soulbound `&…` asset name) to scope the session.
|
|
13099
|
+
* @param options `ttlMinutes` idle window (1–60, default 15); `ratePerMin`
|
|
13100
|
+
* in-session sign/decrypt cap (default 100).
|
|
13101
|
+
*/
|
|
13102
|
+
async depinSessionBegin(token, options) {
|
|
13103
|
+
const command = {
|
|
13104
|
+
action: "depin_session_begin",
|
|
13105
|
+
token,
|
|
13106
|
+
};
|
|
13107
|
+
if (options?.ttlMinutes !== undefined)
|
|
13108
|
+
command.ttl_minutes = options.ttlMinutes;
|
|
13109
|
+
if (options?.ratePerMin !== undefined)
|
|
13110
|
+
command.rate_per_min = options.ratePerMin;
|
|
13111
|
+
// Waits on a physical approval (up to ~30 s), like getInfo/getAddress.
|
|
13112
|
+
const response = await this.serial.sendCommand(command, 35000);
|
|
13113
|
+
this.assertSuccess(response);
|
|
13114
|
+
return response;
|
|
13115
|
+
}
|
|
13116
|
+
/**
|
|
13117
|
+
* Read the device's DePIN chat identity (address + compressed pubkey + BIP44
|
|
13118
|
+
* path). Requires an active session; no per-call prompt. This is the fix for
|
|
13119
|
+
* the hardware-wallet DePIN spinner: instead of deriving the identity from a
|
|
13120
|
+
* mnemonic the device doesn't expose, the wallet obtains it from the device.
|
|
13121
|
+
*/
|
|
13122
|
+
async getDepinIdentity() {
|
|
13123
|
+
const response = await this.serial.sendCommand({ action: "get_depin_identity" }, 10000);
|
|
13124
|
+
this.assertSuccess(response);
|
|
13125
|
+
return response;
|
|
13126
|
+
}
|
|
13127
|
+
/**
|
|
13128
|
+
* Sign a DePIN chat message on the device. The host performs the recipient
|
|
13129
|
+
* public-key ECIES encryption and passes the resulting fields; the device
|
|
13130
|
+
* assembles the canonical CDepinMessage preimage and returns the DER
|
|
13131
|
+
* signature. `sender` MUST equal the device's DePIN address and `token` the
|
|
13132
|
+
* active session channel (the device rejects otherwise). Requires an active
|
|
13133
|
+
* session and the `depin_message` capability.
|
|
13134
|
+
*
|
|
13135
|
+
* @param params.messageType 1 = direct (DATA), 2 = group (BROADCAST).
|
|
13136
|
+
* @param params.encryptedPayload Hex ECIES payload built host-side.
|
|
13137
|
+
*/
|
|
13138
|
+
async depinSign(params) {
|
|
13139
|
+
const response = await this.serial.sendCommand({
|
|
13140
|
+
action: "depin_sign",
|
|
13141
|
+
token: params.token,
|
|
13142
|
+
sender: params.sender,
|
|
13143
|
+
timestamp: params.timestamp,
|
|
13144
|
+
message_type: params.messageType,
|
|
13145
|
+
encrypted_payload: params.encryptedPayload,
|
|
13146
|
+
}, 35000);
|
|
13147
|
+
this.assertSuccess(response);
|
|
13148
|
+
return response;
|
|
13149
|
+
}
|
|
13150
|
+
/**
|
|
13151
|
+
* Decrypt a full serialized CDepinMessage addressed to this device, returning
|
|
13152
|
+
* the plaintext base64-encoded. GCM-authenticated; the sender's signature is
|
|
13153
|
+
* verified host-side (it needs the sender's on-chain pubkey). Returns a
|
|
13154
|
+
* `not_for_us` device error if this identity is not among the recipients.
|
|
13155
|
+
* Requires an active session and the `depin_message` capability.
|
|
13156
|
+
*
|
|
13157
|
+
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13158
|
+
*/
|
|
13159
|
+
async depinDecrypt(depinMessageHex) {
|
|
13160
|
+
const response = await this.serial.sendCommand({ action: "depin_decrypt", depin_message: depinMessageHex }, 35000);
|
|
13161
|
+
this.assertSuccess(response);
|
|
13162
|
+
return response;
|
|
13163
|
+
}
|
|
13164
|
+
/**
|
|
13165
|
+
* End the current DePIN session: auto-sign/decrypt stops and the identity is
|
|
13166
|
+
* no longer revealed until a new {@link depinSessionBegin} approval. Safe to
|
|
13167
|
+
* call with no active session.
|
|
13168
|
+
*/
|
|
13169
|
+
async depinSessionEnd() {
|
|
13170
|
+
const response = await this.serial.sendCommand({ action: "depin_session_end" }, 10000);
|
|
13171
|
+
this.assertSuccess(response);
|
|
13172
|
+
}
|
|
13006
13173
|
async signPsbt(psbtBase64, display) {
|
|
13007
13174
|
const response = await this.serial.sendCommandFinal({
|
|
13008
13175
|
action: "sign_psbt",
|