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

package/README.md

@@ -50,7 +50,7 @@ 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);
+    const signer = await createSessionSigner(session, adapter);
     // use signer with polkadot-api transactions
 }
 ```
@@ -63,7 +63,7 @@ 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)
+- `endpoints?` -- statement store WebSocket endpoints (defaults to `StatementStoreNetworks.paseo`)
 - `hostMetadata?` -- optional host environment info
 - `storageDir?` -- override the on-disk session directory (defaults to `~/.polkadot-apps/`). Useful in tests and containerised environments.
 
@@ -71,34 +71,78 @@ Creates a terminal adapter backed by the host-papp SDK.
 - `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.
+- `destroy()` -- disconnect the WebSocket and release resources. Idempotent. Drops `@novasamatech/statement-store`'s benign `Statement subscription error: Client destroyed` line, which it emits synchronously while disconnecting a live subscription — only that line; every other `console.error` passes through.
 
-### `createSessionSigner(session, adapter): PolkadotSigner`
+### `StatementStoreNetworks`
+
+The statement store endpoints terminal can pair against, keyed by network.
+
+| Key | Network | Endpoint |
+| --- | --- | --- |
+| `paseo` | Paseo Next v2 | `wss://paseo-people-next-system-rpc.polkadot.io` |
+| `previewnet` | zombienet, a step ahead of paseo | whatever host-papp's `SS_PREVIEW_STAGE_ENDPOINTS` resolves to, today `wss://previewnet.substrate.dev/people` |
+
+Keyed the same way as `BULLETIN_RPCS` in `@parity/product-sdk-host`. There is deliberately no
+`devnet` key: that people chain has a statement store, but no endpoint for it is published here, and
+no phone build pairs against it. Pass `endpoints` explicitly to reach one.
+
+Pairing only works when the terminal and the phone are on the **same** people chain, and the phone
+picks its chain per build flavour. The Polkadot app's nightly build uses `paseo`, which is why that
+is the default; a preview-flavour phone needs `endpoints: StatementStoreNetworks.previewnet`.
+
+`SS_STABLE_STAGE_ENDPOINTS` is also exported. It is internal to the Parity network and does not
+answer from outside it.
+
+### `isBenignTeardownError(error): boolean`
+
+Whether `error` is the benign teardown noise above (`Client destroyed`, matched on the message so it never swallows another package's `DestroyedError`). `destroy()` already drops it during its own teardown; export it so a consumer with its own `console.error` guard can drop the same line without reinventing the match.
+
+### `createSessionSigner(session, adapter, publicKey?, options?): Promise<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.
 
+Async because the signer needs the product's subtree public key (RFC-0022), which only the paired wallet holds. That is one consent-free round trip the first time a product is seen; afterwards it is served from a cache on disk.
+
 ```ts
 const [session] = adapter.sessions.sessions.read();
-const signer = createSessionSigner(session, adapter);
+const signer = await createSessionSigner(session, adapter);
 await contract.publish.tx(domain, cid, { signer, origin });
 ```
 
-### `createSessionSignerForAccount(session, ref): PolkadotSigner`
+### `createSessionSignerForAccount(session, ref, options?): Promise<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.
+- `derivationIndex` -- child-key index within the product's subtree. `0` is the default account; non-zero indices reach additional sub-accounts of the same product.
 
 ```ts
-const subSigner = createSessionSignerForAccount(session, {
+const subSigner = await 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.
+Both factories accept `SessionSignerOptions`, extending `ProductSubtreeOptions` with optional `txExtVersion` (default `0`). For example, pass `{ txExtVersion: 1 }` as the final `options` argument. The extension bytes supplied to `signTx` must match that version. PAPI 2.1.6's standard transaction builder encodes version `0`; this option does not change its encoder.
+
+> **Wire format note:** `@novasamatech/host-papp` expects `productAccountId: [productId, { tag: "Index", value: 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.
+
+### `getProductSubtreePublicKey(session, productId, options?): Promise<Uint8Array>`
+
+Fetches the sr25519 public key of `//product//{productId}` from the paired wallet (RFC-0022). Both signer factories call it for you; reach for it directly to warm the cache before going offline, or to derive a product address without building a signer.
+
+The request is consent-free, so it raises no prompt on the phone, but it does need the phone reachable. The result is cached in memory and on disk, so only a cold cache reaches the wallet.
+
+```ts
+await getProductSubtreePublicKey(session, adapter.appId, { appId: adapter.appId });
+```
+
+`options` is `ProductSubtreeOptions`:
+- `appId` -- names the cache file (`~/.polkadot-apps/${appId}_ProductSubtrees.json`). Defaults to `productId`. **Pass your app id.** Anything that sweeps `~/.polkadot-apps/` by app-id prefix, such as a sign-out that clears local state, only finds the file if it is named after the app.
+- `storageDir` -- overrides `~/.polkadot-apps/`, matching `createTerminalAdapter({ storageDir })`.
+
+The cache file is written with mode `0600` and keyed by session and product, so re-pairing or switching wallet account does not reuse a stale key.
 
 ### `renderQrCode(data, options?): Promise<string>`
 
@@ -238,20 +282,22 @@ For consumers moving from `@polkadot-apps/terminal` v0.2.0 / v0.3.0. Existing se
 | 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 })` |
+| Default account signer | `createSessionSigner(session)` | `await createSessionSigner(session, adapter)` — pass the adapter as second arg, and await it |
+| Non-default sub-account signer | not exposed | `await 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 |
+| `destroy()` shutdown noise | emitted `Statement subscription error` to stderr | only the benign `Client destroyed` line dropped (synchronously, during disconnect); other `console.error` untouched |
 
 ### 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:
+`@novasamatech/host-papp` 0.7 replaced `SigningRawRequest.address` with `productAccountId: [productId, derivationIndex]`, and 0.10 made the index a tagged `Index | Raw` selector. 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]`)
+- `createSessionSigner(session, adapter)` for the default account (uses `[adapter.appId, { tag: "Index", value: 0 }]`)
 - `createSessionSignerForAccount(session, { productId, derivationIndex })` for everything else
 
+Both return a promise since RFC-0022: a product account hangs off `//product//{productId}`, whose two hard junctions no public key can cross, so the subtree key has to be fetched from the paired wallet once per product.
+
 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
