detssh 0.1.0__tar.gz

detssh-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip build
+
+      - name: Check if version changed
+        id: check_version
+        run: |
+          LOCAL_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          PUBLISHED_VERSION=$(curl -s -f https://pypi.org/pypi/detssh/json | python -c "import json, sys; print(json.load(sys.stdin).get('info', {}).get('version', ''))" || echo "")
+          echo "Local version: $LOCAL_VERSION, published version: $PUBLISHED_VERSION"
+          if [ "$LOCAL_VERSION" = "$PUBLISHED_VERSION" ]; then
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build package
+        if: steps.check_version.outputs.should_publish == 'true'
+        run: |
+          python -m build
+
+      - name: Publish to PyPI
+        if: steps.check_version.outputs.should_publish == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

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

@@ -0,0 +1,36 @@
+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
+        run: uv run pytest -q
+
+      - name: Run ruff
+        run: uv run ruff check .

detssh-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.idea/
+*.egg-info/
+dist/
+build/

detssh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Işık Kaplan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detssh-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: detssh
+Version: 0.1.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
+Author-email: Işık Kaplan <isik.kaplan@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: argon2,bcrypt,cryptography,ed25519,kdf,pbkdf2,scrypt,ssh
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: argon2-cffi>=21.3
+Requires-Dist: bcrypt>=5.0.0
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=41.0
+Requires-Dist: questionary>=2.1.1
+Description-Content-Type: text/markdown
+
+# detssh
+
+Deterministic Ed25519 SSH key generation from a seed passphrase. Same
+passphrase + same parameters → same keypair, every time, on any machine -
+nothing to back up but what's in your head.
+
+```
+detssh
+```
+Prompts for everything (passphrase hidden + confirmed) and writes to the
+same place `ssh-keygen` would: `~/.ssh/id_ed25519` / `~/.ssh/id_ed25519.pub`
+(mode 600/700, `~/.ssh` created if missing). Pass `--output` to write
+somewhere else instead.
+
+Non-interactively:
+```
+detssh --kdf argon2id --salt-algo blake2b --seed "..." --label github --overwrite-files
+```
+Any flag switches to non-interactive mode: missing optional fields fall back
+to their defaults, `--seed` is the only required one. Passing `--seed` on the
+command line puts it in your shell history and process list (`ps aux`) - fine
+for local scripting, but prefer the interactive prompt when that matters.
+
+## Backends
+
+- `--kdf`: `argon2id` (default), `argon2i`, `argon2d`, `scrypt`, `pbkdf2`, `bcrypt_pbkdf`
+- `--salt-algo`: `blake2b` (default), `blake2s`, `sha256`, `sha384`, `sha512`, `sha3_256`, `sha3_384`, `sha3_512`
+
+Each combination has its own options (cost knobs, salt digest size, etc.),
+with their valid ranges shown in both `--help` and the interactive prompts.
+See them with:
+```
+detssh --kdf <kdf> --salt-algo <salt-algo> --help
+```
+
+We recommend sticking with the defaults (`argon2id`, memory-hard with a high
+cost) unless you have a specific reason not to - they make brute-forcing your
+passphrase significantly more expensive than faster KDFs like `pbkdf2`.
+
+Cost knobs (iterations, memory, cost, rounds, ...) also carry a soft safety
+limit meant to catch typos before they cost you minutes of derivation time.
+In interactive mode, going over one doesn't interrupt you - everything you
+exceeded is summarized in one confirmation at the very end. In flag mode, it
+fails immediately unless you pass `--force-allow-soft-constraints`.
+
+## Determinism guarantee
+
+Same explicit parameters → same key, across any release sharing the same
+major version - only a major version bump may change key derivation. That
+guarantee starts at 1.0; we're still on 0.x, so it doesn't apply yet (see
+`tests/golden/README.md`).
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check .
+```

detssh-0.1.0/README.md

@@ -0,0 +1,59 @@
+# detssh
+
+Deterministic Ed25519 SSH key generation from a seed passphrase. Same
+passphrase + same parameters → same keypair, every time, on any machine -
+nothing to back up but what's in your head.
+
+```
+detssh
+```
+Prompts for everything (passphrase hidden + confirmed) and writes to the
+same place `ssh-keygen` would: `~/.ssh/id_ed25519` / `~/.ssh/id_ed25519.pub`
+(mode 600/700, `~/.ssh` created if missing). Pass `--output` to write
+somewhere else instead.
+
+Non-interactively:
+```
+detssh --kdf argon2id --salt-algo blake2b --seed "..." --label github --overwrite-files
+```
+Any flag switches to non-interactive mode: missing optional fields fall back
+to their defaults, `--seed` is the only required one. Passing `--seed` on the
+command line puts it in your shell history and process list (`ps aux`) - fine
+for local scripting, but prefer the interactive prompt when that matters.
+
+## Backends
+
+- `--kdf`: `argon2id` (default), `argon2i`, `argon2d`, `scrypt`, `pbkdf2`, `bcrypt_pbkdf`
+- `--salt-algo`: `blake2b` (default), `blake2s`, `sha256`, `sha384`, `sha512`, `sha3_256`, `sha3_384`, `sha3_512`
+
+Each combination has its own options (cost knobs, salt digest size, etc.),
+with their valid ranges shown in both `--help` and the interactive prompts.
+See them with:
+```
+detssh --kdf <kdf> --salt-algo <salt-algo> --help
+```
+
+We recommend sticking with the defaults (`argon2id`, memory-hard with a high
+cost) unless you have a specific reason not to - they make brute-forcing your
+passphrase significantly more expensive than faster KDFs like `pbkdf2`.
+
+Cost knobs (iterations, memory, cost, rounds, ...) also carry a soft safety
+limit meant to catch typos before they cost you minutes of derivation time.
+In interactive mode, going over one doesn't interrupt you - everything you
+exceeded is summarized in one confirmation at the very end. In flag mode, it
+fails immediately unless you pass `--force-allow-soft-constraints`.
+
+## Determinism guarantee
+
+Same explicit parameters → same key, across any release sharing the same
+major version - only a major version bump may change key derivation. That
+guarantee starts at 1.0; we're still on 0.x, so it doesn't apply yet (see
+`tests/golden/README.md`).
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check .
+```

detssh-0.1.0/detssh/__init__.py

@@ -0,0 +1,14 @@
+from detssh.backends.kdf import BACKENDS as KDF_BACKENDS
+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.1.0"
+__all__ = [
+    "KDF_BACKENDS",
+    "SALT_ALGOS",
+    "default_output_path",
+    "keypair_from_seed",
+    "public_key_path",
+    "write_keypair",
+]

detssh-0.1.0/detssh/backends/base.py

@@ -0,0 +1,177 @@
+from pathlib import Path
+
+import click
+import questionary
+
+from detssh.keygen import keypair_from_seed, public_key_path, write_keypair
+
+
+def _display_path(path):
+    try:
+        return f"~/{Path(path).relative_to(Path.home())}"
+    except (TypeError, ValueError):
+        return str(path)
+
+
+DEFAULT_TEXT_MARKER = "\x00"
+
+
+class Field:
+    def __init__(self, message, kind="text", required=False, choices=(), min_value=None, max_value=None, soft_max=None):
+        self.message = message
+        self.kind = kind
+        self.required = required
+        self.choices = choices
+        self.min_value = min_value
+        self.max_value = max_value
+        self.soft_max = soft_max
+
+    def hint(self):
+        parts = []
+        if self.min_value is not None and self.max_value is not None:
+            parts.append(f"{self.min_value}-{self.max_value}")
+        elif self.min_value is not None:
+            parts.append(f">= {self.min_value}")
+        elif self.max_value is not None:
+            parts.append(f"<= {self.max_value}")
+        if self.soft_max is not None:
+            parts.append(f"soft max {self.soft_max}")
+        return f" ({', '.join(parts)})" if parts else ""
+
+    def hard_error_for(self, value):
+        if value is None:
+            return None
+        if self.min_value is not None and value < self.min_value:
+            return f"must be at least {self.min_value}"
+        if self.max_value is not None and value > self.max_value:
+            return f"must be at most {self.max_value}"
+        return None
+
+    def soft_error_for(self, value):
+        if value is None or self.soft_max is None or value <= self.soft_max:
+            return None
+        return f"is {value}, above the recommended safe limit of {self.soft_max} - this may take a long time"
+
+    def ask(self, default):
+        message = self.message + self.hint()
+        if self.kind == "secret":
+            return click.prompt(message, hide_input=True, confirmation_prompt=True)
+        if self.kind == "int":
+            return click.prompt(message, default=default, type=int)
+        if self.kind == "path":
+            if default is not None:
+                message = f"{message} [{_display_path(default)}]"
+            return click.prompt(
+                message, default=default, type=click.Path(dir_okay=False, path_type=Path), show_default=False
+            )
+        if self.kind == "select":
+            answer = questionary.select(message, choices=list(self.choices), default=default).ask()
+            if answer is None:
+                raise click.Abort()
+            return answer
+        return click.prompt(message, default=default, show_default=bool(default))
+
+
+def build_options(fields, defaults=None):
+    defaults = defaults or {}
+    options = []
+    for name, field in fields.items():
+        kwargs = {"default": None, "help": field.message + field.hint()}
+
+        default_value = defaults.get(name)
+        if callable(default_value):
+            default_value = default_value()
+        if default_value not in (None, ""):
+            display_value = _display_path(default_value) if field.kind == "path" else default_value
+            kwargs["help"] = f"{field.message}{field.hint()}{DEFAULT_TEXT_MARKER}[default: {display_value}]"
+
+        if field.kind == "int":
+            kwargs["type"] = int
+        elif field.kind == "select":
+            kwargs["type"] = click.Choice(field.choices)
+        elif field.kind == "path":
+            kwargs["type"] = click.Path(dir_okay=False, path_type=Path)
+        options.append(click.Option([f"--{name.replace('_', '-')}"], **kwargs))
+    return options
+
+
+def is_interactive(values):
+    return all(value is None for value in values.values())
+
+
+def resolve_fields(fields, values, defaults, interactive, allow_soft_constraints=False):
+    resolved = {}
+    soft_violations = []
+    for name, field in fields.items():
+        flag = f"--{name.replace('_', '-')}"
+        value = values.get(name)
+
+        if value is None and interactive:
+            default = defaults.get(name)
+            if callable(default):
+                default = default()
+            while True:
+                value = field.ask(default)
+                hard_error = field.hard_error_for(value)
+                if hard_error:
+                    click.echo(f"Error: {flag} {hard_error}")
+                    continue
+                break
+            soft_error = field.soft_error_for(value)
+            if soft_error:
+                soft_violations.append(f"{flag} {soft_error}")
+        elif value is None and field.required:
+            raise click.UsageError(f"{flag} is required")
+        elif value is None:
+            default = defaults.get(name)
+            value = default() if callable(default) else default
+        else:
+            hard_error = field.hard_error_for(value)
+            if hard_error:
+                raise click.UsageError(f"{flag} {hard_error}")
+            soft_error = field.soft_error_for(value)
+            if soft_error and not allow_soft_constraints:
+                raise click.UsageError(f"{flag} {soft_error} - pass --force-allow-soft-constraints to override")
+
+        if field.kind == "path" and value is not None:
+            value = Path(value).expanduser()
+        if field.required and not value:
+            raise click.UsageError(f"{flag} must not be empty")
+        resolved[name] = value
+
+    if soft_violations:
+        click.echo("These may take a long time:")
+        for violation in soft_violations:
+            click.echo(f"  {violation}")
+        if not click.confirm("Continue anyway?"):
+            raise click.Abort()
+
+    return resolved
+
+
+def confirm_overwrite(output, overwrite_files):
+    if overwrite_files:
+        return
+    output = Path(output)
+    if (output.exists() or public_key_path(output).exists()) and not click.confirm(
+        f"{output} already exists. Overwrite?"
+    ):
+        raise click.Abort()
+
+
+def write_keypair_and_recap(seed_bytes, output, comment, recap):
+    private_key, public_key = keypair_from_seed(seed_bytes)
+    try:
+        priv_path, pub_path = write_keypair(private_key, public_key, output, comment=comment)
+    except OSError as e:
+        raise click.ClickException(f"couldn't write {output}: {e.strerror or e}") from e
+    except ValueError as e:
+        raise click.UsageError(str(e)) from e
+
+    click.echo(f"Wrote private key: {priv_path}")
+    click.echo(f"Wrote public key:  {pub_path}")
+
+    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}")

