@parity/product-sdk-host 0.2.2 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as polkadot_api from 'polkadot-api';
 import { JsonRpcProvider } from 'polkadot-api';
+import { CodecType, AllocatableResource as AllocatableResource$1, AllocationOutcome as AllocationOutcome$1, RemotePermission as RemotePermission$1, Statement as Statement$1 } from '@novasamatech/host-api';
 export { HexString, assertEnumVariant, enumValue, fromHex, isEnumVariant, resultErr, resultOk, toHex, unwrapResultOrThrow } from '@novasamatech/host-api';
 
 /**
@@ -276,6 +277,108 @@ interface PreimageManager {
  * @returns The accounts provider, or `null` if unavailable.
  */
 declare function getAccountsProvider(): Promise<AccountsProvider | null>;
+/**
+ * Resource types requestable via {@link requestResourceAllocation}.
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+type AllocatableResource = CodecType<typeof AllocatableResource$1>;
+/** Tag-only view of {@link AllocatableResource} for places that just need the variant name. */
+type AllocatableResourceTag = AllocatableResource["tag"];
+/**
+ * Per-resource outcome from {@link requestResourceAllocation}.
+ * The host strips secret payloads from `Allocated` before returning, so
+ * `value` is always `undefined` on the product side.
+ */
+type AllocationOutcome = CodecType<typeof AllocationOutcome$1>;
+/** Tag-only view of {@link AllocationOutcome} (`"Allocated" | "Rejected" | "NotAvailable"`). */
+type AllocationOutcomeTag = AllocationOutcome["tag"];
+/**
+ * Remote permission the dapp can ask the host to grant via
+ * {@link requestPermission}.
+ *
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+type RemotePermission = CodecType<typeof RemotePermission$1>;
+/** Tag-only view of {@link RemotePermission}. */
+type RemotePermissionTag = RemotePermission["tag"];
+/**
+ * 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 Per-resource outcomes in the same order as `resources`.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const outcomes = await requestResourceAllocation([
+ *   { tag: "BulletInAllowance", value: undefined },
+ * ]);
+ * if (outcomes[0].tag === "Allocated") { ... }
+ * ```
+ */
+declare function requestResourceAllocation(resources: AllocatableResource[]): Promise<AllocationOutcome[]>;
+/**
+ * A Statement payload destined for the Statement Store. Matches the
+ * `pallet-statement` Statement structure.
+ *
+ * The optional `proof` field is the same {@link StatementProof} shape that
+ * {@link createProofAuthorized} returns: pass `undefined` here, call
+ * `createProofAuthorized` to obtain the proof, then attach it before
+ * submitting via `HostStatementStore.submit`. The `OnChain` variant of
+ * `StatementProof` is a chain-attestation reference; the `Sr25519` /
+ * `Ed25519` / `Ecdsa` variants are signing proofs.
+ *
+ * Derived from the upstream codec so structural changes surface as compile
+ * errors here, not runtime decode failures.
+ */
+type Statement = CodecType<typeof Statement$1>;
+/**
+ * Have the host sign a Statement using an allowance-bearing account it
+ * picks internally — RFC-10 §"Statement Store allowance".
+ *
+ * The product passes only the Statement payload; the host chooses the
+ * `//allowance//statement-store//{productId}` account that holds SSS
+ * allowance and signs with it. Allowance is provisioned implicitly on
+ * first use if the host hasn't already pre-allocated via
+ * {@link requestResourceAllocation}; products never see the signing
+ * account or its key material.
+ *
+ * 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 The proof to attach before submitting.
+ * @throws If the host is unavailable or the host-side signing fails.
+ *
+ * @example
+ * ```ts
+ * import { createProofAuthorized, getStatementStore } from "@parity/product-sdk-host";
+ *
+ * const statement = {
+ *     proof: undefined,
+ *     decryptionKey: undefined,
+ *     expiry: undefined,
+ *     channel: undefined,
+ *     topics: [],
+ *     data: payload,
+ * };
+ * const proof = await createProofAuthorized(statement);
+ * const store = await getStatementStore();
+ * await store?.submit({ ...statement, proof });
+ * ```
+ *
+ * @remarks
+ * RFC-10 introduces this as a new, strictly additive TruAPI call. The
+ * pre-existing `HostStatementStore.createProof(accountId, statement)`
+ * surface stays available for products that own a non-allowance signing
+ * account; this wrapper is the sponsored-submission path.
+ */
+declare function createProofAuthorized(statement: Statement): Promise<StatementProof>;
 /**
  * One of the user's existing wallet accounts, surfaced through the host and
  * identified by its public key and an optional name. Contrast with
@@ -397,4 +500,37 @@ interface AccountsProvider {
     } | (() => void);
 }
 
-export { type AccountsProvider, BULLETIN_RPCS, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type HostAccount, type HostLocalStorage, type HostStatementStore, type HostSubscription, type PreimageManager, type ProductAccount, type ResultAsync, type StatementProof, type StatementTopicFilter, type StatementsPage, type TruApi, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync };
+/**
+ * Higher-level wrapper for the host's single-permission flow.
+ *
+ * `hostApi.permission` takes a versioned envelope (`enumValue("v1", ...)`)
+ * and returns a neverthrow `ResultAsync` of an unwrapped versioned response.
+ * Consumers rebuild that wrap/unwrap dance every time. `requestPermission`
+ * collapses it to a one-liner that matches the shape of
+ * {@link requestResourceAllocation} (throws on error, returns the unwrapped
+ * payload on success).
+ *
+ * @module
+ */
+
+/**
+ * Request a single remote permission from the host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.permission`, unwraps the response,
+ * and returns the host's boolean granted/denied outcome.
+ *
+ * @param permission - The remote permission to request.
+ * @returns `true` if the host granted the permission, `false` if denied.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const granted = await requestPermission({ tag: "ChainSubmit", value: undefined });
+ * if (!granted) {
+ *   tellUserToReconnect();
+ * }
+ * ```
+ */
+declare function requestPermission(permission: RemotePermission): Promise<boolean>;
+
+export { type AccountsProvider, type AllocatableResource, type AllocatableResourceTag, type AllocationOutcome, type AllocationOutcomeTag, BULLETIN_RPCS, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type HostAccount, type HostLocalStorage, type HostStatementStore, type HostSubscription, type PreimageManager, type ProductAccount, type RemotePermission, type RemotePermissionTag, type ResultAsync, type Statement, type StatementProof, type StatementTopicFilter, type StatementsPage, type TruApi, createProofAuthorized, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync, requestPermission, requestResourceAllocation };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { createLogger } from '@parity/product-sdk-logger';
+import { enumValue } from '@novasamatech/host-api';
 export { assertEnumVariant, enumValue, fromHex, isEnumVariant, resultErr, resultOk, toHex, unwrapResultOrThrow } from '@novasamatech/host-api';
 
 // src/container.ts
@@ -58,6 +59,15 @@ var BULLETIN_RPCS = {
 };
 var DEFAULT_BULLETIN_ENDPOINT = BULLETIN_RPCS.paseo[0];
 var log = createLogger("host");
