feat(local-accounts): replace and remove keys, clear the password #90

Merged
christianmanivong merged 1 commits from fix/local-account-key-replace into main 2026-11-04 10:54:06 +00:00
Owner

What

The local-accounts contract (LocalAccountsMixin) gets three changes, so that what a person changes about their login reaches the device. See NetOrk/netork#2013.

  1. Replace a key: add_local_account(..., replaces=[<old public key>, ...]). The old keys go from the account as the new one goes in. A key is matched by its base64, whatever options or comment its line has. Every other key, including the ones the person added on the host, stays. A replaced key that is not a public key raises ValueError, as public_key does; so does a single string in place of a list. The new key is never removed, even when it is listed in replaces. New step: old keys. It runs even when adding the new key failed, because the old key is the one that matters for security.
  2. Clear the password: add_local_account(..., clear_password=True). The password goes and the account logs in with a key only. New step: password. Passing it together with password_hash or admin=True raises ValueError, because the sudo rule asks for that password. The caller passes admin=False, and the sudo step then removes the rule and the admin groups as before. Drivers supply the new hook _account_clear_password(name) -> list[list[str]]. A driver without it fails the step with "this driver cannot remove a password", so nothing is silently skipped.
  3. Remove keys without a new one: remove_local_account_keys(name, keys). Only the given keys go. The account stays open, and its password, sudo rule and other keys stay as they are. Step: keys. Same refusals as the other actions (no keys, a key that is none, the login user's own account, a system account).

A driver whose host keeps keys somewhere else can override the new hook _account_drop_keys(name, home, keys), alongside _account_add_key and _account_remove_keys. The default rewrites ~/.ssh/authorized_keys{,2} as the person: it stages the file and installs it with install -m 600, and when nothing is left it removes the file instead of staging an empty stdin. Afterwards it reads every file in _account_key_files again, and the step fails if a removed key is still there.

Why these shapes

  • clear_password as a keyword on add_local_account, not a separate method. One call to add_local_account carries the person's whole wanted state: key, password and sudo. admin=False already removes sudo declaratively. A separate method would mean a second run, with a window in which sudo is gone but the password is still there, or the other way round. A keyword, rather than an overloaded password_hash="", keeps "keep the password" (None) and "remove it" apart.
  • remove_local_account_keys as a separate method, not an optional public_key. add_local_account opens a locked account again and applies sudo and the password. A person who deletes their key needs none of that, so this method touches the keys only. public_key also stays required on add, so a new account always gets a key.

Tests

Fixtures only, no device. tests/test_local_accounts.py gains 31 tests covering replace (including other key files, options and comments, a key that is not there, the new key listed in replaces, invalid input, a failed add, and a removal that failed or did not take), clear (refusals, a failed step, a driver without the hook) and remove (only the given keys go, nothing changes as root, a missing account, refusals, a driver's own key store). All of them failed before the change (TypeError/AttributeError on the new API). The full suite passes (1350), ruff and mypy are clean, and napalm-standard check and ratchet pass.

This is a minor release, assumed to be 4.28.0. The driver PRs for napalm-linux, napalm-bsd, napalm-openmediavault and napalm-qnap-qts raise their floor to it.

## What The local-accounts contract (`LocalAccountsMixin`) gets three changes, so that what a person changes about their login reaches the device. See NetOrk/netork#2013. 1. **Replace a key:** `add_local_account(..., replaces=[<old public key>, ...])`. The old keys go from the account as the new one goes in. A key is matched by its base64, whatever options or comment its line has. Every other key, including the ones the person added on the host, stays. A replaced key that is not a public key raises `ValueError`, as `public_key` does; so does a single string in place of a list. The new key is never removed, even when it is listed in `replaces`. New step: `old keys`. It runs even when adding the new key failed, because the old key is the one that matters for security. 2. **Clear the password:** `add_local_account(..., clear_password=True)`. The password goes and the account logs in with a key only. New step: `password`. Passing it together with `password_hash` or `admin=True` raises `ValueError`, because the sudo rule asks for that password. The caller passes `admin=False`, and the `sudo` step then removes the rule and the admin groups as before. Drivers supply the new hook `_account_clear_password(name) -> list[list[str]]`. A driver without it fails the step with "this driver cannot remove a password", so nothing is silently skipped. 3. **Remove keys without a new one:** `remove_local_account_keys(name, keys)`. Only the given keys go. The account stays open, and its password, sudo rule and other keys stay as they are. Step: `keys`. Same refusals as the other actions (no keys, a key that is none, the login user's own account, a system account). A driver whose host keeps keys somewhere else can override the new hook `_account_drop_keys(name, home, keys)`, alongside `_account_add_key` and `_account_remove_keys`. The default rewrites `~/.ssh/authorized_keys{,2}` as the person: it stages the file and installs it with `install -m 600`, and when nothing is left it removes the file instead of staging an empty stdin. Afterwards it reads every file in `_account_key_files` again, and the step fails if a removed key is still there. ## Why these shapes - **`clear_password` as a keyword on `add_local_account`, not a separate method.** One call to `add_local_account` carries the person's whole wanted state: key, password and sudo. `admin=False` already removes sudo declaratively. A separate method would mean a second run, with a window in which sudo is gone but the password is still there, or the other way round. A keyword, rather than an overloaded `password_hash=""`, keeps "keep the password" (`None`) and "remove it" apart. - **`remove_local_account_keys` as a separate method, not an optional `public_key`.** `add_local_account` opens a locked account again and applies sudo and the password. A person who deletes their key needs none of that, so this method touches the keys only. `public_key` also stays required on add, so a new account always gets a key. ## Tests Fixtures only, no device. `tests/test_local_accounts.py` gains 31 tests covering replace (including other key files, options and comments, a key that is not there, the new key listed in `replaces`, invalid input, a failed add, and a removal that failed or did not take), clear (refusals, a failed step, a driver without the hook) and remove (only the given keys go, nothing changes as root, a missing account, refusals, a driver's own key store). All of them failed before the change (`TypeError`/`AttributeError` on the new API). The full suite passes (1350), ruff and mypy are clean, and `napalm-standard check` and `ratchet` pass. This is a minor release, assumed to be **4.28.0**. The driver PRs for napalm-linux, napalm-bsd, napalm-openmediavault and napalm-qnap-qts raise their floor to it.
christianmanivong added 1 commit 2026-11-04 10:50:03 +00:00
feat(local-accounts): replace and remove keys, clear the password
driver / lint (pull_request) Successful in 15s
driver / standard (pull_request) Successful in 18s
driver / types (pull_request) Successful in 1m1s
driver / test (3.13) (pull_request) Successful in 1m10s
driver / test (3.12) (pull_request) Successful in 1m21s
driver / lowest (pull_request) Successful in 40s
driver / build (pull_request) Successful in 39s
driver / security (pull_request) Successful in 1m16s
CI / driver (pull_request) Successful in 2m44s
driver / publish (pull_request) Skipped
00452d0d37
A person who replaces a key, deletes one or removes their password had
no way to see that reach the device: add_local_account only ever added
a key and kept the password.

add_local_account takes replaces=[...] (the old keys go, matched by
their base64, the person's own keys stay) and clear_password=True (the
account logs in with a key only and cannot have sudo).
remove_local_account_keys takes keys off an account and leaves it open.
Drivers supply _account_clear_password and may override
_account_drop_keys for a key store of their own.

See NetOrk/netork#2013
christianmanivong merged commit 1edf458feb into main 2026-11-04 10:54:06 +00:00
christianmanivong deleted branch fix/local-account-key-replace 2026-11-04 10:54:06 +00:00
Sign in to join this conversation.