detssh-0.1.0/detssh/backends/kdf/__init__.py

@@ -0,0 +1,22 @@
+from detssh.backends.kdf.argon2d import Argon2D
+from detssh.backends.kdf.argon2i import Argon2I
+from detssh.backends.kdf.argon2id import Argon2Id
+from detssh.backends.kdf.bcrypt_pbkdf import BcryptPbkdf
+from detssh.backends.kdf.pbkdf2 import Pbkdf2
+from detssh.backends.kdf.scrypt import Scrypt
+
+
+BACKENDS = {
+    "argon2id": Argon2Id,
+    "argon2i": Argon2I,
+    "argon2d": Argon2D,
+    "scrypt": Scrypt,
+    "pbkdf2": Pbkdf2,
+    "bcrypt_pbkdf": BcryptPbkdf,
+}
+
+for _name, _backend in BACKENDS.items():
+    if _backend.name != _name:
+        raise TypeError(f"{_backend.__name__}.name must equal its registry key {_name!r}")
+    if _backend.salt_constraints is None:
+        raise TypeError(f"{_backend.__name__} must set salt_constraints (use NO_SALT_CONSTRAINTS if none apply)")

detssh-0.1.0/detssh/backends/kdf/_argon2.py

@@ -0,0 +1,44 @@
+from argon2.exceptions import Argon2Error
+from argon2.low_level import hash_secret_raw
+
+from detssh.backends.base import Field
+from detssh.backends.kdf.base import KDFBackend, KDFError, SaltConstraints
+
+
+class Argon2Base(KDFBackend):
+    salt_constraints = SaltConstraints(min_size=8)
+    type = None
+
+    fields = {
+        "iterations": Field("Argon2 iterations", kind="int", soft_max=100),
+        "memory": Field("Argon2 memory, in MiB", kind="int", soft_max=2048),
+        "parallelism": Field("Argon2 parallelism", kind="int", soft_max=16),
+    }
+    defaults = {
+        "iterations": 10,
+        "memory": 1024,
+        "parallelism": 4,
+    }
+
+    @classmethod
+    def run(cls, resolved, salt):
+        try:
+            return hash_secret_raw(
+                secret=resolved["seed"].encode("utf-8"),
+                salt=salt,
+                time_cost=resolved["iterations"],
+                memory_cost=resolved["memory"] * 1024,
+                parallelism=resolved["parallelism"],
+                hash_len=resolved["hash_len"],
+                type=cls.type,
+            )
+        except (Argon2Error, OverflowError, ValueError) as e:
+            raise KDFError(str(e)) from e
+
+    @classmethod
+    def recap(cls, resolved):
+        return (
+            ("iterations", resolved["iterations"]),
+            ("memory", f"{resolved['memory']} MiB"),
+            ("parallelism", resolved["parallelism"]),
+        )

