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

package/dist/index.d.ts

@@ -1,13 +1,50 @@
-import { T as TerminalAdapter } from './host-C3KVvc1j.js';
-export { A as AllocatableResource, a as ApAllocationOutcome, O as OnExistingAllowancePolicy, R as RequestResourceAllocationOptions, b as TerminalAdapterOptions, c as createTerminalAdapter, r as requestResourceAllocation, s as sendResourceAllocation } from './host-C3KVvc1j.js';
+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 { UserSession } from '@novasamatech/host-papp';
-export { AllowanceError, AllowanceErrorReason, AllowanceService, HostMetadata, PairingStatus, PappAdapter, SS_PASEO_STABLE_STAGE_ENDPOINTS, SS_STABLE_STAGE_ENDPOINTS, SigningPayloadRequest, SigningPayloadResponse, SigningRawRequest, StoredUserSession, 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';
 export { AllowanceExpiredError, SignerError } from '@parity/product-sdk-signer/errors';
 import { StatementProver } from '@novasamatech/statement-store';
 import { StorageAdapter } from '@novasamatech/storage-adapter';
 import 'neverthrow';
 
+/**
+ * Statement store networks terminal can pair against, keyed as `BULLETIN_RPCS`
+ * in `@parity/product-sdk-host`, where `paseo` is Paseo Next v2.
+ *
+ * Both sides of a pairing must sit on the same people chain. The Polkadot app's
+ * nightly build uses `paseo`, which is why it is the default.
+ */
+
+declare const StatementStoreNetworks: {
+    paseo: string[];
+    previewnet: string[];
+};
+
+/** Network keys with built-in endpoints in {@link StatementStoreNetworks}. */
+type StatementStoreEnvironment = keyof typeof StatementStoreNetworks;
+
+/**
+ * The product-subtree public key of `//product//{productId}` (RFC-0022).
+ *
+ * The request is consent-free and cacheable. The disk layer is what makes that
+ * worth having: without it every CLI command would need the phone reachable
+ * just to render a product address.
+ */
+
+interface ProductSubtreeOptions {
+    /** Names the cache file. Defaults to the productId. */
+    appId?: string;
+    storageDir?: string;
+}
+/**
+ * Fetch the subtree public key for `productId`, reaching the wallet only on a
+ * cold cache.
+ *
+ * @throws Error when the wallet rejects the request or returns a malformed key.
+ */
+declare function getProductSubtreePublicKey(session: UserSession, productId: string, options?: ProductSubtreeOptions): Promise<Uint8Array>;
+
 /**
  * Create a PolkadotSigner from a QR-paired session.
  *
@@ -37,10 +74,10 @@ import 'neverthrow';
  * const [session] = adapter.sessions.sessions.read();
  *
  * // Default account — uses [adapter.appId, 0]:
- * const signer = createSessionSigner(session, adapter);
+ * const signer = await createSessionSigner(session, adapter);
  *
  * // Non-default derivation index, or a different productId:
- * const subSigner = createSessionSignerForAccount(session, {
+ * const subSigner = await createSessionSignerForAccount(session, {
  *     productId: "my-product",
  *     derivationIndex: 3,
  * });
@@ -52,7 +89,7 @@ import 'neverthrow';
 /**
  * Identifies which sub-account of a paired session should sign.
  *
- * Mirrors the `host-papp` wire format `productAccountId: [productId, derivationIndex]`:
+ * Mirrors the `host-papp` wire format `productAccountId: [productId, index]`:
  * `productId` is the dotNS-style identifier for the requesting product (matches
  * the adapter's `appId` in normal usage); `derivationIndex` is the BIP32-style
  * child-key index, where `0` is the session's default account.
@@ -66,46 +103,41 @@ interface ProductAccountRef {
      * The **product account's** sr25519 public key (32 bytes), as derived by the
      * host for `[productId, derivationIndex]`.
      *
-     * PAPI stamps this into the extrinsic's signer address and verifies the
-     * signature against it, so it must be the *product* account's key — not the
-     * wallet's selected/root account (`session.remoteAccount.accountId`). A
-     * mismatch produces an invalid signature.
+     * PAPI stamps this into the extrinsic's signer address and verifies against
+     * it, so a mismatch produces an invalid signature.
      *
-     * When omitted, the signer soft-derives it from the session's root account
-     * (`mnemonic + "/product/{productId}/{derivationIndex}"`), which is correct
-     * for every product account. Supply it explicitly only to avoid the
-     * re-derivation or when you've already derived it elsewhere.
+     * When omitted, the signer fetches the subtree key and derives it. Supply it
+     * to skip that round trip.
      */
     publicKey?: Uint8Array;
 }
