@parity/product-sdk-auth 0.2.0

package/src/sessionSigner.test.ts

@@ -0,0 +1,101 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, test } from "vitest";
+import { ss58Encode } from "@parity/product-sdk-address";
+import { seedToAccount } from "@parity/product-sdk-keys";
+import type { UserSession } from "@parity/product-sdk-terminal";
+import { createSessionSigner } from "./sessionSigner.js";
+
+const DEV_PHRASE = "bottom drive obey lake curtain smoke basket hold race lonely fit walk";
+// Injected product id (the consumer supplies this via ProductAccountRef). Uses
+// the same value playground derives from so the product account is identical.
+const PRODUCT_ID = "playground.dot";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Account equivalence — pins the invariant that every flow which references
+// "the user's account" resolves to the *same* SS58: the product account
+// derived at `mnemonic + "/product/{PRODUCT_ID}/0"`.
+//
+// The signer built by `createSessionSigner(session, {productId, derivationIndex})`
+// must SS58-equal the mobile/playground-app derivation
+// `seedToAccount(mnemonic, "/product/{PRODUCT_ID}/0")`. These tests are the
+// regression guard against the pre-fix bug where the signer used the wallet
+// account (`remoteAccount.accountId`) instead of the product account.
+// ────────────────────────────────────────────────────────────────────────────
+describe("session signer account equivalence", () => {
+    // Stand-in for the mobile's SSO handshake response: `rootAccountId` is
+    // `deriveRootAccount()` on the mobile = the bare-mnemonic keypair pubkey.
+    // Other fields aren't read by `createSessionSigner` in the path under test.
+    function fakeSession(mnemonic: string): UserSession {
+        const root = seedToAccount(mnemonic, "");
+        const wallet = seedToAccount(mnemonic, "//SomeWallet"); // user picking a derived account on mobile
+        return {
+            id: "test",
+            localAccount: { accountId: new Uint8Array(32), pin: undefined },
+            remoteAccount: {
+                accountId: wallet.publicKey,
+                publicKey: wallet.publicKey,
+                pin: undefined,
+            },
+            rootAccountId: root.publicKey,
+        } as unknown as UserSession;
+    }
+
+    test("session signer address === product-account derivation address", () => {
+        const session = fakeSession(DEV_PHRASE);
+
+        const cliSigner = createSessionSigner(session, {
+            productId: PRODUCT_ID,
+            derivationIndex: 0,
+        });
+        const cliAddress = ss58Encode(cliSigner.publicKey);
+
+        const mobileDerived = seedToAccount(DEV_PHRASE, `/product/${PRODUCT_ID}/0`);
+        const productAccountAddress = ss58Encode(mobileDerived.publicKey);
+
+        expect(cliAddress).toEqual(productAccountAddress);
+    });
+
+    test("regression: signer does NOT use remoteAccount.accountId (= wallet account)", () => {
+        const session = fakeSession(DEV_PHRASE);
+        const cliSigner = createSessionSigner(session, {
+            productId: PRODUCT_ID,
+            derivationIndex: 0,
+        });
+        const cliAddress = ss58Encode(cliSigner.publicKey);
+        const walletAddress = ss58Encode(new Uint8Array(session.remoteAccount.accountId));
+
+        // Pre-fix bug: signer.publicKey was set from session.remoteAccount.accountId
+        // (the user's wallet account), not the product-derived account. The wallet
+        // account is what the chain would see as From — different from the funded /
+        // allowance-granted product account. This guard ensures we never slip back.
+        expect(cliAddress).not.toEqual(walletAddress);
+    });
+
+    test("reports stale sessions without a root account public key", () => {
+        const session = {
+            ...fakeSession(DEV_PHRASE),
+            rootAccountId: new Uint8Array(),
+        } as UserSession;
+
+        expect(() =>
+            createSessionSigner(session, {
+                productId: PRODUCT_ID,
+                derivationIndex: 0,
+            }),
+        ).toThrow("Stored login session is missing the root account public key.");
+    });
+});

package/src/sessionSigner.ts

@@ -0,0 +1,31 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Session-backed signing for a product account.
+ *
+ * All of this lives in `@parity/product-sdk-terminal` — the session signer, the
+ * product-account derivation, and the stale-session guard. This module is a
+ * thin re-export so auth consumers get one import surface; nothing is
+ * implemented twice.
+ */
+
+export {
+    createSessionSignerForAccount as createSessionSigner,
+    deriveProductPublicKey,
+    sessionRootPublicKey,
+    INCOMPLETE_SESSION_MESSAGE,
+} from "@parity/product-sdk-terminal";
+export type { ProductAccountRef } from "@parity/product-sdk-terminal";

