diff --git a/.gitattributes b/.gitattributes index 2f77e91..153a12e 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,6 @@ *.ipynb linguist-documentation + +# Checked byte for byte against the same files in the TypeScript SDK, so they +# keep LF line endings on every platform. +sdk/python/tests/fixtures/keystore-vectors/*.json text eol=lf +sdk/python/aleo/keystore/_bip39_english.txt text eol=lf diff --git a/sdk/Readme.md b/sdk/Readme.md index bce957a..cf0bc77 100644 --- a/sdk/Readme.md +++ b/sdk/Readme.md @@ -58,6 +58,13 @@ account = aleo.account.from_private_key("APrivateKey1zkp…") # Derive deterministically from a field seed account = aleo.account.from_seed("123field") +# Recover a wallet account from its recovery phrase (offline; nothing is stored) +account = aleo.account.from_mnemonic(phrase) # first account of the phrase +second = aleo.account.from_mnemonic(phrase, index=1) # the next one + +# Create a new account a wallet can import later (offline; nothing is stored) +phrase, account = aleo.account.create_with_mnemonic() # show `phrase` to the user once + # Sign / verify (bytes) sig = aleo.account.sign(b"hello aleo", account) assert aleo.account.verify(str(account.address), b"hello aleo", sig) @@ -67,10 +74,114 @@ sv = aleo.account.sign_value("100u64", account) assert aleo.account.verify_value(str(account.address), "100u64", sv) ``` +`create_with_mnemonic` makes a new 12-word phrase (24 with `strength=256`) and returns it with its first account; `generate_mnemonic` returns only the phrase. The phrase controls every account derived from it and is not stored anywhere, so give it to the person who will keep it and do not log it. `create` makes an account from a random key instead, which no phrase can recover. `from_mnemonic` takes a BIP-39 English phrase of 12 to 24 lower-case words separated by single spaces and uses the derivation of the Shield wallet and the other Aleo SDKs, so one phrase gives the same accounts everywhere. A mistyped word raises `aleo.keystore.KeystoreError` with `code == "INVALID_MNEMONIC"` instead of deriving a different account. Pass `derivation="legacy"` only to recover an account from a wallet that used the path `m/44'/0'` before Aleo's own path `m/44'/683'` was registered. + Set `aleo.default_account = account` and the verbs below will use it whenever you omit the signer. > **Note:** the facade deliberately has no "recover signer from signature" verb. Aleo is a privacy chain — surfacing "which address signed this?" is a de-anonymisation vector. The low-level `Signature.to_address()` primitive remains available directly if you truly need it. +### Store an account — `aleo.keystore` + +The functions above keep a key in memory. `aleo.keystore` stores an account on disk and finds it again on later runs, in an account file whose format is shared with the other Aleo SDKs, so an account set up once can serve every tool that reads it. The file is network-neutral: one account works on testnet and mainnet, and named accounts keep separate keys apart. Nothing here contacts a network, and nothing is written until `save`, `protect` or `migrate` is called. + +```python +from aleo import Aleo, HTTPProvider, keystore + +aleo = Aleo(HTTPProvider("https://edge.provable.com/api", network="testnet")) + +# First run: create an account and store it under a name. +stored = keystore.save(aleo.account.create(), name="testnet") +print(stored.address, stored.storage, stored.path) # never the key + +# Later runs: resolve the key and hand it to the client. +loaded = keystore.load(name="testnet") +account = aleo.account.from_private_key(loaded.private_key) +``` + +The account file is `~/.aleo/accounts/.json`, readable by its owner only. The name defaults to `default`; `ALEO_ACCOUNT` or the `name` argument selects another. `ALEO_ACCOUNTS_DIR` or the `dir` argument moves the directory, for example into a project or a test directory. + +#### Choose how the key is stored + +`save` takes a `storage` argument. Encryption and the Keychain protect a key at rest: a copied file, a backup, a synced folder. They do not stop a process running as the same user from reading it. + +| `storage` | Where the key is | Choose it when | +| --- | --- | --- | +| `"plaintext"` (default) | In the account file, mode 0600 | The machine and its backups are trusted; no password is ever needed | +| `"keychain"` | In the macOS login keychain, under `aleo-account-key`. Each account file has an entry of its own, named after the address and an identifier the file records, and labelled `aleo-account-key:`; the file holds no secret | Working on a Mac, and the file may be copied or backed up. The key has no other copy, so export it once as a backup | +| `"encrypted"` | In the account file, encrypted under a password | Any system where the file may leak. Each run needs the password | +| `"none"` | Nowhere; the file records the address | The key arrives through the environment on every run and the file only confirms it is the expected account | + +An encrypted account takes its password from the `password` argument, then `ALEO_ACCOUNT_PASSWORD`, then the macOS Keychain when `save_password=True` put it there, then a hidden terminal prompt. A saved password belongs to one encrypted file: its Keychain entry is named after the address and the file's salt, so two files that hold one account under different passwords do not share it. An unattended job cannot answer a prompt, so it relies on the variable or the saved password; pass `prompt=False` to fail at once instead of waiting. A wrong password from any source but the prompt is an error and the later sources are not tried. + +```python +keystore.save(account, name="mainnet", storage="encrypted", save_password=True) # asks for a password twice +keystore.protect(name="testnet", storage="keychain") # move an existing account; the old copy is removed after a check +print(keystore.info(name="testnet")) # name, path, address, storage; None when there is no file +key = keystore.export(name="testnet") # the private key itself: do not log it +``` + +#### How `load` finds the key + +Every tool that uses the keystore resolves the key in the same order, and the first source that supplies one wins: + +1. The `private_key` argument. +2. `ALEO_PRIVATE_KEY`, then its alias `SHIELD_SWAP_PRIVATE_KEY`. +3. The text file named by `ALEO_PRIVATE_KEY_FILE`, then its alias `SHIELD_SWAP_PRIVATE_KEY_FILE`. +4. The selected account file. +5. The `legacy_key` argument, which a tool passes when its own older state file still holds a key. + +A key from the environment is used for that process and never written to disk. A variable that is set but empty is an error, as are two variables that hold different keys, and when the account file exists a key from sources 1 to 3 must belong to the address it records. `load` never generates a key: with no source it raises `ACCOUNT_NOT_FOUND`. `loaded.source` names the source used (`"argument"`, `"env"`, `"env-file"`, `"account-file"` or `"legacy"`). + +`keystore.migrate(path)` copies the key out of a `profile.json` or `state.json` that keeps it in a top-level `private_key` or `privateKey` field. The old file keeps its plaintext copy unless `remove_legacy_key=True` is passed, which strips the field after the new account has been read back. + +#### Handle failures + +Every failure the keystore detects is an `aleo.keystore.KeystoreError` (a subclass of `aleo.AleoError`) with a stable `code`. Messages name addresses and paths, never a key or a password. + +```python +from aleo.keystore import KeystoreError + +try: + loaded = keystore.load() +except KeystoreError as error: + if error.code == "ACCOUNT_NOT_FOUND": + ... # no key in the environment and no account file: create or import one + elif error.code == "PASSWORD_REQUIRED": + ... # encrypted account and no password source + else: + raise +``` + +The codes are `ACCOUNT_NOT_FOUND`, `KEY_NOT_STORED`, `ACCOUNT_EXISTS`, `ACCOUNT_BUSY`, `ADDRESS_MISMATCH`, `KEY_CONFLICT`, `EMPTY_KEY_SOURCE`, `INVALID_KEY`, `INVALID_MNEMONIC`, `INVALID_NAME`, `INVALID_ACCOUNT_FILE`, `UNSUPPORTED_VERSION`, `UNSUPPORTED_STORAGE`, `KEYCHAIN_UNAVAILABLE`, `KEYCHAIN_ITEM_NOT_FOUND`, `KEYCHAIN_FAILED`, `PASSWORD_REQUIRED`, `WRONG_PASSWORD`, `TERMINAL_REQUIRED` and `LEGACY_KEY_NOT_FOUND`; the `KeystoreError` docstring says when each is raised. A file system failure on the account file other than a missing file (permission denied, a directory in its place) is raised as `OSError`. + +#### Set up an account from a terminal + +`python -m aleo.keystore ` runs the same operations without writing code. Passwords are never taken from the command line: they come from `ALEO_ACCOUNT_PASSWORD`, the Keychain or a hidden prompt. + +| Command | Does | +| --- | --- | +| `create` | Generates a key and stores it (`--storage plaintext` unless stated). With `--mnemonic` the key comes from a new recovery phrase, printed once and stored nowhere, so a wallet can import the account later; this needs a terminal | +| `import` | Stores an existing key from `--key-file`, the key variables or a hidden prompt, or the account of a recovery phrase from `--mnemonic-file` or the prompt (`--index`, `--derivation`). The derived key is stored, not the phrase | +| `show` | Prints the address, account name and storage type. Never the key | +| `protect` | Changes the storage with `--storage`; `--save-password` saves the password in the Keychain and `--forget-password` removes a saved one | +| `export` | Prints the key after a confirmation. Requires a terminal | +| `migrate` | Copies a key from `--from `; `--remove-legacy-key` strips it from the old file | + +```sh +python -m aleo.keystore create --name testnet +python -m aleo.keystore import --key-file ./account.key --storage encrypted --save-password +python -m aleo.keystore show --json +``` + +Every command accepts `--name`, `--dir` and `--json`. With `--json` a result is one object with `name`, `address`, `storage` and `path`, and an error is `{"error": {"code": "…", "message": "…"}}` on standard output; without it, errors go to standard error as `: `. `export` and `create --storage none` show a key, so they run only with a terminal attached and never with `--json`: an agent or a script must not run them. + +| Exit status | Meaning | +| --- | --- | +| 0 | Done | +| 1 | Failed | +| 2 | Needs a person: `ACCOUNT_NOT_FOUND`, `KEY_NOT_STORED`, `PASSWORD_REQUIRED` or `TERMINAL_REQUIRED` | +| 64 | Usage error | + ### 3. Read — balance and mappings ```python diff --git a/sdk/python/aleo/__init__.py b/sdk/python/aleo/__init__.py index 92021f4..ac9504b 100644 --- a/sdk/python/aleo/__init__.py +++ b/sdk/python/aleo/__init__.py @@ -68,6 +68,7 @@ SqliteRecordInventoryStore as SqliteRecordInventoryStore, TokenJoinRouter as TokenJoinRouter, ) +from . import keystore as keystore def __getattr__(name: str) -> object: diff --git a/sdk/python/aleo/__init__.pyi b/sdk/python/aleo/__init__.pyi index f62ee40..f74c286 100644 --- a/sdk/python/aleo/__init__.pyi +++ b/sdk/python/aleo/__init__.pyi @@ -49,6 +49,7 @@ from .inventory import ( SqliteRecordInventoryStore as SqliteRecordInventoryStore, TokenJoinRouter as TokenJoinRouter, ) +from . import keystore as keystore def consensus_version(block_height: Optional[int] = None) -> int: ... diff --git a/sdk/python/aleo/facade/account.py b/sdk/python/aleo/facade/account.py index 66a9dba..8e36eea 100644 --- a/sdk/python/aleo/facade/account.py +++ b/sdk/python/aleo/facade/account.py @@ -15,6 +15,8 @@ from typing import TYPE_CHECKING, Any +from ..keystore._mnemonic import derive_seed, generate_phrase + if TYPE_CHECKING: # Import only for type annotations; resolved at runtime via _net(). pass @@ -131,6 +133,151 @@ def from_seed(self, seed: str | Any) -> Any: pk: Any = net.PrivateKey.from_seed(field) return net.Account.from_private_key(pk) + def from_mnemonic( + self, + mnemonic: str, + *, + index: int = 0, + derivation: str = "standard", + ) -> Any: + """Derive an :class:`Account` from a recovery phrase. + + Recovers an account created by a wallet from its BIP-39 phrase, using + the derivation the Shield wallet and the other Aleo SDKs use, so the + same phrase gives the same account everywhere. One phrase holds many + accounts; *index* selects among them. + + The phrase is checked first, so a mistyped word is reported instead of + silently producing a different account. Works offline and stores + nothing: the caller keeps the phrase, which is the only way to derive + the account again. Does not change ``aleo.default_account``. + + Parameters + ---------- + mnemonic: + A BIP-39 English phrase of 12, 15, 18, 21 or 24 lower-case words + separated by single spaces. + index: + Which account of the phrase to derive, from 0 through + ``2**31 - 1``. Defaults to 0, the first account a wallet shows. + derivation: + ``"standard"`` (the default) follows the registered Aleo path + ``m/44'/683'/'/0'``. ``"legacy"`` follows + ``m/44'/0'/'/0'``; choose it only to recover an account + from a wallet that predates the registration. + + Returns + ------- + Account + The account at *index* of the phrase. + + Raises + ------ + aleo.keystore.KeystoreError + With ``code == "INVALID_MNEMONIC"`` when a word is not in the + BIP-39 English word list, the word count is wrong, or the checksum + does not match. The message never repeats a word of the phrase. + ValueError + If *index* or *derivation* is outside the accepted values. + + Example + ------- + :: + + first = aleo.account.from_mnemonic(phrase) + second = aleo.account.from_mnemonic(phrase, index=1) + """ + net = self._net() + seed = derive_seed(mnemonic, index=index, derivation=derivation) + pk: Any = net.PrivateKey.from_seed_unchecked(list(seed)) + return net.Account.from_private_key(pk) + + def generate_mnemonic(self, strength: int = 128) -> str: + """Create a new recovery phrase. + + Draws the randomness from the operating system and encodes it as a + BIP-39 English phrase. Works offline and stores nothing. + + The phrase is the root secret of every account derived from it: whoever + holds it controls them all. Show it to the person who will keep it and + nowhere else: do not log it, write it to a file left on disk, or send + it to a service. + + Parameters + ---------- + strength: + Bits of randomness: 128 (the default) gives 12 words, 256 gives 24. + + Returns + ------- + str + The phrase, as lower-case words separated by single spaces. Pass it + to :meth:`from_mnemonic` to derive its accounts. + + Raises + ------ + ValueError + If *strength* is neither 128 nor 256. + + Example + ------- + :: + + phrase = aleo.account.generate_mnemonic() + account = aleo.account.from_mnemonic(phrase) + """ + return generate_phrase(strength) + + def create_with_mnemonic( + self, + *, + strength: int = 128, + index: int = 0, + derivation: str = "standard", + ) -> "tuple[str, Any]": + """Create a new recovery phrase and derive its account in one call. + + Use this for a new account that a wallet must be able to import later: + the wallet derives the same account from the phrase. :meth:`create` + makes an account from a random key instead, which has no phrase. + + Works offline and stores nothing. The caller must give the phrase to + the person who will keep it; it is the only way to derive the account + again, and it controls every account of the phrase. Does not change + ``aleo.default_account``. + + Parameters + ---------- + strength: + Bits of randomness: 128 (the default) gives 12 words, 256 gives 24. + index: + Which account of the phrase to derive, from 0 through + ``2**31 - 1``. Defaults to 0, the first account a wallet shows. + derivation: + ``"standard"`` (the default) or ``"legacy"``, as in + :meth:`from_mnemonic`. + + Returns + ------- + tuple[str, Account] + The new phrase and the account derived from it. + + Raises + ------ + ValueError + If *strength*, *index* or *derivation* is outside the accepted + values. + + Example + ------- + :: + + phrase, account = aleo.account.create_with_mnemonic() + # show `phrase` to the user once; `account.address` is ready to use + """ + phrase = generate_phrase(strength) + return phrase, self.from_mnemonic(phrase, index=index, derivation=derivation) + # ── Encryption ───────────────────────────────────────────────────────── def export_encrypted(self, account: Any, secret: str) -> Any: diff --git a/sdk/python/aleo/keystore/__init__.py b/sdk/python/aleo/keystore/__init__.py new file mode 100644 index 0000000..b66a1a3 --- /dev/null +++ b/sdk/python/aleo/keystore/__init__.py @@ -0,0 +1,1112 @@ +"""Store an Aleo account on disk and find it again on later runs. + +An account file records an address and, depending on the storage chosen, the +private key itself, a pointer to it in the macOS Keychain, or the key +encrypted under a password. :func:`load` then resolves the signing key the +same way in every tool: a key passed by the caller, the ``ALEO_PRIVATE_KEY`` +or ``ALEO_PRIVATE_KEY_FILE`` variables, and finally the account file. + +Creating a key and storing it are separate steps. Make or import an account +with ``aleo.account.create()``, ``from_private_key()`` or ``from_mnemonic()`` +on a client, then pass it to :func:`save`. Nothing here contacts a network, +and nothing is written unless :func:`save`, :func:`protect` or +:func:`migrate` is called. + +The file is network-neutral: one account serves testnet and mainnet, and the +functions take and return keys and addresses as strings. Named accounts keep +separate keys apart for callers who want that. + +Choose the storage by what must be protected: + +- ``"plaintext"`` (the default) keeps the key in a file only its owner can + read. Anything running as the same user can read it, and so can a backup or + a synced folder. +- ``"keychain"`` keeps the key in the macOS login keychain, so a copied or + backed-up account file holds nothing secret. macOS only. +- ``"encrypted"`` encrypts the key under a password, on every system. Each + load needs the password from ``ALEO_ACCOUNT_PASSWORD``, from the macOS + Keychain when it was saved there, or from a hidden terminal prompt. +- ``"none"`` records the address only. The key is supplied through the + environment on every run, and the file confirms it is the expected account. + +Keychain and encrypted storage protect a key at rest. They do not stop a +process running as the same user from reading it. + +Example:: + + from aleo import Aleo, HTTPProvider, keystore + + aleo = Aleo(HTTPProvider("https://api.provable.com/v2", network="testnet")) + + # First run: create an account and store it. + stored = keystore.save(aleo.account.create(), name="testnet") + + # Later runs: resolve the key and hand it to the client. + loaded = keystore.load(name="testnet") + account = aleo.account.from_private_key(loaded.private_key) + +The same operations are available from a terminal through +``python -m aleo.keystore``. +""" +from __future__ import annotations + +import json +import os +import re +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, Callable, Dict, List, Literal, NamedTuple, Optional, Sequence, Tuple, Union, cast + +from ._encrypted import EncryptedKey, encrypt_key, parse_key +from ._errors import KeystoreError +from ._file import ( + STORAGE_TYPES, + AccountFile, + Location, + account_lock, + loads_strict, + read_account_file, + resolve_location, + write_account_file, + write_file_atomic, +) +from ._keychain import ( + KEY_SERVICE, + PASSWORD_SERVICE, + delete_keychain, + keychain_available, + new_key_entry_account, + read_keychain, + require_keychain, + write_keychain, +) +from ._password import ( + PasswordSubject, + choose_new_password, + password_entry_account, + password_to_keychain_value, + saved_password_entry, + unlock, +) +from ._sources import ( + KEY_FILE_VARIABLES, + KEY_VARIABLES, + PathLike, + Resolved, + error_code, + key_from_environment, +) + +Storage = Literal["none", "plaintext", "keychain", "encrypted"] +"""How an account file holds the private key; see the module description.""" + +# Top-level fields a legacy state file may keep its key in, in order of +# precedence. +_LEGACY_KEY_FIELDS = ("privateKey", "private_key") + +_LONE_SURROGATE = re.compile("[\ud800-\udfff]") + + +@dataclass(frozen=True) +class StoredAccount: + """Describe an account file without its key. + + Safe to print or log: it never holds the private key or a password. + + Attributes: + name: Account name. Pass it as ``name`` to select the same account + again. + path: Absolute path of the account file. + address: Aleo address recorded in the file. + storage: How the file holds the private key: ``"none"``, + ``"plaintext"``, ``"keychain"`` or ``"encrypted"``. + """ + + name: str + path: Path + address: str + storage: Storage + + +@dataclass(frozen=True) +class LoadedAccount: + """The account resolved by :func:`load`. + + Pass ``private_key`` to ``aleo.account.from_private_key()`` on a client to + get an account object for signing. The key is left out of ``repr()`` so a + logged result does not leak it. + + Attributes: + address: Aleo address the key derives. + private_key: The private key (``APrivateKey1...``). Keep it out of + logs and files. + source: Where the key came from: ``"argument"`` (the ``private_key`` + argument), ``"env"`` (``ALEO_PRIVATE_KEY`` or its alias), + ``"env-file"`` (the file named by ``ALEO_PRIVATE_KEY_FILE`` or its + alias), ``"account-file"`` (the selected account file) or + ``"legacy"`` (the ``legacy_key`` argument). A caller that passed + ``legacy_key`` reports the pending migration when this is + ``"legacy"``. + stored: The selected account file when one exists, even when the key + itself came from the environment; otherwise ``None``. + """ + + address: str + private_key: str = field(repr=False) + source: str + stored: Optional[StoredAccount] = None + + +class _Key(NamedTuple): + """A parsed private key and the address it derives.""" + + private_key: str + address: str + + +class _Legacy(NamedTuple): + """A legacy state file, the fields that hold its key, and the parsed key.""" + + text: str + content: Dict[str, Any] + fields: Tuple[str, ...] + account: "_Key" + + +def _describe(location: Location, file: AccountFile) -> StoredAccount: + """Build the public description of an account file.""" + return StoredAccount( + name=location.name, + path=Path(location.path), + address=file["address"], + storage=cast(Storage, file["key"]["type"]), + ) + + +def _assert_storage(storage: object, allowed: Sequence[str]) -> None: + """Check a storage value supplied at run time. + + Raises: + KeystoreError: ``UNSUPPORTED_STORAGE`` for a value outside *allowed*. + """ + if not isinstance(storage, str) or storage not in allowed: + raise KeystoreError( + "UNSUPPORTED_STORAGE", + f'Unsupported storage type "{storage}"; expected one of {", ".join(allowed)}.', + ) + + +def _mismatch(origin: str, actual: str, requirement: str, expected: str) -> KeystoreError: + """Build the error for a key that derives a different address than required.""" + return KeystoreError("ADDRESS_MISMATCH", f"{origin} derives {actual}, but {requirement} {expected}.") + + +def _account_key(account: object) -> Tuple[object, Optional[str]]: + """Take the key, and the address when one is stated, from a ``save`` argument. + + Accepts a key string, a private-key object (its text form is the key) or + an object with a ``private_key`` attribute, such as an account of either + network or a :class:`LoadedAccount`. + """ + if isinstance(account, str): + return account, None + holder: Any = getattr(account, "private_key", None) + if holder is None: + # A private-key object of either network. + return _text_of(account), None + stated: Any = getattr(account, "address", None) + key: object = holder if isinstance(holder, str) else _text_of(holder) + return key, None if stated is None else _text_of(stated) + + +def _text_of(value: object) -> Optional[str]: + """Return the text form of a key or address object, or ``None`` when it has none.""" + try: + return str(value) + except Exception: + return None + + +def _read_stored_key( + file: AccountFile, + location: Location, + password: Union[str, bytes, None], + prompt: bool, +) -> Tuple[str, Optional[bytes]]: + """Read the private key an account file holds or points at. + + Does not consult the key variables. May run the ``security`` tool, stretch + a password and prompt on the terminal, depending on the storage type. + + Returns: + The private key, and for an encrypted file the normalised password + that unlocked it. + + Raises: + KeystoreError: ``KEY_NOT_STORED``, ``INVALID_KEY``, + ``ADDRESS_MISMATCH``, ``KEYCHAIN_UNAVAILABLE``, + ``KEYCHAIN_ITEM_NOT_FOUND``, ``KEYCHAIN_FAILED``, + ``PASSWORD_REQUIRED`` or ``WRONG_PASSWORD``. + """ + key: Dict[str, Any] = file["key"] + address: str = file["address"] + kind: str = key["type"] + if kind == "none": + raise KeystoreError( + "KEY_NOT_STORED", + f"Account file {location.path} records the address {address} without a key; " + "the key of this account is supplied through ALEO_PRIVATE_KEY or ALEO_PRIVATE_KEY_FILE.", + ) + if kind == "plaintext": + origin = f"The key in account file {location.path}" + parsed = _Key(*parse_key(key["privateKey"], origin)) + if parsed.address != address: + raise _mismatch(origin, parsed.address, "the file records", address) + return parsed.private_key, None + if kind == "keychain": + require_keychain( + f"Account file {location.path} keeps its key in the Keychain of the Mac it was created on. " + "Export the key on that Mac and import it here." + ) + value = read_keychain(KEY_SERVICE, key["account"]) + if value is None: + raise KeystoreError( + "KEYCHAIN_ITEM_NOT_FOUND", + f"Account file {location.path} points at the Keychain entry {KEY_SERVICE} for {address}, " + "which does not exist.", + ) + origin = f"The Keychain entry {KEY_SERVICE} for {address}" + parsed = _Key(*parse_key(value, origin)) + if parsed.address != address: + raise _mismatch(origin, parsed.address, f"account file {location.path} records", address) + return parsed.private_key, None + private_key, used = unlock( + PasswordSubject(location.name, address), cast(EncryptedKey, key), password, prompt + ) + return private_key, used + + +class _KeychainEntry(NamedTuple): + """One Keychain entry: its service and its account within the service.""" + + service: str + account: str + + +def _remove_entries(entries: Sequence[_KeychainEntry]) -> None: + """Remove Keychain entries, ignoring failures; used when undoing a failed step.""" + for entry in entries: + try: + delete_keychain(entry.service, entry.account) + except KeystoreError: + pass + + +def _neighbour_uses(location: Location, matches: Callable[[Dict[str, Any]], bool]) -> bool: + """Report whether another account file in the same directory matches. + + Every account file has Keychain entries of its own, so two files share an + entry only when one is a copy of the other. Before an entry is removed, + the neighbouring files are checked so that an entry a copy still uses + stays. Files that cannot be read or parsed are skipped. A copy kept in + another directory is not seen. + + Args: + location: The account file being changed; it is not counted itself. + matches: Decides whether a parsed neighbouring file uses the entry. + """ + try: + names = os.listdir(location.dir) + except OSError: + return False + for name in names: + if not name.endswith(".json") or name == f"{location.name}.json": + continue + try: + with open(os.path.join(location.dir, name), "rb") as handle: + parsed = json.loads(handle.read().decode("utf-8")) + except (OSError, ValueError, RecursionError): + # Not an account file, or not readable: it holds no claim on the entry. + continue + if isinstance(parsed, dict) and matches(cast(Dict[str, Any], parsed)): + return True + return False + + +def _key_of(file: Dict[str, Any]) -> Dict[str, Any]: + """Read the ``key`` object of a loosely parsed account file.""" + key = file.get("key") + return cast(Dict[str, Any], key) if isinstance(key, dict) else {} + + +def _write_storage( + location: Location, + account: _Key, + storage: str, + password: Optional[bytes], + save_password: bool, + exclusive: bool = False, + created: Optional[List[_KeychainEntry]] = None, +) -> AccountFile: + """Write an account under the given storage. + + Secrets held outside the file (the Keychain key entry, a saved password) + are written first, so a failure there leaves no file pointing at a missing + entry. + + Args: + location: Resolved account location. + account: Parsed key and the address it derives. + storage: Storage type to write. + password: Normalised password bytes; required for ``"encrypted"``. + save_password: Whether to save the password in the macOS Keychain. + Applies to ``"encrypted"`` on macOS and is ignored otherwise. + exclusive: Whether the account file must not exist yet. By default + any file at the path is replaced. + created: Receives each Keychain entry this call creates, so a + caller can remove them when a later step fails. + + Returns: + The content written to the account file. + + Raises: + FileExistsError: *exclusive* is set and the account file already + exists. + """ + private_key, address = account + key: Dict[str, Any] + if storage == "none": + key = {"type": "none"} + elif storage == "plaintext": + key = {"type": "plaintext", "privateKey": private_key} + elif storage == "keychain": + # Each account file gets a Keychain entry of its own, so nothing done + # to this file's entry can affect another file that holds the same key. + entry = new_key_entry_account(address) + if write_keychain(KEY_SERVICE, entry, private_key, location.name) and created is not None: + created.append(_KeychainEntry(KEY_SERVICE, entry)) + key = {"type": "keychain", "service": KEY_SERVICE, "account": entry} + else: + if not password: + raise KeystoreError( + "PASSWORD_REQUIRED", f"Encrypting the account {address} needs a password." + ) + key = dict(encrypt_key(private_key, password)) + if save_password and keychain_available(): + # The entry is named after this file's salt, so it cannot collide + # with the saved password of another file for the same address. + entry = password_entry_account(address, key["kdfParams"]["salt"]) + if ( + write_keychain(PASSWORD_SERVICE, entry, password_to_keychain_value(password), location.name) + and created is not None + ): + created.append(_KeychainEntry(PASSWORD_SERVICE, entry)) + file: AccountFile = {"version": 1, "address": address, "key": key} + write_account_file(location, file, exclusive) + return file + + +def _confirm_stored( + location: Location, + account: _Key, + storage: str, + password: Union[str, bytes, None], + prompt: bool, +) -> None: + """Read an account file back and confirm it returns the expected key. + + Raises: + KeystoreError: ``INVALID_ACCOUNT_FILE`` when the file is absent or + holds another account or storage, ``ADDRESS_MISMATCH`` when it + returns another key, plus the failures of reading the stored key. + """ + written = read_account_file(location.path) + if ( + written is None + or written.file["address"] != account.address + or written.file["key"]["type"] != storage + ): + raise KeystoreError( + "INVALID_ACCOUNT_FILE", + f"Account file {location.path} does not hold {account.address} with {storage} storage.", + ) + private_key, _ = _read_stored_key(written.file, location, password, prompt) + if private_key != account.private_key: + raise KeystoreError( + "ADDRESS_MISMATCH", + f"Account file {location.path} does not return the key of {account.address} when read back.", + ) + + +def _store_account( + account: _Key, + location: Location, + storage: str, + password: Optional[str], + save_password: bool, +) -> Tuple[StoredAccount, Optional[bytes]]: + """Store an account unless its file already exists. + + Shared by :func:`save` and :func:`migrate`. + + Returns: + The stored account and, when a new encrypted file was written, the + password it was written with. + + Raises: + KeystoreError: ``ACCOUNT_EXISTS`` when the file exists with another + address or another storage type, plus the failures of writing the + storage. + """ + # Checked before anything is written or asked for. + if storage == "keychain": + require_keychain('Keychain storage works on macOS only; use "plaintext" or "encrypted" here.') + + existing = read_account_file(location.path) + if existing is not None: + held: str = existing.file["address"] + current: str = existing.file["key"]["type"] + if held != account.address: + raise KeystoreError( + "ACCOUNT_EXISTS", + f"Account file {location.path} already holds {held}; refusing to replace it with " + f"{account.address}. Choose another account name.", + ) + if current != storage: + raise KeystoreError( + "ACCOUNT_EXISTS", + f"Account file {location.path} already holds {account.address} with {current} storage. " + "Use protect to change how the key is stored.", + ) + # Same account, same storage: nothing to write. + return _describe(location, existing.file), None + + chosen: Optional[bytes] = None + if storage == "encrypted": + chosen = choose_new_password( + PasswordSubject(location.name, account.address), + explicit=[password], + environment=True, + prompt=True, + ) + # The file is created exclusively: another process may have stored an + # account under this name since the check above, and it must not be + # replaced. + # Keychain entries are made for this file alone, under names no other file + # has, so removing them on failure cannot touch another file's key. + created: List[_KeychainEntry] = [] + try: + file = _write_storage(location, account, storage, chosen, save_password, True, created) + except FileExistsError: + # The file that won the race has Keychain entries of its own; the ones + # made here belong to a file that was never created. They go first, so + # nothing below can leave them behind. + _remove_entries(created) + now = read_account_file(location.path) + same = now is not None and now.file["address"] == account.address and now.file["key"]["type"] == storage + # The same account in the same storage is what was asked for. + if now is not None and same: + return _describe(location, now.file), None + raise KeystoreError( + "ACCOUNT_EXISTS", + f"Account file {location.path} was created by another process while {account.address} was " + "being stored; it was not replaced. Choose another account name.", + ) from None + except BaseException: + # No account file was created, so nothing points at the entries made here. + _remove_entries(created) + raise + return _describe(location, file), chosen + + +def save( + account: object, + *, + name: Optional[str] = None, + dir: Optional[PathLike] = None, + storage: Storage = "plaintext", + password: Optional[str] = None, + save_password: bool = False, +) -> StoredAccount: + """Store an account in an account file so later runs can load it. + + Writes ``/.json`` with owner-only access (directory mode 0700, + file mode 0600) through a temporary file and a rename. Depending on + ``storage`` it also writes the macOS Keychain or stretches a password, and + it prompts for a password when ``"encrypted"`` is requested without one + and a terminal is attached. Does not contact a network. + + An existing file is never replaced. Saving the same account with the same + storage again returns without rewriting; use :func:`protect` to change how + an account is stored. + + Args: + account: The account to store: an ``Account`` or ``PrivateKey`` from + ``aleo.mainnet`` or ``aleo.testnet``, a private-key string, or a + :class:`LoadedAccount`. When the object states an address, the key + must derive it. + name: Account name: 1 to 64 characters of ``a-z``, ``0-9``, ``_`` or + ``-``, starting with a letter or digit. Defaults to + ``ALEO_ACCOUNT``, then ``default``. + dir: Accounts directory; a leading ``~`` expands to the home + directory. Defaults to ``ALEO_ACCOUNTS_DIR``, then + ``~/.aleo/accounts``. Pass it to keep accounts inside a project or + a test directory. + storage: How to hold the key. Defaults to ``"plaintext"``. Use + ``"keychain"`` (macOS) or ``"encrypted"`` to protect a copied or + backed-up file, and ``"none"`` to record the address only; the + caller then keeps the key it already holds. + password: Password for ``"encrypted"``. Defaults to + ``ALEO_ACCOUNT_PASSWORD``, then a hidden prompt that asks twice. + Must not be empty. + save_password: Also save the password in the macOS Keychain, so later + loads need no password. Defaults to False. Applies to + ``"encrypted"`` on macOS and is ignored otherwise. + + Returns: + The stored account, without its key. + + Raises: + KeystoreError: ``ACCOUNT_EXISTS`` when the file holds another address, + or the same address with another storage; ``INVALID_KEY`` or + ``ADDRESS_MISMATCH`` when the key is unusable or does not derive + the stated address; ``INVALID_NAME``; ``UNSUPPORTED_STORAGE``; + ``KEYCHAIN_UNAVAILABLE`` for ``"keychain"`` outside macOS, before + anything is written; ``KEYCHAIN_FAILED``; ``PASSWORD_REQUIRED`` + when ``"encrypted"`` has no password source. + OSError: The directory or file could not be written. + """ + _assert_storage(storage, STORAGE_TYPES) + location = resolve_location(name, dir) + origin = "The private key of the account" + key_text, stated = _account_key(account) + parsed = _Key(*parse_key(key_text, origin)) + if stated is not None and stated != parsed.address: + raise _mismatch(origin, parsed.address, "the account states", stated) + stored, _ = _store_account(parsed, location, storage, password, bool(save_password)) + return stored + + +def load( + *, + name: Optional[str] = None, + dir: Optional[PathLike] = None, + private_key: Optional[str] = None, + legacy_key: Optional[str] = None, + expected_address: Optional[str] = None, + password: Optional[str] = None, + prompt: bool = True, +) -> LoadedAccount: + """Resolve the account to sign with, following the lookup order. + + Sources, first match wins: + + 1. The ``private_key`` argument. The key variables are then not read. + 2. ``ALEO_PRIVATE_KEY``, then its alias ``SHIELD_SWAP_PRIVATE_KEY``. + 3. The file named by ``ALEO_PRIVATE_KEY_FILE``, then its alias + ``SHIELD_SWAP_PRIVATE_KEY_FILE``: a text file holding only the key. + 4. The selected account file. + 5. The ``legacy_key`` argument, only when no account file exists. + + A variable that is set but empty is an error, and so are two variables + that hold different keys. When the selected account file exists, a key + from sources 1 to 3 must derive the address the file records. Nothing here + generates a key or writes one to disk, so a key supplied through the + environment is used for this process only. + + Reads the environment and the account file, tightens a file readable by + others to mode 0600, and for a ``"keychain"`` or ``"encrypted"`` file runs + the macOS ``security`` tool or stretches a password (about 200 ms). The + password of an encrypted file comes from the ``password`` argument, then + ``ALEO_ACCOUNT_PASSWORD``, then a password saved in the macOS Keychain, + then a hidden terminal prompt with three attempts. A wrong password from + any source but the prompt fails at once. Does not contact a network. + + Args: + name: Account name. Defaults to ``ALEO_ACCOUNT``, then ``default``. + dir: Accounts directory. Defaults to ``ALEO_ACCOUNTS_DIR``, then + ``~/.aleo/accounts``. + private_key: Key supplied by the caller, taking precedence over every + other source. + legacy_key: Key from the calling tool's own earlier state. Used only + when no other source and no account file exists; the result then + reports ``source == "legacy"``. When an account file exists, this + key must derive the file's address. + expected_address: Address the resolved key must derive, such as the + address recorded in the calling tool's state. + password: Password for an encrypted account file. + prompt: Whether a password prompt may be shown when a terminal is + attached. Defaults to True. Pass False for unattended jobs. + + Returns: + The address, the private key, the source of the key and the selected + account file when one exists. + + Raises: + KeystoreError: ``ACCOUNT_NOT_FOUND`` when no source produced a key; + ``KEY_NOT_STORED`` when the file records an address only and no + key came from sources 1 to 3; ``EMPTY_KEY_SOURCE``; + ``KEY_CONFLICT``; ``INVALID_KEY``; ``ADDRESS_MISMATCH``; + ``INVALID_NAME``; ``INVALID_ACCOUNT_FILE``, + ``UNSUPPORTED_VERSION`` or ``UNSUPPORTED_STORAGE`` for a file this + reader cannot use; ``KEYCHAIN_UNAVAILABLE``, + ``KEYCHAIN_ITEM_NOT_FOUND`` or ``KEYCHAIN_FAILED``; + ``PASSWORD_REQUIRED`` or ``WRONG_PASSWORD``. + OSError: The account file exists but could not be read. + """ + location = resolve_location(name, dir) + + # Sources 1 to 3: a key handed over by the caller or the environment. + resolved: Optional[Resolved] + if private_key is not None: + origin = "The private_key argument" + resolved = Resolved(*parse_key(private_key, origin), "argument", origin) + else: + resolved = key_from_environment() + + # The account file is read even when a key is already in hand: it records + # which account this name stands for, and an unusable file stops the lookup. + existing = read_account_file(location.path) + legacy_origin = "The legacy_key argument" + if existing is not None and legacy_key is not None: + legacy = _Key(*parse_key(legacy_key, legacy_origin)) + if legacy.address != existing.file["address"]: + raise _mismatch( + legacy_origin, + legacy.address, + f"account file {location.path} records", + existing.file["address"], + ) + + if resolved is not None: + if existing is not None and resolved.address != existing.file["address"]: + raise _mismatch( + resolved.origin, + resolved.address, + f"account file {location.path} records", + existing.file["address"], + ) + elif existing is not None: + # Source 4: the account file itself. + stored_key, _ = _read_stored_key(existing.file, location, password, bool(prompt)) + resolved = Resolved( + stored_key, existing.file["address"], "account-file", f"Account file {location.path}" + ) + elif legacy_key is not None: + # Source 5: the calling tool's earlier state. + resolved = Resolved(*parse_key(legacy_key, legacy_origin), "legacy", legacy_origin) + else: + raise KeystoreError( + "ACCOUNT_NOT_FOUND", + f"No Aleo account found: {KEY_VARIABLES[0]} and {KEY_FILE_VARIABLES[0]} are not set and " + f"there is no account file at {location.path}.", + ) + + if expected_address is not None and resolved.address != expected_address: + raise _mismatch(resolved.origin, resolved.address, "the expected address is", expected_address) + + return LoadedAccount( + address=resolved.address, + private_key=resolved.private_key, + source=resolved.source, + stored=_describe(location, existing.file) if existing is not None else None, + ) + + +def info(*, name: Optional[str] = None, dir: Optional[PathLike] = None) -> Optional[StoredAccount]: + """Describe the selected account file without reading its key. + + Reads only the account file: no key variable, Keychain entry or password + is touched, so the result is safe to show. Tightens a file readable by + others to mode 0600. + + Args: + name: Account name. Defaults to ``ALEO_ACCOUNT``, then ``default``. + dir: Accounts directory. Defaults to ``ALEO_ACCOUNTS_DIR``, then + ``~/.aleo/accounts``. + + Returns: + The account's name, path, address and storage type, or ``None`` when + no account file exists. + + Raises: + KeystoreError: ``INVALID_NAME``, or ``INVALID_ACCOUNT_FILE``, + ``UNSUPPORTED_VERSION`` or ``UNSUPPORTED_STORAGE`` for a file this + reader cannot use. + OSError: The account file exists but could not be read. + """ + location = resolve_location(name, dir) + existing = read_account_file(location.path) + return _describe(location, existing.file) if existing is not None else None + + +def protect( + *, + storage: Literal["plaintext", "keychain", "encrypted"], + name: Optional[str] = None, + dir: Optional[PathLike] = None, + password: Optional[str] = None, + new_password: Optional[str] = None, + save_password: bool = False, + prompt: bool = True, +) -> StoredAccount: + """Change how an existing account file holds its key. + + Reads the current key from the account file, writes the new storage, reads + it back and checks the address, and only then removes the old secret: the + Keychain key entry, or a saved password that no longer applies. When the + check fails the original file is put back. The key variables are not read. + + Requesting ``"encrypted"`` for an account that is already encrypted sets a + new password and a new salt. Requesting the storage a plaintext or + Keychain account already has returns without rewriting. An account cannot + be moved to ``"none"``, which would delete the only stored copy of the + key. + + Moving to ``"keychain"`` or ``"encrypted"`` protects this account file + only. A copy of the key in another tool's own state file stays readable + until it is removed; see :func:`migrate`. + + Args: + storage: Storage to move to: ``"plaintext"``, ``"keychain"`` (macOS) + or ``"encrypted"``. + name: Account name. Defaults to ``ALEO_ACCOUNT``, then ``default``. + dir: Accounts directory. Defaults to ``ALEO_ACCOUNTS_DIR``, then + ``~/.aleo/accounts``. + password: Current password when the account is encrypted; defaults to + ``ALEO_ACCOUNT_PASSWORD``, a password saved in the Keychain, then + a prompt. When the account is not yet encrypted and + ``new_password`` is not given, this is the password to set. + new_password: Password to encrypt with. When the account is not yet + encrypted it defaults to ``password``, then + ``ALEO_ACCOUNT_PASSWORD``, then a prompt that asks twice. When + replacing an existing password it defaults to the prompt only, + because the variable then holds the current password. + save_password: Save the new password in the macOS Keychain. Defaults + to False, which also removes a previously saved password. Applies + to ``"encrypted"`` on macOS and is ignored otherwise. + prompt: Whether password prompts may be shown when a terminal is + attached. Defaults to True. + + Returns: + The account as stored after the change. + + Raises: + KeystoreError: ``ACCOUNT_NOT_FOUND`` when no account file exists; + ``KEY_NOT_STORED`` when the file records an address only; + ``UNSUPPORTED_STORAGE`` for ``"none"`` or an unknown storage; + ``KEYCHAIN_UNAVAILABLE`` outside macOS, before anything is + written; ``KEYCHAIN_ITEM_NOT_FOUND`` or ``KEYCHAIN_FAILED``; + ``PASSWORD_REQUIRED`` or ``WRONG_PASSWORD``; ``ADDRESS_MISMATCH`` + when a stored key does not derive the file's address. + OSError: The account file could not be read or written. + """ + _assert_storage(storage, ("plaintext", "keychain", "encrypted")) + location = resolve_location(name, dir) + if storage == "keychain": + require_keychain('Keychain storage works on macOS only; use "plaintext" or "encrypted" here.') + + existing = read_account_file(location.path) + if existing is None: + raise KeystoreError("ACCOUNT_NOT_FOUND", f"There is no account file at {location.path}.") + current: str = existing.file["key"]["type"] + address: str = existing.file["address"] + subject = PasswordSubject(location.name, address) + + # A plaintext or Keychain account already stored as requested needs nothing. + if current == storage and storage != "encrypted": + return _describe(location, existing.file) + + # Reading the current key also proves the stored copy is intact before + # anything is replaced. An address-only file fails here with KEY_NOT_STORED. + private_key, _ = _read_stored_key(existing.file, location, password, bool(prompt)) + account = _Key(private_key, address) + + chosen: Optional[bytes] = None + if storage == "encrypted": + if current == "encrypted": + # The variable and ``password`` hold the current password here, so + # the new one comes from its own argument or the person at the + # terminal. + chosen = choose_new_password( + subject, explicit=[new_password], environment=False, prompt=bool(prompt) + ) + else: + chosen = choose_new_password( + subject, explicit=[new_password, password], environment=True, prompt=bool(prompt) + ) + saving = storage == "encrypted" and bool(save_password) and keychain_available() + + # One process changes an account file at a time. Passwords were asked for + # above, so the lock is held only while files and the Keychain change. + with account_lock(location): + # The file was read before the lock was taken. If another process has + # changed it since, the key and the old secret worked out above belong + # to a file that no longer exists, and nothing here is safe to do. + latest = read_account_file(location.path) + if latest is None or latest.data != existing.data: + raise KeystoreError( + "ACCOUNT_BUSY", + f"Account file {location.path} was changed by another process while its storage was " + "being changed. Nothing was changed here; run the operation again.", + ) + + # Every step below is undone together if any of them fails: the original + # file goes back, and the Keychain entries this call created are removed. + # The old secret is the last thing touched, and it is touched only once + # everything else has succeeded, so the original file works again as soon + # as it is back in place. + created: List[_KeychainEntry] = [] + try: + # The new file's saved password has its own entry, named after the new + # salt, so the entry of the file being replaced is not disturbed. + _write_storage(location, account, storage, chosen, saving, False, created) + # Read the new storage back the way a later load would, then compare. + _confirm_stored(location, account, storage, chosen, False) + + # Only now is the old secret redundant. Each file has entries of its + # own, so only a copy of this very file can still point at them; an + # entry a copy in the same directory still uses is left in place. + if current == "keychain" and storage != "keychain": + old_entry: str = existing.file["key"]["account"] + if not _neighbour_uses( + location, + lambda file: _key_of(file).get("type") == "keychain" and _key_of(file).get("account") == old_entry, + ): + delete_keychain(KEY_SERVICE, old_entry) + previous = saved_password_entry(existing.file) + if previous is not None and keychain_available(): + salt = existing.file["key"]["kdfParams"]["salt"] + + def same_ciphertext(file: Dict[str, Any]) -> bool: + key = _key_of(file) + params = key.get("kdfParams") + return ( + file.get("address") == address + and key.get("type") == "encrypted" + and isinstance(params, dict) + and cast(Dict[str, Any], params).get("salt") == salt + ) + + if not _neighbour_uses(location, same_ciphertext): + delete_keychain(PASSWORD_SERVICE, previous) + except BaseException: + write_file_atomic(location.path, existing.data) + _remove_entries(created) + raise + + return StoredAccount(name=location.name, path=Path(location.path), address=address, storage=storage) + + +def export( + *, + name: Optional[str] = None, + dir: Optional[PathLike] = None, + password: Optional[str] = None, + prompt: bool = True, +) -> str: + """Return the private key held by the selected account file. + + Use it to back a key up or to move an account to another machine. Reads + only the account file and what it points at (the Keychain entry, or the + password sources of an encrypted file); the key variables are never + consulted. The result is the secret itself: a caller that prints it is + responsible for doing so only for a person at a terminal. + + Args: + name: Account name. Defaults to ``ALEO_ACCOUNT``, then ``default``. + dir: Accounts directory. Defaults to ``ALEO_ACCOUNTS_DIR``, then + ``~/.aleo/accounts``. + password: Password for an encrypted account file. Defaults to + ``ALEO_ACCOUNT_PASSWORD``, a password saved in the Keychain, then + a prompt. + prompt: Whether a password prompt may be shown when a terminal is + attached. Defaults to True. + + Returns: + The private key (``APrivateKey1...``). + + Raises: + KeystoreError: ``ACCOUNT_NOT_FOUND`` when no account file exists; + ``KEY_NOT_STORED`` when the file records an address only; + ``INVALID_KEY`` or ``ADDRESS_MISMATCH`` when the stored key is + unusable; ``KEYCHAIN_UNAVAILABLE``, ``KEYCHAIN_ITEM_NOT_FOUND`` or + ``KEYCHAIN_FAILED``; ``PASSWORD_REQUIRED`` or ``WRONG_PASSWORD``. + OSError: The account file exists but could not be read. + """ + location = resolve_location(name, dir) + existing = read_account_file(location.path) + if existing is None: + raise KeystoreError("ACCOUNT_NOT_FOUND", f"There is no account file at {location.path}.") + private_key, _ = _read_stored_key(existing.file, location, password, bool(prompt)) + return private_key + + +def _read_legacy_key(path: str) -> _Legacy: + """Read the private key from a legacy state file. + + Args: + path: Path of a JSON file with a top-level ``privateKey`` or + ``private_key`` string. + + Raises: + KeystoreError: ``LEGACY_KEY_NOT_FOUND`` when the file cannot be read, + is not a JSON object or has neither field; ``INVALID_KEY`` when a + field holds text that is not a key; ``KEY_CONFLICT`` when the two + fields hold different keys, since it is then unclear which account + the file belongs to. + """ + + def not_found(problem: str) -> KeystoreError: + return KeystoreError("LEGACY_KEY_NOT_FOUND", f"No key found in {path}: {problem}.") + + try: + with open(path, "rb") as handle: + data = handle.read() + except OSError as error: + raise not_found(f"the file could not be read ({error_code(error)})") from error + + # The parser's message can quote the file, which holds a key, so neither + # failure below carries the underlying error. + text: Optional[str] + try: + text = data.decode("utf-8") + except UnicodeDecodeError: + text = None + if text is None: + raise not_found("the file is not UTF-8 text") + content: Any = None + is_json = True + try: + content = loads_strict(text) + except (ValueError, RecursionError): + is_json = False + if not is_json: + raise not_found("the file is not JSON") + if not isinstance(content, dict): + raise not_found("the file does not hold a JSON object") + record = cast(Dict[str, Any], content) + fields = tuple( + name for name in _LEGACY_KEY_FIELDS if isinstance(record.get(name), str) and record.get(name) != "" + ) + if not fields: + raise not_found('it has no "privateKey" or "private_key" field') + first = fields[0] + account = _Key(*parse_key(record[first], f'The "{first}" field of {path}')) + if len(fields) > 1: + second = fields[1] + other = _Key(*parse_key(record[second], f'The "{second}" field of {path}')) + if other.address != account.address: + raise KeystoreError( + "KEY_CONFLICT", + f'{path} holds two different keys: "{first}" belongs to {account.address} and "{second}" to ' + f"{other.address}. Remove the one that is not wanted, then migrate again.", + ) + return _Legacy(text, record, fields, account) + + +def _without_key_fields(legacy: _Legacy) -> str: + """Render a legacy state file without its key fields. + + Keeps the other fields in their order, the indentation of the original and + whether it ended with a newline. + """ + rest = {name: value for name, value in legacy.content.items() if name not in legacy.fields} + # The indentation is whatever precedes the first field on its own line; a + # file written on one line stays on one line. + layout = re.match(r"\s*\{\r?\n([ \t]+)\S", legacy.text) + if layout is None: + body = json.dumps(rest, ensure_ascii=False, separators=(",", ":")) + else: + # At most ten characters of indentation, the limit of JSON.stringify, + # so every SDK rewrites a file the same way. + body = json.dumps(rest, ensure_ascii=False, indent=layout.group(1)[:10]) + # A lone surrogate cannot be written as UTF-8; it keeps its escaped form. + body = _LONE_SURROGATE.sub(lambda found: f"\\u{ord(found.group()):04x}", body) + return f"{body}\n" if legacy.text.endswith("\n") else body + + +def migrate( + source: PathLike, + *, + name: Optional[str] = None, + dir: Optional[PathLike] = None, + storage: Storage = "plaintext", + password: Optional[str] = None, + save_password: bool = False, + remove_legacy_key: bool = False, +) -> StoredAccount: + """Copy the private key from a legacy state file into an account file. + + Reads a JSON file that keeps a key in a top-level ``privateKey`` or + ``private_key`` field, such as a Shield Swap CLI ``state.json`` or a + Shield Swap Python ``profile.json``, and stores that key exactly as + :func:`save` would. The legacy file is left untouched unless + ``remove_legacy_key`` is set, so by default a plaintext copy of the key + remains there. + + With ``remove_legacy_key``, the new account is read back and its key + confirmed first; the legacy file is then rewritten without the key field, + keeping its other fields, their order and its indentation, at mode 0600. + + Args: + source: Path of the legacy JSON file. + name: Account name. Defaults to ``ALEO_ACCOUNT``, then ``default``. + dir: Accounts directory. Defaults to ``ALEO_ACCOUNTS_DIR``, then + ``~/.aleo/accounts``. + storage: How to hold the key. Defaults to ``"plaintext"``. + password: Password for ``"encrypted"``. Defaults to + ``ALEO_ACCOUNT_PASSWORD``, then a hidden prompt that asks twice. + save_password: Also save the password in the macOS Keychain. Defaults + to False. Applies to ``"encrypted"`` on macOS. + remove_legacy_key: Strip the key from the legacy file once the new + account file is confirmed. Defaults to False. Not allowed with + ``storage="none"``, which would leave no stored copy. + + Returns: + The stored account, without its key. When ``remove_legacy_key`` was + set and the call returns, the legacy file no longer holds the key. + + Raises: + KeystoreError: ``LEGACY_KEY_NOT_FOUND`` when the file holds no key; + ``INVALID_KEY``; ``KEY_NOT_STORED`` when ``remove_legacy_key`` is + combined with ``"none"``; plus every failure of :func:`save`, + including ``ACCOUNT_EXISTS``. + OSError: The account file or the legacy file could not be written. + """ + _assert_storage(storage, STORAGE_TYPES) + removing = bool(remove_legacy_key) + if storage == "none" and removing: + raise KeystoreError( + "KEY_NOT_STORED", + "An account stored without its key cannot replace the legacy key; " + "choose another storage or keep the legacy key.", + ) + location = resolve_location(name, dir) + + origin_path = os.fspath(source) + legacy = _read_legacy_key(origin_path) + account = legacy.account + stored, chosen = _store_account(account, location, storage, password, bool(save_password)) + + if not removing: + return stored + + # The legacy copy goes only after the new one has been read back in full. + _confirm_stored(location, account, storage, chosen if chosen is not None else password, True) + write_file_atomic(origin_path, _without_key_fields(legacy)) + return stored + + +__all__ = [ + "KeystoreError", + "LoadedAccount", + "Storage", + "StoredAccount", + "export", + "info", + "load", + "migrate", + "protect", + "save", +] diff --git a/sdk/python/aleo/keystore/__main__.py b/sdk/python/aleo/keystore/__main__.py new file mode 100644 index 0000000..0ce9da0 --- /dev/null +++ b/sdk/python/aleo/keystore/__main__.py @@ -0,0 +1,12 @@ +"""Run the account commands: ``python -m aleo.keystore ``. + +``create``, ``import``, ``show``, ``protect``, ``export`` and ``migrate`` +store and inspect an Aleo account on this machine; ``--help`` lists the flags +of each. +""" +from __future__ import annotations + +from ._cli import main + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/sdk/python/aleo/keystore/_bip39_english.txt b/sdk/python/aleo/keystore/_bip39_english.txt new file mode 100644 index 0000000..942040e --- /dev/null +++ b/sdk/python/aleo/keystore/_bip39_english.txt @@ -0,0 +1,2048 @@ +abandon +ability +able +about +above +absent +absorb +abstract +absurd +abuse +access +accident +account +accuse +achieve +acid +acoustic +acquire +across +act +action +actor +actress +actual +adapt +add +addict +address +adjust +admit +adult +advance +advice +aerobic +affair +afford +afraid +again +age +agent +agree +ahead +aim +air +airport +aisle +alarm +album +alcohol +alert +alien +all +alley +allow +almost +alone +alpha +already +also +alter +always +amateur +amazing +among +amount +amused +analyst +anchor +ancient +anger +angle +angry +animal +ankle +announce +annual +another +answer +antenna +antique +anxiety +any +apart +apology +appear +apple +approve +april +arch +arctic +area +arena +argue +arm +armed +armor +army +around +arrange +arrest +arrive +arrow +art +artefact +artist +artwork +ask +aspect +assault +asset +assist +assume +asthma +athlete +atom +attack +attend +attitude +attract +auction +audit +august +aunt +author +auto +autumn +average +avocado +avoid +awake +aware +away +awesome +awful +awkward +axis +baby +bachelor +bacon +badge +bag +balance +balcony +ball +bamboo +banana +banner +bar +barely +bargain +barrel +base +basic +basket +battle +beach +bean +beauty +because +become +beef +before +begin +behave +behind +believe +below +belt +bench +benefit +best +betray +better +between +beyond +bicycle +bid +bike +bind +biology +bird +birth +bitter +black +blade +blame +blanket +blast +bleak +bless +blind +blood +blossom +blouse +blue +blur +blush +board +boat +body +boil +bomb +bone +bonus +book +boost +border +boring +borrow +boss +bottom +bounce +box +boy +bracket +brain +brand +brass +brave +bread +breeze +brick +bridge +brief +bright +bring +brisk +broccoli +broken +bronze +broom +brother +brown +brush +bubble +buddy +budget +buffalo +build +bulb +bulk +bullet +bundle +bunker +burden +burger +burst +bus +business +busy +butter +buyer +buzz +cabbage +cabin +cable +cactus +cage +cake +call +calm +camera +camp +can +canal +cancel +candy +cannon +canoe +canvas +canyon +capable +capital +captain +car +carbon +card +cargo +carpet +carry +cart +case +cash +casino +castle +casual +cat +catalog +catch +category +cattle +caught +cause +caution +cave +ceiling +celery +cement +census +century +cereal +certain +chair +chalk +champion +change +chaos +chapter +charge +chase +chat +cheap +check +cheese +chef +cherry +chest +chicken +chief +child +chimney +choice +choose +chronic +chuckle +chunk +churn +cigar +cinnamon +circle +citizen +city +civil +claim +clap +clarify +claw +clay +clean +clerk +clever +click +client +cliff +climb +clinic +clip +clock +clog +close +cloth +cloud +clown +club +clump +cluster +clutch +coach +coast +coconut +code +coffee +coil +coin +collect +color +column +combine +come +comfort +comic +common +company +concert +conduct +confirm +congress +connect +consider +control +convince +cook +cool +copper +copy +coral +core +corn +correct +cost +cotton +couch +country +couple +course +cousin +cover +coyote +crack +cradle +craft +cram +crane +crash +crater +crawl +crazy +cream +credit +creek +crew +cricket +crime +crisp +critic +crop +cross +crouch +crowd +crucial +cruel +cruise +crumble +crunch +crush +cry +crystal +cube +culture +cup +cupboard +curious +current +curtain +curve +cushion +custom +cute +cycle +dad +damage +damp +dance +danger +daring +dash +daughter +dawn +day +deal +debate +debris +decade +december +decide +decline +decorate +decrease +deer +defense +define +defy +degree +delay +deliver +demand +demise +denial +dentist +deny +depart +depend +deposit +depth +deputy +derive +describe +desert +design +desk +despair +destroy +detail +detect +develop +device +devote +diagram +dial +diamond +diary +dice +diesel +diet +differ +digital +dignity +dilemma +dinner +dinosaur +direct +dirt +disagree +discover +disease +dish +dismiss +disorder +display +distance +divert +divide +divorce +dizzy +doctor +document +dog +doll +dolphin +domain +donate +donkey +donor +door +dose +double +dove +draft +dragon +drama +drastic +draw +dream +dress +drift +drill +drink +drip +drive +drop +drum +dry +duck +dumb +dune +during +dust +dutch +duty +dwarf +dynamic +eager +eagle +early +earn +earth +easily +east +easy +echo +ecology +economy +edge +edit +educate +effort +egg +eight +either +elbow +elder +electric +elegant +element +elephant +elevator +elite +else +embark +embody +embrace +emerge +emotion +employ +empower +empty +enable +enact +end +endless +endorse +enemy +energy +enforce +engage +engine +enhance +enjoy +enlist +enough +enrich +enroll +ensure +enter +entire +entry +envelope +episode +equal +equip +era +erase +erode +erosion +error +erupt +escape +essay +essence +estate +eternal +ethics +evidence +evil +evoke +evolve +exact +example +excess +exchange +excite +exclude +excuse +execute +exercise +exhaust +exhibit +exile +exist +exit +exotic +expand +expect +expire +explain +expose +express +extend +extra +eye +eyebrow +fabric +face +faculty +fade +faint +faith +fall +false +fame +family +famous +fan +fancy +fantasy +farm +fashion +fat +fatal +father +fatigue +fault +favorite +feature +february +federal +fee +feed +feel +female +fence +festival +fetch +fever +few +fiber +fiction +field +figure +file +film +filter +final +find +fine +finger +finish +fire +firm +first +fiscal +fish +fit +fitness +fix +flag +flame +flash +flat +flavor +flee +flight +flip +float +flock +floor +flower +fluid +flush +fly +foam +focus +fog +foil +fold +follow +food +foot +force +forest +forget +fork +fortune +forum +forward +fossil +foster +found +fox +fragile +frame +frequent +fresh +friend +fringe +frog +front +frost +frown +frozen +fruit +fuel +fun +funny +furnace +fury +future +gadget +gain +galaxy +gallery +game +gap +garage +garbage +garden +garlic +garment +gas +gasp +gate +gather +gauge +gaze +general +genius +genre +gentle +genuine +gesture +ghost +giant +gift +giggle +ginger +giraffe +girl +give +glad +glance +glare +glass +glide +glimpse +globe +gloom +glory +glove +glow +glue +goat +goddess +gold +good +goose +gorilla +gospel +gossip +govern +gown +grab +grace +grain +grant +grape +grass +gravity +great +green +grid +grief +grit +grocery +group +grow +grunt +guard +guess +guide +guilt +guitar +gun +gym +habit +hair +half +hammer +hamster +hand +happy +harbor +hard +harsh +harvest +hat +have +hawk +hazard +head +health +heart +heavy +hedgehog +height +hello +helmet +help +hen +hero +hidden +high +hill +hint +hip +hire +history +hobby +hockey +hold +hole +holiday +hollow +home +honey +hood +hope +horn +horror +horse +hospital +host +hotel +hour +hover +hub +huge +human +humble +humor +hundred +hungry +hunt +hurdle +hurry +hurt +husband +hybrid +ice +icon +idea +identify +idle +ignore +ill +illegal +illness +image +imitate +immense +immune +impact +impose +improve +impulse +inch +include +income +increase +index +indicate +indoor +industry +infant +inflict +inform +inhale +inherit +initial +inject +injury +inmate +inner +innocent +input +inquiry +insane +insect +inside +inspire +install +intact +interest +into +invest +invite +involve +iron +island +isolate +issue +item +ivory +jacket +jaguar +jar +jazz +jealous +jeans +jelly +jewel +job +join +joke +journey +joy +judge +juice +jump +jungle +junior +junk +just +kangaroo +keen +keep +ketchup +key +kick +kid +kidney +kind +kingdom +kiss +kit +kitchen +kite +kitten +kiwi +knee +knife +knock +know +lab +label +labor +ladder +lady +lake +lamp +language +laptop +large +later +latin +laugh +laundry +lava +law +lawn +lawsuit +layer +lazy +leader +leaf +learn +leave +lecture +left +leg +legal +legend +leisure +lemon +lend +length +lens +leopard +lesson +letter +level +liar +liberty +library +license +life +lift +light +like +limb +limit +link +lion +liquid +list +little +live +lizard +load +loan +lobster +local +lock +logic +lonely +long +loop +lottery +loud +lounge +love +loyal +lucky +luggage +lumber +lunar +lunch +luxury +lyrics +machine +mad +magic +magnet +maid +mail +main +major +make +mammal +man +manage +mandate +mango +mansion +manual +maple +marble +march +margin +marine +market +marriage +mask +mass +master +match +material +math +matrix +matter +maximum +maze +meadow +mean +measure +meat +mechanic +medal +media +melody +melt +member +memory +mention +menu +mercy +merge +merit +merry +mesh +message +metal +method +middle +midnight +milk +million +mimic +mind +minimum +minor +minute +miracle +mirror +misery +miss +mistake +mix +mixed +mixture +mobile +model +modify +mom +moment +monitor +monkey +monster +month +moon +moral +more +morning +mosquito +mother +motion +motor +mountain +mouse +move +movie +much +muffin +mule +multiply +muscle +museum +mushroom +music +must +mutual +myself +mystery +myth +naive +name +napkin +narrow +nasty +nation +nature +near +neck +need +negative +neglect +neither +nephew +nerve +nest +net +network +neutral +never +news +next +nice +night +noble +noise +nominee +noodle +normal +north +nose +notable +note +nothing +notice +novel +now +nuclear +number +nurse +nut +oak +obey +object +oblige +obscure +observe +obtain +obvious +occur +ocean +october +odor +off +offer +office +often +oil +okay +old +olive +olympic +omit +once +one +onion +online +only +open +opera +opinion +oppose +option +orange +orbit +orchard +order +ordinary +organ +orient +original +orphan +ostrich +other +outdoor +outer +output +outside +oval +oven +over +own +owner +oxygen +oyster +ozone +pact +paddle +page +pair +palace +palm +panda +panel +panic +panther +paper +parade +parent +park +parrot +party +pass +patch +path +patient +patrol +pattern +pause +pave +payment +peace +peanut +pear +peasant +pelican +pen +penalty +pencil +people +pepper +perfect +permit +person +pet +phone +photo +phrase +physical +piano +picnic +picture +piece +pig +pigeon +pill +pilot +pink +pioneer +pipe +pistol +pitch +pizza +place +planet +plastic +plate +play +please +pledge +pluck +plug +plunge +poem +poet +point +polar +pole +police +pond +pony +pool +popular +portion +position +possible +post +potato +pottery +poverty +powder +power +practice +praise +predict +prefer +prepare +present +pretty +prevent +price +pride +primary +print +priority +prison +private +prize +problem +process +produce +profit +program +project +promote +proof +property +prosper +protect +proud +provide +public +pudding +pull +pulp +pulse +pumpkin +punch +pupil +puppy +purchase +purity +purpose +purse +push +put +puzzle +pyramid +quality +quantum +quarter +question +quick +quit +quiz +quote +rabbit +raccoon +race +rack +radar +radio +rail +rain +raise +rally +ramp +ranch +random +range +rapid +rare +rate +rather +raven +raw +razor +ready +real +reason +rebel +rebuild +recall +receive +recipe +record +recycle +reduce +reflect +reform +refuse +region +regret +regular +reject +relax +release +relief +rely +remain +remember +remind +remove +render +renew +rent +reopen +repair +repeat +replace +report +require +rescue +resemble +resist +resource +response +result +retire +retreat +return +reunion +reveal +review +reward +rhythm +rib +ribbon +rice +rich +ride +ridge +rifle +right +rigid +ring +riot +ripple +risk +ritual +rival +river +road +roast +robot +robust +rocket +romance +roof +rookie +room +rose +rotate +rough +round +route +royal +rubber +rude +rug +rule +run +runway +rural +sad +saddle +sadness +safe +sail +salad +salmon +salon +salt +salute +same +sample +sand +satisfy +satoshi +sauce +sausage +save +say +scale +scan +scare +scatter +scene +scheme +school +science +scissors +scorpion +scout +scrap +screen +script +scrub +sea +search +season +seat +second +secret +section +security +seed +seek +segment +select +sell +seminar +senior +sense +sentence +series +service +session +settle +setup +seven +shadow +shaft +shallow +share +shed +shell +sheriff +shield +shift +shine +ship +shiver +shock +shoe +shoot +shop +short +shoulder +shove +shrimp +shrug +shuffle +shy +sibling +sick +side +siege +sight +sign +silent +silk +silly +silver +similar +simple +since +sing +siren +sister +situate +six +size +skate +sketch +ski +skill +skin +skirt +skull +slab +slam +sleep +slender +slice +slide +slight +slim +slogan +slot +slow +slush +small +smart +smile +smoke +smooth +snack +snake +snap +sniff +snow +soap +soccer +social +sock +soda +soft +solar +soldier +solid +solution +solve +someone +song +soon +sorry +sort +soul +sound +soup +source +south +space +spare +spatial +spawn +speak +special +speed +spell +spend +sphere +spice +spider +spike +spin +spirit +split +spoil +sponsor +spoon +sport +spot +spray +spread +spring +spy +square +squeeze +squirrel +stable +stadium +staff +stage +stairs +stamp +stand +start +state +stay +steak +steel +stem +step +stereo +stick +still +sting +stock +stomach +stone +stool +story +stove +strategy +street +strike +strong +struggle +student +stuff +stumble +style +subject +submit +subway +success +such +sudden +suffer +sugar +suggest +suit +summer +sun +sunny +sunset +super +supply +supreme +sure +surface +surge +surprise +surround +survey +suspect +sustain +swallow +swamp +swap +swarm +swear +sweet +swift +swim +swing +switch +sword +symbol +symptom +syrup +system +table +tackle +tag +tail +talent +talk +tank +tape +target +task +taste +tattoo +taxi +teach +team +tell +ten +tenant +tennis +tent +term +test +text +thank +that +theme +then +theory +there +they +thing +this +thought +three +thrive +throw +thumb +thunder +ticket +tide +tiger +tilt +timber +time +tiny +tip +tired +tissue +title +toast +tobacco +today +toddler +toe +together +toilet +token +tomato +tomorrow +tone +tongue +tonight +tool +tooth +top +topic +topple +torch +tornado +tortoise +toss +total +tourist +toward +tower +town +toy +track +trade +traffic +tragic +train +transfer +trap +trash +travel +tray +treat +tree +trend +trial +tribe +trick +trigger +trim +trip +trophy +trouble +truck +true +truly +trumpet +trust +truth +try +tube +tuition +tumble +tuna +tunnel +turkey +turn +turtle +twelve +twenty +twice +twin +twist +two +type +typical +ugly +umbrella +unable +unaware +uncle +uncover +under +undo +unfair +unfold +unhappy +uniform +unique +unit +universe +unknown +unlock +until +unusual +unveil +update +upgrade +uphold +upon +upper +upset +urban +urge +usage +use +used +useful +useless +usual +utility +vacant +vacuum +vague +valid +valley +valve +van +vanish +vapor +various +vast +vault +vehicle +velvet +vendor +venture +venue +verb +verify +version +very +vessel +veteran +viable +vibrant +vicious +victory +video +view +village +vintage +violin +virtual +virus +visa +visit +visual +vital +vivid +vocal +voice +void +volcano +volume +vote +voyage +wage +wagon +wait +walk +wall +walnut +want +warfare +warm +warrior +wash +wasp +waste +water +wave +way +wealth +weapon +wear +weasel +weather +web +wedding +weekend +weird +welcome +west +wet +whale +what +wheat +wheel +when +where +whip +whisper +wide +width +wife +wild +will +win +window +wine +wing +wink +winner +winter +wire +wisdom +wise +wish +witness +wolf +woman +wonder +wood +wool +word +work +world +worry +worth +wrap +wreck +wrestle +wrist +write +wrong +yard +year +yellow +you +young +youth +zebra +zero +zone +zoo diff --git a/sdk/python/aleo/keystore/_cli.py b/sdk/python/aleo/keystore/_cli.py new file mode 100644 index 0000000..ff57c89 --- /dev/null +++ b/sdk/python/aleo/keystore/_cli.py @@ -0,0 +1,441 @@ +"""The account commands behind ``python -m aleo.keystore``. + +Six commands set up and inspect a stored account from a terminal: + +- ``create`` generates a key and stores it. +- ``import`` stores an existing key or the account of a recovery phrase. +- ``show`` prints the address, name and storage type, never the key. +- ``protect`` changes how the key is stored. +- ``export`` prints the key for a person at a terminal. +- ``migrate`` copies a key out of another tool's state file. + +None of them contacts a network. A password is never taken from the command +line: it comes from ``ALEO_ACCOUNT_PASSWORD``, the macOS Keychain or a hidden +prompt. + +Exit status: 0 when done, 1 when the command failed, 2 when it needs a person +or a decision (no account, no stored key, no password, no terminal), and 64 +for a usage error. +""" +from __future__ import annotations + +import argparse +import json +import sys +from typing import Any, Callable, Dict, List, NoReturn, Optional, Sequence + +from ..mainnet import PrivateKey +from . import StoredAccount +from . import export as export_key +from . import info, migrate, protect, save +from ._errors import KeystoreError +from ._file import read_account_file, resolve_location +from ._keychain import keychain_available, require_keychain +from ._mnemonic import clean_phrase, derive_seed, generate_phrase +from ._password import forget_saved_password +from ._runtime import runtime +from ._sources import TRIMMED, key_from_environment, read_key_text + +EXIT_DONE = 0 +EXIT_FAILED = 1 +EXIT_NEEDS_PERSON = 2 +EXIT_USAGE = 64 + +# Failures a person has to resolve: an agent or a script stops and asks. +_NEEDS_PERSON = frozenset({"ACCOUNT_NOT_FOUND", "KEY_NOT_STORED", "PASSWORD_REQUIRED", "TERMINAL_REQUIRED"}) + +_PROGRAM = "python -m aleo.keystore" +_KEY_PREFIX = "APrivateKey1" +_MAX_INDEX = 2**31 - 1 + + +class _Parser(argparse.ArgumentParser): + """An argument parser whose usage errors exit with status 64.""" + + def error(self, message: str) -> NoReturn: + self.print_usage(sys.stderr) + self.exit(EXIT_USAGE, f"{self.prog}: error: {message}\n") + + +def _account_index(text: str) -> int: + """Parse ``--index``: a whole number from 0 through 2**31 - 1.""" + try: + value = int(text, 10) + except ValueError: + raise argparse.ArgumentTypeError("must be a whole number") from None + if not 0 <= value <= _MAX_INDEX: + raise argparse.ArgumentTypeError("must be from 0 through 2147483647") + return value + + +def _build_parser() -> _Parser: + parser = _Parser( + prog=_PROGRAM, + description="Store an Aleo account on this machine and inspect it.", + allow_abbrev=False, + ) + _add_common(parser, top_level=True) + commands = parser.add_subparsers(dest="command", metavar="", parser_class=_Parser) + + def command(name: str, summary: str) -> argparse.ArgumentParser: + added = commands.add_parser(name, help=summary, description=summary, allow_abbrev=False) + _add_common(added, top_level=False) + return added + + def storage_flags(target: argparse.ArgumentParser, choices: Sequence[str], required: bool) -> None: + target.add_argument( + "--storage", + choices=choices, + default=None if required else "plaintext", + help="how to hold the key" + ("" if required else " (default: plaintext)"), + ) + target.add_argument( + "--save-password", + action="store_true", + help="save the password in the macOS Keychain (encrypted storage on macOS)", + ) + + create = command("create", "Generate a key and store it.") + storage_flags(create, ("plaintext", "keychain", "encrypted", "none"), required=False) + create.add_argument( + "--mnemonic", + action="store_true", + help="derive the key from a new recovery phrase, shown once and stored nowhere, " + "so a wallet can import the account later; requires a terminal", + ) + + imported = command("import", "Store an existing key, or the account of a recovery phrase.") + storage_flags(imported, ("plaintext", "keychain", "encrypted", "none"), required=False) + imported.add_argument("--key-file", metavar="", help="text file holding the private key") + imported.add_argument("--mnemonic-file", metavar="", help="text file holding a recovery phrase") + imported.add_argument( + "--index", metavar="", type=_account_index, default=0, + help="account index for a recovery phrase (default: 0)", + ) + imported.add_argument( + "--derivation", choices=("standard", "legacy"), default="standard", + help="derivation path for a recovery phrase (default: standard)", + ) + + command("show", "Print the address, account name and storage type. Never the key.") + + protected = command("protect", "Change how the key is stored.") + storage_flags(protected, ("plaintext", "keychain", "encrypted"), required=True) + protected.add_argument( + "--forget-password", action="store_true", + help="remove a saved password from the macOS Keychain", + ) + + command("export", "Print the private key. Requires a terminal.") + + migrated = command("migrate", "Copy a key from a legacy profile.json or state.json into an account file.") + storage_flags(migrated, ("plaintext", "keychain", "encrypted"), required=False) + migrated.add_argument( + "--from", dest="source", metavar="", required=True, + help="the legacy profile.json or state.json", + ) + migrated.add_argument( + "--remove-legacy-key", action="store_true", + help="strip the key from the legacy file after checking the new account", + ) + return parser + + +def _add_common(parser: argparse.ArgumentParser, *, top_level: bool) -> None: + """Add the flags every command accepts, before or after the command name.""" + # A flag left out after the command name must not reset one given before it. + unset: Dict[str, Any] = {} if top_level else {"default": argparse.SUPPRESS} + parser.add_argument("--name", metavar="", help="account name (default: ALEO_ACCOUNT, then default)", **unset) + parser.add_argument( + "--dir", metavar="", + help="accounts directory (default: ALEO_ACCOUNTS_DIR, then ~/.aleo/accounts)", **unset, + ) + parser.add_argument( + "--json", action="store_true", help="machine-readable output on standard output", **unset + ) + + +def _out(text: str) -> None: + sys.stdout.write(f"{text}\n") + sys.stdout.flush() + + +def _report(stored: StoredAccount, as_json: bool, sentence: str) -> None: + """Print the outcome of a command that leaves an account file in place.""" + if as_json: + _out( + json.dumps( + { + "name": stored.name, + "address": stored.address, + "storage": stored.storage, + "path": str(stored.path), + }, + ensure_ascii=False, + ) + ) + else: + _out(sentence) + + +def _summary(stored: StoredAccount, verb: str) -> str: + return f"{verb} Aleo account {stored.name} ({stored.address}) with {stored.storage} storage in {stored.path}." + + +def _require_terminal(what: str, as_json: bool, secret: str = "the private key") -> None: + """Stop a command that shows a secret unless a person is at a terminal. + + Args: + what: The command, as the person typed it. + as_json: Whether ``--json`` was given. + secret: What the command shows, named in the message. + + Raises: + KeystoreError: ``TERMINAL_REQUIRED`` when ``--json`` was given, or + when standard input, output or error is not a terminal. + """ + if as_json: + raise KeystoreError( + "TERMINAL_REQUIRED", + f"{what} shows {secret} to a person at a terminal and has no --json output.", + ) + if not (runtime.terminal_attached() and runtime.output_is_terminal()): + raise KeystoreError( + "TERMINAL_REQUIRED", + f"{what} shows {secret} and runs only with a terminal attached to its input and output.", + ) + + +def _storage_notes(stored: StoredAccount, save_password: bool) -> None: + """Tell the person what the chosen storage does not do on this system.""" + if save_password and not (stored.storage == "encrypted" and keychain_available()): + runtime.notify( + "--save-password applies to encrypted storage on macOS only; no password was saved." + ) + if stored.storage == "plaintext" and runtime.platform == "win32": + runtime.notify( + f"Windows does not enforce owner-only file modes: {stored.path} is protected only by the " + "access rules of its folder." + ) + + +def _key_of_phrase(text: str, index: int, derivation: str) -> str: + """Derive the private key of a recovery phrase after tidying it.""" + seed = derive_seed(clean_phrase(text), index=index, derivation=derivation) + return str(PrivateKey.from_seed_unchecked(list(seed))) + + +def _create(args: argparse.Namespace) -> int: + storage: str = args.storage + with_phrase: bool = args.mnemonic + # A phrase, or a key that is stored nowhere, is shown once, so a person + # must be there to receive it. Checked before anything is generated or + # written. + if with_phrase: + _require_terminal("create --mnemonic", args.json, "the recovery phrase") + if storage == "none": + _require_terminal("create --storage none", args.json) + phrase = generate_phrase() if with_phrase else None + key = _key_of_phrase(phrase, 0, "standard") if phrase is not None else str(PrivateKey.random()) + stored = save( + key, name=args.name, dir=args.dir, storage=args.storage, save_password=args.save_password + ) + _report(stored, args.json, _summary(stored, "Created")) + _storage_notes(stored, args.save_password) + if phrase is not None: + _out(f"Recovery phrase: {phrase}") + runtime.notify( + "This phrase is shown once and stored nowhere. Write it down and keep it offline. " + "A wallet imports this account from it, and whoever holds it controls every account " + "derived from it." + ) + if storage == "none": + _out(f"Private key: {key}") + runtime.notify( + "This key is stored nowhere. Keep it safe and supply it through ALEO_PRIVATE_KEY or " + "ALEO_PRIVATE_KEY_FILE on every run." + ) + elif storage == "keychain" and phrase is None: + runtime.notify( + "The key of this account exists only in the macOS Keychain of this Mac. " + f"Back it up with: {_PROGRAM} export" + ) + return EXIT_DONE + + +def _key_to_import(args: argparse.Namespace) -> str: + """Find the key to import: a file flag, the key variables, then a prompt.""" + if args.key_file is not None: + return read_key_text(args.key_file, f"The key file {args.key_file}") + if args.mnemonic_file is not None: + phrase = read_key_text(args.mnemonic_file, f"The recovery phrase file {args.mnemonic_file}") + return _key_of_phrase(phrase, args.index, args.derivation) + from_environment = key_from_environment() + if from_environment is not None: + return from_environment.private_key + if not runtime.terminal_attached(): + raise KeystoreError( + "ACCOUNT_NOT_FOUND", + "No key to import: pass --key-file or --mnemonic-file, set ALEO_PRIVATE_KEY or " + "ALEO_PRIVATE_KEY_FILE, or run with a terminal attached.", + ) + typed = "" + try: + typed = runtime.prompt_hidden("Private key or recovery phrase to import: ").strip(TRIMMED) + except KeystoreError as error: + if error.code != "PASSWORD_REQUIRED": + raise + if not typed: + raise KeystoreError("EMPTY_KEY_SOURCE", "No key or recovery phrase was entered.") + if typed.startswith(_KEY_PREFIX): + return typed + return _key_of_phrase(typed, args.index, args.derivation) + + +def _import(args: argparse.Namespace) -> int: + key = _key_to_import(args) + stored = save( + key, name=args.name, dir=args.dir, storage=args.storage, save_password=args.save_password + ) + _report(stored, args.json, _summary(stored, "Imported")) + _storage_notes(stored, args.save_password) + return EXIT_DONE + + +def _existing(args: argparse.Namespace) -> StoredAccount: + """Describe the selected account file, failing when there is none.""" + stored = info(name=args.name, dir=args.dir) + if stored is None: + path = resolve_location(args.name, args.dir).path + raise KeystoreError("ACCOUNT_NOT_FOUND", f"There is no account file at {path}.") + return stored + + +def _forget_saved(args: argparse.Namespace) -> None: + """Remove the saved password of the selected account file, if it has one.""" + existing = read_account_file(resolve_location(args.name, args.dir).path) + if existing is not None: + forget_saved_password(existing.file) + + +def _show(args: argparse.Namespace) -> int: + stored = _existing(args) + _report( + stored, + args.json, + f"name: {stored.name}\naddress: {stored.address}\nstorage: {stored.storage}\npath: {stored.path}", + ) + return EXIT_DONE + + +def _protect(args: argparse.Namespace) -> int: + if args.storage is None: + # Only the saved password goes; the account file stays as it is. + stored = _existing(args) + require_keychain("A saved password exists only in the macOS Keychain.") + _forget_saved(args) + _report( + stored, + args.json, + f"Removed the saved password of Aleo account {stored.name} ({stored.address}) from the Keychain.", + ) + return EXIT_DONE + stored = protect(storage=args.storage, name=args.name, dir=args.dir, save_password=args.save_password) + if args.forget_password and keychain_available(): + _forget_saved(args) + _report(stored, args.json, _summary(stored, "Stored")) + _storage_notes(stored, args.save_password) + return EXIT_DONE + + +def _export(args: argparse.Namespace) -> int: + _require_terminal("export", args.json) + stored = _existing(args) + answer = runtime.prompt_visible( + f"Show the private key of Aleo account {stored.name} ({stored.address}) on this terminal? [y/N] " + ) + if answer.strip().lower() not in ("y", "yes"): + runtime.notify("Not confirmed. The key was not shown.") + return EXIT_FAILED + _out(export_key(name=args.name, dir=args.dir)) + return EXIT_DONE + + +def _migrate(args: argparse.Namespace) -> int: + stored = migrate( + args.source, + name=args.name, + dir=args.dir, + storage=args.storage, + save_password=args.save_password, + remove_legacy_key=args.remove_legacy_key, + ) + _report(stored, args.json, _summary(stored, "Migrated")) + _storage_notes(stored, args.save_password) + if args.remove_legacy_key: + runtime.notify(f"The key was removed from {args.source}.") + else: + runtime.notify( + f"A plaintext copy of the key remains in {args.source}. " + "Run migrate again with --remove-legacy-key to strip it." + ) + return EXIT_DONE + + +_COMMANDS: Dict[str, Callable[[argparse.Namespace], int]] = { + "create": _create, + "import": _import, + "show": _show, + "protect": _protect, + "export": _export, + "migrate": _migrate, +} + + +def main(argv: Optional[List[str]] = None) -> int: + """Run one account command and report its outcome. + + Results go to standard output; notes, prompts and errors go to standard + error as ``: ``. With ``--json``, a result is one JSON + object with ``name``, ``address``, ``storage`` and ``path``, and an error + is ``{"error": {"code": ..., "message": ...}}`` on standard output. The + private key appears only in the output of ``export`` and of + ``create --storage none``, and never with ``--json``. + + Args: + argv: Command-line arguments; defaults to ``sys.argv[1:]``. + + Returns: + The exit status: 0 when done, 1 when the command failed, 2 when it + needs a person (``ACCOUNT_NOT_FOUND``, ``KEY_NOT_STORED``, + ``PASSWORD_REQUIRED`` or ``TERMINAL_REQUIRED``). + + Raises: + SystemExit: With status 64 for a usage error, after printing the + usage, and with status 0 after ``--help``. + """ + parser = _build_parser() + args = parser.parse_args(argv) + if args.command is None: + parser.error("a command is required: create, import, show, protect, export or migrate") + if args.command == "import" and args.key_file is not None and args.mnemonic_file is not None: + parser.error("--key-file and --mnemonic-file cannot be combined") + if args.command == "protect": + if args.storage is None and not args.forget_password: + parser.error("protect needs --storage, or --forget-password to only remove a saved password") + if args.save_password and args.forget_password: + parser.error("--save-password and --forget-password cannot be combined") + try: + return _COMMANDS[args.command](args) + except KeystoreError as error: + if args.json: + _out(json.dumps({"error": {"code": error.code, "message": str(error)}}, ensure_ascii=False)) + else: + runtime.notify(f"{error.code}: {error}") + return EXIT_NEEDS_PERSON if error.code in _NEEDS_PERSON else EXIT_FAILED + except OSError as error: + runtime.notify(f"aleo.keystore: {error}") + return EXIT_FAILED + + +__all__ = ["main"] diff --git a/sdk/python/aleo/keystore/_encrypted.py b/sdk/python/aleo/keystore/_encrypted.py new file mode 100644 index 0000000..fc12ec0 --- /dev/null +++ b/sdk/python/aleo/keystore/_encrypted.py @@ -0,0 +1,189 @@ +"""Key parsing and the password-encrypted form of a private key. + +A password is stretched with scrypt, and the result is the secret for the +SDK's own private-key ciphertext. The stretching is what slows down password +guessing; the ciphertext scheme alone does not. +""" +from __future__ import annotations + +import base64 +import hashlib +import os +import re +import unicodedata +from typing import Optional, Tuple, TypedDict + +# Private keys and their ciphertexts do not depend on the network, so the +# mainnet types serve accounts of either network. +from ..mainnet import PrivateKey, PrivateKeyCiphertext +from ._errors import KeystoreError + +# scrypt cost used for every new encrypted account file. +SCRYPT_N = 131072 +# scrypt block size. The only value a reader accepts. +SCRYPT_R = 8 +# scrypt parallelisation. The only value a reader accepts. +SCRYPT_P = 1 +# Smallest scrypt cost a reader accepts (2^14). +SCRYPT_MIN_N = 2**14 +# Largest scrypt cost a reader accepts (2^20), which bounds memory at 1 GiB. +SCRYPT_MAX_N = 2**20 +# Salt length for new files, and the shortest salt a reader accepts, in bytes. +SALT_BYTES = 16 + +# Length of the scrypt output, in bytes. +_SECRET_BYTES = 32 +# Memory allowed to scrypt at the default cost, in bytes (256 MiB). +_BASE_MAXMEM = 256 * 1024 * 1024 + +_LONE_SURROGATE = re.compile("[\ud800-\udfff]") + + +class KdfParams(TypedDict): + """scrypt parameters of an encrypted account file.""" + + N: int + r: int + p: int + salt: str + + +class EncryptedKey(TypedDict): + """The ``key`` object of an encrypted account file.""" + + type: str + kdf: str + kdfParams: KdfParams + ciphertext: str + + +def parse_key(private_key: object, origin: str) -> Tuple[str, str]: + """Parse an Aleo private key and derive its address. + + Args: + private_key: Candidate private key string. + origin: Where the string came from, named in the error message. + + Returns: + The key in its canonical text form and the address it derives. + + Raises: + KeystoreError: ``INVALID_KEY`` when the value is not a private key. + The message names the origin and never the value. + """ + parsed: Optional[Tuple[str, str]] = None + if isinstance(private_key, str): + try: + key = PrivateKey.from_string(private_key) + parsed = (str(key), str(key.address)) + except Exception: + parsed = None + if parsed is None: + # Raised outside the handler so nothing derived from the input can + # reach a log through the exception chain. + raise KeystoreError("INVALID_KEY", f"{origin} is not a valid Aleo private key.") + return parsed + + +def encode_password(password: str) -> bytes: + """Return a password's Unicode NFKC form encoded as UTF-8. + + A lone surrogate has no UTF-8 form; it becomes U+FFFD, as in other UTF-8 + encoders, instead of failing. + """ + normalized = unicodedata.normalize("NFKC", password) + return _LONE_SURROGATE.sub("\ufffd", normalized).encode("utf-8") + + +def normalize_password(password: object) -> bytes: + """Convert a password to the bytes that are stretched and stored. + + Returns: + The password normalised to Unicode NFKC and encoded as UTF-8. + + Raises: + KeystoreError: ``PASSWORD_REQUIRED`` when the password is empty. + """ + encoded = encode_password(password) if isinstance(password, str) else b"" + if not encoded: + raise KeystoreError("PASSWORD_REQUIRED", "The password must not be empty.") + return encoded + + +def derive_secret(password: bytes, salt: bytes, n: int) -> str: + """Stretch a password into the secret that encrypts the private key. + + Runs scrypt with ``r = 8``, ``p = 1`` and a 32-byte output. Takes about + 200 ms and 128 MiB at the default cost. + + Args: + password: Normalised password bytes from :func:`normalize_password`. + salt: Salt bytes. + n: scrypt cost, a power of two. + + Returns: + The 32-byte output as 64 lower-case hex characters. + """ + # scrypt needs 128 * N * r bytes plus a few kilobytes. 256 MiB covers the + # default cost; a file with a larger accepted cost gets what it needs, and + # the reader's upper bound on N keeps that at about 1 GiB. + maxmem = max(_BASE_MAXMEM, 128 * n * SCRYPT_R + 1024 * 1024) + derived = hashlib.scrypt( + password, salt=salt, n=n, r=SCRYPT_R, p=SCRYPT_P, maxmem=maxmem, dklen=_SECRET_BYTES + ) + return derived.hex() + + +def encrypt_key(private_key: str, password: bytes) -> EncryptedKey: + """Encrypt a private key under a password with a fresh random salt. + + Args: + private_key: Aleo private key in text form. + password: Normalised password bytes from :func:`normalize_password`. + + Returns: + The ``key`` object for an encrypted account file. + """ + salt = os.urandom(SALT_BYTES) + secret = derive_secret(password, salt, SCRYPT_N) + ciphertext = PrivateKeyCiphertext.encrypt_private_key(PrivateKey.from_string(private_key), secret) + return { + "type": "encrypted", + "kdf": "scrypt", + "kdfParams": { + "N": SCRYPT_N, + "r": SCRYPT_R, + "p": SCRYPT_P, + "salt": base64.b64encode(salt).decode("ascii"), + }, + "ciphertext": str(ciphertext), + } + + +def decrypt_key(key: EncryptedKey, address: str, password: bytes) -> str: + """Decrypt the private key of an encrypted account file. + + Args: + key: The file's ``key`` object, already checked against the format. + address: Address recorded in the file. + password: Normalised password bytes from :func:`normalize_password`. + + Returns: + The private key in text form. + + Raises: + KeystoreError: ``WRONG_PASSWORD`` when decryption fails or the + decrypted key derives an address other than the file's. + """ + params = key["kdfParams"] + secret = derive_secret(password, base64.b64decode(params["salt"]), params["N"]) + decrypted: Optional[Tuple[str, str]] = None + try: + opened = PrivateKeyCiphertext.from_string(key["ciphertext"]).decrypt_to_private_key(secret) + decrypted = (str(opened), str(opened.address)) + except Exception: + decrypted = None + # A decryption that succeeds still has to produce the recorded account. + if decrypted is None or decrypted[1] != address: + raise KeystoreError("WRONG_PASSWORD", f"The password does not unlock the account {address}.") + return decrypted[0] diff --git a/sdk/python/aleo/keystore/_errors.py b/sdk/python/aleo/keystore/_errors.py new file mode 100644 index 0000000..09eb271 --- /dev/null +++ b/sdk/python/aleo/keystore/_errors.py @@ -0,0 +1,77 @@ +"""The error type raised by account storage and recovery-phrase handling.""" +from __future__ import annotations + +from .._client_common import AleoError + + +class KeystoreError(AleoError): + """An account could not be stored, found, or unlocked. + + Branch on :attr:`code`, which is stable across releases and shared with + the other Aleo SDKs; the message is for people and may change. Messages + name addresses and file paths and never contain a private key, a recovery + phrase, or a password, so they are safe to log. + + A file system failure on the account file or its directory other than a + missing file, such as a denied permission, is not wrapped: it is raised as + the ``OSError`` the operating system reported. + + Codes + ----- + ``ACCOUNT_NOT_FOUND`` + No account file exists and no key was supplied another way. + ``KEY_NOT_STORED`` + The account file records only an address, and no key was supplied. + ``ACCOUNT_EXISTS`` + Saving would replace an account file that is already there. + ``ACCOUNT_BUSY`` + Another process is changing the account file, or changed it while + this operation was in progress. Nothing was changed; try again. + ``ADDRESS_MISMATCH`` + A key belongs to a different address than the one expected. + ``KEY_CONFLICT`` + Two environment variables supply different keys, or a legacy state + file holds two different keys. + ``EMPTY_KEY_SOURCE`` + A key variable or key file is set but holds no key. + ``INVALID_KEY`` + A private key string cannot be parsed. + ``INVALID_MNEMONIC`` + A recovery phrase has a wrong word, word count, or checksum. + ``INVALID_NAME`` + The account name is not lower-case letters, digits, ``_`` and ``-``. + ``INVALID_ACCOUNT_FILE`` + The account file is not valid JSON or breaks the file format. + ``UNSUPPORTED_VERSION`` + The account file was written in a newer format. + ``UNSUPPORTED_STORAGE`` + The storage type is unknown, or not allowed for this operation. + ``KEYCHAIN_UNAVAILABLE`` + Keychain storage was requested, or found, on a system other than macOS. + ``KEYCHAIN_ITEM_NOT_FOUND`` + The account file points at a Keychain entry that no longer exists. + ``KEYCHAIN_FAILED`` + The macOS ``security`` tool failed for another reason. + ``PASSWORD_REQUIRED`` + A password is needed and none was supplied. + ``WRONG_PASSWORD`` + The password did not unlock the key. + ``TERMINAL_REQUIRED`` + A command that shows a key was run without a terminal. + ``LEGACY_KEY_NOT_FOUND`` + The file given to ``migrate`` holds no key. + """ + + def __init__(self, code: str, message: str) -> None: + """Build the error for one failure. + + Args: + code: Stable identifier of the failure, one of the codes above. + message: Detail for a person. Must not contain a key, a recovery + phrase or a password. + """ + super().__init__(message) + self.code = code + + +__all__ = ["KeystoreError"] diff --git a/sdk/python/aleo/keystore/_file.py b/sdk/python/aleo/keystore/_file.py new file mode 100644 index 0000000..0a540db --- /dev/null +++ b/sdk/python/aleo/keystore/_file.py @@ -0,0 +1,522 @@ +"""The account file: where it lives, what it holds and how it is written. + +Every writer of the format produces the same bytes for the same account, and +every reader rejects a file that departs from it, so an account written by one +SDK or tool is read unchanged by the others. +""" +from __future__ import annotations + +import base64 +import binascii +import contextlib +import json +import os +import re +import stat +import time +from typing import Any, Dict, Generator, List, NamedTuple, NoReturn, Optional, Sequence, Tuple, Union, cast + +from ._encrypted import SALT_BYTES, SCRYPT_MAX_N, SCRYPT_MIN_N, SCRYPT_P, SCRYPT_R +from ._errors import KeystoreError +from ._keychain import KEY_SERVICE, is_key_entry_account +from ._runtime import runtime + +# Format version written to, and accepted from, an account file. +FILE_VERSION = 1 + +# Account names: lower case so they are distinct on case-insensitive disks. +_NAME_PATTERN = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}") + +# Standard base64 with padding, the only salt encoding accepted. +_BASE64_PATTERN = re.compile(r"(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?") + +# The four ways an account file can hold, or point at, the private key. +STORAGE_TYPES: Tuple[str, ...] = ("none", "plaintext", "keychain", "encrypted") + +# The parsed content of an account file: ``version``, ``address`` and ``key``. +AccountFile = Dict[str, Any] + + +class Location(NamedTuple): + """A resolved account file location. + + Attributes: + name: Account name. + dir: Absolute path of the accounts directory. + path: Absolute path of the account file, ``/.json``. + """ + + name: str + dir: str + path: str + + +class ExistingFile(NamedTuple): + """An account file as found on disk. + + Attributes: + file: The validated content. + data: The raw bytes, kept so the file can be put back unchanged. + """ + + file: AccountFile + data: bytes + + +def resolve_location( + name: Optional[str] = None, dir: Union[str, "os.PathLike[str]", None] = None +) -> Location: + """Resolve which account file a call refers to. + + The name comes from the argument, then ``ALEO_ACCOUNT``, then ``default``. + The directory comes from the argument, then ``ALEO_ACCOUNTS_DIR``, then + ``/.aleo/accounts``; a leading ``~`` expands to the home directory. + An empty variable or an empty ``dir`` counts as absent. Reads the + environment and does not touch the disk. + + Raises: + KeystoreError: ``INVALID_NAME`` when the name does not match + ``^[a-z0-9][a-z0-9_-]{0,63}$``. + """ + # Checked at run time as well: an untyped caller can pass anything. + chosen = cast(object, name if name is not None else (os.environ.get("ALEO_ACCOUNT") or "default")) + if not isinstance(chosen, str) or not _NAME_PATTERN.fullmatch(chosen): + raise KeystoreError( + "INVALID_NAME", + 'The account name must be 1 to 64 characters of a-z, 0-9, "_" or "-", ' + "starting with a letter or digit.", + ) + home = runtime.home() + directory = os.fspath(dir) if dir is not None else "" + directory = directory or os.environ.get("ALEO_ACCOUNTS_DIR") or os.path.join(home, ".aleo", "accounts") + # Only "~" and "~/..." expand; "~name" is left as an ordinary directory name. + if directory == "~": + directory = home + elif directory.startswith("~/") or (runtime.platform == "win32" and directory.startswith("~\\")): + directory = os.path.join(home, directory[2:]) + directory = os.path.abspath(directory) + return Location(chosen, directory, os.path.join(directory, f"{chosen}.json")) + + +def _integer(value: object) -> Optional[int]: + """Return a JSON number as an integer, or ``None`` when it is not one. + + A number written with a zero fraction, such as ``1.0``, is the integer it + equals, as in every JSON reader that has a single number type. + """ + if isinstance(value, bool): + return None + if isinstance(value, int): + return value + if isinstance(value, float) and value.is_integer(): + return int(value) + return None + + +def _reject_constant(_: str) -> NoReturn: + raise ValueError("not a JSON value") + + +def loads_strict(text: str) -> Any: + """Parse JSON text, refusing the ``NaN`` and ``Infinity`` extensions.""" + return json.loads(text, parse_constant=_reject_constant) + + +def parse_account_file(text: str, path: str) -> AccountFile: + """Parse and validate the text of an account file. + + Accepts exactly the fields of the format: no field may be missing and none + may be added. An unknown version or storage type is reported as such + before the remaining fields are examined, since a later format may carry + others. + + Args: + text: File content. + path: File path, named in error messages. + + Returns: + The validated content, with fields in the order of the format. + + Raises: + KeystoreError: ``INVALID_ACCOUNT_FILE``, ``UNSUPPORTED_VERSION`` or + ``UNSUPPORTED_STORAGE``. + """ + + def invalid(problem: str) -> KeystoreError: + return KeystoreError("INVALID_ACCOUNT_FILE", f"Account file {path} is not valid: {problem}.") + + def exact(found: Dict[str, Any], fields: Sequence[str], where: str) -> None: + # Requires an object to hold exactly the named fields. + for field in fields: + if field not in found: + raise invalid(f'{where} is missing "{field}"') + for field in found: + if field not in fields: + raise invalid(f'{where} has the unknown field "{field}"') + + def text_of(value: object, field: str) -> str: + if not isinstance(value, str): + raise invalid(f'"{field}" must be a string') + return value + + parsed: Any = None + is_json = True + try: + parsed = loads_strict(text) + except (ValueError, RecursionError): + is_json = False + if not is_json: + # The parser's message can quote the file, which may hold a key, so the + # error is raised without it. + raise invalid("it is not JSON") + if not isinstance(parsed, dict): + raise invalid("it does not hold a JSON object") + raw = cast(Dict[str, Any], parsed) + + version = _integer(raw.get("version")) + if version is None: + raise invalid('"version" must be an integer') + if version != FILE_VERSION: + raise KeystoreError( + "UNSUPPORTED_VERSION", + f"Account file {path} has version {version}; this reader supports version {FILE_VERSION}.", + ) + exact(raw, ["version", "address", "key"], "the file") + address = text_of(raw["address"], "address") + if not isinstance(raw["key"], dict): + raise invalid('"key" must be an object') + key = cast(Dict[str, Any], raw["key"]) + kind = text_of(key.get("type"), "key.type") + + if kind == "none": + exact(key, ["type"], '"key"') + return {"version": FILE_VERSION, "address": address, "key": {"type": kind}} + if kind == "plaintext": + exact(key, ["type", "privateKey"], '"key"') + private_key = text_of(key["privateKey"], "key.privateKey") + return {"version": FILE_VERSION, "address": address, "key": {"type": kind, "privateKey": private_key}} + if kind == "keychain": + exact(key, ["type", "service", "account"], '"key"') + service = text_of(key["service"], "key.service") + account = text_of(key["account"], "key.account") + # Pinned so a crafted file cannot direct the reader to an entry of + # another service or another address. + if service != KEY_SERVICE: + raise invalid(f'"key.service" must be "{KEY_SERVICE}"') + if not is_key_entry_account(account, address): + raise invalid('"key.account" must be "address" followed by "-" and 32 hex characters') + return { + "version": FILE_VERSION, + "address": address, + "key": {"type": kind, "service": service, "account": account}, + } + if kind == "encrypted": + exact(key, ["type", "kdf", "kdfParams", "ciphertext"], '"key"') + if key["kdf"] != "scrypt": + raise invalid('"key.kdf" must be "scrypt"') + if not isinstance(key["kdfParams"], dict): + raise invalid('"key.kdfParams" must be an object') + params = cast(Dict[str, Any], key["kdfParams"]) + exact(params, ["N", "r", "p", "salt"], '"key.kdfParams"') + cost = _integer(params["N"]) + # The upper bound stops a crafted file from demanding unbounded memory. + if cost is None or cost < SCRYPT_MIN_N or cost > SCRYPT_MAX_N or cost & (cost - 1) != 0: + raise invalid(f'"key.kdfParams.N" must be a power of two from {SCRYPT_MIN_N} to {SCRYPT_MAX_N}') + if _integer(params["r"]) != SCRYPT_R: + raise invalid(f'"key.kdfParams.r" must be {SCRYPT_R}') + if _integer(params["p"]) != SCRYPT_P: + raise invalid(f'"key.kdfParams.p" must be {SCRYPT_P}') + salt = text_of(params["salt"], "key.kdfParams.salt") + if not _BASE64_PATTERN.fullmatch(salt) or _decoded_length(salt) < SALT_BYTES: + raise invalid(f'"key.kdfParams.salt" must be base64 of at least {SALT_BYTES} bytes') + ciphertext = text_of(key["ciphertext"], "key.ciphertext") + return { + "version": FILE_VERSION, + "address": address, + "key": { + "type": kind, + "kdf": "scrypt", + "kdfParams": {"N": cost, "r": SCRYPT_R, "p": SCRYPT_P, "salt": salt}, + "ciphertext": ciphertext, + }, + } + raise KeystoreError( + "UNSUPPORTED_STORAGE", + f'Account file {path} uses the storage type "{kind}", which this reader does not support.', + ) + + +def _decoded_length(salt: str) -> int: + try: + return len(base64.b64decode(salt, validate=True)) + except (binascii.Error, ValueError): + return 0 + + +def serialize_account_file(file: AccountFile) -> str: + """Render an account file to its exact text. + + Fields appear in the fixed order of the format, with two-space + indentation, LF line endings and one trailing newline, so every writer of + the format produces the same bytes for the same account. + """ + key: Dict[str, Any] = file["key"] + kind: str = key["type"] + # Each variant is rebuilt field by field so the order never depends on how + # the caller assembled the mapping. + entry: Dict[str, Any] + if kind == "none": + entry = {"type": "none"} + elif kind == "plaintext": + entry = {"type": "plaintext", "privateKey": key["privateKey"]} + elif kind == "keychain": + entry = {"type": "keychain", "service": key["service"], "account": key["account"]} + else: + params: Dict[str, Any] = key["kdfParams"] + entry = { + "type": "encrypted", + "kdf": key["kdf"], + "kdfParams": {"N": params["N"], "r": params["r"], "p": params["p"], "salt": params["salt"]}, + "ciphertext": key["ciphertext"], + } + content = {"version": file["version"], "address": file["address"], "key": entry} + return json.dumps(content, indent=2, ensure_ascii=False) + "\n" + + +def read_account_file(path: str) -> Optional[ExistingFile]: + """Read and validate an account file. + + Tightens the file to owner-only access (mode 0600) when it is wider, + except on Windows, where file modes are not enforced. + + Returns: + The validated content and the raw bytes, or ``None`` when no file + exists at the path. + + Raises: + KeystoreError: The file breaks the format. + OSError: Any file system failure other than a missing file. + """ + try: + descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_BINARY", 0)) + except FileNotFoundError: + return None + # Windows has no fchmod and does not enforce these modes. + tighten = getattr(os, "fchmod", None) + with os.fdopen(descriptor, "rb") as handle: + if runtime.platform != "win32" and tighten is not None: + status = os.fstat(handle.fileno()) + # Only a regular file is re-moded: a directory in place of the + # file fails below and keeps its mode. + if stat.S_ISREG(status.st_mode) and stat.S_IMODE(status.st_mode) & ~0o600: + # Best effort: a file the user cannot re-mode is still readable. + try: + tighten(handle.fileno(), 0o600) + except OSError: + pass + data = handle.read() + text: Optional[str] + try: + text = data.decode("utf-8") + except UnicodeDecodeError: + text = None + if text is None: + raise KeystoreError( + "INVALID_ACCOUNT_FILE", f"Account file {path} is not valid: it is not UTF-8 text." + ) + return ExistingFile(parse_account_file(text, path), data) + + +def write_file_atomic(path: str, data: Union[str, bytes]) -> None: + """Replace a file's content through a temporary file and a rename. + + The temporary file is created in the same directory with mode 0600 before + any content is written, so the content is never readable by other users + and a reader never sees a partial file. + + Args: + path: Destination path. Its directory must exist. + data: Complete new content; text is written as UTF-8. + """ + payload = data.encode("utf-8") if isinstance(data, str) else data + temporary = os.path.join(os.path.dirname(path), f".{os.urandom(8).hex()}.tmp") + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0) + descriptor = os.open(temporary, flags, 0o600) + try: + with os.fdopen(descriptor, "wb") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + os.replace(temporary, path) + except BaseException: + try: + os.unlink(temporary) + except OSError: + pass + raise + + +def write_file_exclusive(path: str, data: Union[str, bytes]) -> None: + """Create a file that must not exist yet, through a temporary file and a hard link. + + A rename replaces whatever is at the destination; a hard link fails when a + file is already there. Two callers creating the same path at the same + moment therefore cannot both succeed, and neither can replace the other's + file. The temporary file is created in the same directory with mode 0600 + before any content is written, so a reader never sees a partial file. On a + file system without hard links the destination is created directly, still + refusing an existing file. + + Args: + path: Destination path. Its directory must exist. + data: Complete content; text is written as UTF-8. + + Raises: + FileExistsError: A file already exists at the path. Other file system + errors propagate unchanged. + """ + payload = data.encode("utf-8") if isinstance(data, str) else data + temporary = os.path.join(os.path.dirname(path), f".{os.urandom(8).hex()}.tmp") + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0) + descriptor = os.open(temporary, flags, 0o600) + try: + with os.fdopen(descriptor, "wb") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + try: + os.link(temporary, path) + except FileExistsError: + raise + except (OSError, NotImplementedError): + # No hard links here: create the destination itself, exclusively. + target = os.open(path, flags, 0o600) + with os.fdopen(target, "wb") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + finally: + try: + os.unlink(temporary) + except OSError: + pass + + +# How often a waiting caller looks at a held lock again, in seconds. +_LOCK_POLL_SECONDS = 0.05 + + +@contextlib.contextmanager +def account_lock(location: Location) -> Generator[None, None, None]: + """Hold the interprocess lock of one account file while changing it. + + Changing how an account file holds its key reads the file, writes a new + one, removes the old secret, and puts the old file back if a step fails. + Two processes doing that to one file at once could each undo the other's + work, and leave a file that points at a secret the other has removed. The + lock lets one of them through at a time. + + The lock is a file next to the account file, ``.json.lock``, + created exclusively and removed on exit. A caller that finds it held + waits, looking again at short intervals, and gives up after the runtime's + ``lock_wait_seconds``. + + A lock is never removed on another caller's behalf, however old it is: + deciding that a lock is abandoned and removing it cannot be done in one + step, so two waiting callers could both remove it and both go ahead. A + lock left by a process that was killed stays until a person removes it, + and the error says which file that is. + + Args: + location: The account file to lock. Its directory must exist. + + Raises: + KeystoreError: ``ACCOUNT_BUSY`` when the lock is still held after the + wait. + """ + path = f"{location.path}.lock" + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL + deadline = time.monotonic() + runtime.lock_wait_seconds + while True: + try: + os.close(os.open(path, flags, 0o600)) + break + except FileExistsError: + pending_delete = False + except PermissionError: + # Windows reports a file that is being deleted as a permission + # error. Anywhere else it is a real one. + if os.name != "nt": + raise + pending_delete = True + if time.monotonic() >= deadline: + # A permission error with no lock file behind it is a real one. + if pending_delete and not os.path.exists(path): + os.close(os.open(path, flags, 0o600)) + break + raise KeystoreError( + "ACCOUNT_BUSY", + f"Another process is changing account file {location.path}. Try again when it has " + f"finished. If no other process is using the account, remove {path}.", + ) from None + time.sleep(_LOCK_POLL_SECONDS) + try: + yield + finally: + try: + os.unlink(path) + except OSError: + pass + + +def write_account_file(location: Location, file: AccountFile, exclusive: bool = False) -> None: + """Write an account file, creating the accounts directory when needed. + + A directory created here gets mode 0700; missing parents get the default + mode, and an existing directory keeps its mode. The file is written with + mode 0600. It replaces any file already at the path, unless *exclusive* is + set. + + Args: + location: Resolved account location. + file: Account content. + exclusive: Whether the file must not exist yet. Used when storing a + new account, so that two callers storing different accounts under + one name cannot replace each other's file. + + Raises: + FileExistsError: *exclusive* is set and a file already exists at the + path. + """ + os.makedirs(os.path.dirname(location.dir), exist_ok=True) + try: + os.mkdir(location.dir, 0o700) + except FileExistsError: + pass + else: + # mkdir applies the umask; the directory is owner-only regardless of it. + if runtime.platform != "win32": + os.chmod(location.dir, 0o700) + text = serialize_account_file(file) + if exclusive: + write_file_exclusive(location.path, text) + else: + write_file_atomic(location.path, text) + + +__all__: List[str] = [ + "AccountFile", + "ExistingFile", + "FILE_VERSION", + "Location", + "STORAGE_TYPES", + "account_lock", + "loads_strict", + "parse_account_file", + "read_account_file", + "resolve_location", + "serialize_account_file", + "write_account_file", + "write_file_atomic", + "write_file_exclusive", +] diff --git a/sdk/python/aleo/keystore/_keychain.py b/sdk/python/aleo/keystore/_keychain.py new file mode 100644 index 0000000..16d4e18 --- /dev/null +++ b/sdk/python/aleo/keystore/_keychain.py @@ -0,0 +1,200 @@ +"""macOS Keychain access through the system ``security`` tool. + +Entries are generic passwords in the login keychain, one per address. A value +is written through the tool's standard input so that it never appears in the +process arguments. +""" +from __future__ import annotations + +import os +import re +from typing import Optional + +from ._errors import KeystoreError +from ._runtime import runtime + +# Keychain service holding private keys. The entry's account names one account +# file: the address followed by an identifier chosen when the file is written. +KEY_SERVICE = "aleo-account-key" + +# Length of the identifier in a key entry's account, in bytes. +_KEY_ENTRY_ID_BYTES = 16 +_KEY_ENTRY_ID = re.compile(r"[0-9a-f]{32}") + +# Keychain service holding saved passwords. The entry's account names one +# encrypted file: the address followed by the file's salt. +PASSWORD_SERVICE = "aleo-account-password" + +# Exit status ``security`` returns when the requested entry does not exist. +_ITEM_NOT_FOUND_STATUS = 44 + +# Text that can be placed on a ``security -i`` command line without quoting. +# Addresses, private keys and hex strings all satisfy it. +_UNQUOTED = re.compile(r"[A-Za-z0-9]+") + +# Account names as they may appear, unquoted, in an entry's label. +_LABEL_NAME = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}") + +# Entry accounts that can be placed on a ``security -i`` command line without +# quoting: an address, optionally followed by ``-`` and an identifier in hex. +_ENTRY_ACCOUNT = re.compile(r"[A-Za-z0-9]+(?:-[0-9a-f]+)?") + + +def new_key_entry_account(address: str) -> str: + """Name a new Keychain entry for the key of one account file. + + Every account file gets an entry of its own. Entries are never shared + between files that were stored separately, so writing, undoing or removing + one file's entry cannot affect another file that holds the same key. The + account file records the name, so the entry is found again after the file + is renamed or moved. + + Args: + address: Aleo address of the account. + + Returns: + The entry's account: the address, ``-``, and 16 random bytes in hex. + """ + return f"{address}-{os.urandom(_KEY_ENTRY_ID_BYTES).hex()}" + + +def is_key_entry_account(account: str, address: str) -> bool: + """Check that a key entry's account belongs to an address. + + Args: + account: The ``account`` recorded in an account file. + address: The address recorded in the same file. + + Returns: + True when the account is the address, ``-``, and 32 hex characters. + """ + prefix = f"{address}-" + return account.startswith(prefix) and _KEY_ENTRY_ID.fullmatch(account[len(prefix):]) is not None + + +def keychain_available() -> bool: + """Report whether the macOS Keychain exists on this system.""" + return runtime.platform == "darwin" + + +def require_keychain(detail: str) -> None: + """Stop an operation that needs the macOS Keychain on another system. + + Args: + detail: Sentence naming what needed the Keychain and what to do + instead. + + Raises: + KeystoreError: ``KEYCHAIN_UNAVAILABLE`` outside macOS. + """ + if not keychain_available(): + raise KeystoreError( + "KEYCHAIN_UNAVAILABLE", + f"The macOS Keychain is not available on this system. {detail}", + ) + + +def _failed(action: str, service: str, address: str, reason: str) -> KeystoreError: + """Build the error for a Keychain failure without echoing the tool's output.""" + return KeystoreError( + "KEYCHAIN_FAILED", + f"The security tool {reason} while {action} the Keychain entry {service} for {address}.", + ) + + +def _exit_reason(status: Optional[int]) -> str: + """Describe a non-zero or missing exit status of the ``security`` tool.""" + if status is None: + return "could not be started or did not finish within 15 seconds" + return f"exited with status {status}" + + +def read_keychain(service: str, address: str) -> Optional[str]: + """Read one generic password from the macOS login keychain. + + Returns: + The stored value, or ``None`` when the entry does not exist. + + Raises: + KeystoreError: ``KEYCHAIN_FAILED`` when the tool fails for any reason + other than a missing entry. + """ + status, stdout = runtime.security( + ["find-generic-password", "-s", service, "-a", address, "-w"], None + ) + if status == _ITEM_NOT_FOUND_STATUS: + return None + if status != 0: + raise _failed("reading", service, address, _exit_reason(status)) + # The tool prints the value followed by one line ending. + if stdout.endswith("\r\n"): + return stdout[:-2] + if stdout.endswith("\n"): + return stdout[:-1] + return stdout + + +def write_keychain(service: str, address: str, value: str, name: str) -> bool: + """Create or replace one generic password in the macOS login keychain. + + The command travels on the tool's standard input, so the value never + appears in the process arguments. The entry is read back afterwards to + confirm it holds the value. + + The entry is found by service and account. Its label, the name Keychain + Access shows, is ``:``, so entries of several accounts can + be told apart; the label takes no part in finding the entry. + + The existing entry is read first, and one that already holds the value is + left as it is. + + Args: + service: Keychain service name. + address: The entry's account: an Aleo address followed by ``-`` and + an identifier in hex. + value: Secret to store. Must be ASCII letters and digits only. + name: Account name, shown in the entry's label. + + Returns: + True when this call created the entry; False when an entry already + existed. Only an entry a caller created is the caller's to remove if + a later step fails. + + Raises: + KeystoreError: ``KEYCHAIN_FAILED`` when the tool fails or the entry + does not hold the value afterwards. + """ + # Nothing here is quoted, so anything able to split or extend the command + # line is refused before the tool runs. + if ( + not _ENTRY_ACCOUNT.fullmatch(address) + or not _UNQUOTED.fullmatch(value) + or not _LABEL_NAME.fullmatch(name) + ): + raise _failed( + "writing", service, address, "was not run, because the value cannot be passed unquoted," + ) + existing = read_keychain(service, address) + if existing == value: + return False + command = f"add-generic-password -U -s {service} -a {address} -l {service}:{name} -w {value}\n" + status, _ = runtime.security(["-i"], command) + if status != 0: + raise _failed("writing", service, address, _exit_reason(status)) + if read_keychain(service, address) != value: + raise _failed("verifying", service, address, "did not store the value") + return existing is None + + +def delete_keychain(service: str, address: str) -> None: + """Delete one generic password from the macOS login keychain. + + An entry that is already absent counts as deleted. + + Raises: + KeystoreError: ``KEYCHAIN_FAILED`` when the tool fails for any reason + other than a missing entry. + """ + status, _ = runtime.security(["delete-generic-password", "-s", service, "-a", address], None) + if status != 0 and status != _ITEM_NOT_FOUND_STATUS: + raise _failed("deleting", service, address, _exit_reason(status)) diff --git a/sdk/python/aleo/keystore/_mnemonic.py b/sdk/python/aleo/keystore/_mnemonic.py new file mode 100644 index 0000000..7d6fa2d --- /dev/null +++ b/sdk/python/aleo/keystore/_mnemonic.py @@ -0,0 +1,171 @@ +"""Recovery-phrase checking and Aleo key derivation. + +Network-neutral: the result is the 32-byte seed of a private key, which either +network module turns into a key with ``PrivateKey.from_seed_unchecked``. +""" +from __future__ import annotations + +import hashlib +import hmac +import secrets +import unicodedata +from functools import lru_cache +from pathlib import Path +from typing import cast + +from ._errors import KeystoreError + +_WORD_COUNTS = (12, 15, 18, 21, 24) +_HARDENED = 0x80000000 +_MASTER_TAG = b"bls12_377 seed" +# Coin type of the account path m/44'/'/'/0'. +_COIN_TYPES = {"standard": 683, "legacy": 0} + + +@lru_cache(maxsize=1) +def _word_list() -> tuple[str, ...]: + """The BIP-39 English word list, in order: position is the 11-bit value.""" + text = Path(__file__).with_name("_bip39_english.txt").read_text(encoding="utf-8") + words = tuple(text.split()) + if len(words) != 2048: + raise RuntimeError("The bundled BIP-39 word list is damaged.") + return words + + +@lru_cache(maxsize=1) +def _word_indexes() -> dict[str, int]: + """The BIP-39 English word list, mapping each word to its 11-bit value.""" + return {word: index for index, word in enumerate(_word_list())} + + +def entropy_to_phrase(entropy: bytes) -> str: + """Encode random bytes as a BIP-39 English recovery phrase. + + Appends the checksum (the leading bits of the SHA-256 of *entropy*, one + bit per 32 bits of entropy) and writes the result as 11-bit words, so 16 + bytes give 12 words and 32 bytes give 24. + + Args: + entropy: 16, 20, 24, 28 or 32 random bytes. + + Returns: + The phrase, as lower-case words separated by single spaces. + + Raises: + ValueError: If *entropy* has another length. + """ + if len(entropy) not in (16, 20, 24, 28, 32): + raise ValueError(f"entropy must be 16, 20, 24, 28 or 32 bytes, not {len(entropy)}") + checksum_length = len(entropy) // 4 + checksum = hashlib.sha256(entropy).digest()[0] >> (8 - checksum_length) + bits = (int.from_bytes(entropy, "big") << checksum_length) | checksum + count = (len(entropy) * 8 + checksum_length) // 11 + words = _word_list() + return " ".join(words[(bits >> (11 * (count - 1 - position))) & 0x7FF] for position in range(count)) + + +def generate_phrase(strength: int = 128) -> str: + """Create a new BIP-39 English recovery phrase from the system's random source. + + Args: + strength: Bits of randomness: 128 gives 12 words, 256 gives 24. + + Returns: + The phrase. It is the root secret of every account derived from it. + + Raises: + ValueError: If *strength* is neither 128 nor 256. + """ + # A float such as 128.0 compares equal to 128, so the type is checked too. + if isinstance(strength, bool) or not isinstance(cast(object, strength), int) or strength not in (128, 256): + raise ValueError(f"strength must be 128 (12 words) or 256 (24 words), not {strength!r}") + return entropy_to_phrase(secrets.token_bytes(strength // 8)) + + +def clean_phrase(text: str) -> str: + """Tidy a typed or pasted recovery phrase before it is checked. + + Returns: + The phrase with surrounding white space removed, runs of white space + collapsed to single spaces, and letters lower-cased. + """ + return " ".join(text.split()).lower() + + +def _invalid(reason: str) -> KeystoreError: + return KeystoreError("INVALID_MNEMONIC", f"Not a valid recovery phrase: {reason}.") + + +def check_phrase(phrase: str) -> None: + """Raise ``INVALID_MNEMONIC`` unless *phrase* is a valid BIP-39 phrase. + + The phrase is taken as written: lower-case English words separated by + single spaces. The message never repeats a word of the phrase. + """ + words = phrase.split(" ") + if len(words) not in _WORD_COUNTS: + raise _invalid( + "expected 12, 15, 18, 21 or 24 words separated by single spaces, " + f"found {len(words)}" + ) + indexes = _word_indexes() + bits = 0 + for position, word in enumerate(words, start=1): + value = indexes.get(word) + if value is None: + raise _invalid(f"word {position} is not in the BIP-39 English word list") + bits = (bits << 11) | value + checksum_length = len(words) // 3 + entropy = (bits >> checksum_length).to_bytes(len(words) * 4 // 3, "big") + expected = hashlib.sha256(entropy).digest()[0] >> (8 - checksum_length) + if bits & ((1 << checksum_length) - 1) != expected: + raise _invalid("the checksum does not match, so a word is wrong or out of order") + + +def derive_seed(mnemonic: str, *, index: int = 0, derivation: str = "standard") -> bytes: + """Return the private-key seed for one account of a recovery phrase. + + Follows the derivation wallets use for Aleo: the BIP-39 seed of the phrase + (no passphrase), a master node tagged for the BLS12-377 curve, then the + hardened path ``m/44'/683'/'/0'``, or ``m/44'/0'/'/0'`` for + ``"legacy"``. + + Args: + mnemonic: BIP-39 English phrase: lower-case words separated by single + spaces. + index: Account index, from 0 through 2**31 - 1. + derivation: ``"standard"`` or ``"legacy"``. + + Returns: + The 32 bytes that ``PrivateKey.from_seed_unchecked`` turns into the + account's private key. + + Raises: + KeystoreError: ``INVALID_MNEMONIC`` when the phrase fails the word + list, the word count or the checksum. + ValueError: *index* or *derivation* is out of range. + """ + coin_type = _COIN_TYPES.get(derivation) + if coin_type is None: + raise ValueError( + f"derivation must be 'standard' or 'legacy', not {derivation!r}" + ) + # Checked at run time as well: an untyped caller can pass anything. + position = cast(object, index) + if not isinstance(position, int) or isinstance(position, bool) or not 0 <= position < _HARDENED: + raise ValueError( + f"index must be a whole number from 0 to 2**31 - 1, not {index!r}" + ) + + words = cast(object, mnemonic) + if not isinstance(words, str): + raise _invalid("it is not text") + phrase = unicodedata.normalize("NFKD", words) + check_phrase(phrase) + seed = hashlib.pbkdf2_hmac("sha512", phrase.encode("utf-8"), b"mnemonic", 2048, 64) + + node = hmac.new(_MASTER_TAG, seed, hashlib.sha512).digest() + for segment in (44, coin_type, position, 0): + data = b"\x00" + node[:32] + (segment + _HARDENED).to_bytes(4, "big") + node = hmac.new(node[32:], data, hashlib.sha512).digest() + return node[:32] diff --git a/sdk/python/aleo/keystore/_password.py b/sdk/python/aleo/keystore/_password.py new file mode 100644 index 0000000..1a1682c --- /dev/null +++ b/sdk/python/aleo/keystore/_password.py @@ -0,0 +1,234 @@ +"""Where the password of an encrypted account comes from. + +Reading an account tries the supplied password, the ``ALEO_ACCOUNT_PASSWORD`` +variable, a password saved in the macOS Keychain, and then a hidden prompt. +Setting a password never reads the Keychain and asks twice at the prompt. +""" +from __future__ import annotations + +import base64 +import os +import re +from typing import Any, Mapping, NamedTuple, Optional, Sequence, Tuple, Union + +from ._encrypted import EncryptedKey, decrypt_key, encode_password, normalize_password +from ._errors import KeystoreError +from ._keychain import PASSWORD_SERVICE, delete_keychain, keychain_available, read_keychain +from ._runtime import runtime + +# Variable that supplies the password of an encrypted account. +PASSWORD_VARIABLE = "ALEO_ACCOUNT_PASSWORD" + +# Number of tries a person gets at a prompt before the call fails. +_PROMPT_ATTEMPTS = 3 + +_SAVED_PASSWORD = re.compile(r"(?:[0-9a-f]{2})+") + + +class PasswordSubject(NamedTuple): + """Identifies the account a password belongs to. + + Attributes: + name: Account name, shown in prompts. + address: Aleo address, shown in prompts and used as the Keychain + account of a saved password. + """ + + name: str + address: str + + +def _password_from_environment() -> Optional[str]: + """Read the password variable, treating an empty value as unset.""" + return os.environ.get(PASSWORD_VARIABLE) or None + + +def password_entry_account(address: str, salt: str) -> str: + """Name the Keychain entry that holds the saved password of one encrypted file. + + The entry belongs to a file, not to an address: two encrypted files can + hold the same account under different passwords, and each needs its own + saved password. The salt is unique to each encryption, so it identifies + the file, and it changes whenever the file is encrypted again. + + Args: + address: Aleo address of the account. + salt: The file's scrypt salt, as standard base64. + + Returns: + The entry's account: the address, ``-``, and the salt in hex. + """ + return f"{address}-{base64.b64decode(salt).hex()}" + + +def saved_password_entry(file: Mapping[str, Any]) -> Optional[str]: + """Name the saved-password entry of a parsed account file. + + Returns: + The entry's account in the Keychain, or None when the file is not + encrypted, since only an encrypted file has a saved password. + """ + key = file["key"] + if key["type"] != "encrypted": + return None + return password_entry_account(file["address"], key["kdfParams"]["salt"]) + + +def forget_saved_password(file: Mapping[str, Any]) -> None: + """Remove the saved password of a parsed account file from the Keychain. + + Does nothing for a file that is not encrypted. An entry that is already + absent counts as removed. + """ + entry = saved_password_entry(file) + if entry is not None: + delete_keychain(PASSWORD_SERVICE, entry) + + +def password_to_keychain_value(password: bytes) -> str: + """Convert normalised password bytes to the form stored in the Keychain. + + Returns: + The bytes as lower-case hex, which needs no quoting. + """ + return password.hex() + + +def unlock( + subject: PasswordSubject, + key: EncryptedKey, + password: Union[str, bytes, None] = None, + prompt: bool = True, +) -> Tuple[str, bytes]: + """Find the password of an encrypted account and decrypt its key. + + Sources, in order: the explicit password, ``ALEO_ACCOUNT_PASSWORD``, a + password saved in the macOS Keychain, then a hidden prompt when a terminal + is attached. The first source that supplies a password decides: a wrong + one is an error and the later sources are not tried. Only the prompt + retries, up to three times. The Keychain lookup runs the ``security`` tool + on macOS. + + Args: + subject: Account the password belongs to. + key: The account file's encrypted ``key`` object. + password: Explicit password, as text or as already normalised bytes. + prompt: Whether a prompt may be shown when a terminal is attached. + + Returns: + The private key and the normalised password that unlocked it. + + Raises: + KeystoreError: ``WRONG_PASSWORD`` when the password does not decrypt + the key, ``PASSWORD_REQUIRED`` when no source supplies one, and + ``KEYCHAIN_FAILED`` when the saved-password lookup fails. + """ + + def attempt(candidate: bytes) -> Tuple[str, bytes]: + return decrypt_key(key, subject.address, candidate), candidate + + if password is not None: + return attempt(password if isinstance(password, bytes) else normalize_password(password)) + from_environment = _password_from_environment() + if from_environment is not None: + return attempt(normalize_password(from_environment)) + + if keychain_available(): + saved = read_keychain(PASSWORD_SERVICE, password_entry_account(subject.address, key["kdfParams"]["salt"])) + if saved is not None: + # A saved password is the hex of its bytes; anything else was not + # written by the keystore. + if not _SAVED_PASSWORD.fullmatch(saved): + raise KeystoreError( + "KEYCHAIN_FAILED", + f"The Keychain entry {PASSWORD_SERVICE} for {subject.address} does not hold a saved password.", + ) + return attempt(bytes.fromhex(saved)) + + if prompt and runtime.terminal_attached(): + for _ in range(_PROMPT_ATTEMPTS): + typed = runtime.prompt_hidden( + f"Password for Aleo account {subject.name} ({subject.address}): " + ) + try: + return attempt(normalize_password(typed)) + except KeystoreError as error: + if error.code == "PASSWORD_REQUIRED": + runtime.notify("The password must not be empty.") + elif error.code == "WRONG_PASSWORD": + runtime.notify("Wrong password.") + else: + raise + raise KeystoreError( + "WRONG_PASSWORD", + f"No password entered in {_PROMPT_ATTEMPTS} attempts unlocks the account {subject.address}.", + ) + + raise KeystoreError( + "PASSWORD_REQUIRED", + f"The account {subject.address} is encrypted and no password is available. " + f"Set {PASSWORD_VARIABLE}, pass a password, or run with a terminal attached.", + ) + + +def choose_new_password( + subject: PasswordSubject, + explicit: Sequence[Optional[str]], + environment: bool, + prompt: bool, +) -> bytes: + """Obtain the password a new encrypted account file is written with. + + Sources, in order: the explicit candidates, ``ALEO_ACCOUNT_PASSWORD`` when + allowed, then a hidden prompt that asks twice when a terminal is attached. + The prompt repeats up to three times while the entries are empty or + differ. + + Args: + subject: Account the password will protect. + explicit: Passwords supplied by the caller, most specific first; the + first one that is not ``None`` is used. + environment: Whether ``ALEO_ACCOUNT_PASSWORD`` may supply the + password. False when replacing an existing password, where the + variable holds the old one. + prompt: Whether a prompt may be shown when a terminal is attached. + + Returns: + The normalised password bytes. + + Raises: + KeystoreError: ``PASSWORD_REQUIRED`` when a supplied password is + empty, when no source supplies one, or when the prompt is used up. + """ + for candidate in explicit: + if candidate is not None: + return normalize_password(candidate) + if environment: + from_environment = _password_from_environment() + if from_environment is not None: + return normalize_password(from_environment) + + if prompt and runtime.terminal_attached(): + for _ in range(_PROMPT_ATTEMPTS): + first = runtime.prompt_hidden( + f"New password for Aleo account {subject.name} ({subject.address}): " + ) + second = runtime.prompt_hidden("Repeat the new password: ") + password = encode_password(first) + if not password: + runtime.notify("The password must not be empty.") + continue + # Compared after normalisation, which is the form that is stretched. + if password == encode_password(second): + return password + runtime.notify("The passwords do not match.") + raise KeystoreError( + "PASSWORD_REQUIRED", + f"No password was set for the account {subject.address} in {_PROMPT_ATTEMPTS} attempts.", + ) + + raise KeystoreError( + "PASSWORD_REQUIRED", + f"Encrypting the account {subject.address} needs a password. Pass one" + f"{f', set {PASSWORD_VARIABLE},' if environment else ''} or run with a terminal attached.", + ) diff --git a/sdk/python/aleo/keystore/_runtime.py b/sdk/python/aleo/keystore/_runtime.py new file mode 100644 index 0000000..6226c0b --- /dev/null +++ b/sdk/python/aleo/keystore/_runtime.py @@ -0,0 +1,154 @@ +"""Process-level facilities the keystore depends on. + +Everything that reaches outside the process goes through the single +:data:`runtime` object: the operating system name, the home directory, the +macOS ``security`` tool and the terminal. Tests replace its attributes so +that nothing reads a developer's own accounts, Keychain or keyboard. Internal: +not part of the public API. +""" +from __future__ import annotations + +import getpass +import os +import subprocess +import sys +from typing import Callable, Optional, Sequence, Tuple + +from ._errors import KeystoreError + +# Full path of the macOS Keychain tool. Never resolved through ``PATH``. +SECURITY_PATH = "/usr/bin/security" + +# Upper bound on one ``security`` invocation, in seconds. +SECURITY_TIMEOUT_SECONDS = 15 + +# Exit status and standard output of one ``security`` invocation. The status is +# ``None`` when the tool could not be started, was killed by a signal or +# exceeded the time limit. The output holds the secret for a read. +SecurityResult = Tuple[Optional[int], str] + +# Runs the ``security`` tool with the given arguments and optional text for +# its standard input, which keeps a secret out of the process arguments. +SecurityRunner = Callable[[Sequence[str], Optional[str]], SecurityResult] + + +def _run_security(args: Sequence[str], stdin: Optional[str] = None) -> SecurityResult: + """Run ``/usr/bin/security`` as a child process with a 15 second limit. + + A tool that hangs (for example one waiting on a Keychain dialog) is killed + and reported as a failure instead of blocking the caller. + """ + try: + completed = subprocess.run( + [SECURITY_PATH, *args], + input=stdin if stdin is not None else "", + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + encoding="utf-8", + timeout=SECURITY_TIMEOUT_SECONDS, + check=False, + ) + except (OSError, subprocess.SubprocessError, UnicodeError): + return None, "" + # A negative return code means the tool was killed by a signal. + status = completed.returncode if completed.returncode >= 0 else None + return status, completed.stdout + + +def _home() -> str: + """Return the current user's home directory.""" + return os.path.expanduser("~") + + +def _stream_is_terminal(stream: object) -> bool: + isatty = getattr(stream, "isatty", None) + try: + return bool(isatty()) if callable(isatty) else False + except ValueError: # the stream is closed + return False + + +def _terminal_attached() -> bool: + """Report whether a person can answer a prompt. + + True when standard input and standard error are both terminals. + """ + return _stream_is_terminal(sys.stdin) and _stream_is_terminal(sys.stderr) + + +def _output_is_terminal() -> bool: + """Report whether standard output is a terminal, not a pipe or a file.""" + return _stream_is_terminal(sys.stdout) + + +def _prompt_hidden(message: str) -> str: + """Ask for one line on the terminal without echoing it. + + The prompt text goes to the terminal, never to standard output. + + Raises: + KeystoreError: ``PASSWORD_REQUIRED`` when the prompt is cancelled with + Ctrl-C or the input ends before a line is submitted. + """ + cancelled = False + typed = "" + try: + typed = getpass.getpass(message, stream=sys.stderr) + except (EOFError, KeyboardInterrupt): + cancelled = True + if cancelled: + raise KeystoreError("PASSWORD_REQUIRED", "The password prompt was cancelled.") + return typed + + +def _prompt_visible(message: str) -> str: + """Ask for one line on the terminal, echoing what is typed. + + Returns: + The line without its line ending; empty when the input has ended. + """ + sys.stderr.write(message) + sys.stderr.flush() + return sys.stdin.readline().rstrip("\r\n") + + +def _notify(message: str) -> None: + """Write one line to the terminal through standard error.""" + sys.stderr.write(f"{message}\n") + sys.stderr.flush() + + +class KeystoreRuntime: + """The facilities the keystore uses, gathered so tests can replace them. + + Attributes: + platform: Operating system identifier, as ``sys.platform``: + ``"darwin"`` for macOS, ``"win32"`` for Windows. + home: Returns the current user's home directory. + security: Runs the macOS ``security`` tool. + terminal_attached: Reports whether a person can answer a prompt. + output_is_terminal: Reports whether standard output is a terminal. + prompt_hidden: Asks for one line on the terminal without echo. + prompt_visible: Asks for one line on the terminal with echo, for a + confirmation that is not secret. + notify: Writes one line to the terminal, never to standard output. + lock_wait_seconds: How long a caller waits for another process to + finish changing an account file before giving up. + """ + + def __init__(self) -> None: + self.platform: str = sys.platform + self.home: Callable[[], str] = _home + self.security: SecurityRunner = _run_security + self.terminal_attached: Callable[[], bool] = _terminal_attached + self.output_is_terminal: Callable[[], bool] = _output_is_terminal + self.prompt_hidden: Callable[[str], str] = _prompt_hidden + self.prompt_visible: Callable[[str], str] = _prompt_visible + self.notify: Callable[[str], None] = _notify + self.lock_wait_seconds: float = 10.0 + + +# The live facilities: the real platform, Keychain tool and terminal. +runtime = KeystoreRuntime() + +__all__ = ["KeystoreRuntime", "SecurityResult", "SecurityRunner", "runtime"] diff --git a/sdk/python/aleo/keystore/_sources.py b/sdk/python/aleo/keystore/_sources.py new file mode 100644 index 0000000..b3120dd --- /dev/null +++ b/sdk/python/aleo/keystore/_sources.py @@ -0,0 +1,124 @@ +"""The private key a caller supplies through the environment. + +Two variables hold a key and two name a text file that holds one. Every +variable that is set must supply a key, and all of them must supply the same +one, so a stale variable is reported instead of silently selecting another +account. +""" +from __future__ import annotations + +import errno +import os +from typing import List, NamedTuple, Optional, Union + +from ._encrypted import parse_key +from ._errors import KeystoreError + +PathLike = Union[str, "os.PathLike[str]"] + +# Variables holding a private key, in order of precedence. +KEY_VARIABLES = ("ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY") + +# Variables naming a text file that holds only a private key, in order of +# precedence. +KEY_FILE_VARIABLES = ("ALEO_PRIVATE_KEY_FILE", "SHIELD_SWAP_PRIVATE_KEY_FILE") + +# The characters removed from both ends of a key variable or key file: the +# white space and line terminators of ECMAScript's ``String.prototype.trim``, +# so every SDK accepts the same files, including one that starts with a +# byte-order mark. +TRIMMED = ( + "\t\n\x0b\x0c\r \xa0\u1680" + "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a" + "\u2028\u2029\u202f\u205f\u3000\ufeff" +) + + +class Resolved(NamedTuple): + """A key found by the lookup, with the source and a phrase naming it.""" + + private_key: str + address: str + source: str + origin: str + + +def error_code(error: OSError) -> str: + """Name a file system failure by its symbolic code, such as ``ENOENT``.""" + return errno.errorcode.get(error.errno or 0, "unknown error") + + +def key_from_environment() -> Optional[Resolved]: + """Collect the private key supplied through the environment. + + Reads the two key variables and the files named by the two key-file + variables. Every variable that is set must supply a key, and all of them + must supply the same one. + + Returns: + The key with the highest precedence, or ``None`` when none of the + variables is set. + + Raises: + KeystoreError: ``EMPTY_KEY_SOURCE`` when a variable is set but empty + or its file is empty or unreadable, ``INVALID_KEY`` when a value + is not a key, and ``KEY_CONFLICT`` when two variables supply + different keys. + """ + found: List[Resolved] = [] + + for variable in KEY_VARIABLES: + value = os.environ.get(variable) + if value is None: + continue + text = value.strip(TRIMMED) + if not text: + raise KeystoreError("EMPTY_KEY_SOURCE", f"{variable} is set but empty.") + found.append(Resolved(*parse_key(text, variable), "env", variable)) + + for variable in KEY_FILE_VARIABLES: + path = os.environ.get(variable) + if path is None: + continue + if not path.strip(TRIMMED): + raise KeystoreError("EMPTY_KEY_SOURCE", f"{variable} is set but empty.") + origin = f"The key file {path} named by {variable}" + text = read_key_text(path, origin) + found.append(Resolved(*parse_key(text, origin), "env-file", origin)) + + # The first entry is the one with the highest precedence. The others only + # have to agree with it. + if not found: + return None + first = found[0] + for other in found[1:]: + if other.address != first.address: + raise KeystoreError( + "KEY_CONFLICT", + f"{first.origin} and {other.origin} hold different keys " + f"({first.address} and {other.address}). Unset one of them.", + ) + return first + + +def read_key_text(path: PathLike, origin: str) -> str: + """Read a text file that holds only a key or a recovery phrase. + + Returns: + The content with surrounding white space removed. + + Raises: + KeystoreError: ``EMPTY_KEY_SOURCE`` when the file cannot be read or + holds nothing. + """ + try: + with open(path, "rb") as handle: + content = handle.read().decode("utf-8", errors="replace") + except OSError as error: + raise KeystoreError( + "EMPTY_KEY_SOURCE", f"{origin} could not be read ({error_code(error)})." + ) from error + text = content.strip(TRIMMED) + if not text: + raise KeystoreError("EMPTY_KEY_SOURCE", f"{origin} is empty.") + return text diff --git a/sdk/python/tests/fixtures/keystore-vectors/encrypted-js.json b/sdk/python/tests/fixtures/keystore-vectors/encrypted-js.json new file mode 100644 index 0000000..266ed5a --- /dev/null +++ b/sdk/python/tests/fixtures/keystore-vectors/encrypted-js.json @@ -0,0 +1,15 @@ +{ + "version": 1, + "address": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px", + "key": { + "type": "encrypted", + "kdf": "scrypt", + "kdfParams": { + "N": 131072, + "r": 8, + "p": 1, + "salt": "AAECAwQFBgcICQoLDA0ODw==" + }, + "ciphertext": "ciphertext1qvqrhyq4tlv7dzhceqy7aaa59rszrmd6za3mlnx6as3sjkfzvhezypyzyd5h5r4lc723zcxn6ra42ylss86vyl2mm6ekqfgur27xnvwuqek7c45h0k5qfxwwuat762ec8ve3z6p3llkp5wzp07a3knp8z5ts5ayp534" + } +} diff --git a/sdk/python/tests/fixtures/keystore-vectors/encrypted-py.json b/sdk/python/tests/fixtures/keystore-vectors/encrypted-py.json new file mode 100644 index 0000000..84d35a2 --- /dev/null +++ b/sdk/python/tests/fixtures/keystore-vectors/encrypted-py.json @@ -0,0 +1,15 @@ +{ + "version": 1, + "address": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px", + "key": { + "type": "encrypted", + "kdf": "scrypt", + "kdfParams": { + "N": 131072, + "r": 8, + "p": 1, + "salt": "EBESExQVFhcYGRobHB0eHw==" + }, + "ciphertext": "ciphertext1qvqwxkte5nq42f38st3js82tu2q6qes4te7cxzldtx0yc9wt8t0fqrt4jyztwytkscvp0lqnheu5cp29mdmr3p0m8z6lq9fr63wgxk03ql488cdttp9lvdtg9cqeayeywehnhnkxs3l2x6cpveuze8k5sxes25luj9u" + } +} diff --git a/sdk/python/tests/fixtures/keystore-vectors/keychain.json b/sdk/python/tests/fixtures/keystore-vectors/keychain.json new file mode 100644 index 0000000..3d83998 --- /dev/null +++ b/sdk/python/tests/fixtures/keystore-vectors/keychain.json @@ -0,0 +1,9 @@ +{ + "version": 1, + "address": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px", + "key": { + "type": "keychain", + "service": "aleo-account-key", + "account": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px-000102030405060708090a0b0c0d0e0f" + } +} diff --git a/sdk/python/tests/fixtures/keystore-vectors/none.json b/sdk/python/tests/fixtures/keystore-vectors/none.json new file mode 100644 index 0000000..f4fa48f --- /dev/null +++ b/sdk/python/tests/fixtures/keystore-vectors/none.json @@ -0,0 +1,7 @@ +{ + "version": 1, + "address": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px", + "key": { + "type": "none" + } +} diff --git a/sdk/python/tests/fixtures/keystore-vectors/plaintext.json b/sdk/python/tests/fixtures/keystore-vectors/plaintext.json new file mode 100644 index 0000000..488f339 --- /dev/null +++ b/sdk/python/tests/fixtures/keystore-vectors/plaintext.json @@ -0,0 +1,8 @@ +{ + "version": 1, + "address": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px", + "key": { + "type": "plaintext", + "privateKey": "APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH" + } +} diff --git a/sdk/python/tests/fixtures/keystore-vectors/vectors.json b/sdk/python/tests/fixtures/keystore-vectors/vectors.json new file mode 100644 index 0000000..98b4c3f --- /dev/null +++ b/sdk/python/tests/fixtures/keystore-vectors/vectors.json @@ -0,0 +1,68 @@ +{ + "note": "Test-only material. The key is the public devnode key and the phrase is the public BIP-39 test phrase. Never fund these accounts.", + "account": { + "privateKey": "APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH", + "address": "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px" + }, + "encrypted": { + "password": "correct horse battery staple", + "wrongPassword": "incorrect horse battery staple", + "files": [ + "encrypted-js.json", + "encrypted-py.json" + ] + }, + "scrypt": [ + { + "password": "correct horse battery staple", + "salt": "AAECAwQFBgcICQoLDA0ODw==", + "N": 131072, + "r": 8, + "p": 1, + "secret": "1b2946da71f41179e83b99dc33842d15741b87c4121c8c7f3781c1df864fb58b" + }, + { + "password": "pass word é", + "normalized": "pass word é", + "salt": "//79/Pv6+fj39vX08/Lx8A==", + "N": 131072, + "r": 8, + "p": 1, + "secret": "42da99cf9de95506e79f98cb509ad456dbd5980a2ad11a42aa49b81d041cd472" + } + ], + "keychain": { + "keyService": "aleo-account-key", + "passwordService": "aleo-account-password", + "passwordValue": "636f727265637420686f727365206261747465727920737461706c65" + }, + "mnemonic": { + "phrase": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about", + "accounts": [ + { + "derivation": "standard", + "index": 0, + "privateKey": "APrivateKey1zkpEFmDijZZjb1miqaCefgLBWPyM6F661hG4NFRtZGnGQkH", + "address": "aleo1lkjecukweu9uhw9jch8ycvhzlmpnw0lv87kwe4lx8a9ev0228sfq6hf9tv" + }, + { + "derivation": "standard", + "index": 1, + "privateKey": "APrivateKey1zkp93UuhVFh4anH1CgNDEjMKf22FskFwsXuomuFMtsutvZV", + "address": "aleo1vvc44uhv7hw3wvdt8n99wmqvqpv33zxt9vrs0jlq008uzwwyuuxs4ecws0" + }, + { + "derivation": "legacy", + "index": 0, + "privateKey": "APrivateKey1zkp9Bn8hja3Kg5ZHEwDH2jPRGzVgM6zyUMrg8Wno92YsrMw", + "address": "aleo14pfq40wgltv8wrhsxqe5tlme4pkp448rfejfvqhd4yj0qycs7c9s2xkcwv" + }, + { + "derivation": "legacy", + "index": 1, + "privateKey": "APrivateKey1zkpAMYZgho8zNE3TTXWsD6BhuZwzWrpUUm6Tnjz1D5vexWY", + "address": "aleo1cghrqlh8ec4tat4hy5xrdvyzx86tt07wd29aq0cfwl4uzr5zsu9qsrv7w3" + } + ] + } +} diff --git a/sdk/python/tests/keystore_helpers.py b/sdk/python/tests/keystore_helpers.py new file mode 100644 index 0000000..3771385 --- /dev/null +++ b/sdk/python/tests/keystore_helpers.py @@ -0,0 +1,224 @@ +"""Shared scaffolding for the account keystore tests. + +Every test that uses the ``sandbox`` fixture runs in a fresh temporary +directory, with the key, account and password variables cleared and the home +directory, the Keychain tool and the terminal replaced, so nothing reads or +writes the developer's own accounts or Keychain. +""" +from __future__ import annotations + +import json +import os +import re +import stat +from pathlib import Path +from types import SimpleNamespace +from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple + +import pytest + +from aleo.keystore import KeystoreError +from aleo.keystore._runtime import KeystoreRuntime, runtime +from aleo.mainnet import Account + +VECTORS_DIR = Path(__file__).parent / "fixtures" / "keystore-vectors" +VECTORS: Dict[str, Any] = json.loads((VECTORS_DIR / "vectors.json").read_text(encoding="utf-8")) + +# The public sample account. Never funded. +SAMPLE = SimpleNamespace( + address=VECTORS["account"]["address"], private_key=VECTORS["account"]["privateKey"] +) + +# Variables a developer's shell could leak into a test. +VARIABLES = ( + "ALEO_PRIVATE_KEY", + "ALEO_PRIVATE_KEY_FILE", + "ALEO_ACCOUNT", + "ALEO_ACCOUNTS_DIR", + "ALEO_ACCOUNT_PASSWORD", + "SHIELD_SWAP_PRIVATE_KEY", + "SHIELD_SWAP_PRIVATE_KEY_FILE", +) + +# Test-only passwords. Never used for a funded account. +PASSWORD = "correct horse battery staple" +OTHER_PASSWORD = "another test password" + +POSIX = os.name != "nt" + +SecurityResult = Tuple[Optional[int], str] + + +class FakeSecurity: + """An in-memory stand-in for the macOS ``security`` tool.""" + + def __init__(self) -> None: + self.entries: Dict[str, str] = {} + # The label each entry was last written with. + self.labels: Dict[str, str] = {} + self.calls: List[Dict[str, Any]] = [] + self._override: Optional[Callable[[Sequence[str]], Optional[SecurityResult]]] = None + + def force(self, override: Optional[Callable[[Sequence[str]], Optional[SecurityResult]]]) -> None: + """Force the outcome of matching invocations.""" + self._override = override + + def run(self, args: Sequence[str], stdin: Optional[str] = None) -> SecurityResult: + args = list(args) + self.calls.append({"args": args, "stdin": stdin}) + forced = self._override(args) if self._override is not None else None + if forced is not None: + return forced + if args == ["-i"]: + match = re.fullmatch(r"add-generic-password -U -s (\S+) -a (\S+) -l (\S+) -w (\S+)\n", stdin or "") + if match is None: + return 1, "" + self.entries[f"{match.group(1)} {match.group(2)}"] = match.group(4) + self.labels[f"{match.group(1)} {match.group(2)}"] = match.group(3) + return 0, "" + if len(args) == 6 and args[0] == "find-generic-password" and args[1] == "-s" and args[3] == "-a" and args[5] == "-w": + value = self.entries.get(f"{args[2]} {args[4]}") + return (44, "") if value is None else (0, f"{value}\n") + if len(args) == 5 and args[0] == "delete-generic-password" and args[1] == "-s" and args[3] == "-a": + if self.entries.pop(f"{args[2]} {args[4]}", None) is None: + return 44, "" + return 0, 'keychain: "login.keychain-db"\n' + return 1, "" + + +class Sandbox: + """The replaced surroundings of one test. + + Attributes: + root: Temporary directory of the test. + home: Stand-in home directory, inside ``root``. + dir: Accounts directory the test passes explicitly. Not created. + security: The in-memory Keychain tool. + notes: Lines the keystore wrote to the terminal. + prompts: Prompt texts shown, hidden and visible, in order. + answers: Lines the stand-in person types, consumed in order. + terminal: Whether a person can answer a prompt. + output_terminal: Whether standard output is a terminal. + real: The untouched facilities, for the opt-in real-Keychain test. + real_home: The ``HOME`` the test started with, which the real + ``security`` tool needs to find the login keychain. + """ + + def __init__(self, root: Path, real: KeystoreRuntime) -> None: + self.root = root + self.home = root / "home" + self.dir = root / "accounts" + self.security = FakeSecurity() + self.notes: List[str] = [] + self.prompts: List[str] = [] + self.answers: List[str] = [] + self.terminal = False + self.output_terminal = False + self.real = real + self.real_home = os.environ.get("HOME") + + def answer(self, message: str) -> str: + self.prompts.append(message) + if not self.answers: + raise AssertionError("unexpected prompt") + return self.answers.pop(0) + + def put(self, name: str, content: Any) -> Path: + """Write a crafted account file into the test accounts directory.""" + self.dir.mkdir(parents=True, exist_ok=True) + path = self.dir / f"{name}.json" + text = content if isinstance(content, str) else json.dumps(content, indent=2) + "\n" + path.write_bytes(text.encode("utf-8")) + path.chmod(0o600) + return path + + def copy_vectors(self) -> None: + """Copy the shared sample files into the test accounts directory.""" + self.dir.mkdir(parents=True, exist_ok=True) + for source in VECTORS_DIR.iterdir(): + target = self.dir / source.name + target.write_bytes(source.read_bytes()) + target.chmod(0o600) + + +@pytest.fixture +def sandbox(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Sandbox: + for name in VARIABLES: + monkeypatch.delenv(name, raising=False) + real = KeystoreRuntime() + for attribute in vars(real): + setattr(real, attribute, getattr(runtime, attribute)) + box = Sandbox(tmp_path, real) + box.home.mkdir() + # The home directory is replaced twice over: in the keystore's own lookup + # and in the environment any other code would consult. + monkeypatch.setenv("HOME", str(box.home)) + monkeypatch.setenv("USERPROFILE", str(box.home)) + monkeypatch.setattr(runtime, "platform", "darwin") + monkeypatch.setattr(runtime, "home", lambda: str(box.home)) + monkeypatch.setattr(runtime, "security", box.security.run) + monkeypatch.setattr(runtime, "terminal_attached", lambda: box.terminal) + monkeypatch.setattr(runtime, "output_is_terminal", lambda: box.output_terminal) + monkeypatch.setattr(runtime, "prompt_hidden", box.answer) + monkeypatch.setattr(runtime, "prompt_visible", box.answer) + monkeypatch.setattr(runtime, "notify", box.notes.append) + return box + + +def key_entry_account(path: Any) -> str: + """The Keychain account of the key entry that one Keychain account file points at.""" + return json.loads(Path(path).read_text(encoding="utf-8"))["key"]["account"] + + +def key_entry(path: Any) -> str: + """The stand-in Keychain's key for the key entry of one Keychain account file.""" + return f"aleo-account-key {key_entry_account(path)}" + + +def saved_password_account(path: Any) -> str: + """The Keychain account of the saved password that belongs to one encrypted account file.""" + from aleo.keystore._password import password_entry_account + + file = json.loads(Path(path).read_text(encoding="utf-8")) + return password_entry_account(file["address"], file["key"]["kdfParams"]["salt"]) + + +def saved_password_entry(path: Any) -> str: + """The stand-in Keychain's key for the saved password of one encrypted account file.""" + return f"aleo-account-password {saved_password_account(path)}" + + +def new_account() -> SimpleNamespace: + """Generate a random account as an address and private-key pair of strings.""" + account = Account.random() + return SimpleNamespace(address=str(account.address), private_key=str(account.private_key)) + + +def failure(call: Callable[[], Any]) -> KeystoreError: + """Return the keystore error a call fails with.""" + try: + call() + except KeystoreError as error: + return error + raise AssertionError("expected the call to fail") + + +def code_of(call: Callable[[], Any]) -> str: + """Return the error code a call fails with.""" + return failure(call).code + + +def check_secret(actual: object, expected: object) -> None: + """Compare two secrets without putting either into an assertion message.""" + if not isinstance(actual, str) or actual != expected: + raise AssertionError("the secret values differ") + + +def absent(text: str, secret: str) -> None: + """Assert a secret does not occur in some text, without printing either.""" + if secret in text: + raise AssertionError("the text contains a secret") + + +def mode(path: Any) -> int: + return stat.S_IMODE(os.stat(path).st_mode) diff --git a/sdk/python/tests/test_facade_mnemonic.py b/sdk/python/tests/test_facade_mnemonic.py new file mode 100644 index 0000000..e01863d --- /dev/null +++ b/sdk/python/tests/test_facade_mnemonic.py @@ -0,0 +1,265 @@ +"""Tests for ``aleo.account.from_mnemonic``: accounts from a recovery phrase. + +The expected keys and addresses come from the shared keystore sample files, +which the other Aleo SDKs derive from the same phrase. All tests are local. +""" +from __future__ import annotations + +import hashlib +import json +from pathlib import Path +from typing import Any, Dict + +import pytest + +import aleo.keystore +from aleo import Aleo, AsyncAleo, HTTPProvider +from aleo.keystore import KeystoreError +from aleo.keystore._mnemonic import check_phrase, clean_phrase, derive_seed, entropy_to_phrase, generate_phrase + +from keystore_helpers import VECTORS, check_secret + +BASE = "https://api.provable.com/v2" +PHRASE: str = VECTORS["mnemonic"]["phrase"] +ACCOUNTS = VECTORS["mnemonic"]["accounts"] + +# The published BIP-39 test phrase for 32 bytes of zero entropy. +PHRASE_24 = " ".join(["abandon"] * 23 + ["art"]) + +# SHA-256 of the BIP-39 English word list as published with the standard. +WORD_LIST_SHA256 = "2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda" + + +def make_client(network: str = "mainnet") -> Aleo: + return Aleo(HTTPProvider(BASE, network=network)) + + +def invalid(call: Any) -> KeystoreError: + with pytest.raises(KeystoreError) as raised: + call() + assert raised.value.code == "INVALID_MNEMONIC" + return raised.value + + +def test_the_sample_files_hold_both_derivations_at_two_indexes() -> None: + assert len(ACCOUNTS) == 4 + assert sorted((entry["derivation"], entry["index"]) for entry in ACCOUNTS) == [ + ("legacy", 0), + ("legacy", 1), + ("standard", 0), + ("standard", 1), + ] + + +@pytest.mark.parametrize("network", ["mainnet", "testnet"]) +@pytest.mark.parametrize("expected", ACCOUNTS, ids=lambda entry: f"{entry['derivation']}-{entry['index']}") +def test_derives_every_sample_account(network: str, expected: Dict[str, Any]) -> None: + client = make_client(network) + account = client.account.from_mnemonic(PHRASE, index=expected["index"], derivation=expected["derivation"]) + assert str(account.address) == expected["address"] + check_secret(str(account.private_key), expected["privateKey"]) + # The result is an ordinary account of the client's network. + signature = client.account.sign(b"hello aleo", account) + assert client.account.verify(str(account.address), b"hello aleo", signature) + + +def test_defaults_to_the_first_account_on_the_standard_path() -> None: + first = next(entry for entry in ACCOUNTS if entry["derivation"] == "standard" and entry["index"] == 0) + assert str(make_client().account.from_mnemonic(PHRASE).address) == first["address"] + + +def test_index_and_derivation_are_keyword_only() -> None: + with pytest.raises(TypeError): + make_client().account.from_mnemonic(PHRASE, 1) # type: ignore[misc] + + +def test_does_not_change_the_default_account() -> None: + client = make_client() + client.account.from_mnemonic(PHRASE) + assert client.default_account is None + + +def test_is_available_on_the_async_client() -> None: + first = next(entry for entry in ACCOUNTS if entry["derivation"] == "standard" and entry["index"] == 0) + client = AsyncAleo(HTTPProvider(BASE, network="testnet")) + assert str(client.account.from_mnemonic(PHRASE).address) == first["address"] + + +def test_derives_from_a_24_word_phrase_and_a_high_index() -> None: + client = make_client() + first = client.account.from_mnemonic(PHRASE_24) + again = client.account.from_mnemonic(PHRASE_24) + assert str(first.address) == str(again.address) + assert str(first.address) != str(client.account.from_mnemonic(PHRASE).address) + last = client.account.from_mnemonic(PHRASE_24, index=2**31 - 1) + assert str(last.address) != str(first.address) + + +def test_follows_the_published_derivation_steps() -> None: + """An independent walk through the derivation gives the same seed.""" + import hmac + + seed = hashlib.pbkdf2_hmac("sha512", PHRASE.encode("utf-8"), b"mnemonic", 2048, 64) + node = hmac.new(b"bls12_377 seed", seed, hashlib.sha512).digest() + for segment in (44, 683, 1, 0): + data = b"\x00" + node[:32] + (segment + 2**31).to_bytes(4, "big") + node = hmac.new(node[32:], data, hashlib.sha512).digest() + assert derive_seed(PHRASE, index=1) == node[:32] + assert len(derive_seed(PHRASE, derivation="legacy")) == 32 + + +@pytest.mark.parametrize( + "phrase", + [ + pytest.param(" ".join(PHRASE.split()[:-1] + ["abandon"]), id="a wrong checksum"), + pytest.param(" ".join(PHRASE.split()[:-1]), id="eleven words"), + pytest.param(PHRASE + " abandon", id="thirteen words"), + pytest.param(" ".join(PHRASE.split()[:-1] + ["zzzzzz"]), id="a word outside the list"), + pytest.param(PHRASE.upper(), id="upper case"), + pytest.param(PHRASE.replace(" ", " ", 1), id="two spaces"), + pytest.param(" " + PHRASE, id="a leading space"), + pytest.param(PHRASE + "\n", id="a trailing line ending"), + pytest.param(PHRASE.replace(" ", "\t"), id="tabs"), + pytest.param("", id="nothing"), + ], +) +def test_rejects_an_invalid_phrase_without_repeating_it(phrase: str) -> None: + error = invalid(lambda: make_client().account.from_mnemonic(phrase)) + assert isinstance(error, aleo.AleoError) + assert "abandon" not in str(error) + assert "zzzzzz" not in str(error) + assert "ABANDON" not in str(error) + + +@pytest.mark.parametrize("phrase", [None, 7, b"abandon", ["abandon"] * 12]) +def test_rejects_a_phrase_that_is_not_text(phrase: Any) -> None: + invalid(lambda: make_client().account.from_mnemonic(phrase)) + + +@pytest.mark.parametrize("index", [-1, 2**31, True, 1.5, "0", None]) +def test_rejects_an_index_out_of_range(index: Any) -> None: + with pytest.raises(ValueError): + make_client().account.from_mnemonic(PHRASE, index=index) + + +@pytest.mark.parametrize("derivation", ["bip44", "", "Standard", None]) +def test_rejects_an_unknown_derivation(derivation: Any) -> None: + with pytest.raises(ValueError): + make_client().account.from_mnemonic(PHRASE, derivation=derivation) + + +def test_accepts_every_standard_phrase_length() -> None: + # The published all-zero-entropy phrases: "abandon" repeated, then the + # one word that completes the checksum. + for count, last in ((12, "about"), (15, "address"), (18, "agent"), (21, "admit"), (24, "art")): + check_phrase(" ".join(["abandon"] * (count - 1) + [last])) + + +def test_tidies_a_pasted_phrase() -> None: + assert clean_phrase(" Abandon\tABOUT \n art ") == "abandon about art" + + +def test_ships_the_bip39_english_word_list_beside_the_module() -> None: + path = Path(aleo.keystore.__file__).with_name("_bip39_english.txt") + data = path.read_bytes() + assert hashlib.sha256(data).hexdigest() == WORD_LIST_SHA256 + words = data.decode("ascii").split() + assert len(words) == 2048 + assert words[0] == "abandon" and words[-1] == "zoo" + assert words == sorted(words) + + +def test_sample_files_are_unmodified_json() -> None: + """The mnemonic vectors parse and name the phrase they were derived from.""" + path = Path(__file__).parent / "fixtures" / "keystore-vectors" / "vectors.json" + assert json.loads(path.read_text(encoding="utf-8"))["mnemonic"]["phrase"] == PHRASE + + +# --------------------------------------------------------------------------- +# Creating a new phrase +# --------------------------------------------------------------------------- + +# Published BIP-39 English test vectors: entropy (hex) and the phrase it encodes. +BIP39_VECTORS = [ + ("00" * 16, "abandon " * 11 + "about"), + ("7f" * 16, "legal winner thank year wave sausage worth useful legal winner thank yellow"), + ("80" * 16, "letter advice cage absurd amount doctor acoustic avoid letter advice cage above"), + ("ff" * 16, "zoo " * 11 + "wrong"), + ("00" * 32, "abandon " * 23 + "art"), + ("ff" * 32, "zoo " * 23 + "vote"), +] + + +@pytest.mark.parametrize("entropy, phrase", BIP39_VECTORS) +def test_encodes_the_published_bip39_vectors(entropy: str, phrase: str) -> None: + assert entropy_to_phrase(bytes.fromhex(entropy)) == phrase + check_phrase(phrase) + + +def test_encodes_the_sample_phrase() -> None: + assert entropy_to_phrase(bytes(16)) == VECTORS["mnemonic"]["phrase"] + + +@pytest.mark.parametrize("length", [0, 15, 17, 33, 64]) +def test_rejects_entropy_of_another_length(length: int) -> None: + with pytest.raises(ValueError): + entropy_to_phrase(bytes(length)) + + +@pytest.mark.parametrize("strength, words", [(128, 12), (256, 24)]) +def test_generates_a_valid_phrase_of_each_strength(strength: int, words: int) -> None: + aleo_client = Aleo(HTTPProvider("http://127.0.0.1:1")) + phrase = aleo_client.account.generate_mnemonic(strength) + assert len(phrase.split(" ")) == words + assert phrase == clean_phrase(phrase) + check_phrase(phrase) + + +def test_generates_twelve_words_by_default_and_a_new_phrase_each_time() -> None: + aleo_client = Aleo(HTTPProvider("http://127.0.0.1:1")) + phrases = {aleo_client.account.generate_mnemonic() for _ in range(8)} + assert len(phrases) == 8 + assert all(len(phrase.split(" ")) == 12 for phrase in phrases) + assert len(generate_phrase().split(" ")) == 12 + + +@pytest.mark.parametrize("strength", [0, 127, 160, 192, 224, 512, True, "128", None, 128.0]) +def test_rejects_another_strength(strength: Any) -> None: + aleo_client = Aleo(HTTPProvider("http://127.0.0.1:1")) + with pytest.raises(ValueError): + aleo_client.account.generate_mnemonic(strength) + with pytest.raises(ValueError): + aleo_client.account.create_with_mnemonic(strength=strength) + + +@pytest.mark.parametrize("network", ["testnet", "mainnet"]) +def test_creates_an_account_with_its_phrase(network: str) -> None: + aleo_client = Aleo(HTTPProvider("http://127.0.0.1:1", network=network)) + phrase, account = aleo_client.account.create_with_mnemonic() + assert len(phrase.split(" ")) == 12 + check_phrase(phrase) + again = aleo_client.account.from_mnemonic(phrase) + assert str(again.address) == str(account.address) + check_secret(str(again.private_key), str(account.private_key)) + + +def test_creates_at_an_index_and_derivation_with_a_longer_phrase() -> None: + aleo_client = Aleo(HTTPProvider("http://127.0.0.1:1")) + phrase, account = aleo_client.account.create_with_mnemonic(strength=256, index=3, derivation="legacy") + assert len(phrase.split(" ")) == 24 + assert str(account.address) == str(aleo_client.account.from_mnemonic(phrase, index=3, derivation="legacy").address) + assert str(account.address) != str(aleo_client.account.from_mnemonic(phrase).address) + + +def test_creating_with_a_phrase_takes_keywords_only_and_leaves_the_default_account() -> None: + aleo_client = Aleo(HTTPProvider("http://127.0.0.1:1")) + with pytest.raises(TypeError): + aleo_client.account.create_with_mnemonic(256) # type: ignore[misc] + aleo_client.account.create_with_mnemonic() + assert aleo_client.default_account is None + + +def test_creating_with_a_phrase_is_available_on_the_async_client() -> None: + client = AsyncAleo(HTTPProvider("http://127.0.0.1:1")) + phrase, account = client.account.create_with_mnemonic() + assert str(client.account.from_mnemonic(phrase).address) == str(account.address) diff --git a/sdk/python/tests/test_keystore.py b/sdk/python/tests/test_keystore.py new file mode 100644 index 0000000..8432e86 --- /dev/null +++ b/sdk/python/tests/test_keystore.py @@ -0,0 +1,2383 @@ +"""Tests for the account keystore (``aleo.keystore``). + +Covers the account file bytes, the lookup order, the password sources, the +Keychain commands and the storage changes. Every test runs in a temporary +directory with the environment, the home directory, the Keychain tool and the +terminal replaced (see ``keystore_helpers``). One opt-in test at the end uses +the real macOS Keychain with the public sample account only. +""" +from __future__ import annotations + +import base64 +import getpass +import json +import os +import re +import time +import sys +import unicodedata +from dataclasses import FrozenInstanceError +from pathlib import Path +from typing import Any, Callable, Dict, List, Optional, Sequence + +import pytest + +import aleo +from aleo import keystore +from aleo.keystore import KeystoreError, LoadedAccount, StoredAccount +from aleo.keystore import _runtime as runtime_module +from aleo.keystore._encrypted import derive_secret, normalize_password +from aleo.keystore._file import parse_account_file, serialize_account_file +from aleo.keystore._keychain import KEY_SERVICE, PASSWORD_SERVICE, delete_keychain, read_keychain +from aleo.keystore._password import password_to_keychain_value +from aleo.keystore._runtime import runtime +from aleo.mainnet import Account, PrivateKey, PrivateKeyCiphertext + +from keystore_helpers import ( # noqa: F401 (sandbox is a fixture) + OTHER_PASSWORD, + PASSWORD, + POSIX, + SAMPLE, + Sandbox, + VECTORS, + VECTORS_DIR, + absent, + check_secret, + code_of, + failure, + key_entry, + key_entry_account, + mode, + new_account, + sandbox, + saved_password_account, + saved_password_entry, +) + +pytestmark = pytest.mark.usefixtures("sandbox") + +posix_only = pytest.mark.skipif(not POSIX, reason="file modes are not enforced on Windows") + + +def read_json(path: Any) -> Any: + return json.loads(Path(path).read_text(encoding="utf-8")) + + +# --------------------------------------------------------------------------- +# Shared sample files +# --------------------------------------------------------------------------- + + +def test_reads_every_sample_account_file(sandbox: Sandbox) -> None: + sandbox.copy_vectors() + expected = { + "none": "none", + "plaintext": "plaintext", + "keychain": "keychain", + "encrypted-js": "encrypted", + "encrypted-py": "encrypted", + } + files = sorted(path.name for path in VECTORS_DIR.iterdir() if path.name != "vectors.json") + assert files == sorted(f"{name}.json" for name in expected) + for name, storage in expected.items(): + assert keystore.info(dir=sandbox.dir, name=name) == StoredAccount( + name=name, path=sandbox.dir / f"{name}.json", address=SAMPLE.address, storage=storage + ) + + +def test_renders_every_sample_account_file_byte_for_byte() -> None: + """Parsing a sample and rendering it again gives the same bytes, encrypted ones included.""" + for path in VECTORS_DIR.iterdir(): + if path.name == "vectors.json": + continue + data = path.read_bytes() + assert not data.startswith(b"\xef\xbb\xbf") and b"\r" not in data and data.endswith(b"}\n") + parsed = parse_account_file(data.decode("utf-8"), str(path)) + assert serialize_account_file(parsed).encode("utf-8") == data, path.name + + +@pytest.mark.parametrize("storage", ["none", "plaintext"]) +def test_writes_the_sample_byte_for_byte(sandbox: Sandbox, storage: str) -> None: + stored = keystore.save(SAMPLE.private_key, dir=sandbox.dir, name=storage, storage=storage) + assert stored == StoredAccount( + name=storage, path=sandbox.dir / f"{storage}.json", address=SAMPLE.address, storage=storage + ) + assert stored.path.read_bytes() == (VECTORS_DIR / f"{storage}.json").read_bytes() + + +def test_writes_the_keychain_sample_byte_for_byte_apart_from_the_entry_name_it_chooses(sandbox: Sandbox) -> None: + stored = keystore.save(SAMPLE.private_key, dir=sandbox.dir, name="keychain", storage="keychain") + sample = (VECTORS_DIR / "keychain.json").read_text(encoding="utf-8") + # Each file names an entry of its own: the address, "-", and 16 random bytes in hex. + chosen = key_entry_account(stored.path) + assert re.fullmatch(f"{SAMPLE.address}-[0-9a-f]{{32}}", chosen) + written = stored.path.read_text(encoding="utf-8") + assert written.replace(chosen, key_entry_account(VECTORS_DIR / "keychain.json")) == sample + # Two files for one account never choose the same entry. + again = keystore.save(SAMPLE.private_key, dir=sandbox.dir, name="again", storage="keychain") + assert key_entry_account(again.path) != chosen + + +def test_returns_the_sample_key_from_the_plaintext_and_keychain_samples(sandbox: Sandbox) -> None: + sandbox.copy_vectors() + sandbox.security.entries[key_entry(sandbox.dir / "keychain.json")] = SAMPLE.private_key + for name in ("plaintext", "keychain"): + loaded = keystore.load(dir=sandbox.dir, name=name) + assert loaded.source == "account-file" + assert loaded.address == SAMPLE.address + check_secret(loaded.private_key, SAMPLE.private_key) + assert code_of(lambda: keystore.load(dir=sandbox.dir, name="none")) == "KEY_NOT_STORED" + + +@pytest.mark.parametrize("file", VECTORS["encrypted"]["files"]) +def test_decrypts_the_sample_and_rejects_the_wrong_password(sandbox: Sandbox, file: str) -> None: + sandbox.copy_vectors() + name = re.sub(r"\.json$", "", file) + password = VECTORS["encrypted"]["password"] + wrong = VECTORS["encrypted"]["wrongPassword"] + check_secret(keystore.export(dir=sandbox.dir, name=name, password=password, prompt=False), SAMPLE.private_key) + + loaded = keystore.load(dir=sandbox.dir, name=name, password=password, prompt=False) + assert loaded.address == SAMPLE.address + check_secret(loaded.private_key, SAMPLE.private_key) + assert loaded.stored is not None and loaded.stored.storage == "encrypted" + + assert code_of(lambda: keystore.export(dir=sandbox.dir, name=name, password=wrong, prompt=False)) == "WRONG_PASSWORD" + assert code_of(lambda: keystore.load(dir=sandbox.dir, name=name, password=wrong, prompt=False)) == "WRONG_PASSWORD" + + +def test_sample_files_name_both_encrypted_samples() -> None: + assert VECTORS["encrypted"]["files"] == ["encrypted-js.json", "encrypted-py.json"] + + +def test_reproduces_both_scrypt_vectors_including_the_nfkc_one() -> None: + assert len(VECTORS["scrypt"]) == 2 + for vector in VECTORS["scrypt"]: + assert [vector["N"], vector["r"], vector["p"]] == [131072, 8, 1] + secret = derive_secret(normalize_password(vector["password"]), base64.b64decode(vector["salt"]), vector["N"]) + assert secret == vector["secret"] + nfkc = VECTORS["scrypt"][1] + assert nfkc["password"] != nfkc["normalized"] + assert unicodedata.normalize("NFKC", nfkc["password"]) == nfkc["normalized"] + assert normalize_password(nfkc["password"]) == nfkc["normalized"].encode("utf-8") + + +def test_uses_the_sample_keychain_service_names_and_password_encoding() -> None: + assert KEY_SERVICE == VECTORS["keychain"]["keyService"] + assert PASSWORD_SERVICE == VECTORS["keychain"]["passwordService"] + encoded = password_to_keychain_value(normalize_password(VECTORS["encrypted"]["password"])) + assert encoded == VECTORS["keychain"]["passwordValue"] + + +# --------------------------------------------------------------------------- +# Public surface +# --------------------------------------------------------------------------- + + +def test_exports_exactly_the_keystore_names() -> None: + assert sorted(keystore.__all__) == sorted( + ["KeystoreError", "LoadedAccount", "Storage", "StoredAccount", "export", "info", "load", "migrate", "protect", "save"] + ) + assert aleo.keystore is keystore + # A module of the package, not something bound to a network client. + assert not hasattr(aleo.Aleo, "keystore") + + +def test_reports_failures_as_keystore_error_with_a_stable_code(sandbox: Sandbox) -> None: + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert isinstance(error, KeystoreError) + assert isinstance(error, aleo.AleoError) + assert type(error).__name__ == "KeystoreError" + assert error.code == "ACCOUNT_NOT_FOUND" + assert str(sandbox.dir / "default.json") in str(error) + + +def test_result_types_are_frozen_and_hide_the_key(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + loaded = keystore.load(dir=sandbox.dir) + assert isinstance(loaded, LoadedAccount) + assert isinstance(stored.path, Path) + absent(repr(loaded), account.private_key) + absent(str(loaded), account.private_key) + with pytest.raises(FrozenInstanceError): + loaded.address = "aleo1other" # type: ignore[misc] + with pytest.raises(FrozenInstanceError): + stored.name = "other" # type: ignore[misc] + + +# --------------------------------------------------------------------------- +# Names and directory +# --------------------------------------------------------------------------- + + +def test_defaults_to_the_account_default_under_the_home_directory(sandbox: Sandbox) -> None: + stored = keystore.save(Account.random()) + assert stored.name == "default" + assert stored.path == sandbox.home / ".aleo" / "accounts" / "default.json" + assert stored.path.exists() + + +def test_takes_the_name_from_the_argument_then_the_variable(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_ACCOUNT", "from-env") + assert keystore.save(Account.random(), dir=sandbox.dir).name == "from-env" + assert keystore.save(Account.random(), dir=sandbox.dir, name="from-option").name == "from-option" + monkeypatch.setenv("ALEO_ACCOUNT", "") + assert keystore.save(Account.random(), dir=sandbox.dir).name == "default" + + +def test_takes_the_directory_from_the_argument_then_the_variable(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + from_env = sandbox.root / "env-dir" + monkeypatch.setenv("ALEO_ACCOUNTS_DIR", str(from_env)) + assert keystore.save(Account.random()).path == from_env / "default.json" + assert keystore.save(Account.random(), dir=sandbox.dir).path == sandbox.dir / "default.json" + # A path object and its text are the same directory; an empty one counts as absent. + assert keystore.info(dir=str(sandbox.dir)) == keystore.info(dir=sandbox.dir) + assert keystore.save(Account.random(), dir="", name="other").path == from_env / "other.json" + + +def test_expands_a_leading_tilde_in_the_argument_and_in_the_variable(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + assert keystore.save(Account.random(), dir="~/keys").path == sandbox.home / "keys" / "default.json" + monkeypatch.setenv("ALEO_ACCOUNTS_DIR", "~/from-env") + assert keystore.save(Account.random()).path == sandbox.home / "from-env" / "default.json" + monkeypatch.setenv("ALEO_ACCOUNTS_DIR", "~") + assert keystore.save(Account.random(), name="top").path == sandbox.home / "top.json" + + +def test_leaves_a_tilde_that_names_another_user_alone(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.chdir(sandbox.root) + stored = keystore.save(Account.random(), dir="~someone") + assert stored.path == sandbox.root / "~someone" / "default.json" + + +def test_resolves_a_relative_directory_against_the_working_directory(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.chdir(sandbox.root) + assert keystore.save(Account.random(), dir="relative/../keys").path == sandbox.root / "keys" / "default.json" + + +@pytest.mark.parametrize( + "name", ["", "Default", "a/b", "../x", ".hidden", "-lead", "_lead", "a.b", "a b", "abc\n", "x" * 65] +) +def test_rejects_the_name(sandbox: Sandbox, name: str) -> None: + assert code_of(lambda: keystore.save(Account.random(), dir=sandbox.dir, name=name)) == "INVALID_NAME" + assert code_of(lambda: keystore.info(dir=sandbox.dir, name=name)) == "INVALID_NAME" + + +def test_rejects_a_name_that_is_not_text(sandbox: Sandbox) -> None: + assert code_of(lambda: keystore.info(dir=sandbox.dir, name=7)) == "INVALID_NAME" # type: ignore[arg-type] + + +def test_rejects_an_invalid_name_from_the_variable(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_ACCOUNT", "Not_Valid") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "INVALID_NAME" + + +@pytest.mark.parametrize("name", ["a", "0", "main-net_2", "x" * 64]) +def test_accepts_the_name(sandbox: Sandbox, name: str) -> None: + assert keystore.save(Account.random(), dir=sandbox.dir, name=name).name == name + + +@posix_only +def test_creates_the_directory_at_0700_and_the_file_at_0600(sandbox: Sandbox) -> None: + previous = os.umask(0o022) + try: + stored = keystore.save(Account.random(), dir=sandbox.root / "deep" / "accounts") + finally: + os.umask(previous) + assert mode(stored.path.parent) == 0o700 + assert mode(stored.path) == 0o600 + # Only the account file is left behind: no temporary file. + assert os.listdir(stored.path.parent) == ["default.json"] + + +@posix_only +def test_leaves_the_mode_of_an_existing_directory_alone(sandbox: Sandbox) -> None: + sandbox.dir.mkdir() + sandbox.dir.chmod(0o755) + keystore.save(Account.random(), dir=sandbox.dir) + assert mode(sandbox.dir) == 0o755 + + +@posix_only +def test_tightens_a_file_that_is_wider_than_0600_when_it_is_read(sandbox: Sandbox) -> None: + stored = keystore.save(Account.random(), dir=sandbox.dir) + stored.path.chmod(0o644) + keystore.info(dir=sandbox.dir) + assert mode(stored.path) == 0o600 + stored.path.chmod(0o640) + keystore.load(dir=sandbox.dir) + assert mode(stored.path) == 0o600 + stored.path.chmod(0o400) + keystore.load(dir=sandbox.dir) + assert mode(stored.path) == 0o400 + + +@posix_only +def test_does_not_tighten_file_modes_on_windows(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + stored = keystore.save(Account.random(), dir=sandbox.dir) + stored.path.chmod(0o644) + monkeypatch.setattr(runtime, "platform", "win32") + keystore.info(dir=sandbox.dir) + assert mode(stored.path) == 0o644 + + +# --------------------------------------------------------------------------- +# Account file format +# --------------------------------------------------------------------------- + +ADDRESS = SAMPLE.address + + +def encrypted_sample() -> Dict[str, Any]: + return read_json(VECTORS_DIR / "encrypted-js.json") + + +def test_returns_nothing_for_a_missing_file(sandbox: Sandbox) -> None: + assert keystore.info(dir=sandbox.dir) is None + + +@pytest.mark.parametrize( + "content", + [ + pytest.param("not json", id="text that is not JSON"), + pytest.param( + "\N{ZERO WIDTH NO-BREAK SPACE}" + json.dumps({"version": 1, "address": ADDRESS, "key": {"type": "none"}}), + id="a byte-order mark", + ), + pytest.param("[]", id="an array"), + pytest.param("null", id="null"), + pytest.param({"address": ADDRESS, "key": {"type": "none"}}, id="a missing version"), + pytest.param({"version": "1", "address": ADDRESS, "key": {"type": "none"}}, id="a string version"), + pytest.param({"version": 1.5, "address": ADDRESS, "key": {"type": "none"}}, id="a fractional version"), + pytest.param({"version": True, "address": ADDRESS, "key": {"type": "none"}}, id="a boolean version"), + pytest.param({"version": 1, "key": {"type": "none"}}, id="a missing address"), + pytest.param({"version": 1, "address": 5, "key": {"type": "none"}}, id="a numeric address"), + pytest.param({"version": 1, "address": ADDRESS}, id="a missing key"), + pytest.param({"version": 1, "address": ADDRESS, "key": "none"}, id="a key that is not an object"), + pytest.param({"version": 1, "address": ADDRESS, "key": {}}, id="a missing key type"), + pytest.param({"version": 1, "address": ADDRESS, "key": {"type": 1}}, id="a numeric key type"), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "none"}, "network": "testnet"}, + id="an extra top-level field", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "none", "privateKey": "x"}}, + id="an extra field in a none key", + ), + pytest.param({"version": 1, "address": ADDRESS, "key": {"type": "plaintext"}}, id="a plaintext key without privateKey"), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "plaintext", "privateKey": 1}}, + id="a plaintext key with a numeric privateKey", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "plaintext", "privateKey": "x", "note": ""}}, + id="a plaintext key with an extra field", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "keychain", "service": KEY_SERVICE}}, + id="a keychain key without account", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "keychain", "service": "login", "account": ADDRESS}}, + id="a keychain key with another service", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "keychain", "service": KEY_SERVICE, "account": "aleo1other"}}, + id="a keychain key with another account", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "keychain", "service": KEY_SERVICE, "account": ADDRESS}}, + id="a keychain key named after the bare address", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "keychain", "service": KEY_SERVICE, "account": "aleo1other-" + "0" * 32}}, + id="a keychain key named after another address's entry", + ), + pytest.param( + {"version": 1, "address": ADDRESS, "key": {"type": "keychain", "service": KEY_SERVICE, "account": ADDRESS + "-XYZ"}}, + id="a keychain key with a malformed entry name", + ), + pytest.param('{"version": NaN, "address": "a", "key": {"type": "none"}}', id="a NaN version"), + pytest.param('{"version": 1, "address": "a", "key": {"type": "none"}} trailing', id="trailing text"), + ], +) +def test_rejects_the_file(sandbox: Sandbox, content: Any) -> None: + sandbox.put("default", content) + assert code_of(lambda: keystore.info(dir=sandbox.dir)) == "INVALID_ACCOUNT_FILE" + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "INVALID_ACCOUNT_FILE" + + +def test_rejects_a_file_that_is_not_utf8(sandbox: Sandbox) -> None: + sandbox.dir.mkdir(parents=True) + (sandbox.dir / "default.json").write_bytes(bytes([0x7B, 0xFF, 0xFE, 0x7D])) + assert code_of(lambda: keystore.info(dir=sandbox.dir)) == "INVALID_ACCOUNT_FILE" + + +def _set(path: Sequence[str], value: Any) -> Callable[[Dict[str, Any]], None]: + def change(file: Dict[str, Any]) -> None: + target = file + for part in path[:-1]: + target = target[part] + target[path[-1]] = value + + return change + + +def _drop(path: Sequence[str]) -> Callable[[Dict[str, Any]], None]: + def change(file: Dict[str, Any]) -> None: + target = file + for part in path[:-1]: + target = target[part] + del target[path[-1]] + + return change + + +def _strip_salt_padding(file: Dict[str, Any]) -> None: + file["key"]["kdfParams"]["salt"] = file["key"]["kdfParams"]["salt"].rstrip("=") + + +@pytest.mark.parametrize( + "change", + [ + pytest.param(_set(["key", "kdf"], "argon2id"), id="another kdf"), + pytest.param(_set(["key", "kdfParams", "N"], 2**13), id="N below 2^14"), + pytest.param(_set(["key", "kdfParams", "N"], 2**21), id="N above 2^20"), + pytest.param(_set(["key", "kdfParams", "N"], 100000), id="N that is not a power of two"), + pytest.param(_set(["key", "kdfParams", "N"], 16384.5), id="a fractional N"), + pytest.param(_set(["key", "kdfParams", "N"], "131072"), id="a string N"), + pytest.param(_set(["key", "kdfParams", "N"], True), id="a boolean N"), + pytest.param(_set(["key", "kdfParams", "r"], 16), id="r other than 8"), + pytest.param(_set(["key", "kdfParams", "p"], 2), id="p other than 1"), + pytest.param(_set(["key", "kdfParams", "p"], True), id="a boolean p"), + pytest.param( + _set(["key", "kdfParams", "salt"], base64.b64encode(bytes(15)).decode("ascii")), + id="a salt shorter than 16 bytes", + ), + pytest.param(_set(["key", "kdfParams", "salt"], "!!!!!!!!!!!!!!!!!!!!!!!!"), id="a salt that is not base64"), + pytest.param(_strip_salt_padding, id="a salt without padding"), + pytest.param(_set(["key", "kdfParams", "salt"], "AAECAwQFBgcICQoLDA0ODw==\n"), id="a salt with a line ending"), + pytest.param(_drop(["key", "ciphertext"]), id="a missing ciphertext"), + pytest.param(_set(["key", "kdfParams", "dkLen"], 32), id="an extra kdf parameter"), + pytest.param(_set(["key", "hint"], "x"), id="an extra key field"), + ], +) +def test_rejects_an_encrypted_file(sandbox: Sandbox, change: Callable[[Dict[str, Any]], None]) -> None: + file = encrypted_sample() + change(file) + sandbox.put("default", file) + assert code_of(lambda: keystore.info(dir=sandbox.dir)) == "INVALID_ACCOUNT_FILE" + + +@pytest.mark.parametrize("cost", [2**14, 2**15, 2**20]) +def test_accepts_an_encrypted_file_with_cost(sandbox: Sandbox, cost: int) -> None: + file = encrypted_sample() + file["key"]["kdfParams"]["N"] = cost + sandbox.put("default", file) + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "encrypted" + + +def test_accepts_whole_numbers_written_with_a_fraction_or_an_exponent(sandbox: Sandbox) -> None: + # JSON has one number type, so 1.0 and 1e0 are the integer 1. + text = (VECTORS_DIR / "encrypted-js.json").read_text(encoding="utf-8") + replacements = [ + ('"version": 1,', '"version": 1.0,'), + ('"N": 131072,', '"N": 1.31072e5,'), + ('"r": 8,', '"r": 8.0,'), + ('"p": 1,', '"p": 1e0,'), + ] + for old, new in replacements: + assert old in text + text = text.replace(old, new) + sandbox.put("default", text) + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "encrypted" + check_secret( + keystore.export(dir=sandbox.dir, password=VECTORS["encrypted"]["password"], prompt=False), SAMPLE.private_key + ) + + sandbox.put("default", '{"version":2.0,"address":"' + ADDRESS + '","key":{"type":"none"}}\n') + assert code_of(lambda: keystore.info(dir=sandbox.dir)) == "UNSUPPORTED_VERSION" + + +def test_decrypts_a_file_whose_cost_is_above_the_default(sandbox: Sandbox) -> None: + # Written by hand at N = 2^18, which needs more memory than the default cost. + account = new_account() + salt = bytes([7]) * 16 + secret = derive_secret(normalize_password(PASSWORD), salt, 2**18) + ciphertext = str(PrivateKeyCiphertext.encrypt_private_key(PrivateKey.from_string(account.private_key), secret)) + sandbox.put( + "default", + { + "version": 1, + "address": account.address, + "key": { + "type": "encrypted", + "kdf": "scrypt", + "kdfParams": {"N": 2**18, "r": 8, "p": 1, "salt": base64.b64encode(salt).decode("ascii")}, + "ciphertext": ciphertext, + }, + }, + ) + check_secret(keystore.export(dir=sandbox.dir, password=PASSWORD), account.private_key) + + +@pytest.mark.parametrize("version", [0, 2, -1]) +def test_reports_the_version_as_unsupported_even_with_unknown_fields( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, version: int +) -> None: + sandbox.put("default", {"version": version, "address": ADDRESS, "key": {"type": "none"}, "added": True}) + assert code_of(lambda: keystore.info(dir=sandbox.dir)) == "UNSUPPORTED_VERSION" + monkeypatch.setenv("ALEO_PRIVATE_KEY", SAMPLE.private_key) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "UNSUPPORTED_VERSION" + + +def test_reports_an_unknown_storage_type_as_unsupported_and_does_not_fall_back( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + sandbox.put("default", {"version": 1, "address": ADDRESS, "key": {"type": "secret-service", "collection": "login"}}) + assert code_of(lambda: keystore.info(dir=sandbox.dir)) == "UNSUPPORTED_STORAGE" + monkeypatch.setenv("ALEO_PRIVATE_KEY", SAMPLE.private_key) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "UNSUPPORTED_STORAGE" + assert code_of(lambda: keystore.load(dir=sandbox.dir, legacy_key=SAMPLE.private_key)) == "UNSUPPORTED_STORAGE" + + +def test_does_not_quote_a_malformed_file_in_the_error(sandbox: Sandbox) -> None: + account = new_account() + sandbox.put( + "default", + f'{{"version": 1, "address": "{account.address}", "key": {{"type": "plaintext", "privateKey": "{account.private_key}" oops', + ) + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "INVALID_ACCOUNT_FILE" + absent(str(error), account.private_key) + assert error.__cause__ is None + assert error.__context__ is None + + +def test_reports_an_unparseable_or_mismatched_plaintext_key(sandbox: Sandbox) -> None: + sandbox.put("default", {"version": 1, "address": ADDRESS, "key": {"type": "plaintext", "privateKey": "APrivateKey1nope"}}) + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "plaintext" + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "INVALID_KEY" + + other = new_account() + sandbox.put("default", {"version": 1, "address": ADDRESS, "key": {"type": "plaintext", "privateKey": other.private_key}}) + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "ADDRESS_MISMATCH" + assert ADDRESS in str(error) + assert other.address in str(error) + absent(str(error), other.private_key) + + +# --------------------------------------------------------------------------- +# save +# --------------------------------------------------------------------------- + + +def test_stores_plaintext_by_default_and_returns_the_account_without_its_key(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + assert stored == StoredAccount( + name="default", path=sandbox.dir / "default.json", address=account.address, storage="plaintext" + ) + file = read_json(stored.path) + assert list(file) == ["version", "address", "key"] + assert list(file["key"]) == ["type", "privateKey"] + check_secret(file["key"]["privateKey"], account.private_key) + assert stored.path.read_text(encoding="utf-8") == json.dumps(file, indent=2, ensure_ascii=False) + "\n" + + +def test_accepts_accounts_and_keys_of_either_network_and_key_strings(sandbox: Sandbox) -> None: + import aleo.testnet as testnet + + mainnet_account = Account.random() + testnet_account = testnet.Account.random() + testnet_key = testnet.PrivateKey.random() + mainnet_key = PrivateKey.random() + cases = [ + ("mainnet-account", mainnet_account, str(mainnet_account.address), str(mainnet_account.private_key)), + ("testnet-account", testnet_account, str(testnet_account.address), str(testnet_account.private_key)), + ("mainnet-key", mainnet_key, str(mainnet_key.address), str(mainnet_key)), + ("testnet-key", testnet_key, str(testnet_key.address), str(testnet_key)), + ("key-string", str(mainnet_key), str(mainnet_key.address), str(mainnet_key)), + ] + for name, account, address, private_key in cases: + stored = keystore.save(account, dir=sandbox.dir, name=name) + assert stored.address == address + check_secret(keystore.export(dir=sandbox.dir, name=name), private_key) + + +def test_accepts_a_loaded_account(sandbox: Sandbox) -> None: + account = new_account() + loaded = keystore.load(dir=sandbox.dir, private_key=account.private_key) + stored = keystore.save(loaded, dir=sandbox.dir) + assert stored.address == account.address + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_returns_without_rewriting_for_the_same_account_and_storage(sandbox: Sandbox) -> None: + account = new_account() + first = keystore.save(account.private_key, dir=sandbox.dir) + before = os.stat(first.path) + again = keystore.save(account.private_key, dir=sandbox.dir) + assert again == first + after = os.stat(first.path) + assert after.st_ino == before.st_ino + assert after.st_mtime_ns == before.st_mtime_ns + + +def test_returns_for_the_same_encrypted_account_without_a_password_or_a_keychain_call(sandbox: Sandbox) -> None: + account = new_account() + first = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + data = first.path.read_bytes() + assert keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted") == first + again = keystore.save( + account.private_key, dir=sandbox.dir, storage="encrypted", password=OTHER_PASSWORD, save_password=True + ) + assert again == first + assert first.path.read_bytes() == data + assert sandbox.security.calls == [] + assert sandbox.prompts == [] + + +def test_refuses_the_same_account_with_another_storage_and_points_at_protect(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + error = failure(lambda: keystore.save(account.private_key, dir=sandbox.dir, storage="none")) + assert error.code == "ACCOUNT_EXISTS" + assert "protect" in str(error) + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "plaintext" + + +def test_refuses_to_replace_a_file_that_holds_another_address(sandbox: Sandbox) -> None: + first = new_account() + second = new_account() + stored = keystore.save(first.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + error = failure(lambda: keystore.save(second.private_key, dir=sandbox.dir)) + assert error.code == "ACCOUNT_EXISTS" + assert first.address in str(error) + assert second.address in str(error) + assert stored.path.read_bytes() == data + + +def test_does_not_overwrite_a_file_it_cannot_read(sandbox: Sandbox) -> None: + path = sandbox.put("default", {"version": 2, "address": "aleo1future", "key": {}}) + data = path.read_bytes() + assert code_of(lambda: keystore.save(Account.random(), dir=sandbox.dir)) == "UNSUPPORTED_VERSION" + assert path.read_bytes() == data + + +def test_rejects_a_key_that_cannot_be_parsed_or_does_not_derive_the_address(sandbox: Sandbox) -> None: + account = new_account() + bad = failure(lambda: keystore.save("APrivateKey1nope", dir=sandbox.dir)) + assert bad.code == "INVALID_KEY" + assert "APrivateKey1nope" not in str(bad) + assert bad.__cause__ is None and bad.__context__ is None + for not_a_key in (None, 7, b"APrivateKey1", object()): + assert code_of(lambda: keystore.save(not_a_key, dir=sandbox.dir)) == "INVALID_KEY" + # An object that states an address must hold the key of that address. + stated = LoadedAccount(address=SAMPLE.address, private_key=account.private_key, source="argument") + assert code_of(lambda: keystore.save(stated, dir=sandbox.dir)) == "ADDRESS_MISMATCH" + assert not (sandbox.dir / "default.json").exists() + + +def test_rejects_an_unknown_storage_type(sandbox: Sandbox) -> None: + for storage in ("vault", "", None, 1, ["plaintext"]): + assert code_of(lambda: keystore.save(Account.random(), dir=sandbox.dir, storage=storage)) == "UNSUPPORTED_STORAGE" # type: ignore[arg-type] + assert not sandbox.dir.exists() + + +def test_writes_the_address_only_form_for_storage_none(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="none") + assert stored.storage == "none" + absent(stored.path.read_text(encoding="utf-8"), account.private_key) + assert read_json(stored.path) == {"version": 1, "address": account.address, "key": {"type": "none"}} + + +# --------------------------------------------------------------------------- +# load: the lookup order +# --------------------------------------------------------------------------- + + +def test_fails_with_account_not_found_when_nothing_supplies_a_key_and_generates_nothing(sandbox: Sandbox) -> None: + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "ACCOUNT_NOT_FOUND" + assert not sandbox.dir.exists() + + +def test_reads_the_account_file_when_the_environment_supplies_nothing(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + loaded = keystore.load(dir=sandbox.dir) + assert loaded.source == "account-file" + assert loaded.stored == stored + assert loaded.address == account.address + check_secret(loaded.private_key, account.private_key) + assert isinstance(loaded.address, str) and isinstance(loaded.private_key, str) + + +def test_a_loaded_key_becomes_an_account_on_either_network(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + loaded = keystore.load(dir=sandbox.dir) + for network in ("mainnet", "testnet"): + client = aleo.Aleo(aleo.HTTPProvider("https://api.provable.com/v2", network=network)) + assert str(client.account.from_private_key(loaded.private_key).address) == account.address + + +def test_prefers_an_explicit_key_and_then_ignores_the_key_variables(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", "") + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", new_account().private_key) + loaded = keystore.load(dir=sandbox.dir, private_key=account.private_key) + assert loaded.source == "argument" + assert loaded.stored is None + assert loaded.address == account.address + + +@pytest.mark.parametrize("variable", ["ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY"]) +def test_reads_the_key_from_the_variable(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, variable: str) -> None: + account = new_account() + monkeypatch.setenv(variable, f" {account.private_key}\n") + loaded = keystore.load(dir=sandbox.dir) + assert loaded.source == "env" + assert loaded.address == account.address + check_secret(loaded.private_key, account.private_key) + # A key from the environment is used for the process and never stored. + assert not sandbox.dir.exists() + + +@pytest.mark.parametrize("variable", ["ALEO_PRIVATE_KEY_FILE", "SHIELD_SWAP_PRIVATE_KEY_FILE"]) +def test_reads_the_key_from_the_file_named_by_the_variable( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, variable: str +) -> None: + account = new_account() + key_file = sandbox.root / "key.txt" + key_file.write_text(f"\n {account.private_key} \n", encoding="utf-8") + monkeypatch.setenv(variable, str(key_file)) + loaded = keystore.load(dir=sandbox.dir) + assert loaded.source == "env-file" + assert loaded.address == account.address + assert not sandbox.dir.exists() + + +def test_reads_a_key_file_that_starts_with_a_byte_order_mark(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + key_file = sandbox.root / "key.txt" + key_file.write_bytes(b"\xef\xbb\xbf" + account.private_key.encode("ascii") + b"\r\n") + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", str(key_file)) + assert keystore.load(dir=sandbox.dir).address == account.address + + +def test_reports_the_variable_ahead_of_the_key_file_when_both_hold_the_same_key( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + key_file = sandbox.root / "key.txt" + key_file.write_text(account.private_key, encoding="utf-8") + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", str(key_file)) + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY_FILE", str(key_file)) + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", account.private_key) + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + loaded = keystore.load(dir=sandbox.dir) + assert loaded.source == "env" + assert loaded.address == account.address + + +@pytest.mark.parametrize( + ("one", "two"), + [ + ("ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY"), + ("ALEO_PRIVATE_KEY", "ALEO_PRIVATE_KEY_FILE"), + ("SHIELD_SWAP_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY_FILE"), + ("ALEO_PRIVATE_KEY_FILE", "SHIELD_SWAP_PRIVATE_KEY_FILE"), + ], +) +def test_fails_with_key_conflict_when_two_variables_hold_different_keys( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, one: str, two: str +) -> None: + first = new_account() + second = new_account() + + def set_variable(variable: str, key: str) -> None: + if variable.endswith("_FILE"): + key_file = sandbox.root / f"{variable}.txt" + key_file.write_text(key, encoding="utf-8") + monkeypatch.setenv(variable, str(key_file)) + else: + monkeypatch.setenv(variable, key) + + set_variable(one, first.private_key) + set_variable(two, second.private_key) + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "KEY_CONFLICT" + assert one in str(error) + assert two in str(error) + absent(str(error), first.private_key) + absent(str(error), second.private_key) + + +@pytest.mark.parametrize( + "variable", ["ALEO_PRIVATE_KEY", "SHIELD_SWAP_PRIVATE_KEY", "ALEO_PRIVATE_KEY_FILE", "SHIELD_SWAP_PRIVATE_KEY_FILE"] +) +def test_fails_with_empty_key_source_when_the_variable_is_set_but_empty_even_with_an_account_file( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, variable: str +) -> None: + keystore.save(Account.random(), dir=sandbox.dir) + monkeypatch.setenv(variable, "") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "EMPTY_KEY_SOURCE" + monkeypatch.setenv(variable, " ") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "EMPTY_KEY_SOURCE" + + +def test_fails_with_empty_key_source_for_an_empty_or_missing_key_file(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + key_file = sandbox.root / "key.txt" + key_file.write_text(" \n", encoding="utf-8") + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", str(key_file)) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "EMPTY_KEY_SOURCE" + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", str(sandbox.root / "absent.txt")) + error = failure(lambda: keystore.load(dir=sandbox.dir, legacy_key=new_account().private_key)) + assert error.code == "EMPTY_KEY_SOURCE" + assert "absent.txt" in str(error) + assert "ENOENT" in str(error) + + +def test_fails_with_invalid_key_without_echoing_the_value(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_PRIVATE_KEY", "APrivateKey1definitelynotakey") + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "INVALID_KEY" + assert "ALEO_PRIVATE_KEY" in str(error) + assert "definitelynotakey" not in str(error) + assert error.__cause__ is None and error.__context__ is None + monkeypatch.delenv("ALEO_PRIVATE_KEY") + assert code_of(lambda: keystore.load(dir=sandbox.dir, private_key="")) == "INVALID_KEY" + assert code_of(lambda: keystore.load(dir=sandbox.dir, private_key=7)) == "INVALID_KEY" # type: ignore[arg-type] + + +def test_requires_a_key_from_the_caller_or_the_environment_to_match_the_account_file( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + other = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + matching = keystore.load(dir=sandbox.dir) + assert matching.source == "env" + assert matching.stored == stored + + monkeypatch.setenv("ALEO_PRIVATE_KEY", other.private_key) + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "ADDRESS_MISMATCH" + assert account.address in str(error) + assert other.address in str(error) + + monkeypatch.delenv("ALEO_PRIVATE_KEY") + assert code_of(lambda: keystore.load(dir=sandbox.dir, private_key=other.private_key)) == "ADDRESS_MISMATCH" + assert keystore.load(dir=sandbox.dir, private_key=account.private_key).source == "argument" + + +def test_uses_an_address_only_file_to_check_a_key_from_the_environment(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="none") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "KEY_NOT_STORED" + assert code_of(lambda: keystore.load(dir=sandbox.dir, legacy_key=account.private_key)) == "KEY_NOT_STORED" + + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + loaded = keystore.load(dir=sandbox.dir) + assert loaded.source == "env" + assert loaded.stored is not None and loaded.stored.storage == "none" + + monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "ADDRESS_MISMATCH" + + +def test_checks_the_resolved_key_against_the_expected_address(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + assert keystore.load(dir=sandbox.dir, expected_address=account.address).address == account.address + error = failure(lambda: keystore.load(dir=sandbox.dir, expected_address=SAMPLE.address)) + assert error.code == "ADDRESS_MISMATCH" + assert account.address in str(error) + assert SAMPLE.address in str(error) + empty = sandbox.root / "empty" + assert ( + code_of(lambda: keystore.load(dir=empty, private_key=account.private_key, expected_address=SAMPLE.address)) + == "ADDRESS_MISMATCH" + ) + + +def test_uses_the_legacy_key_only_when_nothing_else_supplies_one(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + legacy = new_account() + from_legacy = keystore.load(dir=sandbox.dir, legacy_key=legacy.private_key) + assert from_legacy.source == "legacy" + assert from_legacy.stored is None + assert from_legacy.address == legacy.address + assert not sandbox.dir.exists() + + env = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", env.private_key) + from_env = keystore.load(dir=sandbox.dir, legacy_key=legacy.private_key) + assert from_env.source == "env" + assert from_env.address == env.address + monkeypatch.delenv("ALEO_PRIVATE_KEY") + + assert code_of(lambda: keystore.load(dir=sandbox.dir, legacy_key="APrivateKey1nope")) == "INVALID_KEY" + + +def test_prefers_the_account_file_over_a_legacy_key_and_requires_them_to_match(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + loaded = keystore.load(dir=sandbox.dir, legacy_key=account.private_key) + assert loaded.source == "account-file" + error = failure(lambda: keystore.load(dir=sandbox.dir, legacy_key=new_account().private_key)) + assert error.code == "ADDRESS_MISMATCH" + assert account.address in str(error) + + +def test_reports_a_bad_variable_ahead_of_a_bad_account_file(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + sandbox.put("default", "not json") + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY_FILE", "") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "EMPTY_KEY_SOURCE" + # With an explicit key the variables are not read, so the file is what fails. + assert code_of(lambda: keystore.load(dir=sandbox.dir, private_key=new_account().private_key)) == "INVALID_ACCOUNT_FILE" + + +def test_validates_every_variable_that_is_set(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", "APrivateKey1nope") + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "INVALID_KEY" + assert "SHIELD_SWAP_PRIVATE_KEY" in str(error) + + +def test_treats_a_directory_named_as_the_key_file_as_an_empty_source(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", str(sandbox.home)) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "EMPTY_KEY_SOURCE" + # The path is used as written: a leading "~" is not expanded. + (sandbox.home / "key.txt").write_text(new_account().private_key, encoding="utf-8") + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", "~/key.txt") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "EMPTY_KEY_SOURCE" + + +def test_does_not_trim_a_key_passed_in_code(sandbox: Sandbox) -> None: + account = new_account() + padded = f" {account.private_key}\n" + assert code_of(lambda: keystore.load(dir=sandbox.dir, private_key=padded)) == "INVALID_KEY" + assert code_of(lambda: keystore.load(dir=sandbox.dir, legacy_key=padded)) == "INVALID_KEY" + assert code_of(lambda: keystore.save(padded, dir=sandbox.dir)) == "INVALID_KEY" + + +def test_ignores_an_unused_legacy_key_when_the_environment_supplies_the_key( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + loaded = keystore.load(dir=sandbox.dir, legacy_key="APrivateKey1nope") + assert loaded.source == "env" + assert loaded.address == account.address + + +def test_reads_the_stored_key_before_checking_the_expected_address(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + assert code_of(lambda: keystore.load(dir=sandbox.dir, expected_address=SAMPLE.address)) == "PASSWORD_REQUIRED" + assert ( + code_of(lambda: keystore.load(dir=sandbox.dir, expected_address=SAMPLE.address, password=PASSWORD)) + == "ADDRESS_MISMATCH" + ) + + +def test_passes_file_system_failures_on_the_account_file_through(sandbox: Sandbox) -> None: + sandbox.dir.mkdir() + blocked = sandbox.dir / "default.json" + blocked.mkdir() + before = mode(blocked) + for call in ( + lambda: keystore.info(dir=sandbox.dir), + lambda: keystore.load(dir=sandbox.dir), + lambda: keystore.export(dir=sandbox.dir), + lambda: keystore.save(Account.random(), dir=sandbox.dir), + lambda: keystore.protect(dir=sandbox.dir, storage="plaintext"), + ): + with pytest.raises(OSError) as raised: + call() + assert not isinstance(raised.value, KeystoreError) + assert mode(blocked) == before + + +# --------------------------------------------------------------------------- +# Encrypted storage and password sources +# --------------------------------------------------------------------------- + + +def test_writes_the_encrypted_form_with_a_fresh_salt_and_the_fixed_scrypt_cost(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + assert stored.storage == "encrypted" + text = stored.path.read_text(encoding="utf-8") + absent(text, account.private_key) + absent(text, PASSWORD) + file = json.loads(text) + assert list(file) == ["version", "address", "key"] + assert list(file["key"]) == ["type", "kdf", "kdfParams", "ciphertext"] + assert list(file["key"]["kdfParams"]) == ["N", "r", "p", "salt"] + assert file["key"]["kdf"] == "scrypt" + params = file["key"]["kdfParams"] + assert [params["N"], params["r"], params["p"]] == [131072, 8, 1] + assert all(type(params[field]) is int for field in ("N", "r", "p")) + assert type(file["version"]) is int + assert len(base64.b64decode(params["salt"])) == 16 + assert re.fullmatch(r"[A-Za-z0-9+/]{22}==", params["salt"]) + assert file["key"]["ciphertext"].startswith("ciphertext1") + assert text == json.dumps(file, indent=2, ensure_ascii=False) + "\n" + # Nothing reached the Keychain without save_password. + assert sandbox.security.calls == [] + + second = keystore.save(account.private_key, dir=sandbox.dir, name="second", storage="encrypted", password=PASSWORD) + other = read_json(second.path) + assert other["key"]["kdfParams"]["salt"] != params["salt"] + + +def test_takes_the_password_from_the_argument_then_the_variable(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + + via_argument = keystore.load(dir=sandbox.dir, password=PASSWORD, prompt=False) + assert via_argument.source == "account-file" + check_secret(via_argument.private_key, account.private_key) + + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + assert keystore.load(dir=sandbox.dir, prompt=False).address == account.address + + # The argument wins over the variable, and a wrong one does not fall through. + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", OTHER_PASSWORD) + assert keystore.load(dir=sandbox.dir, password=PASSWORD).address == account.address + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + assert code_of(lambda: keystore.load(dir=sandbox.dir, password=OTHER_PASSWORD)) == "WRONG_PASSWORD" + + +def test_does_not_fall_through_to_the_keychain_or_the_prompt_after_a_wrong_variable( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + sandbox.terminal = True + sandbox.answers.append(PASSWORD) + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", OTHER_PASSWORD) + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "WRONG_PASSWORD" + absent(str(error), OTHER_PASSWORD) + assert sandbox.prompts == [] + + +def test_sets_the_password_from_the_variable_when_none_is_passed(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted") + monkeypatch.delenv("ALEO_ACCOUNT_PASSWORD") + check_secret(keystore.export(dir=sandbox.dir, password=PASSWORD), account.private_key) + + +def test_treats_passwords_that_are_equal_under_nfkc_as_the_same_password(sandbox: Sandbox) -> None: + account = new_account() + written = "\N{FULLWIDTH LATIN SMALL LETTER P}ass\N{NO-BREAK SPACE}word e\N{COMBINING ACUTE ACCENT}" + typed = "pass word \N{LATIN SMALL LETTER E WITH ACUTE}" + assert written != typed + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=written) + check_secret(keystore.export(dir=sandbox.dir, password=typed), account.private_key) + + +def test_rejects_an_empty_password(sandbox: Sandbox) -> None: + account = new_account() + assert ( + code_of(lambda: keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password="")) + == "PASSWORD_REQUIRED" + ) + assert not (sandbox.dir / "default.json").exists() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + assert code_of(lambda: keystore.load(dir=sandbox.dir, password="")) == "PASSWORD_REQUIRED" + + +def test_fails_with_password_required_when_no_source_supplies_a_password( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + assert code_of(lambda: keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted")) == "PASSWORD_REQUIRED" + assert not (sandbox.dir / "default.json").exists() + + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "PASSWORD_REQUIRED" + assert code_of(lambda: keystore.export(dir=sandbox.dir)) == "PASSWORD_REQUIRED" + # An empty variable counts as unset. + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", "") + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "PASSWORD_REQUIRED" + # A terminal is attached, but the caller forbade prompting. + sandbox.terminal = True + assert code_of(lambda: keystore.load(dir=sandbox.dir, prompt=False)) == "PASSWORD_REQUIRED" + assert sandbox.prompts == [] + + +def test_reads_a_saved_password_from_the_keychain(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + # The entry is named after the address and this file's salt. + entry_account = saved_password_account(stored.path) + assert re.fullmatch(f"{account.address}-[0-9a-f]{{32}}", entry_account) + assert sandbox.security.entries.get(f"{PASSWORD_SERVICE} {entry_account}") == PASSWORD.encode("utf-8").hex() + sandbox.security.calls.clear() + + loaded = keystore.load(dir=sandbox.dir, prompt=False) + assert loaded.address == account.address + assert sandbox.security.calls == [ + {"args": ["find-generic-password", "-s", "aleo-account-password", "-a", entry_account, "-w"], "stdin": None} + ] + + +def test_fails_on_a_wrong_saved_password_without_prompting(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + sandbox.security.entries[saved_password_entry(stored.path)] = OTHER_PASSWORD.encode("utf-8").hex() + sandbox.terminal = True + sandbox.answers.append(PASSWORD) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "WRONG_PASSWORD" + assert sandbox.prompts == [] + # The variable is consulted first, so it still unlocks the account. + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + assert keystore.load(dir=sandbox.dir).address == account.address + + +def test_reports_a_failing_keychain_lookup_instead_of_prompting(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + sandbox.security.force(lambda args: (36, "") if args[0] == "find-generic-password" else None) + sandbox.terminal = True + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "KEYCHAIN_FAILED" + sandbox.security.force(None) + for not_a_saved_password in ("not-hex", "", "abc", "ABCD"): + sandbox.security.entries[saved_password_entry(stored.path)] = not_a_saved_password + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "KEYCHAIN_FAILED" + assert sandbox.prompts == [] + + +def test_skips_the_keychain_outside_macos_and_ignores_save_password_there( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(runtime, "platform", "linux") + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "PASSWORD_REQUIRED" + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + assert keystore.load(dir=sandbox.dir).address == account.address + assert sandbox.security.calls == [] + + +def test_prompts_on_the_terminal_and_allows_three_attempts(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + sandbox.terminal = True + + sandbox.answers.extend([OTHER_PASSWORD, "", PASSWORD]) + loaded = keystore.load(dir=sandbox.dir) + assert loaded.address == account.address + assert len(sandbox.prompts) == 3 + assert account.address in sandbox.prompts[0] + assert "default" in sandbox.prompts[0] + assert sandbox.notes == ["Wrong password.", "The password must not be empty."] + + sandbox.prompts.clear() + sandbox.answers.extend([OTHER_PASSWORD, OTHER_PASSWORD, OTHER_PASSWORD, PASSWORD]) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "WRONG_PASSWORD" + assert len(sandbox.prompts) == 3 + assert sandbox.answers == [PASSWORD] + + +def test_asks_twice_when_setting_a_password_at_the_terminal(sandbox: Sandbox) -> None: + account = new_account() + sandbox.terminal = True + sandbox.answers.extend([PASSWORD, OTHER_PASSWORD, "", "", PASSWORD, PASSWORD]) + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted") + assert len(sandbox.prompts) == 6 + assert sandbox.notes == ["The passwords do not match.", "The password must not be empty."] + check_secret(keystore.export(dir=sandbox.dir, password=PASSWORD, prompt=False), account.private_key) + + sandbox.answers.extend([PASSWORD, OTHER_PASSWORD, PASSWORD, OTHER_PASSWORD, PASSWORD, OTHER_PASSWORD]) + assert ( + code_of(lambda: keystore.save(Account.random(), dir=sandbox.dir, name="second", storage="encrypted")) + == "PASSWORD_REQUIRED" + ) + assert not (sandbox.dir / "second.json").exists() + + +def test_reports_a_damaged_ciphertext_as_a_wrong_password(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + file = read_json(stored.path) + file["key"]["ciphertext"] = "ciphertext1qqqq" + sandbox.put("default", file) + error = failure(lambda: keystore.load(dir=sandbox.dir, password=PASSWORD)) + assert error.code == "WRONG_PASSWORD" + assert error.__cause__ is None and error.__context__ is None + + +def test_reports_a_ciphertext_for_another_account_as_a_wrong_password(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + file = read_json(stored.path) + file["address"] = SAMPLE.address + sandbox.put("default", file) + assert code_of(lambda: keystore.load(dir=sandbox.dir, password=PASSWORD)) == "WRONG_PASSWORD" + + +# --------------------------------------------------------------------------- +# Keychain storage +# --------------------------------------------------------------------------- + + +def test_writes_the_key_through_security_i_and_never_as_a_process_argument(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + assert stored.storage == "keychain" + calls = sandbox.security.calls + entry = key_entry_account(stored.path) + assert re.fullmatch(f"{account.address}-[0-9a-f]{{32}}", entry) + find = {"args": ["find-generic-password", "-s", "aleo-account-key", "-a", entry, "-w"], "stdin": None} + assert len(calls) == 3 + # The entry is looked for before it is written. + assert calls[0] == find + assert calls[1]["args"] == ["-i"] + check_secret(calls[1]["stdin"], f"add-generic-password -U -s aleo-account-key -a {entry} -l aleo-account-key:default -w {account.private_key}\n") + # The write is confirmed by reading the entry back. + assert calls[2] == find + for call in calls: + assert not any("APrivateKey1" in argument for argument in call["args"]) + + text = stored.path.read_text(encoding="utf-8") + assert "APrivateKey1" not in text + assert json.loads(text) == { + "version": 1, + "address": account.address, + "key": {"type": "keychain", "service": "aleo-account-key", "account": entry}, + } + + +def test_labels_each_entry_with_the_account_name_and_finds_it_by_the_name_the_file_records(sandbox: Sandbox) -> None: + first = new_account() + trading_key = keystore.save(first.private_key, dir=sandbox.dir, name="trading", storage="keychain") + assert sandbox.security.labels[key_entry(trading_key.path)] == "aleo-account-key:trading" + + second = new_account() + bot = keystore.save(second.private_key, dir=sandbox.dir, name="bot_1-a", storage="encrypted", password=PASSWORD, save_password=True) + assert sandbox.security.labels[saved_password_entry(bot.path)] == "aleo-account-password:bot_1-a" + + # Changing the storage writes the new entry under the same account name. + bot_key = keystore.protect(dir=sandbox.dir, name="bot_1-a", storage="keychain", password=PASSWORD) + assert sandbox.security.labels[key_entry(bot_key.path)] == "aleo-account-key:bot_1-a" + trading = keystore.protect(dir=sandbox.dir, name="trading", storage="encrypted", password=PASSWORD, save_password=True) + assert sandbox.security.labels[saved_password_entry(trading.path)] == "aleo-account-password:trading" + + # The label plays no part in the lookup: reads name only the service and the entry. + sandbox.security.calls.clear() + keystore.load(dir=sandbox.dir, name="bot_1-a") + assert sandbox.security.calls == [ + {"args": ["find-generic-password", "-s", "aleo-account-key", "-a", key_entry_account(bot_key.path), "-w"], "stdin": None} + ] + + +def test_reads_the_key_back_from_the_keychain(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + sandbox.security.calls.clear() + loaded = keystore.load(dir=sandbox.dir) + assert loaded.source == "account-file" + check_secret(loaded.private_key, account.private_key) + assert sandbox.security.calls == [ + {"args": ["find-generic-password", "-s", "aleo-account-key", "-a", key_entry_account(stored.path), "-w"], "stdin": None} + ] + + +def test_maps_exit_status_44_to_item_not_found_and_other_failures_to_keychain_failed(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + sandbox.security.entries.clear() + missing = failure(lambda: keystore.load(dir=sandbox.dir)) + assert missing.code == "KEYCHAIN_ITEM_NOT_FOUND" + assert account.address in str(missing) + + sandbox.security.force(lambda args: (51, "")) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "KEYCHAIN_FAILED" + # A timeout or a tool that cannot start has no exit status. + sandbox.security.force(lambda args: (None, "")) + assert code_of(lambda: keystore.load(dir=sandbox.dir)) == "KEYCHAIN_FAILED" + + +def test_fails_with_address_mismatch_when_the_keychain_entry_holds_another_key(sandbox: Sandbox) -> None: + account = new_account() + other = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + sandbox.security.entries[key_entry(stored.path)] = other.private_key + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "ADDRESS_MISMATCH" + assert account.address in str(error) + assert other.address in str(error) + absent(str(error), other.private_key) + + +def test_writes_no_file_when_the_keychain_write_fails(sandbox: Sandbox) -> None: + sandbox.security.force(lambda args: (1, "") if args[0] == "-i" else None) + assert code_of(lambda: keystore.save(Account.random(), dir=sandbox.dir, storage="keychain")) == "KEYCHAIN_FAILED" + assert not (sandbox.dir / "default.json").exists() + + +def test_fails_when_the_entry_does_not_hold_the_key_after_the_write(sandbox: Sandbox) -> None: + sandbox.security.force(lambda args: (0, "") if args[0] == "-i" else None) + assert code_of(lambda: keystore.save(Account.random(), dir=sandbox.dir, storage="keychain")) == "KEYCHAIN_FAILED" + assert not (sandbox.dir / "default.json").exists() + + +def test_never_echoes_the_security_tools_output_in_an_error(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + sandbox.security.force(lambda args: (1, f"{account.private_key}\n")) + error = failure(lambda: keystore.load(dir=sandbox.dir)) + assert error.code == "KEYCHAIN_FAILED" + absent(str(error), account.private_key) + + +def test_refuses_keychain_storage_outside_macos_before_anything_is_written( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(runtime, "platform", "linux") + account = new_account() + error = failure(lambda: keystore.save(account.private_key, dir=sandbox.dir, storage="keychain")) + assert error.code == "KEYCHAIN_UNAVAILABLE" + assert not sandbox.dir.exists() + assert sandbox.security.calls == [] + + keystore.save(account.private_key, dir=sandbox.dir) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="keychain")) == "KEYCHAIN_UNAVAILABLE" + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "plaintext" + + +def test_fails_to_load_a_keychain_file_outside_macos_and_never_falls_back( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + monkeypatch.setattr(runtime, "platform", "linux") + sandbox.security.calls.clear() + + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "keychain" + error = failure(lambda: keystore.load(dir=sandbox.dir, legacy_key=account.private_key)) + assert error.code == "KEYCHAIN_UNAVAILABLE" + assert re.search(r"[Ee]xport", str(error)) + assert re.search(r"import", str(error)) + assert code_of(lambda: keystore.export(dir=sandbox.dir)) == "KEYCHAIN_UNAVAILABLE" + assert sandbox.security.calls == [] + + # A key from the environment needs no Keychain; the file still checks it. + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + assert keystore.load(dir=sandbox.dir).source == "env" + + +# --------------------------------------------------------------------------- +# protect +# --------------------------------------------------------------------------- + + +def test_moves_an_account_through_every_storage_and_removes_each_old_secret(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + + # plaintext -> keychain + stored = keystore.protect(dir=sandbox.dir, storage="keychain") + assert stored == StoredAccount( + name="default", path=sandbox.dir / "default.json", address=account.address, storage="keychain" + ) + assert "APrivateKey1" not in stored.path.read_text(encoding="utf-8") + key_entry_name = key_entry(stored.path) + check_secret(sandbox.security.entries[key_entry_name], account.private_key) + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + # keychain -> encrypted, password saved: the key entry goes, the password entry appears. + stored = keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True, prompt=False) + assert stored.storage == "encrypted" + assert key_entry_name not in sandbox.security.entries + assert sandbox.security.entries.get(saved_password_entry(stored.path)) == PASSWORD.encode("utf-8").hex() + check_secret(keystore.export(dir=sandbox.dir, prompt=False), account.private_key) + + # encrypted -> plaintext: the saved password goes. + stored = keystore.protect(dir=sandbox.dir, storage="plaintext", prompt=False) + assert stored.storage == "plaintext" + assert sandbox.security.entries == {} + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + if POSIX: + assert mode(stored.path) == 0o600 + assert os.listdir(sandbox.dir) == ["default.json"] + + +def test_sets_a_new_password_and_a_new_salt_on_an_encrypted_account(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + before = read_json(stored.path) + + keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, new_password=OTHER_PASSWORD, prompt=False) + after = read_json(stored.path) + assert after["key"]["kdfParams"]["salt"] != before["key"]["kdfParams"]["salt"] + assert after["key"]["ciphertext"] != before["key"]["ciphertext"] + # save_password was not repeated, so the saved (old) password is gone. + assert sandbox.security.entries == {} + assert code_of(lambda: keystore.export(dir=sandbox.dir, password=PASSWORD)) == "WRONG_PASSWORD" + check_secret(keystore.export(dir=sandbox.dir, password=OTHER_PASSWORD), account.private_key) + + +def test_takes_a_replacement_password_from_new_password_or_the_prompt_only( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + + # The variable holds the current password and is not reused as the new one. + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted")) == "PASSWORD_REQUIRED" + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + sandbox.terminal = True + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", prompt=False)) == "PASSWORD_REQUIRED" + sandbox.answers.extend([OTHER_PASSWORD, OTHER_PASSWORD]) + rekeyed = keystore.protect(dir=sandbox.dir, storage="encrypted", save_password=True) + assert len(sandbox.prompts) == 2 + assert sandbox.security.entries.get(saved_password_entry(rekeyed.path)) == OTHER_PASSWORD.encode("utf-8").hex() + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", OTHER_PASSWORD) + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_sets_the_first_password_from_new_password_password_then_the_variable( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + keystore.protect(dir=sandbox.dir, storage="encrypted", prompt=False) + monkeypatch.delenv("ALEO_ACCOUNT_PASSWORD") + check_secret(keystore.export(dir=sandbox.dir, password=PASSWORD), account.private_key) + + keystore.protect(dir=sandbox.dir, storage="plaintext", password=PASSWORD) + keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, new_password=OTHER_PASSWORD) + check_secret(keystore.export(dir=sandbox.dir, password=OTHER_PASSWORD), account.private_key) + + keystore.protect(dir=sandbox.dir, storage="plaintext", password=OTHER_PASSWORD) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", prompt=False)) == "PASSWORD_REQUIRED" + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "plaintext" + + # With no new_password, the password argument is the one to set. + keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, prompt=False) + check_secret(keystore.export(dir=sandbox.dir, password=PASSWORD), account.private_key) + + +def test_keeps_the_account_usable_when_the_current_password_is_wrong(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + data = stored.path.read_bytes() + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="plaintext", password=OTHER_PASSWORD)) == "WRONG_PASSWORD" + assert stored.path.read_bytes() == data + + +def test_reports_a_wrong_current_password_before_a_missing_new_one(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + assert ( + code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=OTHER_PASSWORD, prompt=False)) + == "WRONG_PASSWORD" + ) + assert ( + code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, prompt=False)) + == "PASSWORD_REQUIRED" + ) + + +def test_leaves_a_saved_password_alone_until_the_new_storage_reads_back(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + saved = dict(sandbox.security.entries) + data = (sandbox.dir / "default.json").read_bytes() + sandbox.security.force(lambda args: (1, "") if args[0] == "-i" else None) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="keychain", prompt=False)) == "KEYCHAIN_FAILED" + assert sandbox.security.entries == saved + assert (sandbox.dir / "default.json").read_bytes() == data + sandbox.security.force(None) + check_secret(keystore.export(dir=sandbox.dir, prompt=False), account.private_key) + + +def test_returns_without_rewriting_when_the_storage_is_already_in_place(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + before = os.stat(stored.path) + assert keystore.protect(dir=sandbox.dir, storage="plaintext") == stored + assert os.stat(stored.path).st_ino == before.st_ino + + keystore.protect(dir=sandbox.dir, storage="keychain") + sandbox.security.calls.clear() + assert keystore.protect(dir=sandbox.dir, storage="keychain").storage == "keychain" + assert sandbox.security.calls == [] + + +def test_does_not_move_an_account_to_none_and_needs_a_stored_key(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="none")) == "UNSUPPORTED_STORAGE" # type: ignore[arg-type] + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "plaintext" + + keystore.save(account.private_key, dir=sandbox.dir, name="address-only", storage="none") + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, name="address-only", storage="plaintext")) == "KEY_NOT_STORED" + assert code_of(lambda: keystore.protect(dir=sandbox.dir, name="absent", storage="plaintext")) == "ACCOUNT_NOT_FOUND" + + +def test_keeps_the_old_secret_when_the_new_storage_cannot_be_written(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + sandbox.security.force(lambda args: (1, "") if args[0] == "-i" else None) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="keychain")) == "KEYCHAIN_FAILED" + assert stored.path.read_bytes() == data + + +def _vanishing_entry() -> Callable[[Sequence[str]], Optional[Any]]: + """The entry is looked for, written and confirmed, then disappears before the check.""" + finds: List[int] = [] + + def override(args: Sequence[str]) -> Optional[Any]: + if args[0] != "find-generic-password": + return None + finds.append(1) + return (44, "") if len(finds) >= 3 else None + + return override + + +def test_puts_the_original_file_back_when_the_new_storage_does_not_read_back(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + sandbox.security.force(_vanishing_entry()) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="keychain")) == "KEYCHAIN_ITEM_NOT_FOUND" + assert stored.path.read_bytes() == data + if POSIX: + assert mode(stored.path) == 0o600 + assert os.listdir(sandbox.dir) == ["default.json"] + sandbox.security.force(None) + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_removes_the_new_keychain_entry_when_the_new_storage_does_not_read_back(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + finds = {"count": 0} + + def another_key_on_read_back(args: Any) -> Any: + if args[0] != "find-generic-password": + return None + finds["count"] += 1 + # The write is confirmed, then the read-back sees another key. + return (0, f"{new_account().private_key}\n") if finds["count"] >= 3 else None + + sandbox.security.force(another_key_on_read_back) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="keychain")) == "ADDRESS_MISMATCH" + assert stored.path.read_bytes() == data + assert f"{KEY_SERVICE} {account.address}" not in sandbox.security.entries + + +def test_goes_back_to_the_original_file_when_the_new_password_cannot_be_saved(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + data = stored.path.read_bytes() + # Reading the saved password works; writing the new one does not. + sandbox.security.force(lambda args: (1, "") if args[0] == "-i" else None) + assert ( + code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", new_password=OTHER_PASSWORD, save_password=True, prompt=False)) + == "KEYCHAIN_FAILED" + ) + sandbox.security.force(None) + assert stored.path.read_bytes() == data + # The original saved password is untouched, so an unattended load still works. + assert sandbox.security.entries == {saved_password_entry(stored.path): PASSWORD.encode("utf-8").hex()} + check_secret(keystore.export(dir=sandbox.dir, prompt=False), account.private_key) + assert code_of(lambda: keystore.export(dir=sandbox.dir, password=OTHER_PASSWORD, prompt=False)) == "WRONG_PASSWORD" + + +def test_keeps_the_encrypted_file_when_the_saved_password_cannot_be_removed(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + data = stored.path.read_bytes() + sandbox.security.force(lambda args: (1, "") if args[0] == "delete-generic-password" else None) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="plaintext", prompt=False)) == "KEYCHAIN_FAILED" + sandbox.security.force(None) + # Still encrypted, and the saved password still unlocks it. + assert stored.path.read_bytes() == data + check_secret(keystore.export(dir=sandbox.dir, prompt=False), account.private_key) + + +def test_keeps_the_keychain_key_until_a_move_out_of_the_keychain_has_fully_succeeded(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + data = stored.path.read_bytes() + # Saving the password of the new encrypted file fails. + sandbox.security.force(lambda args: (1, "") if args[0] == "-i" else None) + assert ( + code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True, prompt=False)) + == "KEYCHAIN_FAILED" + ) + sandbox.security.force(None) + assert stored.path.read_bytes() == data + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +# --------------------------------------------------------------------------- +# Storing a new account never replaces a file +# --------------------------------------------------------------------------- + + +def test_creates_a_file_exclusively_and_leaves_an_existing_one_untouched(sandbox: Sandbox) -> None: + from aleo.keystore._file import write_file_exclusive + + sandbox.dir.mkdir(parents=True) + path = sandbox.dir / "exclusive.json" + write_file_exclusive(str(path), "first") + with pytest.raises(FileExistsError): + write_file_exclusive(str(path), "second") + assert path.read_text(encoding="utf-8") == "first" + if POSIX: + assert mode(path) == 0o600 + # No temporary file is left behind by either call. + assert os.listdir(sandbox.dir) == ["exclusive.json"] + + +def _plaintext_file(account: Any) -> Dict[str, Any]: + return {"version": 1, "address": account.address, "key": {"type": "plaintext", "privateKey": account.private_key}} + + +def test_removes_the_keychain_entry_it_wrote_when_another_account_takes_the_name_first(sandbox: Sandbox) -> None: + mine = new_account() + theirs = new_account() + + def other_account_appears(args: Any) -> Any: + # The other account appears between the existence check and the write. + if args[0] == "-i" and not (sandbox.dir / "default.json").exists(): + sandbox.put("default", _plaintext_file(theirs)) + return None + + sandbox.security.force(other_account_appears) + error = failure(lambda: keystore.save(mine.private_key, dir=sandbox.dir, storage="keychain")) + assert error.code == "ACCOUNT_EXISTS" + assert mine.address in str(error) + assert sandbox.security.entries == {} + check_secret(keystore.export(dir=sandbox.dir), theirs.private_key) + assert os.listdir(sandbox.dir) == ["default.json"] + + +def test_accepts_the_same_account_in_the_same_storage_stored_by_another_process_meanwhile(sandbox: Sandbox) -> None: + account = new_account() + their_entry = f"{account.address}-{'ab' * 16}" + + def same_account_appears(args: Any) -> Any: + # The other process stores the same account, with a Keychain entry of its own. + if args[0] == "-i" and not (sandbox.dir / "default.json").exists(): + sandbox.security.entries[f"{KEY_SERVICE} {their_entry}"] = account.private_key + sandbox.put("default", {"version": 1, "address": account.address, "key": {"type": "keychain", "service": KEY_SERVICE, "account": their_entry}}) + return None + + sandbox.security.force(same_account_appears) + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + assert (stored.name, stored.address, stored.storage) == ("default", account.address, "keychain") + # The entry made for the file that was never created is gone; the winner's is untouched. + assert list(sandbox.security.entries) == [f"{KEY_SERVICE} {their_entry}"] + sandbox.security.force(None) + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_removes_the_keychain_entry_when_the_account_file_cannot_be_created(sandbox: Sandbox) -> None: + account = new_account() + # A file where the accounts directory should be makes the write fail. + sandbox.dir.write_text("not a directory", encoding="utf-8") + with pytest.raises(OSError): + keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + assert sandbox.security.entries == {} + + +# --------------------------------------------------------------------------- +# Keychain entries shared between account files +# --------------------------------------------------------------------------- + + +def test_leaves_another_account_files_key_alone_when_a_later_save_of_the_same_account_fails(sandbox: Sandbox) -> None: + account = new_account() + original = keystore.save(account.private_key, dir=sandbox.dir, name="original", storage="keychain") + # The same account is saved again where the file cannot be created. + blocked = sandbox.root / "blocked" + blocked.write_text("not a directory", encoding="utf-8") + with pytest.raises(OSError): + keystore.save(account.private_key, dir=blocked, name="copy", storage="keychain") + # The failed save made and removed an entry of its own; the original's is untouched. + assert list(sandbox.security.entries) == [key_entry(original.path)] + check_secret(keystore.export(dir=sandbox.dir, name="original"), account.private_key) + + +def test_does_not_let_a_failed_save_remove_the_key_of_a_save_that_succeeds_alongside_it(sandbox: Sandbox) -> None: + account = new_account() + saved: List[Any] = [] + + def second_save_runs_in_between(args: Any) -> Any: + # Once the first save is writing its Keychain entry, a second save of + # the same account runs to completion, and the first one's file can + # then no longer be created. + if args[0] == "-i" and not saved: + saved.append(None) + saved[0] = keystore.save(account.private_key, dir=sandbox.dir, name="b", storage="keychain") + (sandbox.dir / "a.json").mkdir() + return None + + sandbox.security.force(second_save_runs_in_between) + with pytest.raises(OSError): + keystore.save(account.private_key, dir=sandbox.dir, name="a", storage="keychain") + sandbox.security.force(None) + # Neither save can adopt the other's entry, so the failed one removes only its own. + assert list(sandbox.security.entries) == [key_entry(saved[0].path)] + check_secret(keystore.export(dir=sandbox.dir, name="b"), account.private_key) + + +def test_gives_two_account_files_for_one_account_separate_key_entries(sandbox: Sandbox) -> None: + account = new_account() + first = keystore.save(account.private_key, dir=sandbox.dir, name="first", storage="keychain") + second = keystore.save(account.private_key, dir=sandbox.dir, name="second", storage="keychain") + assert key_entry(first.path) != key_entry(second.path) + assert len(sandbox.security.entries) == 2 + assert sandbox.security.labels[key_entry(first.path)] == "aleo-account-key:first" + assert sandbox.security.labels[key_entry(second.path)] == "aleo-account-key:second" + + +def test_removes_only_its_own_key_entry_when_one_of_two_files_for_an_account_leaves_the_keychain(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, name="first", storage="keychain") + second = keystore.save(account.private_key, dir=sandbox.dir, name="second", storage="keychain") + keystore.protect(dir=sandbox.dir, name="first", storage="plaintext") + assert list(sandbox.security.entries) == [key_entry(second.path)] + check_secret(keystore.export(dir=sandbox.dir, name="second"), account.private_key) + keystore.protect(dir=sandbox.dir, name="second", storage="plaintext") + assert sandbox.security.entries == {} + + +def test_leaves_the_same_account_in_another_directory_working_when_one_leaves_the_keychain(sandbox: Sandbox) -> None: + account = new_account() + elsewhere = sandbox.root / "other-project" + keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + other = keystore.save(account.private_key, dir=elsewhere, storage="keychain") + keystore.protect(dir=sandbox.dir, storage="plaintext") + # The other directory's file has its own entry, which nothing here touched. + assert list(sandbox.security.entries) == [key_entry(other.path)] + check_secret(keystore.export(dir=elsewhere), account.private_key) + + +def test_keeps_the_key_entry_while_a_copy_of_the_keychain_account_file_remains_beside_it(sandbox: Sandbox) -> None: + account = new_account() + original = keystore.save(account.private_key, dir=sandbox.dir, name="original", storage="keychain") + (sandbox.dir / "copy.json").write_bytes(original.path.read_bytes()) + keystore.protect(dir=sandbox.dir, name="original", storage="plaintext") + # The copy points at the same entry, so it still finds the key. + check_secret(keystore.export(dir=sandbox.dir, name="copy"), account.private_key) + keystore.protect(dir=sandbox.dir, name="copy", storage="plaintext") + assert sandbox.security.entries == {} + + +def test_keeps_the_key_of_a_neighbouring_file_when_a_failed_move_into_the_keychain_is_undone(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, name="first", storage="keychain") + second = keystore.save(account.private_key, dir=sandbox.dir, name="second") + data = second.path.read_bytes() + finds = {"count": 0} + + def read_back_fails(args: Any) -> Any: + if args[0] != "find-generic-password": + return None + finds["count"] += 1 + # The existing entry is seen, then the read-back fails. + return (51, "") if finds["count"] >= 2 else None + + sandbox.security.force(read_back_fails) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, name="second", storage="keychain")) == "KEYCHAIN_FAILED" + sandbox.security.force(None) + assert second.path.read_bytes() == data + check_secret(keystore.export(dir=sandbox.dir, name="first"), account.private_key) + + +def test_gives_each_encrypted_file_its_own_saved_password(sandbox: Sandbox) -> None: + account = new_account() + first = keystore.save(account.private_key, dir=sandbox.dir, name="first", storage="encrypted", password=PASSWORD, save_password=True) + second = keystore.save(account.private_key, dir=sandbox.dir, name="second", storage="encrypted", password=OTHER_PASSWORD, save_password=True) + assert saved_password_entry(first.path) != saved_password_entry(second.path) + assert len(sandbox.security.entries) == 2 + # Both open unattended, each with its own password. + for name in ("first", "second"): + check_secret(keystore.export(dir=sandbox.dir, name=name, prompt=False), account.private_key) + # Changing one file's password leaves the other's saved password alone. + keystore.protect(dir=sandbox.dir, name="first", storage="encrypted", new_password="a third test password", prompt=False) + assert len(sandbox.security.entries) == 1 + check_secret(keystore.export(dir=sandbox.dir, name="second", prompt=False), account.private_key) + + +def test_does_not_consult_the_saved_password_of_another_file_for_the_same_address(sandbox: Sandbox) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, name="saved", storage="encrypted", password=PASSWORD, save_password=True) + keystore.save(account.private_key, dir=sandbox.dir, name="unsaved", storage="encrypted", password=OTHER_PASSWORD) + # No saved password of its own: the load asks for one instead of failing on the neighbour's. + assert code_of(lambda: keystore.load(dir=sandbox.dir, name="unsaved", prompt=False)) == "PASSWORD_REQUIRED" + sandbox.terminal = True + sandbox.answers.append(OTHER_PASSWORD) + assert keystore.load(dir=sandbox.dir, name="unsaved").address == account.address + + +def test_keeps_the_saved_password_while_a_copy_of_the_encrypted_file_remains(sandbox: Sandbox) -> None: + account = new_account() + original = keystore.save(account.private_key, dir=sandbox.dir, name="original", storage="encrypted", password=PASSWORD, save_password=True) + (sandbox.dir / "copy.json").write_bytes(original.path.read_bytes()) + keystore.protect(dir=sandbox.dir, name="original", storage="plaintext", prompt=False) + # The copy has the same salt, so it still finds the saved password. + check_secret(keystore.export(dir=sandbox.dir, name="copy", prompt=False), account.private_key) + keystore.protect(dir=sandbox.dir, name="copy", storage="plaintext", prompt=False) + assert sandbox.security.entries == {} + + +def test_goes_back_to_keychain_storage_when_the_old_key_cannot_be_removed(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + data = stored.path.read_bytes() + sandbox.security.force(lambda args: (1, "") if args[0] == "delete-generic-password" else None) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="plaintext")) == "KEYCHAIN_FAILED" + sandbox.security.force(None) + # The rejected operation left the account exactly as it was. + assert stored.path.read_bytes() == data + info = keystore.info(dir=sandbox.dir) + assert info is not None and info.storage == "keychain" + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_removes_the_new_saved_password_when_a_move_to_encrypted_storage_is_undone(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + data = stored.path.read_bytes() + # The new file and its saved password are written, then the old key cannot be removed. + sandbox.security.force(lambda args: (1, "") if args[0] == "delete-generic-password" and args[2] == KEY_SERVICE else None) + assert ( + code_of(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True, prompt=False)) + == "KEYCHAIN_FAILED" + ) + sandbox.security.force(None) + assert stored.path.read_bytes() == data + # Only the original key entry is left. + assert list(sandbox.security.entries) == [key_entry(stored.path)] + + +# --------------------------------------------------------------------------- +# One process changes an account file at a time +# --------------------------------------------------------------------------- + + +def test_does_not_restore_a_stale_file_over_a_change_another_process_made(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir, storage="keychain") + entry = key_entry(stored.path) + interleaved: List[Any] = [] + + def other_process_changes_the_file(args: Any) -> Any: + # The first caller reads the key from the Keychain. Before it goes on, + # another process moves the same account to plaintext, which removes + # the Keychain entry the first caller has just read. + if args[0] == "find-generic-password" and not interleaved: + value = sandbox.security.entries[entry] + # Marked first, so the other process's own Keychain reads pass through. + interleaved.append(None) + interleaved[0] = keystore.protect(dir=sandbox.dir, storage="plaintext") + return 0, f"{value}\n" + return None + + sandbox.security.force(other_process_changes_the_file) + error = failure(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, prompt=False)) + sandbox.security.force(None) + assert error.code == "ACCOUNT_BUSY" + assert str(stored.path) in str(error) + # The other process's result stands: the stale Keychain pointer was not put back. + assert interleaved[0].storage == "plaintext" + info = keystore.info(dir=sandbox.dir) + assert info is not None and info.storage == "plaintext" + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + assert sandbox.security.entries == {} + assert os.listdir(sandbox.dir) == ["default.json"] + + +def test_waits_for_the_lock_and_gives_up_with_account_busy(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + lock = sandbox.dir / "default.json.lock" + lock.write_bytes(b"") + monkeypatch.setattr(runtime, "lock_wait_seconds", 0.2) + error = failure(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, prompt=False)) + assert error.code == "ACCOUNT_BUSY" + assert str(lock) in str(error) + # Nothing was changed, and the other process's lock was left alone. + assert stored.path.read_bytes() == data + assert lock.exists() + + # Once the lock is released, the same call goes through and leaves no lock behind. + lock.unlink() + assert keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, prompt=False).storage == "encrypted" + assert os.listdir(sandbox.dir) == ["default.json"] + + +def test_never_removes_a_lock_on_its_own_however_old_it_is(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + lock = sandbox.dir / "default.json.lock" + lock.write_bytes(b"") + long_ago = time.time() - 7 * 24 * 3600 + os.utime(lock, (long_ago, long_ago)) + monkeypatch.setattr(runtime, "lock_wait_seconds", 0.2) + # Two waiting callers that both removed an old lock would both go ahead. + error = failure(lambda: keystore.protect(dir=sandbox.dir, storage="encrypted", password=PASSWORD, prompt=False)) + assert error.code == "ACCOUNT_BUSY" + assert str(lock) in str(error) + assert lock.exists() + assert stored.path.read_bytes() == data + + +def test_releases_the_lock_when_the_change_fails(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + data = stored.path.read_bytes() + sandbox.security.force(lambda args: (1, "") if args[0] == "-i" else None) + assert code_of(lambda: keystore.protect(dir=sandbox.dir, storage="keychain")) == "KEYCHAIN_FAILED" + sandbox.security.force(None) + assert stored.path.read_bytes() == data + assert os.listdir(sandbox.dir) == ["default.json"] + # The next change is not blocked. + assert keystore.protect(dir=sandbox.dir, storage="keychain").storage == "keychain" + + +# --------------------------------------------------------------------------- +# export +# --------------------------------------------------------------------------- + + +def test_returns_the_stored_key_and_never_reads_the_key_variables(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_fails_when_there_is_no_file_or_no_stored_key(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + assert code_of(lambda: keystore.export(dir=sandbox.dir)) == "ACCOUNT_NOT_FOUND" + keystore.save(account.private_key, dir=sandbox.dir, storage="none") + assert code_of(lambda: keystore.export(dir=sandbox.dir)) == "KEY_NOT_STORED" + + +# --------------------------------------------------------------------------- +# migrate +# --------------------------------------------------------------------------- + + +def legacy_content(field: str, key: str) -> Dict[str, Any]: + return { + "address": "placeholder", + field: key, + "apiUrl": "https://example.test", + "accessRedeemed": True, + "nested": {"b": 1, "a": [1, 2]}, + } + + +def legacy_text(field: str, key: str) -> str: + return json.dumps(legacy_content(field, key), indent=2) + "\n" + + +@pytest.mark.parametrize("field", ["privateKey", "private_key"]) +def test_copies_the_field_into_an_account_file_and_keeps_the_legacy_file(sandbox: Sandbox, field: str) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text(legacy_text(field, account.private_key), encoding="utf-8") + before = source.read_bytes() + + migrated = keystore.migrate(source, dir=sandbox.dir) + assert migrated == StoredAccount( + name="default", path=sandbox.dir / "default.json", address=account.address, storage="plaintext" + ) + assert source.read_bytes() == before + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def _both_fields(first: str, second: str) -> str: + content = {"address": "placeholder", "privateKey": first, "network": "testnet", "private_key": second, "endpoint": "https://example.test"} + return json.dumps(content, indent=2) + "\n" + + +def test_removes_both_fields_when_a_legacy_file_holds_the_same_key_in_each(sandbox: Sandbox) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text(_both_fields(account.private_key, account.private_key), encoding="utf-8") + assert keystore.migrate(str(source), dir=sandbox.dir, remove_legacy_key=True).address == account.address + expected = {"address": "placeholder", "network": "testnet", "endpoint": "https://example.test"} + assert source.read_text(encoding="utf-8") == json.dumps(expected, indent=2) + "\n" + check_secret(keystore.export(dir=sandbox.dir), account.private_key) + + +def test_refuses_a_legacy_file_whose_two_fields_hold_different_keys(sandbox: Sandbox) -> None: + first = new_account() + second = new_account() + source = sandbox.root / "state.json" + text = _both_fields(first.private_key, second.private_key) + source.write_text(text, encoding="utf-8") + for removing in (False, True): + error = failure(lambda: keystore.migrate(str(source), dir=sandbox.dir, remove_legacy_key=removing)) + assert error.code == "KEY_CONFLICT" + assert first.address in str(error) and second.address in str(error) + assert "APrivateKey1" not in str(error) + assert source.read_text(encoding="utf-8") == text + assert not sandbox.dir.exists() + + +def test_fails_with_invalid_key_when_the_second_legacy_field_is_not_a_key(sandbox: Sandbox) -> None: + source = sandbox.root / "state.json" + source.write_text(_both_fields(new_account().private_key, "APrivateKey1nope"), encoding="utf-8") + assert code_of(lambda: keystore.migrate(str(source), dir=sandbox.dir)) == "INVALID_KEY" + assert not sandbox.dir.exists() + + +def test_strips_the_key_field_and_keeps_the_other_fields_their_order_and_the_indentation(sandbox: Sandbox) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text(legacy_text("privateKey", account.private_key), encoding="utf-8") + source.chmod(0o644) + + migrated = keystore.migrate(source, dir=sandbox.dir, storage="encrypted", password=PASSWORD, remove_legacy_key=True) + assert migrated.storage == "encrypted" + # What JSON.stringify(rest, null, 2) + "\n" produces for the remaining fields. + expected = ( + "{\n" + ' "address": "placeholder",\n' + ' "apiUrl": "https://example.test",\n' + ' "accessRedeemed": true,\n' + ' "nested": {\n' + ' "b": 1,\n' + ' "a": [\n' + " 1,\n" + " 2\n" + " ]\n" + " }\n" + "}\n" + ) + assert source.read_text(encoding="utf-8") == expected + if POSIX: + assert mode(source) == 0o600 + assert sorted(os.listdir(sandbox.root)) == ["accounts", "home", "state.json"] + check_secret(keystore.export(dir=sandbox.dir, password=PASSWORD), account.private_key) + + # The key is gone, so a second run finds nothing to migrate. + assert code_of(lambda: keystore.migrate(source, dir=sandbox.dir)) == "LEGACY_KEY_NOT_FOUND" + + +def test_keeps_four_space_tab_one_space_and_single_line_layouts(sandbox: Sandbox) -> None: + account = new_account() + key = account.private_key + # Each pair is the file before and what JSON.stringify writes without the key. + cases = [ + ( + '{\n "network": "testnet",\n "private_key": "' + key + '",\n "endpoint": "https://example.test"\n}', + '{\n "network": "testnet",\n "endpoint": "https://example.test"\n}', + ), + ( + '{\n\t"network": "testnet",\n\t"private_key": "' + key + '",\n\t"endpoint": "https://example.test"\n}\n', + '{\n\t"network": "testnet",\n\t"endpoint": "https://example.test"\n}\n', + ), + ( + '{"network":"testnet","private_key":"' + key + '","endpoint":"https://example.test"}', + '{"network":"testnet","endpoint":"https://example.test"}', + ), + ( + '{\n "network": "testnet",\n "private_key": "' + key + '",\n "endpoint": "https://example.test"\n}\n', + '{\n "network": "testnet",\n "endpoint": "https://example.test"\n}\n', + ), + ( + # Written by Python's json.dumps on one line: re-rendered without spaces. + '{"network": "testnet", "private_key": "' + key + '", "endpoint": "https://example.test"}\n', + '{"network":"testnet","endpoint":"https://example.test"}\n', + ), + ( + # Windows line endings select the layout; the rewrite uses LF. + '{\r\n "network": "testnet",\r\n "private_key": "' + key + '"\r\n}\r\n', + '{\n "network": "testnet"\n}\n', + ), + ( + # Nothing but the key: an empty object, as JSON.stringify writes it. + '{\n "private_key": "' + key + '"\n}\n', + "{}\n", + ), + ( + # Indentation beyond ten characters is cut to ten, the JSON.stringify limit. + '{\n "private_key": "' + key + '",\n "a": [],\n "b": {}\n}', + '{\n "a": [],\n "b": {}\n}', + ), + ] + for index, (before, after) in enumerate(cases): + source = sandbox.root / f"profile-{index}.json" + source.write_bytes(before.encode("utf-8")) + keystore.migrate(source, dir=sandbox.dir, remove_legacy_key=True) + assert source.read_bytes() == after.encode("utf-8"), f"layout {index}" + + +def test_keeps_text_outside_ascii_and_escapes_as_json_stringify_does(sandbox: Sandbox) -> None: + account = new_account() + source = sandbox.root / "state.json" + # A non-ASCII letter stays as written; an escaped control character keeps + # its short escape; an escaped lone surrogate keeps its escaped form. + before = ( + '{"privateKey":"' + account.private_key + '","label":"caf\N{LATIN SMALL LETTER E WITH ACUTE} \\u00e9",' + '"tab":"a\\tb\\u0001","lone":"\\ud83d","slash":"a\\/b"}' + ) + after = ( + '{"label":"caf\N{LATIN SMALL LETTER E WITH ACUTE} \N{LATIN SMALL LETTER E WITH ACUTE}",' + '"tab":"a\\tb\\u0001","lone":"\\ud83d","slash":"a/b"}' + ) + source.write_bytes(before.encode("utf-8")) + keystore.migrate(source, dir=sandbox.dir, remove_legacy_key=True) + assert source.read_bytes() == after.encode("utf-8") + + +def test_follows_the_rules_of_save_for_an_existing_account_file(sandbox: Sandbox) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text(legacy_text("privateKey", account.private_key), encoding="utf-8") + + keystore.save(Account.random(), dir=sandbox.dir) + assert code_of(lambda: keystore.migrate(source, dir=sandbox.dir, remove_legacy_key=True)) == "ACCOUNT_EXISTS" + assert account.private_key in source.read_text(encoding="utf-8") + + keystore.save(account.private_key, dir=sandbox.dir, name="mine") + assert code_of(lambda: keystore.migrate(source, dir=sandbox.dir, name="mine", storage="keychain")) == "ACCOUNT_EXISTS" + migrated = keystore.migrate(source, dir=sandbox.dir, name="mine", remove_legacy_key=True) + assert migrated.storage == "plaintext" + absent(source.read_text(encoding="utf-8"), account.private_key) + + +def test_keeps_the_legacy_key_when_the_new_account_does_not_read_back(sandbox: Sandbox) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text(legacy_text("privateKey", account.private_key), encoding="utf-8") + sandbox.security.force(_vanishing_entry()) + assert ( + code_of(lambda: keystore.migrate(source, dir=sandbox.dir, storage="keychain", remove_legacy_key=True)) + == "KEYCHAIN_ITEM_NOT_FOUND" + ) + assert account.private_key in source.read_text(encoding="utf-8") + + +def test_does_not_strip_the_legacy_key_for_an_address_only_account(sandbox: Sandbox) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text(legacy_text("privateKey", account.private_key), encoding="utf-8") + assert ( + code_of(lambda: keystore.migrate(source, dir=sandbox.dir, storage="none", remove_legacy_key=True)) + == "KEY_NOT_STORED" + ) + assert not sandbox.dir.exists() + assert keystore.migrate(source, dir=sandbox.dir, storage="none").storage == "none" + assert account.private_key in source.read_text(encoding="utf-8") + + +@pytest.mark.parametrize( + "content", + [ + pytest.param(None, id="a missing file"), + pytest.param('{"privateKey": "APrivateKey1', id="text that is not JSON"), + pytest.param("[]", id="an array"), + pytest.param('{"address": "aleo1x"}', id="a file without a key field"), + pytest.param('{"privateKey": ""}', id="an empty key field"), + pytest.param('{"account": {"privateKey": "APrivateKey1x"}}', id="a nested key field"), + pytest.param('{"private_key": 7}', id="a key field that is not a string"), + pytest.param(b'{"privateKey": "APrivateKey1\xff"}', id="bytes that are not UTF-8"), + ], +) +def test_fails_with_legacy_key_not_found(sandbox: Sandbox, content: Any) -> None: + source = sandbox.root / "state.json" + if content is not None: + source.write_bytes(content if isinstance(content, bytes) else content.encode("utf-8")) + error = failure(lambda: keystore.migrate(source, dir=sandbox.dir)) + assert error.code == "LEGACY_KEY_NOT_FOUND" + assert str(source) in str(error) + assert "APrivateKey1" not in str(error) + assert error.__context__ is None or isinstance(error.__context__, OSError) + assert not sandbox.dir.exists() + + +def test_fails_with_invalid_key_for_a_legacy_key_that_cannot_be_parsed(sandbox: Sandbox) -> None: + source = sandbox.root / "state.json" + source.write_text('{"privateKey": "APrivateKey1nope"}', encoding="utf-8") + assert code_of(lambda: keystore.migrate(source, dir=sandbox.dir)) == "INVALID_KEY" + + +# --------------------------------------------------------------------------- +# The terminal and the security tool +# --------------------------------------------------------------------------- + + +def test_hidden_prompt_reads_a_line_through_the_terminal_and_not_standard_output( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + seen: List[Any] = [] + + def fake_getpass(prompt: str = "", stream: Any = None) -> str: + seen.append((prompt, stream)) + return "typed" + + monkeypatch.setattr(getpass, "getpass", fake_getpass) + assert sandbox.real.prompt_hidden("Password: ") == "typed" + assert seen == [("Password: ", sys.stderr)] + assert capsys.readouterr().out == "" + + +@pytest.mark.parametrize("interruption", [EOFError, KeyboardInterrupt]) +def test_hidden_prompt_fails_with_password_required_when_cancelled_or_when_the_input_ends( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, interruption: type +) -> None: + def fake_getpass(prompt: str = "", stream: Any = None) -> str: + raise interruption() + + monkeypatch.setattr(getpass, "getpass", fake_getpass) + error = failure(lambda: sandbox.real.prompt_hidden("Password: ")) + assert error.code == "PASSWORD_REQUIRED" + + +def test_notes_go_to_standard_error(sandbox: Sandbox, capsys: pytest.CaptureFixture[str]) -> None: + sandbox.real.notify("Wrong password.") + captured = capsys.readouterr() + assert captured.out == "" + assert captured.err == "Wrong password.\n" + + +def test_no_terminal_is_attached_when_the_streams_are_not_terminals(sandbox: Sandbox, capsys: pytest.CaptureFixture[str]) -> None: + # Under capture neither stream is a terminal. + assert sandbox.real.terminal_attached() is False + assert sandbox.real.output_is_terminal() is False + + +@posix_only +def test_runs_the_security_tool_by_its_full_path_with_the_command_on_standard_input( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + assert runtime_module.SECURITY_PATH == "/usr/bin/security" + assert runtime_module.SECURITY_TIMEOUT_SECONDS == 15 + tool = sandbox.root / "tool" + tool.write_text('#!/bin/sh\nprintf "%s|" "$@"\ncat\necho "noise" >&2\nexit 7\n', encoding="utf-8") + tool.chmod(0o700) + monkeypatch.setattr(runtime_module, "SECURITY_PATH", str(tool)) + assert sandbox.real.security(["-i"], "add-generic-password -U\n") == (7, "-i|add-generic-password -U\n") + assert sandbox.real.security(["find-generic-password", "-w"], None) == (7, "find-generic-password|-w|") + + +@posix_only +def test_reports_a_tool_that_cannot_start_hangs_or_is_killed_as_having_no_status( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(runtime_module, "SECURITY_PATH", str(sandbox.root / "absent")) + assert sandbox.real.security(["-i"], None) == (None, "") + + slow = sandbox.root / "slow" + slow.write_text("#!/bin/sh\nsleep 5\n", encoding="utf-8") + slow.chmod(0o700) + monkeypatch.setattr(runtime_module, "SECURITY_PATH", str(slow)) + monkeypatch.setattr(runtime_module, "SECURITY_TIMEOUT_SECONDS", 0.2) + assert sandbox.real.security(["-i"], None) == (None, "") + + killed = sandbox.root / "killed" + killed.write_text("#!/bin/sh\nkill -9 $$\n", encoding="utf-8") + killed.chmod(0o700) + monkeypatch.setattr(runtime_module, "SECURITY_PATH", str(killed)) + assert sandbox.real.security(["-i"], None) == (None, "") + + +def test_refuses_a_keychain_value_that_cannot_be_passed_unquoted(sandbox: Sandbox) -> None: + from aleo.keystore._keychain import write_keychain + + for address, value in (("aleo1x", "two words"), ("aleo1 x", "value"), ("aleo1x", "quote\"d"), ("aleo1x", "")): + assert code_of(lambda: write_keychain(KEY_SERVICE, address, value, "default")) == "KEYCHAIN_FAILED" + # The account name goes into the label unquoted, so it is held to the same rule. + for name in ("two words", "quote\"d", "", "Upper", "a\n"): + assert code_of(lambda: write_keychain(KEY_SERVICE, "aleo1x", "value", name)) == "KEYCHAIN_FAILED" + assert sandbox.security.calls == [] + + +# --------------------------------------------------------------------------- +# The real macOS Keychain +# --------------------------------------------------------------------------- + + +@pytest.mark.skipif( + os.environ.get("ALEO_KEYSTORE_KEYCHAIN_TEST") != "1" or sys.platform != "darwin", + reason="set ALEO_KEYSTORE_KEYCHAIN_TEST=1 on macOS to exercise the real Keychain", +) +def test_stores_reads_and_removes_the_sample_account_through_the_real_keychain( + sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch +) -> None: + """Uses the public sample account only and deletes both of its entries afterwards.""" + # Undo the stand-ins for this test only. + monkeypatch.setattr(runtime, "platform", sandbox.real.platform) + monkeypatch.setattr(runtime, "security", sandbox.real.security) + # The security tool finds the login keychain through HOME. Account files + # still go to the temporary directory passed as ``dir``. + if sandbox.real_home is not None: + monkeypatch.setenv("HOME", sandbox.real_home) + + # Every entry is named after its own file, so each one this test makes is + # recorded, checked and removed. Nothing here can touch another run's entries. + made: List[Any] = [] + + def leftovers() -> List[bool]: + return [read_keychain(service, account) is None for service, account in made] + + password = VECTORS["encrypted"]["password"] + try: + stored = keystore.save(SAMPLE.private_key, dir=sandbox.dir, name="keychain", storage="keychain") + made.append((KEY_SERVICE, key_entry_account(stored.path))) + loaded = keystore.load(dir=sandbox.dir, name="keychain", prompt=False) + assert loaded.source == "account-file" + assert loaded.address == SAMPLE.address + check_secret(loaded.private_key, SAMPLE.private_key) + + # Move to an encrypted file with the password saved: the key entry goes. + encrypted = keystore.protect( + dir=sandbox.dir, name="keychain", storage="encrypted", password=password, save_password=True, prompt=False + ) + made.append((PASSWORD_SERVICE, saved_password_account(encrypted.path))) + assert read_keychain(*made[0]) is None + assert read_keychain(*made[1]) == VECTORS["keychain"]["passwordValue"] + check_secret(keystore.export(dir=sandbox.dir, name="keychain", prompt=False), SAMPLE.private_key) + + # Back to plaintext: the saved password goes too. + keystore.protect(dir=sandbox.dir, name="keychain", storage="plaintext", prompt=False) + assert all(leftovers()) + finally: + for service, account in made: + delete_keychain(service, account) + assert all(leftovers()) diff --git a/sdk/python/tests/test_keystore_cli.py b/sdk/python/tests/test_keystore_cli.py new file mode 100644 index 0000000..0299539 --- /dev/null +++ b/sdk/python/tests/test_keystore_cli.py @@ -0,0 +1,904 @@ +"""Tests for the account commands (``python -m aleo.keystore``). + +Each command runs in-process against a temporary accounts directory, with the +environment, the home directory, the Keychain tool and the terminal replaced +(see ``keystore_helpers``). Output is captured, so the keys that ``export`` +and ``create --storage none`` print by design never reach the test log. +""" +from __future__ import annotations + +import json +import os +import subprocess +import sys +from pathlib import Path +from typing import Any, List, NamedTuple + +import pytest + +import aleo +from aleo import keystore +from aleo.keystore._cli import main +from aleo.keystore._runtime import runtime +from aleo.mainnet import PrivateKey + +from keystore_helpers import ( # noqa: F401 (sandbox is a fixture) + OTHER_PASSWORD, + PASSWORD, + POSIX, + SAMPLE, + Sandbox, + VARIABLES, + VECTORS, + absent, + check_secret, + key_entry, + mode, + new_account, + sandbox, + saved_password_entry, +) + +pytestmark = pytest.mark.usefixtures("sandbox") + +PHRASE = VECTORS["mnemonic"]["phrase"] + + +class Outcome(NamedTuple): + """What one command left behind: exit status, standard output, standard error.""" + + status: int + out: str + err: str + + @property + def json(self) -> Any: + return json.loads(self.out) + + +@pytest.fixture +def run(sandbox: Sandbox, capsys: pytest.CaptureFixture[str]): + """Run one command against the test accounts directory.""" + + def invoke(*argv: str, with_dir: bool = True) -> Outcome: + sandbox.notes.clear() + arguments: List[str] = list(argv) + if with_dir: + arguments += ["--dir", str(sandbox.dir)] + try: + status = main(arguments) + except SystemExit as exit_request: + status = exit_request.code if isinstance(exit_request.code, int) else 1 + captured = capsys.readouterr() + # Notes and errors go through the replaced terminal; usage text goes + # straight to standard error. + return Outcome(status, captured.out, captured.err + "".join(f"{note}\n" for note in sandbox.notes)) + + return invoke + + +def stored_key(sandbox: Sandbox, name: str = "default", password: Any = None) -> str: + return keystore.export(dir=sandbox.dir, name=name, password=password, prompt=False) + + +# --------------------------------------------------------------------------- +# Usage errors +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "argv", + [ + pytest.param([], id="no command"), + pytest.param(["destroy"], id="an unknown command"), + pytest.param(["show", "--verbose"], id="an unknown flag"), + pytest.param(["show", "--nam", "x"], id="an abbreviated flag"), + pytest.param(["show", "extra"], id="a stray argument"), + pytest.param(["create", "--storage", "vault"], id="an unknown storage"), + pytest.param(["create", "--password", "x"], id="a password on the command line"), + pytest.param(["protect"], id="protect without a storage"), + pytest.param(["protect", "--storage", "none"], id="protect to none"), + pytest.param(["protect", "--save-password"], id="protect saving a password without a storage"), + pytest.param(["protect", "--storage", "encrypted", "--save-password", "--forget-password"], id="save and forget"), + pytest.param(["migrate"], id="migrate without --from"), + pytest.param(["migrate", "--from", "x.json", "--storage", "none"], id="migrate to none"), + pytest.param(["import", "--key-file", "a", "--mnemonic-file", "b"], id="a key file and a phrase file"), + pytest.param(["import", "--index", "-1"], id="a negative index"), + pytest.param(["import", "--index", "2147483648"], id="an index beyond 2^31 - 1"), + pytest.param(["import", "--index", "one"], id="an index that is not a number"), + pytest.param(["import", "--derivation", "bip44"], id="an unknown derivation"), + pytest.param(["show", "--forget-password"], id="a flag of another command"), + pytest.param(["export", "--storage", "plaintext"], id="a storage on export"), + pytest.param(["create", "--name"], id="a flag without its value"), + ], +) +def test_usage_errors_exit_64(sandbox: Sandbox, run: Any, argv: List[str]) -> None: + outcome = run(*argv) + assert outcome.status == 64 + assert outcome.out == "" + assert "usage:" in outcome.err + assert not sandbox.dir.exists() + + +def test_help_exits_0(run: Any) -> None: + outcome = run("--help", with_dir=False) + assert outcome.status == 0 + for command in ("create", "import", "show", "protect", "export", "migrate"): + assert command in outcome.out + assert run("import", "--help", with_dir=False).status == 0 + + +def test_common_flags_work_before_and_after_the_command(sandbox: Sandbox, run: Any) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, name="named") + after = run("show", "--name", "named", "--json") + before = run("--json", "--name", "named", "--dir", str(sandbox.dir), "show", with_dir=False) + assert after.status == before.status == 0 + assert after.json == before.json + assert after.json["name"] == "named" + + +# --------------------------------------------------------------------------- +# Output and exit status +# --------------------------------------------------------------------------- + + +def test_show_prints_the_account_and_never_the_key(sandbox: Sandbox, run: Any) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + + outcome = run("show", "--json") + assert outcome.status == 0 + assert outcome.err == "" + assert outcome.out.count("\n") == 1 + assert outcome.json == { + "name": "default", + "address": account.address, + "storage": "plaintext", + "path": str(stored.path), + } + assert list(outcome.json) == ["name", "address", "storage", "path"] + + plain = run("show") + assert plain.status == 0 + for value in ("default", account.address, "plaintext", str(stored.path)): + assert value in plain.out + absent(plain.out + plain.err + outcome.out, account.private_key) + + +def test_show_reads_only_the_account_file(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + monkeypatch.setenv("ALEO_PRIVATE_KEY", "") + outcome = run("show", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "encrypted" + assert sandbox.security.calls == [] + assert sandbox.prompts == [] + + +def test_errors_go_to_standard_error_as_code_and_message(sandbox: Sandbox, run: Any) -> None: + outcome = run("show") + assert outcome.status == 2 + assert outcome.out == "" + assert outcome.err.startswith("ACCOUNT_NOT_FOUND: ") + assert str(sandbox.dir / "default.json") in outcome.err + + +def test_errors_go_to_standard_output_as_json_with_the_flag(sandbox: Sandbox, run: Any) -> None: + outcome = run("show", "--json") + assert outcome.status == 2 + assert outcome.err == "" + assert list(outcome.json) == ["error"] + assert list(outcome.json["error"]) == ["code", "message"] + assert outcome.json["error"]["code"] == "ACCOUNT_NOT_FOUND" + assert str(sandbox.dir / "default.json") in outcome.json["error"]["message"] + + +def test_needs_a_person_exits_2_and_other_failures_exit_1(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + # ACCOUNT_NOT_FOUND + assert run("show").status == 2 + # KEY_NOT_STORED + keystore.save(account.private_key, dir=sandbox.dir, name="address-only", storage="none") + outcome = run("protect", "--storage", "plaintext", "--name", "address-only", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (2, "KEY_NOT_STORED") + # PASSWORD_REQUIRED + outcome = run("create", "--storage", "encrypted", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (2, "PASSWORD_REQUIRED") + # TERMINAL_REQUIRED + outcome = run("export", "--name", "address-only") + assert outcome.status == 2 and outcome.err.startswith("TERMINAL_REQUIRED: ") + # Everything else is a plain failure. + keystore.save(account.private_key, dir=sandbox.dir) + outcome = run("create", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "ACCOUNT_EXISTS") + outcome = run("show", "--name", "Not_Valid", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "INVALID_NAME") + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + keystore.save(account.private_key, dir=sandbox.dir, name="locked", storage="encrypted") + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", OTHER_PASSWORD) + outcome = run("protect", "--storage", "plaintext", "--name", "locked", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "WRONG_PASSWORD") + absent(outcome.out + outcome.err, OTHER_PASSWORD) + + +def test_a_file_system_failure_exits_1(sandbox: Sandbox, run: Any) -> None: + sandbox.dir.mkdir() + (sandbox.dir / "default.json").mkdir() + outcome = run("show") + assert outcome.status == 1 + assert outcome.out == "" + assert outcome.err.startswith("aleo.keystore: ") + + +# --------------------------------------------------------------------------- +# create +# --------------------------------------------------------------------------- + + +def test_create_generates_a_key_and_stores_it_in_plaintext_by_default(sandbox: Sandbox, run: Any) -> None: + outcome = run("create", "--json") + assert outcome.status == 0 + assert list(outcome.json) == ["name", "address", "storage", "path"] + assert outcome.json["name"] == "default" + assert outcome.json["storage"] == "plaintext" + assert outcome.json["path"] == str(sandbox.dir / "default.json") + key = stored_key(sandbox) + assert str(PrivateKey.from_string(key).address) == outcome.json["address"] + absent(outcome.out + outcome.err, key) + if POSIX: + assert mode(sandbox.dir / "default.json") == 0o600 + assert mode(sandbox.dir) == 0o700 + + # A second account under another name gets another key. + other = run("create", "--name", "second") + assert other.status == 0 + assert "second" in other.out + assert stored_key(sandbox, "second") != key + absent(other.out + other.err, stored_key(sandbox, "second")) + + +def test_create_refuses_to_replace_an_existing_account(sandbox: Sandbox, run: Any) -> None: + assert run("create").status == 0 + data = (sandbox.dir / "default.json").read_bytes() + outcome = run("create") + assert outcome.status == 1 + assert outcome.err.startswith("ACCOUNT_EXISTS: ") + assert (sandbox.dir / "default.json").read_bytes() == data + + +def test_create_takes_the_name_and_directory_from_the_variables(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_ACCOUNT", "from-env") + monkeypatch.setenv("ALEO_ACCOUNTS_DIR", str(sandbox.root / "env-dir")) + outcome = run("create", "--json", with_dir=False) + assert outcome.status == 0 + assert outcome.json["path"] == str(sandbox.root / "env-dir" / "from-env.json") + + +def test_create_without_a_stored_key_needs_a_terminal_and_shows_the_key_once(sandbox: Sandbox, run: Any) -> None: + # No terminal: nothing is generated or written. + outcome = run("create", "--storage", "none") + assert outcome.status == 2 + assert outcome.err.startswith("TERMINAL_REQUIRED: ") + assert "APrivateKey1" not in outcome.out + outcome.err + assert not sandbox.dir.exists() + + # Standard output redirected: the key would land in a pipe or a file. + sandbox.terminal = True + assert run("create", "--storage", "none").status == 2 + assert not sandbox.dir.exists() + + # A key never appears with --json, even at a terminal. + sandbox.output_terminal = True + outcome = run("create", "--storage", "none", "--json") + assert outcome.status == 2 + assert outcome.json["error"]["code"] == "TERMINAL_REQUIRED" + assert "APrivateKey1" not in outcome.out + outcome.err + assert not sandbox.dir.exists() + + outcome = run("create", "--storage", "none") + assert outcome.status == 0 + shown = [word for word in outcome.out.split() if word.startswith("APrivateKey1")] + assert len(shown) == 1 + assert "APrivateKey1" not in outcome.err + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "none" + address = str(PrivateKey.from_string(shown[0]).address) + if address != stored.address: + raise AssertionError("the key shown is not the key of the stored address") + absent((sandbox.dir / "default.json").read_text(encoding="utf-8"), shown[0]) + assert "ALEO_PRIVATE_KEY" in outcome.err + + +def _phrase_shown(out: str) -> str: + """The recovery phrase a command printed, without its label.""" + lines = [line for line in out.splitlines() if line.startswith("Recovery phrase: ")] + assert len(lines) == 1 + return lines[0][len("Recovery phrase: "):] + + +def test_create_from_a_new_phrase_needs_a_terminal_and_shows_the_phrase_once(sandbox: Sandbox, run: Any) -> None: + # No terminal: nothing is generated or written. + outcome = run("create", "--mnemonic") + assert outcome.status == 2 + assert outcome.err.startswith("TERMINAL_REQUIRED: ") + assert "recovery phrase" in outcome.err + assert "Recovery phrase:" not in outcome.out + outcome.err + assert not sandbox.dir.exists() + + # Standard output redirected: the phrase would land in a pipe or a file. + sandbox.terminal = True + assert run("create", "--mnemonic").status == 2 + assert not sandbox.dir.exists() + + # A phrase never appears with --json, even at a terminal. + sandbox.output_terminal = True + outcome = run("create", "--mnemonic", "--json") + assert outcome.status == 2 + assert outcome.json["error"]["code"] == "TERMINAL_REQUIRED" + assert not sandbox.dir.exists() + + outcome = run("create", "--mnemonic") + assert outcome.status == 0 + phrase = _phrase_shown(outcome.out) + assert len(phrase.split(" ")) == 12 + assert "Recovery phrase:" not in outcome.err + assert "stored nowhere" in outcome.err + # No key is printed: the account is stored, and the phrase is the backup. + assert "APrivateKey1" not in outcome.out + outcome.err + + # The stored account is the first account of the phrase, as a wallet derives it. + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "plaintext" + client = aleo.Aleo(aleo.HTTPProvider("http://127.0.0.1:1")) + derived = client.account.from_mnemonic(phrase) + if str(derived.address) != stored.address: + raise AssertionError("the phrase shown does not derive the stored address") + if str(derived.private_key) != stored_key(sandbox): + raise AssertionError("the phrase shown does not derive the stored key") + # The phrase is in no file. + for path in sandbox.dir.iterdir(): + absent(path.read_text(encoding="utf-8"), phrase) + for word in phrase.split(" ")[:3]: + assert f" {word} " not in path.read_text(encoding="utf-8") + + +def test_create_from_a_new_phrase_makes_a_different_account_each_time(sandbox: Sandbox, run: Any) -> None: + sandbox.terminal = sandbox.output_terminal = True + first = run("create", "--mnemonic", "--name", "one") + second = run("create", "--mnemonic", "--name", "two") + assert first.status == 0 and second.status == 0 + assert _phrase_shown(first.out) != _phrase_shown(second.out) + one, two = keystore.info(dir=sandbox.dir, name="one"), keystore.info(dir=sandbox.dir, name="two") + assert one is not None and two is not None and one.address != two.address + + +def test_create_from_a_new_phrase_shows_nothing_when_the_account_cannot_be_stored(sandbox: Sandbox, run: Any) -> None: + sandbox.terminal = sandbox.output_terminal = True + assert run("create").status == 0 + before = (sandbox.dir / "default.json").read_bytes() + outcome = run("create", "--mnemonic") + assert outcome.status == 1 + assert outcome.err.startswith("ACCOUNT_EXISTS: ") + assert "Recovery phrase:" not in outcome.out + outcome.err + assert (sandbox.dir / "default.json").read_bytes() == before + + +def test_create_from_a_new_phrase_in_the_keychain_names_the_phrase_as_the_backup(sandbox: Sandbox, run: Any) -> None: + sandbox.terminal = sandbox.output_terminal = True + outcome = run("create", "--mnemonic", "--storage", "keychain", "--name", "wallet") + assert outcome.status == 0 + phrase = _phrase_shown(outcome.out) + stored = keystore.info(dir=sandbox.dir, name="wallet") + assert stored is not None and stored.storage == "keychain" + key = sandbox.security.entries[key_entry(stored.path)] + client = aleo.Aleo(aleo.HTTPProvider("http://127.0.0.1:1")) + if str(client.account.from_mnemonic(phrase).private_key) != key: + raise AssertionError("the phrase shown does not derive the key in the Keychain") + absent(outcome.out + outcome.err, key) + # The export hint is for accounts with no phrase. + assert "export" not in outcome.err + + +def test_create_from_a_new_phrase_with_no_stored_key_shows_the_phrase_and_the_key(sandbox: Sandbox, run: Any) -> None: + sandbox.terminal = sandbox.output_terminal = True + outcome = run("create", "--mnemonic", "--storage", "none") + assert outcome.status == 0 + phrase = _phrase_shown(outcome.out) + shown = [word for word in outcome.out.split() if word.startswith("APrivateKey1")] + assert len(shown) == 1 + client = aleo.Aleo(aleo.HTTPProvider("http://127.0.0.1:1")) + if str(client.account.from_mnemonic(phrase).private_key) != shown[0]: + raise AssertionError("the key shown is not the key of the phrase shown") + stored = keystore.info(dir=sandbox.dir) + assert stored is not None and stored.storage == "none" + + +def test_create_in_the_keychain_says_the_key_has_no_other_copy(sandbox: Sandbox, run: Any) -> None: + outcome = run("create", "--storage", "keychain", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "keychain" + key = sandbox.security.entries[key_entry(outcome.json["path"])] + absent(outcome.out + outcome.err, key) + assert "APrivateKey1" not in (sandbox.dir / "default.json").read_text(encoding="utf-8") + assert "export" in outcome.err + assert "Keychain" in outcome.err + + +def test_create_in_the_keychain_fails_outside_macos_before_anything_is_written( + sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(runtime, "platform", "linux") + outcome = run("create", "--storage", "keychain") + assert outcome.status == 1 + assert outcome.err.startswith("KEYCHAIN_UNAVAILABLE: ") + assert not sandbox.dir.exists() + + +def test_create_encrypted_takes_the_password_from_the_variable_or_the_prompt( + sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + # No password source and no terminal: needs a person. + assert run("create", "--storage", "encrypted").status == 2 + assert not sandbox.dir.exists() + + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + outcome = run("create", "--storage", "encrypted", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "encrypted" + assert sandbox.security.calls == [] + monkeypatch.delenv("ALEO_ACCOUNT_PASSWORD") + key = stored_key(sandbox, password=PASSWORD) + absent(outcome.out + outcome.err, key) + absent(outcome.out + outcome.err, PASSWORD) + + # At a terminal the password is asked for twice. + sandbox.terminal = True + sandbox.answers.extend([OTHER_PASSWORD, OTHER_PASSWORD]) + outcome = run("create", "--storage", "encrypted", "--name", "typed") + assert outcome.status == 0 + assert len(sandbox.prompts) == 2 + assert str(PrivateKey.from_string(stored_key(sandbox, "typed", OTHER_PASSWORD)).address) in outcome.out + + +def test_create_can_save_the_password_in_the_keychain(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + outcome = run("create", "--storage", "encrypted", "--save-password", "--json") + assert outcome.status == 0 + assert sandbox.security.entries == {saved_password_entry(outcome.json["path"]): PASSWORD.encode("utf-8").hex()} + assert "--save-password" not in outcome.err + + # Where it cannot apply, the flag is reported as having had no effect. + plain = run("create", "--name", "plain", "--save-password") + assert plain.status == 0 + assert "--save-password" in plain.err + monkeypatch.setattr(runtime, "platform", "linux") + elsewhere = run("create", "--name", "elsewhere", "--storage", "encrypted", "--save-password") + assert elsewhere.status == 0 + assert "--save-password" in elsewhere.err + assert len(sandbox.security.entries) == 1 + + +def test_storing_plaintext_on_windows_says_file_modes_are_not_enforced( + sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(runtime, "platform", "win32") + outcome = run("create") + assert outcome.status == 0 + assert "Windows" in outcome.err + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + encrypted = run("create", "--name", "locked", "--storage", "encrypted") + assert encrypted.status == 0 + assert "Windows" not in encrypted.err + + +# --------------------------------------------------------------------------- +# import +# --------------------------------------------------------------------------- + + +def test_import_stores_the_key_of_a_key_file(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + key_file = sandbox.root / "key.txt" + key_file.write_text(f"\n {account.private_key}\n", encoding="utf-8") + # The flag comes first: the variables are not consulted. + monkeypatch.setenv("ALEO_PRIVATE_KEY", "") + outcome = run("import", "--key-file", str(key_file), "--json") + assert outcome.status == 0 + assert outcome.json == { + "name": "default", + "address": account.address, + "storage": "plaintext", + "path": str(sandbox.dir / "default.json"), + } + check_secret(stored_key(sandbox), account.private_key) + absent(outcome.out + outcome.err, account.private_key) + + # Importing the same key again changes nothing and succeeds. + assert run("import", "--key-file", str(key_file)).status == 0 + # Another key under the same name is refused. + key_file.write_text(new_account().private_key, encoding="utf-8") + again = run("import", "--key-file", str(key_file), "--json") + assert (again.status, again.json["error"]["code"]) == (1, "ACCOUNT_EXISTS") + + +@pytest.mark.parametrize( + ("content", "code"), + [(None, "EMPTY_KEY_SOURCE"), (" \n", "EMPTY_KEY_SOURCE"), ("APrivateKey1nope", "INVALID_KEY")], +) +def test_import_reports_an_unusable_key_file(sandbox: Sandbox, run: Any, content: Any, code: str) -> None: + key_file = sandbox.root / "key.txt" + if content is not None: + key_file.write_text(content, encoding="utf-8") + for flag in ("--key-file", "--mnemonic-file"): + outcome = run("import", flag, str(key_file), "--json") + expected = "INVALID_MNEMONIC" if (flag, code) == ("--mnemonic-file", "INVALID_KEY") else code + assert (outcome.status, outcome.json["error"]["code"]) == (1, expected) + assert "nope" not in outcome.out + assert not sandbox.dir.exists() + + +def test_import_stores_a_key_supplied_through_the_variables(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", account.private_key) + outcome = run("import", "--storage", "keychain", "--json") + assert outcome.status == 0 + assert outcome.json["address"] == account.address + check_secret(sandbox.security.entries[key_entry(outcome.json["path"])], account.private_key) + absent(outcome.out + outcome.err, account.private_key) + + key_file = sandbox.root / "key.txt" + key_file.write_text(account.private_key, encoding="utf-8") + monkeypatch.delenv("SHIELD_SWAP_PRIVATE_KEY") + monkeypatch.setenv("ALEO_PRIVATE_KEY_FILE", str(key_file)) + from_file = run("import", "--name", "from-file", "--json") + assert from_file.status == 0 + check_secret(stored_key(sandbox, "from-file"), account.private_key) + + +def test_import_applies_the_rules_of_the_key_variables(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("ALEO_PRIVATE_KEY", "") + outcome = run("import", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "EMPTY_KEY_SOURCE") + monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) + monkeypatch.setenv("SHIELD_SWAP_PRIVATE_KEY", new_account().private_key) + outcome = run("import", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "KEY_CONFLICT") + assert not sandbox.dir.exists() + + +@pytest.mark.parametrize("expected", VECTORS["mnemonic"]["accounts"], ids=lambda entry: f"{entry['derivation']}-{entry['index']}") +def test_import_stores_the_derived_key_of_a_recovery_phrase_file_and_not_the_phrase( + sandbox: Sandbox, run: Any, expected: Any +) -> None: + phrase_file = sandbox.root / "phrase.txt" + # Pasted phrases arrive with stray white space and capitals. + phrase_file.write_text(" " + PHRASE.upper().replace(" ", " \n\t ") + "\n\n", encoding="utf-8") + outcome = run( + "import", "--mnemonic-file", str(phrase_file), + "--index", str(expected["index"]), "--derivation", expected["derivation"], "--json", + ) + assert outcome.status == 0 + assert outcome.json["address"] == expected["address"] + check_secret(stored_key(sandbox), expected["privateKey"]) + text = (sandbox.dir / "default.json").read_text(encoding="utf-8") + assert "abandon" not in text and "about" not in text + assert "abandon" not in outcome.out + outcome.err + + +def test_import_defaults_to_the_first_account_on_the_standard_path(sandbox: Sandbox, run: Any) -> None: + phrase_file = sandbox.root / "phrase.txt" + phrase_file.write_text(PHRASE, encoding="utf-8") + outcome = run("import", "--mnemonic-file", str(phrase_file), "--json") + first = next(a for a in VECTORS["mnemonic"]["accounts"] if a["derivation"] == "standard" and a["index"] == 0) + assert outcome.json["address"] == first["address"] + + +def test_import_rejects_an_invalid_recovery_phrase(sandbox: Sandbox, run: Any) -> None: + phrase_file = sandbox.root / "phrase.txt" + words = PHRASE.split() + for phrase in ( + " ".join(words[:-1] + ["abandon"]), # checksum + " ".join(words[:-1]), # word count + " ".join(words[:-1] + ["zzzzzz"]), # word list + ): + phrase_file.write_text(phrase, encoding="utf-8") + outcome = run("import", "--mnemonic-file", str(phrase_file), "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "INVALID_MNEMONIC") + assert "abandon" not in outcome.out and "zzzzzz" not in outcome.out + assert not sandbox.dir.exists() + + +def test_import_asks_at_a_hidden_prompt_when_nothing_else_supplies_a_key(sandbox: Sandbox, run: Any) -> None: + # No source and no terminal: needs a person. + outcome = run("import", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (2, "ACCOUNT_NOT_FOUND") + assert sandbox.prompts == [] + + sandbox.terminal = True + # Text that starts with APrivateKey1 is a key. + account = new_account() + sandbox.answers.append(f" {account.private_key}\n") + outcome = run("import", "--json") + assert outcome.status == 0 + assert outcome.json["address"] == account.address + assert len(sandbox.prompts) == 1 + absent(outcome.out + outcome.err, account.private_key) + + # Anything else is a recovery phrase, tidied before it is checked. + second = next(a for a in VECTORS["mnemonic"]["accounts"] if a["derivation"] == "legacy" and a["index"] == 1) + sandbox.answers.append(" " + PHRASE.title().replace(" ", " ") + " ") + outcome = run("import", "--name", "phrase", "--index", "1", "--derivation", "legacy", "--json") + assert outcome.status == 0 + assert outcome.json["address"] == second["address"] + check_secret(stored_key(sandbox, "phrase"), second["privateKey"]) + + sandbox.answers.append("APrivateKey1nope") + outcome = run("import", "--name", "bad-key", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "INVALID_KEY") + sandbox.answers.append("not a recovery phrase") + outcome = run("import", "--name", "bad-phrase", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "INVALID_MNEMONIC") + sandbox.answers.append(" ") + outcome = run("import", "--name", "nothing", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "EMPTY_KEY_SOURCE") + + +def test_import_can_record_the_address_only(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + monkeypatch.setenv("ALEO_PRIVATE_KEY", account.private_key) + outcome = run("import", "--storage", "none", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "none" + absent((sandbox.dir / "default.json").read_text(encoding="utf-8"), account.private_key) + absent(outcome.out + outcome.err, account.private_key) + + +# --------------------------------------------------------------------------- +# protect +# --------------------------------------------------------------------------- + + +def test_protect_changes_the_storage(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + + outcome = run("protect", "--storage", "keychain", "--json") + assert outcome.status == 0 + assert outcome.json == { + "name": "default", + "address": account.address, + "storage": "keychain", + "path": str(sandbox.dir / "default.json"), + } + + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + outcome = run("protect", "--storage", "encrypted", "--save-password", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "encrypted" + assert sandbox.security.entries == {saved_password_entry(outcome.json["path"]): PASSWORD.encode("utf-8").hex()} + + outcome = run("protect", "--storage", "plaintext") + assert outcome.status == 0 + assert sandbox.security.entries == {} + monkeypatch.delenv("ALEO_ACCOUNT_PASSWORD") + check_secret(stored_key(sandbox), account.private_key) + absent(outcome.out + outcome.err, account.private_key) + + +def test_protect_sets_a_new_password_on_an_encrypted_account_from_the_prompt_only( + sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + before = (sandbox.dir / "default.json").read_bytes() + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + + outcome = run("protect", "--storage", "encrypted", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (2, "PASSWORD_REQUIRED") + assert (sandbox.dir / "default.json").read_bytes() == before + + sandbox.terminal = True + sandbox.answers.extend([OTHER_PASSWORD, OTHER_PASSWORD]) + assert run("protect", "--storage", "encrypted").status == 0 + assert (sandbox.dir / "default.json").read_bytes() != before + monkeypatch.delenv("ALEO_ACCOUNT_PASSWORD") + check_secret(stored_key(sandbox, password=OTHER_PASSWORD), account.private_key) + + +def test_protect_can_forget_a_saved_password_and_leave_the_account_as_it_is(sandbox: Sandbox, run: Any) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + before = (sandbox.dir / "default.json").read_bytes() + assert sandbox.security.entries != {} + + outcome = run("protect", "--forget-password", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "encrypted" + assert sandbox.security.entries == {} + assert (sandbox.dir / "default.json").read_bytes() == before + assert sandbox.prompts == [] + # The account still opens with its password; only the saved copy is gone. + check_secret(stored_key(sandbox, password=PASSWORD), account.private_key) + # Forgetting again is not an error. + assert run("protect", "--forget-password").status == 0 + + assert run("protect", "--forget-password", "--name", "absent").status == 2 + + +def test_protect_forget_password_with_a_storage_change_removes_the_saved_password( + sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch +) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD, save_password=True) + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + outcome = run("protect", "--storage", "keychain", "--forget-password", "--json") + assert outcome.status == 0 + assert list(sandbox.security.entries) == [key_entry(outcome.json["path"])] + + +def test_protect_forget_password_fails_outside_macos(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + keystore.save(new_account().private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + monkeypatch.setattr(runtime, "platform", "linux") + outcome = run("protect", "--forget-password", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (1, "KEYCHAIN_UNAVAILABLE") + assert sandbox.security.calls == [] + + +# --------------------------------------------------------------------------- +# export +# --------------------------------------------------------------------------- + + +def test_export_prints_the_key_only_for_a_person_who_confirms(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir) + # A key in the environment is never what export prints. + monkeypatch.setenv("ALEO_PRIVATE_KEY", new_account().private_key) + + # No terminal: refused before anything is read or asked. + outcome = run("export") + assert outcome.status == 2 + assert outcome.err.startswith("TERMINAL_REQUIRED: ") + assert outcome.out == "" + sandbox.terminal = True + assert run("export").status == 2 + sandbox.output_terminal = True + outcome = run("export", "--json") + assert (outcome.status, outcome.json["error"]["code"]) == (2, "TERMINAL_REQUIRED") + assert sandbox.prompts == [] + + # Declined, or answered with anything but yes: nothing is shown. + for answer in ("n", "", "maybe"): + sandbox.answers.append(answer) + outcome = run("export") + assert outcome.status == 1 + assert outcome.out == "" + absent(outcome.err, account.private_key) + + sandbox.prompts.clear() + sandbox.answers.append("y") + outcome = run("export") + assert outcome.status == 0 + check_secret(outcome.out, f"{account.private_key}\n") + absent(outcome.err, account.private_key) + assert len(sandbox.prompts) == 1 + assert account.address in sandbox.prompts[0] and "default" in sandbox.prompts[0] + + sandbox.answers.append("YES") + assert run("export").status == 0 + + +def test_export_reports_a_missing_account_or_key_before_asking(sandbox: Sandbox, run: Any) -> None: + sandbox.terminal = sandbox.output_terminal = True + outcome = run("export") + assert outcome.status == 2 + assert outcome.err.startswith("ACCOUNT_NOT_FOUND: ") + + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="none") + sandbox.answers.append("y") + outcome = run("export") + assert outcome.status == 2 + assert outcome.err.startswith("KEY_NOT_STORED: ") + assert outcome.out == "" + + +def test_export_unlocks_an_encrypted_account_at_the_prompt(sandbox: Sandbox, run: Any) -> None: + account = new_account() + keystore.save(account.private_key, dir=sandbox.dir, storage="encrypted", password=PASSWORD) + sandbox.terminal = sandbox.output_terminal = True + sandbox.answers.extend(["y", OTHER_PASSWORD, PASSWORD]) + outcome = run("export") + assert outcome.status == 0 + check_secret(outcome.out, f"{account.private_key}\n") + assert "Wrong password." in outcome.err + absent(outcome.out + outcome.err, PASSWORD) + + +# --------------------------------------------------------------------------- +# migrate +# --------------------------------------------------------------------------- + + +def test_migrate_copies_a_legacy_key_and_reports_the_copy_that_remains(sandbox: Sandbox, run: Any) -> None: + account = new_account() + source = sandbox.root / "profile.json" + text = json.dumps({"address": account.address, "private_key": account.private_key, "network": "testnet"}, indent=2) + "\n" + source.write_text(text, encoding="utf-8") + + outcome = run("migrate", "--from", str(source), "--json") + assert outcome.status == 0 + assert outcome.json == { + "name": "default", + "address": account.address, + "storage": "plaintext", + "path": str(sandbox.dir / "default.json"), + } + assert source.read_text(encoding="utf-8") == text + assert str(source) in outcome.err + assert "--remove-legacy-key" in outcome.err + absent(outcome.out + outcome.err, account.private_key) + check_secret(stored_key(sandbox), account.private_key) + + +def test_migrate_can_strip_the_legacy_key(sandbox: Sandbox, run: Any, monkeypatch: pytest.MonkeyPatch) -> None: + account = new_account() + source = sandbox.root / "state.json" + source.write_text( + json.dumps({"privateKey": account.private_key, "address": account.address, "apiUrl": "https://example.test"}, indent=2) + "\n", + encoding="utf-8", + ) + monkeypatch.setenv("ALEO_ACCOUNT_PASSWORD", PASSWORD) + outcome = run("migrate", "--from", str(source), "--storage", "encrypted", "--remove-legacy-key", "--json") + assert outcome.status == 0 + assert outcome.json["storage"] == "encrypted" + assert json.loads(source.read_text(encoding="utf-8")) == {"address": account.address, "apiUrl": "https://example.test"} + assert "--remove-legacy-key" not in outcome.err + if POSIX: + assert mode(source) == 0o600 + check_secret(stored_key(sandbox, password=PASSWORD), account.private_key) + + again = run("migrate", "--from", str(source), "--json") + assert (again.status, again.json["error"]["code"]) == (1, "LEGACY_KEY_NOT_FOUND") + + +# --------------------------------------------------------------------------- +# The module entry point +# --------------------------------------------------------------------------- + + +def test_runs_as_a_module_with_the_documented_exit_status(sandbox: Sandbox) -> None: + account = new_account() + stored = keystore.save(account.private_key, dir=sandbox.dir) + environment = {name: value for name, value in os.environ.items() if name not in VARIABLES} + environment["PYTHONPATH"] = str(Path(aleo.__file__).resolve().parents[1]) + environment["HOME"] = str(sandbox.home) + + def module(*argv: str) -> "subprocess.CompletedProcess[str]": + return subprocess.run( + [sys.executable, "-m", "aleo.keystore", *argv], + env=environment, cwd=str(sandbox.root), capture_output=True, text=True, stdin=subprocess.DEVNULL, timeout=120, + ) + + shown = module("show", "--dir", str(sandbox.dir), "--json") + assert shown.returncode == 0 + assert shown.stderr == "" + assert json.loads(shown.stdout) == { + "name": "default", + "address": account.address, + "storage": "plaintext", + "path": str(stored.path), + } + + assert module("show", "--dir", str(sandbox.root / "empty")).returncode == 2 + # Not a terminal: the key is not printed. + exported = module("export", "--dir", str(sandbox.dir)) + assert exported.returncode == 2 + assert exported.stderr.startswith("TERMINAL_REQUIRED: ") + assert exported.stdout == "" + usage = module("show", "--unknown") + assert usage.returncode == 64 + assert "usage:" in usage.stderr + assert module().returncode == 64