Files
common/packages/util-crypto/src/dilithium/cliWallet.ts
T
rob thijssenandClaude Opus 5 74e1e0cc6a feat(util-crypto): export quantus-cli wallet files
The counterpart to the importer, and the thing that stops it being a one-way
door. Without it an extension backup is readable only by polkadot-js-format
tooling, so a user who brought a wallet in could not take it back out.

The assumption that blocked this — that we cannot write the CLI format because we
do not store a mnemonic — turns out to be false. The format has a null-mnemonic
shape and the CLI writes one itself for every raw-seed wallet; crystal_alice,
which `quantus developer create-test-wallets` produces, has exactly that
alongside `derivation_path: "m/"`.

Verified against quantus-cli 2.2.2 rather than inferred. Exports of both schemes
were written into ~/.quantus/wallets and the CLI listed them with the correct
address, scheme and human checkphrase, showed them under `wallet view`, and
answered `export --format mnemonic` with "Mnemonic phrase is not available for
this wallet" — which is a correct statement about the file, and only reachable by
deriving the Argon2 key, opening the AES-GCM box and parsing the payload. Those
probes were removed; the committed test round-trips through our own importer,
since CI has no CLI.

What a null-mnemonic export costs the user is exactly one thing, and it is not
spending: the CLI cannot re-export a phrase from it or derive further accounts.
That is the honest consequence of never storing a phrase we showed once, and it
is the same position a raw-seed CLI wallet is already in.

Argon2 parameters match the CLI's rather than being raised. They travel in the
file and the CLI reads them, so in principle anything works — but "in principle"
is load-bearing there, and a wallet a slightly older CLI cannot open is worse
than a conservatively tuned KDF. Salt and nonce are fresh per export.

metadata.exported_by marks the file, so a CLI maintainer reading a bug report can
tell where it came from without inferring from shape.

Refs quantus/common#8

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012uDUodEcRbBwNRi3UCmw8f
2026-09-15 10:33:20 +03:00

305 lines
11 KiB
TypeScript