package/src/signer.test.ts

@@ -0,0 +1,97 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, test } from "vitest";
+import { ss58Encode } from "@parity/product-sdk-address";
+import { getDevPublicKey } from "@parity/product-sdk-tx";
+import { seedToAccount } from "@parity/product-sdk-keys";
+import { resolveSigner, SignerNotAvailableError, parseDevAccountName } from "./signer.js";
+import type { AuthClient } from "./auth.js";
+
+const DEV_PHRASE = "bottom drive obey lake curtain smoke basket hold race lonely fit walk";
+
+// Minimal AuthClient stub — only `getSessionSigner` is exercised by resolveSigner.
+function stubAuthClient(session: Awaited<ReturnType<AuthClient["getSessionSigner"]>>): AuthClient {
+    return {
+        getSessionSigner: async () => session,
+    } as unknown as AuthClient;
+}
+
+describe("parseDevAccountName", () => {
+    test("recognizes well-known dev SURIs (exact case, // prefix)", () => {
+        expect(parseDevAccountName("//Alice")).toBe("Alice");
+        expect(parseDevAccountName("//Bob")).toBe("Bob");
+    });
+    test("requires the // prefix — a bare name is not a dev SURI", () => {
+        expect(parseDevAccountName("Alice")).toBeNull();
+    });
+    test("is case-sensitive, matching Substrate SURI semantics", () => {
+        expect(parseDevAccountName("//alice")).toBeNull();
+        expect(parseDevAccountName("//BOB")).toBeNull();
+    });
+    test("returns null for non-dev suris", () => {
+        expect(parseDevAccountName("//NotADev")).toBeNull();
+        expect(parseDevAccountName(DEV_PHRASE)).toBeNull();
+    });
+});
+
+describe("resolveSigner", () => {
+    const noSession = stubAuthClient(null);
+
+    test("--suri //Alice → dev signer at Alice's address", async () => {
+        const r = await resolveSigner(noSession, { suri: "//Alice" });
+        expect(r.source).toBe("dev");
+        expect(r.address).toBe(ss58Encode(getDevPublicKey("Alice")));
+    });
+
+    test("--suri <mnemonic> → dev signer at the seed-derived address", async () => {
+        const r = await resolveSigner(noSession, { suri: DEV_PHRASE });
+        expect(r.source).toBe("dev");
+        expect(r.address).toBe(ss58Encode(seedToAccount(DEV_PHRASE, "").publicKey));
+    });
+
+    test("--suri <mnemonic>//path → dev signer at the derived sub-account", async () => {
+        const r = await resolveSigner(noSession, { suri: `${DEV_PHRASE}//stash` });
+        expect(r.source).toBe("dev");
+        expect(r.address).toBe(ss58Encode(seedToAccount(DEV_PHRASE, "//stash").publicKey));
+    });
+
+    test("garbage suri → throws 'Unrecognized SURI'", async () => {
+        await expect(resolveSigner(noSession, { suri: "not a valid suri !!" })).rejects.toThrow(
+            /Unrecognized SURI/,
+        );
+    });
+
+    test("no suri + no session → SignerNotAvailableError", async () => {
+        await expect(resolveSigner(noSession)).rejects.toBeInstanceOf(SignerNotAvailableError);
+    });
+
+    test("no suri + a session → session signer (source 'session')", async () => {
+        const fakeHandle = {
+            address: "5SESSION",
+            addresses: {
+                rootAddress: "r",
+                productAddress: "5SESSION",
+                productH160: "0xabc" as `0x${string}`,
+            },
+            signer: {} as never,
+            userSession: {} as never,
+            destroy() {},
+        };
+        const r = await resolveSigner(stubAuthClient(fakeHandle));
+        expect(r.source).toBe("session");
+        expect(r.address).toBe("5SESSION");
+    });
+});

package/src/signer.ts

