keyloom 0.1.0__py3-none-any.whl

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 (28) hide show
  1. keyloom/__init__.py +357 -0
  2. keyloom/_cli.py +481 -0
  3. keyloom/_envelope.py +338 -0
  4. keyloom/_errors.py +36 -0
  5. keyloom/_files.py +389 -0
  6. keyloom/_formats.py +235 -0
  7. keyloom/_metadata.py +30 -0
  8. keyloom/_tree.py +236 -0
  9. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/icon/pdf/keyloom-icon-color-on-transparent-none.pdf +0 -0
  10. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/icon/png/keyloom-icon-color-on-transparent-none-2048px.png +0 -0
  11. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/icon/svg/keyloom-icon-color-on-transparent-none.svg +44 -0
  12. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/logo-horizontal/pdf/keyloom-logo-horizontal-color-on-transparent-none.pdf +0 -0
  13. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/logo-horizontal/png/keyloom-logo-horizontal-color-on-transparent-none-2048px.png +0 -0
  14. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/logo-horizontal/svg/keyloom-logo-horizontal-color-on-transparent-none.svg +45 -0
  15. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/manifest.json +174 -0
  16. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/wordmark/pdf/keyloom-wordmark-color-on-transparent-none.pdf +0 -0
  17. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/wordmark/png/keyloom-wordmark-color-on-transparent-none-2048px.png +0 -0
  18. keyloom-0.1.0.data/data/share/keyloom/brandkit/generated/wordmark/svg/keyloom-wordmark-color-on-transparent-none.svg +8 -0
  19. keyloom-0.1.0.data/data/share/keyloom/source/ADLaMDisplay-Regular.ttf +0 -0
  20. keyloom-0.1.0.data/data/share/keyloom/source/icon.svg +45 -0
  21. keyloom-0.1.0.data/data/share/keyloom/source/logo.svg +239 -0
  22. keyloom-0.1.0.data/data/share/keyloom/source/wordmark.svg +64 -0
  23. keyloom-0.1.0.dist-info/METADATA +31 -0
  24. keyloom-0.1.0.dist-info/RECORD +28 -0
  25. keyloom-0.1.0.dist-info/WHEEL +4 -0
  26. keyloom-0.1.0.dist-info/entry_points.txt +2 -0
  27. keyloom-0.1.0.dist-info/licenses/LICENSES/Apache-2.0.txt +73 -0
  28. keyloom-0.1.0.dist-info/licenses/LICENSES/OFL-1.1.txt +43 -0
