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

package/src/transport.ts

@@ -0,0 +1,181 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Access to the in-house TruAPI client (`@parity/truapi`) for the host package.
+ *
+ * Environment detection and the lazily-built, cached client come from
+ * `@parity/truapi/sandbox`; this module layers the product-sdk-specific glue on
+ * top — an async {@link getClient} accessor and {@link subscribeWithInterrupt},
+ * which adapts a truapi stream into the host's {@link HostSubscription} shape.
+ *
+ * @module
+ */
+
+import type { ObservableLike, TrUApiClient } from "@parity/truapi";
+import {
+    getClientSync as sandboxGetClientSync,
+    isCorrectEnvironment as sandboxIsCorrectEnvironment,
+} from "@parity/truapi/sandbox";
+
+import type { HostSubscription } from "./types.js";
+
+/** A {@link HostSubscription} carrying the transport-assigned subscription id. */
+export interface TransportSubscription extends HostSubscription {
+    readonly subscriptionId: string;
+}
+
+// Test-only override. When set — via `setTruApiClient`, exposed through
+// `@parity/product-sdk-host/testing` — every host accessor resolves this client
+// instead of the sandbox one. `null` in production, so the branches below are
+// no-ops there.
+let clientOverride: TrUApiClient | null = null;
+
+function isProductionBuild(): boolean {
+    try {
+        // Must stay a plain `process.env.NODE_ENV` member expression: bundlers
+        // (Vite, esbuild, webpack) substitute it textually, which is how this
+        // check works in browser builds where `process` doesn't exist.
+        return process.env.NODE_ENV === "production";
+    } catch {
+        // No `process` and no bundler define — can't tell, stay quiet.
+        return false;
+    }
+}
+
+/**
+ * Test-only seam: force {@link getClient} / {@link getClientSync} to return
+ * `client`, and {@link isCorrectEnvironment} to report `true`. Pass `null` to
+ * restore normal detection. Exposed through `@parity/product-sdk-host/testing`,
+ * not the package's main entry.
+ *
+ * Calling this in a production build silently reroutes every host accessor to
+ * the injected client, so we warn — it almost always means a `/testing` import
+ * leaked into a production path.
+ */
+export function setTruApiClient(client: TrUApiClient | null): void {
+    if (client !== null && isProductionBuild()) {
+        console.warn(
+            "[product-sdk] setTruApiClient() was called in a production build. This is a test-only seam from @parity/product-sdk-host/testing; a leaked import will silently reroute all host access to the injected client.",
+        );
+    }
+    clientOverride = client;
+}
+
+/**
+ * Synchronous TruAPI client accessor. Returns the injected test client when one
+ * is set, otherwise the sandbox client (`null` outside a host container).
+ */
+export function getClientSync(): TrUApiClient | null {
+    return clientOverride ?? sandboxGetClientSync();
+}
+
+/**
+ * Host-container detection. `true` when a test client is injected, otherwise the
+ * sandbox heuristic (iframe / webview marker / injected message port).
+ */
+export function isCorrectEnvironment(): boolean {
+    return clientOverride !== null || sandboxIsCorrectEnvironment();
+}
+
+/**
+ * Get the TruAPI client. Returns `null` outside a host container. Async wrapper
+ * over {@link getClientSync} for the host wrappers that already `await` it.
+ */
+export async function getClient(): Promise<TrUApiClient | null> {
+    return getClientSync();
+}
+
+/**
+ * Adapt a truapi `ObservableLike` stream into the host's callback-style
+ * {@link HostSubscription} (`unsubscribe` + `onInterrupt`). `onNext` fires for
+ * each item; the registered `onInterrupt` callback fires when the host ends the
+ * subscription server-side — which the generated client surfaces as either
+ * `complete` (a host interrupt frame) or `error` (transport close). Shared by
+ * the statement-store and preimage adapters, which both expose this shape.
+ */
+export function subscribeWithInterrupt<Item, Reason = never>(
+    observable: ObservableLike<Item, Reason>,
+    onNext: (item: Item) => void,
+): TransportSubscription {
+    let interruptCallback: ((reason?: unknown) => void) | undefined;
+    const sub = observable.subscribe({
+        next: onNext,
+        error: (reason) => interruptCallback?.(reason),
+        complete: () => interruptCallback?.(),
+    });
+    return {
+        subscriptionId: sub.subscriptionId,
+        unsubscribe: () => sub.unsubscribe(),
+        onInterrupt: (callback) => {
+            interruptCallback = callback;
+            return () => {
+                if (interruptCallback === callback) interruptCallback = undefined;
+            };
+        },
+    };
+}
+
+if (import.meta.vitest) {
+    const { test, expect, afterEach } = import.meta.vitest;
+
+    afterEach(() => setTruApiClient(null));
+
+    // Environment detection and client building are covered by `@parity/truapi`'s
+    // own sandbox tests; here we only assert the local glue degrades outside a
+    // host container.
+    test("getClientSync returns null outside a container", () => {
+        expect(getClientSync()).toBeNull();
+    });
+
+    test("getClient resolves null outside a container", async () => {
+        expect(await getClient()).toBeNull();
+    });
+
+    test("setTruApiClient overrides the client and container detection", async () => {
+        const fake = {} as TrUApiClient;
+        setTruApiClient(fake);
+        expect(getClientSync()).toBe(fake);
+        expect(await getClient()).toBe(fake);
+        expect(isCorrectEnvironment()).toBe(true);
+
+        setTruApiClient(null);
+        expect(getClientSync()).toBeNull();
+        expect(isCorrectEnvironment()).toBe(false);
+    });
+
+    test("setTruApiClient warns when injecting in a production build", () => {
+        const original = process.env.NODE_ENV;
+        const warnings: string[] = [];
+        const realWarn = console.warn;
+        console.warn = (...args: unknown[]) => void warnings.push(String(args[0]));
+        try {
+            process.env.NODE_ENV = "production";
+            setTruApiClient({} as TrUApiClient);
+            expect(warnings).toHaveLength(1);
+            expect(warnings[0]).toContain("production build");
+
+            // Clearing the override must not warn.
+            setTruApiClient(null);
+            expect(warnings).toHaveLength(1);
+        } finally {
+            console.warn = realWarn;
+            process.env.NODE_ENV = original;
+        }
+    });
+
+    test("subscribeWithInterrupt preserves the transport subscription id", () => {
+        const observable = {
+            subscribe: () => ({
+                subscriptionId: "p:17",
+                unsubscribe: () => {},
+            }),
+            [Symbol.observable]() {
+                return this;
+            },
+        } as ObservableLike<never>;
+
+        const subscription = subscribeWithInterrupt(observable, () => {});
+
+        expect(subscription.subscriptionId).toBe("p:17");
+    });
+}