+function formatError(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
 var cachedTruApi = null;
 async function getTruApi() {
   if (cachedTruApi) return cachedTruApi;
@@ -87,7 +97,55 @@ async function getAccountsProvider() {
     return null;
   }
 }
+async function requestResourceAllocation(resources) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("requestResourceAllocation: TruAPI unavailable");
+  }
+  log.debug("requestResourceAllocation", { resources: resources.map((r) => r.tag) });
+  return await truApi.requestResourceAllocation(enumValue("v1", resources)).match(
+    (envelope) => envelope.value,
+    (err) => {
+      throw new Error(`requestResourceAllocation failed: ${formatError(err)}`, {
+        cause: err
+      });
+    }
+  );
+}
+async function createProofAuthorized(statement) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("createProofAuthorized: TruAPI unavailable");
+  }
+  log.debug("createProofAuthorized", {
+    topics: statement.topics.length,
+    dataLen: statement.data?.length ?? 0
+  });
+  return await truApi.statementStoreCreateProofAuthorized(enumValue("v1", statement)).match(
+    (envelope) => envelope.value,
+    (err) => {
+      throw new Error(`createProofAuthorized failed: ${formatError(err)}`, { cause: err });
+    }
+  );
+}
+var log2 = createLogger("host:permissions");
+async function requestPermission(permission) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("requestPermission: TruAPI unavailable");
+  }
+  log2.debug("requestPermission", { tag: permission.tag });
+  return await truApi.permission(enumValue("v1", permission)).match(
+    (envelope) => envelope.value,
+    (err) => {
+      throw new Error(
+        `requestPermission failed: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
+      );
+    }
+  );
+}
 
-export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync };
+export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT, createProofAuthorized, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync, requestPermission, requestResourceAllocation };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/container.ts","../src/chains.ts","../src/truapi.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { JsonRpcProvider } from \"polkadot-api\";\n\nimport type { HostLocalStorage, HostStatementStore } from \"./types.js\";\n\n/**\n * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).\n *\n * The SDK is designed to run exclusively inside a host container. This function\n * is primarily useful for early validation or informational purposes.\n *\n * Uses product-sdk's sandboxProvider as primary detection.\n * Falls back to manual signal checks when product-sdk is not installed.\n */\nexport async function isInsideContainer(): Promise<boolean> {\n    if (typeof window === \"undefined\") return false;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.sandboxProvider.isCorrectEnvironment();\n    } catch {\n        return isInsideContainerSync();\n    }\n}\n\n/**\n * Get the Host API localStorage instance when running inside a container.\n * Returns null outside a container or when product-sdk is unavailable.\n */\nexport async function getHostLocalStorage(): Promise<HostLocalStorage | null> {\n    if (!(await isInsideContainer())) return null;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.hostLocalStorage as HostLocalStorage;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.\n *\n * When running inside a Polkadot container, this wraps the chain connection via the\n * host's `createPapiProvider`, enabling shared connections and efficient routing.\n * Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).\n * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.\n */\nexport async function getHostProvider(genesisHash: `0x${string}`): Promise<JsonRpcProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createPapiProvider(genesisHash);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Synchronous container detection — fast heuristic check without product-sdk.\n *\n * Checks for iframe, webview marker, and host message port signals.\n * Use this when you need a quick sync check (e.g., in hot code paths).\n * For full detection including product-sdk, use {@link isInsideContainer} (async).\n */\nexport function isInsideContainerSync(): boolean {\n    if (typeof window === \"undefined\") return false;\n\n    const win = window as unknown as Record<string, unknown>;\n\n    // Iframe detection (polkadot.com browser)\n    try {\n        if (window !== window.top) return true;\n    } catch {\n        // Cross-origin iframe — likely inside a container\n        return true;\n    }\n\n    // Webview detection (Polkadot Desktop)\n    if (win.__HOST_WEBVIEW_MARK__ === true) return true;\n\n    // Desktop message-passing API\n    if (win.__HOST_API_PORT__ != null) return true;\n\n    return false;\n}\n\n/**\n * Get the host API statement store when running inside a container.\n *\n * Returns a statement store with `subscribe`, `createProof`, and `submit` methods\n * that communicate through the host's native binary protocol — bypassing JSON-RPC\n * entirely. Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @returns The host statement store, or `null` if unavailable.\n */\nexport async function getStatementStore(): Promise<HostStatementStore | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createStatementStore() as HostStatementStore;\n    } catch {\n        return null;\n    }\n}\n\nif (import.meta.vitest) {\n    const { test, expect, vi } = import.meta.vitest;\n\n    test(\"returns false in Node environment (no window)\", async () => {\n        expect(await isInsideContainer()).toBe(false);\n    });\n\n    test(\"manualDetection returns true for __HOST_WEBVIEW_MARK__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_WEBVIEW_MARK__: true,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for __HOST_API_PORT__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_API_PORT__: 12345,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns false when no signals present\", async () => {\n        const fakeWindow = { top: null };\n        Object.defineProperty(fakeWindow, \"top\", { get: () => fakeWindow });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(false);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for cross-origin iframe\", async () => {\n        const fakeWindow = {};\n        Object.defineProperty(fakeWindow, \"top\", {\n            get: () => {\n                throw new DOMException(\"cross-origin\");\n            },\n        });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true when window !== window.top (iframe)\", async () => {\n        const fakeWindow = { top: {} }; // top is a different object\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"getHostLocalStorage returns null outside container\", async () => {\n        expect(await getHostLocalStorage()).toBeNull();\n    });\n\n    test(\"getHostProvider returns null when product-sdk unavailable\", async () => {\n        const result = await getHostProvider(\"0xabc\");\n        expect(result).toBeNull();\n    });\n\n    test(\"getStatementStore returns null when product-sdk unavailable\", async () => {\n        const result = await getStatementStore();\n        expect(result).toBeNull();\n    });\n}\n","/**\n * Shared chain network configuration — single source of truth for\n * chain-specific endpoints used by multiple packages.\n */\n\n/**\n * Bulletin Chain RPC endpoints per network environment. `paseo` and `previewnet`\n * are populated today; `polkadot` and `kusama` are reserved for when those\n * Bulletin deployments go live.\n */\nexport const BULLETIN_RPCS = {\n    paseo: [\"wss://paseo-bulletin-next-rpc.polkadot.io\"],\n    previewnet: [\"wss://previewnet.substrate.dev/bulletin\"],\n    polkadot: [] as string[],\n    kusama: [] as string[],\n} as const;\n\n/** Default Bulletin Chain endpoint — the first entry under {@link BULLETIN_RPCS}.paseo. */\nexport const DEFAULT_BULLETIN_ENDPOINT: string = BULLETIN_RPCS.paseo[0];\n\nif (import.meta.vitest) {\n    const { describe, test, expect } = import.meta.vitest;\n\n    describe(\"chains config\", () => {\n        test(\"BULLETIN_RPCS has paseo endpoint\", () => {\n            expect(BULLETIN_RPCS.paseo.length).toBeGreaterThan(0);\n            expect(BULLETIN_RPCS.paseo[0]).toMatch(/^wss:\\/\\//);\n        });\n\n        test(\"BULLETIN_RPCS has previewnet endpoint\", () => {\n            expect(BULLETIN_RPCS.previewnet.length).toBeGreaterThan(0);\n            expect(BULLETIN_RPCS.previewnet[0]).toMatch(/^wss:\\/\\//);\n        });\n\n        test(\"BULLETIN_RPCS polkadot and kusama are empty until live\", () => {\n            expect(BULLETIN_RPCS.polkadot).toEqual([]);\n            expect(BULLETIN_RPCS.kusama).toEqual([]);\n        });\n\n        test(\"DEFAULT_BULLETIN_ENDPOINT matches first paseo endpoint\", () => {\n            expect(DEFAULT_BULLETIN_ENDPOINT).toBe(BULLETIN_RPCS.paseo[0]);\n        });\n    });\n}\n","/**\n * TruAPI - the protocol for communicating between apps and the Polkadot host container.\n *\n * This module centralizes access to @novasamatech/product-sdk and @novasamatech/host-api,\n * allowing other @parity/product-sdk-* packages to import from here rather than depending\n * directly on novasama packages.\n *\n * @module\n */\n\nimport { createLogger } from \"@parity/product-sdk-logger\";\n\nconst log = createLogger(\"host\");\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers from @novasamatech/host-api (re-exported from @novasamatech/scale)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport {\n    /**\n     * Construct an enum variant for TruAPI calls.\n     *\n     * @example\n     * ```ts\n     * import { enumValue, getTruApi } from \"@parity/product-sdk-host\";\n     *\n     * const truApi = await getTruApi();\n     * if (truApi) {\n     *   await truApi.permission([enumValue(\"ChainSubmit\")]);\n     * }\n     * ```\n     */\n    enumValue,\n    /**\n     * Check if a value is a specific enum variant.\n     */\n    isEnumVariant,\n    /**\n     * Assert that a value is a specific enum variant, throwing if not.\n     */\n    assertEnumVariant,\n    /**\n     * Unwrap a Result, throwing on error.\n     */\n    unwrapResultOrThrow,\n    /**\n     * Create an Ok result.\n     */\n    resultOk,\n    /**\n     * Create an Err result.\n     */\n    resultErr,\n    /**\n     * Convert bytes to hex string.\n     */\n    toHex,\n    /**\n     * Convert hex string to bytes.\n     */\n    fromHex,\n} from \"@novasamatech/host-api\";\n\n/** A `0x`-prefixed hex string (the template literal type ``\\`0x${string}\\``) used by the host API surface for raw byte payloads. Re-exported from `@novasamatech/host-api` so consumers bridging between host APIs and SDK code can reach the host-side type without an additional dependency. */\nexport type { HexString } from \"@novasamatech/host-api\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// TruAPI accessor\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The TruApi type - provides low-level methods for communicating with the host.\n *\n * Methods include:\n * - `navigateTo(url)` — Navigate to a URL within the host\n * - `permission(permissions)` — Request permissions from the host\n * - `localStorageRead/Write/Clear` — Host-backed storage\n * - `sign(payload)` — Request transaction signing\n * - `deriveEntropy(context)` — Derive deterministic entropy\n * - `themeSubscribe()` — Subscribe to host theme changes\n * - And many more...\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type TruApi = any;\n\n/** Cached TruApi instance */\nlet cachedTruApi: TruApi | null = null;\n\n/**\n * Get the TruAPI instance for direct low-level access.\n *\n * Returns the `hostApi` object from `@novasamatech/product-sdk` which provides\n * methods for communicating directly with the host container. Returns `null`\n * when running outside a container or when the SDK is unavailable.\n *\n * For most use cases, prefer the higher-level functions like `getHostLocalStorage()`,\n * `getHostProvider()`, etc. Use this when you need direct access to host methods\n * like `navigateTo()`, `permission()`, or `deriveEntropy()`.\n *\n * @example\n * ```ts\n * import { getTruApi, enumValue } from \"@parity/product-sdk-host\";\n *\n * const truApi = await getTruApi();\n * if (truApi) {\n *   // Request permission\n *   const result = await truApi.permission([enumValue(\"ChainSubmit\")]);\n *\n *   // Navigate to a URL\n *   await truApi.navigateTo(\"polkadot://settings\");\n *\n *   // Subscribe to theme changes\n *   const sub = truApi.themeSubscribe(undefined, (theme) => {\n *     console.log(\"Theme changed:\", theme);\n *   });\n * }\n * ```\n *\n * @returns The TruAPI instance, or `null` if unavailable.\n */\nexport async function getTruApi(): Promise<TruApi | null> {\n    if (cachedTruApi) return cachedTruApi;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        cachedTruApi = sdk.hostApi;\n        log.debug(\"TruAPI loaded\");\n        return cachedTruApi;\n    } catch {\n        log.debug(\"TruAPI unavailable (not in container or SDK not installed)\");\n        return null;\n    }\n}\n\n/**\n * Get the preimage manager for bulletin chain operations.\n *\n * The preimage manager handles uploading and looking up preimages (arbitrary data)\n * on the bulletin chain through the host's optimized path.\n *\n * @returns The preimage manager, or `null` if unavailable.\n *\n * @example\n * ```ts\n * import { getPreimageManager } from \"@parity/product-sdk-host\";\n *\n * const manager = await getPreimageManager();\n * if (manager) {\n *   // Submit a preimage\n *   const key = await manager.submit(new Uint8Array([1, 2, 3]));\n *\n *   // Look up a preimage\n *   const sub = manager.lookup(key, (data) => {\n *     if (data) console.log(\"Found:\", data);\n *   });\n * }\n * ```\n */\nexport async function getPreimageManager(): Promise<PreimageManager | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.preimageManager;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Preimage manager interface for bulletin chain operations.\n */\nexport interface PreimageManager {\n    /**\n     * Submit a preimage to the bulletin chain.\n     * @param data - The data to submit.\n     * @returns The preimage key (hex string).\n     */\n    submit(data: Uint8Array): Promise<string>;\n\n    /**\n     * Look up a preimage by key.\n     * @param key - The preimage key (hex string).\n     * @param callback - Called with the data when found, or null if not yet available.\n     * @returns Subscription handle with unsubscribe method.\n     */\n    lookup(\n        key: string,\n        callback: (preimage: Uint8Array | null) => void,\n    ): { unsubscribe: () => void; onInterrupt: (cb: () => void) => () => void };\n}\n\n/**\n * Get the accounts provider for managing host accounts.\n *\n * @returns The accounts provider, or `null` if unavailable.\n */\nexport async function getAccountsProvider(): Promise<AccountsProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createAccountsProvider() as unknown as AccountsProvider;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * One of the user's existing wallet accounts, surfaced through the host and\n * identified by its public key and an optional name. Contrast with\n * {@link ProductAccount}, which is also user-controlled but derived by the\n * host for a specific app rather than picked from the user's existing keys.\n */\nexport interface HostAccount {\n    publicKey: Uint8Array;\n    name?: string;\n}\n\n/**\n * A product account — an app-scoped derived account managed by the host wallet.\n *\n * The host derives a unique keypair for each app (identified by `dotNsIdentifier`)\n * so apps get their own account that the user controls but is scoped to the app.\n */\nexport interface ProductAccount {\n    /** App identifier (e.g., \"mark3t.dot\"). */\n    dotNsIdentifier: string;\n    /** Derivation index within the app scope. Default: 0 */\n    derivationIndex: number;\n    /** Raw public key (32 bytes). */\n    publicKey: Uint8Array;\n}\n\n/**\n * A contextual alias obtained from Ring VRF.\n *\n * Proves account membership in a ring without revealing which account.\n */\nexport interface ContextualAlias {\n    /** Ring context (32 bytes). */\n    context: Uint8Array;\n    /** The Ring VRF alias bytes. */\n    alias: Uint8Array;\n}\n\n/**\n * Neverthrow-style ResultAsync returned by product-sdk methods.\n *\n * Use `.match(onOk, onErr)` to handle success/error cases.\n */\nexport interface ResultAsync<T, E> {\n    match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;\n}\n\n/**\n * Accounts provider interface from @novasamatech/product-sdk.\n *\n * Provides methods for accessing host wallet accounts, product accounts,\n * and Ring VRF operations.\n */\nexport interface AccountsProvider {\n    /**\n     * Get legacy accounts (user's external wallets connected to the host).\n     *\n     * Renamed from `getNonProductAccounts` in @novasamatech/product-sdk 0.7.\n     *\n     * @returns ResultAsync resolving to array of accounts.\n     */\n    getLegacyAccounts: () => ResultAsync<HostAccount[], unknown>;\n\n    /**\n     * Get a signer for a legacy account.\n     *\n     * Renamed from `getNonProductAccountSigner` in @novasamatech/product-sdk 0.7.\n     *\n     * @param account - The product account (used for public key lookup).\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getLegacyAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get an app-scoped product account from the host.\n     *\n     * Product accounts are derived by the host wallet for each app, identified\n     * by `dotNsIdentifier` (e.g., \"mark3t.dot\"). The user controls these accounts\n     * but they are scoped to the requesting app.\n     *\n     * @param dotNsIdentifier - App identifier (e.g., \"mark3t.dot\").\n     * @param derivationIndex - Derivation index within the app scope. Default: 0\n     * @returns ResultAsync resolving to the account.\n     */\n    getProductAccount: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<HostAccount, unknown>;\n\n    /**\n     * Get a signer for a product account.\n     *\n     * @param account - The product account.\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getProductAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get a contextual alias for a product account via Ring VRF.\n     *\n     * Aliases prove account membership in a ring without revealing which\n     * account produced the alias.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index. Default: 0\n     * @returns ResultAsync resolving to the contextual alias.\n     */\n    getProductAccountAlias: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<ContextualAlias, unknown>;\n\n    /**\n     * Create a Ring VRF proof for anonymous operations.\n     *\n     * Proves that the signer is a member of the ring at the given location\n     * without revealing which member.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index.\n     * @param location - Ring location on-chain.\n     * @param message - Message to sign.\n     * @returns ResultAsync resolving to the proof bytes.\n     */\n    createRingVRFProof: (\n        dotNsIdentifier: string,\n        derivationIndex: number,\n        location: unknown,\n        message: Uint8Array,\n    ) => ResultAsync<Uint8Array, unknown>;\n\n    /**\n     * Subscribe to account connection status changes.\n     *\n     * @param callback - Called with status string (\"connected\" | \"disconnected\").\n     * @returns Unsubscribe handle.\n     */\n    subscribeAccountConnectionStatus: (\n        callback: (status: string) => void,\n    ) => { unsubscribe: () => void } | (() => void);\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tests\n// ─────────────────────────────────────────────────────────────────────────────\n\nif (import.meta.vitest) {\n    const { test, expect } = import.meta.vitest;\n\n    test(\"getTruApi returns TruApi when SDK is available\", async () => {\n        // Reset cache for test\n        cachedTruApi = null;\n        const api = await getTruApi();\n        // In dev/test mode, product-sdk is installed\n        expect(api === null || typeof api === \"object\").toBe(true);\n    });\n\n    test(\"getPreimageManager returns manager when SDK is available\", async () => {\n        const manager = await getPreimageManager();\n        // In dev/test mode, product-sdk is installed\n        expect(manager === null || typeof manager === \"object\").toBe(true);\n    });\n\n    test(\"getAccountsProvider returns provider when SDK is available\", async () => {\n        // In dev/test mode, product-sdk is installed, so this returns a provider\n        const provider = await getAccountsProvider();\n        // Just verify it returns something (null when SDK unavailable, provider when available)\n        expect(provider === null || typeof provider === \"object\").toBe(true);\n    });\n\n    test(\"enumValue is exported\", async () => {\n        const { enumValue } = await import(\"./truapi.js\");\n        expect(typeof enumValue).toBe(\"function\");\n    });\n}\n"]}
+{"version":3,"sources":["../src/container.ts","../src/chains.ts","../src/truapi.ts","../src/permissions.ts"],"names":["log","createLogger","enumValue"],"mappings":";;;;;AAaA,eAAsB,iBAAA,GAAsC;AACxD,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,KAAA;AAE1C,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,OAAO,GAAA,CAAI,gBAAgB,oBAAA,EAAqB;AAAA,EACpD,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,qBAAA,EAAsB;AAAA,EACjC;AACJ;AAMA,eAAsB,mBAAA,GAAwD;AAC1E,EAAA,IAAI,CAAE,MAAM,iBAAA,EAAkB,EAAI,OAAO,IAAA;AAEzC,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,OAAO,GAAA,CAAI,gBAAA;AAAA,EACf,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,IAAA;AAAA,EACX;AACJ;AAYA,eAAsB,gBAAgB,WAAA,EAA6D;AAC/F,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,OAAO,GAAA,CAAI,mBAAmB,WAAW,CAAA;AAAA,EAC7C,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,IAAA;AAAA,EACX;AACJ;AASO,SAAS,qBAAA,GAAiC;AAC7C,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,KAAA;AAE1C,EAAA,MAAM,GAAA,GAAM,MAAA;AAGZ,EAAA,IAAI;AACA,IAAA,IAAI,MAAA,KAAW,MAAA,CAAO,GAAA,EAAK,OAAO,IAAA;AAAA,EACtC,CAAA,CAAA,MAAQ;AAEJ,IAAA,OAAO,IAAA;AAAA,EACX;AAGA,EAAA,IAAI,GAAA,CAAI,qBAAA,KAA0B,IAAA,EAAM,OAAO,IAAA;AAG/C,EAAA,IAAI,GAAA,CAAI,iBAAA,IAAqB,IAAA,EAAM,OAAO,IAAA;AAE1C,EAAA,OAAO,KAAA;AACX;AAWA,eAAsB,iBAAA,GAAwD;AAC1E,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,OAAO,IAAI,oBAAA,EAAqB;AAAA,EACpC,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,IAAA;AAAA,EACX;AACJ;;;AC7FO,IAAM,aAAA,GAAgB;AAAA,EACzB,KAAA,EAAO,CAAC,2CAA2C,CAAA;AAAA,EACnD,UAAA,EAAY,CAAC,yCAAyC,CAAA;AAAA,EACtD,UAAU,EAAC;AAAA,EACX,QAAQ;AACZ;AAGO,IAAM,yBAAA,GAAoC,aAAA,CAAc,KAAA,CAAM,CAAC;ACKtE,IAAM,GAAA,GAAM,aAAa,MAAM,CAAA;AAQ/B,SAAS,YAAY,GAAA,EAAsB;AACvC,EAAA,IAAI,GAAA,YAAe,KAAA,EAAO,OAAO,GAAA,CAAI,OAAA;AACrC,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,EAAA,IAAI;AACA,IAAA,OAAO,IAAA,CAAK,UAAU,GAAG,CAAA;AAAA,EAC7B,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,OAAO,GAAG,CAAA;AAAA,EACrB;AACJ;AA0EA,IAAI,YAAA,GAA8B,IAAA;AAkClC,eAAsB,SAAA,GAAoC;AACtD,EAAA,IAAI,cAAc,OAAO,YAAA;AAEzB,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,YAAA,GAAe,GAAA,CAAI,OAAA;AACnB,IAAA,GAAA,CAAI,MAAM,eAAe,CAAA;AACzB,IAAA,OAAO,YAAA;AAAA,EACX,CAAA,CAAA,MAAQ;AACJ,IAAA,GAAA,CAAI,MAAM,4DAA4D,CAAA;AACtE,IAAA,OAAO,IAAA;AAAA,EACX;AACJ;AA0BA,eAAsB,kBAAA,GAAsD;AACxE,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,OAAO,GAAA,CAAI,eAAA;AAAA,EACf,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,IAAA;AAAA,EACX;AACJ;AA8BA,eAAsB,mBAAA,GAAwD;AAC1E,EAAA,IAAI;AACA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,2BAA2B,CAAA;AACpD,IAAA,OAAO,IAAI,sBAAA,EAAuB;AAAA,EACtC,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,IAAA;AAAA,EACX;AACJ;AAwDA,eAAsB,0BAClB,SAAA,EAC4B;AAC5B,EAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAC/B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACT,IAAA,MAAM,IAAI,MAAM,+CAA+C,CAAA;AAAA,EACnE;AACA,EAAA,GAAA,CAAI,KAAA,CAAM,2BAAA,EAA6B,EAAE,SAAA,EAAW,SAAA,CAAU,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,GAAG,CAAA,EAAG,CAAA;AAGjF,EAAA,OAAO,MAAM,MAAA,CAAO,yBAAA,CAA0B,UAAU,IAAA,EAAM,SAAS,CAAC,CAAA,CAAE,KAAA;AAAA,IACtE,CAAC,aAAwD,QAAA,CAAS,KAAA;AAAA,IAClE,CAAC,GAAA,KAAiB;AACd,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,kCAAA,EAAqC,WAAA,CAAY,GAAG,CAAC,CAAA,CAAA,EAAI;AAAA,QACrE,KAAA,EAAO;AAAA,OACV,CAAA;AAAA,IACL;AAAA,GACJ;AACJ;AA+DA,eAAsB,sBAAsB,SAAA,EAA+C;AACvF,EAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAC/B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACT,IAAA,MAAM,IAAI,MAAM,2CAA2C,CAAA;AAAA,EAC/D;AACA,EAAA,GAAA,CAAI,MAAM,uBAAA,EAAyB;AAAA,IAC/B,MAAA,EAAQ,UAAU,MAAA,CAAO,MAAA;AAAA,IACzB,OAAA,EAAS,SAAA,CAAU,IAAA,EAAM,MAAA,IAAU;AAAA,GACtC,CAAA;AAGD,EAAA,OAAO,MAAM,MAAA,CAAO,mCAAA,CAAoC,UAAU,IAAA,EAAM,SAAS,CAAC,CAAA,CAAE,KAAA;AAAA,IAChF,CAAC,aAAmD,QAAA,CAAS,KAAA;AAAA,IAC7D,CAAC,GAAA,KAAiB;AACd,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,8BAAA,EAAiC,WAAA,CAAY,GAAG,CAAC,CAAA,CAAA,EAAI,EAAE,KAAA,EAAO,GAAA,EAAK,CAAA;AAAA,IACvF;AAAA,GACJ;AACJ;AC9WA,IAAMA,IAAAA,GAAMC,aAAa,kBAAkB,CAAA;AAoB3C,eAAsB,kBAAkB,UAAA,EAAgD;AACpF,EAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAC/B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACT,IAAA,MAAM,IAAI,MAAM,uCAAuC,CAAA;AAAA,EAC3D;AACA,EAAAD,KAAI,KAAA,CAAM,mBAAA,EAAqB,EAAE,GAAA,EAAK,UAAA,CAAW,KAAK,CAAA;AAEtD,EAAA,OAAO,MAAM,MAAA,CAAO,UAAA,CAAWE,UAAU,IAAA,EAAM,UAAU,CAAC,CAAA,CAAE,KAAA;AAAA,IACxD,CAAC,aAA4C,QAAA,CAAS,KAAA;AAAA,IACtD,CAAC,GAAA,KAAiB;AACd,MAAA,MAAM,IAAI,KAAA;AAAA,QACN,6BAA6B,GAAA,YAAe,KAAA,GAAQ,IAAI,OAAA,GAAU,MAAA,CAAO,GAAG,CAAC,CAAA,CAAA;AAAA,QAC7E,EAAE,OAAO,GAAA;AAAI,OACjB;AAAA,IACJ;AAAA,GACJ;AACJ","file":"index.js","sourcesContent":["import type { JsonRpcProvider } from \"polkadot-api\";\n\nimport type { HostLocalStorage, HostStatementStore } from \"./types.js\";\n\n/**\n * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).\n *\n * The SDK is designed to run exclusively inside a host container. This function\n * is primarily useful for early validation or informational purposes.\n *\n * Uses product-sdk's sandboxProvider as primary detection.\n * Falls back to manual signal checks when product-sdk is not installed.\n */\nexport async function isInsideContainer(): Promise<boolean> {\n    if (typeof window === \"undefined\") return false;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.sandboxProvider.isCorrectEnvironment();\n    } catch {\n        return isInsideContainerSync();\n    }\n}\n\n/**\n * Get the Host API localStorage instance when running inside a container.\n * Returns null outside a container or when product-sdk is unavailable.\n */\nexport async function getHostLocalStorage(): Promise<HostLocalStorage | null> {\n    if (!(await isInsideContainer())) return null;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.hostLocalStorage as HostLocalStorage;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.\n *\n * When running inside a Polkadot container, this wraps the chain connection via the\n * host's `createPapiProvider`, enabling shared connections and efficient routing.\n * Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).\n * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.\n */\nexport async function getHostProvider(genesisHash: `0x${string}`): Promise<JsonRpcProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createPapiProvider(genesisHash);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Synchronous container detection — fast heuristic check without product-sdk.\n *\n * Checks for iframe, webview marker, and host message port signals.\n * Use this when you need a quick sync check (e.g., in hot code paths).\n * For full detection including product-sdk, use {@link isInsideContainer} (async).\n */\nexport function isInsideContainerSync(): boolean {\n    if (typeof window === \"undefined\") return false;\n\n    const win = window as unknown as Record<string, unknown>;\n\n    // Iframe detection (polkadot.com browser)\n    try {\n        if (window !== window.top) return true;\n    } catch {\n        // Cross-origin iframe — likely inside a container\n        return true;\n    }\n\n    // Webview detection (Polkadot Desktop)\n    if (win.__HOST_WEBVIEW_MARK__ === true) return true;\n\n    // Desktop message-passing API\n    if (win.__HOST_API_PORT__ != null) return true;\n\n    return false;\n}\n\n/**\n * Get the host API statement store when running inside a container.\n *\n * Returns a statement store with `subscribe`, `createProof`, and `submit` methods\n * that communicate through the host's native binary protocol — bypassing JSON-RPC\n * entirely. Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @returns The host statement store, or `null` if unavailable.\n */\nexport async function getStatementStore(): Promise<HostStatementStore | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createStatementStore() as HostStatementStore;\n    } catch {\n        return null;\n    }\n}\n\nif (import.meta.vitest) {\n    const { test, expect, vi } = import.meta.vitest;\n\n    test(\"returns false in Node environment (no window)\", async () => {\n        expect(await isInsideContainer()).toBe(false);\n    });\n\n    test(\"manualDetection returns true for __HOST_WEBVIEW_MARK__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_WEBVIEW_MARK__: true,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for __HOST_API_PORT__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_API_PORT__: 12345,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns false when no signals present\", async () => {\n        const fakeWindow = { top: null };\n        Object.defineProperty(fakeWindow, \"top\", { get: () => fakeWindow });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(false);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for cross-origin iframe\", async () => {\n        const fakeWindow = {};\n        Object.defineProperty(fakeWindow, \"top\", {\n            get: () => {\n                throw new DOMException(\"cross-origin\");\n            },\n        });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true when window !== window.top (iframe)\", async () => {\n        const fakeWindow = { top: {} }; // top is a different object\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"getHostLocalStorage returns null outside container\", async () => {\n        expect(await getHostLocalStorage()).toBeNull();\n    });\n\n    test(\"getHostProvider returns null when product-sdk unavailable\", async () => {\n        const result = await getHostProvider(\"0xabc\");\n        expect(result).toBeNull();\n    });\n\n    test(\"getStatementStore returns null when product-sdk unavailable\", async () => {\n        const result = await getStatementStore();\n        expect(result).toBeNull();\n    });\n}\n","/**\n * Shared chain network configuration — single source of truth for\n * chain-specific endpoints used by multiple packages.\n */\n\n/**\n * Bulletin Chain RPC endpoints per network environment. `paseo` and `previewnet`\n * are populated today; `polkadot` and `kusama` are reserved for when those\n * Bulletin deployments go live.\n */\nexport const BULLETIN_RPCS = {\n    paseo: [\"wss://paseo-bulletin-next-rpc.polkadot.io\"],\n    previewnet: [\"wss://previewnet.substrate.dev/bulletin\"],\n    polkadot: [] as string[],\n    kusama: [] as string[],\n} as const;\n\n/** Default Bulletin Chain endpoint — the first entry under {@link BULLETIN_RPCS}.paseo. */\nexport const DEFAULT_BULLETIN_ENDPOINT: string = BULLETIN_RPCS.paseo[0];\n\nif (import.meta.vitest) {\n    const { describe, test, expect } = import.meta.vitest;\n\n    describe(\"chains config\", () => {\n        test(\"BULLETIN_RPCS has paseo endpoint\", () => {\n            expect(BULLETIN_RPCS.paseo.length).toBeGreaterThan(0);\n            expect(BULLETIN_RPCS.paseo[0]).toMatch(/^wss:\\/\\//);\n        });\n\n        test(\"BULLETIN_RPCS has previewnet endpoint\", () => {\n            expect(BULLETIN_RPCS.previewnet.length).toBeGreaterThan(0);\n            expect(BULLETIN_RPCS.previewnet[0]).toMatch(/^wss:\\/\\//);\n        });\n\n        test(\"BULLETIN_RPCS polkadot and kusama are empty until live\", () => {\n            expect(BULLETIN_RPCS.polkadot).toEqual([]);\n            expect(BULLETIN_RPCS.kusama).toEqual([]);\n        });\n\n        test(\"DEFAULT_BULLETIN_ENDPOINT matches first paseo endpoint\", () => {\n            expect(DEFAULT_BULLETIN_ENDPOINT).toBe(BULLETIN_RPCS.paseo[0]);\n        });\n    });\n}\n","/**\n * TruAPI - the protocol for communicating between apps and the Polkadot host container.\n *\n * This module centralizes access to @novasamatech/product-sdk and @novasamatech/host-api,\n * allowing other @parity/product-sdk-* packages to import from here rather than depending\n * directly on novasama packages.\n *\n * @module\n */\n\nimport { createLogger } from \"@parity/product-sdk-logger\";\n\nimport { enumValue } from \"@novasamatech/host-api\";\nimport type {\n    AllocatableResource as AllocatableResourceCodec,\n    AllocationOutcome as AllocationOutcomeCodec,\n    CodecType,\n    RemotePermission as RemotePermissionCodec,\n    Statement as StatementCodec,\n} from \"@novasamatech/host-api\";\n\nimport type { StatementProof } from \"./types.js\";\n\nconst log = createLogger(\"host\");\n\n/**\n * Extract a human-readable message from an unknown error. `JSON.stringify`\n * on `Error` returns `\"{}\"` because `message` and `stack` are non-enumerable\n * — without this helper, wire failures surface as `\"... failed: {}\"` with\n * zero diagnostic context.\n */\nfunction formatError(err: unknown): string {\n    if (err instanceof Error) return err.message;\n    if (typeof err === \"string\") return err;\n    try {\n        return JSON.stringify(err);\n    } catch {\n        return String(err);\n    }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers from @novasamatech/host-api (re-exported from @novasamatech/scale)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport {\n    /**\n     * Construct an enum variant for TruAPI calls.\n     *\n     * @example\n     * ```ts\n     * import { enumValue, getTruApi } from \"@parity/product-sdk-host\";\n     *\n     * const truApi = await getTruApi();\n     * if (truApi) {\n     *   await truApi.permission([enumValue(\"ChainSubmit\")]);\n     * }\n     * ```\n     */\n    enumValue,\n    /**\n     * Check if a value is a specific enum variant.\n     */\n    isEnumVariant,\n    /**\n     * Assert that a value is a specific enum variant, throwing if not.\n     */\n    assertEnumVariant,\n    /**\n     * Unwrap a Result, throwing on error.\n     */\n    unwrapResultOrThrow,\n    /**\n     * Create an Ok result.\n     */\n    resultOk,\n    /**\n     * Create an Err result.\n     */\n    resultErr,\n    /**\n     * Convert bytes to hex string.\n     */\n    toHex,\n    /**\n     * Convert hex string to bytes.\n     */\n    fromHex,\n} from \"@novasamatech/host-api\";\n\n/** A `0x`-prefixed hex string (the template literal type ``\\`0x${string}\\``) used by the host API surface for raw byte payloads. Re-exported from `@novasamatech/host-api` so consumers bridging between host APIs and SDK code can reach the host-side type without an additional dependency. */\nexport type { HexString } from \"@novasamatech/host-api\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// TruAPI accessor\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The TruApi type - provides low-level methods for communicating with the host.\n *\n * Methods include:\n * - `navigateTo(url)` — Navigate to a URL within the host\n * - `permission(permissions)` — Request permissions from the host\n * - `localStorageRead/Write/Clear` — Host-backed storage\n * - `sign(payload)` — Request transaction signing\n * - `deriveEntropy(context)` — Derive deterministic entropy\n * - `themeSubscribe()` — Subscribe to host theme changes\n * - And many more...\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type TruApi = any;\n\n/** Cached TruApi instance */\nlet cachedTruApi: TruApi | null = null;\n\n/**\n * Get the TruAPI instance for direct low-level access.\n *\n * Returns the `hostApi` object from `@novasamatech/product-sdk` which provides\n * methods for communicating directly with the host container. Returns `null`\n * when running outside a container or when the SDK is unavailable.\n *\n * For most use cases, prefer the higher-level functions like `getHostLocalStorage()`,\n * `getHostProvider()`, etc. Use this when you need direct access to host methods\n * like `navigateTo()`, `permission()`, or `deriveEntropy()`.\n *\n * @example\n * ```ts\n * import { getTruApi, enumValue } from \"@parity/product-sdk-host\";\n *\n * const truApi = await getTruApi();\n * if (truApi) {\n *   // Request permission\n *   const result = await truApi.permission([enumValue(\"ChainSubmit\")]);\n *\n *   // Navigate to a URL\n *   await truApi.navigateTo(\"polkadot://settings\");\n *\n *   // Subscribe to theme changes\n *   const sub = truApi.themeSubscribe(undefined, (theme) => {\n *     console.log(\"Theme changed:\", theme);\n *   });\n * }\n * ```\n *\n * @returns The TruAPI instance, or `null` if unavailable.\n */\nexport async function getTruApi(): Promise<TruApi | null> {\n    if (cachedTruApi) return cachedTruApi;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        cachedTruApi = sdk.hostApi;\n        log.debug(\"TruAPI loaded\");\n        return cachedTruApi;\n    } catch {\n        log.debug(\"TruAPI unavailable (not in container or SDK not installed)\");\n        return null;\n    }\n}\n\n/**\n * Get the preimage manager for bulletin chain operations.\n *\n * The preimage manager handles uploading and looking up preimages (arbitrary data)\n * on the bulletin chain through the host's optimized path.\n *\n * @returns The preimage manager, or `null` if unavailable.\n *\n * @example\n * ```ts\n * import { getPreimageManager } from \"@parity/product-sdk-host\";\n *\n * const manager = await getPreimageManager();\n * if (manager) {\n *   // Submit a preimage\n *   const key = await manager.submit(new Uint8Array([1, 2, 3]));\n *\n *   // Look up a preimage\n *   const sub = manager.lookup(key, (data) => {\n *     if (data) console.log(\"Found:\", data);\n *   });\n * }\n * ```\n */\nexport async function getPreimageManager(): Promise<PreimageManager | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.preimageManager;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Preimage manager interface for bulletin chain operations.\n */\nexport interface PreimageManager {\n    /**\n     * Submit a preimage to the bulletin chain.\n     * @param data - The data to submit.\n     * @returns The preimage key (hex string).\n     */\n    submit(data: Uint8Array): Promise<string>;\n\n    /**\n     * Look up a preimage by key.\n     * @param key - The preimage key (hex string).\n     * @param callback - Called with the data when found, or null if not yet available.\n     * @returns Subscription handle with unsubscribe method.\n     */\n    lookup(\n        key: string,\n        callback: (preimage: Uint8Array | null) => void,\n    ): { unsubscribe: () => void; onInterrupt: (cb: () => void) => () => void };\n}\n\n/**\n * Get the accounts provider for managing host accounts.\n *\n * @returns The accounts provider, or `null` if unavailable.\n */\nexport async function getAccountsProvider(): Promise<AccountsProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createAccountsProvider() as unknown as AccountsProvider;\n    } catch {\n        return null;\n    }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Resource allocation\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Resource types requestable via {@link requestResourceAllocation}.\n * Derived from the upstream codec so variant renames surface as compile\n * errors, not runtime failures.\n */\nexport type AllocatableResource = CodecType<typeof AllocatableResourceCodec>;\n\n/** Tag-only view of {@link AllocatableResource} for places that just need the variant name. */\nexport type AllocatableResourceTag = AllocatableResource[\"tag\"];\n\n/**\n * Per-resource outcome from {@link requestResourceAllocation}.\n * The host strips secret payloads from `Allocated` before returning, so\n * `value` is always `undefined` on the product side.\n */\nexport type AllocationOutcome = CodecType<typeof AllocationOutcomeCodec>;\n\n/** Tag-only view of {@link AllocationOutcome} (`\"Allocated\" | \"Rejected\" | \"NotAvailable\"`). */\nexport type AllocationOutcomeTag = AllocationOutcome[\"tag\"];\n\n/**\n * Remote permission the dapp can ask the host to grant via\n * {@link requestPermission}.\n *\n * Derived from the upstream codec so variant renames surface as compile\n * errors, not runtime failures.\n */\nexport type RemotePermission = CodecType<typeof RemotePermissionCodec>;\n\n/** Tag-only view of {@link RemotePermission}. */\nexport type RemotePermissionTag = RemotePermission[\"tag\"];\n\n/**\n * Request the host to pre-allocate one or more resource allowances.\n *\n * The host prompts the user once; subsequent operations covered by the\n * granted allowance don't re-prompt.\n *\n * @param resources - Resources to request.\n * @returns Per-resource outcomes in the same order as `resources`.\n * @throws If the host is unavailable or the request fails.\n *\n * @example\n * ```ts\n * const outcomes = await requestResourceAllocation([\n *   { tag: \"BulletInAllowance\", value: undefined },\n * ]);\n * if (outcomes[0].tag === \"Allocated\") { ... }\n * ```\n */\nexport async function requestResourceAllocation(\n    resources: AllocatableResource[],\n): Promise<AllocationOutcome[]> {\n    const truApi = await getTruApi();\n    if (!truApi) {\n        throw new Error(\"requestResourceAllocation: TruAPI unavailable\");\n    }\n    log.debug(\"requestResourceAllocation\", { resources: resources.map((r) => r.tag) });\n\n    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.\n    return await truApi.requestResourceAllocation(enumValue(\"v1\", resources)).match(\n        (envelope: { tag: \"v1\"; value: AllocationOutcome[] }) => envelope.value,\n        (err: unknown) => {\n            throw new Error(`requestResourceAllocation failed: ${formatError(err)}`, {\n                cause: err,\n            });\n        },\n    );\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Authorized Statement Store proof creation (RFC-10 §\"Statement Store allowance\")\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * A Statement payload destined for the Statement Store. Matches the\n * `pallet-statement` Statement structure.\n *\n * The optional `proof` field is the same {@link StatementProof} shape that\n * {@link createProofAuthorized} returns: pass `undefined` here, call\n * `createProofAuthorized` to obtain the proof, then attach it before\n * submitting via `HostStatementStore.submit`. The `OnChain` variant of\n * `StatementProof` is a chain-attestation reference; the `Sr25519` /\n * `Ed25519` / `Ecdsa` variants are signing proofs.\n *\n * Derived from the upstream codec so structural changes surface as compile\n * errors here, not runtime decode failures.\n */\nexport type Statement = CodecType<typeof StatementCodec>;\n\n/**\n * Have the host sign a Statement using an allowance-bearing account it\n * picks internally — RFC-10 §\"Statement Store allowance\".\n *\n * The product passes only the Statement payload; the host chooses the\n * `//allowance//statement-store//{productId}` account that holds SSS\n * allowance and signs with it. Allowance is provisioned implicitly on\n * first use if the host hasn't already pre-allocated via\n * {@link requestResourceAllocation}; products never see the signing\n * account or its key material.\n *\n * Pairs with {@link getStatementStore}'s `submit`: call this to obtain\n * a proof, attach it to the Statement, and submit the result.\n *\n * @param statement - The Statement to be signed.\n * @returns The proof to attach before submitting.\n * @throws If the host is unavailable or the host-side signing fails.\n *\n * @example\n * ```ts\n * import { createProofAuthorized, getStatementStore } from \"@parity/product-sdk-host\";\n *\n * const statement = {\n *     proof: undefined,\n *     decryptionKey: undefined,\n *     expiry: undefined,\n *     channel: undefined,\n *     topics: [],\n *     data: payload,\n * };\n * const proof = await createProofAuthorized(statement);\n * const store = await getStatementStore();\n * await store?.submit({ ...statement, proof });\n * ```\n *\n * @remarks\n * RFC-10 introduces this as a new, strictly additive TruAPI call. The\n * pre-existing `HostStatementStore.createProof(accountId, statement)`\n * surface stays available for products that own a non-allowance signing\n * account; this wrapper is the sponsored-submission path.\n */\nexport async function createProofAuthorized(statement: Statement): Promise<StatementProof> {\n    const truApi = await getTruApi();\n    if (!truApi) {\n        throw new Error(\"createProofAuthorized: TruAPI unavailable\");\n    }\n    log.debug(\"createProofAuthorized\", {\n        topics: statement.topics.length,\n        dataLen: statement.data?.length ?? 0,\n    });\n\n    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.\n    return await truApi.statementStoreCreateProofAuthorized(enumValue(\"v1\", statement)).match(\n        (envelope: { tag: \"v1\"; value: StatementProof }) => envelope.value,\n        (err: unknown) => {\n            throw new Error(`createProofAuthorized failed: ${formatError(err)}`, { cause: err });\n        },\n    );\n}\n\n/**\n * One of the user's existing wallet accounts, surfaced through the host and\n * identified by its public key and an optional name. Contrast with\n * {@link ProductAccount}, which is also user-controlled but derived by the\n * host for a specific app rather than picked from the user's existing keys.\n */\nexport interface HostAccount {\n    publicKey: Uint8Array;\n    name?: string;\n}\n\n/**\n * A product account — an app-scoped derived account managed by the host wallet.\n *\n * The host derives a unique keypair for each app (identified by `dotNsIdentifier`)\n * so apps get their own account that the user controls but is scoped to the app.\n */\nexport interface ProductAccount {\n    /** App identifier (e.g., \"mark3t.dot\"). */\n    dotNsIdentifier: string;\n    /** Derivation index within the app scope. Default: 0 */\n    derivationIndex: number;\n    /** Raw public key (32 bytes). */\n    publicKey: Uint8Array;\n}\n\n/**\n * A contextual alias obtained from Ring VRF.\n *\n * Proves account membership in a ring without revealing which account.\n */\nexport interface ContextualAlias {\n    /** Ring context (32 bytes). */\n    context: Uint8Array;\n    /** The Ring VRF alias bytes. */\n    alias: Uint8Array;\n}\n\n/**\n * Neverthrow-style ResultAsync returned by product-sdk methods.\n *\n * Use `.match(onOk, onErr)` to handle success/error cases.\n */\nexport interface ResultAsync<T, E> {\n    match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;\n}\n\n/**\n * Accounts provider interface from @novasamatech/product-sdk.\n *\n * Provides methods for accessing host wallet accounts, product accounts,\n * and Ring VRF operations.\n */\nexport interface AccountsProvider {\n    /**\n     * Get legacy accounts (user's external wallets connected to the host).\n     *\n     * Renamed from `getNonProductAccounts` in @novasamatech/product-sdk 0.7.\n     *\n     * @returns ResultAsync resolving to array of accounts.\n     */\n    getLegacyAccounts: () => ResultAsync<HostAccount[], unknown>;\n\n    /**\n     * Get a signer for a legacy account.\n     *\n     * Renamed from `getNonProductAccountSigner` in @novasamatech/product-sdk 0.7.\n     *\n     * @param account - The product account (used for public key lookup).\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getLegacyAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get an app-scoped product account from the host.\n     *\n     * Product accounts are derived by the host wallet for each app, identified\n     * by `dotNsIdentifier` (e.g., \"mark3t.dot\"). The user controls these accounts\n     * but they are scoped to the requesting app.\n     *\n     * @param dotNsIdentifier - App identifier (e.g., \"mark3t.dot\").\n     * @param derivationIndex - Derivation index within the app scope. Default: 0\n     * @returns ResultAsync resolving to the account.\n     */\n    getProductAccount: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<HostAccount, unknown>;\n\n    /**\n     * Get a signer for a product account.\n     *\n     * @param account - The product account.\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getProductAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get a contextual alias for a product account via Ring VRF.\n     *\n     * Aliases prove account membership in a ring without revealing which\n     * account produced the alias.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index. Default: 0\n     * @returns ResultAsync resolving to the contextual alias.\n     */\n    getProductAccountAlias: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<ContextualAlias, unknown>;\n\n    /**\n     * Create a Ring VRF proof for anonymous operations.\n     *\n     * Proves that the signer is a member of the ring at the given location\n     * without revealing which member.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index.\n     * @param location - Ring location on-chain.\n     * @param message - Message to sign.\n     * @returns ResultAsync resolving to the proof bytes.\n     */\n    createRingVRFProof: (\n        dotNsIdentifier: string,\n        derivationIndex: number,\n        location: unknown,\n        message: Uint8Array,\n    ) => ResultAsync<Uint8Array, unknown>;\n\n    /**\n     * Subscribe to account connection status changes.\n     *\n     * @param callback - Called with status string (\"connected\" | \"disconnected\").\n     * @returns Unsubscribe handle.\n     */\n    subscribeAccountConnectionStatus: (\n        callback: (status: string) => void,\n    ) => { unsubscribe: () => void } | (() => void);\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tests\n// ─────────────────────────────────────────────────────────────────────────────\n\nif (import.meta.vitest) {\n    const { test, expect } = import.meta.vitest;\n\n    test(\"getTruApi returns TruApi when SDK is available\", async () => {\n        // Reset cache for test\n        cachedTruApi = null;\n        const api = await getTruApi();\n        // In dev/test mode, product-sdk is installed\n        expect(api === null || typeof api === \"object\").toBe(true);\n    });\n\n    test(\"getPreimageManager returns manager when SDK is available\", async () => {\n        const manager = await getPreimageManager();\n        // In dev/test mode, product-sdk is installed\n        expect(manager === null || typeof manager === \"object\").toBe(true);\n    });\n\n    test(\"getAccountsProvider returns provider when SDK is available\", async () => {\n        // In dev/test mode, product-sdk is installed, so this returns a provider\n        const provider = await getAccountsProvider();\n        // Just verify it returns something (null when SDK unavailable, provider when available)\n        expect(provider === null || typeof provider === \"object\").toBe(true);\n    });\n\n    test(\"enumValue is exported\", async () => {\n        const { enumValue } = await import(\"./truapi.js\");\n        expect(typeof enumValue).toBe(\"function\");\n    });\n\n    test(\"requestResourceAllocation throws when TruAPI is unavailable\", async () => {\n        cachedTruApi = null;\n        const api = await getTruApi();\n        if (api === null) {\n            await expect(\n                requestResourceAllocation([{ tag: \"BulletInAllowance\", value: undefined }]),\n            ).rejects.toThrow(/TruAPI unavailable/);\n        } else {\n            expect(typeof requestResourceAllocation).toBe(\"function\");\n        }\n    });\n\n    test(\"createProofAuthorized throws when TruAPI is unavailable\", async () => {\n        cachedTruApi = null;\n        const api = await getTruApi();\n        if (api === null) {\n            await expect(\n                createProofAuthorized({\n                    proof: undefined,\n                    decryptionKey: undefined,\n                    expiry: undefined,\n                    channel: undefined,\n                    topics: [],\n                    data: undefined,\n                }),\n            ).rejects.toThrow(/TruAPI unavailable/);\n        } else {\n            expect(typeof createProofAuthorized).toBe(\"function\");\n        }\n    });\n}\n","/**\n * Higher-level wrapper for the host's single-permission flow.\n *\n * `hostApi.permission` takes a versioned envelope (`enumValue(\"v1\", ...)`)\n * and returns a neverthrow `ResultAsync` of an unwrapped versioned response.\n * Consumers rebuild that wrap/unwrap dance every time. `requestPermission`\n * collapses it to a one-liner that matches the shape of\n * {@link requestResourceAllocation} (throws on error, returns the unwrapped\n * payload on success).\n *\n * @module\n */\n\nimport { createLogger } from \"@parity/product-sdk-logger\";\n\nimport { enumValue, getTruApi, type RemotePermission } from \"./truapi.js\";\n\nconst log = createLogger(\"host:permissions\");\n\n/**\n * Request a single remote permission from the host.\n *\n * Builds the `v1` envelope, calls `hostApi.permission`, unwraps the response,\n * and returns the host's boolean granted/denied outcome.\n *\n * @param permission - The remote permission to request.\n * @returns `true` if the host granted the permission, `false` if denied.\n * @throws If the host is unavailable or the request fails.\n *\n * @example\n * ```ts\n * const granted = await requestPermission({ tag: \"ChainSubmit\", value: undefined });\n * if (!granted) {\n *   tellUserToReconnect();\n * }\n * ```\n */\nexport async function requestPermission(permission: RemotePermission): Promise<boolean> {\n    const truApi = await getTruApi();\n    if (!truApi) {\n        throw new Error(\"requestPermission: TruAPI unavailable\");\n    }\n    log.debug(\"requestPermission\", { tag: permission.tag });\n\n    return await truApi.permission(enumValue(\"v1\", permission)).match(\n        (envelope: { tag: \"v1\"; value: boolean }) => envelope.value,\n        (err: unknown) => {\n            throw new Error(\n                `requestPermission failed: ${err instanceof Error ? err.message : String(err)}`,\n                { cause: err },\n            );\n        },\n    );\n}\n\nif (import.meta.vitest) {\n    const { test, expect, describe, vi } = import.meta.vitest;\n\n    async function withMockedTruApi<T>(\n        bridge: { permission?: (req: unknown) => unknown } | null,\n        fn: (mod: typeof import(\"./permissions.js\")) => Promise<T>,\n    ): Promise<T> {\n        vi.resetModules();\n        vi.doMock(\"./truapi.js\", () => ({\n            getTruApi: async () => bridge,\n            enumValue: (version: string, value: unknown) => ({ tag: version, value }),\n        }));\n        try {\n            const mod = await import(\"./permissions.js\");\n            return await fn(mod);\n        } finally {\n            vi.doUnmock(\"./truapi.js\");\n            vi.resetModules();\n        }\n    }\n\n    describe(\"requestPermission\", () => {\n        test(\"throws when TruAPI is unavailable\", async () => {\n            await withMockedTruApi(null, async (mod) => {\n                await expect(\n                    mod.requestPermission({ tag: \"ChainSubmit\", value: undefined }),\n                ).rejects.toThrow(/TruAPI unavailable/);\n            });\n        });\n\n        test(\"unwraps the v1 boolean outcome\", async () => {\n            await withMockedTruApi(\n                {\n                    permission: vi.fn().mockReturnValue({\n                        match: async (onOk: (v: unknown) => unknown) =>\n                            onOk({ tag: \"v1\", value: true }),\n                    }),\n                },\n                async (mod) => {\n                    const granted = await mod.requestPermission({\n                        tag: \"ChainSubmit\",\n                        value: undefined,\n                    });\n                    expect(granted).toBe(true);\n                },\n            );\n        });\n\n        test(\"wraps host errors with a diagnostic message\", async () => {\n            await withMockedTruApi(\n                {\n                    permission: vi.fn().mockReturnValue({\n                        match: async (\n                            _onOk: (v: unknown) => unknown,\n                            onErr: (e: unknown) => unknown,\n                        ) =>\n                            onErr({\n                                tag: \"v1\",\n                                value: { name: \"GenericError\", message: \"boom\" },\n                            }),\n                    }),\n                },\n                async (mod) => {\n                    await expect(\n                        mod.requestPermission({ tag: \"ChainSubmit\", value: undefined }),\n                    ).rejects.toThrow(/requestPermission failed/);\n                },\n            );\n        });\n    });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-sdk-host",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Host container detection and storage access for Polkadot Desktop and Mobile environments",
   "type": "module",
   "sideEffects": false,

package/src/index.ts

@@ -29,6 +29,8 @@ export {
     getTruApi,
     getPreimageManager,
     getAccountsProvider,
+    requestResourceAllocation,
+    createProofAuthorized,
     // Helpers from @novasamatech/host-api
     enumValue,
     isEnumVariant,
@@ -48,4 +50,14 @@ export type {
     ProductAccount,
     ContextualAlias,
     ResultAsync,
+    AllocatableResource,
+    AllocatableResourceTag,
+    AllocationOutcome,
+    AllocationOutcomeTag,
+    RemotePermission,
+    RemotePermissionTag,
+    Statement,
 } from "./truapi.js";
+
+// Higher-level permission wrapper
+export { requestPermission } from "./permissions.js";

package/src/permissions.ts

@@ -0,0 +1,126 @@
+/**
+ * Higher-level wrapper for the host's single-permission flow.
+ *
+ * `hostApi.permission` takes a versioned envelope (`enumValue("v1", ...)`)
+ * and returns a neverthrow `ResultAsync` of an unwrapped versioned response.
+ * Consumers rebuild that wrap/unwrap dance every time. `requestPermission`
+ * collapses it to a one-liner that matches the shape of
+ * {@link requestResourceAllocation} (throws on error, returns the unwrapped
+ * payload on success).
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { enumValue, getTruApi, type RemotePermission } from "./truapi.js";
+
+const log = createLogger("host:permissions");
+
+/**
+ * Request a single remote permission from the host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.permission`, unwraps the response,
+ * and returns the host's boolean granted/denied outcome.
+ *
+ * @param permission - The remote permission to request.
+ * @returns `true` if the host granted the permission, `false` if denied.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const granted = await requestPermission({ tag: "ChainSubmit", value: undefined });
+ * if (!granted) {
+ *   tellUserToReconnect();
+ * }
+ * ```
+ */
+export async function requestPermission(permission: RemotePermission): Promise<boolean> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("requestPermission: TruAPI unavailable");
+    }
+    log.debug("requestPermission", { tag: permission.tag });
+
+    return await truApi.permission(enumValue("v1", permission)).match(
+        (envelope: { tag: "v1"; value: boolean }) => envelope.value,
+        (err: unknown) => {
+            throw new Error(
+                `requestPermission failed: ${err instanceof Error ? err.message : String(err)}`,
+                { cause: err },
+            );
+        },
+    );
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: { permission?: (req: unknown) => unknown } | null,
+        fn: (mod: typeof import("./permissions.js")) => Promise<T>,
+    ): Promise<T> {
+        vi.resetModules();
+        vi.doMock("./truapi.js", () => ({
+            getTruApi: async () => bridge,
+            enumValue: (version: string, value: unknown) => ({ tag: version, value }),
+        }));
+        try {
+            const mod = await import("./permissions.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    describe("requestPermission", () => {
+        test("throws when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                await expect(
+                    mod.requestPermission({ tag: "ChainSubmit", value: undefined }),
+                ).rejects.toThrow(/TruAPI unavailable/);
+            });
+        });
+
+        test("unwraps the v1 boolean outcome", async () => {
+            await withMockedTruApi(
+                {
+                    permission: vi.fn().mockReturnValue({
+                        match: async (onOk: (v: unknown) => unknown) =>
+                            onOk({ tag: "v1", value: true }),
+                    }),
+                },
+                async (mod) => {
+                    const granted = await mod.requestPermission({
+                        tag: "ChainSubmit",
+                        value: undefined,
+                    });
+                    expect(granted).toBe(true);
+                },
+            );
+        });
+
+        test("wraps host errors with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    permission: vi.fn().mockReturnValue({
+                        match: async (
+                            _onOk: (v: unknown) => unknown,
+                            onErr: (e: unknown) => unknown,
+                        ) =>
+                            onErr({
+                                tag: "v1",
+                                value: { name: "GenericError", message: "boom" },
+                            }),
+                    }),
+                },
+                async (mod) => {
+                    await expect(
+                        mod.requestPermission({ tag: "ChainSubmit", value: undefined }),
+                    ).rejects.toThrow(/requestPermission failed/);
+                },
+            );
+        });
+    });
+}

