pykeepassgate 0.0.1__py3-none-any.whl

pykeepassgate/credentials.py

@@ -0,0 +1,323 @@
+"""What a paired client keeps, and where it keeps it.
+
+Pairing hands over two secrets, a trust anchor and some text about them. The authority is a
+certificate anybody may see; what has to stay unread is the client's own key and the gate key. This
+writes each of the three to a file of its own and the text to a fourth, so that nothing secret is in
+the file a person is most likely to open, paste or attach.
+
+**The client's key is on the disk, and that is not the contradiction it looks like.** The plugin
+goes to some trouble to keep the *host* key out of the user's profile, because a password manager
+holding the database can hold its own key in memory for as long as it runs. A client is a program
+that has to still be the same client tomorrow, so its key has to survive it exiting. What the
+design concedes throughout, and concedes here as well, is local code execution as the user: nothing
+in this file defends against it, and nothing claims to.
+
+What it does do is refuse to be careless. The directory and the files are *created* with
+owner-only permissions where the platform has them, rather than created and then narrowed, and
+the key is written once rather than through a temporary file that a crash could leave behind.
+Nothing is written at all until the whole bundle has been read and found to be what it claims.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.serialization import pkcs12
+
+from . import sni
+from .errors import ProtocolError, StorageError
+
+IDENTITY_FILE = "identity.pem"
+AUTHORITY_FILE = "authority.pem"
+GATE_KEY_FILE = "gate.key"
+DETAILS_FILE = "client.json"
+
+#: Owner read and write, and nothing for anybody else. Meaningless on Windows, where the file's
+#: inherited ACL is what actually decides, so it is applied anyway and relied on nowhere.
+_OWNER_ONLY = stat.S_IRUSR | stat.S_IWUSR
+
+
+def default_directory(name: str = "default") -> Path:
+    """Where credentials live when nobody says otherwise.
+
+    Per profile rather than one place, because a client that has paired with two databases holds
+    two identities and they are not interchangeable.
+    """
+    # `os.name` rather than `sys.platform`, which a type checker narrows to whichever platform it
+    # happens to be running on and then calls the other branch unreachable.
+    if os.name == "nt":
+        # Local rather than roaming. What goes in here is an unencrypted private key and
+        # a gate key, and `%APPDATA%` is copied to a domain file server at logoff on a
+        # machine with a roaming profile or folder redirection, which are the ordinary
+        # enterprise settings. A credential that identifies this client should not
+        # follow the person to every machine they sign into.
+        local = os.environ.get("LOCALAPPDATA")
+        base = Path(local) if local else Path.home() / "AppData" / "Local"
+    else:
+        config = os.environ.get("XDG_CONFIG_HOME")
+        base = Path(config) if config else Path.home() / ".config"
+
+    return base / "pykeepassgate" / name
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """One paired identity: where it is stored, and what it is for."""
+
+    directory: Path
+    port: int
+    subject: str
+    database: str
+    profiles: tuple[str, ...]
+    expires: str
+
+    @property
+    def identity(self) -> Path:
+        """The client's own certificate and key, which `ssl` loads as one file."""
+        return self.directory / IDENTITY_FILE
+
+    @property
+    def authority(self) -> Path:
+        """The one certificate this client trusts to have issued a host certificate."""
+        return self.directory / AUTHORITY_FILE
+
+    @property
+    def gate_key(self) -> bytes:
+        """The key every connection after pairing is named from."""
+        try:
+            return (self.directory / GATE_KEY_FILE).read_bytes()
+        except OSError as error:
+            # `FileNotFoundError` is one of these and the command line catches it by
+            # name. The rest would otherwise reach the caller mid request as a bare
+            # `OSError`: a file locked by a backup agent, a directory locked down
+            # after this client opened.
+            raise StorageError(f"the gate key in {self.directory} will not read") from error
+
+
+def save(directory: Path, port: int, bundle: dict[str, Any]) -> Credentials:
+    """Write what pairing handed over, and hand back what a client needs to use it.
+
+    The PKCS#12 the gate sends is converted to PEM here rather than at every connection, because
+    `ssl` reads PEM from a path and nothing else, and because converting once means the key is
+    handled once.
+
+    **Everything is read before anything is written.** A bundle refused halfway destroys a
+    working identity: the key and the gate key would already be the new ones while the anchor
+    and the details still described the old, so `load` would report a subject that does not
+    belong to the key beside it. On a first pairing it would leave an unencrypted key with no
+    `client.json`, which `load` refuses, so nothing would ever clean it up.
+    """
+    # Everything is read before anything is written. See the note in the docstring above: a
+    # bundle refused halfway is a working identity destroyed, and the invitation that produced
+    # it is spent either way, so there is nothing left to try again with.
+    identity = _identity(_text(bundle, "identity"))
+    anchor = _anchor(_text(bundle, "authority"))
+    key = _gate_key(_text(bundle, "gateKey"))
+    details = _details(port, bundle)
+
+    _make(directory)
+
+    _write(directory / IDENTITY_FILE, identity)
+    _write(directory / GATE_KEY_FILE, key)
+    _write(directory / AUTHORITY_FILE, anchor)
+    _write(directory / DETAILS_FILE, details)
+    return load(directory)
+
+
+def load(directory: Path) -> Credentials:
+    """Read back what `save` wrote.
+
+    This is the one place that reads a file somebody could have edited, truncated or filled a
+    disk halfway through, so it is the one place that refuses in this library's own terms. Left
+    alone, a `client.json` that will not parse arrives as `JSONDecodeError`, one missing its
+    port as `KeyError`, one holding a JSON array as `TypeError` and one whose port is not a
+    number as `ValueError`. That is four ways past a caller who was promised one root to catch,
+    and four tracebacks out of a command line that documents an exit code instead.
+    """
+    details_path = directory / DETAILS_FILE
+    if not details_path.exists():
+        raise FileNotFoundError(f"no paired client in {directory}")
+
+    try:
+        details = json.loads(details_path.read_text("utf-8"))
+    except (OSError, ValueError) as error:
+        raise StorageError(f"{details_path} will not read: {error}") from error
+
+    if not isinstance(details, dict):
+        raise StorageError(f"{details_path} is not what this client wrote")
+
+    try:
+        port = int(details["port"])
+    except (KeyError, TypeError, ValueError) as error:
+        raise StorageError(f"{details_path} names no port this client can use") from error
+
+    return Credentials(
+        directory=directory,
+        port=port,
+        subject=str(details.get("subject", "")),
+        database=str(details.get("database", "")),
+        profiles=tuple(details.get("profiles") or []),
+        expires=str(details.get("expires", "")),
+    )
+
+
+def _identity(value: str) -> bytes:
+    """The PKCS#12 the gate sent, as the PEM `ssl` will read."""
+    try:
+        key, certificate, _ = pkcs12.load_key_and_certificates(
+            _base64(value, "identity"),
+            # The gate writes the PKCS#12 with no password: what protects it in the database is
+            # the database, and what protects it here is the file.
+            password=None,
+        )
+    except ValueError as error:
+        raise ProtocolError("the bundle's identity is not a PKCS#12") from error
+
+    if key is None or certificate is None:
+        raise ProtocolError("the bundle's identity carries no certificate and key")
+
+    return certificate.public_bytes(serialization.Encoding.PEM) + key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def _anchor(value: str) -> bytes:
+    """The trust anchor, parsed rather than wrapped in delimiters.
+
+    Writing the PEM markers around whatever arrived stores a base64 blob that need not be a
+    certificate at all, and the refusal then turns up at the next connection out of
+    `SSLContext.load_verify_locations` as an `SSLError`, which is an `OSError` and so is not a
+    `GateError`. The identity beside it is parsed; this is the same care for the half of the
+    bundle that decides who this client will trust from here on.
+    """
+    try:
+        certificate = x509.load_der_x509_certificate(_base64(value, "authority"))
+    except ValueError as error:
+        raise ProtocolError("the bundle's authority is not a certificate") from error
+
+    return certificate.public_bytes(serialization.Encoding.PEM)
+
+
+def _gate_key(value: str) -> bytes:
+    """The key every name after pairing is built from, at the one length it can be."""
+    key = _base64(value, "gateKey")
+    if len(key) != sni.KEY_LENGTH:
+        raise ProtocolError(f"a gate key is {sni.KEY_LENGTH} bytes, not {len(key)}")
+
+    return key
+
+
+def _details(port: int, bundle: dict[str, Any]) -> bytes:
+    """The text about the identity, which is the part of the bundle nothing else checks."""
+    profiles = bundle.get("profiles") or []
+    if not isinstance(profiles, list) or not all(isinstance(name, str) for name in profiles):
+        # `list()` over a string spells it out one character at a time, and the operator is
+        # then shown six profiles nobody approved.
+        raise ProtocolError("the bundle's profiles are not a list of names")
+
+    details = {
+        "port": port,
+        "subject": _optional(bundle, "subject"),
+        "database": _optional(bundle, "database"),
+        "expires": _optional(bundle, "expires"),
+        "profiles": list(profiles),
+    }
+
+    return json.dumps(details, indent=2).encode("utf-8") + b"\n"
+
+
+def _optional(bundle: dict[str, Any], key: str) -> str:
+    """Text the bundle may leave out, which is not the same as text it set to null.
+
+    `get` with a default fires only on absence, so a JSON `null` travels all the way to `str()`
+    and comes back as the four letters `None`.
+    """
+    value = bundle.get(key)
+    return value if isinstance(value, str) else ""
+
+
+def _make(directory: Path) -> None:
+    """Create the directory and whatever it needs above it, narrowing only what this created.
+
+    The narrowing has to happen after the fact rather than in the call: `mkdir` applies its
+    `mode` to the leaf alone and creates everything above it with the process umask, so a
+    `pykeepassgate` directory this call brings into existence would name which profiles exist
+    to anybody while the files inside it are not readable at all.
+
+    **What was already there keeps the mode it had**, and that is the whole of what this
+    refuses to do. A directory the caller named is the caller's, and its parent is nobody's
+    business here: `--directory ~/agent` would otherwise change the mode of a home directory,
+    and a parent this process does not own, `/tmp` among them, would refuse the change and
+    raise. Either way the invitation is spent by then, the record is written and saved, and the
+    certificate is in hand with nowhere to put it, so a refusal here loses an identity that
+    cannot be asked for again.
+    """
+    # Collected before the call, because afterwards there is no way to tell what it made.
+    fresh = [path for path in (directory, *directory.parents) if not path.exists()]
+    directory.mkdir(parents=True, exist_ok=True, mode=stat.S_IRWXU)
+    for path in fresh:
+        _own(path, stat.S_IRWXU)
+
+
+def _write(path: Path, content: bytes) -> None:
+    """Create the file closed, rather than creating it open and narrowing it after.
+
+    `Path.write_bytes` creates with the process umask, which is world-readable under the
+    usual one, and the `chmod` is the statement after it: the client's key exists at
+    0644 for the interval between the two. Opening with the mode closes that interval.
+    """
+    try:
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _OWNER_ONLY)
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(content)
+    except OSError as error:
+        raise StorageError(f"{path} could not be written: {error}") from error
+
+    # The mode above applies only where the file is created, so an overwrite keeps
+    # whatever the old one had. A re-pair is an overwrite.
+    _own(path, _OWNER_ONLY)
+
+
+def _own(path: Path, mode: int) -> None:
+    """Narrow what a platform with permissions will honor.
+
+    Suppressed on Windows only, where the inherited ACL is what actually decides and a
+    `chmod` means almost nothing either way. Everywhere else a refusal means the key is
+    still readable by whoever could read it before, which is the one thing this function
+    exists to prevent, so it is reported rather than swallowed.
+    """
+    if os.name == "nt":
+        with contextlib.suppress(OSError):
+            path.chmod(mode)
+        return
+
+    try:
+        path.chmod(mode)
+    except OSError as error:
+        raise StorageError(f"{path} could not be made owner-only: {error}") from error
+
+
+def _text(bundle: dict[str, Any], key: str) -> str:
+    value = bundle.get(key)
+    if not isinstance(value, str) or not value:
+        raise ProtocolError(f"the bundle is missing {key}")
+
+    return value
+
+
+def _base64(value: str, key: str) -> bytes:
+    try:
+        return base64.b64decode(value, validate=True)
+    except ValueError as error:
+        raise ProtocolError(f"the bundle's {key} is not base64") from error