package/src/truapi.ts

@@ -0,0 +1,313 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * TruAPI - the protocol for communicating between apps and the Polkadot host container.
+ *
+ * This module centralizes access to the in-house `@parity/truapi` client,
+ * allowing other `@parity/product-sdk-*` packages to import from here rather
+ * than depending directly on the protocol package. The client is built and
+ * cached by {@link module:transport}; this module adds the accessor plus the
+ * two helpers the convenience wrappers fold truapi's `ResultAsync` through —
+ * {@link mapHostResult} (returns a `Result`, used by the public operations) and
+ * {@link unwrapHostResult} (throws, used by the adapter-object methods).
+ *
+ * @module
+ */
+
+import { scale } from "@parity/truapi";
+import type {
+    AllocatableResource,
+    AllocationOutcome,
+    HexString,
+    RemotePermission,
+    TrUApiClient,
+} from "@parity/truapi";
+import { createLogger } from "@parity/product-sdk-logger";
+
+import {
+    type HostError,
+    type HostErrorPayload,
+    HostCallFailedError,
+    HostUnavailableError,
+    formatHostError,
+} from "./errors.js";
+import { type Result, err, ok } from "./result.js";
+import { getClient, subscribeWithInterrupt } from "./transport.js";
+import type { HostSubscription, Statement, StatementProof } from "./types.js";
+
+const log = createLogger("host");
+
+/**
+ * Await a host `ResultAsync`, returning its Ok value or throwing a diagnostic
+ * `Error` built from the host's error payload (preserved as `cause`).
+ *
+ * This is the *throwing* helper, retained for the methods of the adapter objects
+ * returned by the feature-detection getters (`PreimageManager.submit`,
+ * `HostLocalStorage.read`, `AccountsProvider` signing, …). Those objects often
+ * implement external interfaces (e.g. polkadot-api's `JsonRpcProvider`) whose
+ * method signatures can't carry a {@link Result}, so they keep the
+ * throw convention. The flat public operations use {@link mapHostResult} instead.
+ */
+export function unwrapHostResult<T, E>(result: ResultAsync<T, E>, label: string): Promise<T> {
+    return result.match(
+        (value) => value,
+        (error: E) => {
+            throw new Error(`${label}: ${formatHostError(error)}`, { cause: error });
+        },
+    );
+}
+
+/**
+ * Await a host `ResultAsync` and fold it into a tagged {@link Result}: maps the
+ * Ok value through `map`, or wraps the host error payload in a
+ * {@link HostCallFailedError} on the `err` channel. This is the non-throwing
+ * boundary the flat public host operations (`requestPermission`, `deriveEntropy`,
+ * `requestResourceAllocation`, …) return through.
+ */
+export function mapHostResult<T, U>(
+    result: ResultAsync<T, HostErrorPayload>,
+    map: (value: T) => U,
+    label: string,
+): Promise<Result<U, HostError>> {
+    return result.match(
+        (value) => ok(map(value)),
+        (error) => err(new HostCallFailedError(label, error)),
+    );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hex helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Convert bytes to a `0x`-prefixed lower-case hex string. */
+export function toHex(bytes: Uint8Array): HexString {
+    return scale.bytesToHex(bytes);
+}
+
+/** Convert a hex string (with or without `0x`) to bytes. */
+export function fromHex(hex: string): Uint8Array {
+    return scale.hexToBytes(hex);
+}
+
+/** A `0x`-prefixed hex string used by the host API surface for raw byte payloads. */
+export type { HexString };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TruAPI accessor
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The TruApi client — namespaced access to every host protocol domain
+ * (`permissions`, `entropy`, `signing`, `statementStore`, `system`,
+ * `localStorage`, …). Identical to `TrUApiClient` from `@parity/truapi`.
+ *
+ * @example
+ * ```ts
+ * const truApi = await getTruApi();
+ * if (truApi) {
+ *   await truApi.permissions.requestRemotePermission({
+ *     permission: { tag: "ChainSubmit", value: undefined },
+ *   });
+ *   await truApi.system.navigateTo({ url: "polkadot://settings" });
+ * }
+ * ```
+ */
+export type TruApi = TrUApiClient;
+
+/**
+ * Get the TruAPI client for direct low-level access to host protocol domains.
+ *
+ * Returns the cached `@parity/truapi` client once the host transport is built
+ * and the handshake has run, or `null` when running outside a container.
+ *
+ * For most use cases, prefer the higher-level functions like
+ * {@link requestPermission}, {@link deriveEntropy}, or `getHostLocalStorage()`.
+ *
+ * @returns The TruAPI client, or `null` if unavailable.
+ */
+export async function getTruApi(): Promise<TruApi | null> {
+    return getClient();
+}
+
+/**
+ * Preimage manager handle for bulletin chain operations, backed by
+ * `truApi.preimage.*`. `lookup` opens a {@link HostSubscription} (`unsubscribe`
+ * + `onInterrupt`) that delivers the preimage bytes — or `null` until the host
+ * finds them; `submit` uploads a preimage and resolves to its `0x`-prefixed hex
+ * key.
+ */
+export interface PreimageManager {
+    lookup(key: HexString, callback: (preimage: Uint8Array | null) => void): HostSubscription;
+    submit(value: Uint8Array): Promise<HexString>;
+}
+
+/** Build a {@link PreimageManager} over a TruAPI client's `preimage` domain. */
+function adaptPreimageManager(client: TrUApiClient): PreimageManager {
+    const preimage = client.preimage;
+    return {
+        lookup(key, callback) {
+            return subscribeWithInterrupt(preimage.lookupSubscribe({ request: { key } }), (item) =>
+                callback(item.value !== undefined ? fromHex(item.value) : null),
+            );
+        },
+        submit(value) {
+            return unwrapHostResult(preimage.submit(toHex(value)), "preimage submit failed");
+        },
+    };
+}
+
+/**
+ * Get the preimage manager for bulletin chain operations.
+ *
+ * @returns The preimage manager, or `null` if unavailable (outside a container).
+ */
+export async function getPreimageManager(): Promise<PreimageManager | null> {
+    const client = await getClient();
+    return client ? adaptPreimageManager(client) : null;
+}
+
+/**
+ * Construct a `PreimageManager`. Retained for API compatibility; with the single
+ * cached TruAPI client this is equivalent to {@link getPreimageManager}.
+ *
+ * @returns A `PreimageManager` instance, or `null` if unavailable.
+ */
+export async function createHostPreimageManager(): Promise<PreimageManager | null> {
+    return getPreimageManager();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Resource allocation
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Resource-allocation / permission types, re-exported verbatim from
+// `@parity/truapi` (imported above for the local signatures):
+// - `AllocatableResource` — resource types requestable via `requestResourceAllocation`.
+//   Its `SmartContractAllowance` variant carries the tagged `DerivationIndex`
+//   selector (`{ tag: "Index", value: number }` for a plain index, `{ tag:
+//   "Raw", value: HexString }` for a raw 32-byte index).
+// - `AllocationOutcome` — per-resource outcome, the string union
+//   `"Allocated" | "Rejected" | "NotAvailable"` (RFC-10).
+// - `RemotePermission` — permission the dapp asks the host to grant via `requestPermission`.
+export type { AllocatableResource, AllocationOutcome, RemotePermission };
+
+/**
+ * Request the host to pre-allocate one or more resource allowances.
+ *
+ * The host prompts the user once; subsequent operations covered by the
+ * granted allowance don't re-prompt.
+ *
+ * @param resources - Resources to request.
+ * @returns `ok` with per-resource outcomes in the same order as `resources`, or
+ *   `err(HostUnavailableError | HostCallFailedError)`.
+ *
+ * @example
+ * ```ts
+ * const r = await requestResourceAllocation([
+ *   { tag: "BulletinAllowance", value: undefined },
+ * ]);
+ * if (r.ok && r.value[0] === "Allocated") { ... }
+ * ```
+ */
+export async function requestResourceAllocation(
+    resources: AllocatableResource[],
+): Promise<Result<AllocationOutcome[], HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("requestResourceAllocation: TruAPI unavailable"));
+    }
+    log.debug("requestResourceAllocation", { resources: resources.map((r) => r.tag) });
+
+    return mapHostResult(
+        truApi.resourceAllocation.request({ resources }),
+        (response) => response.outcomes,
+        "requestResourceAllocation failed",
+    );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Authorized Statement Store proof creation (RFC-10 §"Statement Store allowance")
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Have the host sign a Statement using the product's allowance-bearing account,
+ * which it picks internally — RFC-10 §"Statement Store allowance". No per-call
+ * account id is needed (this is the sponsored-submission path).
+ *
+ * Pairs with {@link getStatementStore}'s `submit`: call this to obtain a proof,
+ * attach it to the Statement, and submit the result.
+ *
+ * @param statement - The Statement to be signed.
+ * @returns `ok` with the proof to attach before submitting, or
+ *   `err(HostUnavailableError | HostCallFailedError)`.
+ */
+export async function createProofAuthorized(
+    statement: Statement,
+): Promise<Result<StatementProof, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("createProofAuthorized: TruAPI unavailable"));
+    }
+    log.debug("createProofAuthorized", { topics: statement.topics.length });
+
+    return mapHostResult(
+        truApi.statementStore.createProofAuthorized(statement),
+        (response) => response.proof,
+        "createProofAuthorized failed",
+    );
+}
+
+/**
+ * Neverthrow-style ResultAsync returned by product-sdk methods.
+ *
+ * Use `.match(onOk, onErr)` to handle success/error cases.
+ */
+export interface ResultAsync<T, E> {
+    match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+if (import.meta.vitest) {
+    const { test, expect } = import.meta.vitest;
+
+    test("getTruApi returns null outside a container", async () => {
+        const api = await getTruApi();
+        expect(api === null || typeof api === "object").toBe(true);
+    });
+
+    test("getPreimageManager returns manager or null", async () => {
+        const manager = await getPreimageManager();
+        expect(manager === null || typeof manager === "object").toBe(true);
+    });
+
+    test("createHostPreimageManager returns null outside container", async () => {
+        expect(await createHostPreimageManager()).toBeNull();
+    });
+
+    test("hex helpers", () => {
+        expect(toHex(new Uint8Array([0xde, 0xad]))).toBe("0xdead");
+        expect(Array.from(fromHex("0xdead"))).toEqual([0xde, 0xad]);
+    });
+
+    test("requestResourceAllocation returns err when TruAPI is unavailable", async () => {
+        const api = await getTruApi();
+        if (api === null) {
+            const result = await requestResourceAllocation([
+                { tag: "BulletinAllowance", value: undefined },
+            ]);
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(HostUnavailableError);
+            }
+        } else {
+            expect(typeof requestResourceAllocation).toBe("function");
+        }
+    });
+
+    test("createProofAuthorized is callable", () => {
+        expect(typeof createProofAuthorized).toBe("function");
+    });
+}

