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.
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/PKG-INFO +45 -30
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/pyproject.toml +43 -10
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/README.md +44 -29
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/__init__.py +8 -6
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/api.py +19 -13
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/cli.py +848 -181
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/client.py +772 -140
- pykeepassgate-0.2.0/src/pykeepassgate/compatibility.py +83 -0
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/credentials.py +226 -38
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/errors.py +96 -27
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/model.py +154 -55
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/pairing.py +39 -18
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/refs.py +253 -63
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/sni.py +1 -1
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/testing.py +420 -62
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/transport.py +682 -120
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/.gitignore +0 -0
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/LICENSE +0 -0
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/proofs.py +0 -0
- {pykeepassgate-0.1.0 → pykeepassgate-0.2.0}/src/pykeepassgate/py.typed +0 -0
- {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.
|
|
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
|
|
35
|
-
and minor
|
|
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,
|
|
97
|
-
operator's tab shows a rule, and `.allows("RP")` asks whether one of those
|
|
98
|
-
protected values there; `pykeepassgate access --entry <uuid>` prints them. A
|
|
99
|
-
|
|
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
|
|
117
|
-
answers with the tag it left, for the next write to name. The gate
|
|
118
|
-
|
|
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
|
|
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
|
|
163
|
-
| `AuthorityUndecided` | The database holds
|
|
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
|
|
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.
|
|
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.
|
|
177
|
-
| `RouteRefused` | Everything else the gate refuses, carrying the status and the reason it gave, usually one word: a `413`
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
-
**
|
|
202
|
-
asking again reads the same answer to the same
|
|
203
|
-
|
|
204
|
-
|
|
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:
|
|
220
|
-
|
|
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
|
|
109
|
-
#
|
|
110
|
-
# look further, RUF001 to RUF003 know more ambiguous characters. None of it finds
|
|
111
|
-
# code, which passes with `--no-preview` as well. But preview behavior is what a
|
|
112
|
-
# change with no rule added or selected, so a finding that arrives with an upgrade
|
|
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
|
|
22
|
-
and minor
|
|
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,
|
|
84
|
-
operator's tab shows a rule, and `.allows("RP")` asks whether one of those
|
|
85
|
-
protected values there; `pykeepassgate access --entry <uuid>` prints them. A
|
|
86
|
-
|
|
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
|
|
104
|
-
answers with the tag it left, for the next write to name. The gate
|
|
105
|
-
|
|
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
|
|
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
|
|
150
|
-
| `AuthorityUndecided` | The database holds
|
|
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
|
|
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.
|
|
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.
|
|
164
|
-
| `RouteRefused` | Everything else the gate refuses, carrying the status and the reason it gave, usually one word: a `413`
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
-
**
|
|
189
|
-
asking again reads the same answer to the same
|
|
190
|
-
|
|
191
|
-
|
|
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:
|
|
207
|
-
|
|
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
|
-
#:
|
|
60
|
-
|
|
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
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
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
|
|
153
|
-
#
|
|
154
|
-
#
|
|
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:
|