@prosopo/keyring 2.9.61 → 2.9.62

package/src/keyring/pairs.test.ts

@@ -0,0 +1,133 @@
+// 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 type { KeyringPair } from "@prosopo/types";
+import { decodeAddress, encodeAddress } from "@prosopo/util-crypto";
+import { describe, expect, it } from "vitest";
+import { nobody } from "../pair/nobody.js";
+import { Pairs } from "./pairs.js";
+
+/**
+ * A pair is stored under `decodeAddress(pair.address).toString()`, which is the
+ * comma-joined bytes of the public key. Only `address` and `publicKey` are read
+ * by `Pairs`, so the inert `nobody` pair supplies the rest of the surface.
+ */
+const stubPair = (publicKey: Uint8Array): KeyringPair => ({
+	...nobody(),
+	address: encodeAddress(publicKey, 42),
+	addressRaw: publicKey,
+	publicKey,
+});
+
+const keyOf = (byte: number): Uint8Array => new Uint8Array(32).fill(byte);
+
+describe("Pairs", () => {
+	it("returns the pair it was given, so callers can chain off add", () => {
+		const pairs = new Pairs();
+		const pair = stubPair(keyOf(1));
+		expect(pairs.add(pair)).toBe(pair);
+	});
+
+	it("starts empty", () => {
+		expect(new Pairs().all()).toEqual([]);
+	});
+
+	it("retrieves a pair by SS58 address, public key or raw bytes", () => {
+		const pairs = new Pairs();
+		const publicKey = keyOf(2);
+		const pair = pairs.add(stubPair(publicKey));
+
+		expect(pairs.get(pair.address)).toBe(pair);
+		expect(pairs.get(publicKey)).toBe(pair);
+		// A different SS58 prefix decodes to the same public key, so it must
+		// find the same pair — the map is keyed on bytes, not on the string.
+		expect(pairs.get(encodeAddress(publicKey, 2))).toBe(pair);
+	});
+
+	it("keeps only the latest pair for a public key", () => {
+		const pairs = new Pairs();
+		const publicKey = keyOf(3);
+		pairs.add(stubPair(publicKey));
+		const second = stubPair(publicKey);
+		pairs.add(second);
+
+		expect(pairs.all()).toHaveLength(1);
+		expect(pairs.get(publicKey)).toBe(second);
+	});
+
+	it("keeps distinct public keys apart", () => {
+		const pairs = new Pairs();
+		const first = pairs.add(stubPair(keyOf(4)));
+		const second = pairs.add(stubPair(keyOf(5)));
+
+		expect(pairs.all()).toEqual([first, second]);
+		expect(pairs.get(first.address)).toBe(first);
+		expect(pairs.get(second.address)).toBe(second);
+	});
+
+	it("names the address it could not find, formatting bytes as hex", () => {
+		const pairs = new Pairs();
+		// A caller debugging a missing key needs to see which key was asked
+		// for; a bare "not found" would be useless.
+		expect(() => pairs.get(keyOf(6))).toThrow(
+			`Unable to retrieve keypair '0x${"06".repeat(32)}'`,
+		);
+	});
+
+	it("names the address verbatim when it was given as SS58", () => {
+		const address = encodeAddress(keyOf(7), 42);
+		expect(() => new Pairs().get(address)).toThrow(
+			`Unable to retrieve keypair '${address}'`,
+		);
+	});
+
+	it("rejects an address that is not decodable at all", () => {
+		expect(() => new Pairs().get("not-an-address")).toThrow();
+	});
+
+	it("removes a pair, after which lookup throws again", () => {
+		const pairs = new Pairs();
+		const publicKey = keyOf(8);
+		pairs.add(stubPair(publicKey));
+		pairs.remove(publicKey);
+
+		expect(pairs.all()).toEqual([]);
+		expect(() => pairs.get(publicKey)).toThrow("Unable to retrieve keypair");
+	});
+
+	it("removes by any encoding of the same key", () => {
+		const pairs = new Pairs();
+		const publicKey = keyOf(9);
+		const pair = pairs.add(stubPair(publicKey));
+		pairs.remove(encodeAddress(publicKey, 2));
+		expect(pairs.all()).toEqual([]);
+		expect(pair.address).toBe(encodeAddress(publicKey, 42));
+	});
+
+	it("ignores removal of a key that was never added", () => {
+		const pairs = new Pairs();
+		const kept = pairs.add(stubPair(keyOf(10)));
+		expect(() => pairs.remove(keyOf(11))).not.toThrow();
+		expect(pairs.all()).toEqual([kept]);
+	});
+
+	it("decodes the address for the map key rather than trusting the string", () => {
+		// Guards the assumption the class is built on: two encodings of one
+		// key must decode to identical bytes.
+		const publicKey = keyOf(12);
+		expect(decodeAddress(encodeAddress(publicKey, 42)).toString()).toBe(
+			decodeAddress(encodeAddress(publicKey, 2)).toString(),
+		);
+	});
+});

package/src/keyring/testing.test.ts

@@ -0,0 +1,146 @@
+// 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 { describe, expect, it } from "vitest";
+import { PAIRSSR25519, createTestKeyring } from "./testing.js";
+import { createTestPairs } from "./testingPairs.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("createTestKeyring", SLOW, () => {
+	it("adds a pair for every well-known dev account", () => {
+		expect(createTestKeyring().getPairs()).toHaveLength(PAIRSSR25519.length);
+	});
+
+	it("names each pair after its seed, lowercased with the path flattened", () => {
+		// `Alice//stash` becomes `alice_stash`, which is the name the rest of
+		// the stack looks pairs up by.
+		const names = createTestKeyring()
+			.getPairs()
+			.map((pair) => pair.meta.name);
+		expect(names).toEqual([
+			"alice",
+			"alice_stash",
+			"bob",
+			"bob_stash",
+			"charlie",
+			"dave",
+			"eve",
+			"ferdie",
+		]);
+	});
+
+	it("marks every pair as a testing pair", () => {
+		for (const pair of createTestKeyring().getPairs()) {
+			expect(pair.meta.isTesting).toBe(true);
+		}
+	});
+
+	it("uses the hard-coded public keys, not derivation, by default", () => {
+		const keyring = createTestKeyring();
+		for (const { p } of PAIRSSR25519) {
+			expect(u8aToHex(keyring.getPair(p).publicKey)).toBe(p);
+		}
+	});
+
+	it("replaces lock with a no-op so the fixtures stay usable", () => {
+		// The pairs carry their secret in the clear; locking them would make
+		// every downstream test fail to sign.
+		const pair = createTestKeyring().getPairs()[0];
+		expect(pair).toBeDefined();
+		if (!pair) return;
+		expect(() => pair.lock()).not.toThrow();
+		expect(pair.isLocked).toBe(false);
+	});
+
+	it("produces signable pairs", () => {
+		const pair = createTestKeyring().getPair(PAIRSSR25519[0]?.p ?? "0x");
+		const message = new TextEncoder().encode("hello");
+		expect(pair.verify(message, pair.sign(message), pair.publicKey)).toBe(true);
+	});
+
+	it("honours a requested ss58 format", () => {
+		const alice = PAIRSSR25519[0]?.p ?? "0x";
+		expect(
+			createTestKeyring({ ss58Format: 42 }).getPair(alice).address,
+		).not.toBe(createTestKeyring({ ss58Format: 2 }).getPair(alice).address);
+	});
+
+	it("derives different keys when asked to, because the seeds are bare names", () => {
+		// The `isDerived = false` branch feeds the seed straight to
+		// `addFromUri`, and the seeds are names like "Alice" rather than
+		// "//Alice". They are therefore padded raw phrases, not dev-phrase
+		// derivations, so the pairs are NOT the well-known dev accounts.
+		// Anything relying on Alice's address must use the default mode.
+		const derived = createTestKeyring({}, false);
+		expect(derived.getPairs()).toHaveLength(PAIRSSR25519.length);
+		for (const { p } of PAIRSSR25519) {
+			expect(() => derived.getPair(p)).toThrow("Unable to retrieve keypair");
+		}
+	});
+
+	it("rejects a keyring type it cannot support", () => {
+		expect(() => createTestKeyring({ type: "ed25519" })).toThrow(
+			"Expected a keyring type of either 'sr25519'",
+		);
+	});
+});
+
+describe("createTestPairs", SLOW, () => {
+	it("exposes every named pair plus nobody", () => {
+		const pairs = createTestPairs();
+		for (const name of [
+			"nobody",
+			"alice",
+			"alice_stash",
+			"bob",
+			"bob_stash",
+			"charlie",
+			"dave",
+			"eve",
+			"ferdie",
+		]) {
+			expect(pairs[name], name).toBeDefined();
+		}
+	});
+
+	it("maps alice to the well-known Alice public key", () => {
+		expect(
+			u8aToHex(createTestPairs().alice?.publicKey ?? new Uint8Array()),
+		).toBe(PAIRSSR25519[0]?.p);
+	});
+
+	it("includes nobody, which cannot verify anything", () => {
+		const nobodyPair = createTestPairs().nobody;
+		expect(nobodyPair).toBeDefined();
+		expect(nobodyPair?.isLocked).toBe(true);
+		expect(
+			nobodyPair?.verify(
+				new Uint8Array(1),
+				new Uint8Array(64),
+				nobodyPair.publicKey,
+			),
+		).toBe(false);
+	});
+
+	it("returns independent maps so one test cannot poison another", () => {
+		const first = createTestPairs();
+		const second = createTestPairs();
+		expect(first).not.toBe(second);
+		expect(first.alice).not.toBe(second.alice);
+	});
+});

package/src/keyring.test-d.ts

@@ -0,0 +1,134 @@
+// 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 type {
+	IProviderAccount,
+	ISite,
+	KeyringInstance,
+	KeyringPair,
+	KeyringPair$Json,
+} from "@prosopo/types";
+import { assertType, describe, expectTypeOf, it } from "vitest";
+import {
+	Keyring,
+	generateMiniSecret,
+	generateMnemonic,
+	getDefaultProviders,
+	getDefaultSiteKeys,
+	getPair,
+} from "./index.js";
+// The testing helpers and `nobody` are deliberately not re-exported from the
+// package barrel, so they are imported from their modules directly.
+import type {
+	DetectMap,
+	DetectPairType,
+	TestKeyringMapEthereum,
+	TestKeyringMapSubstrate,
+} from "./keyring/testingPairs.js";
+import { nobody } from "./pair/nobody.js";
+
+describe("Keyring types", () => {
+	it("implements the shared KeyringInstance contract", () => {
+		expectTypeOf<Keyring>().toExtend<KeyringInstance>();
+	});
+
+	it("returns KeyringPair from every add and create method", () => {
+		const keyring = new Keyring();
+		expectTypeOf(keyring.addFromUri("//Alice")).toEqualTypeOf<KeyringPair>();
+		expectTypeOf(keyring.addFromMnemonic("x")).toEqualTypeOf<KeyringPair>();
+		expectTypeOf(
+			keyring.addFromSeed(new Uint8Array()),
+		).toEqualTypeOf<KeyringPair>();
+		expectTypeOf(keyring.addFromAddress("x")).toEqualTypeOf<KeyringPair>();
+		expectTypeOf(keyring.getPair("x")).toEqualTypeOf<KeyringPair>();
+		expectTypeOf(keyring.getPairs()).toEqualTypeOf<KeyringPair[]>();
+		expectTypeOf(keyring.publicKeys).toEqualTypeOf<Uint8Array[]>();
+		expectTypeOf(keyring.toJson("x")).toEqualTypeOf<KeyringPair$Json>();
+	});
+
+	it("accepts an address as either a string or raw bytes", () => {
+		const keyring = new Keyring();
+		assertType(keyring.getPair("5abc"));
+		assertType(keyring.getPair(new Uint8Array(32)));
+		// @ts-expect-error a number is not an address
+		assertType(keyring.getPair(1));
+	});
+
+	it("rejects a keyring option object with an unknown key", () => {
+		// @ts-expect-error `curve` is not an option
+		new Keyring({ curve: "sr25519" });
+	});
+
+	it("has a readonly type", () => {
+		expectTypeOf<Keyring["type"]>().toEqualTypeOf<
+			import("@prosopo/util-crypto").KeypairType
+		>();
+	});
+});
+
+describe("account helper types", () => {
+	it("returns a pair from getPair with every argument optional", () => {
+		expectTypeOf(getPair).returns.toEqualTypeOf<KeyringPair>();
+		assertType(getPair());
+		assertType(getPair("secret", "account", "sr25519", 42));
+	});
+
+	it("returns the mnemonic and address as a tuple", () => {
+		expectTypeOf(generateMnemonic).returns.resolves.toEqualTypeOf<
+			[string, string]
+		>();
+	});
+
+	it("returns the mini secret as bytes paired with an address", () => {
+		expectTypeOf(generateMiniSecret).returns.resolves.toEqualTypeOf<
+			[Uint8Array, string]
+		>();
+	});
+
+	it("describes the dev fixtures with the shared account types", () => {
+		expectTypeOf(getDefaultSiteKeys()).toEqualTypeOf<ISite[]>();
+		expectTypeOf(getDefaultProviders()).toEqualTypeOf<IProviderAccount[]>();
+	});
+
+	it("returns a real KeyringPair for nobody", () => {
+		expectTypeOf(nobody()).toEqualTypeOf<KeyringPair>();
+	});
+});
+
+describe("test keyring map inference", () => {
+	it("defaults to the substrate map when no options are given", () => {
+		expectTypeOf<DetectPairType<undefined>>().toEqualTypeOf<"sr25519">();
+		expectTypeOf<
+			DetectMap<undefined>
+		>().toEqualTypeOf<TestKeyringMapSubstrate>();
+	});
+
+	it("selects the ethereum map only for an ethereum keyring", () => {
+		expectTypeOf<
+			DetectMap<{ type: "ethereum" }>
+		>().toEqualTypeOf<TestKeyringMapEthereum>();
+		expectTypeOf<
+			DetectMap<{ type: "sr25519" }>
+		>().toEqualTypeOf<TestKeyringMapSubstrate>();
+	});
+
+	it("indexes the map by arbitrary names, always yielding a pair", () => {
+		expectTypeOf<
+			TestKeyringMapSubstrate["alice"]
+		>().toEqualTypeOf<KeyringPair>();
+		expectTypeOf<
+			TestKeyringMapSubstrate["anything-else"]
+		>().toEqualTypeOf<KeyringPair>();
+	});
+});

package/src/pair/decode.spec.ts

@@ -13,7 +13,9 @@ describe("decode", (): void => {
 		);
 	});
 
-	it("returns correct publicKey from encoded", (): void => {
+	// scrypt with the production parameters takes several seconds, which
+	// overruns the 10s default on a loaded CI runner.
+	it("returns correct publicKey from encoded", { timeout: 60000 }, (): void => {
 		const PASS = "testing";
 
 		expect((): void =>

package/src/pair/encode.spec.ts

@@ -18,7 +18,13 @@ describe("encode", (): void => {
 		expect(keyring.alice.encodePkcs8()).toHaveLength(DECODED_LENGTH);
 	});
 
-	it("returns encoded PKCS8 when passphrase supplied", (): void => {
-		expect(keyring.alice.encodePkcs8("testing")).toHaveLength(ENCODED_LENGTH);
-	});
+	// scrypt with the production parameters takes several seconds, which
+	// overruns the 10s default on a loaded CI runner.
+	it(
+		"returns encoded PKCS8 when passphrase supplied",
+		{ timeout: 60000 },
+		(): void => {
+			expect(keyring.alice.encodePkcs8("testing")).toHaveLength(ENCODED_LENGTH);
+		},
+	);
 });

package/src/pair/nobody.test.ts

@@ -0,0 +1,127 @@
+// 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 { encodeAddress } from "@prosopo/util-crypto";
+import { describe, expect, it } from "vitest";
+import {
+	PAIR_DIV,
+	PAIR_HDR,
+	PUB_LENGTH,
+	SALT_LENGTH,
+	SEC_LENGTH,
+	SEED_LENGTH,
+} from "./defaults.js";
+import { nobody } from "./nobody.js";
+
+describe("nobody", () => {
+	it("is the all-zero public key, encoded as the well-known address", () => {
+		const pair = nobody();
+		expect(pair.publicKey).toEqual(new Uint8Array(32));
+		expect(pair.address).toBe(
+			"5C4hrfjw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM",
+		);
+		// The address is a pre-computed constant in the source; if the encoding
+		// ever changed, the constant would silently be wrong.
+		expect(pair.address).toBe(encodeAddress(pair.publicKey, 42));
+	});
+
+	it("is permanently locked", () => {
+		const pair = nobody();
+		expect(pair.isLocked).toBe(true);
+		pair.unlock("anything");
+		expect(pair.isLocked).toBe(true);
+		pair.lock();
+		expect(pair.isLocked).toBe(true);
+	});
+
+	it("never verifies a signature, whatever it is given", () => {
+		// This is the whole point of the pair: it stands in for "no account"
+		// and must never authenticate anyone.
+		const pair = nobody();
+		expect(
+			pair.verify(new Uint8Array(1), new Uint8Array(64), pair.publicKey),
+		).toBe(false);
+		expect(
+			pair.verify(
+				new Uint8Array(0),
+				pair.sign(new Uint8Array(1)),
+				pair.publicKey,
+			),
+		).toBe(false);
+		expect(
+			pair.vrfVerify(new Uint8Array(1), new Uint8Array(96), pair.publicKey),
+		).toBe(false);
+	});
+
+	it("never reports a JWT as valid", () => {
+		const result = nobody().jwtVerify(nobody().jwtIssue());
+		expect(result.isValid).toBe(false);
+		expect(result.error).toBe("JWT verification failed");
+		expect(result.publicKey).toEqual(new Uint8Array(32));
+	});
+
+	it("returns correctly sized but empty signatures", () => {
+		const pair = nobody();
+		expect(pair.sign(new Uint8Array(1))).toEqual(new Uint8Array(64));
+		expect(pair.vrfSign(new Uint8Array(1))).toEqual(new Uint8Array(96));
+		expect(pair.encodePkcs8()).toEqual(new Uint8Array(0));
+	});
+
+	it("derives to itself, so no chain of derivation can escape it", () => {
+		const pair = nobody();
+		expect(pair.derive("//anything")).toBe(pair);
+		expect(pair.derive("//a").derive("//b")).toBe(pair);
+	});
+
+	it("ignores attempts to change its meta", () => {
+		const pair = nobody();
+		pair.setMeta({ name: "somebody" });
+		expect(pair.meta.name).toBe("nobody");
+		expect(pair.meta.isTesting).toBe(true);
+	});
+
+	it("serialises to an unencrypted v0 json blob", () => {
+		const json = nobody().toJson();
+		expect(json.address).toBe(nobody().address);
+		expect(json.encoded).toBe("");
+		expect(json.encoding.version).toBe("0");
+		expect(json.encoding.type).toBe("none");
+	});
+
+	it("returns the same shared instance each call", () => {
+		expect(nobody()).toBe(nobody());
+	});
+
+	it("accepts pkcs8 decoding without throwing", () => {
+		expect(() => nobody().decodePkcs8("pass", new Uint8Array(1))).not.toThrow();
+	});
+});
+
+describe("pair defaults", () => {
+	it("declares the sr25519 key and seed lengths", () => {
+		expect(PUB_LENGTH).toBe(32);
+		expect(SEED_LENGTH).toBe(32);
+		expect(SALT_LENGTH).toBe(32);
+		expect(SEC_LENGTH).toBe(64);
+	});
+
+	it("declares the pkcs8 header and divider used by the encoder", () => {
+		// These framing bytes are what makes an exported key readable by
+		// polkadot-js; a change here silently breaks every existing backup.
+		expect(Array.from(PAIR_DIV)).toEqual([161, 35, 3, 33, 0]);
+		expect(Array.from(PAIR_HDR)).toEqual([
+			48, 83, 2, 1, 1, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32,
+		]);
+	});
+});

package/src/pair/toJson.spec.ts

@@ -24,17 +24,23 @@ describe("toJson", (): void => {
 		});
 	});
 
-	it("creates an encoded output with passphrase", (): void => {
-		const json = keyring.alice.toJson("testing");
+	// scrypt with the production parameters takes several seconds, which
+	// overruns the 10s default on a loaded CI runner.
+	it(
+		"creates an encoded output with passphrase",
+		{ timeout: 60000 },
+		(): void => {
+			const json = keyring.alice.toJson("testing");
 
-		expect(json.encoded).toHaveLength(268);
-		expect(json).toMatchObject({
-			address: "5Engs9f8Gk6JqvVWz3kFyJ8Kqkgx7pLi8C1UTcr7EZ855qBQ",
-			encoding: {
-				content: ["pkcs8", "sr25519"],
-				type: ["scrypt", "xsalsa20-poly1305"],
-				version: "3",
-			},
-		});
-	});
+			expect(json.encoded).toHaveLength(268);
+			expect(json).toMatchObject({
+				address: "5Engs9f8Gk6JqvVWz3kFyJ8Kqkgx7pLi8C1UTcr7EZ855qBQ",
+				encoding: {
+					content: ["pkcs8", "sr25519"],
+					type: ["scrypt", "xsalsa20-poly1305"],
+					version: "3",
+				},
+			});
+		},
+	);
 });