pykeepassgate/errors.py

@@ -0,0 +1,98 @@
+"""What this client raises, and nothing else.
+
+One base class, so a caller can catch everything this library does without also catching what the
+standard library does. The tree mirrors where a failure happened rather than what it felt like: the
+transport, the pairing exchange, or a request the gate refused. A caller deciding whether to retry,
+to wait, or to give up needs that distinction, and a single exception type would take it away.
+
+Nothing here carries a token, a key or a certificate. An exception is the value most likely to be
+logged, printed, and pasted into an issue.
+"""
+
+from __future__ import annotations
+
+
+class GateError(Exception):
+    """Anything this library refuses or cannot do."""
+
+
+class MalformedToken(GateError):
+    """The text handed over is not a pairing token."""
+
+
+class TransportError(GateError):
+    """The connection failed, or was closed before an answer arrived."""
+
+
+class ProtocolError(GateError):
+    """Something on this wire is not what the protocol allows.
+
+    Either direction: an answer this client cannot read, or a request it will not send.
+    """
+
+
+class StorageError(GateError):
+    """What is stored for a paired client could not be written, read or protected.
+
+    Separate from `ProtocolError`, which is about the wire. This is about the four files: one that
+    will not parse, a port that is not a number, a key the platform would not narrow. All of them
+    are ordinary states, reached by a partial write, a full disk or an edit by hand. Every one of
+    them would otherwise leave the standard library's own exception where a caller is promised
+    this hierarchy.
+    """
+
+
+class PairingError(GateError):
+    """The pairing exchange did not reach a certificate."""
+
+
+class ProofRefused(PairingError):
+    """A proof did not verify.
+
+    On the client's own proof this means the token is wrong. On the server's, it means whatever
+    answered is not the KeePass whose operator holds the token, and the exchange stops here: a
+    client with no anchor yet has nothing else to go on.
+    """
+
+
+class PairingRefused(PairingError):
+    """The operator said no, and the invitation is spent."""
+
+
+class PairingUnanswered(PairingError):
+    """Nobody answered the dialog. The invitation is not spent, so this can be tried again."""
+
+
+class GateBusy(GateError):
+    """The gate cannot serve this right now and the caller should try again.
+
+    A dialog open on the group or entry being written is the usual reason: the plugin
+    refuses a write that the dialog would take straight back off again when it is accepted.
+    """
+
+
+class DatabaseLocked(GateError):
+    """Every route answers this while the database is locked.
+
+    It names the lock and nothing else, deliberately: not which database, not whether the caller
+    would have been admitted. A client learns that it should wait, which is the only thing it can
+    act on.
+    """
+
+
+class NotAdmitted(GateError):
+    """The certificate is not one this database holds a record for.
+
+    Every connection is checked against the record, not against the certificate alone, so this is
+    also what a revoked client sees, immediately.
+    """
+
+
+class RouteRefused(GateError):
+    """The gate refused this request, with the status and the word it used."""
+
+    def __init__(self, status: int, error: str) -> None:
+        """Keep the status and the one-word reason the gate gave."""
+        super().__init__(f"the gate answered {status}: {error}")
+        self.status = status
+        self.error = error

