@neuraiproject/neurai-sign-esp32 0.5.9 → 0.5.11
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 +13 -2
- package/dist/NeuraiSignESP32.global.js +80 -3
- package/dist/browser.js +80 -3
- package/dist/index.cjs +80 -3
- package/dist/index.d.ts +48 -1
- package/dist/index.js +80 -3
- package/dist/react-native.d.ts +48 -1
- package/dist/react-native.js +80 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -211,6 +211,10 @@ decryption happen **on the chip**.
|
|
|
211
211
|
|
|
212
212
|
Feature-detect first — `ping()` advertises `capabilities`: `"depin_identity"`
|
|
213
213
|
(identity + session) and `"depin_message"` (on-device `depinSign`/`depinDecrypt`).
|
|
214
|
+
Firmware 0.5.11 also advertises `"depin_bulk_decrypt_b64"` and
|
|
215
|
+
`depin_max_decrypt_bytes` (currently 32768). This library negotiates those
|
|
216
|
+
automatically on the first decrypt: it preserves the public hex API, but sends
|
|
217
|
+
valid inputs in Base64 when supported, avoiding hex's 2× serial expansion.
|
|
214
218
|
|
|
215
219
|
```javascript
|
|
216
220
|
const { capabilities = [] } = await device.ping();
|
|
@@ -245,6 +249,11 @@ const { signature, op_count } = await device.depinSign({
|
|
|
245
249
|
// GCM-authenticated; the sender's signature is verified host-side.
|
|
246
250
|
const { plaintext_b64 } = await device.depinDecrypt(cdepinMessageHex);
|
|
247
251
|
|
|
252
|
+
// For a privacy-wrapped server response { encrypted: "<hex>" }, decrypt the
|
|
253
|
+
// bare ECIES payload. Oversize payloads are rejected locally with a clear
|
|
254
|
+
// error; paginate the server response instead of risking a device reset.
|
|
255
|
+
const result = await device.depinDecryptPayload(encryptedPayloadHex);
|
|
256
|
+
|
|
248
257
|
// 5) End the session when done (also revoked on lock / USB disconnect / timeout).
|
|
249
258
|
await device.depinSessionEnd();
|
|
250
259
|
```
|
|
@@ -579,6 +588,7 @@ using JSON messages. Supported commands:
|
|
|
579
588
|
| `sign_message` | Physical button | 30s |
|
|
580
589
|
| `depin_session_begin` | Physical button (channel token on screen) | 30s |
|
|
581
590
|
| `get_depin_identity` | None (session-gated) | 10s |
|
|
591
|
+
| `depin_sign_digest` | Physical button | 30s |
|
|
582
592
|
| `depin_sign` | None (session-gated, rate-limited) | 30s |
|
|
583
593
|
| `depin_decrypt` | None (session-gated, rate-limited) | 30s |
|
|
584
594
|
| `depin_decrypt_payload` | None (session-gated, rate-limited) | 30s |
|
|
@@ -616,8 +626,9 @@ Main class for device interaction.
|
|
|
616
626
|
| `depinSessionBegin(token, opts?)` | Open a DePIN chat session on a channel token (one approval); enables identity read + auto sign/decrypt |
|
|
617
627
|
| `getDepinIdentity()` | Read the DePIN chat identity (address + pubkey + path); session-gated, no per-call prompt |
|
|
618
628
|
| `depinSign(params)` | Sign a DePIN message on-device (DER over the canonical CDepinMessage); session-gated, rate-limited |
|
|
619
|
-
| `depinDecrypt(depinMessageHex)` | Decrypt a CDepinMessage addressed to this identity → `plaintext_b64`; session-gated |
|
|
620
|
-
| `depinDecryptPayload(encryptedPayloadHex)` | Decrypt a bare ECIES `encrypted_payload_hex` (decomposed server item) → `plaintext_b64`; session-gated |
|
|
629
|
+
| `depinDecrypt(depinMessageHex)` | Decrypt a CDepinMessage addressed to this identity → `plaintext_b64`; session-gated. Uses Base64 automatically on firmware 0.5.11+ |
|
|
630
|
+
| `depinDecryptPayload(encryptedPayloadHex)` | Decrypt a bare ECIES `encrypted_payload_hex` (decomposed server item) → `plaintext_b64`; session-gated. Uses Base64 automatically on firmware 0.5.11+ and rejects data above its announced limit |
|
|
631
|
+
| `depinSignDigest(digestHex)` | Sign a tx sighash with the DePIN key (account 100') → `{ signature, pubkey }`; physical confirmation, for the pubkey-reveal burn |
|
|
621
632
|
| `depinSessionEnd()` | End the DePIN session (also revoked on lock / disconnect / timeout) |
|
|
622
633
|
| `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
|
|
623
634
|
| `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |
|
|
@@ -12916,6 +12916,8 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
12916
12916
|
*/
|
|
12917
12917
|
constructor(options) {
|
|
12918
12918
|
this.deviceInfo = null;
|
|
12919
|
+
this.pingInfo = null;
|
|
12920
|
+
this.depinCapabilityHandshake = null;
|
|
12919
12921
|
this.serial = options?.transport ?? new SerialConnection(options);
|
|
12920
12922
|
}
|
|
12921
12923
|
static isSupported() {
|
|
@@ -12932,6 +12934,8 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
12932
12934
|
}
|
|
12933
12935
|
async disconnect() {
|
|
12934
12936
|
this.deviceInfo = null;
|
|
12937
|
+
this.pingInfo = null;
|
|
12938
|
+
this.depinCapabilityHandshake = null;
|
|
12935
12939
|
await this.serial.close();
|
|
12936
12940
|
}
|
|
12937
12941
|
/**
|
|
@@ -12948,7 +12952,8 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
12948
12952
|
// `ping` replies instantly (no user approval), so a short timeout is enough.
|
|
12949
12953
|
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12950
12954
|
this.assertSuccess(response);
|
|
12951
|
-
|
|
12955
|
+
this.pingInfo = response;
|
|
12956
|
+
return this.pingInfo;
|
|
12952
12957
|
}
|
|
12953
12958
|
/**
|
|
12954
12959
|
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
@@ -13157,10 +13162,17 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
13157
13162
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
13158
13163
|
* Requires an active session and the `depin_message` capability.
|
|
13159
13164
|
*
|
|
13165
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
13166
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
13167
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
13168
|
+
*
|
|
13160
13169
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13161
13170
|
*/
|
|
13162
13171
|
async depinDecrypt(depinMessageHex) {
|
|
13163
|
-
const response = await this.serial.sendCommand({
|
|
13172
|
+
const response = await this.serial.sendCommand({
|
|
13173
|
+
action: "depin_decrypt",
|
|
13174
|
+
...(await this.depinDecryptWirePayload("depin_message", "depin_message_b64", depinMessageHex)),
|
|
13175
|
+
}, 35000);
|
|
13164
13176
|
this.assertSuccess(response);
|
|
13165
13177
|
return response;
|
|
13166
13178
|
}
|
|
@@ -13172,9 +13184,74 @@ var NeuraiSignESP32Bundle = (function () {
|
|
|
13172
13184
|
* message (the common case for a chat client). Returns the plaintext
|
|
13173
13185
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
13174
13186
|
* Requires an active session and the `depin_message` capability.
|
|
13187
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
13188
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
13175
13189
|
*/
|
|
13176
13190
|
async depinDecryptPayload(encryptedPayloadHex) {
|
|
13177
|
-
const response = await this.serial.sendCommand({
|
|
13191
|
+
const response = await this.serial.sendCommand({
|
|
13192
|
+
action: "depin_decrypt_payload",
|
|
13193
|
+
...(await this.depinDecryptWirePayload("encrypted_payload", "encrypted_payload_b64", encryptedPayloadHex)),
|
|
13194
|
+
}, 35000);
|
|
13195
|
+
this.assertSuccess(response);
|
|
13196
|
+
return response;
|
|
13197
|
+
}
|
|
13198
|
+
/**
|
|
13199
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
13200
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
13201
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
13202
|
+
*/
|
|
13203
|
+
async getDepinBulkCapability() {
|
|
13204
|
+
if (this.pingInfo)
|
|
13205
|
+
return this.pingInfo;
|
|
13206
|
+
if (!this.depinCapabilityHandshake) {
|
|
13207
|
+
this.depinCapabilityHandshake = this.ping().catch(() => null);
|
|
13208
|
+
}
|
|
13209
|
+
return this.depinCapabilityHandshake;
|
|
13210
|
+
}
|
|
13211
|
+
/**
|
|
13212
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
13213
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
13214
|
+
* error instead of a new client-side parsing error.
|
|
13215
|
+
*/
|
|
13216
|
+
async depinDecryptWirePayload(hexField, base64Field, hexPayload) {
|
|
13217
|
+
const capability = await this.getDepinBulkCapability();
|
|
13218
|
+
const maxBytes = capability?.depin_max_decrypt_bytes;
|
|
13219
|
+
const supportsBase64 = capability?.capabilities?.includes("depin_bulk_decrypt_b64") === true &&
|
|
13220
|
+
Number.isSafeInteger(maxBytes) &&
|
|
13221
|
+
maxBytes > 0;
|
|
13222
|
+
// Preserve the legacy firmware validation path for malformed hex.
|
|
13223
|
+
if (!/^[0-9a-fA-F]*$/.test(hexPayload) || hexPayload.length % 2 !== 0) {
|
|
13224
|
+
return { [hexField]: hexPayload };
|
|
13225
|
+
}
|
|
13226
|
+
const bytes = bufferExports.Buffer.from(hexPayload, "hex");
|
|
13227
|
+
if (supportsBase64) {
|
|
13228
|
+
if (bytes.length > maxBytes) {
|
|
13229
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes; this device accepts at most ${maxBytes} bytes. Paginate the response before decrypting it.`);
|
|
13230
|
+
}
|
|
13231
|
+
return { [base64Field]: bytes.toString("base64") };
|
|
13232
|
+
}
|
|
13233
|
+
// A 48 KiB serial line leaves roughly 24 KiB for hex before JSON framing.
|
|
13234
|
+
// Do not send a known-unsafe legacy request that could destabilize a device.
|
|
13235
|
+
const legacyMaxBytes = 24 * 1024 - 256;
|
|
13236
|
+
if (bytes.length > legacyMaxBytes) {
|
|
13237
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes and exceeds the ${legacyMaxBytes}-byte legacy hex transport limit. Update the firmware or paginate the response.`);
|
|
13238
|
+
}
|
|
13239
|
+
return { [hexField]: hexPayload };
|
|
13240
|
+
}
|
|
13241
|
+
/**
|
|
13242
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
13243
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
13244
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
13245
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
13246
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
13247
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
13248
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
13249
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
13250
|
+
*
|
|
13251
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
13252
|
+
*/
|
|
13253
|
+
async depinSignDigest(digestHex) {
|
|
13254
|
+
const response = await this.serial.sendCommand({ action: "depin_sign_digest", digest: digestHex }, 35000);
|
|
13178
13255
|
this.assertSuccess(response);
|
|
13179
13256
|
return response;
|
|
13180
13257
|
}
|
package/dist/browser.js
CHANGED
|
@@ -12913,6 +12913,8 @@ class NeuraiESP32 {
|
|
|
12913
12913
|
*/
|
|
12914
12914
|
constructor(options) {
|
|
12915
12915
|
this.deviceInfo = null;
|
|
12916
|
+
this.pingInfo = null;
|
|
12917
|
+
this.depinCapabilityHandshake = null;
|
|
12916
12918
|
this.serial = options?.transport ?? new SerialConnection(options);
|
|
12917
12919
|
}
|
|
12918
12920
|
static isSupported() {
|
|
@@ -12929,6 +12931,8 @@ class NeuraiESP32 {
|
|
|
12929
12931
|
}
|
|
12930
12932
|
async disconnect() {
|
|
12931
12933
|
this.deviceInfo = null;
|
|
12934
|
+
this.pingInfo = null;
|
|
12935
|
+
this.depinCapabilityHandshake = null;
|
|
12932
12936
|
await this.serial.close();
|
|
12933
12937
|
}
|
|
12934
12938
|
/**
|
|
@@ -12945,7 +12949,8 @@ class NeuraiESP32 {
|
|
|
12945
12949
|
// `ping` replies instantly (no user approval), so a short timeout is enough.
|
|
12946
12950
|
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12947
12951
|
this.assertSuccess(response);
|
|
12948
|
-
|
|
12952
|
+
this.pingInfo = response;
|
|
12953
|
+
return this.pingInfo;
|
|
12949
12954
|
}
|
|
12950
12955
|
/**
|
|
12951
12956
|
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
@@ -13154,10 +13159,17 @@ class NeuraiESP32 {
|
|
|
13154
13159
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
13155
13160
|
* Requires an active session and the `depin_message` capability.
|
|
13156
13161
|
*
|
|
13162
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
13163
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
13164
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
13165
|
+
*
|
|
13157
13166
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13158
13167
|
*/
|
|
13159
13168
|
async depinDecrypt(depinMessageHex) {
|
|
13160
|
-
const response = await this.serial.sendCommand({
|
|
13169
|
+
const response = await this.serial.sendCommand({
|
|
13170
|
+
action: "depin_decrypt",
|
|
13171
|
+
...(await this.depinDecryptWirePayload("depin_message", "depin_message_b64", depinMessageHex)),
|
|
13172
|
+
}, 35000);
|
|
13161
13173
|
this.assertSuccess(response);
|
|
13162
13174
|
return response;
|
|
13163
13175
|
}
|
|
@@ -13169,9 +13181,74 @@ class NeuraiESP32 {
|
|
|
13169
13181
|
* message (the common case for a chat client). Returns the plaintext
|
|
13170
13182
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
13171
13183
|
* Requires an active session and the `depin_message` capability.
|
|
13184
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
13185
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
13172
13186
|
*/
|
|
13173
13187
|
async depinDecryptPayload(encryptedPayloadHex) {
|
|
13174
|
-
const response = await this.serial.sendCommand({
|
|
13188
|
+
const response = await this.serial.sendCommand({
|
|
13189
|
+
action: "depin_decrypt_payload",
|
|
13190
|
+
...(await this.depinDecryptWirePayload("encrypted_payload", "encrypted_payload_b64", encryptedPayloadHex)),
|
|
13191
|
+
}, 35000);
|
|
13192
|
+
this.assertSuccess(response);
|
|
13193
|
+
return response;
|
|
13194
|
+
}
|
|
13195
|
+
/**
|
|
13196
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
13197
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
13198
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
13199
|
+
*/
|
|
13200
|
+
async getDepinBulkCapability() {
|
|
13201
|
+
if (this.pingInfo)
|
|
13202
|
+
return this.pingInfo;
|
|
13203
|
+
if (!this.depinCapabilityHandshake) {
|
|
13204
|
+
this.depinCapabilityHandshake = this.ping().catch(() => null);
|
|
13205
|
+
}
|
|
13206
|
+
return this.depinCapabilityHandshake;
|
|
13207
|
+
}
|
|
13208
|
+
/**
|
|
13209
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
13210
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
13211
|
+
* error instead of a new client-side parsing error.
|
|
13212
|
+
*/
|
|
13213
|
+
async depinDecryptWirePayload(hexField, base64Field, hexPayload) {
|
|
13214
|
+
const capability = await this.getDepinBulkCapability();
|
|
13215
|
+
const maxBytes = capability?.depin_max_decrypt_bytes;
|
|
13216
|
+
const supportsBase64 = capability?.capabilities?.includes("depin_bulk_decrypt_b64") === true &&
|
|
13217
|
+
Number.isSafeInteger(maxBytes) &&
|
|
13218
|
+
maxBytes > 0;
|
|
13219
|
+
// Preserve the legacy firmware validation path for malformed hex.
|
|
13220
|
+
if (!/^[0-9a-fA-F]*$/.test(hexPayload) || hexPayload.length % 2 !== 0) {
|
|
13221
|
+
return { [hexField]: hexPayload };
|
|
13222
|
+
}
|
|
13223
|
+
const bytes = bufferExports.Buffer.from(hexPayload, "hex");
|
|
13224
|
+
if (supportsBase64) {
|
|
13225
|
+
if (bytes.length > maxBytes) {
|
|
13226
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes; this device accepts at most ${maxBytes} bytes. Paginate the response before decrypting it.`);
|
|
13227
|
+
}
|
|
13228
|
+
return { [base64Field]: bytes.toString("base64") };
|
|
13229
|
+
}
|
|
13230
|
+
// A 48 KiB serial line leaves roughly 24 KiB for hex before JSON framing.
|
|
13231
|
+
// Do not send a known-unsafe legacy request that could destabilize a device.
|
|
13232
|
+
const legacyMaxBytes = 24 * 1024 - 256;
|
|
13233
|
+
if (bytes.length > legacyMaxBytes) {
|
|
13234
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes and exceeds the ${legacyMaxBytes}-byte legacy hex transport limit. Update the firmware or paginate the response.`);
|
|
13235
|
+
}
|
|
13236
|
+
return { [hexField]: hexPayload };
|
|
13237
|
+
}
|
|
13238
|
+
/**
|
|
13239
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
13240
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
13241
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
13242
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
13243
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
13244
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
13245
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
13246
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
13247
|
+
*
|
|
13248
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
13249
|
+
*/
|
|
13250
|
+
async depinSignDigest(digestHex) {
|
|
13251
|
+
const response = await this.serial.sendCommand({ action: "depin_sign_digest", digest: digestHex }, 35000);
|
|
13175
13252
|
this.assertSuccess(response);
|
|
13176
13253
|
return response;
|
|
13177
13254
|
}
|
package/dist/index.cjs
CHANGED
|
@@ -12915,6 +12915,8 @@ class NeuraiESP32 {
|
|
|
12915
12915
|
*/
|
|
12916
12916
|
constructor(options) {
|
|
12917
12917
|
this.deviceInfo = null;
|
|
12918
|
+
this.pingInfo = null;
|
|
12919
|
+
this.depinCapabilityHandshake = null;
|
|
12918
12920
|
this.serial = options?.transport ?? new SerialConnection(options);
|
|
12919
12921
|
}
|
|
12920
12922
|
static isSupported() {
|
|
@@ -12931,6 +12933,8 @@ class NeuraiESP32 {
|
|
|
12931
12933
|
}
|
|
12932
12934
|
async disconnect() {
|
|
12933
12935
|
this.deviceInfo = null;
|
|
12936
|
+
this.pingInfo = null;
|
|
12937
|
+
this.depinCapabilityHandshake = null;
|
|
12934
12938
|
await this.serial.close();
|
|
12935
12939
|
}
|
|
12936
12940
|
/**
|
|
@@ -12947,7 +12951,8 @@ class NeuraiESP32 {
|
|
|
12947
12951
|
// `ping` replies instantly (no user approval), so a short timeout is enough.
|
|
12948
12952
|
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12949
12953
|
this.assertSuccess(response);
|
|
12950
|
-
|
|
12954
|
+
this.pingInfo = response;
|
|
12955
|
+
return this.pingInfo;
|
|
12951
12956
|
}
|
|
12952
12957
|
/**
|
|
12953
12958
|
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
@@ -13156,10 +13161,17 @@ class NeuraiESP32 {
|
|
|
13156
13161
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
13157
13162
|
* Requires an active session and the `depin_message` capability.
|
|
13158
13163
|
*
|
|
13164
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
13165
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
13166
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
13167
|
+
*
|
|
13159
13168
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13160
13169
|
*/
|
|
13161
13170
|
async depinDecrypt(depinMessageHex) {
|
|
13162
|
-
const response = await this.serial.sendCommand({
|
|
13171
|
+
const response = await this.serial.sendCommand({
|
|
13172
|
+
action: "depin_decrypt",
|
|
13173
|
+
...(await this.depinDecryptWirePayload("depin_message", "depin_message_b64", depinMessageHex)),
|
|
13174
|
+
}, 35000);
|
|
13163
13175
|
this.assertSuccess(response);
|
|
13164
13176
|
return response;
|
|
13165
13177
|
}
|
|
@@ -13171,9 +13183,74 @@ class NeuraiESP32 {
|
|
|
13171
13183
|
* message (the common case for a chat client). Returns the plaintext
|
|
13172
13184
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
13173
13185
|
* Requires an active session and the `depin_message` capability.
|
|
13186
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
13187
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
13174
13188
|
*/
|
|
13175
13189
|
async depinDecryptPayload(encryptedPayloadHex) {
|
|
13176
|
-
const response = await this.serial.sendCommand({
|
|
13190
|
+
const response = await this.serial.sendCommand({
|
|
13191
|
+
action: "depin_decrypt_payload",
|
|
13192
|
+
...(await this.depinDecryptWirePayload("encrypted_payload", "encrypted_payload_b64", encryptedPayloadHex)),
|
|
13193
|
+
}, 35000);
|
|
13194
|
+
this.assertSuccess(response);
|
|
13195
|
+
return response;
|
|
13196
|
+
}
|
|
13197
|
+
/**
|
|
13198
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
13199
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
13200
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
13201
|
+
*/
|
|
13202
|
+
async getDepinBulkCapability() {
|
|
13203
|
+
if (this.pingInfo)
|
|
13204
|
+
return this.pingInfo;
|
|
13205
|
+
if (!this.depinCapabilityHandshake) {
|
|
13206
|
+
this.depinCapabilityHandshake = this.ping().catch(() => null);
|
|
13207
|
+
}
|
|
13208
|
+
return this.depinCapabilityHandshake;
|
|
13209
|
+
}
|
|
13210
|
+
/**
|
|
13211
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
13212
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
13213
|
+
* error instead of a new client-side parsing error.
|
|
13214
|
+
*/
|
|
13215
|
+
async depinDecryptWirePayload(hexField, base64Field, hexPayload) {
|
|
13216
|
+
const capability = await this.getDepinBulkCapability();
|
|
13217
|
+
const maxBytes = capability?.depin_max_decrypt_bytes;
|
|
13218
|
+
const supportsBase64 = capability?.capabilities?.includes("depin_bulk_decrypt_b64") === true &&
|
|
13219
|
+
Number.isSafeInteger(maxBytes) &&
|
|
13220
|
+
maxBytes > 0;
|
|
13221
|
+
// Preserve the legacy firmware validation path for malformed hex.
|
|
13222
|
+
if (!/^[0-9a-fA-F]*$/.test(hexPayload) || hexPayload.length % 2 !== 0) {
|
|
13223
|
+
return { [hexField]: hexPayload };
|
|
13224
|
+
}
|
|
13225
|
+
const bytes = bufferExports.Buffer.from(hexPayload, "hex");
|
|
13226
|
+
if (supportsBase64) {
|
|
13227
|
+
if (bytes.length > maxBytes) {
|
|
13228
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes; this device accepts at most ${maxBytes} bytes. Paginate the response before decrypting it.`);
|
|
13229
|
+
}
|
|
13230
|
+
return { [base64Field]: bytes.toString("base64") };
|
|
13231
|
+
}
|
|
13232
|
+
// A 48 KiB serial line leaves roughly 24 KiB for hex before JSON framing.
|
|
13233
|
+
// Do not send a known-unsafe legacy request that could destabilize a device.
|
|
13234
|
+
const legacyMaxBytes = 24 * 1024 - 256;
|
|
13235
|
+
if (bytes.length > legacyMaxBytes) {
|
|
13236
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes and exceeds the ${legacyMaxBytes}-byte legacy hex transport limit. Update the firmware or paginate the response.`);
|
|
13237
|
+
}
|
|
13238
|
+
return { [hexField]: hexPayload };
|
|
13239
|
+
}
|
|
13240
|
+
/**
|
|
13241
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
13242
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
13243
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
13244
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
13245
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
13246
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
13247
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
13248
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
13249
|
+
*
|
|
13250
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
13251
|
+
*/
|
|
13252
|
+
async depinSignDigest(digestHex) {
|
|
13253
|
+
const response = await this.serial.sendCommand({ action: "depin_sign_digest", digest: digestHex }, 35000);
|
|
13177
13254
|
this.assertSuccess(response);
|
|
13178
13255
|
return response;
|
|
13179
13256
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -108,6 +108,13 @@ interface IPingResponse {
|
|
|
108
108
|
* Absent on firmware predating capability negotiation.
|
|
109
109
|
*/
|
|
110
110
|
capabilities?: string[];
|
|
111
|
+
/**
|
|
112
|
+
* Maximum decoded byte length accepted by the firmware for a DePIN decrypt
|
|
113
|
+
* request. Present together with the `depin_bulk_decrypt_b64` capability.
|
|
114
|
+
* The library uses it before serializing a large payload, so an oversize
|
|
115
|
+
* request is rejected locally instead of risking an ESP32 reset.
|
|
116
|
+
*/
|
|
117
|
+
depin_max_decrypt_bytes?: number;
|
|
111
118
|
}
|
|
112
119
|
interface IDeviceInfo {
|
|
113
120
|
status: string;
|
|
@@ -255,6 +262,13 @@ interface IDepinDecryptResponse {
|
|
|
255
262
|
plaintext_b64: string;
|
|
256
263
|
op_count: number;
|
|
257
264
|
}
|
|
265
|
+
interface IDepinSignDigestResponse {
|
|
266
|
+
status: string;
|
|
267
|
+
/** DER signature over the digest (no sighash-type byte; append it host-side). */
|
|
268
|
+
signature: string;
|
|
269
|
+
/** Compressed secp256k1 DePIN public key (33 bytes), hex — for the scriptSig. */
|
|
270
|
+
pubkey: string;
|
|
271
|
+
}
|
|
258
272
|
interface IErrorResponse {
|
|
259
273
|
status: "error";
|
|
260
274
|
message: string;
|
|
@@ -263,7 +277,7 @@ interface IProcessingResponse {
|
|
|
263
277
|
status: "processing";
|
|
264
278
|
stage: string;
|
|
265
279
|
}
|
|
266
|
-
type DeviceResponse = IPingResponse | IDeviceInfo | IAddressResponse | IBip32PubkeyResponse | ISignPsbtResponse | ISignTxResponse | ISignMessageResponse | ISetupSeedResponse | IDepinSessionResponse | IDepinIdentityResponse | IDepinSignResponse | IDepinDecryptResponse | IErrorResponse | IProcessingResponse;
|
|
280
|
+
type DeviceResponse = IPingResponse | IDeviceInfo | IAddressResponse | IBip32PubkeyResponse | ISignPsbtResponse | ISignTxResponse | ISignMessageResponse | ISetupSeedResponse | IDepinSessionResponse | IDepinIdentityResponse | IDepinSignResponse | IDepinDecryptResponse | IDepinSignDigestResponse | IErrorResponse | IProcessingResponse;
|
|
267
281
|
/**
|
|
268
282
|
* Message-level transport consumed by {@link NeuraiESP32}. This is the only
|
|
269
283
|
* surface the device class depends on, so any platform (Web Serial, React
|
|
@@ -389,6 +403,8 @@ interface ISignTxResponse {
|
|
|
389
403
|
declare class NeuraiESP32 {
|
|
390
404
|
private serial;
|
|
391
405
|
private deviceInfo;
|
|
406
|
+
private pingInfo;
|
|
407
|
+
private depinCapabilityHandshake;
|
|
392
408
|
/**
|
|
393
409
|
* @param options Pass `{ transport }` to drive the device over a custom
|
|
394
410
|
* transport (e.g. React Native / Android USB). Without it, the default Web
|
|
@@ -517,6 +533,10 @@ declare class NeuraiESP32 {
|
|
|
517
533
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
518
534
|
* Requires an active session and the `depin_message` capability.
|
|
519
535
|
*
|
|
536
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
537
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
538
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
539
|
+
*
|
|
520
540
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
521
541
|
*/
|
|
522
542
|
depinDecrypt(depinMessageHex: string): Promise<IDepinDecryptResponse>;
|
|
@@ -528,8 +548,35 @@ declare class NeuraiESP32 {
|
|
|
528
548
|
* message (the common case for a chat client). Returns the plaintext
|
|
529
549
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
530
550
|
* Requires an active session and the `depin_message` capability.
|
|
551
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
552
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
531
553
|
*/
|
|
532
554
|
depinDecryptPayload(encryptedPayloadHex: string): Promise<IDepinDecryptResponse>;
|
|
555
|
+
/**
|
|
556
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
557
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
558
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
559
|
+
*/
|
|
560
|
+
private getDepinBulkCapability;
|
|
561
|
+
/**
|
|
562
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
563
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
564
|
+
* error instead of a new client-side parsing error.
|
|
565
|
+
*/
|
|
566
|
+
private depinDecryptWirePayload;
|
|
567
|
+
/**
|
|
568
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
569
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
570
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
571
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
572
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
573
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
574
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
575
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
576
|
+
*
|
|
577
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
578
|
+
*/
|
|
579
|
+
depinSignDigest(digestHex: string): Promise<IDepinSignDigestResponse>;
|
|
533
580
|
/**
|
|
534
581
|
* End the current DePIN session: auto-sign/decrypt stops and the identity is
|
|
535
582
|
* no longer revealed until a new {@link depinSessionBegin} approval. Safe to
|
package/dist/index.js
CHANGED
|
@@ -12913,6 +12913,8 @@ class NeuraiESP32 {
|
|
|
12913
12913
|
*/
|
|
12914
12914
|
constructor(options) {
|
|
12915
12915
|
this.deviceInfo = null;
|
|
12916
|
+
this.pingInfo = null;
|
|
12917
|
+
this.depinCapabilityHandshake = null;
|
|
12916
12918
|
this.serial = options?.transport ?? new SerialConnection(options);
|
|
12917
12919
|
}
|
|
12918
12920
|
static isSupported() {
|
|
@@ -12929,6 +12931,8 @@ class NeuraiESP32 {
|
|
|
12929
12931
|
}
|
|
12930
12932
|
async disconnect() {
|
|
12931
12933
|
this.deviceInfo = null;
|
|
12934
|
+
this.pingInfo = null;
|
|
12935
|
+
this.depinCapabilityHandshake = null;
|
|
12932
12936
|
await this.serial.close();
|
|
12933
12937
|
}
|
|
12934
12938
|
/**
|
|
@@ -12945,7 +12949,8 @@ class NeuraiESP32 {
|
|
|
12945
12949
|
// `ping` replies instantly (no user approval), so a short timeout is enough.
|
|
12946
12950
|
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12947
12951
|
this.assertSuccess(response);
|
|
12948
|
-
|
|
12952
|
+
this.pingInfo = response;
|
|
12953
|
+
return this.pingInfo;
|
|
12949
12954
|
}
|
|
12950
12955
|
/**
|
|
12951
12956
|
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
@@ -13154,10 +13159,17 @@ class NeuraiESP32 {
|
|
|
13154
13159
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
13155
13160
|
* Requires an active session and the `depin_message` capability.
|
|
13156
13161
|
*
|
|
13162
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
13163
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
13164
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
13165
|
+
*
|
|
13157
13166
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13158
13167
|
*/
|
|
13159
13168
|
async depinDecrypt(depinMessageHex) {
|
|
13160
|
-
const response = await this.serial.sendCommand({
|
|
13169
|
+
const response = await this.serial.sendCommand({
|
|
13170
|
+
action: "depin_decrypt",
|
|
13171
|
+
...(await this.depinDecryptWirePayload("depin_message", "depin_message_b64", depinMessageHex)),
|
|
13172
|
+
}, 35000);
|
|
13161
13173
|
this.assertSuccess(response);
|
|
13162
13174
|
return response;
|
|
13163
13175
|
}
|
|
@@ -13169,9 +13181,74 @@ class NeuraiESP32 {
|
|
|
13169
13181
|
* message (the common case for a chat client). Returns the plaintext
|
|
13170
13182
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
13171
13183
|
* Requires an active session and the `depin_message` capability.
|
|
13184
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
13185
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
13172
13186
|
*/
|
|
13173
13187
|
async depinDecryptPayload(encryptedPayloadHex) {
|
|
13174
|
-
const response = await this.serial.sendCommand({
|
|
13188
|
+
const response = await this.serial.sendCommand({
|
|
13189
|
+
action: "depin_decrypt_payload",
|
|
13190
|
+
...(await this.depinDecryptWirePayload("encrypted_payload", "encrypted_payload_b64", encryptedPayloadHex)),
|
|
13191
|
+
}, 35000);
|
|
13192
|
+
this.assertSuccess(response);
|
|
13193
|
+
return response;
|
|
13194
|
+
}
|
|
13195
|
+
/**
|
|
13196
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
13197
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
13198
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
13199
|
+
*/
|
|
13200
|
+
async getDepinBulkCapability() {
|
|
13201
|
+
if (this.pingInfo)
|
|
13202
|
+
return this.pingInfo;
|
|
13203
|
+
if (!this.depinCapabilityHandshake) {
|
|
13204
|
+
this.depinCapabilityHandshake = this.ping().catch(() => null);
|
|
13205
|
+
}
|
|
13206
|
+
return this.depinCapabilityHandshake;
|
|
13207
|
+
}
|
|
13208
|
+
/**
|
|
13209
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
13210
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
13211
|
+
* error instead of a new client-side parsing error.
|
|
13212
|
+
*/
|
|
13213
|
+
async depinDecryptWirePayload(hexField, base64Field, hexPayload) {
|
|
13214
|
+
const capability = await this.getDepinBulkCapability();
|
|
13215
|
+
const maxBytes = capability?.depin_max_decrypt_bytes;
|
|
13216
|
+
const supportsBase64 = capability?.capabilities?.includes("depin_bulk_decrypt_b64") === true &&
|
|
13217
|
+
Number.isSafeInteger(maxBytes) &&
|
|
13218
|
+
maxBytes > 0;
|
|
13219
|
+
// Preserve the legacy firmware validation path for malformed hex.
|
|
13220
|
+
if (!/^[0-9a-fA-F]*$/.test(hexPayload) || hexPayload.length % 2 !== 0) {
|
|
13221
|
+
return { [hexField]: hexPayload };
|
|
13222
|
+
}
|
|
13223
|
+
const bytes = bufferExports.Buffer.from(hexPayload, "hex");
|
|
13224
|
+
if (supportsBase64) {
|
|
13225
|
+
if (bytes.length > maxBytes) {
|
|
13226
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes; this device accepts at most ${maxBytes} bytes. Paginate the response before decrypting it.`);
|
|
13227
|
+
}
|
|
13228
|
+
return { [base64Field]: bytes.toString("base64") };
|
|
13229
|
+
}
|
|
13230
|
+
// A 48 KiB serial line leaves roughly 24 KiB for hex before JSON framing.
|
|
13231
|
+
// Do not send a known-unsafe legacy request that could destabilize a device.
|
|
13232
|
+
const legacyMaxBytes = 24 * 1024 - 256;
|
|
13233
|
+
if (bytes.length > legacyMaxBytes) {
|
|
13234
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes and exceeds the ${legacyMaxBytes}-byte legacy hex transport limit. Update the firmware or paginate the response.`);
|
|
13235
|
+
}
|
|
13236
|
+
return { [hexField]: hexPayload };
|
|
13237
|
+
}
|
|
13238
|
+
/**
|
|
13239
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
13240
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
13241
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
13242
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
13243
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
13244
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
13245
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
13246
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
13247
|
+
*
|
|
13248
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
13249
|
+
*/
|
|
13250
|
+
async depinSignDigest(digestHex) {
|
|
13251
|
+
const response = await this.serial.sendCommand({ action: "depin_sign_digest", digest: digestHex }, 35000);
|
|
13175
13252
|
this.assertSuccess(response);
|
|
13176
13253
|
return response;
|
|
13177
13254
|
}
|
package/dist/react-native.d.ts
CHANGED
|
@@ -108,6 +108,13 @@ interface IPingResponse {
|
|
|
108
108
|
* Absent on firmware predating capability negotiation.
|
|
109
109
|
*/
|
|
110
110
|
capabilities?: string[];
|
|
111
|
+
/**
|
|
112
|
+
* Maximum decoded byte length accepted by the firmware for a DePIN decrypt
|
|
113
|
+
* request. Present together with the `depin_bulk_decrypt_b64` capability.
|
|
114
|
+
* The library uses it before serializing a large payload, so an oversize
|
|
115
|
+
* request is rejected locally instead of risking an ESP32 reset.
|
|
116
|
+
*/
|
|
117
|
+
depin_max_decrypt_bytes?: number;
|
|
111
118
|
}
|
|
112
119
|
interface IDeviceInfo {
|
|
113
120
|
status: string;
|
|
@@ -255,6 +262,13 @@ interface IDepinDecryptResponse {
|
|
|
255
262
|
plaintext_b64: string;
|
|
256
263
|
op_count: number;
|
|
257
264
|
}
|
|
265
|
+
interface IDepinSignDigestResponse {
|
|
266
|
+
status: string;
|
|
267
|
+
/** DER signature over the digest (no sighash-type byte; append it host-side). */
|
|
268
|
+
signature: string;
|
|
269
|
+
/** Compressed secp256k1 DePIN public key (33 bytes), hex — for the scriptSig. */
|
|
270
|
+
pubkey: string;
|
|
271
|
+
}
|
|
258
272
|
interface IErrorResponse {
|
|
259
273
|
status: "error";
|
|
260
274
|
message: string;
|
|
@@ -263,7 +277,7 @@ interface IProcessingResponse {
|
|
|
263
277
|
status: "processing";
|
|
264
278
|
stage: string;
|
|
265
279
|
}
|
|
266
|
-
type DeviceResponse = IPingResponse | IDeviceInfo | IAddressResponse | IBip32PubkeyResponse | ISignPsbtResponse | ISignTxResponse | ISignMessageResponse | ISetupSeedResponse | IDepinSessionResponse | IDepinIdentityResponse | IDepinSignResponse | IDepinDecryptResponse | IErrorResponse | IProcessingResponse;
|
|
280
|
+
type DeviceResponse = IPingResponse | IDeviceInfo | IAddressResponse | IBip32PubkeyResponse | ISignPsbtResponse | ISignTxResponse | ISignMessageResponse | ISetupSeedResponse | IDepinSessionResponse | IDepinIdentityResponse | IDepinSignResponse | IDepinDecryptResponse | IDepinSignDigestResponse | IErrorResponse | IProcessingResponse;
|
|
267
281
|
/**
|
|
268
282
|
* Message-level transport consumed by {@link NeuraiESP32}. This is the only
|
|
269
283
|
* surface the device class depends on, so any platform (Web Serial, React
|
|
@@ -389,6 +403,8 @@ interface ISignTxResponse {
|
|
|
389
403
|
declare class NeuraiESP32 {
|
|
390
404
|
private serial;
|
|
391
405
|
private deviceInfo;
|
|
406
|
+
private pingInfo;
|
|
407
|
+
private depinCapabilityHandshake;
|
|
392
408
|
/**
|
|
393
409
|
* @param options Pass `{ transport }` to drive the device over a custom
|
|
394
410
|
* transport (e.g. React Native / Android USB). Without it, the default Web
|
|
@@ -517,6 +533,10 @@ declare class NeuraiESP32 {
|
|
|
517
533
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
518
534
|
* Requires an active session and the `depin_message` capability.
|
|
519
535
|
*
|
|
536
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
537
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
538
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
539
|
+
*
|
|
520
540
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
521
541
|
*/
|
|
522
542
|
depinDecrypt(depinMessageHex: string): Promise<IDepinDecryptResponse>;
|
|
@@ -528,8 +548,35 @@ declare class NeuraiESP32 {
|
|
|
528
548
|
* message (the common case for a chat client). Returns the plaintext
|
|
529
549
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
530
550
|
* Requires an active session and the `depin_message` capability.
|
|
551
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
552
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
531
553
|
*/
|
|
532
554
|
depinDecryptPayload(encryptedPayloadHex: string): Promise<IDepinDecryptResponse>;
|
|
555
|
+
/**
|
|
556
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
557
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
558
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
559
|
+
*/
|
|
560
|
+
private getDepinBulkCapability;
|
|
561
|
+
/**
|
|
562
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
563
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
564
|
+
* error instead of a new client-side parsing error.
|
|
565
|
+
*/
|
|
566
|
+
private depinDecryptWirePayload;
|
|
567
|
+
/**
|
|
568
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
569
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
570
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
571
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
572
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
573
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
574
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
575
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
576
|
+
*
|
|
577
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
578
|
+
*/
|
|
579
|
+
depinSignDigest(digestHex: string): Promise<IDepinSignDigestResponse>;
|
|
533
580
|
/**
|
|
534
581
|
* End the current DePIN session: auto-sign/decrypt stops and the identity is
|
|
535
582
|
* no longer revealed until a new {@link depinSessionBegin} approval. Safe to
|
package/dist/react-native.js
CHANGED
|
@@ -12913,6 +12913,8 @@ class NeuraiESP32 {
|
|
|
12913
12913
|
*/
|
|
12914
12914
|
constructor(options) {
|
|
12915
12915
|
this.deviceInfo = null;
|
|
12916
|
+
this.pingInfo = null;
|
|
12917
|
+
this.depinCapabilityHandshake = null;
|
|
12916
12918
|
this.serial = options?.transport ?? new SerialConnection(options);
|
|
12917
12919
|
}
|
|
12918
12920
|
static isSupported() {
|
|
@@ -12929,6 +12931,8 @@ class NeuraiESP32 {
|
|
|
12929
12931
|
}
|
|
12930
12932
|
async disconnect() {
|
|
12931
12933
|
this.deviceInfo = null;
|
|
12934
|
+
this.pingInfo = null;
|
|
12935
|
+
this.depinCapabilityHandshake = null;
|
|
12932
12936
|
await this.serial.close();
|
|
12933
12937
|
}
|
|
12934
12938
|
/**
|
|
@@ -12945,7 +12949,8 @@ class NeuraiESP32 {
|
|
|
12945
12949
|
// `ping` replies instantly (no user approval), so a short timeout is enough.
|
|
12946
12950
|
const response = await this.serial.sendCommand({ action: "ping" }, 5000);
|
|
12947
12951
|
this.assertSuccess(response);
|
|
12948
|
-
|
|
12952
|
+
this.pingInfo = response;
|
|
12953
|
+
return this.pingInfo;
|
|
12949
12954
|
}
|
|
12950
12955
|
/**
|
|
12951
12956
|
* Coarse device state, derived from `ping` and the firmware's gate errors:
|
|
@@ -13154,10 +13159,17 @@ class NeuraiESP32 {
|
|
|
13154
13159
|
* `not_for_us` device error if this identity is not among the recipients.
|
|
13155
13160
|
* Requires an active session and the `depin_message` capability.
|
|
13156
13161
|
*
|
|
13162
|
+
* The library negotiates `depin_bulk_decrypt_b64` on first use. On firmware
|
|
13163
|
+
* that advertises it, valid hex input is sent as Base64 to avoid hex's 2x
|
|
13164
|
+
* expansion; older firmware continues to receive the legacy hex field.
|
|
13165
|
+
*
|
|
13157
13166
|
* @param depinMessageHex Hex of the complete serialized CDepinMessage.
|
|
13158
13167
|
*/
|
|
13159
13168
|
async depinDecrypt(depinMessageHex) {
|
|
13160
|
-
const response = await this.serial.sendCommand({
|
|
13169
|
+
const response = await this.serial.sendCommand({
|
|
13170
|
+
action: "depin_decrypt",
|
|
13171
|
+
...(await this.depinDecryptWirePayload("depin_message", "depin_message_b64", depinMessageHex)),
|
|
13172
|
+
}, 35000);
|
|
13161
13173
|
this.assertSuccess(response);
|
|
13162
13174
|
return response;
|
|
13163
13175
|
}
|
|
@@ -13169,9 +13181,74 @@ class NeuraiESP32 {
|
|
|
13169
13181
|
* message (the common case for a chat client). Returns the plaintext
|
|
13170
13182
|
* base64-encoded, or a `not_for_us` device error if not a recipient.
|
|
13171
13183
|
* Requires an active session and the `depin_message` capability.
|
|
13184
|
+
* On firmware supporting `depin_bulk_decrypt_b64`, valid hex input is sent
|
|
13185
|
+
* in Base64 and checked against `depin_max_decrypt_bytes` before USB I/O.
|
|
13172
13186
|
*/
|
|
13173
13187
|
async depinDecryptPayload(encryptedPayloadHex) {
|
|
13174
|
-
const response = await this.serial.sendCommand({
|
|
13188
|
+
const response = await this.serial.sendCommand({
|
|
13189
|
+
action: "depin_decrypt_payload",
|
|
13190
|
+
...(await this.depinDecryptWirePayload("encrypted_payload", "encrypted_payload_b64", encryptedPayloadHex)),
|
|
13191
|
+
}, 35000);
|
|
13192
|
+
this.assertSuccess(response);
|
|
13193
|
+
return response;
|
|
13194
|
+
}
|
|
13195
|
+
/**
|
|
13196
|
+
* Return the safest encoding the connected firmware has explicitly
|
|
13197
|
+
* advertised. The one-time, confirmation-free ping keeps the public DePIN
|
|
13198
|
+
* API backwards compatible: old firmware still gets its original hex field.
|
|
13199
|
+
*/
|
|
13200
|
+
async getDepinBulkCapability() {
|
|
13201
|
+
if (this.pingInfo)
|
|
13202
|
+
return this.pingInfo;
|
|
13203
|
+
if (!this.depinCapabilityHandshake) {
|
|
13204
|
+
this.depinCapabilityHandshake = this.ping().catch(() => null);
|
|
13205
|
+
}
|
|
13206
|
+
return this.depinCapabilityHandshake;
|
|
13207
|
+
}
|
|
13208
|
+
/**
|
|
13209
|
+
* Build the decrypt field for the negotiated firmware. Invalid hex is left
|
|
13210
|
+
* untouched so existing callers receive the firmware's normal validation
|
|
13211
|
+
* error instead of a new client-side parsing error.
|
|
13212
|
+
*/
|
|
13213
|
+
async depinDecryptWirePayload(hexField, base64Field, hexPayload) {
|
|
13214
|
+
const capability = await this.getDepinBulkCapability();
|
|
13215
|
+
const maxBytes = capability?.depin_max_decrypt_bytes;
|
|
13216
|
+
const supportsBase64 = capability?.capabilities?.includes("depin_bulk_decrypt_b64") === true &&
|
|
13217
|
+
Number.isSafeInteger(maxBytes) &&
|
|
13218
|
+
maxBytes > 0;
|
|
13219
|
+
// Preserve the legacy firmware validation path for malformed hex.
|
|
13220
|
+
if (!/^[0-9a-fA-F]*$/.test(hexPayload) || hexPayload.length % 2 !== 0) {
|
|
13221
|
+
return { [hexField]: hexPayload };
|
|
13222
|
+
}
|
|
13223
|
+
const bytes = bufferExports.Buffer.from(hexPayload, "hex");
|
|
13224
|
+
if (supportsBase64) {
|
|
13225
|
+
if (bytes.length > maxBytes) {
|
|
13226
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes; this device accepts at most ${maxBytes} bytes. Paginate the response before decrypting it.`);
|
|
13227
|
+
}
|
|
13228
|
+
return { [base64Field]: bytes.toString("base64") };
|
|
13229
|
+
}
|
|
13230
|
+
// A 48 KiB serial line leaves roughly 24 KiB for hex before JSON framing.
|
|
13231
|
+
// Do not send a known-unsafe legacy request that could destabilize a device.
|
|
13232
|
+
const legacyMaxBytes = 24 * 1024 - 256;
|
|
13233
|
+
if (bytes.length > legacyMaxBytes) {
|
|
13234
|
+
throw new RangeError(`DePIN decrypt payload is ${bytes.length} bytes and exceeds the ${legacyMaxBytes}-byte legacy hex transport limit. Update the firmware or paginate the response.`);
|
|
13235
|
+
}
|
|
13236
|
+
return { [hexField]: hexPayload };
|
|
13237
|
+
}
|
|
13238
|
+
/**
|
|
13239
|
+
* Sign a 32-byte digest with the DePIN key (account 100'). The device ALWAYS
|
|
13240
|
+
* asks for an explicit physical confirmation — this signature can move the
|
|
13241
|
+
* DePIN address's XNA. Used to spend from the DePIN address, notably the
|
|
13242
|
+
* pubkey-reveal burn that publishes the account-100 pubkey on-chain (so other
|
|
13243
|
+
* chat members can encrypt group messages to this identity). The host builds
|
|
13244
|
+
* the transaction, computes each input's legacy sighash, calls this per input,
|
|
13245
|
+
* and assembles the P2PKH scriptSig from `signature` (append the sighash-type
|
|
13246
|
+
* byte) + `pubkey`. Requires the device unlocked; not session-gated.
|
|
13247
|
+
*
|
|
13248
|
+
* @param digestHex 32-byte digest (the tx sighash), hex.
|
|
13249
|
+
*/
|
|
13250
|
+
async depinSignDigest(digestHex) {
|
|
13251
|
+
const response = await this.serial.sendCommand({ action: "depin_sign_digest", digest: digestHex }, 35000);
|
|
13175
13252
|
this.assertSuccess(response);
|
|
13176
13253
|
return response;
|
|
13177
13254
|
}
|