+interface SessionSignerOptions extends ProductSubtreeOptions {
+    /**
+     * Extension version of the supplied signTx bytes. Does not change encoding.
+     *
+     * Defaults to the lowest pipeline version the chain metadata declares that
+     * holds every supplied extension, which is 0 on a chain with one pipeline.
+     */
+    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.";
 /**
- * The session's handshake-time root account public key (`rootUserAccountId` =
- * the user's bare-mnemonic keypair on current mobile builds). This is the
- * parent key product accounts soft-derive from. host-papp's live `UserSession`
- * doesn't surface it on the public type, so we read it structurally.
+ * The wallet's own root account key. Product accounts do **not** derive from it:
+ * RFC-0022 puts two hard junctions in between.
  *
  * @throws {@link INCOMPLETE_SESSION_MESSAGE} if the session predates the
- *   `rootAccountId` field (a stale login that must re-pair).
+ *   `rootAccountId` field.
  */
 declare function sessionRootPublicKey(session: UserSession): Uint8Array;
 /**
- * Soft-derive a product account's sr25519 public key from a paired session's
- * root account.
- *
- * This is the single source of truth for product-account math. The session
- * signer uses it to stamp the correct signer address; consumers that need the
- * product address *without* building a signer (e.g. a login-status display
- * triple) call it directly so the displayed address can't desync from what the
- * signer actually signs with.
+ * The product account's sr25519 public key for `ref`.
  *
- * sr25519 soft derivation is composable on public keys alone, so deriving from
- * `session.rootAccountId` locally produces the SAME key the host derives
- * privately via `mnemonic + "/product/{productId}/{derivationIndex}"`.
+ * The one place product-account math happens, so a displayed address cannot
+ * desync from what the signer signs with.
  *
- * @throws {@link INCOMPLETE_SESSION_MESSAGE} on a stale session with no root key.
+ * @throws Error when the wallet is unreachable on a cold cache.
  */
-declare function deriveProductPublicKey(session: UserSession, ref: ProductAccountRef): Uint8Array;
+declare function deriveProductPublicKey(session: UserSession, ref: ProductAccountRef, options?: ProductSubtreeOptions): Promise<Uint8Array>;
 /**
  * Create a `PolkadotSigner` backed by a QR-paired mobile wallet session,
  * using the session's **default account** (`derivationIndex: 0`).
@@ -116,10 +148,10 @@ declare function deriveProductPublicKey(session: UserSession, ref: ProductAccoun
  * @param adapter The {@link TerminalAdapter} that loaded the session. Its `appId`
  *   is used as the `productId` in the wire request.
  * @param publicKey The product account's sr25519 public key for
- *   `[adapter.appId, 0]`. Optional — when omitted it's soft-derived from the
- *   session root. See {@link ProductAccountRef.publicKey}.
+ *   `[adapter.appId, 0]`. Optional — when omitted it's fetched and derived.
+ *   See {@link ProductAccountRef.publicKey}.
  */
-declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array): PolkadotSigner;
+declare function createSessionSigner(session: UserSession, adapter: TerminalAdapter, publicKey?: Uint8Array, options?: SessionSignerOptions): Promise<PolkadotSigner>;
 /**
  * Create a `PolkadotSigner` for a specific sub-account of a paired session.
  *
@@ -130,7 +162,7 @@ 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): PolkadotSigner;
+declare function createSessionSignerForAccount(session: UserSession, ref: ProductAccountRef, options?: SessionSignerOptions): Promise<PolkadotSigner>;
 
 /**
  * Get a `PolkadotSigner` for a Bulletin allowance slot.
@@ -223,6 +255,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.
  *
@@ -259,4 +384,4 @@ declare function renderQrCode(data: string, options?: QrRenderOptions): Promise<
  */
 declare function createNodeStorageAdapter(appId: string, storageDir?: string): StorageAdapter;
 
-export { INCOMPLETE_SESSION_MESSAGE, type ProductAccountRef, type QrRenderOptions, TerminalAdapter, createNodeStorageAdapter, createSessionSigner, createSessionSignerForAccount, deriveProductPublicKey, getBulletinSigner, 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 };