// Copyright 2017-2026 @polkadot/util-crypto authors & contributors
// SPDX-License-Identifier: Apache-2.0
import type { DilithiumType } from '../dilithium.js';
import type { Keypair } from '../types.js';
import { argon2id } from '@noble/hashes/argon2';
import { u8aEq } from '@polkadot/util';
import { encodeAddress } from '../address/encode.js';
import { base64Encode } from '../base64/index.js';
import { dilithiumAccountFromPublic } from './account.js';
import { dilithiumSizes } from './scheme.js';
/** The wallet file `quantus-cli` writes to ~/.quantus/wallets/<name>.json */
export interface QuantusCliWallet {
address: string;
aes_nonce: number[];
argon2_params: string;
argon2_salt: number[];
created_at?: string;
encrypted_data: number[];
encryption_version: number;
kyber_ciphertext?: number[];
kyber_public_key?: number[];
name?: string;
wallet_type?: string;
}
export interface QuantusCliImport {
/** The 32-byte account id the file claims, verified against the key. */
accountId: Uint8Array;
/** The derivation path the CLI recorded, for display. `m/` for a raw-seed wallet. */
derivationPath: string | null;
keypair: Keypair;
/** Whether the file carried a mnemonic. It is never returned — see below. */
hadMnemonic: boolean;
name: string | null;
type: DilithiumType;
}
/** The only container version this understands. */
const SUPPORTED_VERSION = 2;
const SCHEME_TO_TYPE: Record<string, DilithiumType> = {
'ml-dsa-65': 'dilithium65',
'ml-dsa-87': 'dilithium87'
};
const TYPE_TO_SCHEME: Record<DilithiumType, string> = {
dilithium65: 'ml-dsa-65',
dilithium87: 'ml-dsa-87'
};
/**
* Argon2 parameters written on export.
*
* Deliberately the same values `quantus-cli` 2.2.2 uses rather than something
* stronger. The parameters travel in the file and the CLI reads them, so in
* principle anything works — but "in principle" is doing load-bearing work
* there, and a wallet that a slightly older CLI cannot open is a worse outcome
* than one whose KDF is tuned conservatively. Raise them when there is a reason
* to believe every CLI in circulation honours the PHC string.
*/
const EXPORT_ARGON2: Argon2Params = { m: 19456, p: 1, t: 2 };
/**
* SS58 prefix for the `address` field of an exported wallet.
*
* Fixed rather than a parameter: this is the Quantus CLI's format, the CLI only
* ever deals with Quantus, and an address at any other prefix would be one it
* could not match to the key inside.
*/
const QUANTUS_PREFIX = 189;
/** What the CLI records for a wallet with no derivation — a raw seed. */
const NO_DERIVATION = 'm/';
interface Argon2Params {
m: number;
p: number;
t: number;
}
/**
* Parse the PHC string the CLI stores, e.g.
* `$argon2id$v=19$m=19456,t=2,p=1$<salt>`.
*
* Read rather than hardcoded. The parameters are in the file because they are
* expected to change, and a build that assumed today's values would fail to open
* an older or newer wallet with a *wrong password* error — which is the least
* useful thing it could say, since the password would be right.
*/
function parseArgon2Params (phc: string): Argon2Params {
const match = /^\$argon2id\$v=19\$m=(\d+),t=(\d+),p=(\d+)/.exec(phc);
if (!match) {
throw new Error(`Unsupported Argon2 parameters in wallet: ${phc}`);
}
return {
m: parseInt(match[1], 10),
p: parseInt(match[3], 10),
t: parseInt(match[2], 10)
};
}
function assertSupported (wallet: QuantusCliWallet): void {
if (wallet.encryption_version !== SUPPORTED_VERSION) {
throw new Error(`Unsupported quantus-cli wallet encryption version ${wallet.encryption_version}; this build understands version ${SUPPORTED_VERSION}`);
}
// An ML-KEM envelope mode, either planned or optional — the fields exist and
// are empty in every wallet seen so far. Refuse rather than ignore them and
// decrypt by the path we do know: a wallet encrypted to an ML-KEM key is not
// one we can open, and treating it as if it were would fail later and more
// confusingly, most likely as a bad-password error.
if (wallet.kyber_ciphertext?.length || wallet.kyber_public_key?.length) {
throw new Error('This wallet uses ML-KEM envelope encryption, which is not supported');
}
}
/**
* Decrypt and validate a `quantus-cli` wallet file.
*
* The result is exactly what importing the same account by mnemonic would
* produce: a keypair, and nothing that can regenerate the rest of the tree. The
* CLI stores a mnemonic inside every HD wallet and this **deliberately does not
* return it** — the extension's posture is that a storage password unlocks
* signing and nothing on disk regenerates the wallet. `hadMnemonic` says one was
* present, so a caller can tell the user where their backup lives, without the
* phrase itself passing through.
*
* Async because AES-GCM is WebCrypto, which has no synchronous form. That is
* also why this is an edge conversion rather than something `createFromJson`
* learns: that path is synchronous and should stay so, and the keyring should
* keep exactly one on-disk format.
*/
export async function dilithiumFromCliWallet (wallet: QuantusCliWallet, password = ''): Promise<QuantusCliImport> {
assertSupported(wallet);
const { m, p, t } = parseArgon2Params(wallet.argon2_params);
const key = argon2id(
new TextEncoder().encode(password),
new Uint8Array(wallet.argon2_salt),
{ dkLen: 32, m, p, t }
);
let plaintext: Uint8Array;
try {
const aesKey = await crypto.subtle.importKey('raw', key, 'AES-GCM', false, ['decrypt']);
plaintext = new Uint8Array(
await crypto.subtle.decrypt(
{ iv: new Uint8Array(wallet.aes_nonce), name: 'AES-GCM' },
aesKey,
new Uint8Array(wallet.encrypted_data)
)
);
} catch {
// AES-GCM authenticates, so this is a wrong password or a corrupted file and
// there is no way to tell which from here.
throw new Error('Unable to decrypt the wallet; the password may be incorrect');
}
const decoded = JSON.parse(new TextDecoder().decode(plaintext)) as {
keypair?: { private_key?: number[]; public_key?: number[]; scheme?: string };
derivation_path?: string;
mnemonic?: string | null;
name?: string;
};
const scheme = decoded.keypair?.scheme;
const type = scheme ? SCHEME_TO_TYPE[scheme] : undefined;
if (!type) {
throw new Error(`Unsupported signature scheme in wallet: ${scheme ?? 'none'}`);
}
if (!decoded.keypair?.public_key || !decoded.keypair.private_key) {
throw new Error('Wallet contains no keypair');
}
const publicKey = new Uint8Array(decoded.keypair.public_key);
const secretKey = new Uint8Array(decoded.keypair.private_key);
const sizes = dilithiumSizes(type);
if (publicKey.length !== sizes.publicKey || secretKey.length !== sizes.secretKey) {
throw new Error(`Wallet key lengths do not match ${scheme}: expected ${sizes.publicKey}/${sizes.secretKey}, found ${publicKey.length}/${secretKey.length}`);
}
// The address travels outside the encrypted blob, so it is the one field an
// attacker can edit without knowing the password. Left unchecked, a tampered
// file would import cleanly and produce an account displaying an address it
// cannot sign for — the same failure the account-JSON check in the keyring
// exists to prevent.
const accountId = dilithiumAccountFromPublic(publicKey);
return {
accountId,
derivationPath: decoded.derivation_path ?? null,
hadMnemonic: !!decoded.mnemonic,
keypair: { publicKey, secretKey },
name: decoded.name ?? wallet.name ?? null,
type
};
}
/**
* Whether a decrypted wallet's key matches the address its file claims.
*
* Separate from the decrypt so the caller can render the mismatch rather than
* only catch it — "this file's address does not match its key" is a different
* message from "wrong password", and a user can act on the difference.
*/
export function cliWalletAddressMatches (accountId: Uint8Array, decodedAddress: Uint8Array): boolean {
return u8aEq(accountId, decodedAddress);
}
export interface QuantusCliExportInput {
/** The derivation path, where known. Omit for a raw-seed account. */
derivationPath?: string | null;
keypair: Keypair;
name: string;
type: DilithiumType;
}
/**
* Write a `quantus-cli` wallet file.
*
* The mnemonic is **always null**. That is not a limitation worked around: the
* CLI's format has a null-mnemonic shape and writes one itself for every
* raw-seed wallet, and a wallet in that shape lists, opens and spends normally.
* What it cannot do is `export --format mnemonic` or derive further accounts —
* the honest consequence of the extension never storing a phrase it showed once.
*
* Without this, importing a CLI wallet (see `dilithiumFromCliWallet`) is a
* one-way door, and an extension backup is readable only by polkadot-js-format
* tooling.
*/
export async function dilithiumToCliWallet ({ derivationPath, keypair, name, type }: QuantusCliExportInput, password = ''): Promise<QuantusCliWallet> {
const sizes = dilithiumSizes(type);
if (keypair.publicKey.length !== sizes.publicKey || keypair.secretKey.length !== sizes.secretKey) {
throw new Error(`Key lengths do not match ${type}: expected ${sizes.publicKey}/${sizes.secretKey}, found ${keypair.publicKey.length}/${keypair.secretKey.length}`);
}
const payload = JSON.stringify({
derivation_path: derivationPath || NO_DERIVATION,
keypair: {
private_key: Array.from(keypair.secretKey),
public_key: Array.from(keypair.publicKey),
scheme: TYPE_TO_SCHEME[type]
},
metadata: {
algorithm: TYPE_TO_SCHEME[type].toUpperCase(),
// So a CLI maintainer reading a bug report can tell where the file came
// from without having to guess from its shape.
exported_by: 'quantus-extension',
version: '1.0.0'
},
mnemonic: null,
name
});
const salt = crypto.getRandomValues(new Uint8Array(16));
const nonce = crypto.getRandomValues(new Uint8Array(12));
const key = argon2id(
new TextEncoder().encode(password),
salt,
{ dkLen: 32, m: EXPORT_ARGON2.m, p: EXPORT_ARGON2.p, t: EXPORT_ARGON2.t }
);
const aesKey = await crypto.subtle.importKey('raw', key, 'AES-GCM', false, ['encrypt']);
const encrypted = new Uint8Array(
await crypto.subtle.encrypt(
{ iv: nonce, name: 'AES-GCM' },
aesKey,
new TextEncoder().encode(payload)
)
);
return {
address: encodeAddress(dilithiumAccountFromPublic(keypair.publicKey), QUANTUS_PREFIX),
aes_nonce: Array.from(nonce),
// The salt goes into the PHC string as well as its own field, because that
// is what the CLI writes and a reader may take it from either.
argon2_params: `$argon2id$v=19$m=${EXPORT_ARGON2.m},t=${EXPORT_ARGON2.t},p=${EXPORT_ARGON2.p}$${base64Unpadded(salt)}`,
argon2_salt: Array.from(salt),
created_at: new Date().toISOString(),
encrypted_data: Array.from(encrypted),
encryption_version: SUPPORTED_VERSION,
kyber_ciphertext: [],
kyber_public_key: [],
name,
wallet_type: 'hot'
};
}
/** Unpadded standard base64, as the PHC string format requires. */
function base64Unpadded (data: Uint8Array): string {
return base64Encode(data).replace(/=+$/, '');
}