detssh 0.4.0__tar.gz → 0.7.0__tar.gz

detssh-0.7.0/.github/workflows/tests.yml

@@ -0,0 +1,68 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+        os-version: [ubuntu-22.04]
+
+    runs-on: ${{ matrix.os-version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests (100% coverage required)
+        run: uv run pytest -q
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+  mutation:
+    needs: test
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run mutation testing (no unlisted survivors allowed)
+        run: |
+          uv run mutmut run || true
+          uv run mutmut results
+          survivors=$(uv run mutmut results | grep 'survived$' | awk '{print $1}' | sed 's/:$//' | sort)
+          known=$(grep -v '^#' tests/mutmut_known_equivalents.txt | grep -v '^$' | sort)
+          new_survivors=$(comm -23 <(echo "$survivors") <(echo "$known"))
+          if [ -n "$new_survivors" ]; then
+            echo "New surviving mutant(s) not in tests/mutmut_known_equivalents.txt:"
+            echo "$new_survivors"
+            exit 1
+          fi
+          echo "No new survivors."

{detssh-0.4.0 → detssh-0.7.0}/.gitignore

@@ -9,3 +9,5 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+mutants/
+.mutmut-cache

{detssh-0.4.0 → detssh-0.7.0}/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-05
+
+### Added
+
+- `--authorize`: derive the key, but only append its public half to
+  `~/.ssh/authorized_keys` (or `--authorized-keys FILE`), the way
+  `ssh-copy-id` would. No private key is written, so a machine you only want
+  to log *into* never holds one. A key that's already in the file (under any
+  comment or options) is left alone, and an existing file keeps its mode; a
+  new one is created 600 inside a 700 `~/.ssh`.
+- Interactive mode now opens by asking whether to generate a keypair or only
+  add the public key. Generating stays the default. `detssh --authorize`
+  skips that question and still prompts for everything else, so the seed
+  passphrase never has to go on the command line.
+
+### Changed
+
+- `--create-parent-dirs` applies to the `--authorized-keys` file's parent too.
+
+## [0.6.0] - 2026-09-19
+
+### Added
+
+- Mutation testing via `mutmut`, gating CI: it rewrites the source one small
+  change at a time and reruns the suite, catching cases where 100% line
+  coverage still let a real behavior change through untested. Started at
+  300+ surviving mutants (from a from-scratch first run); closed all but
+  40, each confirmed genuinely equivalent - the mutated code is provably
+  indistinguishable from the original for every input (e.g. `"utf-8"` vs
+  `"UTF-8"` as a codec name, which Python's codec lookup can't tell apart)
+  - and documented one by one in `tests/mutmut_known_equivalents.txt`,
+  which CI diffs new runs against.
+- `ruff format --check` now runs in CI alongside `ruff check`.
+
+No application behavior changed in this release - every one of the ~260
+mutants closed was a test that was missing or checking too loosely (an
+exact-message assertion where only a substring was checked before, an edge
+case like a trailing `--kdf` flag with nothing after it, a permission check
+on a directory that already existed rather than one the call under test
+actually creates). The code they exercise was already correct.
+
+## [0.5.0] - 2026-09-19
+
+### Added
+
+- Interactive mode now offers to create a missing output-path parent
+  directory itself, instead of requiring `--create-parent-dirs` up front.
+  It defaults to yes for a path under `~/.ssh` and to no (with a warning)
+  for one outside it - the same rule `--create-parent-dirs` already used.
+
+### Changed
+
+- Flag mode now fails fast with a clear error when the output path's
+  parent is missing and `--create-parent-dirs` wasn't passed, instead of
+  running key derivation first and then failing on a raw `OSError`.
+
+### Fixed
+
+- `--kdf`/`--salt-algo` backend detection (used to decide which options to
+  show before click's real parsing runs) could misread a flag's own value
+  as a second occurrence of the flag when the value happened to equal the
+  flag string itself (e.g. `--kdf --kdf`).
+
 ## [0.4.0] - 2026-09-09
 
 ### Added

{detssh-0.4.0 → detssh-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: detssh
-Version: 0.4.0
+Version: 0.7.0
 Summary: Deterministic Ed25519 SSH key generation from a seed passphrase, via configurable KDF and salt-hash backends.
 Project-URL: Homepage, https://github.com/isik-kaplan/detssh
 Project-URL: Repository, https://github.com/isik-kaplan/detssh
@@ -50,6 +50,26 @@ never touches key derivation, so it doesn't need to be remembered to
 *recreate* the key, only to unlock the file you already have. Same caveat as
 `--seed` applies if passed as a flag.
 
+## Only installing the public key
+
+Because the same seed and parameters always give the same key, a machine
+you only want to log *into* doesn't need the private key at all. Run this
+on that machine instead:
+```
+detssh --authorize
+```
+It prompts for the same seed, label and backend settings as a normal run,
+then appends the public key to `~/.ssh/authorized_keys`, `ssh-copy-id`
+style. No private key is written. If the key is already there, the file is
+left untouched, so running it twice is harmless. The interactive wizard
+asks about this up front too ("Only add the public key to an
+authorized_keys file").
+
+In flag mode, add `--authorize` to the usual flags, plus `--authorized-keys
+FILE` for a file other than `~/.ssh/authorized_keys`. `--output`,
+`--key-passphrase`, `--register` and `--overwrite-files` are rejected
+alongside it, because they only apply when a private key is written.
+
 ## Using the key with `ssh`
 
 `ssh` only auto-offers keys with default filenames (`id_rsa`, `id_ed25519`, ...)
@@ -122,8 +142,33 @@ guarantee starts at 1.0; we're still on 0.x, so it doesn't apply yet (see
 uv sync
 uv run pytest
 uv run ruff check .
+uv run ruff format --check .
 ```
 
 `pytest` runs with coverage on by default (`[tool.pytest.ini_options]` in
 `pyproject.toml`) and fails under 100% line+branch coverage - same gate
 locally and in CI, nothing extra to remember to pass.
+
+100% coverage means every line runs under test, not that every behavior
+change gets caught - a test can execute a line without asserting anything
+meaningful about it. [`mutmut`](https://mutmut.readthedocs.io/) checks the
+second thing: it rewrites the source one small change at a time (flips a
+comparison, drops an argument, tweaks a string) and reruns the tests against
+each mutant, one at a time. A mutant that still passes ("survived") is a
+change the suite wouldn't notice.
+
+```
+uv run mutmut run       # takes a few minutes; ctrl-c-safe, resumes where it left off
+uv run mutmut results   # list survivors by name
+uv run mutmut show <name>   # see what a specific mutant changed
+```
+
+A survivor is either a real test gap (add an assertion that would fail
+against the mutant) or a genuinely equivalent mutant - the mutated code is
+provably indistinguishable from the original for every input (e.g.
+`"utf-8"` vs `"UTF-8"` as a codec name: Python's codec lookup is
+case-insensitive, so no test could tell them apart). CI
+(`.github/workflows/tests.yml`, job `mutation`) fails on any survivor not
+listed in `tests/mutmut_known_equivalents.txt`, which names each one and
+says why - add a confirmed-equivalent mutant there (never to silence a
+failure without doing that check) rather than chasing an unwinnable test.

{detssh-0.4.0 → detssh-0.7.0}/README.md

@@ -29,6 +29,26 @@ never touches key derivation, so it doesn't need to be remembered to
 *recreate* the key, only to unlock the file you already have. Same caveat as
 `--seed` applies if passed as a flag.
 
+## Only installing the public key
+
+Because the same seed and parameters always give the same key, a machine
+you only want to log *into* doesn't need the private key at all. Run this
+on that machine instead:
+```
+detssh --authorize
+```
+It prompts for the same seed, label and backend settings as a normal run,
+then appends the public key to `~/.ssh/authorized_keys`, `ssh-copy-id`
+style. No private key is written. If the key is already there, the file is
+left untouched, so running it twice is harmless. The interactive wizard
+asks about this up front too ("Only add the public key to an
+authorized_keys file").
+
+In flag mode, add `--authorize` to the usual flags, plus `--authorized-keys
+FILE` for a file other than `~/.ssh/authorized_keys`. `--output`,
+`--key-passphrase`, `--register` and `--overwrite-files` are rejected
+alongside it, because they only apply when a private key is written.
+
 ## Using the key with `ssh`
 
 `ssh` only auto-offers keys with default filenames (`id_rsa`, `id_ed25519`, ...)
@@ -101,8 +121,33 @@ guarantee starts at 1.0; we're still on 0.x, so it doesn't apply yet (see
 uv sync
 uv run pytest
 uv run ruff check .
+uv run ruff format --check .
 ```
 
 `pytest` runs with coverage on by default (`[tool.pytest.ini_options]` in
 `pyproject.toml`) and fails under 100% line+branch coverage - same gate
 locally and in CI, nothing extra to remember to pass.
+
+100% coverage means every line runs under test, not that every behavior
+change gets caught - a test can execute a line without asserting anything
+meaningful about it. [`mutmut`](https://mutmut.readthedocs.io/) checks the
+second thing: it rewrites the source one small change at a time (flips a
+comparison, drops an argument, tweaks a string) and reruns the tests against
+each mutant, one at a time. A mutant that still passes ("survived") is a
+change the suite wouldn't notice.
+
+```
+uv run mutmut run       # takes a few minutes; ctrl-c-safe, resumes where it left off
+uv run mutmut results   # list survivors by name
+uv run mutmut show <name>   # see what a specific mutant changed
+```
+
+A survivor is either a real test gap (add an assertion that would fail
+against the mutant) or a genuinely equivalent mutant - the mutated code is
+provably indistinguishable from the original for every input (e.g.
+`"utf-8"` vs `"UTF-8"` as a codec name: Python's codec lookup is
+case-insensitive, so no test could tell them apart). CI
+(`.github/workflows/tests.yml`, job `mutation`) fails on any survivor not
+listed in `tests/mutmut_known_equivalents.txt`, which names each one and
+says why - add a confirmed-equivalent mutant there (never to silence a
+failure without doing that check) rather than chasing an unwinnable test.

{detssh-0.4.0 → detssh-0.7.0}/detssh/__init__.py

@@ -3,7 +3,7 @@ from detssh.backends.salt import ALGOS as SALT_ALGOS
 from detssh.keygen import default_output_path, keypair_from_seed, public_key_path, write_keypair
 
 
-__version__ = "0.4.0"
+__version__ = "0.7.0"
 __all__ = [
     "KDF_BACKENDS",
     "SALT_ALGOS",

{detssh-0.4.0 → detssh-0.7.0}/detssh/backends/base.py

@@ -3,7 +3,14 @@ from pathlib import Path
 import click
 import questionary
 
-from detssh.keygen import keypair_from_seed, public_key_path, ssh_dir, write_keypair
+from detssh.keygen import (
+    authorize_public_key,
+    keypair_from_seed,
+    public_key_line,
+    public_key_path,
+    ssh_dir,
+    write_keypair,
+)
 
 
 def _display_path(path):
@@ -164,13 +171,36 @@ def confirm_overwrite(output, overwrite_files):
 
 
 def confirm_create_parent_dirs(output, create_parent_dirs, interactive):
+    """Decide whether to create the output path's missing parent directories.
+
+    Returns the (possibly updated) flag for write_keypair_and_recap to act on. Flag
+    mode requires --create-parent-dirs up front and fails fast otherwise, so a typo
+    surfaces before key derivation rather than as a raw OSError after it. Interactive
+    mode prompts for the same decision instead, defaulting to yes under ~/.ssh and to
+    no (with a warning) elsewhere - matching what --create-parent-dirs would have done.
+    """
     parent = Path(output).parent
-    if not create_parent_dirs or parent.exists() or parent == ssh_dir():
-        return
-    if interactive and not parent.is_relative_to(ssh_dir()):
+    if parent.exists() or parent == ssh_dir():
+        return create_parent_dirs
+
+    outside = not parent.is_relative_to(ssh_dir())
+
+    if not interactive:
+        if not create_parent_dirs:
+            raise click.UsageError(f"{_display_path(parent)} doesn't exist. Pass --create-parent-dirs to create it.")
+        return True
+
+    if not create_parent_dirs and not outside:
+        question, default = f"{_display_path(parent)} doesn't exist. Create it?", True
+    elif outside:
         click.echo(f"Warning: {_display_path(parent)} is outside ~/.ssh.")
-        if not click.confirm("Create it anyway?"):
-            raise click.Abort()
+        question, default = "Create it anyway?", False
+    else:
+        return True
+
+    if not click.confirm(question, default=default):
+        raise click.Abort()
+    return True
 
 
 def write_keypair_and_recap(seed_bytes, output, comment, recap, key_passphrase="", create_parent_dirs=False):
@@ -192,9 +222,31 @@ def write_keypair_and_recap(seed_bytes, output, comment, recap, key_passphrase="
     click.echo(f"Wrote private key: {priv_path}{' (encrypted)' if key_passphrase else ''}")
     click.echo(f"Wrote public key:  {pub_path}")
 
+    echo_recap(recap)
+
+    return priv_path, pub_path
+
+
+def authorize_and_recap(seed_bytes, authorized_keys, comment, recap, create_parent_dirs=False):
+    _, public_key = keypair_from_seed(seed_bytes)
+    try:
+        added = authorize_public_key(
+            public_key, authorized_keys, comment=comment, create_parent_dirs=create_parent_dirs
+        )
+    except OSError as e:
+        raise click.ClickException(f"couldn't write {authorized_keys}: {e.strerror or e}") from e
+
+    if added:
+        click.echo(f"Added public key to {authorized_keys}:")
+    else:
+        click.echo(f"Public key already in {authorized_keys}, left it unchanged:")
+    click.echo(f"  {public_key_line(public_key, comment).decode('utf-8').rstrip()}")
+
+    echo_recap(recap)
+
+
+def echo_recap(recap):
     click.echo()
     click.echo("To recreate this exact key, remember your passphrase (keep it secret) plus:")
     for name, value in (*recap, ("algorithm", "ed25519")):
         click.echo(f"  {name:<18} {value}")
-
-    return priv_path, pub_path

{detssh-0.4.0 → detssh-0.7.0}/detssh/cli.py

@@ -1,5 +1,6 @@
 import sys
 import textwrap
+from pathlib import Path
 
 import click
 from click.formatting import measure_table
@@ -8,6 +9,8 @@ from detssh.backends import kdf, salt
 from detssh.backends.base import (
     DEFAULT_TEXT_MARKER,
     Field,
+    _display_path,
+    authorize_and_recap,
     build_options,
     confirm_create_parent_dirs,
     confirm_overwrite,
@@ -17,7 +20,12 @@ from detssh.backends.base import (
 )
 from detssh.backends.kdf.base import KDFError
 from detssh.backends.salt.base import SaltError
-from detssh.keygen import COMMENT_FORBIDDEN_CHARS, ED25519_SEED_LENGTH, default_output_path
+from detssh.keygen import (
+    COMMENT_FORBIDDEN_CHARS,
+    ED25519_SEED_LENGTH,
+    default_authorized_keys_path,
+    default_output_path,
+)
 from detssh.ssh_cli import OptionalPort, register_entry, split_destination
 
 
@@ -25,6 +33,12 @@ DEFAULT_KDF = "argon2id"
 DEFAULT_SALT_ALGO = "blake2b"
 HASH_LEN = ED25519_SEED_LENGTH
 
+GENERATE_MODE = "Generate a keypair (private + public key)"
+AUTHORIZE_MODE = "Only add the public key to an authorized_keys file"
+MODE = Field("What do you want to do?", kind="select", choices=(GENERATE_MODE, AUTHORIZE_MODE))
+# Flags that only make sense when a private key gets written.
+KEYPAIR_ONLY_FLAGS = ("output", "key_passphrase", "register", "register_port")
+
 SELECTORS = {
     "kdf": Field("KDF backend", kind="select", choices=tuple(kdf.BACKENDS)),
     "salt_algo": Field("Salt hash algorithm", kind="select", choices=tuple(salt.ALGOS)),
@@ -47,17 +61,26 @@ DEFAULTS = {
 
 
 def _peek(args, flag, default):
+    """Guess a flag's value before click does the real parsing, so we know which
+    backend's options to register. Skips past a consumed value instead of scanning
+    it as a token in its own right, so a value that happens to equal the flag itself
+    (e.g. `--kdf --kdf`) isn't misread as a second occurrence of the flag."""
     value = default
-    for i, arg in enumerate(args):
+    i = 0
+    while i < len(args):
+        arg = args[i]
         if arg == flag and i + 1 < len(args):
             value = args[i + 1]
-        elif arg.startswith(flag + "="):
+            i += 2
+            continue
+        if arg.startswith(flag + "="):
             value = arg.split("=", 1)[1]
+        i += 1
     return value
 
 
-def _fields_for(kdf_cls, salt_cls):
-    return {
+def _fields_for(kdf_cls, salt_cls, authorize=False):
+    fields = {
         "seed": COMMON["seed"],
         "label": COMMON["label"],
         **kdf_cls.fields,
@@ -66,6 +89,9 @@ def _fields_for(kdf_cls, salt_cls):
         "comment": COMMON["comment"],
         "key_passphrase": COMMON["key_passphrase"],
     }
+    if authorize:
+        del fields["output"], fields["key_passphrase"]
+    return fields
 
 
 def _help_note(kdf_cls, salt_cls):
@@ -101,6 +127,30 @@ def _registration_from_flags(label, values):
     return label, user, host, port
 
 
+def _check_authorize_flags(authorize, authorized_keys, overwrite_files, values):
+    """Reject flag combinations --authorize can't honor, before any key derivation."""
+    if not authorize:
+        if authorized_keys is not None:
+            raise click.UsageError("--authorized-keys needs --authorize")
+        return
+    if overwrite_files:
+        raise click.UsageError("--overwrite-files can't be used with --authorize: it only appends")
+    for name in KEYPAIR_ONLY_FLAGS:
+        if values.get(name) is not None:
+            flag = f"--{name.replace('_', '-')}"
+            raise click.UsageError(f"{flag} can't be used with --authorize: no private key is written")
+
+
+def _ask_authorized_keys():
+    default = default_authorized_keys_path()
+    return click.prompt(
+        f"authorized_keys file to add the public key to [{_display_path(default)}]",
+        default=default,
+        type=click.Path(dir_okay=False, path_type=Path),
+        show_default=False,
+    )
+
+
 def _register_interactively(label, key_path):
     """Offer to wire the key we just wrote into ~/.ssh/config. Declining leaves the key
     exactly as written - `detssh ssh register` does the same thing later on."""
@@ -134,12 +184,27 @@ class KDFSaltCommand(click.Command):
         fields = {**SELECTORS, **_fields_for(kdf_cls, salt_cls)}
         defaults = {**DEFAULTS, **kdf_cls.defaults, **salt_cls.defaults}
         self.params = build_options(fields, defaults) + [
+            click.Option(
+                ["--authorize"],
+                is_flag=True,
+                help="Only add the public key to an authorized_keys file (see --authorized-keys), so the "
+                "machine accepts logins from wherever you derived the private key. Writes no private key. "
+                "Doesn't switch to flag mode on its own: `detssh --authorize` still prompts for the rest.",
+            ),
+            click.Option(
+                ["--authorized-keys"],
+                type=click.Path(dir_okay=False, path_type=Path),
+                default=None,
+                help="authorized_keys file for --authorize to append to. Skipped if the key is already "
+                f"in it.{DEFAULT_TEXT_MARKER}[default: ~/.ssh/authorized_keys]",
+            ),
             click.Option(["--overwrite-files"], is_flag=True, help="Overwrite existing output files without asking."),
             click.Option(
                 ["--create-parent-dirs"],
                 is_flag=True,
-                help="Create the output path's parent directories if missing, even outside ~/.ssh. "
-                "Interactive mode still confirms before creating one outside ~/.ssh.",
+                help="Create the output path's (or --authorized-keys file's) parent directories if missing, "
+                "even outside ~/.ssh. Interactive mode prompts for this itself if you don't pass the flag; "
+                "non-interactive mode requires it explicitly.",
             ),
             click.Option(
                 ["--register"],
@@ -189,10 +254,14 @@ class KDFSaltCommand(click.Command):
 
 
 @click.command(cls=KDFSaltCommand, context_settings={"help_option_names": ["-h", "--help"], "max_content_width": 120})
-def main(overwrite_files, create_parent_dirs, **values):
+def main(overwrite_files, create_parent_dirs, authorize, authorized_keys, **values):
     interactive = is_interactive(values)
     force_allow_soft_constraints = bool(values.get("force_allow_soft_constraints"))
 
+    _check_authorize_flags(authorize, authorized_keys, overwrite_files, values)
+    if interactive and not authorize:
+        authorize = MODE.ask(GENERATE_MODE) == AUTHORIZE_MODE
+
     kdf_name = values["kdf"]
     if kdf_name is None:
         kdf_name = SELECTORS["kdf"].ask(DEFAULTS["kdf"]) if interactive else DEFAULTS["kdf"]
@@ -203,7 +272,7 @@ def main(overwrite_files, create_parent_dirs, **values):
         salt_name = SELECTORS["salt_algo"].ask(DEFAULTS["salt_algo"]) if interactive else DEFAULTS["salt_algo"]
     salt_cls = salt.ALGOS[salt_name]
 
-    fields = _fields_for(kdf_cls, salt_cls)
+    fields = _fields_for(kdf_cls, salt_cls, authorize)
     defaults = {**DEFAULTS, **kdf_cls.defaults, **salt_cls.defaults}
 
     resolved = {
@@ -216,6 +285,13 @@ def main(overwrite_files, create_parent_dirs, **values):
     if any(char in resolved["comment"] for char in COMMENT_FORBIDDEN_CHARS):
         raise click.UsageError("--comment must not contain newlines")
 
+    if authorize:
+        if authorized_keys is None:
+            authorized_keys = _ask_authorized_keys() if interactive else default_authorized_keys_path()
+        target = authorized_keys.expanduser()
+    else:
+        target = resolved["output"]
+
     registration = None if interactive else _registration_from_flags(resolved["label"], values)
 
     try:
@@ -226,8 +302,9 @@ def main(overwrite_files, create_parent_dirs, **values):
     if salt_error:
         raise click.UsageError(f"{kdf_name} {salt_error}")
 
-    confirm_overwrite(resolved["output"], overwrite_files)
-    confirm_create_parent_dirs(resolved["output"], create_parent_dirs, interactive)
+    if not authorize:
+        confirm_overwrite(target, overwrite_files)
+    create_parent_dirs = confirm_create_parent_dirs(target, create_parent_dirs, interactive)
 
     click.echo("Deriving key...")
     try:
@@ -245,6 +322,10 @@ def main(overwrite_files, create_parent_dirs, **values):
         ("hash-len", resolved["hash_len"]),
     )
 
+    if authorize:
+        authorize_and_recap(seed_bytes, target, resolved["comment"], recap, create_parent_dirs=create_parent_dirs)
+        return
+
     priv_path, _ = write_keypair_and_recap(
         seed_bytes,
         resolved["output"],

{detssh-0.4.0 → detssh-0.7.0}/detssh/keygen.py

@@ -20,6 +20,10 @@ def default_output_path():
     return ssh_dir() / "id_ed25519"
 
 
+def default_authorized_keys_path():
+    return ssh_dir() / "authorized_keys"
+
+
 # ed25519 is the only algorithm whose private key is literally its own seed, so it's the only one usable here.
 def keypair_from_seed(seed):
     if len(seed) != ED25519_SEED_LENGTH:
@@ -33,9 +37,20 @@ def public_key_path(private_key_path):
     return private_key_path.with_name(private_key_path.name + ".pub")
 
 
-def write_keypair(private_key, public_key, output_path, comment="", key_passphrase="", create_parent_dirs=False):
+def public_key_line(public_key, comment=""):
+    """The public key as one authorized_keys / .pub line, newline included."""
     if any(char in comment for char in COMMENT_FORBIDDEN_CHARS):
         raise ValueError("comment must not contain newlines")
+    public_bytes = public_key.public_bytes(
+        encoding=serialization.Encoding.OpenSSH,
+        format=serialization.PublicFormat.OpenSSH,
+    )
+    comment_suffix = f" {comment}" if comment else ""
+    return public_bytes + comment_suffix.encode("utf-8") + b"\n"
+
+
+def write_keypair(private_key, public_key, output_path, comment="", key_passphrase="", create_parent_dirs=False):
+    pub_line = public_key_line(public_key, comment)
 
     output_path = Path(output_path)
     pub_path = public_key_path(output_path)
@@ -53,17 +68,35 @@ def write_keypair(private_key, public_key, output_path, comment="", key_passphra
         format=serialization.PrivateFormat.OpenSSH,
         encryption_algorithm=encryption_algorithm,
     )
-    public_bytes = public_key.public_bytes(
-        encoding=serialization.Encoding.OpenSSH,
-        format=serialization.PublicFormat.OpenSSH,
-    )
 
     fd = os.open(output_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, PRIVATE_KEY_MODE)
     os.fchmod(fd, PRIVATE_KEY_MODE)
     with os.fdopen(fd, "wb") as f:
         f.write(private_bytes)
 
-    comment_suffix = f" {comment}" if comment else ""
-    pub_path.write_bytes(public_bytes + comment_suffix.encode("utf-8") + b"\n")
+    pub_path.write_bytes(pub_line)
 
     return output_path, pub_path
+
+
+def authorize_public_key(public_key, authorized_keys_path, comment="", create_parent_dirs=False):
+    """Append the public key to an authorized_keys file, ssh-copy-id style. Returns False
+    without touching the file when the key is already in it (under any comment or options)."""
+    line = public_key_line(public_key, comment)
+    key_blob = line.split()[1]
+    authorized_keys_path = Path(authorized_keys_path)
+
+    existing = authorized_keys_path.read_bytes() if authorized_keys_path.exists() else b""
+    if any(key_blob in existing_line.split() for existing_line in existing.splitlines()):
+        return False
+
+    if create_parent_dirs or authorized_keys_path.parent == ssh_dir():
+        authorized_keys_path.parent.mkdir(mode=SSH_DIR_MODE, parents=True, exist_ok=True)
+
+    # An existing file keeps its own mode; sshd's StrictModes is what decides whether that's acceptable.
+    fd = os.open(authorized_keys_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, PRIVATE_KEY_MODE)
+    with os.fdopen(fd, "wb") as f:
+        if existing and not existing.endswith(b"\n"):
+            f.write(b"\n")
+        f.write(line)
+    return True