@prosopo/keyring 2.9.61 → 2.9.63

package/src/accounts/getPair.test.ts

@@ -0,0 +1,142 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// 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 { u8aToHex } from "@polkadot/util";
+import type { KeyringPair$Json } from "@prosopo/types";
+import { encodeAddress, sr25519FromSeed } from "@prosopo/util-crypto";
+import { describe, expect, it } from "vitest";
+import { DEV_PHRASE, Keyring } from "../keyring/index.js";
+import { getPair } from "./getPair.js";
+
+const SEED_32 = new Uint8Array(32).fill(7);
+const SEED_HEX = u8aToHex(SEED_32);
+const ALICE_PUBLIC =
+	"0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d";
+
+const pairJson = (
+	overrides: Partial<KeyringPair$Json> = {},
+): KeyringPair$Json => ({
+	address: encodeAddress(new Uint8Array(32).fill(8), 42),
+	encoded: "0x00",
+	encoding: { content: ["pkcs8", "sr25519"], type: ["none"], version: "3" },
+	meta: {},
+	...overrides,
+});
+
+// Key derivation runs scrypt/pbkdf2 with production parameters and takes
+// seconds per call, so these suites need more than the 10s default.
+const SLOW = { timeout: 60000 };
+
+describe("getPair secret handling", SLOW, () => {
+	it("derives from a mnemonic", () => {
+		expect(getPair(DEV_PHRASE).address).toBe(
+			new Keyring({ ss58Format: 42 }).addFromMnemonic(DEV_PHRASE).address,
+		);
+	});
+
+	it("derives from a hex seed", () => {
+		expect(u8aToHex(getPair(SEED_HEX).publicKey)).toBe(
+			u8aToHex(sr25519FromSeed(SEED_32).publicKey),
+		);
+	});
+
+	it("derives from a suri with a hard derivation path", () => {
+		expect(u8aToHex(getPair(`${DEV_PHRASE}//Alice`).publicKey)).toBe(
+			ALICE_PUBLIC,
+		);
+	});
+
+	it("prefers the mnemonic branch over the suri branch", () => {
+		// A bare valid mnemonic contains no "//", but the ordering matters if
+		// one is ever added: mnemonic validation must win so the derivation
+		// path is honoured rather than the whole string being padded.
+		const suri = `${DEV_PHRASE}//1`;
+		expect(getPair(suri).address).not.toBe(getPair(DEV_PHRASE).address);
+	});
+
+	it("parses a JSON string, taking the crypto type from its encoding", () => {
+		const pair = getPair(JSON.stringify(pairJson()));
+		expect(pair.type).toBe("sr25519");
+		expect(u8aToHex(pair.publicKey)).toBe(u8aToHex(new Uint8Array(32).fill(8)));
+	});
+
+	it("accepts a JSON object directly", () => {
+		expect(getPair(pairJson()).type).toBe("sr25519");
+	});
+
+	it("reports a missing secret when the string is neither key nor JSON", () => {
+		// The unparseable case funnels into the same error as a genuinely
+		// absent secret, so an operator sees one actionable message.
+		expect(() => getPair("this is not a secret")).toThrow();
+	});
+
+	it("reports a missing secret for JSON without an encoding block", () => {
+		expect(() => getPair('{"address":"x"}')).toThrow();
+	});
+
+	it("throws when neither a secret nor an account is given", () => {
+		expect(() => getPair()).toThrow();
+	});
+
+	it("throws when the secret is an empty string and no account is given", () => {
+		expect(() => getPair("")).toThrow();
+	});
+});
+
+describe("getPair account handling", SLOW, () => {
+	it("builds a watch-only pair from an address when no secret is given", () => {
+		const address = getPair(DEV_PHRASE).address;
+		const watchOnly = getPair(undefined, address);
+		expect(watchOnly.address).toBe(address);
+		expect(watchOnly.isLocked).toBe(true);
+	});
+
+	it("accepts a raw public key as the account", () => {
+		const pair = getPair(DEV_PHRASE);
+		expect(getPair(undefined, pair.publicKey).address).toBe(pair.address);
+	});
+
+	it("ignores the account once a secret is supplied", () => {
+		const other = getPair(`${DEV_PHRASE}//other`).address;
+		expect(getPair(DEV_PHRASE, other).address).toBe(
+			getPair(DEV_PHRASE).address,
+		);
+	});
+});
+
+describe("getPair defaults", SLOW, () => {
+	it("defaults to sr25519 and ss58 format 42", () => {
+		const pair = getPair(DEV_PHRASE);
+		expect(pair.type).toBe("sr25519");
+		expect(pair.address).toBe(encodeAddress(pair.publicKey, 42));
+	});
+
+	it("honours an explicit ss58 format", () => {
+		const pair = getPair(DEV_PHRASE, undefined, "sr25519", 2);
+		expect(pair.address).toBe(encodeAddress(pair.publicKey, 2));
+	});
+
+	it("rejects a pair type the keyring does not support", () => {
+		expect(() => getPair(DEV_PHRASE, undefined, "ed25519")).toThrow(
+			"Expected a keyring type of either 'sr25519'",
+		);
+	});
+
+	it("treats ss58 format 0 as unset, because it is falsy", () => {
+		// Documents a live quirk of the `||` defaulting: Polkadot's own
+		// format 0 cannot be requested and silently becomes 42.
+		const pair = getPair(DEV_PHRASE, undefined, "sr25519", 0);
+		expect(pair.address).toBe(encodeAddress(pair.publicKey, 42));
+	});
+});