keyloom/__init__.py ADDED
@@ -0,0 +1,357 @@
1
+ # ------------------------------------------------------------------------------
2
+ # SPDX-FileCopyrightText: 2026 SEANERGYS Partners <https://seanergys.eu>
3
+ # SPDX-License-Identifier: Apache-2.0
4
+ # ------------------------------------------------------------------------------
5
+ """Field-level encryption for configuration files.
6
+
7
+ A configuration file marks each secret value with a wrapper,
8
+ `{"__keyloom__": "secret", "value": ...}`. keyloom encrypts the value
9
+ in place and leaves the rest of the file readable. A wrapper whose value is
10
+ `__keyloom__secret__` is a placeholder, whose secret is entered when the
11
+ file is encrypted.
12
+ Applications read such a file with `load`; tools write one with `store` or
13
+ encrypt one with `encrypt_file`.
14
+
15
+ Everything listed in `__all__` is defined here and is the whole public API.
16
+ The modules whose names start with an underscore are the implementation.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import typing as _typing
22
+
23
+ import keyloom._envelope as _envelope
24
+ import keyloom._files as _files
25
+ import keyloom._metadata as _metadata
26
+ import keyloom._tree as _tree
27
+
28
+ # The annotations name typing and pathlib rather than private aliases, so that
29
+ # the API reference reads naturally; they are never evaluated at run time.
30
+ if _typing.TYPE_CHECKING:
31
+ import pathlib
32
+ import typing
33
+
34
+ __version__ = _metadata.__version__
35
+ """The version of the installed keyloom package."""
36
+
37
+ # ------------------------------------------------------------------------------
38
+ # Errors
39
+ # ------------------------------------------------------------------------------
40
+
41
+
42
+ class KeyloomError(Exception):
43
+ """Base class of every failure a user can cause or fix.
44
+
45
+ Any other exception raised by keyloom is a bug.
46
+ """
47
+
48
+
49
+ class PasswordError(KeyloomError):
50
+ """The vault password is empty or was not confirmed."""
51
+
52
+
53
+ class ParseError(KeyloomError):
54
+ """A file is not valid TOML, YAML, JSON or UTF-8."""
55
+
56
+
57
+ class UnsupportedFormat(KeyloomError):
58
+ """A file extension is not supported, or the format cannot hold the data."""
59
+
60
+
61
+ class InvalidSecret(KeyloomError):
62
+ """A `__keyloom__` wrapper is not a valid secret."""
63
+
64
+
65
+ class PlaintextSecret(KeyloomError):
66
+ """A secret that must be encrypted holds plaintext."""
67
+
68
+
69
+ class MissingSecret(KeyloomError):
70
+ """A secret is a placeholder, or no value was entered for it."""
71
+
72
+
73
+ class MalformedEnvelope(KeyloomError):
74
+ """An encrypted value is not a valid envelope."""
75
+
76
+
77
+ class UnsupportedAlgorithm(KeyloomError):
78
+ """An algorithm name is not known to this version of keyloom."""
79
+
80
+
81
+ class DecryptionError(KeyloomError):
82
+ """The password is wrong or the encrypted value was modified."""
83
+
84
+
85
+ class UnsafeOutput(KeyloomError):
86
+ """Writing the output would replace the encrypted input with plaintext."""
87
+
88
+
89
+ # ------------------------------------------------------------------------------
90
+ # Configuration in applications
91
+ # ------------------------------------------------------------------------------
92
+
93
+
94
+ def load(*, path: str | pathlib.Path, password: str) -> typing.Any:
95
+ """Read a configuration file and return it with its secrets decrypted.
96
+
97
+ The result is made of plain dicts, lists and scalars, with every secret
98
+ wrapper replaced by its value.
99
+
100
+ @param path TOML, YAML or JSON file, chosen by its extension.
101
+
102
+ @param password The vault password.
103
+
104
+ @return The decrypted configuration.
105
+
106
+ @throws PlaintextSecret A secret in the file is not encrypted.
107
+
108
+ @throws MissingSecret A secret in the file is a placeholder.
109
+
110
+ @throws DecryptionError The password is wrong or a value was modified.
111
+ """
112
+ return _files.load(path=path, password=password)
113
+
114
+
115
+ def store(
116
+ *,
117
+ path: str | pathlib.Path,
118
+ data: typing.Any,
119
+ password: str,
120
+ algorithm: str,
121
+ ) -> int:
122
+ """Write data to a configuration file with its secrets encrypted.
123
+
124
+ Mark each secret in `data` with `secret`. The file is written fresh and
125
+ atomically: comments of an existing file are not kept, but its
126
+ permissions are, and a new file gets mode 0600. `data` itself is not
127
+ changed.
128
+
129
+ @param path TOML, YAML or JSON file, chosen by its extension.
130
+
131
+ @param data Dicts, lists and scalars, with secrets marked by `secret`.
132
+
133
+ @param password The vault password.
134
+
135
+ @param algorithm The algorithm for the secrets, from `algorithms`.
136
+
137
+ @return The number of secrets encrypted.
138
+
139
+ @throws MissingSecret A secret in `data` is a placeholder.
140
+
141
+ @throws UnsupportedFormat The file format cannot hold the data.
142
+ """
143
+ return _files.store(
144
+ path=path, data=data, password=password, algorithm=algorithm
145
+ )
146
+
147
+
148
+ def secret(*, value: typing.Any) -> dict[str, typing.Any]:
149
+ """Mark a value as a secret, for the data passed to `store`.
150
+
151
+ @param value A string, number, boolean or None.
152
+
153
+ @return The wrapper `{"__keyloom__": "secret", "value": value}`.
154
+ """
155
+ return _tree.secret(value=value)
156
+
157
+
158
+ # ------------------------------------------------------------------------------
159
+ # Files
160
+ # ------------------------------------------------------------------------------
161
+
162
+
163
+ def encrypt_file(
164
+ *,
165
+ input_path: str | pathlib.Path,
166
+ output_path: str | pathlib.Path,
167
+ password: str,
168
+ algorithm: str,
169
+ prompt: typing.Callable[[str], typing.Any] | None,
170
+ ) -> int:
171
+ """Encrypt the plaintext secrets and placeholders of a configuration file.
172
+
173
+ Pass the same path twice to encrypt in place. The output is written
174
+ atomically and keeps the permissions of a file it replaces. A file
175
+ without plaintext secrets or placeholders is not rewritten in place, so
176
+ its formatting stays exactly as it was. Existing envelopes keep their
177
+ algorithm.
178
+
179
+ Existing envelopes are checked against `password` before `prompt` is
180
+ called, and every value is encrypted only after all placeholders have
181
+ one, so nothing is written if any step fails.
182
+
183
+ @param input_path The file to read.
184
+
185
+ @param output_path The file to write; may be `input_path`.
186
+
187
+ @param password The vault password, also checked against existing
188
+ envelopes.
189
+
190
+ @param algorithm The algorithm for newly encrypted secrets.
191
+
192
+ @param prompt Called once for every placeholder, in document order, with
193
+ its location such as `git."gitlab.example.org".token`; returns its
194
+ value. None makes a placeholder an error.
195
+
196
+ @return The number of secrets encrypted, placeholders included.
197
+
198
+ @throws DecryptionError An existing envelope uses another password.
199
+
200
+ @throws MissingSecret The file has a placeholder and `prompt` is None.
201
+ """
202
+ return _files.encrypt_file(
203
+ input_path=input_path,
204
+ output_path=output_path,
205
+ password=password,
206
+ algorithm=algorithm,
207
+ prompt=prompt,
208
+ )
209
+
210
+
211
+ def decrypt_file(
212
+ *,
213
+ input_path: str | pathlib.Path,
214
+ output_path: str | pathlib.Path,
215
+ password: str,
216
+ ) -> None:
217
+ """Decrypt the secrets of a configuration file into a plaintext file.
218
+
219
+ The wrappers are kept, so `encrypt_file` turns the output back into an
220
+ encrypted file. The output is written atomically with mode 0600.
221
+
222
+ @param input_path The encrypted file.
223
+
224
+ @param output_path The plaintext file; must not be `input_path`.
225
+
226
+ @param password The vault password.
227
+
228
+ @throws UnsafeOutput The output is the input file, directly or through a
229
+ link.
230
+
231
+ @throws PlaintextSecret A secret in the file is not encrypted.
232
+
233
+ @throws MissingSecret A secret in the file is a placeholder.
234
+ """
235
+ _files.decrypt_file(
236
+ input_path=input_path, output_path=output_path, password=password
237
+ )
238
+
239
+
240
+ def reencrypt_file(
241
+ *,
242
+ input_path: str | pathlib.Path,
243
+ output_path: str | pathlib.Path,
244
+ password: str,
245
+ new_password: str,
246
+ algorithm: str,
247
+ ) -> int:
248
+ """Encrypt every secret of a file again, without writing plaintext.
249
+
250
+ Every secret is decrypted with `password` and encrypted with
251
+ `new_password` and `algorithm`, in memory. Pass the same password twice
252
+ to change only the algorithm, and the same path twice to work in place.
253
+
254
+ @param input_path The encrypted file.
255
+
256
+ @param output_path The file to write; may be `input_path`.
257
+
258
+ @param password The current vault password.
259
+
260
+ @param new_password The vault password to encrypt with.
261
+
262
+ @param algorithm The algorithm to encrypt with.
263
+
264
+ @return The number of secrets encrypted again.
265
+
266
+ @throws PlaintextSecret A secret in the file is not encrypted.
267
+
268
+ @throws MissingSecret A secret in the file is a placeholder.
269
+ """
270
+ return _files.reencrypt_file(
271
+ input_path=input_path,
272
+ output_path=output_path,
273
+ password=password,
274
+ new_password=new_password,
275
+ algorithm=algorithm,
276
+ )
277
+
278
+
279
+ # ------------------------------------------------------------------------------
280
+ # Single values
281
+ # ------------------------------------------------------------------------------
282
+
283
+
284
+ def encrypt_value(*, value: typing.Any, password: str, algorithm: str) -> str:
285
+ """Encrypt one value into a self-contained envelope string.
286
+
287
+ The envelope names its algorithm and carries its own salt and nonce, so
288
+ it can be decrypted wherever it is copied.
289
+
290
+ @param value A string, number, boolean or None.
291
+
292
+ @param password The vault password.
293
+
294
+ @param algorithm The algorithm, from `algorithms`.
295
+
296
+ @return An envelope such as `$KEYLOOM;1;argon2;s=...;n=...;c=...`.
297
+
298
+ @throws InvalidSecret The value is not a scalar, or is a string that
299
+ starts with `$KEYLOOM;`.
300
+
301
+ @throws UnsupportedAlgorithm The algorithm is not known.
302
+ """
303
+ return _envelope.encrypt_value(
304
+ value=value, password=password, algorithm=algorithm
305
+ )
306
+
307
+
308
+ def decrypt_value(*, value: str, password: str) -> typing.Any:
309
+ """Authenticate and decrypt one envelope string.
310
+
311
+ @param value The envelope.
312
+
313
+ @param password The vault password.
314
+
315
+ @return The original string, number, boolean or None.
316
+
317
+ @throws DecryptionError The password is wrong or the value was modified.
318
+
319
+ @throws MalformedEnvelope The value is not a valid envelope.
320
+ """
321
+ return _envelope.decrypt_value(value=value, password=password)
322
+
323
+
324
+ def algorithms() -> tuple[str, ...]:
325
+ """Return the names of the supported algorithms.
326
+
327
+ An algorithm name fixes every cryptographic parameter; new parameters
328
+ come as a new name.
329
+
330
+ @return The names, such as `("argon2",)`.
331
+ """
332
+ return _envelope.algorithms()
333
+
334
+
335
+ __all__ = [
336
+ "DecryptionError",
337
+ "InvalidSecret",
338
+ "KeyloomError",
339
+ "MalformedEnvelope",
340
+ "MissingSecret",
341
+ "ParseError",
342
+ "PasswordError",
343
+ "PlaintextSecret",
344
+ "UnsafeOutput",
345
+ "UnsupportedAlgorithm",
346
+ "UnsupportedFormat",
347
+ "__version__",
348
+ "algorithms",
349
+ "decrypt_file",
350
+ "decrypt_value",
351
+ "encrypt_file",
352
+ "encrypt_value",
353
+ "load",
354
+ "reencrypt_file",
355
+ "secret",
356
+ "store",
357
+ ]