@parity/product-sdk-terminal 0.0.0-dev.312.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,337 @@
+# @parity/product-sdk-terminal
+
+> Migrated from `@polkadot-apps/terminal` v0.3.0 (`paritytech/polkadot-apps`).
+
+QR code login, attestation, and transaction signing for CLI/terminal apps via the Polkadot mobile wallet.
+
+Wraps the [`@novasamatech/host-papp`](https://www.npmjs.com/package/@novasamatech/host-papp) SDK with Node.js-compatible adapters (file-based storage, WebSocket transport) so the full SSO protocol works outside the browser.
+
+## Installation
+
+```bash
+pnpm add @parity/product-sdk-terminal
+```
+
+## Setup
+
+**Requires Node ≥21.** The package relies on the global `WebSocket` exposed by Node 21+ (via `@polkadot-api/ws-provider@0.9`). On older Node versions the WebSocket connection fails at runtime with `WebSocket is not defined`.
+
+> **Note (≥0.3):** The `@parity/product-sdk-terminal/register` WASM loader hook has been removed. It existed only to patch `verifiablejs` (a browser-only inline-WASM dependency of `@novasamatech/host-papp`). host-papp ≥0.7.9 no longer uses `verifiablejs` — its sr25519 primitives are pure JS — so no loader hook is needed. Drop any `--import @parity/product-sdk-terminal/register` flags from your `node`/`tsx` invocations.
+
+## Quick Start
+
+```ts
+import { createTerminalAdapter, renderQrCode, waitForSessions } from "@parity/product-sdk-terminal";
+
+// 1. Create the adapter
+const adapter = createTerminalAdapter({
+    appId: "my-terminal-app",
+});
+
+// 2. Subscribe to pairing status to show the QR code
+adapter.sso.pairingStatus.subscribe(async (status) => {
+    if (status.step === "pairing") {
+        console.log(await renderQrCode(status.payload));
+        console.log("Scan with the Polkadot mobile app...");
+    }
+});
+
+// 3. Authenticate (QR pairing + on-chain attestation)
+const result = await adapter.sso.authenticate();
+
+result.match(
+    (session) => console.log("Logged in!", session?.id),
+    (error) => console.error("Failed:", error.message),
+);
+
+// 4. Wait for sessions to load (they load asynchronously from disk)
+const sessions = await waitForSessions(adapter, 2000);
+
+// 5. Sign messages via the paired wallet
+if (sessions.length > 0) {
+    const session = sessions[0];
+    const signer = createSessionSigner(session, adapter);
+    // use signer with polkadot-api transactions
+}
+```
+
+## API
+
+### `createTerminalAdapter(options): TerminalAdapter`
+
+Creates a terminal adapter backed by the host-papp SDK.
+
+**Options:**
+- `appId` -- unique app identifier (used as storage namespace)
+- `endpoints?` -- statement store WebSocket endpoints (defaults to Paseo)
+- `hostMetadata?` -- optional host environment info
+- `storageDir?` -- override the on-disk session directory (defaults to `~/.polkadot-apps/`). Useful in tests and containerised environments.
+
+**Returns** a `TerminalAdapter` with:
+- `appId` -- the value you passed in (re-exposed so `createSessionSigner` can pull the productId from the adapter)
+- `sso` -- auth component (`.authenticate()`, `.abortAuthentication()`, status subscriptions)
+- `sessions` -- session manager (signing, disconnect)
+- `destroy()` -- disconnect the WebSocket and release resources. Idempotent. Suppresses `@novasamatech/statement-store`'s noisy `Statement subscription error` log for ~50 ms after the call.
+
+### `createSessionSigner(session, adapter): PolkadotSigner`
+
+Creates a `PolkadotSigner` backed by a QR-paired mobile wallet session, using the session's **default account** (`derivationIndex: 0`) under the adapter's `appId`. This is the right entry point for ~all CLI flows.
+
+```ts
+const [session] = adapter.sessions.sessions.read();
+const signer = createSessionSigner(session, adapter);
+await contract.publish.tx(domain, cid, { signer, origin });
+```
+
+### `createSessionSignerForAccount(session, ref): PolkadotSigner`
+
+Escape hatch for signing as a non-default sub-account of a paired session, or as a `productId` that differs from the adapter's `appId`. Most callers don't need this.
+
+`ref` is `{ productId: string; derivationIndex: number }`:
+- `productId` -- dotNS-style identifier of the requesting product. In normal usage this equals the adapter's `appId`; pass a different value only if you have an explicit reason.
+- `derivationIndex` -- BIP32-style child-key index. `0` is the default account; non-zero indices reach additional sub-accounts derived from the same root.
+
+```ts
+const subSigner = createSessionSignerForAccount(session, {
+    productId: "my-product",
+    derivationIndex: 3,
+});
+```
+
+> **Wire format note:** `@novasamatech/host-papp` 0.7 expects `productAccountId: [productId, derivationIndex]` in `SigningRawRequest`. Both functions above hide that tuple — pass an adapter for the default case or a named-fields object for the escape hatch.
+
+### `renderQrCode(data, options?): Promise<string>`
+
+Render a string as a QR code using Unicode half-block characters for terminal display.
+
+### `createNodeStorageAdapter(appId, storageDir?): StorageAdapter`
+
+File-based storage adapter for Node.js. Data persists in `storageDir` (defaults to `~/.polkadot-apps/`).
+
+### `waitForSessions(adapter, timeoutMs?): Promise<UserSession[]>`
+
+Waits for the session list to emit at least one entry, or resolves with `[]` after `timeoutMs`.
+
+## Allowance signers — the canonical path
+
+For CLIs that need to write to Bulletin or publish to the Statement Store: ask the paired wallet for an allowance slot, get a `PolkadotSigner` back, sign extrinsics with it. This is what most consumers want.
+
+```ts
+import {
+    createTerminalAdapter,
+    getBulletinSigner,
+    getStatementStoreProver,
+    waitForSessions,
+} from "@parity/product-sdk-terminal";
+
+const adapter = createTerminalAdapter({ appId: "my-cli" });
+
+// ...QR pair the phone, wait for the session...
+await waitForSessions(adapter);
+
+// First call prompts the wallet for an allowance slot; subsequent calls
+// return the cached slot key — no wire round-trip.
+const bulletinSigner = await getBulletinSigner(adapter, "my-cli.dot");
+await bulletinClient.tx.TransactionStorage.store({ data }).signAndSubmit(bulletinSigner);
+
+// Same idea, returns a StatementProver for `@novasamatech/statement-store` writes.
+const prover = await getStatementStoreProver(adapter, "my-cli.dot");
+```
+
+### `getBulletinSigner(adapter, productId, sessionId?): Promise<PolkadotSigner>`
+
+### `getStatementStoreProver(adapter, productId, sessionId?): Promise<StatementProver>`
+
+Both default `sessionId` to the only paired session. With zero or more than one paired sessions and no explicit id, both throw `AllowanceError` with `reason: 'NoSession'`. Pass an explicit `sessionId` to disambiguate.
+
+Failures from the host (`Rejected`, `NotAvailable`, codec drift) surface as `AllowanceError`:
+
+```ts
+import { AllowanceError } from "@parity/product-sdk-terminal";
+
+try {
+    const signer = await getBulletinSigner(adapter, "my-cli.dot");
+} catch (err) {
+    if (err instanceof AllowanceError && err.reason === "Rejected") {
+        // user denied the allowance request on the phone
+    }
+    throw err;
+}
+```
+
+Behind the scenes both helpers wrap `adapter.allowance` (inherited from host-papp's `PappAdapter`) and unwrap its neverthrow `ResultAsync` into a throwing `Promise`. If you want to keep neverthrow's `.match()` / `.mapErr()` ergonomics or need explicit multi-session handling, call `adapter.allowance.getBulletinSigner(sessionId, productId)` / `getStatementStoreProver(...)` directly.
+
+### Cache-only probes — `hasBulletinAllowance` / `hasStatementStoreAllowance`
+
+For paths that must run silently — login health checks, "would calling `getBulletinSigner` prompt the phone?" decisions, readiness probes — use the cache-only variants. They read host-papp's on-disk allowance file directly and **never** trigger a wallet prompt.
+
+```ts
+import {
+    getBulletinSigner,
+    hasBulletinAllowance,
+} from "@parity/product-sdk-terminal";
+
+if (await hasBulletinAllowance(adapter, "my-cli.dot")) {
+    // happy path — fetch the signer without risking a wallet prompt
+    const signer = await getBulletinSigner(adapter, "my-cli.dot");
+} else {
+    // tell the user a wallet prompt will fire, then call getBulletinSigner
+    console.log("Approve the allowance request on your phone…");
+    const signer = await getBulletinSigner(adapter, "my-cli.dot");
+}
+```
+
+#### `hasBulletinAllowance(adapter, productId, sessionId?): Promise<boolean>`
+
+#### `hasStatementStoreAllowance(adapter, productId, sessionId?): Promise<boolean>`
+
+Resolves `true` when a slot key for `(sessionId, productId, resource)` is already cached on disk; `false` when it is not (file absent, or present with no matching entry). Same `sessionId` defaulting as the fetching helpers: defaults to the only paired session, throws `AllowanceError('NoSession')` for zero or multiple paired sessions without an explicit id.
+
+Rejects only on decrypt or decode failures — a corrupted cache file is a real failure, not a "no allowance" signal.
+
+> The cache-only check uses an internal mirror of host-papp's `AllowanceRepository` codec because host-papp doesn't expose a public probe today. We'll switch to the upstream API when one ships; the public surface (`hasBulletinAllowance` / `hasStatementStoreAllowance`) won't change.
+
+## Allowance management — manual cache + AP control (`./host` subpath)
+
+For CLIs that need finer control — pre-allocating multiple resources in one wallet prompt, inspecting the cache before round-tripping, or building a signer over a cached key without consulting the wallet — the `@parity/product-sdk-terminal/host` subpath exposes the lower-level Host-runner surface (the [RFC-10](https://github.com/paritytech/triangle-js-sdks/blob/valentunn-rfc-0010/docs/rfcs/0010-allowance.md) Accounts Protocol companion, an on-disk allowance-key cache, and a local sr25519 signer over the cached keys). Most CLIs don't need this — start with `getBulletinSigner` / `getStatementStoreProver` above.
+
+```ts
+import {
+    ensureSlotAccountSigner,
+    requestResourceAllocation,
+    getCachedAllocation,
+    createSlotAccountSigner,
+} from "@parity/product-sdk-terminal/host";
+
+// First call prompts the wallet; subsequent calls are wire-free.
+const signer = await ensureSlotAccountSigner(session, adapter, {
+    tag: "BulletInAllowance",
+    value: undefined,
+});
+await bulletinTx.submitAndWatch(signer);
+```
+
+### `ensureSlotAccountSigner(session, adapter, resource): Promise<PolkadotSigner>`
+
+The one call most CLIs want. Cache hit → returns signer; cache miss → allocates via the wallet, then returns signer. Throws on `Rejected` / `NotAvailable`. Slot-table resources only (`BulletInAllowance`, `StatementStoreAllowance`).
+
+### `requestResourceAllocation(session, adapter, resources, options?): Promise<ApAllocationOutcome[]>`
+
+Lower-level: pre-allocate any combination of resources. Granted keys cached at `{storageDir}/{appId}_AllowanceKeys.json` (`0o600`, atomic write). `onExisting` auto-picks `Ignore`/`Increase` based on cache state; override via `options.onExisting`.
+
+### `getCachedAllocation(adapter, resource): Promise<CachedAllocation | null>`
+
+Read-only cache lookup; no wire round-trip.
+
+### `createSlotAccountSigner(adapter, resource): Promise<PolkadotSigner | null>`
+
+Build a `PolkadotSigner` from the cached slot key without round-tripping. Returns `null` if nothing's cached (use `ensureSlotAccountSigner` for the round-trip-if-missing flow).
+
+> **Caveats.** `AutoSigning` currently returns `NotAvailable` on both Android and iOS wallets. Slot renewal at expiry depends on [paritytech/individuality#931](https://github.com/paritytech/individuality/pull/931) (open) — first-time allocation works end-to-end today.
+
+## Migration from `@polkadot-apps/terminal`
+
+For consumers moving from `@polkadot-apps/terminal` v0.2.0 / v0.3.0. Existing sessions on disk (`~/.polkadot-apps/`) carry over — same `appId`, same path. No re-pairing required for the migration itself.
+
+| Concern | `@polkadot-apps/terminal` | `@parity/product-sdk-terminal` |
+| --- | --- | --- |
+| Package name | `@polkadot-apps/terminal` | `@parity/product-sdk-terminal` |
+| WASM loader hook | `--import @polkadot-apps/terminal/register` (required) | **removed** — no `--import` needed (host-papp ≥0.7.9 dropped `verifiablejs`) |
+| `createTerminalAdapter` | `async` — returned `Promise<TerminalAdapter>` | **sync** — returns `TerminalAdapter` directly. Drop the `await`. |
+| Default account signer | `createSessionSigner(session)` | `createSessionSigner(session, adapter)` — pass the adapter as second arg |
+| Non-default sub-account signer | not exposed | `createSessionSignerForAccount(session, { productId, derivationIndex })` |
+| Override session storage dir | not supported (hard-coded `~/.polkadot-apps/`) | `createTerminalAdapter({ ..., storageDir })` option |
+| E2E test helper for sessions | none | `createTestSession` from `@parity/product-sdk-terminal/testing` |
+| Node version | any (bundled `ws`) | **≥21** (uses global `WebSocket`) |
+| `destroy()` shutdown noise | emitted `Statement subscription error` to stderr | suppressed; `console.error` muted for ~50 ms |
+
+### Why the signer API changed
+
+`@novasamatech/host-papp` 0.7 replaced `SigningRawRequest.address` with `productAccountId: [productId, derivationIndex]`. The wire format requires both fields, so a session-only argument is no longer enough — the signer needs to know *which sub-account of which product is asking*. We split that into two functions to keep the common case ergonomic:
+
+- `createSessionSigner(session, adapter)` for the default account (uses `[adapter.appId, 0]`)
+- `createSessionSignerForAccount(session, { productId, derivationIndex })` for everything else
+
+The single-argument `createSessionSigner(session)` from `@polkadot-apps/terminal` no longer works against host-papp 0.7 regardless of which package you use.
+
+### Migration steps
+
+1. **Replace the dep**: `pnpm remove @polkadot-apps/terminal && pnpm add @parity/product-sdk-terminal`
+2. **Remove the `--import @.../register` flag** from your `node` / `tsx` invocations or `package.json` scripts — the WASM loader hook no longer exists (and is no longer needed).
+3. **Drop `await`** in front of `createTerminalAdapter(...)` calls.
+4. **Update each `createSessionSigner` call site**: change `createSessionSigner(session)` → `createSessionSigner(session, adapter)`.
+5. **Verify Node version** is ≥21 (`node --version`).
+
+If your existing sessions don't appear after migrating, double-check that the `appId` is identical to what you used in `@polkadot-apps/terminal` — the on-disk file names depend on it.
+
+## Testing
+
+The `@parity/product-sdk-terminal/testing` subpath exports `createTestSession`, a helper that synthesizes a valid persisted session on disk. E2E tests can inject a known-good session without going through QR pairing + attestation:
+
+```ts
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTerminalAdapter, waitForSessions } from "@parity/product-sdk-terminal";
+import { createTestSession } from "@parity/product-sdk-terminal/testing";
+
+const storageDir = mkdtempSync(join(tmpdir(), "e2e-"));
+const { sessionId } = await createTestSession({
+    appId: "my-terminal-app",
+    storageDir,
+});
+
+const adapter = createTerminalAdapter({
+    appId: "my-terminal-app",
+    storageDir,
+});
+const sessions = await waitForSessions(adapter);
+// sessions[0].id === sessionId
+```
+
+**Limits and usage notes.**
+
+- **Signing does not round-trip.** Both `session.signRaw` and `session.signPayload` go out over the statement store and expect a real phone to respond. Use this helper for flows that test session discovery, persistence, and logout — not happy-path signing.
+- **Expiry tests still work.** The synthesized local account was never registered on the People chain, so any statement-store write from this session fails with `NoAllowanceError`. That's the same error the CLI sees when a previously valid session's on-chain attestation has expired.
+- **No `expiresAt` option.** The on-disk codec has no expiry field; validity lives on chain.
+- **Corrupted-session cases** don't need a helper — `fs.writeFile("<storageDir>/<appId>_SsoSessions.json", "not-hex")` from the test is enough.
+
+## Signing
+
+After login and attestation, the paired wallet can sign both transactions and raw messages via the statement store. The `PolkadotSigner` returned by `createSessionSigner` routes each path to the right host-papp method:
+
+- **Transactions** (`signTx` from polkadot-api's perspective — what `submitAndWatch`, `signSubmitAndWatch`, contract method calls, etc. invoke) go through `session.signRaw` with the `Payload` tag. polkadot-api assembles the full SCALE-encoded signing payload from runtime metadata — `callData ‖ extras ‖ additionalSigneds` for every signed extension the chain declares — and hands the bytes to the wallet as an opaque hex blob. The wallet signs the payload as-is, with no envelope wrapping. Any signed extension declared by the runtime (including extensions polkadot-api doesn't know about, e.g. `AsPgas` on Paseo Next v2) survives end-to-end because the wallet doesn't inspect the bytes — it just signs them.
+- **Raw bytes** (`signBytes`) go through `session.signRaw` with the `Bytes` tag. Mobile applies the standard `<Bytes>...</Bytes>` anti-phishing wrap before signing — appropriate for arbitrary data, the same behavior `signRaw` has across all Polkadot wallets.
+
+> **Note on previous bugs.** Versions prior to `0.1.1` routed *all* signing through `signRaw` with no tag distinction, producing `BadProof`-rejected signatures. Versions `0.1.1` through `0.2.x` then used `polkadot-api/pjs-signer`, which threw `PJS does not support this signed-extension: <name>` on any extension outside its eight built-in mappers (notably `AsPgas`). The current path bypasses both pitfalls.
+
+## Notes
+
+### WebSocket transport
+
+The adapter uses `@polkadot-api/ws-provider@0.9`, which relies on the global `WebSocket` exposed by Node ≥21. Older Node versions (18, 20) will fail at connect time with `WebSocket is not defined` — upgrade Node, or pass an explicit `websocketClass` from the [`ws`](https://www.npmjs.com/package/ws) package.
+
+The default WebSocket is constructed without `followRedirects: true`, so endpoints behind an HTTP redirect will fail to connect. If you must point at an endpoint that does, supply the resolved URL directly via the `endpoints` option.
+
+## How It Works
+
+1. **QR Pairing** -- generates Sr25519 + P256 keypairs, encodes a `polkadotapp://pair?handshake=0x...` deep link, subscribes to the statement store
+2. **Attestation** -- registers the local account on the People chain so it can publish statements
+3. **Signing** -- sends encrypted signing requests to the wallet via the statement store, receives signed responses
+
+Sessions are persisted to `~/.polkadot-apps/` and survive across restarts. The SDK loads them asynchronously on startup — subscribe to `adapter.sessions.sessions` and wait for the first emission.
+
+## Dependencies
+
+- `@novasamatech/host-papp` -- Polkadot host-product SDK (auth, attestation, signing)
+- `@novasamatech/statement-store` -- statement store client and session management
+- `@novasamatech/storage-adapter` -- storage interface
+- `@polkadot-api/ws-provider` -- WebSocket JSON-RPC provider
+- `neverthrow` -- Result type for error handling
+- `qrcode` -- QR code generation
+
+## Future Work
+
+- **`KvStore`↔`StorageAdapter` bridge.** This package implements its own file-backed `StorageAdapter` for Node.js (`createNodeStorageAdapter`). Once `@parity/product-sdk-local-storage` grows a file backend with the same `read/write/clear/subscribe` `ResultAsync` shape, replace `node-storage.ts` with a thin adapter over it.
+- **Codec re-exports from `@parity/product-sdk-statement-store`.** `testing.ts` imports session-account codec helpers (`AccountIdCodec`, `LocalSessionAccountCodec`, etc.) directly from `@novasamatech/statement-store`. Re-exporting them through the in-monorepo wrapper would let this package depend only on workspace siblings.
+- **`@noble/*` major version drift.** This package pins `@noble/{ciphers,curves,hashes}: ^2.x` because upstream `@polkadot-apps/terminal` did, and the `testing.ts` codec helpers use the v2 import paths (`@noble/hashes/blake2.js`, `@noble/curves/nist.js`). The rest of the monorepo is on `^1.x`. Both majors coexist in the lockfile; not a runtime problem today but worth a coordinated bump. Either move the whole monorepo to v2, or rewrite `testing.ts` against v1 paths (`@noble/hashes/blake2b.js` etc.).