authkeys 0.4.0__tar.gz

authkeys-0.4.0/.gitignore

@@ -0,0 +1,29 @@
+# Build/dist output and generated docs site
+dist/
+build/
+site/
+*.egg-info/
+
+# Agent/harness tooling (never commit these)
+AGENTS.md
+.agents/
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.venv/
+
+# Project-specific
+/.pyenv
+/.env
+/_*
+/src/_*

authkeys-0.4.0/CHANGELOG.md

@@ -0,0 +1,196 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-07-20
+
+Feature release with fixes — no breaking changes.
+
+### Fixed
+- **`--config` with a Windows absolute path was silently ignored.** The
+  colon-separated path list was split naively, so `C:\path\authkeys.conf` became
+  `["C", "\path\authkeys.conf"]` and the file was never read — the caller got an
+  empty config with no error. For `authkeys serve` this also skipped the
+  fail-closed `api_key` check and left the server running unauthenticated.
+  Drive-letter prefixes are now preserved; POSIX `a.conf:b.conf` lists still split.
+- CI reliability (test-only, no runtime code changed):
+  - The HTTP key-server tests now bypass any proxy configured in the environment
+    (GitHub's Windows runners set `HTTP(S)_PROXY`), which otherwise routed the
+    localhost test requests through an unreachable proxy and hung.
+  - A concurrency test joined its worker threads without a timeout; the join is
+    now bounded and the threads are daemons.
+  - A hard per-test `timeout` (via `pytest-timeout`) is configured so any future
+    socket/thread stall fails fast with a traceback instead of hanging the job.
+
+### Added
+- **Options-prefixed `authorized_keys` lines are now preserved verbatim.** A
+  real-world line like `command="...",no-pty ssh-rsa AAAA bob` was previously
+  misparsed (the options list was read as the key type). `AuthorizedKey` gains
+  an `options: str = ""` field; `parse` now detects an options prefix (a first
+  token containing `=`, or not matching a recognized key-type prefix) and
+  keeps it separate from `type`/`key`/`comment`, round-tripping byte-for-byte
+  through `resolve`/`serve` output. Deduplication now keys on
+  `(options, type, key)`, so an option-bearing key is kept distinct from the
+  bare form of the same key.
+- **`--format authorized_keys|json`** on `authkeys resolve` and
+  `authkeys check`. `authorized_keys` (default) is unchanged; `json` prints a
+  single JSON array of `{"type", "key", "comment", "options"}` objects instead,
+  for scripting/tooling consumers. `serve` is unaffected (always sshd wire
+  format).
+- **`examples/authkeys-serve.service`**: a template systemd unit for running
+  `authkeys serve`, with hardening directives (`DynamicUser=`,
+  `NoNewPrivileges=true`, `ProtectSystem=strict`, `PrivateTmp=true`, a minimal
+  `RestrictAddressFamilies=`, dropped capabilities) and both ways to supply
+  `AUTHKEYS_APIKEY` without putting it in `authkeys.conf`. Documented in
+  `docs/guide/server.md`, including why `ProtectHome=` is `read-only` rather
+  than stricter (the service needs to read users' `~/.ssh`).
+
+### Changed
+- **Internal refactor**: `Source` is now a `@dataclass` instead of an
+  `argparse.Namespace` subclass. Same fields (`cached`/`enabled`/`backend`/
+  `sanitize`/`expire`), same `from_config` signature, no behavior change.
+
+## [0.3.0] - 2026-07-19
+
+Additive feature release — no breaking changes.
+
+### Added
+- **`authkeys.sources.github`**: fetch a user's public keys from GitHub's
+  plain-text `.keys` endpoint (`https://github.com/{username}.keys` by
+  default). The `url` template can be overridden to point at any forge with
+  the same convention (e.g. GitLab), so no separate source class is needed.
+  Uses the existing `[http]` extra (`requests`); no new extra.
+- **`authkeys check <user>`**: a debugging counterpart to `resolve` that
+  prints the same resolved keys to stdout while surfacing the per-source
+  resolution trace (which source served/cached which key) on stderr.
+- **`authkeys completion [bash|zsh|fish]`**: prints a self-contained shell
+  completion script (generated from the CLI's own argument parser via
+  `duho`'s completion support) for the given shell.
+- **Source registry**: `authkeys.sources.register_source(alias, cls)` and
+  `get_source(alias)` for programmatic lookup of source classes by short
+  name. The four built-in sources (`authorizedkeys`, `http`, `github`,
+  `ldap`) are registered through it; existing `backend =
+  authkeys.sources.<alias>` config resolution is unchanged.
+
+### Changed
+- `KeyServer.__init__` gained a `require_auth: bool = False` parameter: when
+  `True` and `api_key` is falsy, construction raises `ValueError` instead of
+  silently starting with authentication disabled. `authkeys serve` now passes
+  `require_auth=True` whenever `[serve]` configures an `api_key`, in addition
+  to its existing friendly `SystemExit` message — the user-facing CLI
+  behavior is unchanged, but the fail-closed invariant now also holds for
+  direct `KeyServer` construction (e.g. embedding authkeys as a library).
+
+## [0.2.0] - 2026-07-19
+
+A security and robustness release from a second review pass. **One breaking
+change** in the LDAP source (see below).
+
+### Security
+- **LDAP now verifies the server certificate by default** (breaking). Previously
+  the LDAPS connection trusted any peer certificate. A new `tls_verify` option
+  controls it: unset/`system` verifies against the OS trust store (default), a
+  path verifies against that CA file/directory, and `none` disables verification
+  (insecure; logs a warning). **Deployments that relied on no verification must
+  set `tls_verify = none`.** `tls_cert`/`tls_key` are now documented as the client
+  mutual-TLS credentials, not server verification.
+- The HTTP key server no longer 500s (with a traceback) on a non-ASCII `apikey`;
+  it returns a clean 401.
+- `authkeys serve` caps the number of `?username=` parameters per request
+  (`max_usernames`, default 16), bounding the work an unauthenticated request can
+  force.
+
+### Fixed
+- A single malformed line in a source (e.g. a corrupt `authorized_keys`) is now
+  skipped and logged instead of discarding **all** of that user's keys — which,
+  with `expired_on_error`, could previously serve stale/revoked keys.
+- The HTTP source now raises on a non-2xx status, so a transient 5xx/403 routes
+  through `expired_on_error` (stale fallback) instead of being cached as "this
+  user has no keys". Errored fetches are never cached as empty.
+- The resolve path never emits a traceback: on a config/internal error it logs one
+  line to stderr and exits non-zero (exit 3), keeping `auth.log` clean.
+- Bounded LDAP connection/receive timeouts, and the resolver no longer holds its
+  lock across the upstream fetch, so one slow/hung source can't stall other
+  logins (or, in `serve`, other concurrent requests).
+- Emitted keys are deduplicated by `(type, key)`, so the same public key coming
+  from two sources is no longer emitted twice with different comments.
+
+### Added
+- **Negative caching** with its own `negative_expire` TTL for keyless principals.
+- **Per-source `expire`** overriding `[cache] expire` (`0` = don't cache a source).
+- **Atomic file-cache writes** (temp file + rename) with `0600`/`0700` perms.
+- **`authkeys cache`** subcommand: `show`, `purge` (`--user`/`--source`/
+  `--expired`/`--all`), and `warm <users...>`; plus optional `max_age`/
+  `max_entries` eviction bounds for the file backend.
+
+### Changed
+- `authkeys.__version__` is now read from the installed distribution metadata
+  (single source of truth with `pyproject.toml`).
+
+## [0.1.1] - 2026-07-18
+
+Hardening release from a code-review pass. No API breaks.
+
+### Security
+- LDAP source now escapes the username in the search filter
+  (`escape_filter_chars`), preventing LDAP filter injection when the username is
+  attacker-controlled (e.g. via the HTTP key server).
+- HTTP source percent-encodes the username before templating it into the request
+  URL, preventing path/query tampering of the upstream key service.
+- `authkeys serve` now fails closed: if `[serve] api_key` is present but resolves
+  empty (e.g. an unset `${env:...}`), it refuses to start instead of silently
+  disabling authentication. A truly absent `api_key` still runs unauthenticated
+  with a warning.
+
+### Fixed
+- HTTP source `verify` now interprets bool-like values (`true`/`false`/...) as a
+  boolean; other values remain a CA-bundle path. Previously `verify = false` was
+  passed to requests as the string `"false"` (a CA path) and did not disable
+  verification.
+- The key server (`ThreadingHTTPServer`) now resolves under a lock, so concurrent
+  requests no longer race on the shared cache backend or issue duplicate upstream
+  fetches for the same key.
+- A malformed cache `expire` value falls back to the default TTL instead of
+  disabling caching entirely (and no longer masks genuine backend errors).
+
+### Changed
+- `authkeys serve` now honors each user's `~/.ssh/authkeys.conf` user/group
+  delegation, matching `authkeys resolve` (both go through the new
+  `AuthKeys.resolve()`).
+- `authkeys <user>` default-command insertion is more robust: a leading flag
+  before a bare username (`authkeys -v alice`) is routed to the `resolve`
+  subparser instead of erroring.
+
+## [0.1.0] - 2026-07-18
+
+Initial packaged release: a `src/` layout, a `duho`-based CLI, and a published
+`authkeys` console script.
+
+### Added
+- Declarative CLI (`authkeys resolve` / `authkeys serve`) built on `duho`, with
+  `--verbose`/`--quiet`/`--loglevel` and `--version`. `resolve` is the default
+  command so `authkeys %u` works directly as an `AuthorizedKeysCommand`.
+- Config-driven HTTP key server (`authkeys serve`): bind/port/path/API key from a
+  `[serve]` section, constant-time API-key comparison, threaded server with clean
+  shutdown, and `${env:VAR}` interpolation to keep secrets off disk.
+- `file`, `http`, and `ldap` key sources with lazy imports of their optional
+  dependencies (`requests`, `ldap3`, `cryptography`); `http` gains request
+  timeouts and configurable TLS verification.
+- Packaging: `pyproject.toml` with `http`/`ldap`/`all`/`dev` extras, `py.typed`,
+  MIT license, and PyPI classifiers. Supports Python 3.9–3.14.
+
+### Fixed
+- In-memory and file cache backends now store and retrieve entries by
+  `(uid, source)` and carry a timestamp, so cache lookups actually hit and the
+  TTL is honored (the previous mem backend never returned a cached value).
+- `Source.from_config` is a real `classmethod`; source defaults (e.g. the default
+  sanitizer) are applied when a section omits them.
+- Group resolution failures during user-config loading are logged and skipped
+  instead of aborting key resolution.
+- Blank lines in `authorized_keys` files are no longer emitted as empty keys.
+
+### Changed
+- Replaced the shell `bin/authkeys` wrapper and standalone `keygrabber` script
+  with the unified `authkeys` CLI and `authkeys serve` subcommand.

authkeys-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to authkeys
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/jose-pr/authkeys.git
+cd authkeys
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode with test dependencies and the optional extras
+# whose tests you want to run (the LDAP test skips without ldap3).
+pip install -e ".[dev,http,ldap]"
+```
+
+> authkeys resolves keys via the POSIX `pwd`/`grp` databases, so key resolution
+> only works on a POSIX host. The package still imports and the test suite still
+> runs on any platform (the file source's `pwd` use is faked in tests).
+
+## Running Tests
+
+```bash
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=src/authkeys tests/
+```
+
+Use `pytest -rs` to see which optional-extra tests were skipped.
+
+## Documentation
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve          # live preview at http://127.0.0.1:8000
+mkdocs build --strict # what CI runs
+```
+
+## Code Style
+
+- Follow PEP 8
+- Use type hints (quote runtime `X | Y` unions, or add
+  `from __future__ import annotations`, for the Python 3.9 floor)
+- Keep functions focused and well-named
+- Import optional dependencies (`requests`, `ldap3`, `cryptography`) lazily so the
+  core stays dependency-free and importable everywhere
+
+## Commit Guidelines
+
+Follow the format: `type: description`
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `test:` Test additions/improvements
+- `ci:` CI/workflow changes
+- `chore:` Build or tooling changes
+
+Examples:
+- `feat: add an HTTP key server subcommand`
+- `fix: escape the username in the LDAP filter`
+- `docs: document the serve fail-closed behavior`
+
+## Pull Request Process
+
+1. Create a feature branch: `git checkout -b feature/my-feature`
+2. Make your changes and add tests
+3. Run `pytest` to ensure all tests pass (on the oldest supported Python if you
+   can — 3.9)
+4. Commit with a clear message (see guidelines above)
+5. Push to your fork and open a pull request
+
+## Reporting Issues
+
+When reporting bugs, please include:
+
+- Python version
+- authkeys version
+- Which source(s) are configured
+- Minimal config that reproduces the issue
+- Expected vs. actual behavior
+
+## Questions?
+
+Open a discussion or issue on GitHub!

authkeys-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+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.

authkeys-0.4.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: authkeys
+Version: 0.4.0
+Summary: Pluggable AuthorizedKeysCommand provider for OpenSSH (file/HTTP/LDAP sources, TTL cache, optional key server)
+Project-URL: Homepage, https://github.com/jose-pr/authkeys/
+Project-URL: Documentation, https://jose-pr.github.io/authkeys/
+Project-URL: Issues, https://github.com/jose-pr/authkeys/issues
+Author: Jose A.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authorized_keys,cli,ldap,openssh,ssh
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: duho
+Provides-Extra: all
+Requires-Dist: cryptography; extra == 'all'
+Requires-Dist: ldap3; extra == 'all'
+Requires-Dist: requests; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-timeout; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: http
+Requires-Dist: requests; extra == 'http'
+Provides-Extra: ldap
+Requires-Dist: cryptography; extra == 'ldap'
+Requires-Dist: ldap3; extra == 'ldap'
+Description-Content-Type: text/markdown
+
+# authkeys
+
+[![PyPI version](https://img.shields.io/pypi/v/authkeys.svg)](https://pypi.org/project/authkeys/)
+[![Python versions](https://img.shields.io/pypi/pyversions/authkeys.svg)](https://pypi.org/project/authkeys/)
+[![Documentation](https://img.shields.io/badge/docs-jose--pr.github.io%2Fauthkeys-blue.svg)](https://jose-pr.github.io/authkeys/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/authkeys/blob/main/LICENSE)
+
+A pluggable OpenSSH [`AuthorizedKeysCommand`](https://man.openbsd.org/sshd_config#AuthorizedKeysCommand)
+provider. It resolves a user's authorized SSH keys from one or more configured
+**sources** — local key files, an HTTP endpoint, or LDAP-stored X.509
+certificates — with optional TTL caching, user/group aliasing, and a small
+unattended HTTP key server for hosts that fetch keys centrally.
+
+Built on the [duho](https://github.com/jose-pr/duho) declarative CLI framework.
+
+## Install
+
+```bash
+pip install authkeys            # core (file source only)
+pip install authkeys[http]      # + HTTP source (requests)
+pip install authkeys[ldap]      # + LDAP cert source (ldap3, cryptography)
+pip install authkeys[all]       # everything
+```
+
+> authkeys targets POSIX systems (it reads the system user/group databases via
+> `pwd`/`grp`). The package imports on any platform for testing, but resolution
+> requires a POSIX host.
+
+## Usage
+
+```bash
+authkeys resolve alice          # print alice's authorized keys
+authkeys alice                  # 'resolve' is the default command
+authkeys serve --bind 0.0.0.0 --port 8090
+```
+
+Wire it into `sshd_config`:
+
+```
+AuthorizedKeysCommand /usr/bin/authkeys resolve %u
+AuthorizedKeysCommandUser nobody
+```
+
+## Configuration
+
+authkeys reads (in order) `/etc/authkeys.conf`,
+`/etc/authkeys/authkeys.conf`, `/etc/ssh/authkeys.conf`, or a colon-separated
+list passed with `--config`. A per-user `~/.ssh/authkeys.conf` may authorize
+additional users/groups. See [`examples/authkeys.conf`](examples/authkeys.conf)
+for a fully commented example.
+
+```ini
+[cache]
+backend = authkeys.cache.AuthKeysCacheMemBackend
+expire = 3600
+expired_on_error = 1
+
+[source:files]
+backend = authkeys.sources.authorizedkeys
+paths =
+    authorized_keys
+    authorized_keys2
+
+[source:ldap]
+enabled = 1
+backend = authkeys.sources.ldap
+server = ldaps://ldap.example.com:636
+basedn = o=Example,c=US
+```
+
+### Sources
+
+| Alias (`backend =`)                | Reads keys from                              | Extra dep |
+| ---------------------------------- | -------------------------------------------- | --------- |
+| `authkeys.sources.authorizedkeys`  | `~/.ssh/authorized_keys*` files              | —         |
+| `authkeys.sources.http`            | an HTTP URL (`{username}` templated)         | `requests` |
+| `authkeys.sources.ldap`            | X.509 certs in an LDAP directory             | `ldap3`, `cryptography` |
+
+Each `[source:<name>]` section supports `enabled` and `cached` (both default
+`true`) and an optional `sanitize` callable to rewrite/drop keys.
+
+### Caching
+
+- `AuthKeysCacheMemBackend` — per-process, in-memory (default).
+- `AuthKeysCacheFileBackend` — on-disk under `path`, shared across invocations.
+
+With `expired_on_error = 1`, a source failure falls back to the last-known
+(expired) cached keys instead of returning nothing — useful when the SSH login
+must not be blocked by a transient LDAP/HTTP outage.
+
+### User / group aliasing
+
+A per-user `~/.ssh/authkeys.conf` may grant other principals' keys:
+
+```ini
+[authorized]
+users =
+    alice
+    bob
+groups =
+    admins
+```
+
+## HTTP key server (`authkeys serve`)
+
+For hosts that can't run the command locally, `authkeys serve` exposes the same
+resolution over HTTP:
+
+```
+GET /keys?username=alice&apikey=<key>
+```
+
+Bind address, port, path, and API key come from the `[serve]` config section
+(or `--bind`/`--port`). The API key is compared in constant time; pull it from
+the environment with `api_key = ${env:AUTHKEYS_APIKEY}` to keep it off disk. If
+no API key is configured, authentication is disabled — only bind to a trusted
+interface in that case.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

authkeys-0.4.0/README.md

@@ -0,0 +1,121 @@
+# authkeys
+
+[![PyPI version](https://img.shields.io/pypi/v/authkeys.svg)](https://pypi.org/project/authkeys/)
+[![Python versions](https://img.shields.io/pypi/pyversions/authkeys.svg)](https://pypi.org/project/authkeys/)
+[![Documentation](https://img.shields.io/badge/docs-jose--pr.github.io%2Fauthkeys-blue.svg)](https://jose-pr.github.io/authkeys/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/authkeys/blob/main/LICENSE)
+
+A pluggable OpenSSH [`AuthorizedKeysCommand`](https://man.openbsd.org/sshd_config#AuthorizedKeysCommand)
+provider. It resolves a user's authorized SSH keys from one or more configured
+**sources** — local key files, an HTTP endpoint, or LDAP-stored X.509
+certificates — with optional TTL caching, user/group aliasing, and a small
+unattended HTTP key server for hosts that fetch keys centrally.
+
+Built on the [duho](https://github.com/jose-pr/duho) declarative CLI framework.
+
+## Install
+
+```bash
+pip install authkeys            # core (file source only)
+pip install authkeys[http]      # + HTTP source (requests)
+pip install authkeys[ldap]      # + LDAP cert source (ldap3, cryptography)
+pip install authkeys[all]       # everything
+```
+
+> authkeys targets POSIX systems (it reads the system user/group databases via
+> `pwd`/`grp`). The package imports on any platform for testing, but resolution
+> requires a POSIX host.
+
+## Usage
+
+```bash
+authkeys resolve alice          # print alice's authorized keys
+authkeys alice                  # 'resolve' is the default command
+authkeys serve --bind 0.0.0.0 --port 8090
+```
+
+Wire it into `sshd_config`:
+
+```
+AuthorizedKeysCommand /usr/bin/authkeys resolve %u
+AuthorizedKeysCommandUser nobody
+```
+
+## Configuration
+
+authkeys reads (in order) `/etc/authkeys.conf`,
+`/etc/authkeys/authkeys.conf`, `/etc/ssh/authkeys.conf`, or a colon-separated
+list passed with `--config`. A per-user `~/.ssh/authkeys.conf` may authorize
+additional users/groups. See [`examples/authkeys.conf`](examples/authkeys.conf)
+for a fully commented example.
+
+```ini
+[cache]
+backend = authkeys.cache.AuthKeysCacheMemBackend
+expire = 3600
+expired_on_error = 1
+
+[source:files]
+backend = authkeys.sources.authorizedkeys
+paths =
+    authorized_keys
+    authorized_keys2
+
+[source:ldap]
+enabled = 1
+backend = authkeys.sources.ldap
+server = ldaps://ldap.example.com:636
+basedn = o=Example,c=US
+```
+
+### Sources
+
+| Alias (`backend =`)                | Reads keys from                              | Extra dep |
+| ---------------------------------- | -------------------------------------------- | --------- |
+| `authkeys.sources.authorizedkeys`  | `~/.ssh/authorized_keys*` files              | —         |
+| `authkeys.sources.http`            | an HTTP URL (`{username}` templated)         | `requests` |
+| `authkeys.sources.ldap`            | X.509 certs in an LDAP directory             | `ldap3`, `cryptography` |
+
+Each `[source:<name>]` section supports `enabled` and `cached` (both default
+`true`) and an optional `sanitize` callable to rewrite/drop keys.
+
+### Caching
+
+- `AuthKeysCacheMemBackend` — per-process, in-memory (default).
+- `AuthKeysCacheFileBackend` — on-disk under `path`, shared across invocations.
+
+With `expired_on_error = 1`, a source failure falls back to the last-known
+(expired) cached keys instead of returning nothing — useful when the SSH login
+must not be blocked by a transient LDAP/HTTP outage.
+
+### User / group aliasing
+
+A per-user `~/.ssh/authkeys.conf` may grant other principals' keys:
+
+```ini
+[authorized]
+users =
+    alice
+    bob
+groups =
+    admins
+```
+
+## HTTP key server (`authkeys serve`)
+
+For hosts that can't run the command locally, `authkeys serve` exposes the same
+resolution over HTTP:
+
+```
+GET /keys?username=alice&apikey=<key>
+```
+
+Bind address, port, path, and API key come from the `[serve]` config section
+(or `--bind`/`--port`). The API key is compared in constant time; pull it from
+the environment with `api_key = ${env:AUTHKEYS_APIKEY}` to keep it off disk. If
+no API key is configured, authentication is disabled — only bind to a trusted
+interface in that case.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

authkeys-0.4.0/docs/api/authkeys.md

@@ -0,0 +1,15 @@
+# authkeys
+
+::: authkeys
+
+## Usermaps
+
+::: authkeys.usermaps
+
+## Group members
+
+::: authkeys.groupmembers
+
+## Utilities
+
+::: authkeys.utils

authkeys-0.4.0/docs/api/cache.md

@@ -0,0 +1,3 @@
+# Cache
+
+::: authkeys.cache

authkeys-0.4.0/docs/api/config.md

@@ -0,0 +1,3 @@
+# Config
+
+::: authkeys.config

authkeys-0.4.0/docs/api/reference.md

@@ -0,0 +1,10 @@
+# API Reference
+
+Generated from docstrings, organized by module:
+
+- **[authkeys](authkeys.md)** — the core `AuthKeys` resolver, `AuthorizedKey`,
+  `Source`/`AuthkeysSource`, and the usermap/groupmembers/utils helpers.
+- **[Sources](sources.md)** — the built-in file, HTTP, and LDAP key sources.
+- **[Server](server.md)** — the `authkeys serve` HTTP key server.
+- **[Cache](cache.md)** — the TTL cache and its in-memory / file backends.
+- **[Config](config.md)** — `AuthkeysConfig` and config loading.

authkeys-0.4.0/docs/api/server.md

@@ -0,0 +1,3 @@
+# Server
+
+::: authkeys.server

authkeys-0.4.0/docs/api/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+::: authkeys.sources.file
+
+::: authkeys.sources.http
+
+::: authkeys.sources.github
+
+::: authkeys.sources.ldap