@neuraiproject/neurai-sign-esp32 0.5.11 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -49,6 +49,8 @@ For classic HTML pages without ESM imports, load the global bundle:
49
49
  <script src="./dist/NeuraiSignESP32.global.js"></script>
50
50
  <script>
51
51
  const device = new window.NeuraiSignESP32.NeuraiESP32();
52
+ // The IIFE exposes the DePIN adapter too:
53
+ // window.NeuraiSignESP32.createDepinDeviceIdentity(device, options)
52
54
  </script>
53
55
  ```
54
56
 
@@ -262,6 +264,93 @@ await device.depinSessionEnd();
262
264
  > the freshness of `timestamp` — the host supplies it and the chip only validates
263
265
  > the message structure and channel/sender scope.
264
266
 
267
+ ### DePIN protocol 2: use the device as a messaging identity
268
+
269
+ The calls above are the raw device commands. For the full **DePIN Messaging
270
+ Protocol 2** flows (challenge → receive → publish → purge) there is an adapter
271
+ that turns the device into an identity consumable by
272
+ [`@neuraiproject/neurai-depin-msg`](https://www.npmjs.com/package/@neuraiproject/neurai-depin-msg)
273
+ `>= 3.1.0`, without the private key ever leaving the chip:
274
+
275
+ ```javascript
276
+ import { createDepinDeviceIdentity } from "@neuraiproject/neurai-sign-esp32";
277
+ import { requestDepinChallenge, receiveDepinMessages } from "@neuraiproject/neurai-depin-msg";
278
+
279
+ // Opens (or reuses) a session for the token and validates the announced
280
+ // identity against the network you expect. ONE physical approval.
281
+ const identity = await createDepinDeviceIdentity(device, {
282
+ token: "&NEURAI.CHAT",
283
+ expectedNetwork: "test", // must match the app's network
284
+ sessionPermissions: ["receive", "publish"], // default: ["receive"]
285
+ ttlMinutes: 15,
286
+ });
287
+
288
+ // From here it is an ordinary depin-msg identity.
289
+ const challenge = await requestDepinChallenge({
290
+ rpc, identity, token: "&NEURAI.CHAT", poolPublicKey,
291
+ });
292
+ const page = await receiveDepinMessages({
293
+ rpc, identity, token: "&NEURAI.CHAT", challenge: challenge.challenge,
294
+ poolPublicKey, network: "test", limit: 25,
295
+ });
296
+ ```
297
+
298
+ **Session permissions.** They are independent capabilities, because a session
299
+ approved for reading must not be able to publish in the owner's name or purge
300
+ the pool:
301
+
302
+ | Permission | Authorises |
303
+ | --- | --- |
304
+ | `receive` | `DEPIN-REQ` (type `receive`) and `DEPIN-GET` — reading |
305
+ | `publish` | `depin_sign` — publishing messages |
306
+ | `admin` | `DEPIN-REQ` (type `admin`) and `DEPIN-CLEAR` — purging |
307
+
308
+ Decryption is inherent to **any** live session, so say so when asking for
309
+ approval. An omitted list grants only `["receive"]`, never `admin`. Requesting
310
+ a different set than the device granted fails instead of silently reusing a
311
+ more privileged session. And `admin` implies a *total* purge: the `mode`
312
+ argument of `depinclearmsg` is not part of the signed `DEPIN-CLEAR` preimage,
313
+ so a purge signature cannot be narrowed after the fact.
314
+
315
+ **Why not `depinSignDigest`.** That command signs an arbitrary 32-byte hash —
316
+ possibly a transaction sighash — which is exactly why it is *not* session-gated
317
+ and always asks for a physical confirmation. The adapter never uses it:
318
+ authentication goes through `depinSignAuth`, where the device receives the
319
+ structured fields, rebuilds `DEPIN-REQ|…` / `DEPIN-GET|…` / `DEPIN-CLEAR|…`
320
+ plus the signed-message envelope itself, and validates them against the session
321
+ before signing. `depinSignDigest` stays for what it was meant for, such as the
322
+ pubkey-reveal transaction.
323
+
324
+ Every signature the device returns is verified on the host before it is used,
325
+ so a device that signs the wrong digest or with another key fails locally
326
+ instead of at the node. Errors are `DepinDeviceIdentityError` with stable
327
+ `code`s (`SESSION_PERMISSION_INSUFFICIENT`, `SESSION_TIME_BUDGET_INSUFFICIENT`,
328
+ `INVALID_DEVICE_SIGNATURE`, `PAYLOAD_TOO_LARGE`…) so a UI can map them to
329
+ concrete actions.
330
+
331
+ **Sizing the session.** `identity.maxDecryptBytes` reports what the device can
332
+ decrypt in one go; pick `limit` so a page fits, because a reply the device
333
+ cannot open costs the whole challenge (`next_challenge` travels *inside* it).
334
+ A round costs roughly 4 device operations for an initial read, 2 for a chained
335
+ one, 2 to publish and 4 to purge — size `ratePerMin` accordingly. Before a
336
+ sequence that spans several calls, reserve time explicitly:
337
+
338
+ ```javascript
339
+ await identity.session.ensure({ minRemainingSeconds: 60 });
340
+ ```
341
+
342
+ > **Firmware requirement.** The adapter needs firmware advertising protocol 2
343
+ > with `depin_identity`, `depin_message`, `depin_auth_sign`,
344
+ > `depin_session_key` and `depin_session_permissions`; it refuses to downgrade.
345
+ > `depin_sign_auth` and session permissions are **not implemented in current
346
+ > firmware yet** — the contract they must satisfy is specified, and exercised
347
+ > by a cryptographically faithful device mock, in this package's tests.
348
+ > `@neuraiproject/neurai-depin-msg@3.1.0` must be published before installing
349
+ > this repository from scratch or publishing `neurai-sign-esp32@0.6.0`. The
350
+ > package has no runtime dependency on `neurai-depin-msg`; it is a `^3.1.0`
351
+ > development dependency used only by the integration tests. The package gate
352
+ > validates the adapter from a clean `neurai-sign-esp32` tarball.
353
+
265
354
  ### Provision an unconfigured device (`setup_seed`)
266
355
 
267
356
  Firmware with the security layer boots **unconfigured** until a seed is stored
@@ -592,7 +681,8 @@ using JSON messages. Supported commands:
592
681
  | `depin_sign` | None (session-gated, rate-limited) | 30s |
593
682
  | `depin_decrypt` | None (session-gated, rate-limited) | 30s |
594
683
  | `depin_decrypt_payload` | None (session-gated, rate-limited) | 30s |
595
- | `depin_session_end` | None | 10s |
684
+ | `depin_session_status` | None (session-key gated) | 10s |
685
+ | `depin_session_end` | None (session-key gated) | 10s |
596
686
 
597
687
  `info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
