pykeepassgate 0.0.1__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/.gitignore +38 -34
  2. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/LICENSE +21 -21
  3. pykeepassgate-0.2.0/PKG-INFO +244 -0
  4. pykeepassgate-0.2.0/pyproject.toml +211 -0
  5. pykeepassgate-0.2.0/src/pykeepassgate/README.md +231 -0
  6. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/src/pykeepassgate/__init__.py +101 -57
  7. pykeepassgate-0.2.0/src/pykeepassgate/api.py +259 -0
  8. pykeepassgate-0.2.0/src/pykeepassgate/cli.py +2550 -0
  9. pykeepassgate-0.2.0/src/pykeepassgate/client.py +1953 -0
  10. pykeepassgate-0.2.0/src/pykeepassgate/compatibility.py +83 -0
  11. pykeepassgate-0.2.0/src/pykeepassgate/credentials.py +992 -0
  12. pykeepassgate-0.2.0/src/pykeepassgate/errors.py +411 -0
  13. pykeepassgate-0.2.0/src/pykeepassgate/model.py +905 -0
  14. pykeepassgate-0.2.0/src/pykeepassgate/pairing.py +474 -0
  15. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/src/pykeepassgate/proofs.py +91 -89
  16. pykeepassgate-0.2.0/src/pykeepassgate/refs.py +680 -0
  17. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/src/pykeepassgate/sni.py +63 -63
  18. pykeepassgate-0.2.0/src/pykeepassgate/testing.py +888 -0
  19. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/src/pykeepassgate/token.py +62 -62
  20. pykeepassgate-0.2.0/src/pykeepassgate/transport.py +1554 -0
  21. pykeepassgate-0.0.1/PKG-INFO +0 -105
  22. pykeepassgate-0.0.1/pyproject.toml +0 -141
  23. pykeepassgate-0.0.1/src/pykeepassgate/README.md +0 -92
  24. pykeepassgate-0.0.1/src/pykeepassgate/api.py +0 -96
  25. pykeepassgate-0.0.1/src/pykeepassgate/cli.py +0 -377
  26. pykeepassgate-0.0.1/src/pykeepassgate/client.py +0 -416
  27. pykeepassgate-0.0.1/src/pykeepassgate/credentials.py +0 -323
  28. pykeepassgate-0.0.1/src/pykeepassgate/errors.py +0 -98
  29. pykeepassgate-0.0.1/src/pykeepassgate/model.py +0 -210
  30. pykeepassgate-0.0.1/src/pykeepassgate/pairing.py +0 -261
  31. pykeepassgate-0.0.1/src/pykeepassgate/transport.py +0 -374
  32. {pykeepassgate-0.0.1 → pykeepassgate-0.2.0}/src/pykeepassgate/py.typed +0 -0