package/src/accounts/mnemonic.test.ts

@@ -0,0 +1,103 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// 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 { u8aToHex } from "@polkadot/util";
+import {
+	mnemonicToMiniSecret,
+	mnemonicValidate,
+	sr25519FromSeed,
+} from "@prosopo/util-crypto";
+import { describe, expect, it } from "vitest";
+import { Keyring } from "../keyring/index.js";
+import { generateMiniSecret, generateMnemonic } from "./mnemonic.js";
+
+// Key derivation runs scrypt/pbkdf2 with production parameters and takes
+// seconds per call, so these suites need more than the 10s default.
+const SLOW = { timeout: 60000 };
+
+describe("generateMnemonic", SLOW, () => {
+	it("returns a valid twelve word mnemonic and its address", async () => {
+		const [mnemonic, address] = await generateMnemonic();
+		expect(mnemonic.split(" ")).toHaveLength(12);
+		expect(mnemonicValidate(mnemonic)).toBe(true);
+		expect(address).toBe(new Keyring().addFromMnemonic(mnemonic).address);
+	});
+
+	it("generates a fresh mnemonic each call", async () => {
+		// A repeated mnemonic would mean every generated account shares a key.
+		const [first] = await generateMnemonic();
+		const [second] = await generateMnemonic();
+		expect(second).not.toBe(first);
+	});
+
+	it("adds the account to a keyring it is given", async () => {
+		const keyring = new Keyring();
+		const [, address] = await generateMnemonic(keyring);
+		expect(keyring.getPairs()).toHaveLength(1);
+		expect(keyring.getPair(address).address).toBe(address);
+	});
+
+	it("uses a fresh keyring when none is passed, leaving no shared state", async () => {
+		const keyring = new Keyring();
+		await generateMnemonic();
+		expect(keyring.getPairs()).toEqual([]);
+	});
+
+	it("honours the requested pair type when it creates the keyring", async () => {
+		const [, address] = await generateMnemonic(undefined, "sr25519");
+		expect(typeof address).toBe("string");
+		await expect(generateMnemonic(undefined, "ed25519")).rejects.toThrow(
+			"Expected a keyring type of either 'sr25519'",
+		);
+	});
+
+	it("ignores the pair type when a keyring is supplied", async () => {
+		// The keyring already fixes the curve; the argument is only used to
+		// construct one, so an incompatible value must not throw here.
+		const keyring = new Keyring({ type: "sr25519" });
+		await expect(generateMnemonic(keyring, "ed25519")).resolves.toBeDefined();
+	});
+});
+
+describe("generateMiniSecret", SLOW, () => {
+	it("returns the 32 byte mini secret for the generated mnemonic", async () => {
+		const keyring = new Keyring();
+		const [secret, address] = await generateMiniSecret(keyring);
+
+		expect(secret).toHaveLength(32);
+		expect(u8aToHex(sr25519FromSeed(secret).publicKey)).toBe(
+			u8aToHex(keyring.getPair(address).publicKey),
+		);
+	});
+
+	it("derives the secret from the same mnemonic it registered", async () => {
+		const keyring = new Keyring();
+		const [secret] = await generateMiniSecret(keyring);
+		const registered = keyring.getPairs()[0];
+		expect(registered).toBeDefined();
+		expect(u8aToHex(secret)).not.toBe(u8aToHex(new Uint8Array(32)));
+	});
+
+	it("agrees with mnemonicToMiniSecret for a known phrase", async () => {
+		const phrase =
+			"bottom drive obey lake curtain smoke basket hold race lonely fit walk";
+		expect(u8aToHex(mnemonicToMiniSecret(phrase))).toHaveLength(66);
+	});
+
+	it("generates a fresh secret each call", async () => {
+		const [first] = await generateMiniSecret();
+		const [second] = await generateMiniSecret();
+		expect(u8aToHex(second)).not.toBe(u8aToHex(first));
+	});
+});

package/src/accounts/testAccounts.test.ts

@@ -0,0 +1,100 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// 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 { CaptchaType } from "@prosopo/types";
+import { describe, expect, it } from "vitest";
+import { DEV_PHRASE } from "../keyring/index.js";
+import { getPair } from "./getPair.js";
+import { getDefaultProviders, getDefaultSiteKeys } from "./testAccounts.js";
+
+// Key derivation runs scrypt/pbkdf2 with production parameters and takes
+// seconds per call, so these suites need more than the 10s default.
+const SLOW = { timeout: 60000 };
+
+describe("getDefaultSiteKeys", SLOW, () => {
+	it("provides one site per captcha type, in a stable order", () => {
+		expect(
+			getDefaultSiteKeys().map((site) => site.settings.captchaType),
+		).toEqual([
+			CaptchaType.image,
+			CaptchaType.pow,
+			CaptchaType.frictionless,
+			CaptchaType.puzzle,
+		]);
+	});
+
+	it("derives each site key from the dev phrase and its captcha type", () => {
+		// The seeded dev site keys are checked into fixtures and referenced by
+		// the demos, so the derivation must not drift.
+		for (const site of getDefaultSiteKeys()) {
+			expect(site.secret).toBe(`${DEV_PHRASE}//${site.settings.captchaType}`);
+			expect(site.address).toBe(getPair(site.secret).address);
+			expect(site.pair?.address).toBe(site.address);
+		}
+	});
+
+	it("gives every site a distinct address", () => {
+		const addresses = getDefaultSiteKeys().map((site) => site.address);
+		expect(new Set(addresses).size).toBe(addresses.length);
+	});
+
+	it("writes the settings explicitly rather than leaning on schema defaults", () => {
+		for (const site of getDefaultSiteKeys()) {
+			expect(site.settings.domains).toEqual(["localhost"]);
+			expect(site.settings.imageMaxRounds).toBe(2);
+			expect(site.settings.frictionlessThreshold).toBe(0.8);
+		}
+	});
+
+	it("returns a fresh array each call, so callers cannot corrupt the seed", () => {
+		const first = getDefaultSiteKeys();
+		const second = getDefaultSiteKeys();
+		expect(first).not.toBe(second);
+		first.pop();
+		expect(second).toHaveLength(4);
+	});
+});
+
+describe("getDefaultProviders", SLOW, () => {
+	it("provides a single local provider with a matching pair and address", () => {
+		const providers = getDefaultProviders();
+		expect(providers).toHaveLength(1);
+		const provider = providers[0];
+		expect(provider).toBeDefined();
+		if (!provider) return;
+		expect(provider.url).toBe("https://localhost:9229");
+		expect(provider.address).toBe(provider.pair?.address);
+	});
+
+	it("points at the checked-in dev dataset", () => {
+		const provider = getDefaultProviders()[0];
+		expect(provider?.datasetFile).toBe("./dev/data/captchas.json");
+		expect(provider?.captchaDatasetId).toMatch(/^0x[0-9a-f]{64}$/);
+	});
+
+	it("is deterministic across calls", () => {
+		expect(getDefaultProviders()[0]?.address).toBe(
+			getDefaultProviders()[0]?.address,
+		);
+	});
+
+	it("does not reuse a site key as the provider key", () => {
+		const siteAddresses = new Set(
+			getDefaultSiteKeys().map((site) => site.address),
+		);
+		expect(siteAddresses.has(getDefaultProviders()[0]?.address ?? "")).toBe(
+			false,
+		);
+	});
+});