pykeepassgate 0.0.1__py3-none-any.whl

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/__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/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)

pykeepassgate/cli.py

@@ -0,0 +1,377 @@
+"""The command line, which does nothing the library cannot.
+
+Every command here is a few lines over `pykeepassgate.api`, deliberately: if the command line could
+do something a program could not, the library would be the wrong shape. So this parses arguments,
+calls one function, and prints what came back.
+
+**It never prints a credential.** The invitation is read from an argument or from standard
+input, and what is printed afterwards is what the credentials are, not what they hold. A
+protected field is a different thing: `show` prints one when the gate answers with it, which
+is when the rule granted `P`, and prints `(withheld)` when it did not.
+
+Exit codes are the point of a command line: `0` worked, `1` the gate refused or could not be
+reached, `2` the arguments were wrong. A script can branch on that without reading English.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import api
+from .errors import GateError
+
+#: Everything went wrong that this program knows how to be wrong about.
+FAILED = 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one command and return what the shell should see."""
+    parser = _parser()
+    arguments = parser.parse_args(argv)
+
+    try:
+        return int(arguments.run(arguments))
+    except GateError as error:
+        # The exception hierarchy already says what happened in a sentence a person can act on, so
+        # the command line adds nothing to it beyond the class name for anybody grepping.
+        print(f"{type(error).__name__}: {error}", file=sys.stderr)
+        return FAILED
+    except FileNotFoundError as error:
+        print(str(error), file=sys.stderr)
+        return FAILED
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pykeepassgate",
+        description="The reference client for KeePassGate.",
+    )
+
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    pairing = commands.add_parser(
+        "pair",
+        help="become a client of a database, using an invitation from the KPG tab",
+        description=(
+            "Pairs with a KeePass over an invitation. The operator has to approve it on screen, "
+            "so this waits, and what it stores is what they approved rather than what was asked."
+        ),
+    )
+
+    pairing.add_argument(
+        "--port", type=int, required=True, help="the port the gate is listening on"
+    )
+    pairing.add_argument("--name", required=True, help="what this client should be called")
+    pairing.add_argument(
+        "--profile-name",
+        action="append",
+        default=[],
+        dest="profiles",
+        metavar="PROFILE",
+        help="a profile to ask for; repeat for more, and the operator may take any of them away",
+    )
+
+    pairing.add_argument(
+        "--invitation",
+        help="the invitation from the tab. Omit it and it is read from standard input instead.",
+    )
+
+    _shared(pairing)
+    _dialled(pairing)
+    pairing.set_defaults(run=_pair)
+
+    status = commands.add_parser(
+        "status",
+        help="ask the gate whether it is listening, unlocked, and still admitting this client",
+    )
+
+    _shared(status)
+    _dialled(status)
+    status.set_defaults(run=_status)
+
+    who = commands.add_parser("whoami", help="say what this client is, without connecting")
+    _shared(who)
+    who.set_defaults(run=_whoami)
+
+    groups = commands.add_parser(
+        "groups",
+        help="list the groups this client may see",
+        description=(
+            "Anchored at the root, so it needs `list` there. Name a group to walk one level "
+            "instead, which is a different question and a different grant."
+        ),
+    )
+
+    groups.add_argument("--under", help="a group identifier, or root, to list one level below")
+    _shared(groups)
+    _dialled(groups)
+    groups.set_defaults(run=_groups)
+
+    entries = commands.add_parser(
+        "entries",
+        help="list the entries this client may see",
+    )
+
+    entries.add_argument(
+        "--group",
+        help="a group identifier, or root, for that group's own entries",
+    )
+    _shared(entries)
+    _dialled(entries)
+    entries.set_defaults(run=_entries)
+
+    show = commands.add_parser(
+        "show",
+        help="read one entry, secrets included",
+        description=(
+            "Prints every string the entry holds. A protected one arrives only when the rule "
+            "grants `protected`. Redirect it or read it directly: this is the one command "
+            "that puts a password on a terminal."
+        ),
+    )
+
+    show.add_argument("uuid", help="the entry's identifier")
+    _shared(show)
+    _dialled(show)
+    show.set_defaults(run=_show)
+
+    add = commands.add_parser("add", help="create an entry in a group")
+    add.add_argument("--group", default=api.ROOT, help="where to put it, by identifier or root")
+    add.add_argument("--title", help="what to call it")
+    add.add_argument("--username", help="the user name")
+    add.add_argument("--url", help="the address")
+    add.add_argument("--notes", help="the notes")
+    add.add_argument(
+        "--password",
+        action="store_true",
+        help="read the password from standard input, so it stays out of the process list",
+    )
+
+    _shared(add)
+    _dialled(add)
+    add.set_defaults(run=_add)
+
+    remove = commands.add_parser("remove", help="delete an entry")
+    remove.add_argument("uuid", help="the entry's identifier")
+    _shared(remove)
+    _dialled(remove)
+    remove.set_defaults(run=_remove)
+
+    files = commands.add_parser("attachments", help="list an entry's attachments")
+    files.add_argument("uuid", help="the entry's identifier")
+    _shared(files)
+    _dialled(files)
+    files.set_defaults(run=_attachments)
+
+    fetch = commands.add_parser("fetch", help="write one attachment to a file")
+    fetch.add_argument("uuid", help="the entry's identifier")
+    fetch.add_argument("name", help="the attachment's name")
+    fetch.add_argument("--to", type=Path, required=True, help="where to write it")
+    _shared(fetch)
+    _dialled(fetch)
+    fetch.set_defaults(run=_fetch)
+
+    return parser
+
+
+
+def _shared(parser: argparse.ArgumentParser) -> None:
+    # One slot, so saying it twice is an error rather than a silent precedence. Both name
+    # the directory an identity lives in. `--profile` chooses the usual place for a name and
+    # `--directory` gives one outright, and `pair --directory D --profile work` used to store
+    # where `status --profile work` would not look. Exit code 2, which the module docstring
+    # already reserves for arguments that are wrong.
+    where = parser.add_mutually_exclusive_group()
+    where.add_argument(
+        "--profile",
+        default="default",
+        help="which stored identity to use, since a client can pair with more than one database",
+    )
+
+    where.add_argument(
+        "--directory",
+        type=Path,
+        help="where the identity is stored, if not the usual place for this platform",
+    )
+
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=None,
+        help="seconds to wait for the gate, if not the default for what is being done",
+    )
+
+
+def _dialled(parser: argparse.ArgumentParser) -> None:
+    """Where to open the socket, for the commands that open one.
+
+    Not on `whoami`, which answers out of the stored identity and never connects: an option that
+    cannot change what a command does is an option that misleads whoever reads `--help`.
+    """
+    parser.add_argument(
+        "--host",
+        default=api.LOOPBACK,
+        help=(
+            "where to dial, if the gate is not reachable on loopback. It binds to loopback, so "
+            "anything else is the local end of a tunnel somebody put in front of it."
+        ),
+    )
+
+
+def _waiting(arguments: argparse.Namespace) -> dict[str, float]:
+    """`--timeout` when it was given, and nothing at all when it was not.
+
+    Passing nothing is what lets each caller keep its own default: a pairing waits on a
+    person and gets `transport.PAIRING_TIMEOUT`, and everything else gets the ordinary
+    one. Passing `None` through would flatten both into whatever this file decided.
+    """
+    return {} if arguments.timeout is None else {"timeout": arguments.timeout}
+
+
+def _pair(arguments: argparse.Namespace) -> int:
+    invitation = arguments.invitation
+    if not invitation:
+        # Read rather than argued, so the token does not end up in a shell history or in the
+        # process list, where anything running as this user can read it.
+        invitation = sys.stdin.readline().strip()
+
+    credentials = api.pair(
+        port=arguments.port,
+        invitation=invitation,
+        name=arguments.name,
+        profiles=list(arguments.profiles),
+        directory=arguments.directory,
+        profile=arguments.profile,
+        host=arguments.host,
+        **_waiting(arguments),
+    )
+
+    print(f"paired as {credentials.subject} with database {credentials.database}")
+    print(f"profiles approved: {', '.join(credentials.profiles) or 'none'}")
+    print(f"stored in {credentials.directory}")
+    return 0
+
+
+def _status(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+    status = client.status()
+    print(f"gate {status.version} serving database {status.database}")
+    return 0 if status.ok else FAILED
+
+
+def _whoami(arguments: argparse.Namespace) -> int:
+    where = arguments.directory or api.default_directory(arguments.profile)
+    credentials = api.load(where)
+    print(f"subject:  {credentials.subject}")
+    print(f"database: {credentials.database}")
+    print(f"profiles: {', '.join(credentials.profiles) or 'none'}")
+    print(f"expires:  {credentials.expires}")
+    print(f"port:     {credentials.port}")
+    print(f"stored:   {credentials.directory}")
+    return 0
+
+
+def _groups(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+    found = client.subgroups(arguments.under) if arguments.under else client.groups()
+
+    for group in found:
+        print(f"{group.uuid}  {group.name}")
+
+    return 0
+
+
+def _entries(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+
+    for entry in client.entries(arguments.group):
+        # A withheld title is not a title. Saying so beats printing the word "None".
+        print(f"{entry.uuid}  {entry.title if entry.title is not None else '(withheld)'}")
+
+    return 0
+
+
+def _show(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+    entry = client.entry(arguments.uuid)
+
+    print(f"uuid:  {entry.uuid}")
+    print(f"group: {entry.group}")
+
+    for name, value in sorted((entry.fields or {}).items()):
+        guarded = " (protected)" if name in entry.protected else ""
+        # A withheld value is not a value. Printing it as one would put the word "None" where a
+        # password goes, which reads exactly like a password somebody chose badly.
+        shown = "(withheld)" if value is None else value
+        print(f"{name}: {shown}{guarded}")
+
+    return 0
+
+
+def _add(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+
+    password = None
+    if arguments.password:
+        # Read rather than argued, for the same reason the invitation is: an argument is in the
+        # process list, where anything running as this user can read it.
+        password = sys.stdin.readline().rstrip("\n")
+
+    uuid = client.create_entry(
+        group=arguments.group,
+        title=arguments.title,
+        username=arguments.username,
+        password=password,
+        url=arguments.url,
+        notes=arguments.notes,
+    )
+
+    print(uuid)
+    return 0
+
+
+def _remove(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+    client.delete_entry(arguments.uuid)
+    print(f"removed {arguments.uuid}")
+    return 0
+
+
+def _attachments(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+
+    for attachment in client.attachments(arguments.uuid):
+        print(f"{attachment.size:>10}  {attachment.name}")
+
+    return 0
+
+
+def _fetch(arguments: argparse.Namespace) -> int:
+    client = api.GateClient.open(
+        arguments.directory, arguments.profile, arguments.host, **_waiting(arguments)
+    )
+    attachment = client.attachment(arguments.uuid, arguments.name)
+
+    arguments.to.write_bytes(attachment.content or b"")
+    print(f"wrote {len(attachment.content or b'')} bytes to {arguments.to}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover, the module entry point
+    raise SystemExit(main())