@@ -1,34 +1,38 @@
1
- # Anchored with a leading slash, so that a rule meant for one place cannot quietly match another
2
- # somewhere else. What a project writes is ignored beside that project rather than from here.
3
- #
4
- # `__pycache__/` is the one exception and is deliberately recursive, because Python writes it
5
- # wherever a package happens to live.
6
-
7
- /.tmp/
8
-
9
- # What the gallery fixtures draw, for somebody to look at and nobody to keep. Rewritten on every
10
- # run and never published: `docs/images` is the set that is committed, because those are the ones a
11
- # reader of the documentation sees.
12
- /.gallery/
13
- /.vs/
14
-
15
- # What the coverage collector writes, one report per test assembly per run.
16
- /.cov/
17
-
18
- # The KeePass this repository pins, fetched by `tools/KeePass.ps1` and named after its
19
- # version. Provided rather than committed: it is somebody else's program.
20
- /.keepass/
21
-
22
- /node_modules/
23
- /scratchpad/
24
-
25
- # `uv` builds this from `uv.lock`, which is committed.
26
- /.venv/
27
- /.pytest_cache/
28
- /.mypy_cache/
29
- /.ruff_cache/
30
- /.coverage
31
- __pycache__/
32
-
33
- # Per machine, and not everybody's business: the checked-in `.claude/settings.json` is.
34
- /.claude/settings.local.json
1
+ # Anchored with a leading slash, so that a rule meant for one place cannot quietly match another
2
+ # somewhere else. What a project writes is ignored beside that project rather than from here.
3
+ #
4
+ # `__pycache__/` is the one exception and is deliberately recursive, because Python writes it
5
+ # wherever a package happens to live.
6
+
7
+ /.tmp/
8
+
9
+ # What the gallery fixtures draw, for somebody to look at and nobody to keep. Rewritten on every
10
+ # run and never published: `docs/images` is the set that is committed, because those are the ones a
11
+ # reader of the documentation sees.
12
+ /.gallery/
13
+ /.vs/
14
+
15
+ # What the coverage collector writes, one report per test assembly per run.
16
+ /.cov/
17
+
18
+ # What `build.ps1 -Task Package` makes: a zip a release would publish and the sums beside it.
19
+ # Published from here when there is a release, and never committed.
20
+ /dist/
21
+
22
+ # The KeePass this repository pins, fetched by `tools/KeePass.ps1` and named after its
23
+ # version. Provided rather than committed: it is somebody else's program.
24
+ /.keepass/
25
+
26
+ /node_modules/
27
+ /scratchpad/
28
+
29
+ # `uv` builds this from `uv.lock`, which is committed.
30
+ /.venv/
31
+ /.pytest_cache/
32
+ /.mypy_cache/
33
+ /.ruff_cache/
34
+ /.coverage
35
+ __pycache__/
36
+
37
+ # Per machine, and not everybody's business: the checked-in `.claude/settings.json` is.
38
+ /.claude/settings.local.json
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Martin Freund
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Martin Freund
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,244 @@
1
+ Metadata-Version: 2.5
2
+ Name: pykeepassgate
3
+ Version: 0.2.0
4
+ Summary: The reference client for KeePassGate: pairing, and everything the gate serves.
5
+ Project-URL: Homepage, https://github.com/mfrnd/KeePassGate
6
+ Author: KeePassGate contributors
7
+ License: MIT
8
+ License-File: LICENSE
9
+ Keywords: keepass,keepassgate,mtls,password-manager
10
+ Requires-Python: >=3.14
11
+ Requires-Dist: cryptography>=48.0.1
12
+ Description-Content-Type: text/markdown
13
+
14
+ # PyKeePassGate
15
+
16
+ <!-- One of Python's built-in functions, named the way Python names it. -->
17
+ <!-- cspell:ignore repr -->
18
+
19
+ The reference client for [KeePassGate](https://github.com/mfrnd/KeePassGate), a KeePass 2.x plugin
20
+ that serves a small specification-defined API over mutual TLS so that automation and AI agents can
21
+ each be given a narrow, revocable, audited slice of a database.
22
+
23
+ **Reference implementation** means the code here is the second copy of the specification. Where the
24
+ plugin and this disagree, one of them is wrong and a test should already have said so. It also means
25
+ what is missing is a statement: a route with no method here is a route the gate does not serve.
26
+
27
+ ## Install
28
+
29
+ ```shell
30
+ uv add pykeepassgate # as a dependency of the project this is run in
31
+ uv tool install pykeepassgate # or the command line on its own
32
+ ```
33
+
34
+ `pip install pykeepassgate` takes the same path. A client works with a plugin of its own major
35
+ version whose major and minor it does not lead, whatever the patch on either side, so `0.2` works
36
+ with `0.2` and `0.3` and not `0.1`, and it refuses any other before it sends anything else, as
37
+ [`API.md`](https://github.com/mfrnd/KeePassGate/blob/master/API.md) §411 has it. One dependency,
38
+ `cryptography`, because the gate
39
+ hands over a PKCS#12 and Python's `ssl` reads PEM. Everything else, the command line included, is
40
+ the standard library.
41
+
42
+ ## Pair
43
+
44
+ The operator presses **Invite** on the **KPG** tab of the database's settings dialog and sends
45
+ the invitation over a second channel. What they see while doing it is
46
+ [`docs/pairing.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pairing.md), and worked
47
+ examples of everything below are
48
+ [`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md).
49
+ It is spent by the first client to use it and it does not survive KeePass closing.
50
+
51
+ ```shell
52
+ pykeepassgate pair --name agent-invented --profile-name reader
53
+ ```
54
+
55
+ The gate listens on 51776 unless its operator chose another port, and `pair` dials that without
56
+ being told. A different one goes in `--port`, and the **Listening** row of the operator's
57
+ **Tools**, **KeePassGate (KPG)** window shows which it is.
58
+
59
+ Leave `--invitation` off and the token is read from standard input, so it stays out of the shell
60
+ history and out of the process list. At a terminal it is asked for, and each character typed or
61
+ pasted shows as a `*`.
62
+
63
+ The same thing from a program:
64
+
65
+ ```python
66
+ from pykeepassgate import api
67
+
68
+ credentials = api.pair(
69
+ invitation="...",
70
+ name="agent-invented",
71
+ profiles=["reader"],
72
+ )
73
+
74
+ print(credentials.profiles) # what the operator approved, not what was asked for
75
+ print(credentials.admission_key) # what the operator's audit file names this certificate by
76
+ print(credentials.client_key) # what the KPG tab knows this client by, kept through renewals
77
+ ```
78
+
79
+ `pair` prints the profiles and the admission key, and `identity` prints them again with the
80
+ client key, without connecting.
81
+
82
+ ## Use
83
+
84
+ ```python
85
+ from pykeepassgate import GateClient
86
+
87
+ client = GateClient.open()
88
+ print(client.status())
89
+ print(client.identity()) # who the gate admits this client as, and which profiles count now
90
+ ```
91
+
92
+ ```shell
93
+ pykeepassgate status
94
+ pykeepassgate identity # what is stored, without connecting
95
+ pykeepassgate whoami # what the gate admits this client as now
96
+ ```
97
+
98
+ **What a client may do at a node is something it can ask before trying.**
99
+ `client.entry_access(uuid)` and `client.group_access(uuid)` answer one mask per profile, in the
100
+ notation the operator's tab shows a rule in, and `.allows("RP")` asks whether one of those masks
101
+ reads the protected values there; `pykeepassgate access --entry <uuid>` prints them. A mask is
102
+ what the rules grant at the node rather than which operations would succeed there: removing the
103
+ node asks the group above it for `D` as well. A node where it may do nothing is refused as a node
104
+ that is not there.
105
+
106
+ An entry KeePass shows as expired is listed and read like any other, because an expiry is advice
107
+ rather than a control. `client.entries(include_expired=False)` leaves the expired ones out, a read
108
+ entry's `expires` says when it expires, and `client.update_entry(uuid, expires=False)` takes the
109
+ mark off a password that has just been rotated.
110
+
111
+ **A value comes back as the entry stores it**, a field reference such as `{REF:P@I:...}`
112
+ included, and `pykeepassgate.refs.resolve(client, entry, value)` gives what KeePass would give
113
+ for it instead: it follows a reference by identifier, reading the entry it names under this client's
114
+ rules, and the placeholders for the entry's own strings, and refuses with `Unresolved` what it
115
+ cannot answer as KeePass would, such as a search by title. `pykeepassgate show <uuid> --resolve`
116
+ prints an entry that way.
117
+
118
+ **A write can wait on the node still holding what was read.** A group, an entry, a field or an
119
+ attachment read on its own carries `etag`, and every write about one takes `if_match=`: the write
120
+ is refused with `PreconditionFailed`, and nothing changed, when somebody changed the node after it
121
+ was read, the operator in KeePass among them. An entry's tag covers everything in it that this
122
+ client may read, and a write answers with the tag it left, for the next write to name. The gate
123
+ hands a tag to every client holding `read`, so two clients that see different things of an entry
124
+ hold different tags for it, and a client writing a value it may not read is not told by its tag
125
+ that the value changed in between. It answers the `if_match` of a client without `read` with
126
+ `PreconditionFailed`.
127
+
128
+ **Nothing it hands back prints a value.** The `repr` of an entry, its fields, a field, an
129
+ attachment or a response names what it is and shows none of what it holds, so a log line or a
130
+ traceback carries no secret. A value is printed only by reading it.
131
+
132
+ **Every command takes `-o json`** for a program, such as `pykeepassgate entries -o json | jq`, and
133
+ `plain`, lines for a person, unless told otherwise. Both name a withheld value as withheld rather
134
+ than printing it empty, and a failure is a sentence on standard error and an exit code in either.
135
+
136
+ ## Renew a certificate, or give one up
137
+
138
+ ```shell
139
+ pykeepassgate renew --lifetime 30
140
+ pykeepassgate revoke
141
+ ```
142
+
143
+ `renew` asks the operator for a new certificate in place of the one this client holds, which they
144
+ approve on screen as they did the pairing, so it waits while they read: six minutes, as pairing
145
+ does, or longer when `--connection-timeout` says so. It stores the new identity where the old one
146
+ was, by writing it whole beside the old one first and then writing the four files over, leaving
147
+ anything else in the directory alone, and then gives the old certificate up by presenting it.
148
+ `--lifetime` is a proposal, and the new `expires` is what the operator picked. When giving the old
149
+ one up does not happen, the renewal has still worked: the old identity is kept beside the new one
150
+ in a directory ending `.retired`, `renew` says so and exits 1, and `revoke --directory` on that
151
+ directory gives it up. A later `renew` gives it up first itself, and forgets it once the gate takes
152
+ it back, already refuses it or it has expired.
153
+
154
+ `revoke` asks the gate to revoke the certificate this client presents and, once the gate says the
155
+ revocation is saved, removes what is stored for it. When the gate does not confirm it,
156
+ nothing is removed. A certificate the gate already refuses, revoked or expired, counts as given up,
157
+ and its files are removed as well. From a program, `client.renew()` and `client.revoke_certificate()` ask the
158
+ gate, and `api.forget(directory)` removes the files.
159
+
160
+ ## What to catch
161
+
162
+ Every exception says what to do next rather than what went wrong, because that is the part a caller
163
+ has to decide. Everything in the table but its last four rows derives from `GateError`, which
164
+ catches whatever this client raises of its own and nothing the standard library raises.
165
+
166
+ | Exception | What it means, and what to do |
167
+ | --- | --- |
168
+ | `DatabaseLocked` | The database is locked. Wait, and try again, or hand `retry_locked_timeout=` to the client and let it wait. Raised before anything is sent when the handshake was answered with the certificate only a locked database has, and as the gate's `503 locked` when the database is locked, or locks while a request is on its way, a read or a write alike: nothing was done. |
169
+ | `GateBusy` | The gate cannot serve this right now: a write under a dialog open on what it would change, under a message box, or while KeePass is busy with something of its own for longer than a write waits, or a read while KeePass could not be held still for it. The same, with `retry_busy_timeout=`. A pairing or a renewal meets it as well while the database's list of profiles will not read, which does not end until the operator repairs the list, and no budget outlasts that. |
170
+ | `AuthorityUndecided` | The database holds more than one certificate authority and the operator has not yet kept any of them, which KeePass asks about on its own screen. The same, with `retry_undecided_timeout=`, and pair again if the authority kept is not this client's. |
171
+ | `GateUnavailable` | The base of the three above, so catching it catches every `503`, and raised on its own for a `503` whose word this client does not know or that names none, with the word on `.error`. Nothing waits that one out. |
172
+ | `NotAdmitted` | The gate does not admit this certificate: it was never admitted, it was revoked, or it has expired, which is named as such, with the moment, before anything is dialed once this machine's clock is five minutes past it. To go on reaching the gate, pair again: a renewal needs a certificate that has not expired. To give the identity up, `revoke` removes what is stored for it. |
173
+ | `ProofRefused` | During pairing: the token is wrong, or whatever answered is not the KeePass whose operator holds it. Stop. |
174
+ | `PairingRefused` | The operator said no. The invitation is spent, so ask for another. |
175
+ | `PairingUnanswered` | Nobody answered the dialog. The invitation is **not** spent, so this can be tried again. |
176
+ | `PairingError` | The base of the three above, and raised on its own for the rest of what stops a pairing, with a message saying which. A name or a profile the gate would refuse, or more profiles than the 32 it takes, is caught before the request is sent: correct it and pair again. An invitation that is gone ran out or was spent: ask for another. An exchange the gate no longer holds leaves the invitation good: pair again with it. A pairing route the gate does not have is the two halves disagreeing about the wire. |
177
+ | `RenewalRefused` | The operator refused this renewal. On the dialog's own turn every refusal reads so, including one for this session, until a date or forever, which the next request is answered with at once, without the dialog. The certificate this client holds still works until it expires: ask again later, or pair again before then. |
178
+ | `RenewalRefusedThisSession` | The operator refused every renewal of this certificate until KeePass exits, and the gate keeps that answer in memory only. Ask again after KeePass has been restarted or once the operator has allowed renewal again on the KPG tab's clients page, or pair again before the certificate this client holds expires. |
179
+ | `RenewalTooEarly` | The operator refused renewing this certificate until `.not_before`, and asking before then is answered without anybody being asked. Ask again from then, or once the operator has allowed renewal again on the KPG tab's clients page. |
180
+ | `RenewalRefusedForever` | The operator refused every renewal of this certificate. Ask again once the operator has allowed renewal again on the KPG tab's clients page, or pair again, with an invitation from the operator, before the certificate this client holds expires. |
181
+ | `RenewalUnanswered` | Nobody answered the renewal dialog, and nothing changed. Ask again when somebody is at the screen. |
182
+ | `RenewalError` | The base of the five above, for a caller that only wants to know whether the operator let the renewal happen. Never raised on its own. |
183
+ | `PreconditionFailed` | The gate did not serve a request made with `if_match`, so nothing was read or changed: `412`. Most often the node no longer holds what the tag named: somebody changed it after the tag was taken, another client, the operator in KeePass, a merge or a plugin. Read it again, which hands back its tag as it is now, and decide again. Any `if_match` from a client the gate hands no tag to is answered the same; send none. An `if_match` the gate could not read, a tag without its quotes or a weak tag, is a `ProtocolError` before anything is sent. A `RouteRefused` with `status` `412`, so catching that catches this. |
184
+ | `RouteRefused` | Everything else the gate refuses, carrying the status and the reason it gave, usually one word: a `413` tells in a sentence that the request's body is over the 1 MiB the gate takes. A refused `head` carries the status alone, because its answer has no body to tell anything in, a `503` aside, whose word the gate names in a field as well. 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. |
185
+ | `Withheld` | A protected value this client may not read, from every way of reading one: the rule that lets it read or list the entry does not grant `P`, which the operator can add. Never `None` or an empty string in its place; `entry.withheld` and `field.withheld` name what is kept back without a `try`, so `{name: entry.fields[name] for name in entry.fields if name not in entry.withheld}` reads every value this client may read. |
186
+ | `Unresolved` | From `pykeepassgate.refs.resolve` alone: a value it will not give as KeePass would, such as a reference that searches by title or names an entry this client cannot read, a placeholder KeePass replaces and it does not, or a value that takes more work than it spends. The message names which. |
187
+ | `AmbiguousName` | A name only KeePass's own comparison can match: an entry's standard strings, `password` among them, when the entry holds the string under no name spelled exactly so beside a name beyond ASCII or with a null in it that KeePass may read as it, and a placeholder naming a field only in another case beyond ASCII. Never an empty string in its place. |
188
+ | `IncompatibleGate` | This client does not work with the gate's version: another major version, or a minor version this client is ahead of. Raised before anything else is sent, naming both versions, which are `.client` and `.gate` as well. Update whichever half is behind. |
189
+ | `MalformedToken` | The text handed over is not an invitation, so nothing was sent. Check what was pasted. |
190
+ | `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. An answer longer than the limit it was read under is refused this way too. For a read under `max_response_kilobytes` the message names the setting: raise it, for that read or for the client, rather than retry. An answer of a bounded shape, a pairing's or a write's among them, is read under a limit no setting raises, and its message names none: asking again reads the same answer. |
191
+ | `NotPaired` | Nothing is stored for a paired client where this looked: nothing has paired under that profile, its identity was given up, or the directory named is not the one the pairing used. Pair, or name the profile or the directory it used. A `StorageError`, so catching that catches this as well. |
192
+ | `StorageError` | From `pair`, before anything is sent: the directory cannot hold credentials, and the message says why. Nothing is spent, so fix that and pair again. Afterwards: what is stored for this client will not read, or could not be written, and the message names the file or the directory to look at. A key stored under a password is one of these when no password was given, or the one given does not open it. |
193
+ | `TransportError` | No whole answer arrived: nothing is listening, the socket a `dial` handed back could not be used, closed or never connected, the handshake failed, as below, or the connection broke or timed out once the request was on its way. After a read, send it again. After a write, the change may have landed, so look before sending it again: read or list what it changed, where the rules allow that, or ask the operator. |
194
+ | `ValueError` | A setting or an argument that could not work, refused where it is given and before anything is dialed, stored or spent: a port, a host, a timeout, a retry budget, a response limit, a lifetime, a profile's name, an expiry, a key password or a `dial`. The message names it. |
195
+ | `AttributeError` | Something this client never read: a listed entry's `username`, `password`, `notes`, `protected`, `expires` or `custom()`, a listed group's `notes`, a listed field's `value`, a listed attachment's `content`, a listed group's or entry's `etag`. Read it first. Also the `etag` of an answer the gate gave no tag for, because this client holds no `read` on the node, which the message names. Never raised for a withheld value. |
196
+ | `KeyError` | A name `entry.fields` or `entry.custom()` does not hold, as from any mapping. |
197
+ | `TypeError` | A `dial` that handed back something other than a connected stream socket, such as a datagram socket, which is a mistake in the program's own `dial`; what it handed back is closed first, if it can be. A socket it handed back already closed or never connected is a `TransportError`, whose message is that the socket could not be used rather than that a handshake failed. |
198
+
199
+ **The `503`s are the only refusals this client will wait out**, and only when a budget says so.
200
+ Each carries a `Retry-After` saying when to come back, and each of the three budgets, one per word,
201
+ says for how long to go on doing that. All three are off by default, so a refusal is raised exactly
202
+ where it happened, and a word none of them names is raised at once whatever they say. Nothing else
203
+ is retried, because waiting fixes none of it. `docs/` has the whole of it.
204
+
205
+ **A failed handshake says why.** `certificate has expired` is a database that has stayed locked
206
+ longer than ninety days, which unlocking it in KeePass mends.
207
+ [`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md)
208
+ gives the other reasons.
209
+
210
+ **A read's answer over 4096 kilobytes fails whole with `ProtocolError`** rather than arriving cut
211
+ short, and asking again reads the same answer to the same limit. The plugin serves a listing of
212
+ groups, of entries or of an entry's fields whole and an entry or an attachment at any size, so
213
+ an answer grows with the database, and a very large database or entry can need more, and so can
214
+ an attachment of 3 MiB or more, which arrives as base64, four thirds of its size:
215
+ `max_response_kilobytes=` on the read that needs it or on the client, or
216
+ `--max-response-kilobytes` on the command line, raises it, and the message names them. A
217
+ kilobyte is 1024 bytes. Pairing, a renewal, the status and the answer to a write have a bounded
218
+ shape and are read under a limit of their own, so no setting can stop them.
219
+
220
+ ## Test a program built on it
221
+
222
+ `pykeepassgate.testing` is a scripted TLS stand-in for the gate: a certificate authority, a host
223
+ certificate under it, and a TLS 1.3 server on loopback that answers one request per connection, as
224
+ the plugin does, with whatever the test tells it to answer. It is not a model of the rules, so a
225
+ program tested against it has been tested against its script, and it imports no test framework.
226
+ [`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md)
227
+ shows a client pointed at one.
228
+
229
+ ## What it does not do
230
+
231
+ **It does not open a `.kdbx`.** There is no file and no master password on this side of the API, by
232
+ design. What that means for anybody expecting a `pykeepass` object is measured on the
233
+ `spikes/pykeepass-compatibility` branch: 65 of the 122 public members of `PyKeePass`, `Entry`,
234
+ `Group` and `Attachment` are servable over the routes the gate already has, 24 of the 56 on
235
+ `PyKeePass` itself, and the object itself is not one of them.
236
+
237
+ **It defends nothing against local code execution as the user.** The client's key is on the disk,
238
+ because a client has to still be the same client tomorrow. The whole design concedes this
239
+ throughout, and so does this. The key can be stored under a password, with `pair --key-password`,
240
+ which asks at a terminal and takes the password no other way, or with `key_password=` from a
241
+ program, and that protects copies of the directory, such as backups and disk images, and nothing
242
+ against a process running as the user. How well it protects a copy is the password's to decide:
243
+ the key is encrypted with PBKDF2 at OpenSSL's default of 2048 iterations, which is little work per
244
+ guess, so a program should pass a long random one.
@@ -0,0 +1,211 @@
1
+ [project]
2
+ name = "pykeepassgate"
3
+ dynamic = ["version"]
4
+ description = "The reference client for KeePassGate: pairing, and everything the gate serves."
5
+ readme = "src/pykeepassgate/README.md"
6
+ requires-python = ">=3.14"
7
+ license = { text = "MIT" }
8
+ authors = [{ name = "KeePassGate contributors" }]
9
+ keywords = ["keepass", "keepassgate", "mtls", "password-manager"]
10
+
11
+ # One dependency, and it is the one that cannot be written here. `cryptography` parses the PKCS#12
12
+ # the gate hands over and writes the PEM that `ssl` can load; the standard library reads neither.
13
+ # Everything else, including the command line, is the standard library on purpose: this is the
14
+ # reference implementation, so what it needs is what the protocol needs.
15
+ #
16
+ # The floor is a crash rather than a feature: the wheel's own OpenSSL is what parses the bundle,
17
+ # and in 42.0.0 and 42.0.1 a malformed PKCS#12 segfaults the interpreter where `credentials.py`
18
+ # promises a `ProtocolError`. 48.0.1 is the newest release to fix its bundled OpenSSL, and this
19
+ # client reads a PKCS#12 from a peer on every pairing, so it takes that one.
20
+ dependencies = ["cryptography>=48.0.1"]
21
+
22
+ [project.scripts]
23
+ pykeepassgate = "pykeepassgate.cli:main"
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/mfrnd/KeePassGate"
27
+
28
+ # No version here, because this is what builds the client wherever its source distribution is
29
+ # built, and a pin here would hold everybody who builds it to that version. What this repository
30
+ # builds it with is the `build` group below.
31
+ [build-system]
32
+ requires = ["hatchling"]
33
+ build-backend = "hatchling.build"
34
+
35
+ # The version is not written here. It is `Version` in `Directory.Build.props`, the one place the
36
+ # plugin, this client and the routing document take it from, and hatchling reads it from there.
37
+ # The source distribution carries none of the C# build, and needs none of it: the wheel built from
38
+ # it takes the version from the sdist's own `PKG-INFO`, which is how hatchling builds from one.
39
+ [tool.hatch.version]
40
+ path = "Directory.Build.props"
41
+ pattern = "<Version>(?P<version>[^<]+)</Version>"
42
+
43
+ # **And uv is told to watch it.** uv builds the project again only when a key below changes, and
44
+ # left to itself it watches this file and whether `src` exists, which is its own list less the
45
+ # `setup.py` and `setup.cfg` this project has neither of. Without `Directory.Build.props` here an
46
+ # environment made before the number moved keeps the old version in its metadata, which is where
47
+ # the client reads its own, and the version test fails locally after a correct bump, and nowhere
48
+ # else. Measured: with it, moving the version reinstalls the client on the next `uv sync`.
49
+ [tool.uv]
50
+ cache-keys = [{ file = "pyproject.toml" }, { dir = "src" }, { file = "Directory.Build.props" }]
51
+
52
+ [tool.hatch.build.targets.wheel]
53
+ packages = ["src/pykeepassgate"]
54
+
55
+ # The sdist default is everything the version control does not ignore, which here is the whole
56
+ # repository: the plugin's C#, its tests, and every design document, inside a package whose whole
57
+ # claim is that it is one dependency and the standard library. Naming the same directory is what
58
+ # stops that.
59
+ #
60
+ # `only-include` rather than `packages`, and the difference is the whole sdist. `packages` rewrites
61
+ # the paths as it copies, so `src/pykeepassgate` arrives as `pykeepassgate` while the project file
62
+ # beside it still says `readme = "src/pykeepassgate/README.md"` and builds its wheel from
63
+ # `src/pykeepassgate`: the sdist cannot be built into a wheel, which is what `uv build` does with
64
+ # it. `only-include` keeps the layout and excludes everything else just as narrowly.
65
+ [tool.hatch.build.targets.sdist]
66
+ only-include = ["src/pykeepassgate", "LICENSE"]
67
+
68
+ [dependency-groups]
69
+ dev = [
70
+ "mypy>=1.11",
71
+ "pre-commit>=4",
72
+ # Only the test that holds this client to the plugin's routing table reads it, and the plugin
73
+ # writes that table in YAML because its OpenAPI reader ships a YAML parser either way.
74
+ "pyyaml>=6",
75
+ "types-pyyaml>=6",
76
+ "pytest>=8",
77
+ "pytest-cov>=5",
78
+ "ruff>=0.6",
79
+ # Only the release workflow runs it, to check that what it built is a distribution PyPI will
80
+ # take, on a pull request as well, where nothing is uploaded and nothing else would look.
81
+ "twine>=6",
82
+ # Only `tools/suppressions.py` reads them: a grammar of each language CodeQL takes suppressions
83
+ # in, so that a comment is found where the language has one and never inside a string. Chosen
84
+ # over Roslyn and `tokenize` once both were built and found the same comments in every file.
85
+ "tree-sitter>=0.26",
86
+ "tree-sitter-c-sharp>=0.23.5",
87
+ "tree-sitter-python>=0.25",
88
+ ]
89
+ # What the client is built with, so that a release is built with what the gate built with rather
90
+ # than with whatever was newest that day. Locked and never installed, since `uv sync` installs the
91
+ # `dev` group alone. `build.ps1` and `release.yml` hold `uv build` to the hatchling locked here,
92
+ # exported with its hashes, and every workflow's setup-uv installs the uv locked here through
93
+ # `version-file: uv.lock`, while a machine of somebody's own keeps the uv it has. Each setup-uv
94
+ # has to name the lock, because without it setup-uv finds the floor below and takes the newest
95
+ # release above it. Dependabot moves both with the rest of the lock, a week after a release, and
96
+ # the floors are where the pins started.
97
+ build = [
98
+ "hatchling>=1.33",
99
+ "uv>=0.13.6",
100
+ ]
101
+
102
+ # ---------------------------------------------------------------------------------------------
103
+ # The checks. One config for one repository, at the root, beside the two that check the prose.
104
+ # ---------------------------------------------------------------------------------------------
105
+
106
+ [tool.ruff]
107
+ line-length = 100
108
+ target-version = "py314"
109
+ src = ["src", "tests/pykeepassgate", "tools", "tests/tools"]
110
+
111
+ [tool.ruff.lint]
112
+ # The default set plus what catches real mistakes in a client that talks to a password manager:
113
+ # bugbear for the traps, security for the ones that matter here, and the import and comprehension
114
+ # rules because they are free.
115
+ select = [
116
+ "E", "W", # pycodestyle
117
+ "E301", "E302", "E303", "E304", "E305", "E306", # its blank lines, see `preview` below
118
+ "F", # pyflakes
119
+ "I", # import order
120
+ "B", # bugbear
121
+ "C4", # comprehensions
122
+ "UP", # pyupgrade
123
+ "S", # bandit
124
+ "RUF", # ruff's own
125
+ "SIM", # simplify
126
+ "PTH", # pathlib over os.path
127
+ "RET", # returns
128
+ "ARG", # unused arguments
129
+ "N", # naming
130
+ "D", # docstrings
131
+ ]
132
+
133
+ # pycodestyle's blank-line rules are preview rules in this ruff, so selecting `E` does not turn
134
+ # them on and a missing blank line would pass. `explicit-preview-rules` keeps every other preview
135
+ # rule out: one runs only when it is selected by its full code.
136
+ #
137
+ # **What it does not keep out is preview behavior.** `preview` also changes how some stable rules
138
+ # check, and many of the rules selected here document checking more with it, how many moving with
139
+ # each ruff `uv.lock` takes: the bandit rules on insecure calls flag a reference as well as a call,
140
+ # F401 and F811 look further, RUF001 to RUF003 know more ambiguous characters. None of it finds
141
+ # anything in this code, which passes with `--no-preview` as well. But preview behavior is what a
142
+ # ruff release may change with no rule added or selected, so a finding that arrives with an upgrade
143
+ # may come from here, and `--no-preview` is how to tell.
144
+ preview = true
145
+ explicit-preview-rules = true
146
+
147
+ ignore = [
148
+ # A one-line summary is required; the blank line after it and the mood of the first word are
149
+ # not, because this project's comments are sentences rather than a docstring format.
150
+ "D203", "D212", "D401", "D407", "D413",
151
+
152
+ # N818: an exception class should be named `...Error`. Every one of these derives from
153
+ # `GateError`, which is, and the names are chosen to read at the place they are caught:
154
+ # `except DatabaseLocked` says what to do about it and `except DatabaseLockedError` does not.
155
+ # The guideline exists so a reader can tell an exception from a value type, and nothing in
156
+ # `errors.py` is a value. This is the same call, for the same reason, that `CA1710` gets on the
157
+ # plugin's side of the protocol.
158
+ "N818",
159
+ ]
160
+
161
+ [tool.ruff.lint.per-file-ignores]
162
+ # A test says what it does in its name, and it asserts, which `S101` is about. A fake gate is
163
+ # handed every argument whether it reads them or not, which is `ARG`. And a test vector that looks
164
+ # like a credential is an input written down beside its expected output, which is `S105` and its
165
+ # siblings: the whole point of `test_protocol.py` is that these values are public and reproducible.
166
+ "tests/**/*.py" = [
167
+ "S101", "S105", "S106", "S107",
168
+ "D100", "D101", "D102", "D103", "D104", "D107",
169
+ "ARG001", "ARG002", "ARG005",
170
+ ]
171
+
172
+ [tool.ruff.lint.isort]
173
+ # `conftest` is imported by name because the test directory is not a package: making it one would
174
+ # shadow the package under test, which is called the same thing.
175
+ known-first-party = ["pykeepassgate", "conftest"]
176
+
177
+ [tool.ruff.lint.pydocstyle]
178
+ convention = "pep257"
179
+
180
+ [tool.mypy]
181
+ python_version = "3.14"
182
+ files = ["src/pykeepassgate", "tests/pykeepassgate", "tools", "tests/tools"]
183
+ mypy_path = "tools"
184
+ strict = true
185
+ # A reference implementation says what it means. These three turn "it type checks" into "it says
186
+ # what it is": no silent `Any` crossing a boundary, no untyped call slipping through, and a warning
187
+ # when an annotation turns out to be unnecessary.
188
+ warn_unreachable = true
189
+ warn_return_any = true
190
+ warn_unused_ignores = true
191
+
192
+
193
+ [tool.pytest.ini_options]
194
+ testpaths = ["tests/pykeepassgate", "tests/tools"]
195
+ # The tools are scripts rather than a package, so their tests import them from where they are.
196
+ pythonpath = ["tools"]
197
+ addopts = "--strict-markers --strict-config"
198
+
199
+ [tool.coverage.run]
200
+ source = ["src/pykeepassgate", "tools"]
201
+ branch = true
202
+
203
+ [tool.coverage.report]
204
+ # The client is the reference implementation, so an untested path in it is a paragraph of the
205
+ # specification nobody has run.
206
+ fail_under = 90
207
+ show_missing = true
208
+ exclude_also = [
209
+ "if TYPE_CHECKING:",
210
+ "raise NotImplementedError",
211
+ ]