package/src/types.ts

@@ -0,0 +1,101 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Public types for the host wrappers.
+ *
+ * The statement-store types are re-exported from `@parity/truapi` so the Parity
+ * surface stays in lockstep with the in-house protocol codec types. Their fields
+ * are `0x`-prefixed hex strings (`HexString`) and their enums are `{ tag }` unions.
+ */
+
+import type {
+    ProductAccountId,
+    RemoteStatementStoreSubscribeItem,
+    SignedStatement,
+    Statement,
+    StatementProof,
+    Topic,
+} from "@parity/truapi";
+
+// Statement-store types, re-exported verbatim from `@parity/truapi` (imported
+// above for the local signatures): `Statement` / `SignedStatement` /
+// `StatementProof` / `Topic` / `ProductAccountId`. Their fields are
+// `0x`-prefixed `HexString`s and their enums are `{ tag }` unions; the proof
+// variants cover `Sr25519` / `Ed25519` / `Ecdsa` / `OnChain`.
+export type { ProductAccountId, SignedStatement, Statement, StatementProof, Topic };
+
+/**
+ * Persistent storage exposed by the host container, including string, JSON
+ * and raw byte (`readBytes`/`writeBytes`) accessors. Most apps reach it
+ * indirectly through the Storage package's `KvStore`; reach for it directly
+ * via {@link getHostLocalStorage} when you need raw host storage without the
+ * KV abstraction.
+ *
+ * Backed by `truApi.localStorage.*` (raw `read`/`write`/`clear` over hex bytes);
+ * {@link getHostLocalStorage} adapts that into this richer surface. `readString`
+ * resolves to `""` for a missing key and `readJSON`/`readBytes` to
+ * `null`/`undefined`.
+ */
+export interface HostLocalStorage {
+    /** Read a UTF-8 string value; `""` when the key is absent. */
+    readString(key: string): Promise<string>;
+    /** Write a UTF-8 string value. */
+    writeString(key: string, value: string): Promise<void>;
+    /** Read and JSON-parse a value; `null` when the key is absent. */
+    readJSON(key: string): Promise<unknown>;
+    /** JSON-stringify and write a value. */
+    writeJSON(key: string, value: unknown): Promise<void>;
+    /** Read raw bytes; `undefined` when the key is absent. */
+    readBytes(key: string): Promise<Uint8Array | undefined>;
+    /** Write raw bytes. */
+    writeBytes(key: string, value: Uint8Array): Promise<void>;
+    /** Remove a key. */
+    clear(key: string): Promise<void>;
+}
+
+/**
+ * Topic-based subscription filter. The host delivers statements that match
+ * either *all* of the listed topics (`matchAll`) or *any* of them (`matchAny`).
+ *
+ * This is a field-discriminated form of truapi's `RemoteStatementStoreSubscribeRequest`,
+ * which is a tagged union (`{ tag: "MatchAll"; value: Topic[] } | { tag: "MatchAny"; value: Topic[] }`).
+ * The transport maps between the two.
+ */
+export type StatementTopicFilter = { matchAll: Topic[] } | { matchAny: Topic[] };
+
+/**
+ * A page of signed statements delivered by {@link HostStatementStore.subscribe}.
+ *
+ * truapi's `RemoteStatementStoreSubscribeItem`, re-exported under a friendlier
+ * name. Pages arrive sequentially; `isComplete` is `false` while the host
+ * streams the historical backfill and `true` once it's done (and on every
+ * subsequent live-update page).
+ */
+export type StatementsPage = RemoteStatementStoreSubscribeItem;
+
+/**
+ * Subscription handle returned by the host. Exposes `unsubscribe()` plus an
+ * `onInterrupt` hook that fires if the host interrupts the subscription
+ * server-side; `onInterrupt` returns a function that cancels the hook.
+ */
+export interface HostSubscription {
+    unsubscribe(): void;
+    onInterrupt(callback: (reason?: unknown) => void): () => void;
+}
+
+/**
+ * Statement Store handle exposed by the host container, backed by
+ * `truApi.statementStore.*`. `subscribe` streams matching statements;
+ * `createProofAuthorized` signs a statement with the product's RFC-10 allowance
+ * account (the sponsored path — no per-call account id); `submit` publishes a
+ * signed statement. The `statement-store` package layers a higher-level client
+ * on top.
+ */
+export interface HostStatementStore {
+    subscribe(
+        filter: StatementTopicFilter,
+        callback: (page: StatementsPage) => void,
+    ): HostSubscription;
+    createProofAuthorized(statement: Statement): Promise<StatementProof>;
+    submit(signedStatement: SignedStatement): Promise<void>;
+}