pykeepassgate/model.py

@@ -0,0 +1,210 @@
+"""What the gate answers with, as objects rather than dictionaries.
+
+**Duck-typed after `pykeepass`, and honest about not being it.** A `PyKeePass` cannot be
+synthesized from this side of an API: that class is a decrypted `.kdbx`, and this client has
+neither the file nor the master password on purpose. The `spikes/pykeepass-compatibility` branch
+measures what that costs, member by member. What is offered instead is the
+shape a reader expects, so code written against `pykeepass` mostly moves across, under two rules
+decided before any of it was built.
+
+**No `save`.** A method that looks like `pykeepass`'s and does something else is worse than no
+method. Writes go through named calls on the client that say they are talking to a gate.
+
+**Absent rather than empty.** Where the gate does not serve something, the attribute does not exist,
+so `hasattr` is the compatibility test and a missing feature is never an empty list. An `Entry` from
+a listing therefore has no `password`: it was not withheld, it was never asked for, and a client
+that treats absence as emptiness would report a database of blank passwords.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+TITLE = "Title"
+USERNAME = "UserName"
+# The name of a field, not one.
+PASSWORD = "Password"  # noqa: S105
+URL = "URL"
+NOTES = "Notes"
+
+STANDARD = (TITLE, USERNAME, PASSWORD, URL, NOTES)
+
+
+def _optional(value: Any) -> str | None:
+    """A string the gate sent, or nothing when it withheld one."""
+    return None if value is None else str(value)
+
+
+def _moment(text: str | None) -> datetime | None:
+    """RFC 3339 as the gate writes it, or None when it said nothing or said it wrongly."""
+    if not text:
+        return None
+
+    try:
+        return datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=UTC)
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True)
+class Group:
+    """A group, as the gate describes one."""
+
+    uuid: str
+    name: str
+    parent: str | None
+    notes: str | None = None
+    created: datetime | None = None
+    modified: datetime | None = None
+
+    @property
+    def is_root(self) -> bool:
+        """The one group with nothing above it, which is how a client finds the top."""
+        return self.parent is None
+
+    @classmethod
+    def of(cls, body: dict[str, Any]) -> Group:
+        """Read one out of an answer."""
+        return cls(
+            uuid=str(body.get("uuid", "")),
+            name=str(body.get("name", "")),
+            parent=body.get("parent"),
+            notes=body.get("notes"),
+            created=_moment(body.get("created")),
+            modified=_moment(body.get("modified")),
+        )
+
+
+@dataclass(frozen=True)
+class Entry:
+    """An entry, with as much of it as the gate was asked for.
+
+    A listing fills in what a listing gives: the identifier, the group, the title, the URL and
+    the two times. Reading one
+    fills in `fields`, and only then do `username`, `password` and `notes` exist at all. Asking for
+    one that was never read raises `AttributeError`, which is the point: absence is not emptiness.
+    """
+
+    uuid: str
+    group: str
+    title: str | None
+    url: str | None
+    created: datetime | None = None
+    modified: datetime | None = None
+    fields: dict[str, str | None] | None = None
+    protected: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def username(self) -> str:
+        """The user name, when this entry has been read."""
+        return self._field(USERNAME)
+
+    @property
+    def password(self) -> str:
+        """The password, when this entry has been read."""
+        return self._field(PASSWORD)
+
+    @property
+    def notes(self) -> str:
+        """The notes, when this entry has been read."""
+        return self._field(NOTES)
+
+    @property
+    def is_read(self) -> bool:
+        """Whether this came from reading an entry rather than from listing one."""
+        return self.fields is not None
+
+    def custom(self) -> dict[str, str | None]:
+        """Everything that is not one of the five standard strings."""
+        if self.fields is None:
+            raise AttributeError("this entry was listed rather than read, so it holds no fields")
+
+        return {name: value for name, value in self.fields.items() if name not in STANDARD}
+
+    def _field(self, name: str) -> str:
+        if self.fields is None:
+            raise AttributeError(
+                f"this entry was listed rather than read, so it has no {name}. "
+                "Read it with GateClient.entry() first."
+            )
+
+        value = self.fields.get(name, "")
+        if value is None:
+            # Withheld rather than absent: the field is there and this client was not given
+            # `protected`. Raising keeps the promise the class docstring makes, and stops a
+            # stand-in value being mistaken for the real one.
+            raise AttributeError(
+                f"{name} is protected and this client may not read protected values. "
+                "Pair with a profile granting `P` to see it."
+            )
+
+        return value
+
+    @classmethod
+    def listed(cls, body: dict[str, Any]) -> Entry:
+        """One out of a listing, which carries no values."""
+        # A protected title or URL comes back as `null` when the rule lacks `P`, so neither is
+        # forced through `str`: the word "None" is not what the gate said.
+        return cls(
+            uuid=str(body.get("uuid", "")),
+            group=str(body.get("group", "")),
+            title=_optional(body.get("title")),
+            url=_optional(body.get("url")),
+            created=_moment(body.get("created")),
+            modified=_moment(body.get("modified")),
+        )
+
+    @classmethod
+    def read(cls, body: dict[str, Any]) -> Entry:
+        """One out of a read, which carries everything the entry holds."""
+        # `None` survives as `None`: the gate says `null` for a protected value this
+        # client may not read, and `str` would turn that into the word "None".
+        fields = {
+            str(k): (None if v is None else str(v))
+            for k, v in dict(body.get("fields", {})).items()
+        }
+
+        return cls(
+            uuid=str(body.get("uuid", "")),
+            group=str(body.get("group", "")),
+            title=fields.get(TITLE),
+            url=fields.get(URL),
+            created=_moment(body.get("created")),
+            modified=_moment(body.get("modified")),
+            fields=fields,
+            protected=tuple(str(name) for name in body.get("protected", [])),
+        )
+
+
+@dataclass(frozen=True)
+class Field:
+    """One of an entry's strings, named and possibly quoted."""
+
+    name: str
+    protected: bool
+    value: str | None = None
+
+    @property
+    def is_read(self) -> bool:
+        """Whether this came from reading the field rather than from listing the names.
+
+        A protected value the rule does not reach reads as withheld rather than as read: it arrives
+        as `None`, the same as a name that was only listed. `protected` is what tells those apart.
+        """
+        return self.value is not None
+
+
+@dataclass(frozen=True)
+class Attachment:
+    """One of an entry's attachments, named and sized, with its bytes when they were asked for."""
+
+    name: str
+    size: int
+    content: bytes | None = None
+
+    @property
+    def is_read(self) -> bool:
+        """Whether the bytes were fetched, as opposed to only the name and the size."""
+        return self.content is not None