detssh-0.1.0/detssh/backends/kdf/argon2d.py

@@ -0,0 +1,8 @@
+from argon2.low_level import Type
+
+from detssh.backends.kdf._argon2 import Argon2Base
+
+
+class Argon2D(Argon2Base):
+    name = "argon2d"
+    type = Type.D

detssh-0.1.0/detssh/backends/kdf/argon2i.py

@@ -0,0 +1,8 @@
+from argon2.low_level import Type
+
+from detssh.backends.kdf._argon2 import Argon2Base
+
+
+class Argon2I(Argon2Base):
+    name = "argon2i"
+    type = Type.I

detssh-0.1.0/detssh/backends/kdf/argon2id.py

@@ -0,0 +1,8 @@
+from argon2.low_level import Type
+
+from detssh.backends.kdf._argon2 import Argon2Base
+
+
+class Argon2Id(Argon2Base):
+    name = "argon2id"
+    type = Type.ID

detssh-0.1.0/detssh/backends/kdf/base.py

@@ -0,0 +1,36 @@
+class SaltConstraints:
+    def __init__(self, min_size=None, max_size=None, exact_size=None):
+        self.min_size = min_size
+        self.max_size = max_size
+        self.exact_size = exact_size
+
+    def error_for(self, size):
+        if self.exact_size is not None and size != self.exact_size:
+            return f"needs a salt of exactly {self.exact_size} bytes, got {size}"
+        if self.min_size is not None and size < self.min_size:
+            return f"needs a salt of at least {self.min_size} bytes, got {size}"
+        if self.max_size is not None and size > self.max_size:
+            return f"needs a salt of at most {self.max_size} bytes, got {size}"
+        return None
+
+
+NO_SALT_CONSTRAINTS = SaltConstraints()
+
+
+class KDFError(Exception):
+    pass
+
+
+class KDFBackend:
+    name = None
+    salt_constraints = None
+    fields = {}
+    defaults = {}
+
+    @classmethod
+    def run(cls, resolved, salt):
+        raise NotImplementedError
+
+    @classmethod
+    def recap(cls, resolved):
+        return ()