package/src/truapi.ts

@@ -10,8 +10,35 @@
 
 import { createLogger } from "@parity/product-sdk-logger";
 
+import { enumValue } from "@novasamatech/host-api";
+import type {
+    AllocatableResource as AllocatableResourceCodec,
+    AllocationOutcome as AllocationOutcomeCodec,
+    CodecType,
+    RemotePermission as RemotePermissionCodec,
+    Statement as StatementCodec,
+} from "@novasamatech/host-api";
+
+import type { StatementProof } from "./types.js";
+
 const log = createLogger("host");
 
+/**
+ * Extract a human-readable message from an unknown error. `JSON.stringify`
+ * on `Error` returns `"{}"` because `message` and `stack` are non-enumerable
+ * — without this helper, wire failures surface as `"... failed: {}"` with
+ * zero diagnostic context.
+ */
+function formatError(err: unknown): string {
+    if (err instanceof Error) return err.message;
+    if (typeof err === "string") return err;
+    try {
+        return JSON.stringify(err);
+    } catch {
+        return String(err);
+    }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers from @novasamatech/host-api (re-exported from @novasamatech/scale)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -202,6 +229,160 @@ export async function getAccountsProvider(): Promise<AccountsProvider | null> {
     }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Resource allocation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resource types requestable via {@link requestResourceAllocation}.
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+export type AllocatableResource = CodecType<typeof AllocatableResourceCodec>;
+
+/** Tag-only view of {@link AllocatableResource} for places that just need the variant name. */
+export type AllocatableResourceTag = AllocatableResource["tag"];
+
+/**
+ * Per-resource outcome from {@link requestResourceAllocation}.
+ * The host strips secret payloads from `Allocated` before returning, so
+ * `value` is always `undefined` on the product side.
+ */
+export type AllocationOutcome = CodecType<typeof AllocationOutcomeCodec>;
+
+/** Tag-only view of {@link AllocationOutcome} (`"Allocated" | "Rejected" | "NotAvailable"`). */
+export type AllocationOutcomeTag = AllocationOutcome["tag"];
+
+/**
+ * Remote permission the dapp can ask the host to grant via
+ * {@link requestPermission}.
+ *
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+export type RemotePermission = CodecType<typeof RemotePermissionCodec>;
+
+/** Tag-only view of {@link RemotePermission}. */
+export type RemotePermissionTag = RemotePermission["tag"];
+
+/**
+ * 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 Per-resource outcomes in the same order as `resources`.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const outcomes = await requestResourceAllocation([
+ *   { tag: "BulletInAllowance", value: undefined },
+ * ]);
+ * if (outcomes[0].tag === "Allocated") { ... }
+ * ```
+ */
+export async function requestResourceAllocation(
+    resources: AllocatableResource[],
+): Promise<AllocationOutcome[]> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("requestResourceAllocation: TruAPI unavailable");
+    }
+    log.debug("requestResourceAllocation", { resources: resources.map((r) => r.tag) });
+
+    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.
+    return await truApi.requestResourceAllocation(enumValue("v1", resources)).match(
+        (envelope: { tag: "v1"; value: AllocationOutcome[] }) => envelope.value,
+        (err: unknown) => {
+            throw new Error(`requestResourceAllocation failed: ${formatError(err)}`, {
+                cause: err,
+            });
+        },
+    );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Authorized Statement Store proof creation (RFC-10 §"Statement Store allowance")
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A Statement payload destined for the Statement Store. Matches the
+ * `pallet-statement` Statement structure.
+ *
+ * The optional `proof` field is the same {@link StatementProof} shape that
+ * {@link createProofAuthorized} returns: pass `undefined` here, call
+ * `createProofAuthorized` to obtain the proof, then attach it before
+ * submitting via `HostStatementStore.submit`. The `OnChain` variant of
+ * `StatementProof` is a chain-attestation reference; the `Sr25519` /
+ * `Ed25519` / `Ecdsa` variants are signing proofs.
+ *
+ * Derived from the upstream codec so structural changes surface as compile
+ * errors here, not runtime decode failures.
+ */
+export type Statement = CodecType<typeof StatementCodec>;
+
+/**
+ * Have the host sign a Statement using an allowance-bearing account it
+ * picks internally — RFC-10 §"Statement Store allowance".
+ *
+ * The product passes only the Statement payload; the host chooses the
+ * `//allowance//statement-store//{productId}` account that holds SSS
+ * allowance and signs with it. Allowance is provisioned implicitly on
+ * first use if the host hasn't already pre-allocated via
+ * {@link requestResourceAllocation}; products never see the signing
+ * account or its key material.
+ *
+ * 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 The proof to attach before submitting.
+ * @throws If the host is unavailable or the host-side signing fails.
+ *
+ * @example
+ * ```ts
+ * import { createProofAuthorized, getStatementStore } from "@parity/product-sdk-host";
+ *
+ * const statement = {
+ *     proof: undefined,
+ *     decryptionKey: undefined,
+ *     expiry: undefined,
+ *     channel: undefined,
+ *     topics: [],
+ *     data: payload,
+ * };
+ * const proof = await createProofAuthorized(statement);
+ * const store = await getStatementStore();
+ * await store?.submit({ ...statement, proof });
+ * ```
+ *
+ * @remarks
+ * RFC-10 introduces this as a new, strictly additive TruAPI call. The
+ * pre-existing `HostStatementStore.createProof(accountId, statement)`
+ * surface stays available for products that own a non-allowance signing
+ * account; this wrapper is the sponsored-submission path.
+ */
+export async function createProofAuthorized(statement: Statement): Promise<StatementProof> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("createProofAuthorized: TruAPI unavailable");
+    }
+    log.debug("createProofAuthorized", {
+        topics: statement.topics.length,
+        dataLen: statement.data?.length ?? 0,
+    });
+
+    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.
+    return await truApi.statementStoreCreateProofAuthorized(enumValue("v1", statement)).match(
+        (envelope: { tag: "v1"; value: StatementProof }) => envelope.value,
+        (err: unknown) => {
+            throw new Error(`createProofAuthorized failed: ${formatError(err)}`, { cause: err });
+        },
+    );
+}
+
 /**
  * One of the user's existing wallet accounts, surfaced through the host and
  * identified by its public key and an optional name. Contrast with
@@ -376,4 +557,35 @@ if (import.meta.vitest) {
         const { enumValue } = await import("./truapi.js");
         expect(typeof enumValue).toBe("function");
     });
+
+    test("requestResourceAllocation throws when TruAPI is unavailable", async () => {
+        cachedTruApi = null;
+        const api = await getTruApi();
+        if (api === null) {
+            await expect(
+                requestResourceAllocation([{ tag: "BulletInAllowance", value: undefined }]),
+            ).rejects.toThrow(/TruAPI unavailable/);
+        } else {
+            expect(typeof requestResourceAllocation).toBe("function");
+        }
+    });
+
+    test("createProofAuthorized throws when TruAPI is unavailable", async () => {
+        cachedTruApi = null;
+        const api = await getTruApi();
+        if (api === null) {
+            await expect(
+                createProofAuthorized({
+                    proof: undefined,
+                    decryptionKey: undefined,
+                    expiry: undefined,
+                    channel: undefined,
+                    topics: [],
+                    data: undefined,
+                }),
+            ).rejects.toThrow(/TruAPI unavailable/);
+        } else {
+            expect(typeof createProofAuthorized).toBe("function");
+        }
+    });
 }