598
688
  returns only the public key (the library derives the address) and signing uses
@@ -628,7 +718,10 @@ Main class for device interaction.
628
718
  | `depinSign(params)` | Sign a DePIN message on-device (DER over the canonical CDepinMessage); session-gated, rate-limited |
629
719
  | `depinDecrypt(depinMessageHex)` | Decrypt a CDepinMessage addressed to this identity → `plaintext_b64`; session-gated. Uses Base64 automatically on firmware 0.5.11+ |
630
720
  | `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 |
721
+ | `depinSignAuth(command)` | Sign a protocol-2 authentication preimage (`request`/`get`/`clear`) from STRUCTURED fields: the device rebuilds `DEPIN-REQ|…`/`DEPIN-GET|…`/`DEPIN-CLEAR|…` and validates it against the session. Session-gated, permission-checked |
722
+ | `depinSignDigest(digestHex)` | Sign a tx sighash with the DePIN key (account 100') → `{ signature, pubkey }`; physical confirmation, **not** session-gated, for the pubkey-reveal burn. Never used by the DePIN messaging adapter |
723
+ | `depinSessionStatus()` | Check whether the cached/`setDepinSessionKey` key still names a live session → `{ active, token?, expires_in_s? }` (proto v2) |
724
+ | `getDepinSessionKey()` / `setDepinSessionKey(key)` | Read / restore the per-session capability key (persist it in the OS keystore across restarts) |
632
725
  | `depinSessionEnd()` | End the DePIN session (also revoked on lock / disconnect / timeout) |
633
726
  | `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
634
727
  | `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |