@prosopo/keyring 2.9.61 → 2.9.63

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",
+				},
+			});
+		},
+	);
 });