pykeepassgate 0.0.1__py3-none-any.whl

pykeepassgate/transport.py

@@ -0,0 +1,374 @@
+"""One TLS connection, one request, then closed. The client half of what the gate serves.
+
+The gate answers one request per connection and never offers keep-alive, so this does not pretend
+otherwise: a connection is opened, a request is written, an answer is read to the end, and the
+socket is closed. That is also why the name is rebuilt every time.
+
+**Why this is written out rather than handed to a library.** The name in the ClientHello rotates
+per connection and is not a host name anybody resolves, so the connection has to be made to an
+address and the name given separately. `http.client` derives the name it sends from the host it
+dials, which is exactly the coupling this protocol breaks. What is left to write is a status line
+and a header block.
+
+**Why the server certificate is exposed before the body is written.** During pairing the request
+body carries a proof over ``tls-server-end-point``, which is a hash of the certificate the server
+is serving with. So the handshake has to have happened, and its certificate has to be readable,
+while the body is still being built.
+
+**Why one identity is refused before a request reaches it.** A locked database answers with a
+responder certificate, and `CA.md` 208 marks that certificate so a client can refuse to send real
+requests over it. Refusing has to happen before the write rather than after the answer, because a
+request body carries whatever it was going to store.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import socket
+import ssl
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from cryptography import x509
+
+from .errors import DatabaseLocked, ProtocolError, TransportError
+
+#: Where the gate binds, and therefore where a client dials unless it is told otherwise. Reaching
+#: a gate from another machine is a tunnel's job, and a tunnel puts its own end somewhere: that is
+#: the whole of why `connect` takes a host at all, and why the default is this one.
+LOOPBACK = "127.0.0.1"
+
+#: How much of an answer to read before giving up on it. This is the only bound there is: the gate
+#: bounds what it accepts, not what it sends, and an attachment answer is as large as whatever the
+#: operator attached in KeePass. So this also decides the largest attachment this client can read,
+#: and a bigger one fails here rather than being truncated.
+MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+#: What marks the certificate a locked database answers with, and the whole of what tells one
+#: apart: `AuthorityIssuer.ResponderClaim` on the plugin's side, written into the subject
+#: alternative name as a URI. A responder is minted at unlock and held only in memory, and it can
+#: say nothing but that the database is locked, so a request is never sent over one.
+RESPONDER_CLAIM = "kpg://host/responder"
+
+#: How long to wait, in seconds, for anything that is not a pairing.
+DEFAULT_TIMEOUT = 120.0
+
+#: What a pairing gets instead, which is the one exchange that waits on a person. It has to outlast
+#: the plugin's own sum of `PairingOptions.ApprovalTimeout` two minutes, plus
+#: `PairingApprovalPrompt.Grace` fifteen seconds, plus `DatabaseWriter.LockTimeout` twenty and
+#: `WriteTimeout` thirty. That sum is 185 seconds, and is why `GateOptions.PairingBudget` is five
+#: minutes. Hanging up early cancels nothing: the invitation is spent and the record is written and
+#: saved regardless, and only the answer is lost, leaving a record for a certificate nobody holds.
+PAIRING_TIMEOUT = 300.0
+
+
+@dataclass(frozen=True)
+class Response:
+    """What came back from one request."""
+
+    status: int
+    body: str
+
+    def json(self) -> dict[str, Any]:
+        """The body as an object, or a refusal if it is not one."""
+        try:
+            parsed = json.loads(self.body)
+        except ValueError as error:
+            raise ProtocolError(
+                f"the gate answered {self.status} with something that is not JSON"
+            ) from error
+
+        if not isinstance(parsed, dict):
+            raise ProtocolError(f"the gate answered {self.status} with JSON that is not an object")
+
+        return parsed
+
+    def error(self) -> str:
+        """The one word the gate refuses with, or an empty string if it did not give one."""
+        try:
+            named = self.json().get("error")
+        except ProtocolError:
+            return ""
+
+        return named if isinstance(named, str) else ""
+
+
+def unpaired_context() -> ssl.SSLContext:
+    """The context for a client that has no anchor yet, which is every client while it pairs.
+
+    Nothing is verified here and nothing can be: the authority is what pairing is for. The server's
+    proof over the certificate in use is what decides, and it is checked after the handshake rather
+    than during it. Refusing the certificate here instead would refuse every honest server too.
+    """
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    _pin_to_tls13(context)
+    return context
+
+
+def paired_context(authority: Path, identity: Path) -> ssl.SSLContext:
+    """The context for a client that has been through pairing.
+
+    The authority handed over at pairing is the only anchor loaded, so a certificate that does not
+    chain to it fails the handshake rather than being reported afterwards. That is the difference
+    from the plugin's own side of this, where the platform's chain builder had to be told to pin
+    and then checked by hand: here the trust store holds one certificate and nothing else.
+
+    Host name checking is off because the name rotates by design and is not a name anybody
+    resolves. What replaces it is the anchor: only the authority that issued this client's own
+    certificate can produce a host certificate this will accept.
+    """
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_REQUIRED
+    context.load_verify_locations(cafile=str(authority))
+    context.load_cert_chain(certfile=str(identity))
+    _pin_to_tls13(context)
+    return context
+
+
+class Connection:
+    """One open connection. Not reusable, because the gate does not reuse them either."""
+
+    def __init__(self, wrapped: ssl.SSLSocket) -> None:
+        """Take a socket that has already shaken hands.
+
+        Keeps the certificate it was served with, which the proofs are computed over, and reads
+        off it whether the identity that answered is the one a locked database has.
+        """
+        self._socket = wrapped
+        der = wrapped.getpeercert(binary_form=True)
+        if not der:
+            raise TransportError("the server sent no certificate")
+
+        self.server_certificate = der
+        self.responder = _responder(der)
+
+    def send(self, method: str, path: str, body: str = "") -> Response:
+        """Write one request and read the whole answer, unless a responder answered the handshake.
+
+        Nothing is written to a responder. What a locked database answers is `503 locked` on
+        every path and method, decided before it reads anything, so there is no request this
+        could carry that would be answered; and an impostor that came by the responder key while
+        the database was locked reads nothing but could answer with a fabricated secret. Waiting
+        for the answer to decide that has already handed over the request, which on a write is
+        the value being stored.
+        """
+        if self.responder:
+            raise DatabaseLocked(
+                "the connection was served with the responder identity, which only a locked "
+                "database has, so no request was sent over it"
+            )
+
+        _check(method, path)
+        payload = body.encode("utf-8")
+        head = (
+            f"{method} {path} HTTP/1.1\r\n"
+            # The name this connection was made under, which is what the gate resolved it by. It is
+            # sent because HTTP/1.1 requires a `Host`, not because the gate reads it.
+            f"Host: {self._socket.server_hostname}\r\n"
+            "Content-Type: application/json\r\n"
+            f"Content-Length: {len(payload)}\r\n"
+            "\r\n"
+        )
+
+        try:
+            self._socket.sendall(head.encode("ascii") + payload)
+            raw = self._read_all()
+        except (OSError, ssl.SSLError) as error:
+            raise TransportError(f"the connection failed: {error}") from error
+
+        return _parse(raw)
+
+    def close(self) -> None:
+        """Close the socket, whatever state it is in."""
+        # Suppressed: a socket that is already broken is what this method is for.
+        with contextlib.suppress(OSError):
+            self._socket.close()
+
+    def _read_all(self) -> bytes:
+        """Read until the answer is whole, which is what it said rather than when it ends.
+
+        The gate frames every response and closes after it, so reading to the close gives the
+        right answer for one that completed. It gives the wrong one for everything else: a
+        response cut short reads as a complete one, and a peer that frames correctly and does
+        not close costs the whole timeout and then has its answer thrown away. Neither peer
+        has to be the gate, because during pairing this client has no anchor and verifies
+        nothing.
+        """
+        buffer = bytearray()
+        declared: int | None = None
+        body_at = -1
+
+        while True:
+            chunk = self._socket.recv(65536)
+            if not chunk:
+                # Nothing declared a length, or the peer stopped early. `_parse` says which.
+                return bytes(buffer)
+
+            buffer += chunk
+
+            # Checked after the append rather than before it. Before, the loop enters `recv` with
+            # the buffer already at the cap, so a peer feeding it gets one whole chunk past the
+            # number this is here to enforce.
+            if len(buffer) > MAX_RESPONSE_BYTES:
+                raise TransportError(f"the answer is over {MAX_RESPONSE_BYTES} bytes")
+
+            if body_at < 0:
+                blank = buffer.find(b"\r\n\r\n")
+                if blank < 0:
+                    continue
+
+                body_at = blank + 4
+                declared = _declared_length(bytes(buffer[:blank]).decode("ascii", "replace"))
+
+            if declared is not None and len(buffer) - body_at >= declared:
+                return bytes(buffer)
+
+
+@contextmanager
+def connect(
+    port: int,
+    context: ssl.SSLContext,
+    server_name: str,
+    host: str = LOOPBACK,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> Iterator[Connection]:
+    """Open one connection, hand it over, and close it however this ends."""
+    try:
+        raw = socket.create_connection((host, port), timeout=timeout)
+    except OSError as error:
+        raise TransportError(f"nothing is listening on {host}:{port}: {error}") from error
+
+    try:
+        wrapped = context.wrap_socket(raw, server_hostname=server_name)
+    except (OSError, ssl.SSLError) as error:
+        raw.close()
+        # A handshake that fails against a paired context is the interesting one: it means the
+        # certificate did not chain to the authority this client pinned at pairing.
+        raise TransportError(f"the handshake failed: {error}") from error
+
+    connection = Connection(wrapped)
+    try:
+        yield connection
+    finally:
+        connection.close()
+
+
+def _responder(der: bytes) -> bool:
+    """Whether this certificate is the one a locked database answers with.
+
+    Read off the marker rather than off the subject name, because the subject is a convention and
+    `CA.md` 208 asks for something a client can decide on. The marker cannot be put on a certificate
+    or taken off one either: what the authority signed is what arrives, and a paired client accepts
+    nothing the authority did not sign.
+
+    An encoding this cannot read is not a responder, which is the direction that keeps an honest
+    connection working: a certificate the authority issued is one this reads, and one it did not
+    issue never gets past the pin.
+    """
+    try:
+        certificate = x509.load_der_x509_certificate(der)
+        names = certificate.extensions.get_extension_for_class(x509.SubjectAlternativeName)
+    # Everything reading a certificate can refuse with: bytes that are not one, no subject
+    # alternative name at all, two of them, and a name of a kind this library will not decode.
+    except (
+        ValueError,
+        x509.ExtensionNotFound,
+        x509.DuplicateExtension,
+        x509.UnsupportedGeneralNameType,
+    ):
+        return False
+
+    return RESPONDER_CLAIM in names.value.get_values_for_type(x509.UniformResourceIdentifier)
+
+
+def _pin_to_tls13(context: ssl.SSLContext) -> None:
+    """Nothing older is offered, so nothing older can be negotiated.
+
+    The gate serves TLS 1.3 only. Pinning both ends of the range rather than the minimum means a
+    downgrade is a failed handshake here rather than a connection this client did not intend to
+    make.
+    """
+    context.minimum_version = ssl.TLSVersion.TLSv1_3
+    context.maximum_version = ssl.TLSVersion.TLSv1_3
+
+
+def _check(method: str, path: str) -> None:
+    """Refuse anything that could not be a request line, before it reaches the wire.
+
+    The gate reads a head as US-ASCII and refuses a byte that is not, so a path this client cannot
+    spell is refused here rather than sent. Two things go wrong otherwise, and neither is the
+    caller's fault to discover on the wire. A carriage return or a newline in a path
+    replaces the whole head the gate parses, headers and all, with whatever the caller wrote;
+    and a character outside ASCII raises `UnicodeEncodeError` out of `encode`, which is a
+    `ValueError` and so is not a `GateError` at all.
+
+    `send` is the documented way to reach a route this client has no method for, so its arguments
+    are caller data, and the threat model says a caller can be prompt-injected.
+    """
+    if not method.isascii() or not method.isalpha():
+        raise ProtocolError(f"that is not a method: {method!r}")
+
+    if not path.startswith("/") or not path.isascii():
+        raise ProtocolError(f"that is not a path this client will send: {path!r}")
+
+    if any(character in path for character in " \r\n\t\x00"):
+        raise ProtocolError(f"that path holds something a request line cannot: {path!r}")
+
+
+def _declared_length(head: str) -> int | None:
+    """What the answer said its body would be, if it said."""
+    for line in head.split("\r\n")[1:]:
+        name, _, value = line.partition(":")
+        if name.strip().lower() != "content-length":
+            continue
+
+        try:
+            return int(value.strip())
+        except ValueError:
+            raise ProtocolError(f"that is not a content length: {value.strip()!r}") from None
+
+    return None
+
+
+def _parse(raw: bytes) -> Response:
+    """Read the status line and the body, and nothing else.
+
+    The gate sends a `Content-Length` and closes, so the body is what follows the blank line. There
+    is no chunked encoding to handle because the gate refuses to produce one.
+
+    **The length is read rather than assumed.** Believing the close instead makes a truncated
+    answer indistinguishable from a complete one, and an answer whose body never arrived would
+    become an empty object. A caller cannot tell that from a gate that said so.
+    """
+    if not raw:
+        raise TransportError("the connection was closed without an answer")
+
+    blank = raw.find(b"\r\n\r\n")
+    if blank < 0:
+        raise ProtocolError("the answer has no header block")
+
+    line = raw[: raw.find(b"\r\n")].decode("ascii", "replace")
+    parts = line.split(" ", 2)
+    if len(parts) < 2 or not parts[0].startswith("HTTP/"):
+        raise ProtocolError(f"that is not a status line: {line!r}")
+
+    try:
+        status = int(parts[1])
+    except ValueError as error:
+        raise ProtocolError(f"that is not a status: {parts[1]!r}") from error
+
+    body = raw[blank + 4 :]
+    declared = _declared_length(raw[:blank].decode("ascii", "replace"))
+    if declared is not None and len(body) < declared:
+        raise TransportError(
+            f"the answer stopped {declared - len(body)} bytes short of its own content length"
+        )
+
+    return Response(status=status, body=body.decode("utf-8", "replace"))

pykeepassgate-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,19 @@
+pykeepassgate/README.md,sha256=SPDCtvhZqnHBGBcVt3BNCkuGXfeaiWUVT4VNs2HUF-4,4254
+pykeepassgate/__init__.py,sha256=x1zpRBcAMb_qeFxJ9oLCvogiZgJ3cRKifEITxa1V3mU,1438
+pykeepassgate/api.py,sha256=4AeKOw5oX2LnJDXDlB-dgGj8u_wbU8Uhht_bZSWB6Is,3051
+pykeepassgate/cli.py,sha256=1TzHjlgCjv3ub1xrF-9NnGufcA4RNrbeOTjPhOJnvLc,13574
+pykeepassgate/client.py,sha256=j_yledBdVyGATOeX0CwvVX5wN_ujmqlt7IzQav5O9tw,17653
+pykeepassgate/credentials.py,sha256=6Kj11E0fPxg_qpy8GKcESzcIOqu52eQ07RCeEnr_9nc,14414
+pykeepassgate/errors.py,sha256=XEde6BjJ6UcfimnXr48DNIxledKOZ8bjxmzZAmWTxog,3606
+pykeepassgate/model.py,sha256=UmaiXpn5Lqd4kd7DFUmCyI9T1d2F0Q2weRjHGvkcm24,7744
+pykeepassgate/pairing.py,sha256=Sg1WUdWPxL5tgdIfxczzIEgMyjABFZOvTRCZ7awBMng,11465
+pykeepassgate/proofs.py,sha256=xyYZkYSMmoEeHKSkQYd325K9aGEPF5Uhy5rnEKI0xbM,3946
+pykeepassgate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pykeepassgate/sni.py,sha256=UskduO3PJEPwIG3-MSgxBw0Vk9iHwOY2BNMKibqtgIk,2763
+pykeepassgate/token.py,sha256=gfw5DpGKGL7A0J_nYqSmc97ZHNDyB1UuQ3HUsibgWrs,2625
+pykeepassgate/transport.py,sha256=4TH14Tvf5GoaHj3c7Evr0eUJt4DExLBLVwODdRgb3PU,16786
+pykeepassgate-0.0.1.dist-info/METADATA,sha256=M3uBt76vedflEwYHNEEayec3oSk2pPhgQ5uR5_9H63w,4676
+pykeepassgate-0.0.1.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+pykeepassgate-0.0.1.dist-info/entry_points.txt,sha256=So3UZISPwK4VzDVOvRbVz7clsX6kYUUoJqiKZmTZ0uQ,57
+pykeepassgate-0.0.1.dist-info/licenses/LICENSE,sha256=uCertC9NeOzBTVLtAfAgtD9HznOtGxAdSD711DiCMhs,1091
+pykeepassgate-0.0.1.dist-info/RECORD,,

pykeepassgate-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

pykeepassgate-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pykeepassgate = pykeepassgate.cli:main

pykeepassgate-0.0.1.dist-info/licenses/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.