pykeepassgate 0.0.1__tar.gz

pykeepassgate-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+# Anchored with a leading slash, so that a rule meant for one place cannot quietly match another
+# somewhere else. What a project writes is ignored beside that project rather than from here.
+#
+# `__pycache__/` is the one exception and is deliberately recursive, because Python writes it
+# wherever a package happens to live.
+
+/.tmp/
+
+# What the gallery fixtures draw, for somebody to look at and nobody to keep. Rewritten on every
+# run and never published: `docs/images` is the set that is committed, because those are the ones a
+# reader of the documentation sees.
+/.gallery/
+/.vs/
+
+# What the coverage collector writes, one report per test assembly per run.
+/.cov/
+
+# The KeePass this repository pins, fetched by `tools/KeePass.ps1` and named after its
+# version. Provided rather than committed: it is somebody else's program.
+/.keepass/
+
+/node_modules/
+/scratchpad/
+
+# `uv` builds this from `uv.lock`, which is committed.
+/.venv/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/
+/.coverage
+__pycache__/
+
+# Per machine, and not everybody's business: the checked-in `.claude/settings.json` is.
+/.claude/settings.local.json

pykeepassgate-0.0.1/LICENSE

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

pykeepassgate-0.0.1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: pykeepassgate
+Version: 0.0.1
+Summary: The reference client for KeePassGate: pairing, and everything the gate serves.
+Project-URL: Homepage, https://github.com/mfrnd/KeePassGate
+Author: KeePassGate contributors
+License: MIT
+License-File: LICENSE
+Keywords: keepass,keepassgate,mtls,password-manager
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Description-Content-Type: text/markdown
+
+# PyKeePassGate
+
+The reference client for [KeePassGate](https://github.com/mfrnd/KeePassGate), a KeePass 2.x plugin
+that serves a small specification-defined API over mutual TLS so that automation and AI agents can
+each be given a narrow, revocable, audited slice of a database.
+
+**Reference implementation** means the code here is the second copy of the specification. Where the
+plugin and this disagree, one of them is wrong and a test should already have said so. It also means
+what is missing is a statement: a route with no method here is a route the gate does not serve.
+
+## Install
+
+```shell
+uv add pykeepassgate
+```
+
+One dependency, `cryptography`, because the gate hands over a PKCS#12 and Python's `ssl` reads PEM.
+Everything else, the command line included, is the standard library.
+
+## Pair
+
+The operator presses **Renew invite** on the **KPG** tab of the database's settings dialog and sends
+the invitation over a second channel. What they see while doing it is
+[`docs/pairing.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pairing.md), and worked examples of everything below are
+[`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md). It is spent by the first client to use it
+and it does not survive KeePass closing.
+
+```shell
+pykeepassgate pair --port 45678 --name agent-invented --profile-name reader
+```
+
+Leave `--invitation` off and the token is read from standard input, so it stays out of the shell
+history and out of the process list.
+
+The same thing from a program:
+
+```python
+from pykeepassgate import api
+
+credentials = api.pair(
+    port=45678,
+    invitation="...",
+    name="agent-invented",
+    profiles=["reader"],
+)
+
+print(credentials.profiles)  # what the operator approved, not what was asked for
+```
+
+## Use
+
+```python
+from pykeepassgate import GateClient
+
+client = GateClient.open()
+print(client.status())
+```
+
+```shell
+pykeepassgate status
+pykeepassgate whoami
+```
+
+## What to catch
+
+Every exception says what to do next rather than what went wrong, because that is the part a caller
+has to decide.
+
+| Exception | What it means, and what to do |
+| --- | --- |
+| `DatabaseLocked` | The database is locked. Wait, and try again. |
+| `GateBusy` | The gate cannot write right now, usually because a group dialog is open. Retry. |
+| `NotAdmitted` | This database holds no record for this certificate. It was never admitted, or it was revoked. Pair again. |
+| `ProofRefused` | During pairing: the token is wrong, or whatever answered is not the KeePass whose operator holds it. Stop. |
+| `PairingRefused` | The operator said no. The invitation is spent, so ask for another. |
+| `PairingUnanswered` | Nobody answered the dialog. The invitation is **not** spent, so this can be tried again. |
+| `RouteRefused` | Everything else the gate refuses, carrying the status and the one word it used. A `404` is deliberately both "no such node" and "not yours", so a client cannot map a database by asking: if the node should be there, the rule is too narrow and the operator has to widen it. |
+| `MalformedToken` | The text handed over is not an invitation, so nothing was sent. Check what was pasted. |
+| `ProtocolError` | Something on the wire is not what the protocol allows: an answer this client cannot read, or a request it will not send. Do not retry an answer it cannot read: the two halves disagree about the wire, which `tests/pykeepassgate/test_protocol.py` exists to stop. |
+| `StorageError` | What is stored for this client will not read, or could not be written. Look at the directory `status` names. |
+| `TransportError` | Nothing is listening, or the handshake failed. |
+
+## What it does not do
+
+**It does not open a `.kdbx`.** There is no file and no master password on this side of the API, by
+design. What that means for anybody expecting a `pykeepass` object is measured on the
+`spikes/pykeepass-compatibility` branch: 23 of its 56 public members are servable over the routes the
+gate already has, and the object itself is not one of them.
+
+**It defends nothing against local code execution as the user.** The client's key is on the disk,
+because a client has to still be the same client tomorrow. The whole design concedes this
+throughout, and so does this.

pykeepassgate-0.0.1/pyproject.toml

@@ -0,0 +1,141 @@
+[project]
+name = "pykeepassgate"
+version = "0.0.1"
+description = "The reference client for KeePassGate: pairing, and everything the gate serves."
+readme = "src/pykeepassgate/README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "KeePassGate contributors" }]
+keywords = ["keepass", "keepassgate", "mtls", "password-manager"]
+
+# One dependency, and it is the one that cannot be written here. `cryptography` parses the PKCS#12
+# the gate hands over and writes the PEM that `ssl` can load; the standard library reads neither.
+# Everything else, including the command line, is the standard library on purpose: this is the
+# reference implementation, so what it needs is what the protocol needs.
+dependencies = ["cryptography>=42"]
+
+[project.scripts]
+pykeepassgate = "pykeepassgate.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/mfrnd/KeePassGate"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pykeepassgate"]
+
+# The sdist default is everything the version control does not ignore, which here is the whole
+# repository: the plugin's C#, its tests, and every design document, inside a package whose whole
+# claim is that it is one dependency and the standard library. Naming the same directory is what
+# stops that.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/pykeepassgate", "LICENSE"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11",
+    "pre-commit>=4",
+    # Only the test that holds this client to the plugin's routing table reads it, and the plugin
+    # writes that table in YAML because its OpenAPI reader ships a YAML parser either way.
+    "pyyaml>=6",
+    "types-pyyaml>=6",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+]
+
+# ---------------------------------------------------------------------------------------------
+# The checks. One config for one repository, at the root, beside the two that check the prose.
+# ---------------------------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests/pykeepassgate"]
+
+[tool.ruff.lint]
+# The default set plus what catches real mistakes in a client that talks to a password manager:
+# bugbear for the traps, security for the ones that matter here, and the import and comprehension
+# rules because they are free.
+select = [
+    "E", "W",      # pycodestyle
+    "F",           # pyflakes
+    "I",           # import order
+    "B",           # bugbear
+    "C4",          # comprehensions
+    "UP",          # pyupgrade
+    "S",           # bandit
+    "RUF",         # ruff's own
+    "SIM",         # simplify
+    "PTH",         # pathlib over os.path
+    "RET",         # returns
+    "ARG",         # unused arguments
+    "N",           # naming
+    "D",           # docstrings
+]
+
+ignore = [
+    # A one-line summary is required; the blank line after it and the mood of the first word are
+    # not, because this project's comments are sentences rather than a docstring format.
+    "D203", "D212", "D401", "D407", "D413",
+
+    # N818: an exception class should be named `...Error`. Every one of these derives from
+    # `GateError`, which is, and the names are chosen to read at the place they are caught:
+    # `except DatabaseLocked` says what to do about it and `except DatabaseLockedError` does not.
+    # The guideline exists so a reader can tell an exception from a value type, and nothing in
+    # `errors.py` is a value. This is the same call, for the same reason, that `CA1710` gets on the
+    # plugin's side of the protocol.
+    "N818",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# A test says what it does in its name, and it asserts, which `S101` is about. A fake gate is
+# handed every argument whether it reads them or not, which is `ARG`. And a test vector that looks
+# like a credential is an input written down beside its expected output, which is `S105` and its
+# siblings: the whole point of `test_protocol.py` is that these values are public and reproducible.
+"tests/**/*.py" = [
+    "S101", "S105", "S106", "S107",
+    "D100", "D101", "D102", "D103", "D104", "D107",
+    "ARG001", "ARG002", "ARG005",
+]
+
+[tool.ruff.lint.isort]
+# `conftest` is imported by name because the test directory is not a package: making it one would
+# shadow the package under test, which is called the same thing.
+known-first-party = ["pykeepassgate", "conftest"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/pykeepassgate", "tests/pykeepassgate"]
+strict = true
+# A reference implementation says what it means. These three turn "it type checks" into "it says
+# what it is": no silent `Any` crossing a boundary, no untyped call slipping through, and a warning
+# when an annotation turns out to be unnecessary.
+warn_unreachable = true
+warn_return_any = true
+warn_unused_ignores = true
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests/pykeepassgate"]
+addopts = "--strict-markers --strict-config"
+
+[tool.coverage.run]
+source = ["src/pykeepassgate"]
+branch = true
+
+[tool.coverage.report]
+# The client is the reference implementation, so an untested path in it is a paragraph of the
+# specification nobody has run.
+fail_under = 90
+show_missing = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

pykeepassgate-0.0.1/src/pykeepassgate/README.md

@@ -0,0 +1,92 @@
+# PyKeePassGate
+
+The reference client for [KeePassGate](https://github.com/mfrnd/KeePassGate), a KeePass 2.x plugin
+that serves a small specification-defined API over mutual TLS so that automation and AI agents can
+each be given a narrow, revocable, audited slice of a database.
+
+**Reference implementation** means the code here is the second copy of the specification. Where the
+plugin and this disagree, one of them is wrong and a test should already have said so. It also means
+what is missing is a statement: a route with no method here is a route the gate does not serve.
+
+## Install
+
+```shell
+uv add pykeepassgate
+```
+
+One dependency, `cryptography`, because the gate hands over a PKCS#12 and Python's `ssl` reads PEM.
+Everything else, the command line included, is the standard library.
+
+## Pair
+
+The operator presses **Renew invite** on the **KPG** tab of the database's settings dialog and sends
+the invitation over a second channel. What they see while doing it is
+[`docs/pairing.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pairing.md), and worked examples of everything below are
+[`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md). It is spent by the first client to use it
+and it does not survive KeePass closing.
+
+```shell
+pykeepassgate pair --port 45678 --name agent-invented --profile-name reader
+```
+
+Leave `--invitation` off and the token is read from standard input, so it stays out of the shell
+history and out of the process list.
+
+The same thing from a program:
+
+```python
+from pykeepassgate import api
+
+credentials = api.pair(
+    port=45678,
+    invitation="...",
+    name="agent-invented",
+    profiles=["reader"],
+)
+
+print(credentials.profiles)  # what the operator approved, not what was asked for
+```
+
+## Use
+
+```python
+from pykeepassgate import GateClient
+
+client = GateClient.open()
+print(client.status())
+```
+
+```shell
+pykeepassgate status
+pykeepassgate whoami
+```
+
+## What to catch
+
+Every exception says what to do next rather than what went wrong, because that is the part a caller
+has to decide.
+
+| Exception | What it means, and what to do |
+| --- | --- |
+| `DatabaseLocked` | The database is locked. Wait, and try again. |
+| `GateBusy` | The gate cannot write right now, usually because a group dialog is open. Retry. |
+| `NotAdmitted` | This database holds no record for this certificate. It was never admitted, or it was revoked. Pair again. |
+| `ProofRefused` | During pairing: the token is wrong, or whatever answered is not the KeePass whose operator holds it. Stop. |
+| `PairingRefused` | The operator said no. The invitation is spent, so ask for another. |
+| `PairingUnanswered` | Nobody answered the dialog. The invitation is **not** spent, so this can be tried again. |
+| `RouteRefused` | Everything else the gate refuses, carrying the status and the one word it used. A `404` is deliberately both "no such node" and "not yours", so a client cannot map a database by asking: if the node should be there, the rule is too narrow and the operator has to widen it. |
+| `MalformedToken` | The text handed over is not an invitation, so nothing was sent. Check what was pasted. |
+| `ProtocolError` | Something on the wire is not what the protocol allows: an answer this client cannot read, or a request it will not send. Do not retry an answer it cannot read: the two halves disagree about the wire, which `tests/pykeepassgate/test_protocol.py` exists to stop. |
+| `StorageError` | What is stored for this client will not read, or could not be written. Look at the directory `status` names. |
+| `TransportError` | Nothing is listening, or the handshake failed. |
+
+## What it does not do
+
+**It does not open a `.kdbx`.** There is no file and no master password on this side of the API, by
+design. What that means for anybody expecting a `pykeepass` object is measured on the
+`spikes/pykeepass-compatibility` branch: 23 of its 56 public members are servable over the routes the
+gate already has, and the object itself is not one of them.
+
+**It defends nothing against local code execution as the user.** The client's key is on the disk,
+because a client has to still be the same client tomorrow. The whole design concedes this
+throughout, and so does this.

pykeepassgate-0.0.1/src/pykeepassgate/__init__.py

@@ -0,0 +1,57 @@
+"""PyKeePassGate: the reference client for KeePassGate.
+
+Two halves, and the split is deliberate. `pykeepassgate.api` is the library: pairing, the paired
+client, and the pieces of the protocol on their own so that each can be read and tested without a
+KeePass in the room. `pykeepassgate.cli` is a command line built on that library and nothing else,
+so anything the command line can do, a program can do the same way.
+
+Being the reference implementation means the code is the second copy of the specification, so what
+it does not do is a statement too: a route with no method here is a route the gate does not serve.
+"""
+
+from __future__ import annotations
+
+from .api import (
+    Credentials,
+    DatabaseLocked,
+    Exchange,
+    GateBusy,
+    GateClient,
+    GateError,
+    MalformedToken,
+    NotAdmitted,
+    Pairing,
+    PairingError,
+    PairingRefused,
+    PairingUnanswered,
+    ProofRefused,
+    ProtocolError,
+    RouteRefused,
+    Status,
+    TransportError,
+    pair,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Credentials",
+    "DatabaseLocked",
+    "Exchange",
+    "GateBusy",
+    "GateClient",
+    "GateError",
+    "MalformedToken",
+    "NotAdmitted",
+    "Pairing",
+    "PairingError",
+    "PairingRefused",
+    "PairingUnanswered",
+    "ProofRefused",
+    "ProtocolError",
+    "RouteRefused",
+    "Status",
+    "TransportError",
+    "__version__",
+    "pair",
+]

pykeepassgate-0.0.1/src/pykeepassgate/api.py

@@ -0,0 +1,96 @@
+"""The library, gathered into one name so that a program imports one thing.
+
+Everything a caller needs is re-exported here: pairing, the paired client, the credentials on disk,
+and the exceptions that say what to do next. The modules underneath stay importable, because the
+pieces of the protocol are worth reading on their own, but nothing outside this package has to know
+which module a name lives in.
+
+The one thing `api` adds rather than re-exports is `pair`, which is the whole exchange as one call.
+It exists because the two-connection shape is the protocol's business rather than the caller's, and
+a reference implementation that made every caller drive both halves by hand would be teaching the
+wrong lesson.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .client import ROOT, GateClient, Status
+from .credentials import Credentials, default_directory, load, save
+from .errors import (
+    DatabaseLocked,
+    GateBusy,
+    GateError,
+    MalformedToken,
+    NotAdmitted,
+    PairingError,
+    PairingRefused,
+    PairingUnanswered,
+    ProofRefused,
+    ProtocolError,
+    RouteRefused,
+    TransportError,
+)
+from .model import Attachment, Entry, Field, Group
+from .pairing import Exchange, Pairing
+from .transport import DEFAULT_TIMEOUT, LOOPBACK, PAIRING_TIMEOUT
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "LOOPBACK",
+    "PAIRING_TIMEOUT",
+    "ROOT",
+    "Attachment",
+    "Credentials",
+    "DatabaseLocked",
+    "Entry",
+    "Exchange",
+    "Field",
+    "GateBusy",
+    "GateClient",
+    "GateError",
+    "Group",
+    "MalformedToken",
+    "NotAdmitted",
+    "Pairing",
+    "PairingError",
+    "PairingRefused",
+    "PairingUnanswered",
+    "ProofRefused",
+    "ProtocolError",
+    "RouteRefused",
+    "Status",
+    "TransportError",
+    "default_directory",
+    "load",
+    "pair",
+    "save",
+]
+
+
+def pair(
+    port: int,
+    invitation: str,
+    name: str,
+    profiles: list[str] | None = None,
+    directory: Path | None = None,
+    profile: str = "default",
+    # Not `DEFAULT_TIMEOUT`. This is the one exchange that waits on a person, and the gate
+    # gives itself five minutes for it because its own worst case is 185 seconds. Hanging up
+    # first cancels nothing: the invitation is spent and the record is written and saved
+    # anyway, and only the answer is lost.
+    timeout: float = PAIRING_TIMEOUT,
+    host: str = LOOPBACK,
+) -> Credentials:
+    """Pair with a KeePass and keep what it hands over.
+
+    Blocks while the operator reads the dialog, which is the slow half and is meant to be. What
+    comes back says which profiles were actually approved, and that is not always what was asked
+    for: the dialog can take any of them away.
+    """
+    exchange = Pairing(port, invitation, timeout=timeout, host=host)
+    started = exchange.hello()
+    bundle = exchange.request(started, name, profiles or [])
+
+    where = directory or default_directory(profile)
+    return save(where, port, bundle)