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

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { T as TerminalAdapter } from './host-_G9M0isV.js';
-export { A as AllocatableResource, a as ApAllocationOutcome, O as OnExistingAllowancePolicy, R as RequestResourceAllocationOptions, b as TerminalAdapterOptions, c as createTerminalAdapter, i as isBenignTeardownError, r as requestResourceAllocation, s as sendResourceAllocation } from './host-_G9M0isV.js';
+import { T as TerminalAdapter } from './host-Dk5G2hVc.js';
+export { A as AllocatableResource, a as ApAllocationOutcome, O as OnExistingAllowancePolicy, R as RequestResourceAllocationOptions, b as TerminalAdapterOptions, c as createTerminalAdapter, i as isBenignTeardownError, r as requestResourceAllocation, s as sendResourceAllocation } from './host-Dk5G2hVc.js';
 import { UserSession } from '@novasamatech/host-papp';
 export { AllowanceError, AllowanceErrorReason, AllowanceService, HostMetadata, PairingStatus, PappAdapter, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, UserSession } from '@novasamatech/host-papp';
-import { PolkadotSigner } from 'polkadot-api';
+import { CommonSignerTxCreator } from '@polkadot-api/signers-common';
 export { AllowanceExpiredError, SignerError } from '@parity/product-sdk-signer/errors';
 import { StatementProver } from '@novasamatech/statement-store';
 import { StorageAdapter } from '@novasamatech/storage-adapter';
@@ -46,7 +46,7 @@ interface ProductSubtreeOptions {
 declare function getProductSubtreePublicKey(session: UserSession, productId: string, options?: ProductSubtreeOptions): Promise<Uint8Array>;
 
 /**
- * Create a PolkadotSigner from a QR-paired session.
+ * Create a PAPI 3 transaction creator from a QR-paired session.
  *
  * Routes **transaction signing** through `session.createTransaction` — the
  * host-papp `CreateTransactionRequest`/`CreateTransactionResponse` SSO
@@ -112,7 +112,15 @@ interface ProductAccountRef {
     publicKey?: Uint8Array;
 }
 interface SessionSignerOptions extends ProductSubtreeOptions {
-    /** Extension version of the supplied signTx bytes. Defaults to 0; does not change encoding. */
+    /**
+     * Pipeline version to prefer when the transaction names none. Defaults to 0.
+     *
+     * When that pipeline does not declare every extension the caller supplied,
+     * for example in `customSignedExtensions`, the signer uses the lowest version
+     * that does, and refuses a transaction no pipeline can carry. A wrapper that
+     * writes its own extensions, such as `withAsPerson`, sets the version on the
+     * transaction itself, and that always wins.
+     */
     txExtVersion?: number;
 }
 declare const INCOMPLETE_SESSION_MESSAGE = "Stored login session is missing the root account public key. Run \"logout\" and then \"login\" to pair again.";
@@ -134,7 +142,7 @@ declare function sessionRootPublicKey(session: UserSession): Uint8Array;
  */
 declare function deriveProductPublicKey(session: UserSession, ref: ProductAccountRef, options?: ProductSubtreeOptions): Promise<Uint8Array>;
 /**
- * Create a `PolkadotSigner` backed by a QR-paired mobile wallet session,
+ * Create a PAPI 3 transaction creator backed by a QR-paired mobile wallet session,
  * using the session's **default account** (`derivationIndex: 0`).
  *
  * For non-default sub-accounts, use {@link createSessionSignerForAccount}.
@@ -146,9 +154,9 @@ declare function deriveProductPublicKey(session: UserSession, ref: ProductAccoun
  *   `[adapter.appId, 0]`. Optional — when omitted it's fetched and derived.
  *   See {@link ProductAccountRef.publicKey}.
  */
-declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array, options?: SessionSignerOptions): Promise<PolkadotSigner>;
+declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array, options?: SessionSignerOptions): Promise<CommonSignerTxCreator>;
 /**
- * Create a `PolkadotSigner` for a specific sub-account of a paired session.
+ * Create a PAPI 3 transaction creator for a specific sub-account of a paired session.
  *
  * Use this when you need a derivation index other than `0`, or a `productId`
  * different from the adapter's `appId`. For the common default-account case,
@@ -157,13 +165,13 @@ declare function createSessionSigner(session: UserSession, adapter: TerminalAdap
  * @param session The paired user session.
  * @param ref The product account to sign as: `{ productId, derivationIndex }`.
  */
-declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef, options?: SessionSignerOptions): Promise<PolkadotSigner>;
+declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef, options?: SessionSignerOptions): Promise<CommonSignerTxCreator>;
 
 /**
- * Get a `PolkadotSigner` for a Bulletin allowance slot.
+ * Get a PAPI 3 transaction creator for a Bulletin allowance slot.
  *
  * Allocates an allowance slot via the paired wallet (or returns the cached
- * one), derives the slot-account keypair, and returns a `PolkadotSigner`
+ * one), derives the slot-account keypair, and returns a PAPI 3 transaction creator
  * that signs Bulletin extrinsics with it. Replaces the manual
  * `requestResourceAllocation` + `createSlotAccountSigner` two-step for the
  * common case.
@@ -184,10 +192,10 @@ declare function createSessionSignerForAccount(session: UserSession, ref: Produc
  * const adapter = createTerminalAdapter({ appId: "my-cli" });
  * // ... QR pair, wait for session ...
  * const signer = await getBulletinSigner(adapter, "my-cli.dot");
- * await client.bulletin.tx.TransactionStorage.store({ data }).signAndSubmit(signer);
+ * await client.bulletin.tx.TransactionStorage.store({ data }).createAndSubmit(signer);
  * ```
  */
-declare function getBulletinSigner(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<PolkadotSigner>;
+declare function getBulletinSigner(adapter: TerminalAdapter, productId: string, sessionId?: string): Promise<CommonSignerTxCreator>;
 /**
  * Get a `StatementProver` for a statement-store allowance slot.
  *
@@ -250,6 +258,99 @@ declare function hasStatementStoreAllowance(adapter: TerminalAdapter, productId:
  */
 declare function waitForSessions(adapter: TerminalAdapter, timeoutMs?: number): Promise<UserSession[]>;
 
+/**
+ * Client-side RFC-0007 product-entropy derivation for terminal (QR/SSO) sessions.
+ *
+ * Specified normatively by host-spec §C.8 "RFC-0007 product entropy"
+ * ({@link https://github.com/paritytech/host-spec/blob/adb3989208ae1c2107dbf0159611353e6989422c/spec/C-account-derivation.md?plain=1#L129-L147 | spec/C-account-derivation.md}):
+ *
+ *   layer1 = blake2b256_keyed(key = utf8("product-entropy-derivation"), msg = rootAccountSecret)
+ *   layer2 = blake2b256_keyed(key = blake2b256(utf8(productId)),        msg = layer1)
+ *   result = blake2b256_keyed(key = callerKey,                          msg = layer2)
+ *
+ * The paired {@link UserSession} already carries layer 1 as `rootEntropySource`,
+ * so this module computes only layers 2 and 3 — no host round-trip. The output
+ * matches what an in-container app gets from `@parity/product-sdk-host`'s
+ * `deriveEntropy` for the same wallet + product + key, so entropy-derived keys
+ * interoperate across web (in-container) and terminal (QR/SSO) clients.
+ *
+ * Layer 1's input is the raw BIP-39 entropy of the root account — 16 or 32
+ * bytes, *not* the 64-byte PBKDF2 seed. Terminal never sees it: the host applies
+ * layer 1 during the SSO handshake and sends only the 32-byte result.
+ *
+ * The scheme has parallel implementations in five languages — host-container
+ * (TS), host-encoding (Rust, canonical), sdk-swift, sdk-android and
+ * brevity-flutter (Dart) — so the shared artifact is the spec rather than a
+ * package: Swift, Kotlin and Dart cannot import a TS one. The safety net is the
+ * cross-language conformance suite, which the tests below pin against verbatim.
+ * Cite the spec, not any one implementation: mirrors drift.
+ *
+ * A follow-up lifts the two halves into their canonical homes without changing
+ * behaviour: `blake2b256Keyed` into `@parity/product-sdk-crypto` (the missing
+ * sibling of the `blake2b256` already there) and the pure derivation into
+ * `@parity/product-sdk-keys`, beside `product-account.ts`. The session wrapper
+ * below stays exactly as it is.
+ *
+ * @module
+ */
+
+/**
+ * Derive 32 bytes of deterministic entropy for a terminal session, scoped to the
+ * calling product and a caller key (RFC-0007 layers 2 + 3).
+ *
+ * Same wallet + product + key ⇒ same bytes; any difference ⇒ uncorrelated
+ * entropy. Because it derives from the wallet (not the device), the entropy is
+ * recreatable after device loss as long as the wallet is recoverable.
+ *
+ * @param session   - A QR-paired {@link UserSession}. Must carry
+ *   `rootEntropySource` (present since host-papp 0.8.6 / RFC-0007).
+ * @param productId - The calling product's identifier, used verbatim as the
+ *   layer-2 scope. Per host-spec §C.7 that is `<label>.dot` for a dotNS product
+ *   (e.g. `"my-app.dot"`), or `localhost:<port>` — no `.dot` suffix — for local
+ *   dev. It is case-sensitive and is **not** normalized here: `"My-App.dot"`,
+ *   `"my-app.dot "` and `"my-app.dot"` derive three uncorrelated entropies.
+ *
+ *   This must be the identifier the *in-container* deployment is served under —
+ *   the same value you pass as `productId` to `getBulletinSigner` and as
+ *   `options.productId` to `requestResourceAllocation` — because that is the
+ *   scope the host derives against. It is **not** `adapter.appId`: the adapter
+ *   id is a local namespace (cache keys, storage dir) and the two are
+ *   routinely different. The package's own example pairs
+ *   `createTerminalAdapter({ appId: "my-cli" })` with
+ *   `getBulletinSigner(adapter, "my-cli.dot")`. Note that
+ *   `requestResourceAllocation` falls back to `adapter.appId` when
+ *   `options.productId` is omitted, so a call relying on that default is *not*
+ *   a reliable reference point for this argument.
+ *
+ *   The host takes the scope from the iframe's deployment label rather than
+ *   from the caller, so it differs per deployment: production, each PR preview
+ *   and local dev all scope to different entropy. A CLI that hardcodes the
+ *   production id derives valid-but-different bytes against a preview, with no
+ *   error anywhere.
+ *
+ *   Required and positional **by design** — do not give this a default. Unlike
+ *   an allocation request, a wrong product scope here fails silently: it yields
+ *   well-formed entropy that simply cannot decrypt anything.
+ * @param key       - Caller key, 1..32 bytes (the layer-3 BLAKE2b key). Both
+ *   bounds are normative: the spec requires zero-length and >32-byte keys to be
+ *   rejected, because some BLAKE2b implementations silently degrade an empty MAC
+ *   key to unkeyed mode.
+ * @returns 32 bytes of derived entropy.
+ * @throws if the session lacks `rootEntropySource` or carries one of the wrong
+ *   width, if `productId` is not a non-empty string, or if `key` is not 1..32
+ *   bytes.
+ *
+ * @remarks
+ * This reads nothing account-identifying, and a terminal may hold several paired
+ * sessions (see `waitForSessions`). Passing the wrong one yields valid entropy
+ * for a *different* wallet: the intended user cannot decrypt, and the other
+ * wallet's holder can. Pin the identity with `sessionRootPublicKey` before
+ * deriving long-lived keys.
+ *
+ * The return value is raw key material — do not log it or persist it unwrapped.
+ */
+declare function deriveEntropy(session: UserSession, productId: string, key: Uint8Array): Uint8Array;
+
 /**
  * Terminal QR code rendering using Unicode half-block characters.
  *
@@ -286,4 +387,4 @@ declare function renderQrCode(data: string, options?: QrRenderOptions): Promise<
  */
 declare function createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter;
 
-export { INCOMPLETE_SESSION_MESSAGE, type ProductAccountRef, type ProductSubtreeOptions, type QrRenderOptions, type SessionSignerOptions, type StatementStoreEnvironment, StatementStoreNetworks, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, deriveProductPublicKey, getBulletinSigner, getProductSubtreePublicKey, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, renderQrCode, sessionRootPublicKey, waitForSessions };
+export { INCOMPLETE_SESSION_MESSAGE, type ProductAccountRef, type ProductSubtreeOptions, type QrRenderOptions, type SessionSignerOptions, type StatementStoreEnvironment, StatementStoreNetworks, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, deriveEntropy, deriveProductPublicKey, getBulletinSigner, getProductSubtreePublicKey, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, renderQrCode, sessionRootPublicKey, waitForSessions };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { cacheFilePath, withFileLock, loadJsonCache, saveJsonCache } from './chunk-EORPX5XL.js';
-export { requestResourceAllocation, sendResourceAllocation } from './chunk-EORPX5XL.js';
+import { cacheFilePath, withFileLock, loadJsonCache, saveJsonCache } from './chunk-L75TTEEA.js';
+export { requestResourceAllocation, sendResourceAllocation } from './chunk-L75TTEEA.js';
 import { createNodeStorageAdapter, sanitizeKey } from './chunk-GHOFKVUG.js';
 export { createNodeStorageAdapter } from './chunk-GHOFKVUG.js';
 import { SS_PREVIEW_STAGE_ENDPOINTS, createPappAdapter, AllowanceError } from '@novasamatech/host-papp';
@@ -10,12 +10,14 @@ import { getWsProvider } from '@polkadot-api/ws-provider';
 import { deriveProductAccountPublicKey } from '@parity/product-sdk-keys';
 import { AllowanceExpiredError } from '@parity/product-sdk-signer/errors';
 export { AllowanceExpiredError, SignerError } from '@parity/product-sdk-signer/errors';
+import { createHostTxCreator } from '@parity/product-sdk-host/tx-creator';
 import { toHex, fromHex } from '@polkadot-api/utils';
 import { gcm } from '@noble/ciphers/aes.js';
 import { blake2b } from '@noble/hashes/blake2.js';
 import { readFile } from 'fs/promises';
 import { join } from 'path';
 import { Enum, _void, Struct, str, Bytes, Vector } from 'scale-ts';
+import '@noble/hashes/utils.js';
 
 var StatementStoreNetworks = {
   // host-papp has no constant for this host; its `SS_PASEO_STABLE_STAGE_ENDPOINTS`
@@ -196,30 +198,20 @@ function toAllowanceExpiredError(error) {
 function toProductAccountId(ref) {
   return [ref.productId, { tag: "Index", value: ref.derivationIndex }];
 }
-function buildCreateTransactionRequest(productAccountId, callData, signedExtensions, txExtVersion) {
-  const checkGenesis = signedExtensions.CheckGenesis;
-  if (!checkGenesis) {
-    throw new Error(
-      "Cannot build transaction: chain did not provide the CheckGenesis signed extension"
-    );
-  }
+function buildCreateTransactionRequest(productAccountId, request) {
   return {
     payload: {
       tag: "v1",
       value: {
         signer: productAccountId,
-        // CheckGenesis carries the genesis hash as its additionalSigned (implicit) data.
-        // `toHex` is typed `string`; the codec wants the 0x literal type.
-        genesisHash: toHex(checkGenesis.additionalSigned),
-        callData,
-        extensions: Object.values(signedExtensions).map(
-          ({ identifier, value, additionalSigned }) => ({
-            id: identifier,
-            extra: value,
-            additionalSigned
-          })
-        ),
-        txExtVersion
+        genesisHash: request.genesisHash,
+        callData: fromHex(request.callData),
+        extensions: request.extensions.map(({ id, extra, additionalSigned }) => ({
+          id,
+          extra: fromHex(extra),
+          additionalSigned: fromHex(additionalSigned)
+        })),
+        txExtVersion: request.txExtVersion
       }
     }
   };
@@ -233,17 +225,6 @@ async function requestSignedTransaction(session, request) {
   }
   return result.value;
 }
-function makeTxSignTx(session, productAccountId, txExtVersion) {
-  return async (callData, signedExtensions) => requestSignedTransaction(
-    session,
-    buildCreateTransactionRequest(
-      productAccountId,
-      callData,
-      signedExtensions,
-      txExtVersion
-    )
-  );
-}
 function makeRawBytesSignCallback(session, productAccountId) {
   return async (data) => {
     const result = await session.signRaw({
@@ -274,17 +255,17 @@ async function deriveProductPublicKey(session, ref, options) {
 async function buildSessionSigner(session, ref, options) {
   const productAccountId = toProductAccountId(ref);
   const publicKey = ref.publicKey ?? await deriveProductPublicKey(session, ref, options);
-  return {
+  return createHostTxCreator(
     publicKey,
-    // Transaction signing → host-papp `createTransaction`: the wallet builds
-    // and signs the extrinsic, so it can show a decoded tx (no `<Bytes>`
-    // envelope) and unknown signed extensions (e.g. `AsPgas`) survive.
-    signTx: makeTxSignTx(session, productAccountId, options?.txExtVersion ?? 0),
-    // Arbitrary-byte signing keeps the `Bytes` tag so the wallet applies the
-    // `<Bytes>...</Bytes>` anti-phishing envelope exactly once on its side
-    // (correct for non-extrinsic user data).
-    signBytes: makeRawBytesSignCallback(session, productAccountId)
-  };
+    async (request) => toHex(
+      await requestSignedTransaction(
+        session,
+        buildCreateTransactionRequest(productAccountId, request)
+      )
+    ),
+    makeRawBytesSignCallback(session, productAccountId),
+    options?.txExtVersion ?? 0
+  );
 }
 function createSessionSigner(session, adapter, publicKey, options) {
   return buildSessionSigner(
@@ -346,6 +327,8 @@ function resolveSessionId(adapter, sessionId) {
 async function getBulletinSigner(adapter, productId, sessionId) {
   const resolvedSessionId = resolveSessionId(adapter, sessionId);
   return adapter.allowance.getBulletinSigner(resolvedSessionId, productId).match(
+    // host-papp 0.12 builds this with `getTxCreator`, so it carries
+    // `publicKey` and `signBytes`, but its declared type is plain `TxCreator`.
     (signer) => signer,
     (err) => {
       throw err;
@@ -402,6 +385,33 @@ function waitForSessions(adapter, timeoutMs = 3e3) {
     });
   });
 }
+var ROOT_ENTROPY_SOURCE_LEN = 32;
+var MAX_KEY_LEN = 32;
+var textEncoder = new TextEncoder();
+var b2 = (message, key) => key ? blake2b(message, { dkLen: 32, key }) : blake2b(message, { dkLen: 32 });
+function deriveEntropy(session, productId, key) {
+  const rootEntropySource = session.rootEntropySource;
+  if (!rootEntropySource) {
+    throw new Error(
+      'deriveEntropy: stored login session is missing rootEntropySource. Run "logout" and then "login" to pair again with an RFC-0007 host.'
+    );
+  }
+  if (rootEntropySource.length !== ROOT_ENTROPY_SOURCE_LEN) {
+    throw new Error(
+      `deriveEntropy: rootEntropySource must be ${ROOT_ENTROPY_SOURCE_LEN} bytes, got ${rootEntropySource.length}. The session is corrupt or the host emitted a non-conforming width; re-pairing will not help if the host is at fault.`
+    );
+  }
+  if (typeof productId !== "string" || productId.length === 0) {
+    throw new Error(
+      `deriveEntropy: productId must be a non-empty string, got ${typeof productId === "string" ? "an empty string" : String(productId)}`
+    );
+  }
+  if (key.length === 0 || key.length > MAX_KEY_LEN) {
+    throw new Error(`deriveEntropy: key must be 1..${MAX_KEY_LEN} bytes, got ${key.length}`);
+  }
+  const perProduct = b2(rootEntropySource, b2(textEncoder.encode(productId)));
+  return b2(perProduct, key);
+}
 
 // src/qr-encode.ts
 async function renderQrCode(data, options) {
@@ -414,6 +424,6 @@ async function renderQrCode(data, options) {
   return result;
 }
 
-export { INCOMPLETE_SESSION_MESSAGE, StatementStoreNetworks, createSessionSigner, createSessionSignerForAccount, createTerminalAdapter, deriveProductPublicKey, getBulletinSigner, getProductSubtreePublicKey, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, isBenignTeardownError, renderQrCode, sessionRootPublicKey, waitForSessions };
+export { INCOMPLETE_SESSION_MESSAGE, StatementStoreNetworks, createSessionSigner, createSessionSignerForAccount, createTerminalAdapter, deriveEntropy, deriveProductPublicKey, getBulletinSigner, getProductSubtreePublicKey, getStatementStoreProver, hasBulletinAllowance, hasStatementStoreAllowance, isBenignTeardownError, renderQrCode, sessionRootPublicKey, waitForSessions };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map