detssh-0.1.0/detssh/backends/kdf/bcrypt_pbkdf.py

@@ -0,0 +1,32 @@
+import bcrypt
+
+from detssh.backends.base import Field
+from detssh.backends.kdf.base import KDFBackend, KDFError, SaltConstraints
+
+
+class BcryptPbkdf(KDFBackend):
+    name = "bcrypt_pbkdf"
+    salt_constraints = SaltConstraints(min_size=1)
+
+    fields = {
+        "rounds": Field("bcrypt_pbkdf rounds", kind="int", soft_max=2000),
+    }
+    defaults = {
+        "rounds": 16,
+    }
+
+    @classmethod
+    def run(cls, resolved, salt):
+        try:
+            return bcrypt.kdf(
+                password=resolved["seed"].encode("utf-8"),
+                salt=salt,
+                desired_key_bytes=resolved["hash_len"],
+                rounds=resolved["rounds"],
+            )
+        except (ValueError, OverflowError) as e:
+            raise KDFError(str(e)) from e
+
+    @classmethod
+    def recap(cls, resolved):
+        return (("rounds", resolved["rounds"]),)

detssh-0.1.0/detssh/backends/kdf/pbkdf2.py

@@ -0,0 +1,36 @@
+import hashlib
+
+from detssh.backends.base import Field
+from detssh.backends.kdf.base import NO_SALT_CONSTRAINTS, KDFBackend, KDFError
+
+
+class Pbkdf2(KDFBackend):
+    name = "pbkdf2"
+    salt_constraints = NO_SALT_CONSTRAINTS
+
+    fields = {
+        "iterations": Field("PBKDF2 iterations", kind="int", soft_max=50_000_000),
+    }
+    defaults = {
+        "iterations": 600_000,
+    }
+
+    @classmethod
+    def run(cls, resolved, salt):
+        try:
+            return hashlib.pbkdf2_hmac(
+                "sha256",
+                resolved["seed"].encode("utf-8"),
+                salt,
+                resolved["iterations"],
+                dklen=resolved["hash_len"],
+            )
+        except (ValueError, OverflowError) as e:
+            raise KDFError(str(e)) from e
+
+    @classmethod
+    def recap(cls, resolved):
+        return (
+            ("iterations", resolved["iterations"]),
+            ("prf", "sha256"),
+        )