@@ -0,0 +1,124 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Unified signer resolution — "give me a PolkadotSigner, I don't care how."
+ * Lifted from playground-cli `src/utils/signer.ts` (issue #411).
+ *
+ * Dev accounts (`--suri //Alice`) and QR mobile sessions both produce the same
+ * `PolkadotSigner` interface. Consumers call `resolveSigner(authClient)` once at
+ * startup and thread the result through all operations. The `authClient` (from
+ * `createAuthClient`) supplies the session branch, so this module stays free of
+ * product-specific config.
+ */
+
+import { ss58Encode } from "@parity/product-sdk-address";
+import { createDevSigner, getDevPublicKey, type DevAccountName } from "@parity/product-sdk-tx";
+import { seedToAccount } from "@parity/product-sdk-keys";
+import type { PolkadotSigner } from "polkadot-api";
+import type { AuthClient, SessionAddresses, SessionHandle } from "./auth.js";
+
+export type SignerSource = "dev" | "session";
+
+export interface ResolvedSigner {
+    signer: PolkadotSigner;
+    address: string;
+    source: SignerSource;
+    /** Present for QR/mobile sessions; absent for local dev/SURI signers. */
+    userSession?: SessionHandle["userSession"];
+    /** Root / product / H160 triple — present for QR/mobile sessions only. */
+    addresses?: SessionAddresses;
+    /** Tear down session adapter. Call in a finally block. No-op for dev signers. */
+    destroy(): void;
+}
+
+export interface SignerOptions {
+    /** Secret URI like "//Alice". Takes priority over session. */
+    suri?: string;
+}
+
+export class SignerNotAvailableError extends Error {
+    constructor() {
+        super('No signer available. Run "login" to sign in, or pass --suri //Alice for dev.');
+        this.name = "SignerNotAvailableError";
+    }
+}
+
+const DEV_NAMES: readonly DevAccountName[] = ["Alice", "Bob", "Charlie", "Dave", "Eve", "Ferdie"];
+
+/**
+ * Parse a well-known dev-account SURI (`//Alice`, `//Bob`, …).
+ *
+ * Requires the `//` hard-derivation prefix and an exact-case name, matching
+ * Substrate SURI semantics (and `createDevSigner`, which derives `//${name}`).
+ * A bare `Alice` or a different case is NOT a dev SURI — it falls through to the
+ * mnemonic path in `resolveSigner`, where it fails as an invalid mnemonic.
+ */
+export function parseDevAccountName(suri: string): DevAccountName | null {
+    if (!suri.startsWith("//")) return null;
+    const name = suri.slice(2);
+    return DEV_NAMES.find((n) => n === name) ?? null;
+}
+
+/**
+ * Resolve a PolkadotSigner.
+ *
+ *   1. `--suri` flag → dev signer (dev name like //Alice, OR a BIP-39 mnemonic
+ *      with optional `//<path>` derivation suffix)
+ *   2. Persisted QR session → session signer (via `authClient.getSessionSigner`)
+ *   3. Neither → `SignerNotAvailableError`
+ */
+export async function resolveSigner(
+    authClient: AuthClient,
+    options?: SignerOptions,
+): Promise<ResolvedSigner> {
+    if (options?.suri) {
+        const devName = parseDevAccountName(options.suri);
+        if (devName) {
+            return {
+                signer: createDevSigner(devName),
+                address: ss58Encode(getDevPublicKey(devName)),
+                source: "dev",
+                destroy() {},
+            };
+        }
+        // Mnemonic path. Split off an optional `//<path>` derivation suffix so
+        // callers can target a sub-account of the same seed without a separate flag.
+        const sepIdx = options.suri.indexOf("//");
+        const mnemonic = (sepIdx === -1 ? options.suri : options.suri.slice(0, sepIdx)).trim();
+        const path = sepIdx === -1 ? "" : options.suri.slice(sepIdx);
+        try {
+            const account = seedToAccount(mnemonic, path);
+            return {
+                signer: account.signer,
+                address: ss58Encode(account.publicKey),
+                source: "dev",
+                destroy() {},
+            };
+        } catch {
+            throw new Error(
+                `Unrecognized SURI "${options.suri}". ` +
+                    `Expected a dev name (${DEV_NAMES.join(", ")}) or a BIP-39 mnemonic.`,
+            );
+        }
+    }
+
+    const session = await authClient.getSessionSigner();
+    if (session) {
+        return { ...session, source: "session" };
+    }
+
+    throw new SignerNotAvailableError();
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Per-product configuration injected into `createAuthClient`. Lifting the
+ * sign-in glue out of playground-cli (issue #411) means the env-specific
+ * constants playground hard-coded in its `config.ts` (DAPP_ID, product id,
+ * People-chain endpoints) become consumer-supplied so the same package serves
+ * `playground` and `dot` (and future products) unchanged.
+ */
+export interface AuthConfig {
+    /** The dApp identity string. Scopes the on-disk session namespace
+     *  (`~/.polkadot-apps/${dappId}_*`) and the SSO pairing — each product
+     *  gets its own, independently-revocable session. */
+    dappId: string;
+    /** Product id used to derive the product account (`/product/{productId}/{index}`). */
+    productId: string;
+    /** Derivation index of the product account (0 = default). */
+    derivationIndex: number;
+    /** People-parachain RPC endpoints the terminal adapter connects to. */
+    peopleEndpoints: string[];
+}

package/src/ui/index.ts

@@ -0,0 +1,22 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * `@parity/product-sdk-auth/ui` — terminal UI helpers (QR rendering + login/
+ * logout status formatters). Separate entrypoint so headless consumers can
+ * import the package root without pulling terminal-rendering deps.
+ */
+export { renderQrCode } from "./qr.js";
+export { renderLoginStatus, renderLogoutStatus } from "./status.js";

package/src/ui/qr.ts

@@ -0,0 +1,22 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * QR rendering for the terminal. Re-exported from `@parity/product-sdk-terminal`
+ * so consumers get the login QR without depending on the terminal package
+ * directly. Lives under the `./ui` entrypoint (pulls terminal-rendering deps);
+ * headless consumers import the package root instead.
+ */
+export { renderQrCode } from "@parity/product-sdk-terminal";

package/src/ui/status.test.ts

@@ -0,0 +1,60 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, test } from "vitest";
+import { renderLoginStatus, renderLogoutStatus } from "./status.js";
+
+describe("renderLoginStatus", () => {
+    test("waiting", () => {
+        expect(renderLoginStatus({ step: "waiting" })).toMatch(/scan/i);
+    });
+    test("paired", () => {
+        expect(renderLoginStatus({ step: "paired" })).toMatch(/finishing/i);
+    });
+    test("pending surfaces the stage", () => {
+        expect(renderLoginStatus({ step: "pending", stage: "attestation" })).toContain(
+            "attestation",
+        );
+    });
+    test("success surfaces the address", () => {
+        expect(
+            renderLoginStatus({
+                step: "success",
+                address: "5Fy2sypq",
+                addresses: { rootAddress: "r", productAddress: "5Fy2sypq", productH160: "0xabc" },
+            }),
+        ).toContain("5Fy2sypq");
+    });
+    test("error surfaces the message", () => {
+        expect(renderLoginStatus({ step: "error", message: "boom" })).toContain("boom");
+    });
+});
+
+describe("renderLogoutStatus", () => {
+    test("disconnecting", () => {
+        expect(renderLogoutStatus({ step: "disconnecting", address: "5X" })).toContain("5X");
+    });
+    test("success", () => {
+        expect(renderLogoutStatus({ step: "success", address: "5X" })).toMatch(/signed out/i);
+    });
+    test("partial surfaces the reason", () => {
+        expect(renderLogoutStatus({ step: "partial", address: "5X", reason: "ws down" })).toContain(
+            "ws down",
+        );
+    });
+    test("error surfaces the message", () => {
+        expect(renderLogoutStatus({ step: "error", message: "nope" })).toContain("nope");
+    });
+});

package/src/ui/status.ts

@@ -0,0 +1,49 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Pure formatters that map the `LoginStatus` / `LogoutStatus` streams to
+ * one-line terminal messages. No I/O, no terminal deps — `import type` only,
+ * so this module stays unit-testable without the SSO stack.
+ */
+import type { LoginStatus, LogoutStatus } from "../auth.js";
+
+export function renderLoginStatus(status: LoginStatus): string {
+    switch (status.step) {
+        case "waiting":
+            return "Waiting for you to scan the QR code with your phone…";
+        case "paired":
+            return "Paired — finishing sign-in…";
+        case "pending":
+            return `Working: ${status.stage}…`;
+        case "success":
+            return `Signed in as ${status.address}`;
+        case "error":
+            return `Sign-in failed: ${status.message}`;
+    }
+}
+
+export function renderLogoutStatus(status: LogoutStatus): string {
+    switch (status.step) {
+        case "disconnecting":
+            return `Signing out ${status.address}…`;
+        case "success":
+            return `Signed out ${status.address}`;
+        case "partial":
+            return `Signed out locally (${status.address}); the phone was not notified: ${status.reason}`;
+        case "error":
+            return `Sign-out error: ${status.message}`;
+    }
+}