@parity/product-sdk-signer 0.6.4 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-sdk-signer",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Signer manager for Polkadot — Host API and dev accounts",
   "type": "module",
   "sideEffects": false,
@@ -20,13 +20,13 @@
   "dependencies": {
     "polkadot-api": "^2.1.5",
     "@parity/product-sdk-address": "0.1.1",
-    "@parity/product-sdk-keys": "0.3.7",
-    "@parity/product-sdk-logger": "0.1.1",
-    "@parity/product-sdk-host": "0.9.0"
+    "@parity/product-sdk-host": "0.10.0",
+    "@parity/product-sdk-keys": "0.3.8",
+    "@parity/product-sdk-logger": "0.1.1"
   },
   "optionalDependencies": {
-    "@novasamatech/host-api-wrapper": "^0.8.7-2",
-    "@novasamatech/host-api": "^0.8.7-2"
+    "@novasamatech/host-api-wrapper": "^0.8.7",
+    "@novasamatech/host-api": "^0.8.7"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/errors.ts

@@ -10,7 +10,18 @@ export class SignerError extends Error {
     }
 }
 
-/** The Host API is not available (product-sdk not installed or not inside a container). */
+/**
+ * The Host API is not available.
+ *
+ * Common causes:
+ * - The app is loaded outside a Polkadot host container (a regular browser tab
+ *   under `npm run dev`, no iframe, no WebView). This is the dominant case
+ *   during local development.
+ * - The optional `@novasamatech/host-api(-wrapper)` peer is not installed.
+ *
+ * Branch with `instanceof HostUnavailableError` to surface a "open this app
+ * in a Polkadot host, or pick a dev provider" message to the user.
+ */
 export class HostUnavailableError extends SignerError {
     constructor(message = "Host API is not available") {
         super(message);

package/src/providers/host.ts

@@ -55,8 +55,6 @@ export interface HostProviderOptions {
      * `dotNsIdentifier`, skipping the legacy fetch entirely. For apps
      * that sign exclusively with a per-dapp derived account.
      *
-     * `SignerAccount.name` is populated best-effort from
-     * `accounts.getUserId().primaryUsername`; failures leave it null.
      * Signing is pinned to `createTransaction` (see PR #96).
      */
     productAccount?: {
@@ -64,6 +62,20 @@ export interface HostProviderOptions {
         dotNsIdentifier: string;
         /** Derivation index within the app scope. Default: 0. */
         derivationIndex?: number;
+        /**
+         * Populate `SignerAccount.name` best-effort from
+         * `accounts.getUserId().primaryUsername`.
+         *
+         * On by default. Set to `false` to skip the fetch: `getUserId`
+         * triggers a host identity-permission prompt, so apps that don't
+         * render the user's name (those with their own display chain, e.g.
+         * registry username → fallback) can opt out and avoid the prompt.
+         * When enabled and the fetch fails (NotConnected, PermissionDenied,
+         * codec drift) the name stays null and connect still succeeds. The
+         * name can also be fetched later on demand via
+         * {@link HostProvider.getUserId}. Default: `true`.
+         */
+        requestName?: boolean;
     };
 }
 
@@ -181,6 +193,15 @@ export interface ProductSdkModule {
     createAccountsProvider: () => AccountsProvider;
     /** Present from product-sdk ≥ 0.6; used to request TransactionSubmit. */
     hostApi?: HostApiPermissionBridge;
+    /**
+     * `sandboxTransport.isCorrectEnvironment()` returns `false` when the app
+     * is loaded outside a Polkadot host container (e.g. a regular browser
+     * tab). Calling `getLegacyAccounts()` / `getProductAccount()` in that
+     * state surfaces the upstream `Environment is not correct` exception,
+     * so we pre-check during `connect()` and raise a specific
+     * {@link HostUnavailableError} with actionable guidance instead.
+     */
+    sandboxTransport?: { isCorrectEnvironment(): boolean };
 }
 
 /* @integration */
@@ -196,9 +217,13 @@ async function defaultLoadHostApiEnum(): Promise<HostApiEnumHelper> {
 /**
  * Provider for the Host API (Polkadot Desktop / Android).
  *
- * Dynamically imports `@novasamatech/host-api-wrapper` at runtime so it remains
- * an optional peer dependency. Apps running outside a host container will
- * gracefully get a `HOST_UNAVAILABLE` error.
+ * Dynamically imports `@novasamatech/host-api-wrapper` at runtime. Apps running
+ * outside a host container — e.g. a plain browser tab during `npm run dev` —
+ * resolve to {@link HostUnavailableError} with guidance on what to do (open
+ * the app inside a Polkadot host or pick a non-host provider). The check uses
+ * the wrapper's `sandboxTransport.isCorrectEnvironment()` predicate and runs
+ * before any host RPC call, so the user never sees the upstream
+ * `Environment is not correct` exception leaking through.
  *
  * Supports both non-product accounts (user's external wallets) and product
  * accounts (app-scoped derived accounts managed by the host).
@@ -395,6 +420,43 @@ export class HostProvider implements SignerProvider {
         }
     }
 
+    /**
+     * Fetch the connected user's primary username from the host.
+     *
+     * Use this to retrieve the name lazily — e.g. on a profile screen that
+     * actually displays it — when `connect()` ran without
+     * `productAccount.requestName` (the default) and so never fetched it.
+     * Like the connect-time fetch this triggers a host identity-permission
+     * prompt; unlike it, the result is returned as a structured `Result` so
+     * callers can react to a `PermissionDenied` / `NotConnected` rejection
+     * explicitly instead of silently falling back to a nameless account.
+     *
+     * Requires a prior successful `connect()` call.
+     */
+    async getUserId(): Promise<Result<{ primaryUsername: string }, SignerError>> {
+        if (!this.accountsProvider) {
+            return err(new HostUnavailableError("Host provider is not connected"));
+        }
+
+        try {
+            const result = (await this.accountsProvider.getUserId().match(
+                (value) => value,
+                (error) => {
+                    throw new Error(`Host rejected user id request: ${formatError(error)}`);
+                },
+            )) as { primaryUsername: string };
+
+            return ok(result);
+        } catch (cause) {
+            log.error("failed to get user id", { cause });
+            return err(
+                new HostRejectedError(
+                    cause instanceof Error ? cause.message : "Failed to get user id",
+                ),
+            );
+        }
+    }
+
     /**
      * Create a Ring VRF proof for anonymous operations.
      *
@@ -454,11 +516,41 @@ export class HostProvider implements SignerProvider {
             );
         }
 
-        // Step 2: Create accounts provider
+        // Step 2: Verify we're actually running inside a host container.
+        //
+        // The upstream `host-api` transport throws `Error('Environment is not
+        // correct')` from inside `getLegacyAccounts()` / `getProductAccount()`
+        // when `sandboxTransport.isCorrectEnvironment()` returns false (i.e.
+        // we're not in an iframe under Polkadot Desktop, or a WebView under
+        // Polkadot Mobile). Without this pre-check, that exception used to
+        // surface as `HostRejectedError("Host rejected account request:
+        // Environment is not correct")` — misleading because no host rejected
+        // anything; there's no host at all.
+        //
+        // Returning `HostUnavailableError` here matches the TSDoc contract
+        // ("Apps running outside a host container will gracefully get a
+        // HOST_UNAVAILABLE error") and gives consumers actionable guidance.
+        //
+        // The `sandboxTransport` field is optional in `ProductSdkModule` so
+        // older wrapper versions (or test mocks that don't supply it) keep
+        // working — we fall through to the existing flow and rely on the
+        // catch in Step 4 as a safety net.
+        if (sdk.sandboxTransport && !sdk.sandboxTransport.isCorrectEnvironment()) {
+            log.warn("not inside a host container — Host API unavailable");
+            return err(
+                new HostUnavailableError(
+                    "Host API is not available: not running inside a Polkadot host container. " +
+                        "Open this app inside Polkadot Desktop or the Polkadot Mobile WebView, " +
+                        "or pick a non-host signer provider (e.g. dev accounts).",
+                ),
+            );
+        }
+
+        // Step 3: Create accounts provider
         const provider = sdk.createAccountsProvider();
         this.accountsProvider = provider;
 
-        // Step 3: Fetch accounts.
+        // Step 4: Fetch accounts.
         //
         // When `productAccount` is configured, skip the legacy fetch entirely
         // and return a single product account. Product-account-only apps
@@ -471,6 +563,7 @@ export class HostProvider implements SignerProvider {
                 provider,
                 this.productAccount.dotNsIdentifier,
                 this.productAccount.derivationIndex ?? 0,
+                this.productAccount.requestName ?? true,
             );
             if (!accountResult.ok) return accountResult;
             signerAccounts = [accountResult.value];
@@ -484,6 +577,24 @@ export class HostProvider implements SignerProvider {
                     },
                 )) as RawAccount[];
             } catch (cause) {
+                // Safety net: upstream `host-api/transport.js` throws
+                // `Error('Environment is not correct')` synchronously inside
+                // `getLegacyAccounts()` when the env check fails. The Step 2
+                // pre-check catches this normally, but we also re-classify
+                // here for older wrappers that don't expose `sandboxTransport`
+                // and for races where the env flips after the pre-check.
+                // Without this, the user sees a misleading "Host rejected
+                // account request:" prefix for an error nothing rejected.
+                if (cause instanceof Error && /environment is not correct/i.test(cause.message)) {
+                    log.warn("not inside a host container (detected at getLegacyAccounts)");
+                    return err(
+                        new HostUnavailableError(
+                            "Host API is not available: not running inside a Polkadot host container. " +
+                                "Open this app inside Polkadot Desktop or the Polkadot Mobile WebView, " +
+                                "or pick a non-host signer provider (e.g. dev accounts).",
+                        ),
+                    );
+                }
                 log.error("failed to get accounts from host", { cause });
                 return err(
                     new HostRejectedError(
@@ -500,7 +611,7 @@ export class HostProvider implements SignerProvider {
             signerAccounts = this.mapAccounts(rawAccounts);
         }
 
-        // Step 4: Request ChainSubmit permission up-front.
+        // Step 5: Request ChainSubmit permission up-front.
         //
         // The host gates signing on this permission — without it, the
         // production host rejects every sign request with `PermissionDenied`
@@ -561,14 +672,19 @@ export class HostProvider implements SignerProvider {
         provider: AccountsProvider,
         dotNsIdentifier: string,
         derivationIndex: number,
+        requestName: boolean,
     ): Promise<Result<SignerAccount, SignerError>> {
-        // Run the account fetch and the best-effort username fetch in
-        // parallel — they're independent host RPCs. `getUserId` failures
-        // (NotConnected, PermissionDenied, codec drift) resolve to `null`
-        // so they never abort connect; the account name falls back to
-        // whatever `getProductAccount` returned (typically also null,
-        // since product accounts are nameless on the host side).
+        // The name fetch is on by default; `requestName: false` opts out.
+        // `getUserId` triggers a host identity-permission prompt, so apps
+        // that don't render the user's name can skip it. When enabled it
+        // runs in parallel with the account fetch — they're independent host
+        // RPCs — and its failures (NotConnected, PermissionDenied, codec
+        // drift) resolve to `null` so they never abort connect; the account
+        // name then falls back to whatever `getProductAccount` returned
+        // (typically also null, since product accounts are nameless on the
+        // host side).
         const fetchUsername = async (): Promise<string | null> => {
+            if (!requestName) return null;
             try {
                 return await provider.getUserId().match(
                     (result) => result.primaryUsername,
@@ -747,11 +863,21 @@ if (import.meta.vitest) {
         mockProvider: ReturnType<typeof createMockProvider>,
         opts?: {
             hostApi?: HostApiPermissionBridge;
+            /**
+             * When provided, the mock's `sandboxTransport.isCorrectEnvironment()`
+             * returns this value — exercises the env-check branch added in the
+             * `connect()` flow. Omit to skip the check entirely (older-wrapper
+             * compatibility path).
+             */
+            isCorrectEnvironment?: boolean;
         },
     ): ProductSdkModule {
         return {
             createAccountsProvider: () => mockProvider as unknown as AccountsProvider,
             ...(opts?.hostApi ? { hostApi: opts.hostApi } : {}),
+            ...(opts?.isCorrectEnvironment !== undefined
+                ? { sandboxTransport: { isCorrectEnvironment: () => opts.isCorrectEnvironment! } }
+                : {}),
         };
     }
 
@@ -791,6 +917,89 @@ if (import.meta.vitest) {
             }
         });
 
+        test("returns HOST_UNAVAILABLE with actionable guidance when not inside a host container", async () => {
+            // Repro for playground-cli#4: `pg mod foo` + `npm run dev` opens
+            // localhost in a plain browser tab (no iframe, no WebView).
+            // sandboxTransport.isCorrectEnvironment() returns false, and
+            // pre-fix we surfaced the upstream "Environment is not correct"
+            // as `HostRejectedError("Host rejected account request: ...")`.
+            // Post-fix: we pre-check during connect() and return a specific
+            // HostUnavailableError naming the host container and pointing
+            // the user at the fix path.
+            const mockProvider = createMockProvider({ accounts: [] });
+            const provider = new HostProvider({
+                maxRetries: 1,
+                loadSdk: () =>
+                    Promise.resolve(createMockSdk(mockProvider, { isCorrectEnvironment: false })),
+            });
+            const result = await provider.connect();
+
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(HostUnavailableError);
+                expect(result.error.message).toMatch(
+                    /not running inside a Polkadot host container/i,
+                );
+                expect(result.error.message).toMatch(/Polkadot Desktop|Polkadot Mobile/i);
+            }
+            // We never reached `getLegacyAccounts()` — proves the env check
+            // short-circuits before any RPC call, so users in a dev browser
+            // never see the upstream exception text leak through.
+            expect(mockProvider.getLegacyAccounts).not.toHaveBeenCalled();
+        });
+
+        test("safety net: re-classifies upstream 'Environment is not correct' as HOST_UNAVAILABLE", async () => {
+            // For older wrappers (or test mocks) that don't supply
+            // `sandboxTransport`, the Step 2 pre-check is skipped and the
+            // upstream throw surfaces at `getLegacyAccounts()`. The catch
+            // in Step 4 must re-classify it rather than wrapping with the
+            // misleading "Host rejected account request:" prefix.
+            const mockProvider = createMockProvider({
+                shouldReject: true,
+                error: "Environment is not correct",
+            });
+            const provider = new HostProvider({
+                maxRetries: 1,
+                // sandboxTransport intentionally omitted — exercises the
+                // safety-net path, not the pre-check path.
+                loadSdk: () => Promise.resolve(createMockSdk(mockProvider)),
+            });
+            const result = await provider.connect();
+
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(HostUnavailableError);
+                // Must NOT contain the misleading "Host rejected account request:" prefix.
+                expect(result.error.message).not.toMatch(/Host rejected/i);
+                expect(result.error.message).toMatch(
+                    /not running inside a Polkadot host container/i,
+                );
+            }
+        });
+
+        test("connect proceeds when sandboxTransport reports a correct environment", async () => {
+            // Mirror of the existing happy path, but with an explicit
+            // `isCorrectEnvironment: true` to prove the pre-check doesn't
+            // false-fail when the env IS correct.
+            const rawAccounts: RawAccountTest[] = [
+                { publicKey: new Uint8Array(32).fill(0x42), name: "Alice" },
+            ];
+            const mockProvider = createMockProvider({ accounts: rawAccounts });
+            const provider = new HostProvider({
+                maxRetries: 1,
+                loadSdk: () =>
+                    Promise.resolve(createMockSdk(mockProvider, { isCorrectEnvironment: true })),
+            });
+            const result = await provider.connect();
+
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toHaveLength(1);
+                expect(result.value[0].address).toMatch(/^5/);
+            }
+            expect(mockProvider.getLegacyAccounts).toHaveBeenCalled();
+        });
+
         test("returns HOST_REJECTED when getLegacyAccounts fails", async () => {
             const mockProvider = createMockProvider({ shouldReject: true, error: "Rejected" });
             const provider = new HostProvider({
@@ -899,7 +1108,7 @@ if (import.meta.vitest) {
             unsub();
         });
 
-        test("productAccount option returns the derived account, populates name via getUserId, and skips the legacy fetch", async () => {
+        test("productAccount populates name via getUserId by default and skips the legacy fetch", async () => {
             const productPubkey = new Uint8Array(32).fill(0xcc);
             const mockProvider = createMockProvider({
                 accounts: [{ publicKey: productPubkey, name: undefined }],
@@ -932,7 +1141,33 @@ if (import.meta.vitest) {
             expect(mockProvider.getLegacyAccounts).not.toHaveBeenCalled();
         });
 
-        test("productAccount option survives getUserId failure (name stays null, connect still succeeds)", async () => {
+        test("productAccount with requestName:false skips getUserId (no identity prompt) and leaves name null", async () => {
+            // Opt-out: `getUserId` triggers a host identity-permission prompt,
+            // so apps that don't render the name set `requestName: false`.
+            const productPubkey = new Uint8Array(32).fill(0xab);
+            const mockProvider = createMockProvider({
+                accounts: [{ publicKey: productPubkey, name: undefined }],
+                primaryUsername: "alice",
+            });
+            const provider = new HostProvider({
+                maxRetries: 1,
+                loadSdk: () => Promise.resolve(createMockSdk(mockProvider)),
+                productAccount: { dotNsIdentifier: "myapp.dot", requestName: false },
+            });
+            const result = await provider.connect();
+
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toHaveLength(1);
+                expect(result.value[0].publicKey).toEqual(productPubkey);
+                expect(result.value[0].name).toBeNull();
+            }
+            expect(mockProvider.getProductAccount).toHaveBeenCalledWith("myapp.dot", 0);
+            expect(mockProvider.getUserId).not.toHaveBeenCalled();
+            expect(mockProvider.getLegacyAccounts).not.toHaveBeenCalled();
+        });
+
+        test("productAccount survives getUserId failure (name stays null, connect still succeeds)", async () => {
             const productPubkey = new Uint8Array(32).fill(0xee);
             const mockProvider = createMockProvider({
                 accounts: [{ publicKey: productPubkey, name: undefined }],
@@ -957,6 +1192,62 @@ if (import.meta.vitest) {
             }
         });
 
+        test("getUserId() retrieves the primary username after a connect that opted out of the name fetch", async () => {
+            // The escape hatch for `requestName: false`: connect without the
+            // prompt (name=null), then fetch the name lazily later — e.g. when
+            // a profile screen needs to display it.
+            const productPubkey = new Uint8Array(32).fill(0xa1);
+            const mockProvider = createMockProvider({
+                accounts: [{ publicKey: productPubkey, name: undefined }],
+                primaryUsername: "alice",
+            });
+            const provider = new HostProvider({
+                maxRetries: 1,
+                loadSdk: () => Promise.resolve(createMockSdk(mockProvider)),
+                productAccount: { dotNsIdentifier: "myapp.dot", requestName: false },
+            });
+            const connectResult = await provider.connect();
+            expect(connectResult.ok).toBe(true);
+            if (connectResult.ok) expect(connectResult.value[0].name).toBeNull();
+            // Not fetched during connect...
+            expect(mockProvider.getUserId).not.toHaveBeenCalled();
+
+            // ...but reachable on demand afterwards.
+            const userId = await provider.getUserId();
+            expect(userId.ok).toBe(true);
+            if (userId.ok) expect(userId.value.primaryUsername).toBe("alice");
+            expect(mockProvider.getUserId).toHaveBeenCalledTimes(1);
+        });
+
+        test("getUserId() returns HostUnavailableError before connect", async () => {
+            const provider = new HostProvider({ maxRetries: 1 });
+            const result = await provider.getUserId();
+            expect(result.ok).toBe(false);
+            if (!result.ok) expect(result.error).toBeInstanceOf(HostUnavailableError);
+        });
+
+        test("getUserId() surfaces a host rejection as HostRejectedError", async () => {
+            const mockProvider = createMockProvider({
+                accounts: [{ publicKey: new Uint8Array(32).fill(0xa2), name: undefined }],
+            });
+            const provider = new HostProvider({
+                maxRetries: 1,
+                loadSdk: () => Promise.resolve(createMockSdk(mockProvider)),
+                productAccount: { dotNsIdentifier: "myapp.dot", requestName: false },
+            });
+            await provider.connect();
+            // After connect, force the host to reject the on-demand fetch.
+            mockProvider.getUserId.mockReturnValue({
+                match: async (
+                    _onOk: (v: { primaryUsername: string }) => unknown,
+                    onErr: (e: unknown) => unknown,
+                ) => onErr({ tag: "v1", value: { tag: "GetUserIdErr::PermissionDenied" } }),
+            });
+            const result = await provider.getUserId();
+            expect(result.ok).toBe(false);
+            if (!result.ok) expect(result.error).toBeInstanceOf(HostRejectedError);
+        });
+
         test("productAccount option succeeds when host has no legacy accounts (regression: signer 0.5.0 NoAccountsError)", async () => {
             // Without the option, this scenario returned `err(NoAccountsError)`
             // before any product-account fetch could happen — breaking every