@@ -259,7 +305,7 @@ The single-argument `createSessionSigner(session)` from `@polkadot-apps/terminal
 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)`.
+4. **Update each `createSessionSigner` call site**: change `createSessionSigner(session)` → `await 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.
@@ -300,7 +346,7 @@ const sessions = await waitForSessions(adapter);
 
 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.
+- **Transactions** (`signTx`, used by `submitAndWatch`, `signSubmitAndWatch`, and contract calls) go through `session.createTransaction`. The signer forwards the account, call data, `txExtVersion`, and every extension's encoded `extra` and `additionalSigned` bytes, including unknown extensions such as `AsPgas`. The wallet decodes the transaction for display and returns the signed extrinsic.
 - **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.

package/dist/chunk-EORPX5XL.js

@@ -0,0 +1,267 @@
+import { createLogger } from '@parity/product-sdk-logger';
+import { fromHex, toHex } from '@polkadot-api/utils';
+import { readFile, mkdir, writeFile, rename } from 'fs/promises';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { numberToBytesLE, bytesToNumberLE } from '@noble/curves/utils.js';
+import { createDerive, sr25519Derive, sr25519 } from '@polkadot-labs/hdkd-helpers';
+import { getPolkadotSigner } from 'polkadot-api/signer';
+
+// src/host.ts
+var log = createLogger("terminal");
+var DEFAULT_STORAGE_DIR = join(homedir(), ".polkadot-apps");
+var CACHE_FILE_MODE = 384;
+function sanitizeAppId(appId) {
+  return appId.replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+function cacheFilePath(appId, kind, storageDir) {
+  return join(storageDir ?? DEFAULT_STORAGE_DIR, `${sanitizeAppId(appId)}_${kind}.json`);
+}
+async function loadJsonCache(path, version, label) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch (e) {
+    if (e?.code === "ENOENT") return null;
+    throw e;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.version !== version) {
+      log.warn(`${label} schema mismatch; starting fresh`, { path });
+      return null;
+    }
+    return parsed;
+  } catch (e) {
+    log.warn(`${label} parse failed; starting fresh`, { path, error: String(e) });
+    return null;
+  }
+}
+async function saveJsonCache(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tmp, JSON.stringify(value, null, 2), { mode: CACHE_FILE_MODE });
+  await rename(tmp, path);
+}
+var locks = /* @__PURE__ */ new Map();
+function withFileLock(path, fn) {
+  const prev = locks.get(path) ?? Promise.resolve();
+  const next = prev.catch(() => {
+  }).then(fn);
+  locks.set(
+    path,
+    next.catch(() => {
+    })
+  );
+  return next;
+}
+
+// src/host-cache.ts
+function cachePath(appId, storageDir) {
+  return cacheFilePath(appId, "AllowanceKeys", storageDir);
+}
+function emptyCache() {
+  return { version: 2, entries: {} };
+}
+async function loadCache(appId, storageDir) {
+  const path = cachePath(appId, storageDir);
+  const cache = await loadJsonCache(path, 2, "allowance cache");
+  if (!cache || typeof cache.entries !== "object" || cache.entries === null) {
+    return emptyCache();
+  }
+  return cache;
+}
+async function saveCache(appId, cache, storageDir) {
+  await saveJsonCache(cachePath(appId, storageDir), cache);
+}
+function smartContractDest(dest) {
+  return dest.tag === "Index" ? `Index::${dest.value}` : `Raw::${toHex(dest.value)}`;
+}
+function cacheKey(resource) {
+  if (resource.tag === "SmartContractAllowance") {
+    return `${resource.tag}::${smartContractDest(resource.value)}`;
+  }
+  return resource.tag;
+}
+function pickOnExistingPolicy(cache, resources) {
+  if (resources.length === 0) return "Ignore";
+  const allSlotTableAndCached = resources.every((r) => {
+    if (r.tag !== "BulletInAllowance" && r.tag !== "StatementStoreAllowance") return false;
+    return Object.hasOwn(cache.entries, cacheKey(r));
+  });
+  return allSlotTableAndCached ? "Increase" : "Ignore";
+}
+function mergeOutcomes(cache, requested, outcomes) {
+  if (requested.length !== outcomes.length) {
+    throw new Error(
+      `mergeOutcomes: length mismatch \u2014 requested ${requested.length}, got ${outcomes.length}`
+    );
+  }
+  const entries = { ...cache.entries };
+  let mutated = false;
+  for (let i = 0; i < outcomes.length; i++) {
+    const req = requested[i];
+    const out = outcomes[i];
+    if (out.tag !== "Allocated") continue;
+    const inner = out.value;
+    if (inner.tag !== req.tag) {
+      throw new Error(
+        `mergeOutcomes: variant mismatch at index ${i} \u2014 requested ${req.tag}, got Allocated<${inner.tag}>`
+      );
+    }
+    const key = cacheKey(req);
+    switch (inner.tag) {
+      case "BulletInAllowance":
+      case "StatementStoreAllowance":
+        entries[key] = {
+          tag: inner.tag,
+          slotAccountKey: toHex(inner.value.slotAccountKey)
+        };
+        mutated = true;
+        break;
+      case "SmartContractAllowance":
+        if (req.tag === "SmartContractAllowance") {
+          entries[key] = {
+            tag: "SmartContractAllowance",
+            dest: smartContractDest(req.value)
+          };
+          mutated = true;
+        }
+        break;
+      case "AutoSigning":
+        entries[key] = {
+          tag: "AutoSigning",
+          ringVrfDomainEntropy: toHex(inner.value.ringVrfDomainEntropy),
+          productRootPrivateKey: toHex(inner.value.productRootPrivateKey)
+        };
+        mutated = true;
+        break;
+    }
+  }
+  return mutated ? { version: 2, entries } : cache;
+}
+function readCacheEntry(cache, resource) {
+  return cache.entries[cacheKey(resource)] ?? null;
+}
+function withCacheLock(appId, storageDir, fn) {
+  return withFileLock(cachePath(appId, storageDir), fn);
+}
+function canonicalSr25519SecretToEd25519Bytes(secret) {
+  const ed25519Scalar = numberToBytesLE(bytesToNumberLE(secret.subarray(0, 32)) << 3n, 32);
+  const out = new Uint8Array(64);
+  out.set(ed25519Scalar, 0);
+  out.set(secret.subarray(32, 64), 32);
+  return out;
+}
+function buildKeypair(secret) {
+  if (secret.length === 32) {
+    const derive = createDerive({ seed: secret, curve: sr25519, derive: sr25519Derive });
+    const keypair = derive("");
+    return { publicKey: keypair.publicKey, sign: (data) => keypair.sign(data) };
+  }
+  if (secret.length === 64) {
+    const ed25519Secret = canonicalSr25519SecretToEd25519Bytes(secret);
+    return {
+      publicKey: sr25519.getPublicKey(ed25519Secret),
+      sign: (data) => sr25519.sign(data, ed25519Secret)
+    };
+  }
+  throw new Error(
+    `createSlotAccountSigner: unexpected slotAccountKey length ${secret.length}. Expected 32 (mini-secret) or 64 (expanded secret).`
+  );
+}
+function buildSignerFromEntry(entry) {
+  if (entry.tag !== "BulletInAllowance" && entry.tag !== "StatementStoreAllowance") {
+    throw new Error(
+      `createSlotAccountSigner: ${entry.tag} does not carry a slot account key. Slot-table signing is defined for BulletInAllowance and StatementStoreAllowance only.`
+    );
+  }
+  const secret = fromHex(entry.slotAccountKey);
+  const { publicKey, sign } = buildKeypair(secret);
+  return getPolkadotSigner(publicKey, "Sr25519", async (data) => sign(data));
+}
+async function createSlotAccountSigner(adapter, resource, productId) {
+  const cache = await loadCache(productId ?? adapter.appId, adapter.storageDir);
+  const entry = readCacheEntry(cache, resource);
+  if (!entry) return null;
+  return buildSignerFromEntry(entry);
+}
+
+// src/host.ts
+var log2 = createLogger("terminal");
+async function requestResourceAllocation(session, adapter, resources, options = {}) {
+  const productId = options.productId ?? adapter.appId;
+  return withCacheLock(productId, adapter.storageDir, async () => {
+    const cache = await loadCache(productId, adapter.storageDir);
+    const onExisting = options.onExisting ?? pickOnExistingPolicy(cache, resources);
+    log2.debug("requestResourceAllocation", {
+      productId,
+      resources: resources.map((r) => r.tag),
+      onExisting,
+      autoPolicy: options.onExisting === void 0
+    });
+    const outcomes = await sendResourceAllocation(session, productId, resources, onExisting);
+    const next = mergeOutcomes(cache, resources, outcomes);
+    if (next !== cache) {
+      await saveCache(productId, next, adapter.storageDir);
+    }
+    return outcomes;
+  });
+}
+async function sendResourceAllocation(session, productId, resources, onExisting) {
+  const result = await session.requestResourceAllocation({
+    callingProductId: productId,
+    resources,
+    onExisting
+  });
+  if (result.isErr()) {
+    throw new Error(`requestResourceAllocation failed: ${result.error.message}`);
+  }
+  return result.value;
+}
+async function getCachedAllocation(adapter, resource, productId) {
+  const cache = await loadCache(productId ?? adapter.appId, adapter.storageDir);
+  return readCacheEntry(cache, resource);
+}
+async function ensureSlotAccountSigner(session, adapter, resource, productId) {
+  const resolvedProductId = productId ?? adapter.appId;
+  return withCacheLock(resolvedProductId, adapter.storageDir, async () => {
+    const cache = await loadCache(resolvedProductId, adapter.storageDir);
+    const hit = readCacheEntry(cache, resource);
+    if (hit) return buildSignerFromEntry(hit);
+    log2.debug("ensureSlotAccountSigner: cache miss, allocating", { resource: resource.tag });
+    const onExisting = pickOnExistingPolicy(cache, [resource]);
+    const outcomes = await sendResourceAllocation(
+      session,
+      resolvedProductId,
+      [resource],
+      onExisting
+    );
+    const next = mergeOutcomes(cache, [resource], outcomes);
+    if (next !== cache) {
+      await saveCache(resolvedProductId, next, adapter.storageDir);
+    }
+    const outcome = outcomes[0];
+    if (!outcome) {
+      throw new Error(
+        `ensureSlotAccountSigner: protocol violation \u2014 empty outcomes for ${resource.tag}`
+      );
+    }
+    if (outcome.tag !== "Allocated") {
+      throw new Error(
+        `ensureSlotAccountSigner: allocation ${outcome.tag} for ${resource.tag}`
+      );
+    }
+    const freshEntry = readCacheEntry(next, resource);
+    if (!freshEntry) {
+      throw new Error(
+        `ensureSlotAccountSigner: allocation succeeded but cache lookup returned null for ${resource.tag}`
+      );
+    }
+    return buildSignerFromEntry(freshEntry);
+  });
+}
+
+export { cacheFilePath, createSlotAccountSigner, ensureSlotAccountSigner, getCachedAllocation, loadJsonCache, requestResourceAllocation, saveJsonCache, sendResourceAllocation, withFileLock };
+//# sourceMappingURL=chunk-EORPX5XL.js.map
+//# sourceMappingURL=chunk-EORPX5XL.js.map