pykeepassgate 0.1.0__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 (21) hide show
  1. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/PKG-INFO +45 -30
  2. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/pyproject.toml +43 -10
  3. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/README.md +44 -29
  4. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/__init__.py +8 -6
  5. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/api.py +19 -13
  6. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/cli.py +848 -181
  7. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/client.py +772 -140
  8. pykeepassgate-0.2.0/src/pykeepassgate/compatibility.py +83 -0
  9. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/credentials.py +226 -38
  10. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/errors.py +96 -27
  11. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/model.py +154 -55
  12. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/pairing.py +39 -18
  13. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/refs.py +253 -63
  14. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/sni.py +1 -1
  15. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/testing.py +420 -62
  16. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/transport.py +682 -120
  17. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/.gitignore +0 -0
  18. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/LICENSE +0 -0
  19. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/proofs.py +0 -0
  20. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/py.typed +0 -0
  21. {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/token.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pykeepassgate
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: The reference client for KeePassGate: pairing, and everything the gate serves.
5
5
  Project-URL: Homepage, https://github.com/mfrnd/KeePassGate
6
6
  Author: KeePassGate contributors
@@ -31,8 +31,11 @@ uv add pykeepassgate # as a dependency of the project this is run i
31
31
  uv tool install pykeepassgate # or the command line on its own
32
32
  ```
33
33
 
34
- `pip install pykeepassgate` takes the same path. A client works with a plugin of the same major
35
- and minor version, as `0.1`, whatever the patch on either side. One dependency, `cryptography`, because the gate
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
36
39
  hands over a PKCS#12 and Python's `ssl` reads PEM. Everything else, the command line included, is
37
40
  the standard library.
38
41
 
@@ -93,10 +96,12 @@ pykeepassgate whoami # what the gate admits this client as now
93
96
  ```
94
97
 
95
98
  **What a client may do at a node is something it can ask before trying.**
96
- `client.entry_access(uuid)` and `client.group_access(uuid)` answer one mask per profile, as the
97
- operator's tab shows a rule, and `.allows("RP")` asks whether one of those rules reads the
98
- protected values there; `pykeepassgate access --entry <uuid>` prints them. A node where it may do
99
- nothing is refused as one that is not there.
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.
100
105
 
101
106
  An entry KeePass shows as expired is listed and read like any other, because an expiry is advice
102
107
  rather than a control. `client.entries(include_expired=False)` leaves the expired ones out, a read
@@ -113,9 +118,11 @@ prints an entry that way.
113
118
  **A write can wait on the node still holding what was read.** A group, an entry, a field or an
114
119
  attachment read on its own carries `etag`, and every write about one takes `if_match=`: the write
115
120
  is refused with `PreconditionFailed`, and nothing changed, when somebody changed the node after it
116
- was read, the operator in KeePass among them. An entry's tag covers everything in it, and a write
117
- answers with the tag it left, for the next write to name. The gate hands tags only to a client
118
- whose rule reads everything a tag covers, and answers any other client's `if_match` with
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
119
126
  `PreconditionFailed`.
120
127
 
121
128
  **Nothing it hands back prints a value.** The `repr` of an entry, its fields, a field, an
@@ -158,9 +165,9 @@ catches whatever this client raises of its own and nothing the standard library
158
165
 
159
166
  | Exception | What it means, and what to do |
160
167
  | --- | --- |
161
- | `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: nothing was done, apart from a write whose handler had already run, which is `500 internal error`. |
162
- | `GateBusy` | The gate cannot serve this right now: a write under a dialog open on what it would change, or while KeePass is busy with something of its own, or a read while the database kept changing under it. The same, with `retry_busy_timeout=`. |
163
- | `AuthorityUndecided` | The database holds two certificate authorities and the operator has not kept one, which KeePass asks about on its own screen. The same, with `retry_undecided_timeout=`, and pair again if the one kept is not this client's. |
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. |
164
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. |
165
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. |
166
173
  | `ProofRefused` | During pairing: the token is wrong, or whatever answered is not the KeePass whose operator holds it. Stop. |
@@ -168,24 +175,26 @@ catches whatever this client raises of its own and nothing the standard library
168
175
  | `PairingUnanswered` | Nobody answered the dialog. The invitation is **not** spent, so this can be tried again. |
169
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. |
170
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. |
171
- | `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 pair again before the one this client holds expires. |
172
- | `RenewalTooEarly` | The operator refused renewing this certificate until `.not_before`, and asking before then is answered without anybody being asked. Ask again from then. |
173
- | `RenewalRefusedForever` | The operator refused every renewal of this certificate. Pair again, with an invitation from the operator, before the one this client holds expires. |
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. |
174
181
  | `RenewalUnanswered` | Nobody answered the renewal dialog, and nothing changed. Ask again when somebody is at the screen. |
175
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. |
176
- | `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. An `if_match` the gate cannot read, or any from a client the gate hands no tag to, is answered the same; send none. A `RouteRefused` with `status` `412`, so catching that catches this. |
177
- | `RouteRefused` | Everything else the gate refuses, carrying the status and the reason it gave, usually one word: a `413` says in a sentence what was too large. A refused `head` carries the status alone, because its answer has no body to say anything in. 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. |
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. |
178
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. |
179
- | `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, or a placeholder KeePass replaces and it does not. The message says which. |
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. |
180
189
  | `MalformedToken` | The text handed over is not an invitation, so nothing was sent. Check what was pasted. |
181
- | `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 `max_response_bytes` is refused this way too, and the message says so: raise the setting rather than retry. |
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. |
182
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. |
183
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. |
184
- | `TransportError` | No whole answer arrived: nothing is listening, 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. |
185
- | `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 timeout, a retry budget, a response cap, a lifetime, a profile's name, an expiry, a key password or a `dial`. The message names it. |
186
- | `AttributeError` | Something this client never read: a listed entry's `username`, `password`, `notes`, `expires` or `custom()`, a listed group's `notes`, a listed field's `value`, a listed group's or entry's `etag`. Read it first. Also the `etag` of a read the gate gave no tag for, because this client's rule does not read everything a tag covers, which the message says. Never raised for a withheld value. |
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. |
187
196
  | `KeyError` | A name `entry.fields` or `entry.custom()` does not hold, as from any mapping. |
188
- | `TypeError` | A `dial` that handed back something other than a connected socket. |
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. |
189
198
 
190
199
  **The `503`s are the only refusals this client will wait out**, and only when a budget says so.
191
200
  Each carries a `Retry-After` saying when to come back, and each of the three budgets, one per word,
@@ -198,10 +207,15 @@ longer than ninety days, which unlocking it in KeePass mends.
198
207
  [`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md)
199
208
  gives the other reasons.
200
209
 
201
- **An answer over 4 MiB fails whole with `ProtocolError`** rather than arriving cut short, and
202
- asking again reads the same answer to the same cap. The plugin does not page, so a listing grows
203
- with the database, and a very large one can need more: `max_response_bytes=` on the client, or
204
- `--max-response-bytes` on the command line, raises it, and the message names both.
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.
205
219
 
206
220
  ## Test a program built on it
207
221
 
@@ -216,8 +230,9 @@ shows a client pointed at one.
216
230
 
217
231
  **It does not open a `.kdbx`.** There is no file and no master password on this side of the API, by
218
232
  design. What that means for anybody expecting a `pykeepass` object is measured on the
219
- `spikes/pykeepass-compatibility` branch: 23 of its 56 public members are servable over the routes the
220
- gate already has, and the object itself is not one of them.
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.
221
236
 
222
237
  **It defends nothing against local code execution as the user.** The client's key is on the disk,
223
238
  because a client has to still be the same client tomorrow. The whole design concedes this
@@ -25,6 +25,9 @@ pykeepassgate = "pykeepassgate.cli:main"
25
25
  [project.urls]
26
26
  Homepage = "https://github.com/mfrnd/KeePassGate"
27
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.
28
31
  [build-system]
29
32
  requires = ["hatchling"]
30
33
  build-backend = "hatchling.build"
@@ -37,6 +40,15 @@ build-backend = "hatchling.build"
37
40
  path = "Directory.Build.props"
38
41
  pattern = "<Version>(?P<version>[^<]+)</Version>"
39
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
+
40
52
  [tool.hatch.build.targets.wheel]
41
53
  packages = ["src/pykeepassgate"]
42
54
 
@@ -67,6 +79,24 @@ dev = [
67
79
  # Only the release workflow runs it, to check that what it built is a distribution PyPI will
68
80
  # take, on a pull request as well, where nothing is uploaded and nothing else would look.
69
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",
70
100
  ]
71
101
 
72
102
  # ---------------------------------------------------------------------------------------------
@@ -76,7 +106,7 @@ dev = [
76
106
  [tool.ruff]
77
107
  line-length = 100
78
108
  target-version = "py314"
79
- src = ["src", "tests/pykeepassgate"]
109
+ src = ["src", "tests/pykeepassgate", "tools", "tests/tools"]
80
110
 
81
111
  [tool.ruff.lint]
82
112
  # The default set plus what catches real mistakes in a client that talks to a password manager:
@@ -105,12 +135,12 @@ select = [
105
135
  # rule out: one runs only when it is selected by its full code.
106
136
  #
107
137
  # **What it does not keep out is preview behavior.** `preview` also changes how some stable rules
108
- # check, and under the ruff `uv.lock` pins, 0.16.3, 37 of the rules selected here say they check
109
- # more with it: the bandit rules on insecure calls flag a reference as well as a call, F401 and F811
110
- # look further, RUF001 to RUF003 know more ambiguous characters. None of it finds anything in this
111
- # code, which passes with `--no-preview` as well. But preview behavior is what a ruff release may
112
- # change with no rule added or selected, so a finding that arrives with an upgrade may come from
113
- # here, and `--no-preview` is how to tell.
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.
114
144
  preview = true
115
145
  explicit-preview-rules = true
116
146
 
@@ -149,7 +179,8 @@ convention = "pep257"
149
179
 
150
180
  [tool.mypy]
151
181
  python_version = "3.14"
152
- files = ["src/pykeepassgate", "tests/pykeepassgate"]
182
+ files = ["src/pykeepassgate", "tests/pykeepassgate", "tools", "tests/tools"]
183
+ mypy_path = "tools"
153
184
  strict = true
154
185
  # A reference implementation says what it means. These three turn "it type checks" into "it says
155
186
  # what it is": no silent `Any` crossing a boundary, no untyped call slipping through, and a warning
@@ -160,11 +191,13 @@ warn_unused_ignores = true
160
191
 
161
192
 
162
193
  [tool.pytest.ini_options]
163
- testpaths = ["tests/pykeepassgate"]
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"]
164
197
  addopts = "--strict-markers --strict-config"
165
198
 
166
199
  [tool.coverage.run]
167
- source = ["src/pykeepassgate"]
200
+ source = ["src/pykeepassgate", "tools"]
168
201
  branch = true
169
202
 
170
203
  [tool.coverage.report]
@@ -18,8 +18,11 @@ uv add pykeepassgate # as a dependency of the project this is run i
18
18
  uv tool install pykeepassgate # or the command line on its own
19
19
  ```
20
20
 
21
- `pip install pykeepassgate` takes the same path. A client works with a plugin of the same major
22
- and minor version, as `0.1`, whatever the patch on either side. One dependency, `cryptography`, because the gate
21
+ `pip install pykeepassgate` takes the same path. A client works with a plugin of its own major
22
+ version whose major and minor it does not lead, whatever the patch on either side, so `0.2` works
23
+ with `0.2` and `0.3` and not `0.1`, and it refuses any other before it sends anything else, as
24
+ [`API.md`](https://github.com/mfrnd/KeePassGate/blob/master/API.md) §411 has it. One dependency,
25
+ `cryptography`, because the gate
23
26
  hands over a PKCS#12 and Python's `ssl` reads PEM. Everything else, the command line included, is
24
27
  the standard library.
25
28
 
@@ -80,10 +83,12 @@ pykeepassgate whoami # what the gate admits this client as now
80
83
  ```
81
84
 
82
85
  **What a client may do at a node is something it can ask before trying.**
83
- `client.entry_access(uuid)` and `client.group_access(uuid)` answer one mask per profile, as the
84
- operator's tab shows a rule, and `.allows("RP")` asks whether one of those rules reads the
85
- protected values there; `pykeepassgate access --entry <uuid>` prints them. A node where it may do
86
- nothing is refused as one that is not there.
86
+ `client.entry_access(uuid)` and `client.group_access(uuid)` answer one mask per profile, in the
87
+ notation the operator's tab shows a rule in, and `.allows("RP")` asks whether one of those masks
88
+ reads the protected values there; `pykeepassgate access --entry <uuid>` prints them. A mask is
89
+ what the rules grant at the node rather than which operations would succeed there: removing the
90
+ node asks the group above it for `D` as well. A node where it may do nothing is refused as a node
91
+ that is not there.
87
92
 
88
93
  An entry KeePass shows as expired is listed and read like any other, because an expiry is advice
89
94
  rather than a control. `client.entries(include_expired=False)` leaves the expired ones out, a read
@@ -100,9 +105,11 @@ prints an entry that way.
100
105
  **A write can wait on the node still holding what was read.** A group, an entry, a field or an
101
106
  attachment read on its own carries `etag`, and every write about one takes `if_match=`: the write
102
107
  is refused with `PreconditionFailed`, and nothing changed, when somebody changed the node after it
103
- was read, the operator in KeePass among them. An entry's tag covers everything in it, and a write
104
- answers with the tag it left, for the next write to name. The gate hands tags only to a client
105
- whose rule reads everything a tag covers, and answers any other client's `if_match` with
108
+ was read, the operator in KeePass among them. An entry's tag covers everything in it that this
109
+ client may read, and a write answers with the tag it left, for the next write to name. The gate
110
+ hands a tag to every client holding `read`, so two clients that see different things of an entry
111
+ hold different tags for it, and a client writing a value it may not read is not told by its tag
112
+ that the value changed in between. It answers the `if_match` of a client without `read` with
106
113
  `PreconditionFailed`.
107
114
 
108
115
  **Nothing it hands back prints a value.** The `repr` of an entry, its fields, a field, an
@@ -145,9 +152,9 @@ catches whatever this client raises of its own and nothing the standard library
145
152
 
146
153
  | Exception | What it means, and what to do |
147
154
  | --- | --- |
148
- | `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: nothing was done, apart from a write whose handler had already run, which is `500 internal error`. |
149
- | `GateBusy` | The gate cannot serve this right now: a write under a dialog open on what it would change, or while KeePass is busy with something of its own, or a read while the database kept changing under it. The same, with `retry_busy_timeout=`. |
150
- | `AuthorityUndecided` | The database holds two certificate authorities and the operator has not kept one, which KeePass asks about on its own screen. The same, with `retry_undecided_timeout=`, and pair again if the one kept is not this client's. |
155
+ | `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. |
156
+ | `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. |
157
+ | `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. |
151
158
  | `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. |
152
159
  | `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. |
153
160
  | `ProofRefused` | During pairing: the token is wrong, or whatever answered is not the KeePass whose operator holds it. Stop. |
@@ -155,24 +162,26 @@ catches whatever this client raises of its own and nothing the standard library
155
162
  | `PairingUnanswered` | Nobody answered the dialog. The invitation is **not** spent, so this can be tried again. |
156
163
  | `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. |
157
164
  | `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. |
158
- | `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 pair again before the one this client holds expires. |
159
- | `RenewalTooEarly` | The operator refused renewing this certificate until `.not_before`, and asking before then is answered without anybody being asked. Ask again from then. |
160
- | `RenewalRefusedForever` | The operator refused every renewal of this certificate. Pair again, with an invitation from the operator, before the one this client holds expires. |
165
+ | `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. |
166
+ | `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. |
167
+ | `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. |
161
168
  | `RenewalUnanswered` | Nobody answered the renewal dialog, and nothing changed. Ask again when somebody is at the screen. |
162
169
  | `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. |
163
- | `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. An `if_match` the gate cannot read, or any from a client the gate hands no tag to, is answered the same; send none. A `RouteRefused` with `status` `412`, so catching that catches this. |
164
- | `RouteRefused` | Everything else the gate refuses, carrying the status and the reason it gave, usually one word: a `413` says in a sentence what was too large. A refused `head` carries the status alone, because its answer has no body to say anything in. 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. |
170
+ | `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. |
171
+ | `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. |
165
172
  | `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. |
166
- | `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, or a placeholder KeePass replaces and it does not. The message says which. |
173
+ | `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. |
174
+ | `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. |
175
+ | `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. |
167
176
  | `MalformedToken` | The text handed over is not an invitation, so nothing was sent. Check what was pasted. |
168
- | `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 `max_response_bytes` is refused this way too, and the message says so: raise the setting rather than retry. |
177
+ | `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. |
169
178
  | `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. |
170
179
  | `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. |
171
- | `TransportError` | No whole answer arrived: nothing is listening, 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. |
172
- | `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 timeout, a retry budget, a response cap, a lifetime, a profile's name, an expiry, a key password or a `dial`. The message names it. |
173
- | `AttributeError` | Something this client never read: a listed entry's `username`, `password`, `notes`, `expires` or `custom()`, a listed group's `notes`, a listed field's `value`, a listed group's or entry's `etag`. Read it first. Also the `etag` of a read the gate gave no tag for, because this client's rule does not read everything a tag covers, which the message says. Never raised for a withheld value. |
180
+ | `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. |
181
+ | `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. |
182
+ | `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. |
174
183
  | `KeyError` | A name `entry.fields` or `entry.custom()` does not hold, as from any mapping. |
175
- | `TypeError` | A `dial` that handed back something other than a connected socket. |
184
+ | `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. |
176
185
 
177
186
  **The `503`s are the only refusals this client will wait out**, and only when a budget says so.
178
187
  Each carries a `Retry-After` saying when to come back, and each of the three budgets, one per word,
@@ -185,10 +194,15 @@ longer than ninety days, which unlocking it in KeePass mends.
185
194
  [`docs/pykeepassgate.md`](https://github.com/mfrnd/KeePassGate/blob/master/docs/pykeepassgate.md)
186
195
  gives the other reasons.
187
196
 
188
- **An answer over 4 MiB fails whole with `ProtocolError`** rather than arriving cut short, and
189
- asking again reads the same answer to the same cap. The plugin does not page, so a listing grows
190
- with the database, and a very large one can need more: `max_response_bytes=` on the client, or
191
- `--max-response-bytes` on the command line, raises it, and the message names both.
197
+ **A read's answer over 4096 kilobytes fails whole with `ProtocolError`** rather than arriving cut
198
+ short, and asking again reads the same answer to the same limit. The plugin serves a listing of
199
+ groups, of entries or of an entry's fields whole and an entry or an attachment at any size, so
200
+ an answer grows with the database, and a very large database or entry can need more, and so can
201
+ an attachment of 3 MiB or more, which arrives as base64, four thirds of its size:
202
+ `max_response_kilobytes=` on the read that needs it or on the client, or
203
+ `--max-response-kilobytes` on the command line, raises it, and the message names them. A
204
+ kilobyte is 1024 bytes. Pairing, a renewal, the status and the answer to a write have a bounded
205
+ shape and are read under a limit of their own, so no setting can stop them.
192
206
 
193
207
  ## Test a program built on it
194
208
 
@@ -203,8 +217,9 @@ shows a client pointed at one.
203
217
 
204
218
  **It does not open a `.kdbx`.** There is no file and no master password on this side of the API, by
205
219
  design. What that means for anybody expecting a `pykeepass` object is measured on the
206
- `spikes/pykeepass-compatibility` branch: 23 of its 56 public members are servable over the routes the
207
- gate already has, and the object itself is not one of them.
220
+ `spikes/pykeepass-compatibility` branch: 65 of the 122 public members of `PyKeePass`, `Entry`,
221
+ `Group` and `Attachment` are servable over the routes the gate already has, 24 of the 56 on
222
+ `PyKeePass` itself, and the object itself is not one of them.
208
223
 
209
224
  **It defends nothing against local code execution as the user.** The client's key is on the disk,
210
225
  because a client has to still be the same client tomorrow. The whole design concedes this
@@ -16,10 +16,9 @@ it does not do is a statement too: a route with no method here is a route the ga
16
16
 
17
17
  from __future__ import annotations
18
18
 
19
- from importlib.metadata import version
20
-
21
19
  from .api import (
22
20
  Access,
21
+ AmbiguousName,
23
22
  AuthorityUndecided,
24
23
  Credentials,
25
24
  DatabaseLocked,
@@ -29,6 +28,7 @@ from .api import (
29
28
  GateError,
30
29
  GateUnavailable,
31
30
  Identity,
31
+ IncompatibleGate,
32
32
  MalformedToken,
33
33
  NotAdmitted,
34
34
  NotPaired,
@@ -54,14 +54,15 @@ from .api import (
54
54
  Withheld,
55
55
  pair,
56
56
  )
57
+ from .compatibility import CLIENT_VERSION
57
58
 
58
- #: The version this client was installed as, which the plugin and the routing document carry too.
59
- #: It is written in one place, `Directory.Build.props`, and an installed package keeps it in its
60
- #: metadata, so it is read from there rather than written a second time here.
61
- __version__ = version("pykeepassgate")
59
+ #: The version this client was installed as, which the plugin and the routing document carry too,
60
+ #: and which `compatibility` compares with the version a gate reports.
61
+ __version__ = CLIENT_VERSION
62
62
 
63
63
  __all__ = [
64
64
  "Access",
65
+ "AmbiguousName",
65
66
  "AuthorityUndecided",
66
67
  "Credentials",
67
68
  "DatabaseLocked",
@@ -71,6 +72,7 @@ __all__ = [
71
72
  "GateError",
72
73
  "GateUnavailable",
73
74
  "Identity",
75
+ "IncompatibleGate",
74
76
  "MalformedToken",
75
77
  "NotAdmitted",
76
78
  "NotPaired",
@@ -5,10 +5,10 @@ and the exceptions that say what to do next. The modules underneath stay importa
5
5
  pieces of the protocol are worth reading on their own, but nothing outside this package has to know
6
6
  which module a name lives in.
7
7
 
8
- The one thing `api` adds rather than re-exports is `pair`, which is the whole exchange as one call.
9
- It exists because the two-connection shape is the protocol's business rather than the caller's, and
10
- a reference implementation that made every caller drive both halves by hand would be teaching the
11
- wrong lesson.
8
+ What `api` adds rather than re-exports is `pair`, which is the whole exchange as one call, and
9
+ `DEFAULT_PORT`, the port it dials unless told another. `pair` exists because the two-connection
10
+ shape is the protocol's business rather than the caller's, and a reference implementation that
11
+ made every caller drive both halves by hand would be teaching the wrong lesson.
12
12
  """
13
13
 
14
14
  from __future__ import annotations
@@ -19,11 +19,13 @@ from pathlib import Path
19
19
  from .client import ROOT, GateClient, Renewal, Status
20
20
  from .credentials import Credentials, Prepared, default_directory, forget, load, prepare, save
21
21
  from .errors import (
22
+ AmbiguousName,
22
23
  AuthorityUndecided,
23
24
  DatabaseLocked,
24
25
  GateBusy,
25
26
  GateError,
26
27
  GateUnavailable,
28
+ IncompatibleGate,
27
29
  MalformedToken,
28
30
  NotAdmitted,
29
31
  NotPaired,
@@ -55,12 +57,13 @@ from .pairing import (
55
57
  refuse_unusable,
56
58
  )
57
59
  from .transport import (
60
+ BOUNDED_RESPONSE_KILOBYTES,
58
61
  DEFAULT_CONNECTION_TIMEOUT,
59
62
  DEFAULT_RETRY_BUSY_TIMEOUT,
60
63
  DEFAULT_RETRY_LOCKED_TIMEOUT,
61
64
  DEFAULT_RETRY_UNDECIDED_TIMEOUT,
62
65
  LOOPBACK,
63
- MAX_RESPONSE_BYTES,
66
+ MAX_RESPONSE_KILOBYTES,
64
67
  PAIRING_CONNECTION_TIMEOUT,
65
68
  Dial,
66
69
  KeyPassword,
@@ -68,13 +71,14 @@ from .transport import (
68
71
  connection_limit,
69
72
  create_connection,
70
73
  dial_limit,
74
+ host_limit,
71
75
  key_password_limit,
72
76
  key_secret,
73
77
  port_number,
74
- response_limit,
75
78
  )
76
79
 
77
80
  __all__ = [
81
+ "BOUNDED_RESPONSE_KILOBYTES",
78
82
  "DEFAULT_CONNECTION_TIMEOUT",
79
83
  "DEFAULT_PORT",
80
84
  "DEFAULT_RETRY_BUSY_TIMEOUT",
@@ -82,11 +86,12 @@ __all__ = [
82
86
  "DEFAULT_RETRY_UNDECIDED_TIMEOUT",
83
87
  "LONGEST_LIFETIME",
84
88
  "LOOPBACK",
85
- "MAX_RESPONSE_BYTES",
89
+ "MAX_RESPONSE_KILOBYTES",
86
90
  "PAIRING_CONNECTION_TIMEOUT",
87
91
  "ROOT",
88
92
  "SHORTEST_LIFETIME",
89
93
  "Access",
94
+ "AmbiguousName",
90
95
  "Attachment",
91
96
  "AuthorityUndecided",
92
97
  "Credentials",
@@ -102,6 +107,7 @@ __all__ = [
102
107
  "GateUnavailable",
103
108
  "Group",
104
109
  "Identity",
110
+ "IncompatibleGate",
105
111
  "KeyPassword",
106
112
  "MalformedToken",
107
113
  "NotAdmitted",
@@ -149,9 +155,11 @@ def pair(
149
155
  directory: Path | None = None,
150
156
  profile: str = "default",
151
157
  # Not `DEFAULT_CONNECTION_TIMEOUT`. This is one of the two exchanges that wait on a person, and
152
- # the gate gives itself six minutes for it because its own worst case is 305 seconds. Hanging up
153
- # first cancels nothing: the invitation is spent and the record is written and saved
154
- # anyway, and only the answer is lost.
158
+ # the gate keeps everything before its save begins inside its own six minutes, by shortening a
159
+ # dialog that comes up late; the save itself is waited for with no deadline on the gate's side,
160
+ # which a longer timeout here covers. Hanging up first cancels
161
+ # nothing: the invitation is spent and the record is written and saved anyway, and only the
162
+ # answer is lost.
155
163
  connection_timeout: float = PAIRING_CONNECTION_TIMEOUT,
156
164
  host: str = LOOPBACK,
157
165
  dial: Dial = create_connection,
@@ -159,7 +167,6 @@ def pair(
159
167
  retry_locked_timeout: float | None = DEFAULT_RETRY_LOCKED_TIMEOUT,
160
168
  retry_undecided_timeout: float | None = DEFAULT_RETRY_UNDECIDED_TIMEOUT,
161
169
  allow_shared_directory: bool = False,
162
- max_response_bytes: int = MAX_RESPONSE_BYTES,
163
170
  lifetime: timedelta | None = None,
164
171
  key_password: KeyPassword | None = None,
165
172
  ) -> Credentials:
@@ -207,8 +214,8 @@ def pair(
207
214
  # which `Retry` holds to the same rule, and a key password that is none.
208
215
  port_number(port)
209
216
  connection_limit(connection_timeout)
210
- response_limit(max_response_bytes)
211
217
  dial_limit(dial)
218
+ host_limit(host, dial)
212
219
  if lifetime is not None:
213
220
  lifetime_text(lifetime)
214
221
  where = directory or default_directory(profile)
@@ -238,7 +245,6 @@ def pair(
238
245
  connection_timeout=connection_timeout,
239
246
  host=host,
240
247
  dial=dial,
241
- max_response_bytes=max_response_bytes,
242
248
  )
243
249
 
244
250
  try: