skapi 2.4.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.
skapi/_encryption.py ADDED
@@ -0,0 +1,1359 @@
1
+ """
2
+ Client-side record encryption, ported byte for byte from skapi-js (src/utils/crypto.ts,
3
+ src/methods/encryption.ts), so records and files sealed by either SDK open in the other.
4
+
5
+ Only `record.data` of PRIVATE records is sealed, with a per-record key (DEK). The DEK is wrapped
6
+ for the owner under a master key (MK) that only the user's password (or encryption recovery code) opens, and
7
+ for each user the record is shared with through ECDH P-256. The MK lives in a keyring record in the
8
+ reserved table "__skapi__keyring". Needs the `cryptography` package: pip install "skapi[encryption]".
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import base64
14
+ import hashlib
15
+ import json
16
+ import math
17
+ import os
18
+ import time
19
+ import unicodedata
20
+ import warnings
21
+ from typing import Any, Dict, List, Optional, Tuple
22
+
23
+ from .errors import SkapiError
24
+
25
+ ENC_V = "skapi.enc.v1"
26
+ PBKDF2_ITERATIONS = 600000
27
+ ENV_MARKER = "__skapi_enc__"
28
+ WITHHELD = "__skapi_no_access__"
29
+ SPILL_LIMIT = 256 * 1024
30
+ CT_KEY = "__skenc_ct__"
31
+ CT_FILE = "payload.bin"
32
+ CT_FILE_SUFFIX = f"/{CT_KEY}/{CT_FILE}"
33
+ FILE_MARKER = "__skenc__"
34
+ FILE_CHUNK = 4 * 1024 * 1024
35
+ ENVELOPE_CAP = 2 * 1024 * 1024
36
+ B62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
37
+ B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
38
+
39
+
40
+ def _err(message: str, code: str) -> SkapiError:
41
+ return SkapiError(message, code)
42
+
43
+
44
+ # ---- crypto-free helpers (used with encryption off too) ------------------------------------------
45
+
46
+ def is_envelope(v: Any) -> bool:
47
+ return (isinstance(v, dict) and isinstance(v.get(ENV_MARKER), (int, float)) and not isinstance(v.get(ENV_MARKER), bool)
48
+ and all(isinstance(v.get(k), str) for k in ("ct", "iv", "own", "anch")) and isinstance(v.get("k"), dict))
49
+
50
+
51
+ def b62(n: int) -> str:
52
+ if n == 0:
53
+ return "0"
54
+ out = ""
55
+ while n > 0:
56
+ n, r = divmod(n, 62)
57
+ out = B62[r] + out
58
+ return out
59
+
60
+
61
+ def from_b62_strict(s: str) -> Optional[int]:
62
+ if not s:
63
+ return None
64
+ n = 0
65
+ for ch in s:
66
+ i = B62.find(ch)
67
+ if i < 0:
68
+ return None
69
+ n = n * 62 + i
70
+ return n
71
+
72
+
73
+ def parse_file_marker(path_key: str) -> Optional[Tuple[str, int]]:
74
+ """'<form key>__skenc__<b62 plain size>' -> (form key, plain size), else None."""
75
+ i = path_key.rfind(FILE_MARKER)
76
+ if i < 0:
77
+ return None
78
+ size = from_b62_strict(path_key[i + len(FILE_MARKER):])
79
+ return None if size is None else (path_key[:i], size)
80
+
81
+
82
+ def b64u(b: bytes) -> str:
83
+ return base64.urlsafe_b64encode(b).decode("ascii").rstrip("=")
84
+
85
+
86
+ def b64u_dec(s: Any) -> bytes:
87
+ if not isinstance(s, str):
88
+ raise _err("Expected a base64url string.", "INVALID_PARAMETER")
89
+ if len(s) % 4 == 1:
90
+ raise _err("Malformed base64url string.", "INVALID_PARAMETER")
91
+ return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
92
+
93
+
94
+ def utf8(s: str) -> bytes:
95
+ try:
96
+ return s.encode("utf-8")
97
+ except UnicodeEncodeError: # TextEncoder writes a lone surrogate as U+FFFD
98
+ return s.encode("utf-16", "surrogatepass").decode("utf-16", "replace").encode("utf-8")
99
+
100
+
101
+ def utf8_dec(b: bytes) -> str:
102
+ s = b.decode("utf-8", "replace")
103
+ return s[1:] if s.startswith("") else s
104
+
105
+
106
+ def _js_json(v: Any) -> str:
107
+ from ._http import js_json
108
+ return js_json(v)
109
+
110
+
111
+ def check_bits(raw: bytes) -> int:
112
+ """skapi-js's recovery code check: FNV-1a as JavaScript computes it (signed XOR, double multiply)."""
113
+ h = 0x811c9dc5
114
+ for b in raw:
115
+ x = h ^ b
116
+ if x >= 2 ** 31:
117
+ x -= 2 ** 32
118
+ h = int(float(x) * 16777619.0) % 2 ** 32
119
+ return h & 0x3ff
120
+
121
+
122
+ def encode_recovery_code(raw: bytes) -> str:
123
+ out, acc, bits = "", 0, 0
124
+ for b in raw:
125
+ acc = (acc << 8) | b
126
+ bits += 8
127
+ while bits >= 5:
128
+ bits -= 5
129
+ out += B32[(acc >> bits) & 31]
130
+ if bits:
131
+ out += B32[(acc << (5 - bits)) & 31]
132
+ chk = check_bits(raw)
133
+ out += B32[(chk >> 5) & 31] + B32[chk & 31]
134
+ return "-".join(out[i:i + 4] for i in range(0, len(out), 4))
135
+
136
+
137
+ def decode_recovery_code(code: str) -> bytes:
138
+ s = "".join(ch for ch in str(code).upper() if ch not in " \t\r\n-_").replace("O", "0").replace("I", "1").replace("L", "1")
139
+ if len(s) != 28:
140
+ raise _err(f"That does not look like an encryption recovery code: expected 28 characters, got {len(s)}.", "ENCRYPTION_BAD_RECOVERY_CODE")
141
+ for ch in s:
142
+ if ch not in B32:
143
+ raise _err(f'That does not look like an encryption recovery code: "{ch}" is not a valid character.', "ENCRYPTION_BAD_RECOVERY_CODE")
144
+ acc, bits, out = 0, 0, bytearray()
145
+ for ch in s[:26]:
146
+ acc = (acc << 5) | B32.index(ch)
147
+ bits += 5
148
+ if bits >= 8:
149
+ bits -= 8
150
+ out.append((acc >> bits) & 0xFF)
151
+ raw = bytes(out[:16])
152
+ chk = check_bits(raw)
153
+ if s[26:] != B32[(chk >> 5) & 31] + B32[chk & 31]:
154
+ raise _err("That encryption recovery code has a typo in it: the check characters do not match.", "ENCRYPTION_BAD_RECOVERY_CODE")
155
+ return raw
156
+
157
+
158
+ # ---- primitives (cryptography) ------------------------------------------------------------------
159
+
160
+ def _lib():
161
+ try:
162
+ from cryptography.hazmat.primitives import hashes, serialization
163
+ from cryptography.hazmat.primitives.asymmetric import ec
164
+ from cryptography.hazmat.primitives.ciphers.aead import AESGCM
165
+ from cryptography.hazmat.primitives.kdf.hkdf import HKDF
166
+ from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
167
+ except ImportError:
168
+ raise _err('Record encryption needs the "cryptography" package: pip install "skapi[encryption]"', "NOT_SUPPORTED") from None
169
+ return hashes, serialization, ec, AESGCM, HKDF, PBKDF2HMAC
170
+
171
+
172
+ def hkdf(ikm: bytes, salt: bytes, info: str, length: int = 32) -> bytes:
173
+ hashes, _, _, _, HKDF, _ = _lib()
174
+ return HKDF(algorithm=hashes.SHA256(), length=length, salt=salt, info=utf8(info)).derive(ikm)
175
+
176
+
177
+ def seal(key: bytes, pt: bytes, aad: bytes) -> Dict[str, str]:
178
+ AESGCM = _lib()[3]
179
+ iv = os.urandom(12)
180
+ return {"iv": b64u(iv), "ct": b64u(AESGCM(key).encrypt(iv, pt, aad))}
181
+
182
+
183
+ def seal_raw(key: bytes, pt: bytes, aad: bytes) -> Tuple[bytes, bytes]:
184
+ AESGCM = _lib()[3]
185
+ iv = os.urandom(12)
186
+ return iv, AESGCM(key).encrypt(iv, pt, aad)
187
+
188
+
189
+ def open_(key: bytes, iv: bytes, ct: bytes, aad: bytes) -> bytes:
190
+ AESGCM = _lib()[3]
191
+ return AESGCM(key).decrypt(iv, ct, aad)
192
+
193
+
194
+ def password_kek(password: str, salt: bytes, iterations: int, info: str) -> bytes:
195
+ hashes, _, _, _, _, PBKDF2HMAC = _lib()
196
+ prk = PBKDF2HMAC(algorithm=hashes.SHA256(), length=32, salt=salt, iterations=iterations).derive(utf8(unicodedata.normalize("NFC", password)))
197
+ return hkdf(prk, salt, info)
198
+
199
+
200
+ def new_identity():
201
+ _, serialization, ec, _, _, _ = _lib()
202
+ priv = ec.generate_private_key(ec.SECP256R1())
203
+ pub = priv.public_key().public_bytes(serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint)
204
+ pkcs8 = priv.private_bytes(serialization.Encoding.DER, serialization.PrivateFormat.PKCS8, serialization.NoEncryption())
205
+ return priv, pub, pkcs8
206
+
207
+
208
+ def load_pkcs8(der: bytes):
209
+ serialization = _lib()[1]
210
+ return serialization.load_der_private_key(der, password=None)
211
+
212
+
213
+ def load_pub(raw: bytes):
214
+ ec = _lib()[2]
215
+ if len(raw) != 65 or raw[0] != 0x04:
216
+ raise _err("Malformed public key: expected a 65 byte uncompressed P-256 point.", "INVALID_PARAMETER")
217
+ return ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), raw)
218
+
219
+
220
+ def fingerprint(pub_raw: bytes) -> str:
221
+ return b64u(hashlib.sha256(pub_raw).digest())
222
+
223
+
224
+ def ecdh_wrap(dek: bytes, peer_pub_raw: bytes, info: str, aad: bytes) -> Dict[str, str]:
225
+ _, serialization, ec, _, _, _ = _lib()
226
+ eph = ec.generate_private_key(ec.SECP256R1())
227
+ z = eph.exchange(ec.ECDH(), load_pub(peer_pub_raw))
228
+ kw = hkdf(z, b"\x00" * 32, info)
229
+ sealed = seal(kw, dek, aad)
230
+ epk = eph.public_key().public_bytes(serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint)
231
+ return {"epk": b64u(epk), **sealed}
232
+
233
+
234
+ def ecdh_unwrap(priv, wrap: Dict[str, str], info: str, aad: bytes) -> bytes:
235
+ ec = _lib()[2]
236
+ z = priv.exchange(ec.ECDH(), load_pub(b64u_dec(wrap["epk"])))
237
+ return open_(hkdf(z, b"\x00" * 32, info), b64u_dec(wrap["iv"]), b64u_dec(wrap["ct"]), aad)
238
+
239
+
240
+ # ---- encrypted file container "SKENCF" v2 ---------------------------------------------------------
241
+
242
+ def dek_id(dek: bytes) -> bytes:
243
+ return hashlib.sha256(utf8(f"{ENC_V}|dekid") + dek).digest()[:8]
244
+
245
+
246
+ def _file_key(dek: bytes, file_id: bytes, ctx: Dict[str, str]) -> bytes:
247
+ return hkdf(dek, file_id, f"{ENC_V}|binfile|{ctx['service']}|{ctx['owner']}|{ctx['recordOwner']}|{ctx['recordId']}")
248
+
249
+
250
+ def encrypt_file(dek: bytes, ctx: Dict[str, str], content: bytes, name: str, content_type: Optional[str], last_modified: int = 0) -> bytes:
251
+ meta = utf8(json.dumps({"n": name, "t": content_type or "", "lm": last_modified or 0}, separators=(",", ":"), ensure_ascii=False))
252
+ if len(meta) > 4096:
253
+ raise _err("Encrypted file metadata is too large.", "INVALID_PARAMETER")
254
+ count = max(1, math.ceil(len(content) / FILE_CHUNK))
255
+ file_id = os.urandom(16)
256
+ header = (b"SKENCF" + bytes([2, 1 if meta else 0]) + FILE_CHUNK.to_bytes(4, "big") + count.to_bytes(4, "big") + file_id
257
+ + len(content).to_bytes(8, "big") + dek_id(dek) + len(meta).to_bytes(4, "big") + b"\x00\x00\x00\x00" + meta)
258
+ header_hash = b64u(hashlib.sha256(header).digest())
259
+ key = _file_key(dek, file_id, ctx)
260
+ out = [header]
261
+ for i in range(count):
262
+ chunk = content[i * FILE_CHUNK:(i + 1) * FILE_CHUNK]
263
+ aad = utf8(json.dumps([f"{ENC_V}|binchunk", header_hash, i, count], separators=(",", ":")))
264
+ iv, ct = seal_raw(key, chunk, aad)
265
+ out.append((12 + len(ct)).to_bytes(4, "big") + iv + ct)
266
+ return b"".join(out)
267
+
268
+
269
+ def is_encrypted_file(b: bytes) -> bool:
270
+ return len(b) >= 56 and b[:6] == b"SKENCF"
271
+
272
+
273
+ def decrypt_file(dek: bytes, ctx: Dict[str, str], blob: bytes) -> Tuple[bytes, Dict[str, Any]]:
274
+ if len(blob) < 56:
275
+ raise _err("Encrypted file header is truncated.", "INVALID_REQUEST")
276
+ version = blob[6]
277
+ chunk_size = int.from_bytes(blob[8:12], "big")
278
+ count = int.from_bytes(blob[12:16], "big")
279
+ file_id = blob[16:32]
280
+ plain_len = int.from_bytes(blob[32:40], "big")
281
+ did = blob[40:48]
282
+ meta_len = int.from_bytes(blob[48:52], "big")
283
+ if len(blob) < 56 + meta_len:
284
+ raise _err("Encrypted file header is truncated.", "INVALID_REQUEST")
285
+ header = blob[:56 + meta_len]
286
+ meta = json.loads(utf8_dec(blob[56:56 + meta_len])) if meta_len else {}
287
+ if version != 2:
288
+ raise _err(f"This file was encrypted by a different version of the SDK (container v{version}).", "NOT_SUPPORTED")
289
+ if not count or not chunk_size:
290
+ raise _err("Encrypted file header is malformed.", "INVALID_PARAMETER")
291
+ if did != dek_id(dek):
292
+ raise _err("This file was encrypted under a previous data key for this record, so it can no longer be opened. "
293
+ "It was most likely left behind by an interrupted access change.", "ENCRYPTION_FILE_STALE_KEY")
294
+ header_hash = b64u(hashlib.sha256(header).digest())
295
+ key = _file_key(dek, file_id, ctx)
296
+ pos, out = 56 + meta_len, []
297
+ for i in range(count):
298
+ if pos + 4 > len(blob):
299
+ raise _err("Encrypted file is truncated.", "INVALID_REQUEST")
300
+ n = int.from_bytes(blob[pos:pos + 4], "big")
301
+ if pos + 4 + n > len(blob):
302
+ raise _err("Encrypted file is truncated.", "INVALID_REQUEST")
303
+ iv, ct = blob[pos + 4:pos + 16], blob[pos + 16:pos + 4 + n]
304
+ aad = utf8(json.dumps([f"{ENC_V}|binchunk", header_hash, i, count], separators=(",", ":")))
305
+ out.append(open_(key, iv, ct, aad))
306
+ pos += 4 + n
307
+ return b"".join(out)[:plain_len], meta
308
+
309
+
310
+ # ---- per-instance state -----------------------------------------------------------------------------
311
+
312
+ def parse_option(option: Any) -> Optional[Dict[str, Any]]:
313
+ if not option:
314
+ return None
315
+ if option is True:
316
+ option = {}
317
+ if not isinstance(option, dict):
318
+ raise _err('"options.encryption" should be a boolean or an object.', "INVALID_PARAMETER")
319
+ it = option.get("iterations", PBKDF2_ITERATIONS)
320
+ if isinstance(it, (int, float)) and not isinstance(it, bool) and it < 100000:
321
+ raise _err('"encryption.iterations" must be at least 100000.', "INVALID_PARAMETER")
322
+ table = option.get("table")
323
+ return {
324
+ "iterations": int(it) if isinstance(it, (int, float)) and not isinstance(it, bool) else PBKDF2_ITERATIONS,
325
+ "trustPolicy": "strict" if option.get("trustPolicy") == "strict" else "tofu",
326
+ "withheld": "sentinel" if option.get("withheld") == "sentinel" else "null",
327
+ "recovery": "none" if option.get("recovery") == "none" else "code",
328
+ "table": table if isinstance(table, str) and table else "__skapi__keyring",
329
+ }
330
+
331
+
332
+ class EncState:
333
+ def __init__(self, cfg: Dict[str, Any]):
334
+ self.cfg = cfg
335
+ self.clear()
336
+
337
+ def clear(self, keep_recovery: bool = False) -> None:
338
+ """Drops every key. keep_recovery is lock_encryption()'s: an encryption recovery code the app
339
+ has not collected yet can never be shown again, so a lock keeps it; a logout drops it."""
340
+ self.status = "locked"
341
+ self.reason = "NO_SESSION_KEY"
342
+ self.mk: Optional[bytes] = None
343
+ self.ik_priv = None
344
+ self.pub_raw: Optional[bytes] = None
345
+ self.fpr = ""
346
+ self.keyring_record_id = ""
347
+ self.user_id = ""
348
+ self.pins: Dict[str, str] = {}
349
+ self.peer_pub: Dict[str, Tuple[bytes, str]] = {}
350
+ self.deks: Dict[str, Dict[str, Any]] = {}
351
+ self.passthrough: Dict[str, Any] = {}
352
+ self.roll: set = set()
353
+ self.roll_key: Dict[str, bytes] = {} # the key a revoke minted ahead of its roll (see _enc_drop_and_roll)
354
+ if not keep_recovery:
355
+ self.pending_recovery_code: Optional[str] = None
356
+ self.pending_recovery_user = ""
357
+
358
+
359
+ class EncryptionMixin:
360
+ """Mixed into Skapi. self._enc is None when the instance has encryption off."""
361
+
362
+ _enc: Optional[EncState] = None
363
+
364
+ # ---- strings ---------------------------------------------------------------------------------
365
+
366
+ def _e_s(self, kind: str, user: str) -> str:
367
+ return f"{ENC_V}|{kind}|{self.service}|{self.owner}|{user}"
368
+
369
+ def _payload_aad(self, own: str, anch: str, anchor: str) -> bytes:
370
+ return utf8(json.dumps([ENC_V, self.service, self.owner, own, anch, anchor], separators=(",", ":"), ensure_ascii=False))
371
+
372
+ @staticmethod
373
+ def _recipient_aad(payload_aad: bytes, recipient: str, bind: str) -> bytes:
374
+ return payload_aad + b"\x00" + utf8(recipient) + b"\x00" + utf8(bind)
375
+
376
+ def _wrap_info(self, anchor: str, own: str, recipient: str, fpr: str) -> str:
377
+ return f"{ENC_V}|dekwrap|{self.service}|{self.owner}|{anchor}|{own}|{recipient}|{fpr}"
378
+
379
+ @staticmethod
380
+ def _anchor_of(env: Dict[str, Any]) -> str:
381
+ return env.get("uid", "") if env.get("anch") == "uid" else env.get("rid", "") if env.get("anch") == "rid" else ""
382
+
383
+ def _me(self) -> str:
384
+ return (self._user or {}).get("user_id", "")
385
+
386
+ # ---- keyring -----------------------------------------------------------------------------------
387
+
388
+ def _find_keyring(self, uid: str) -> Optional[Dict[str, Any]]:
389
+ res = self.get_records({"table": {"name": self._enc.cfg["table"], "access_group": "private"},
390
+ "index": {"name": "$user_id", "value": uid, "condition": "="}}, {"limit": 2})
391
+ rows = sorted((r for r in res.get("list", []) if r.get("user_id") == uid), key=lambda r: r.get("uploaded", 0))
392
+ return rows[0] if rows else None
393
+
394
+ def _password_wrap(self, mk: bytes, password: str, uid: str) -> Dict[str, Any]:
395
+ it = self._enc.cfg["iterations"]
396
+ salt = os.urandom(16)
397
+ s = b64u(salt)
398
+ kek = password_kek(password, salt, it, self._e_s("kek", uid))
399
+ sealed = seal(kek, mk, utf8(f"{self._e_s('mk', uid)}|PBKDF2-SHA256|{it}|{s}"))
400
+ return {"id": b64u(os.urandom(6)), "p": "password", "kdf": {"a": "PBKDF2-SHA256", "it": it, "s": s}, **sealed, "created": int(time.time() * 1000)}
401
+
402
+ def _recovery_wrap(self, mk: bytes, uid: str) -> Tuple[Dict[str, Any], str]:
403
+ raw = os.urandom(16)
404
+ salt = os.urandom(16)
405
+ s = b64u(salt)
406
+ rk = hkdf(raw, salt, self._e_s("recovery", uid))
407
+ sealed = seal(rk, mk, utf8(f"{self._e_s('rk', uid)}|HKDF-SHA256|{s}"))
408
+ return {"id": b64u(os.urandom(6)), "p": "recovery", "kdf": {"a": "HKDF-SHA256", "s": s}, **sealed, "created": int(time.time() * 1000)}, encode_recovery_code(raw)
409
+
410
+ def _open_with_password(self, data: Dict[str, Any], password: str, uid: str) -> Optional[bytes]:
411
+ wraps = sorted((w for w in data.get("wraps", []) if isinstance(w, dict) and w.get("p") == "password"), key=lambda w: w.get("created", 0), reverse=True)
412
+ if not wraps:
413
+ raise _err("The keyring has no password wrap.", "ENCRYPTION_KEYRING_CORRUPT")
414
+ for w in wraps:
415
+ try:
416
+ kdf = w["kdf"]
417
+ kek = password_kek(password, b64u_dec(kdf["s"]), kdf["it"], self._e_s("kek", uid))
418
+ return open_(kek, b64u_dec(w["iv"]), b64u_dec(w["ct"]), utf8(f"{self._e_s('mk', uid)}|PBKDF2-SHA256|{kdf['it']}|{kdf['s']}"))
419
+ except SkapiError:
420
+ raise
421
+ except Exception:
422
+ continue
423
+ return None
424
+
425
+ def _adopt_keyring(self, keyring: Dict[str, Any], mk: bytes, uid: str) -> None:
426
+ s, data = self._enc, keyring["data"]
427
+ pkcs8 = open_(mk, b64u_dec(data["ik"]["iv"]), b64u_dec(data["ik"]["ct"]), utf8(self._e_s("ik", uid)))
428
+ pins: Dict[str, str] = {}
429
+ if isinstance(data.get("pins"), dict) and data["pins"].get("ct"):
430
+ try:
431
+ pins = json.loads(utf8_dec(open_(mk, b64u_dec(data["pins"]["iv"]), b64u_dec(data["pins"]["ct"]),
432
+ utf8(f"{ENC_V}|pins|{self.service}/{self.owner}|{uid}"))))
433
+ except Exception:
434
+ pins = {}
435
+ s.mk, s.ik_priv = mk, load_pkcs8(pkcs8)
436
+ s.pub_raw, s.fpr = b64u_dec(data["pub"]), data.get("fpr", "")
437
+ s.keyring_record_id, s.user_id = keyring["record_id"], uid
438
+ s.pins = pins if isinstance(pins, dict) else {}
439
+ s.status, s.reason = "unlocked", ""
440
+ try:
441
+ self._repair_public_key(uid)
442
+ except Exception as err: # best effort: it never fails the unlock
443
+ warnings.warn(f"skapi encryption: the public key directory could not be checked: {err}", RuntimeWarning, stacklevel=3)
444
+
445
+ def _repair_public_key(self, uid: str) -> None:
446
+ """
447
+ Puts this keyring's public key back on top of the public key directory when a stray row is
448
+ there instead. Two devices logging in for the first time at once could leave the losing
449
+ keyring's public row behind, and it is the NEWEST row, the one peers read, so they wrapped
450
+ data keys to a key nobody holds. When the newest row does not carry this keyring's key, and
451
+ this session proves it holds the private half, the key is published again and the rows that
452
+ do not match it are removed. As skapi-js repairPublicKey.
453
+ """
454
+ s = self._enc
455
+ pub_raw, ik_priv = s.pub_raw, s.ik_priv
456
+ if not uid or not pub_raw or ik_priv is None:
457
+ return
458
+ res = self.get_records({"table": {"name": s.cfg["table"], "access_group": "authorized"},
459
+ "index": {"name": "$user_id", "value": uid, "condition": "="}}, {"limit": 10})
460
+ rows = sorted((r for r in res.get("list", []) if r.get("user_id") == uid and isinstance(r.get("data"), dict) and r["data"].get("pub")),
461
+ key=lambda r: r.get("uploaded", 0), reverse=True)
462
+ if not rows:
463
+ return
464
+ mine = fingerprint(pub_raw)
465
+
466
+ def fpr_of(r):
467
+ try:
468
+ return fingerprint(b64u_dec(r["data"]["pub"]))
469
+ except Exception:
470
+ return ""
471
+ if fpr_of(rows[0]) == mine:
472
+ return
473
+ # the key about to be published must open what is sealed to it with this session's private key
474
+ probe = os.urandom(32)
475
+ label = utf8(f"{ENC_V}|pubcheck|{uid}")
476
+ try:
477
+ holds = ecdh_unwrap(ik_priv, ecdh_wrap(probe, pub_raw, label.decode("utf-8"), label), label.decode("utf-8"), label) == probe
478
+ except Exception:
479
+ holds = False
480
+ if not holds:
481
+ return
482
+ stray = [r["record_id"] for r in rows if fpr_of(r) != mine and r.get("record_id")]
483
+ if s.user_id != uid or self._me() != uid:
484
+ return # a lock, logout or another user's login since the unlock: leave it
485
+ self.post_record({"v": 1, "alg": "ECDH-P-256", "user_id": uid, "pub": b64u(pub_raw), "fpr": mine, "created": int(time.time() * 1000)},
486
+ {"table": {"name": s.cfg["table"], "access_group": "authorized"}, "index": {"name": "pubkey", "value": uid}})
487
+ if stray and s.user_id == uid and self._me() == uid:
488
+ self.delete_records({"record_id": stray})
489
+
490
+ def _unlock_keyring(self, keyring: Dict[str, Any], password: str, uid: str) -> None:
491
+ data = keyring.get("data") or {}
492
+ if keyring.get("user_id") != uid or (data.get("user_id") and data.get("user_id") != uid):
493
+ raise _err("The encryption keyring does not belong to this user.", "ENCRYPTION_KEYRING_CORRUPT")
494
+ mk = self._open_with_password(data, password, uid)
495
+ if mk is None:
496
+ raise _err("Incorrect password: the encryption keyring could not be opened.", "ENCRYPTION_BAD_PASSWORD")
497
+ self._adopt_keyring(keyring, mk, uid)
498
+
499
+ def _provision_keyring(self, password: str, uid: str) -> None:
500
+ s = self._enc
501
+ mk = os.urandom(32)
502
+ priv, pub, pkcs8 = new_identity()
503
+ fpr = fingerprint(pub)
504
+ wraps = [self._password_wrap(mk, password, uid)]
505
+ code = None
506
+ if s.cfg["recovery"] == "code":
507
+ w, code = self._recovery_wrap(mk, uid)
508
+ wraps.append(w)
509
+ now = int(time.time() * 1000)
510
+ data = {"v": 1, "alg": "ECDH-P-256", "user_id": uid, "wraps": wraps, "ik": seal(mk, pkcs8, utf8(self._e_s("ik", uid))),
511
+ "self": seal(mk, mk, utf8(self._e_s("self", uid))), "pub": b64u(pub), "fpr": fpr, "pins": None, "created": now, "updated": now}
512
+ table = s.cfg["table"]
513
+ pub_rec = self.post_record({"v": 1, "alg": "ECDH-P-256", "user_id": uid, "pub": b64u(pub), "fpr": fpr, "created": now},
514
+ {"table": {"name": table, "access_group": "authorized"}, "index": {"name": "pubkey", "value": uid}})
515
+ rec = self.post_record(data, {"table": {"name": table, "access_group": "private"}})
516
+ oldest = self._find_keyring(uid)
517
+ if oldest and oldest.get("record_id") != rec.get("record_id"):
518
+ # another device enrolled first: its keyring wins. This device's public key and keyring
519
+ # go (best effort), or peers would read this newer public key and wrap for a key nobody holds.
520
+ try:
521
+ self.delete_records({"record_id": [r for r in (pub_rec.get("record_id"), rec.get("record_id")) if r]})
522
+ except Exception as err:
523
+ warnings.warn(f"skapi encryption: this device's unused public key and keyring could not be removed: {err}", RuntimeWarning, stacklevel=3)
524
+ self._unlock_keyring(oldest, password, uid) # adopt the keyring of the device that enrolled first
525
+ return
526
+ self._adopt_keyring(dict(rec, data=data), mk, uid)
527
+ s.pending_recovery_code, s.pending_recovery_user = code, uid
528
+ s.pins = {}
529
+
530
+ def _ensure_keyring(self, password: str, create: bool = True) -> None:
531
+ """Open the keyring with the password, or create it when there is none. Creating is for
532
+ login only (the default), where the password was just proven. unlock_encryption() passes
533
+ create=False: a session restored from tokens proved no password, so creating a keyring
534
+ there would seal the data under whatever was typed. As in skapi-js."""
535
+ s = self._enc
536
+ if s is None or not self._user:
537
+ return
538
+ _lib()
539
+ if self._user.get("is_openid"):
540
+ s.status, s.reason = "locked", "OPENID_UNSUPPORTED"
541
+ return
542
+ uid = self._me()
543
+ keyring = self._find_keyring(uid)
544
+ if keyring:
545
+ self._unlock_keyring(keyring, password, uid)
546
+ elif not create:
547
+ raise _err("Encryption has not been set up for this account yet. It is set up at the first login with the password: "
548
+ "log in with the password to start using it.", "NOT_EXISTS")
549
+ else:
550
+ self._provision_keyring(password, uid)
551
+
552
+ def _enc_after_login(self, password: Optional[str]) -> None:
553
+ """Called after every password sign-in. Never fails the login."""
554
+ if self._enc is None or not password:
555
+ return
556
+ self._enc.clear() # a previous user's keys never carry over
557
+ try:
558
+ self._ensure_keyring(password)
559
+ except Exception as err:
560
+ warnings.warn(f"skapi encryption could not be unlocked at login: {err}", RuntimeWarning, stacklevel=3)
561
+
562
+ def _enc_clear(self) -> None:
563
+ if self._enc is not None:
564
+ self._enc.clear()
565
+
566
+ def _enc_rewrap_password(self, current: str, new: str) -> Optional[Dict[str, Any]]:
567
+ s = self._enc
568
+ if s is None:
569
+ return None
570
+ if s.status != "unlocked" or not s.mk:
571
+ raise _err("Encryption must be unlocked before changing the password, or the encryption keyring would be left "
572
+ "wrapped under a password that no longer exists. Call unlock_encryption(password) first.", "ENCRYPTION_LOCKED")
573
+ res = self.get_records({"record_id": s.keyring_record_id}, {"limit": 1})
574
+ if not res.get("list"):
575
+ raise _err("The encryption keyring could not be read, so the password change was stopped before it could strand it.", "ENCRYPTION_KEYRING_CORRUPT")
576
+ keyring = res["list"][0]
577
+ uid = self._me()
578
+ mk = self._open_with_password(keyring["data"], current, uid)
579
+ if mk is None:
580
+ raise _err("Incorrect current password: the encryption keyring was not re-wrapped.", "ENCRYPTION_BAD_PASSWORD")
581
+ data = dict(keyring["data"])
582
+ data["wraps"] = list(data.get("wraps", [])) + [self._password_wrap(mk, new, uid)]
583
+ data["updated"] = int(time.time() * 1000)
584
+ self.post_record(data, {"record_id": s.keyring_record_id})
585
+ return data
586
+
587
+ def _enc_prune_wraps(self) -> None:
588
+ s = self._enc
589
+ if s is None or s.status != "unlocked":
590
+ return
591
+ try:
592
+ keyring = self.get_records({"record_id": s.keyring_record_id}, {"limit": 1})["list"][0]
593
+ data = dict(keyring["data"])
594
+ pw = sorted((w for w in data.get("wraps", []) if w.get("p") == "password"), key=lambda w: w.get("created", 0), reverse=True)
595
+ if len(pw) > 1:
596
+ data["wraps"] = [pw[0]] + [w for w in data["wraps"] if w.get("p") != "password"]
597
+ data["updated"] = int(time.time() * 1000)
598
+ self.post_record(data, {"record_id": s.keyring_record_id})
599
+ except Exception as err:
600
+ warnings.warn(f"skapi encryption: old password wrap not pruned: {err}", RuntimeWarning, stacklevel=2)
601
+
602
+ # ---- peers ------------------------------------------------------------------------------------
603
+
604
+ def _peer_keys(self, ids: List[str]) -> Dict[str, Optional[Tuple[bytes, str]]]:
605
+ s = self._enc
606
+ out: Dict[str, Optional[Tuple[bytes, str]]] = {}
607
+ pinned_new = False
608
+ for uid in ids:
609
+ if uid in s.peer_pub:
610
+ out[uid] = s.peer_pub[uid]
611
+ continue
612
+ res = self.get_records({"table": {"name": s.cfg["table"], "access_group": "authorized"},
613
+ "index": {"name": "$user_id", "value": uid, "condition": "="}}, {"limit": 10})
614
+ rows = sorted((r for r in res.get("list", []) if r.get("user_id") == uid and isinstance(r.get("data"), dict) and r["data"].get("pub")),
615
+ key=lambda r: r.get("uploaded", 0), reverse=True)
616
+ if not rows:
617
+ out[uid] = None
618
+ continue
619
+ pub = b64u_dec(rows[0]["data"]["pub"])
620
+ fpr = fingerprint(pub)
621
+ if uid in s.pins and s.pins[uid] != fpr:
622
+ raise _err(f'The public key for user "{uid}" has changed since it was first seen. '
623
+ "This is expected if they reset their account, and is what a key substitution attack also looks like. "
624
+ "Verify the new fingerprint out of band, then call pin_peer_key(user_id, fingerprint).", "ENCRYPTION_PEER_KEY_CHANGED")
625
+ if uid not in s.pins:
626
+ if s.cfg["trustPolicy"] == "strict":
627
+ raise _err(f'No pinned key for user "{uid}" and trustPolicy is "strict". Pin it first with pin_peer_key().', "ENCRYPTION_PEER_NOT_PINNED")
628
+ s.pins[uid] = fpr
629
+ pinned_new = True
630
+ s.peer_pub[uid] = (pub, fpr)
631
+ out[uid] = (pub, fpr)
632
+ if pinned_new:
633
+ try:
634
+ self._persist_pins()
635
+ except Exception:
636
+ pass
637
+ return out
638
+
639
+ def _persist_pins(self) -> None:
640
+ s = self._enc
641
+ if not s.mk or not s.keyring_record_id:
642
+ return
643
+ keyring = self.get_records({"record_id": s.keyring_record_id}, {"limit": 1})["list"][0]
644
+ data = dict(keyring["data"])
645
+ data["pins"] = seal(s.mk, utf8(_js_json(s.pins)), utf8(f"{ENC_V}|pins|{self.service}/{self.owner}|{s.user_id}"))
646
+ data["updated"] = int(time.time() * 1000)
647
+ self.post_record(data, {"record_id": s.keyring_record_id})
648
+
649
+ # ---- write ---------------------------------------------------------------------------------------
650
+
651
+ def _write_group(self, view: Dict[str, Any], has_data: bool) -> Tuple[Any, Any, Optional[Dict[str, Any]]]:
652
+ """(access group the write lands on, table name, the record if it had to be read)."""
653
+ table = view.get("table")
654
+ name = table if isinstance(table, str) else (table or {}).get("name") if isinstance(table, dict) else None
655
+
656
+ def norm(g):
657
+ if g in ("private", "*", "**"):
658
+ return "private"
659
+ return {"public": 0, "authorized": 1, "admin": 99}.get(g, g if isinstance(g, (int, float)) else 0)
660
+ if isinstance(table, str):
661
+ return 0, name, None
662
+ if isinstance(table, dict) and "access_group" in table:
663
+ return norm(table["access_group"]), name, None
664
+ rid = view.get("record_id")
665
+ if not rid:
666
+ return 0, name, None
667
+ # The cached data key says only what the group was when this session last saw the record;
668
+ # another device may have made it non-private since, and sealing a payload into a
669
+ # non-private record strands it. So the cache is trusted only for a write with no data,
670
+ # where both answers write nothing (as skapi-js resolveWriteGroup).
671
+ if rid in self._enc.deks and not has_data:
672
+ return self._enc.deks[rid].get("access_group", "private"), name, None
673
+ current = self._read_own_record(rid)
674
+ if current is None:
675
+ raise _err(f'Record "{rid}" not found.', "NOT_EXISTS")
676
+ return current["table"]["access_group"], current["table"]["name"], current
677
+
678
+ def _read_own_record(self, rid: str) -> Optional[Dict[str, Any]]:
679
+ import re
680
+ q = {"record_id": rid} if re.match(r"^[a-zA-Z0-9]+$", rid) else {"unique_id": rid}
681
+ res = self.get_records(q, {"limit": 1})
682
+ return res["list"][0] if res.get("list") else None
683
+
684
+ def _owner_check(self, current: Optional[Dict[str, Any]], rid: str, what: str) -> None:
685
+ if current and current.get("encrypted") and current.get("user_id") != self._me():
686
+ raise _err(f'Record "{rid}" belongs to another user ({current.get("user_id")}), so {what} would either seal it '
687
+ "under the wrong key or strand its contents. Encryption only operates on records you own, "
688
+ "no matter what access level you hold.", "ENCRYPTION_NOT_RECORD_OWNER")
689
+
690
+ def _maybe_encrypt(self, value: Any, view: Dict[str, Any], has_data: bool) -> Dict[str, Any]:
691
+ s = self._enc
692
+ if s is None:
693
+ return {"send": value, "omit": not has_data}
694
+ raw_id = view.get("record_id") or ""
695
+ if raw_id and raw_id in s.passthrough:
696
+ return {"send": s.passthrough.pop(raw_id), "encrypted": True}
697
+ group, table_name, record = self._write_group(view, has_data)
698
+ if group != "private":
699
+ files = None
700
+ current = record
701
+ if raw_id and current is None:
702
+ try:
703
+ current = self._read_own_record(raw_id)
704
+ except SkapiError:
705
+ current = None
706
+ if current is not None and current.get("encrypted"):
707
+ self._owner_check(current, raw_id, "making it non-private")
708
+ if not has_data:
709
+ if current["encrypted"].get("status") == "failed":
710
+ raise _err(f'Cannot make record "{raw_id}" non-private: its current contents could not be decrypted '
711
+ f'({current["encrypted"].get("reason")}), so they cannot be written back in the clear. '
712
+ "Unlock encryption, or supply the record's data with the access group change.", "ENCRYPTION_LOCKED")
713
+ value, has_data = current.get("data"), True
714
+ if current is not None and any(b.get("encrypted") for entries in (current.get("bin") or {}).values() for b in entries):
715
+ files = "decrypt"
716
+ elif current is not None:
717
+ s.deks.pop(current.get("record_id"), None)
718
+ return {"send": value, "omit": not has_data, "files": files}
719
+ if table_name == s.cfg["table"]:
720
+ return {"send": value, "omit": not has_data} # the keyring itself is never sealed
721
+ if not has_data:
722
+ return {"omit": True}
723
+ if isinstance(value, dict) and value.get(WITHHELD) is True:
724
+ raise _err("This record's data could not be decrypted by this session, so it cannot be written back. "
725
+ "Writing it would replace the record with the placeholder.", "ENCRYPTION_CANNOT_REWRITE_WITHHELD")
726
+ if s.status != "unlocked":
727
+ raise _err("Encryption is enabled but locked, so this private record cannot be written. "
728
+ "Call unlock_encryption(password) first, or the user must log in with their password.", "ENCRYPTION_LOCKED")
729
+ if isinstance(value, dict) and ENV_MARKER in value:
730
+ raise _err('"__skapi_enc__" is a reserved key in record data.', "INVALID_PARAMETER")
731
+ if (view.get("service") and view["service"] != self.service) or (view.get("owner") and view["owner"] != self.owner):
732
+ raise _err("Encrypted records cannot be written to another project. The encryption key is derived per project, "
733
+ "so a record written under one service and read under another could never be decrypted. "
734
+ "Construct a separate Skapi instance for that project.", "INVALID_REQUEST")
735
+ me = self._me()
736
+ if not me:
737
+ raise _err("User login is required to write an encrypted record.", "INVALID_REQUEST")
738
+ rolling = False
739
+ roll_key: Optional[bytes] = None
740
+ prior_ct: List[str] = []
741
+ if raw_id and raw_id in s.roll:
742
+ s.roll.discard(raw_id)
743
+ roll_key = s.roll_key.pop(raw_id, None)
744
+ stale = s.deks.pop(raw_id, None) or {}
745
+ prior_ct = [u for u in [stale.get("ct_url")] + list(stale.get("ct_stale") or []) if u]
746
+ rolling = True
747
+ files = None
748
+ entry = self._dek_if_current(raw_id) if raw_id else None
749
+ resolved_id = ""
750
+ uid = view.get("unique_id") or ""
751
+ current = None
752
+ if raw_id and entry is None:
753
+ try:
754
+ current = self._read_own_record(raw_id)
755
+ except SkapiError:
756
+ current = None
757
+ self._owner_check(current, raw_id, "updating it")
758
+ if current is not None:
759
+ if not current.get("encrypted") and any(not b.get("encrypted") for entries in (current.get("bin") or {}).values() for b in entries):
760
+ files = "encrypt"
761
+ resolved_id = current.get("record_id", "")
762
+ uid = uid or current.get("unique_id") or ""
763
+ if current.get("encrypted", {}).get("status") == "failed":
764
+ raise _err(f'Cannot update encrypted record "{raw_id}": its current contents could not be decrypted ({current["encrypted"].get("reason")}), '
765
+ "so its existing key wraps cannot be preserved. Updating anyway would revoke everyone it is shared with.", "ENCRYPTION_LOCKED")
766
+ if not rolling:
767
+ entry = s.deks.get(resolved_id)
768
+ if entry:
769
+ if entry.get("rid"):
770
+ resolved_id = entry["rid"]
771
+ if entry.get("anch") == "uid":
772
+ uid = entry.get("uid") or uid
773
+ if entry.get("own") != me:
774
+ raise _err(f'Record "{raw_id}" belongs to another user ({entry.get("own")}). Encryption only operates on records you own.', "ENCRYPTION_NOT_RECORD_OWNER")
775
+ elif raw_id and not resolved_id and not rolling:
776
+ resolved_id = raw_id
777
+ dek = entry["bytes"] if entry else (roll_key or os.urandom(32))
778
+ recipients = dict(entry["recipients"]) if entry else {}
779
+ anch = "uid" if uid else ("rid" if resolved_id else "new")
780
+ anchor = uid if anch == "uid" else resolved_id if anch == "rid" else ""
781
+ aad = self._payload_aad(me, anch, anchor)
782
+ recipients[me] = {"t": "mk", **seal(s.mk, dek, self._recipient_aad(aad, me, "mk"))}
783
+ if entry and (entry.get("anch") != anch or self._anchor_of(entry) != anchor):
784
+ recipients = self._rewrap_all(dek, recipients, me, anch, anchor, aad)
785
+ iv, ct = seal_raw(dek, utf8(_js_json(value)), aad)
786
+ env = {ENV_MARKER: 1, "enc": "A256GCM", "kw": "ECDH-ES+A256GCM", "anch": anch, "uid": uid, "rid": resolved_id, "own": me,
787
+ "iv": b64u(iv), "ct": b64u(ct), "k": recipients}
788
+ spill, retire = None, None
789
+ if resolved_id and len(env["ct"]) > SPILL_LIMIT:
790
+ spill, env["ct"], env["ct_ref"] = ct, "", CT_FILE_SUFFIX
791
+ if resolved_id:
792
+ # the stored payload files' real urls (never the bare ct_ref suffix, which the server refuses),
793
+ # retired whether the new data spills again or now fits inline
794
+ old = [(entry or {}).get("ct_url")] + list((entry or {}).get("ct_stale") or []) + prior_ct
795
+ retire = list(dict.fromkeys(u for u in old if u)) or None
796
+ env_size = len(json.dumps(env, separators=(",", ":")))
797
+ if env_size > ENVELOPE_CAP:
798
+ raise _err(f"Encrypted record data is too large: once encrypted and base64 encoded it becomes {env_size} bytes, "
799
+ f"over the {ENVELOPE_CAP} byte limit. Encryption costs about 33% plus roughly 230 bytes per additional recipient.", "ENCRYPTED_DATA_TOO_LARGE")
800
+ if resolved_id:
801
+ self._cache_dek(resolved_id, dek, recipients, anch, uid, me)
802
+ dek_entry = {"bytes": dek, "recipients": dict(recipients), "anch": anch, "uid": uid, "own": me, "access_group": "private"}
803
+ return {"send": env, "plain": value, "encrypted": True, "dek": dek_entry, "spill": spill, "retire": retire, "files": files,
804
+ "recipients": list(recipients)}
805
+
806
+ def _dek_if_current(self, key: str) -> Optional[Dict[str, Any]]:
807
+ """A record's cached data key, only while the stored envelope still carries the key wraps it
808
+ was cached with. Another session of the owner may have rolled the key or changed who it is
809
+ wrapped for since; then the cached key is forgotten (None) and the caller reads the record again."""
810
+ s = self._enc
811
+ entry = s.deks.get(key)
812
+ if not entry:
813
+ return None
814
+ rid = entry.get("rid") or key
815
+ stored = self._read_stored_envelope(rid)
816
+ if stored is not None and stored.get("k") == entry.get("recipients"):
817
+ return entry
818
+ s.deks.pop(key, None)
819
+ s.deks.pop(rid, None)
820
+ return None
821
+
822
+ def _bind_record_dek(self, record_id: str, dek_entry: Optional[Dict[str, Any]]) -> None:
823
+ """A just-created record's key, under the record_id the server minted."""
824
+ s = self._enc
825
+ if s is None or not dek_entry or not record_id or record_id in s.deks:
826
+ return
827
+ s.deks[record_id] = dict(dek_entry, rid=record_id)
828
+
829
+ def _convert_record_files(self, record_id: str, direction: str) -> List[str]:
830
+ """Re-uploads a record's attachments sealed ('encrypt') or in the clear ('decrypt'); returns the urls to retire."""
831
+ s = self._enc
832
+ if s is None:
833
+ return []
834
+ rec = self._read_own_record(record_id)
835
+ if not rec:
836
+ return []
837
+ want_sealed = direction == "decrypt"
838
+ targets = [(form_key, f) for form_key, entries in (rec.get("bin") or {}).items() for f in entries if bool(f.get("encrypted")) == want_sealed]
839
+ if not targets:
840
+ return []
841
+ import mimetypes
842
+ from urllib.parse import urlsplit
843
+ uploads, retire = [], []
844
+ for form_key, f in targets:
845
+ content = self.get_file(f["url"], {"dataType": "bytes", "_raw": True})
846
+ content_type = None
847
+ if want_sealed:
848
+ content, meta = self._decrypt_file_for(f["url"], content)
849
+ content_type = meta.get("t") or "application/octet-stream"
850
+ uploads.append({"name": form_key, "filename": f["filename"], "content": content,
851
+ "content_type": content_type or mimetypes.guess_type(f["filename"])[0] or "application/octet-stream"})
852
+ u = urlsplit(f["url"])
853
+ retire.append(f"{u.scheme}://{u.netloc}/{f['path']}")
854
+ # The key leaves the cache for the upload (or the upload would seal the files again), but
855
+ # comes back if anything fails: all or nothing, as in skapi-js. A failed conversion removes
856
+ # the copies that did upload and refuses the write, so the record and its files stay as they were.
857
+ held = s.deks.pop(record_id, None) if want_sealed else None
858
+ try:
859
+ result = self._upload_prepared(uploads, record_id)
860
+ except Exception:
861
+ if held is not None:
862
+ s.deks[record_id] = held
863
+ raise
864
+ if result["failed"]:
865
+ if held is not None:
866
+ s.deks[record_id] = held
867
+ landed = [u for u in result.get("landed") or [] if u]
868
+ if landed:
869
+ try:
870
+ self._remove_landed_copies(record_id, landed)
871
+ except Exception as err:
872
+ warnings.warn(f"skapi: could not remove the partly converted copies: {err}", RuntimeWarning, stacklevel=2)
873
+ first = result["errors"][0]["error"]
874
+ raise _err(f"The record's attached files could not all be converted, so the record was not changed: {first}",
875
+ getattr(first, "code", None) or "ERROR")
876
+ return retire
877
+
878
+ def _remove_landed_copies(self, record_id: str, urls: List[str]) -> None:
879
+ """A record file joins the record's file list a moment after its upload, and removing an address
880
+ the list does not hold yet does nothing, so wait for them to appear, then remove them in one write."""
881
+ import time as _time
882
+ from urllib.parse import unquote
883
+ bare = lambda u: unquote(u.split("?")[0])
884
+ want = {bare(u) for u in urls}
885
+ for attempt in range(8):
886
+ rec = self._read_own_record(record_id) or {}
887
+ have = {bare(f.get("url") or "") for entries in (rec.get("bin") or {}).values() for f in entries}
888
+ if want <= have:
889
+ break
890
+ _time.sleep(0.5 * (attempt + 1))
891
+ self.post_record(config={"record_id": record_id, "remove_bin": urls})
892
+
893
+ def _rewrap_all(self, dek: bytes, recipients: Dict[str, Any], me: str, anch: str, anchor: str, aad: bytes) -> Dict[str, Any]:
894
+ out = {me: recipients[me]}
895
+ others = [u for u in recipients if u != me]
896
+ keys = self._peer_keys(others) if others else {}
897
+ for u in others:
898
+ k = keys.get(u)
899
+ if not k:
900
+ continue # as in skapi-js: a grantee whose key cannot be found is dropped
901
+ out[u] = {"t": "ecdh", **ecdh_wrap(dek, k[0], self._wrap_info(anchor, me, u, k[1]), self._recipient_aad(aad, u, k[1])), "fpr": k[1]}
902
+ return out
903
+
904
+ def _cache_dek(self, rid: str, dek: bytes, recipients: Dict[str, Any], anch: str, uid: str, own: str, ct_url: str = "",
905
+ ct_stale: Optional[List[str]] = None) -> None:
906
+ entry = self._enc.deks.get(rid)
907
+ if entry is None:
908
+ entry = {}
909
+ self._enc.deks[rid] = entry
910
+ entry.update({"bytes": dek, "recipients": dict(recipients), "anch": anch, "uid": uid, "rid": rid, "own": own, "access_group": "private"})
911
+ if ct_url:
912
+ entry["ct_url"] = ct_url
913
+ entry["ct_stale"] = list(ct_stale or [])
914
+
915
+ # ---- read ----------------------------------------------------------------------------------------
916
+
917
+ def _maybe_decrypt(self, raw: Any, ctx: Dict[str, Any]) -> Tuple[Any, Optional[Dict[str, Any]]]:
918
+ """(value, flag). Never raises."""
919
+ if not is_envelope(raw) or ctx.get("access_group") != "private":
920
+ return raw, None
921
+ s = self._enc
922
+ if s is None:
923
+ return None, {"status": "failed", "reason": "ENCRYPTION_DISABLED"}
924
+ if ctx.get("table_name") == s.cfg["table"]:
925
+ return raw, None
926
+
927
+ def fail(reason, recipients=None):
928
+ flag = {"status": "failed", "reason": reason}
929
+ if recipients is not None:
930
+ flag["recipients"] = recipients
931
+ if s.cfg["withheld"] == "sentinel":
932
+ v = {WITHHELD: True, "reason": reason}
933
+ if reason == "NOT_A_RECIPIENT":
934
+ v["recipients"] = recipients
935
+ return v, flag
936
+ return None, flag
937
+
938
+ if raw.get(ENV_MARKER) != 1:
939
+ return fail("UNSUPPORTED_VERSION")
940
+ if raw["own"] != ctx.get("user_id") or (raw.get("uid") and ctx.get("unique_id") and raw["uid"] != ctx["unique_id"]) \
941
+ or (raw.get("rid") and ctx.get("record_id") and raw["rid"] != ctx["record_id"]):
942
+ return fail("BINDING_MISMATCH")
943
+ me = self._me()
944
+ wrap = raw["k"].get(me)
945
+ if not wrap:
946
+ return fail("NOT_A_RECIPIENT", list(raw["k"]))
947
+ if s.status != "unlocked":
948
+ return fail("NO_SESSION_KEY")
949
+ anchor = self._anchor_of(raw)
950
+ aad = self._payload_aad(raw["own"], raw["anch"], anchor)
951
+ try:
952
+ if wrap.get("t") == "mk":
953
+ dek = open_(s.mk, b64u_dec(wrap["iv"]), b64u_dec(wrap["ct"]), self._recipient_aad(aad, me, "mk"))
954
+ elif wrap.get("t") == "ecdh":
955
+ if s.ik_priv is None:
956
+ return fail("NO_SESSION_KEY")
957
+ dek = ecdh_unwrap(s.ik_priv, wrap, self._wrap_info(anchor, raw["own"], me, wrap.get("fpr", "")), self._recipient_aad(aad, me, wrap.get("fpr", "")))
958
+ else:
959
+ return fail("UNSUPPORTED_VERSION")
960
+ except Exception:
961
+ return fail("BAD_KEY")
962
+ ct_used, ct_stale = "", []
963
+ if raw.get("ct_ref"):
964
+ # newest payload file first (see _database.py); older SDKs could leave several, so the first one
965
+ # that passes the GCM tag check is the current one, and the rest are retired on the next update
966
+ candidates = list(ctx.get("ct_urls") or ([ctx["ct_url"]] if ctx.get("ct_url") else []))
967
+ fetched, value = False, None
968
+ for url in candidates:
969
+ try:
970
+ ct = self.get_file(url, {"dataType": "bytes"})
971
+ fetched = True
972
+ except Exception:
973
+ continue
974
+ try:
975
+ value = json.loads(utf8_dec(open_(dek, b64u_dec(raw["iv"]), ct, aad)))
976
+ ct_used = url
977
+ break
978
+ except Exception:
979
+ continue
980
+ if not ct_used:
981
+ return fail("CORRUPT" if fetched else "DATA_UNAVAILABLE")
982
+ ct_stale = [u for u in candidates if u != ct_used]
983
+ else:
984
+ try:
985
+ ct = b64u_dec(raw["ct"])
986
+ except Exception:
987
+ return fail("DATA_UNAVAILABLE")
988
+ try:
989
+ value = json.loads(utf8_dec(open_(dek, b64u_dec(raw["iv"]), ct, aad)))
990
+ except Exception:
991
+ return fail("CORRUPT")
992
+ if ctx.get("record_id"):
993
+ self._cache_dek(ctx["record_id"], dek, raw["k"], raw["anch"], raw.get("uid", ""), raw["own"], ct_used, ct_stale)
994
+ return value, {"status": "encrypted", "recipients": list(raw["k"])}
995
+
996
+ # ---- files ---------------------------------------------------------------------------------------
997
+
998
+ def _maybe_encrypt_file(self, record_id: str, entry: Dict[str, Any]) -> Dict[str, Any]:
999
+ s = self._enc
1000
+ if s is None or entry["name"] == CT_KEY:
1001
+ return {k: v for k, v in entry.items() if k != "_presealed"}
1002
+ if entry.get("_presealed"):
1003
+ # already sealed by a revoke, under the key its roll is about to install
1004
+ return {k: v for k, v in entry.items() if k != "_presealed"}
1005
+ if FILE_MARKER in entry["name"]:
1006
+ raise _err('"__skenc__" is reserved in an upload form key.', "INVALID_PARAMETER")
1007
+ dek_entry = s.deks.get(record_id)
1008
+ if not dek_entry:
1009
+ return entry # as in skapi-js: without the record's key cached, the file goes up as is
1010
+ container = encrypt_file(dek_entry["bytes"], {"service": self.service, "owner": self.owner, "recordOwner": dek_entry["own"], "recordId": record_id},
1011
+ entry["content"], entry["filename"], entry["content_type"], 0)
1012
+ return dict(entry, name=f'{entry["name"]}{FILE_MARKER}{b62(len(entry["content"]))}', content=container, content_type="application/octet-stream")
1013
+
1014
+ def _confirm_file_dek(self, record_id: str) -> None:
1015
+ """
1016
+ Before upload_files seals files with a record's cached data key: the key must still be the
1017
+ record's. Another session of the owner may have rolled it (a revoke) since, and files sealed
1018
+ under the old key could never be opened. A stale key is replaced by reading the record again;
1019
+ when the record is encrypted and this session cannot read its new key, the upload is refused
1020
+ rather than sending the files up in the clear or under a dead key.
1021
+ """
1022
+ s = self._enc
1023
+ if s is None or not record_id or record_id not in s.deks:
1024
+ return
1025
+ if self._dek_if_current(record_id) is not None:
1026
+ return
1027
+ rec = self._read_own_record(record_id)
1028
+ if rec is None or not rec.get("encrypted"):
1029
+ return
1030
+ if rec.get("record_id") != record_id and rec.get("record_id") in s.deks:
1031
+ s.deks[record_id] = s.deks[rec["record_id"]]
1032
+ if record_id not in s.deks:
1033
+ raise _err(f'Cannot attach files to encrypted record "{record_id}": its data key changed on another device and could not '
1034
+ f'be read here ({(rec.get("encrypted") or {}).get("reason")}).', "ENCRYPTION_LOCKED")
1035
+
1036
+ @staticmethod
1037
+ def _sealed_file_segments(url: str) -> Optional[List[str]]:
1038
+ segs = url.split("?")[0].split("/")[3:]
1039
+ if len(segs) < 12 or segs[4] != "records" or segs[7] != "bin" or parse_file_marker(segs[10]) is None:
1040
+ return None
1041
+ return segs
1042
+
1043
+ def _maybe_decrypt_file(self, requested_url: str, blob: bytes) -> bytes:
1044
+ if self._enc is None or self._sealed_file_segments(requested_url) is None:
1045
+ return blob
1046
+ return self._decrypt_file_for(requested_url, blob)[0]
1047
+
1048
+ def _decrypt_file_for(self, requested_url: str, blob: bytes) -> Tuple[bytes, Dict[str, Any]]:
1049
+ segs = self._sealed_file_segments(requested_url)
1050
+ dek_entry = self._enc.deks.get(segs[5])
1051
+ if not dek_entry:
1052
+ raise _err(f'Cannot open this file: the data key for record "{segs[5]}" is not available. Read the record first, and make sure encryption is unlocked.', "ENCRYPTION_LOCKED")
1053
+ if not is_encrypted_file(blob):
1054
+ raise _err("This file is marked as encrypted but its contents are not an encrypted container.", "ENCRYPTION_FILE_CORRUPT")
1055
+ return decrypt_file(dek_entry["bytes"], {"service": self.service, "owner": self.owner, "recordOwner": segs[3], "recordId": segs[5]}, blob)
1056
+
1057
+ # ---- sharing ---------------------------------------------------------------------------------------
1058
+
1059
+ def _load_for_rewrap(self, record_id: str) -> Optional[Dict[str, Any]]:
1060
+ s = self._enc
1061
+ entry = self._dek_if_current(record_id)
1062
+ if entry:
1063
+ return entry
1064
+ rec = self._read_own_record(record_id)
1065
+ if rec is None:
1066
+ raise _err(f'Record "{record_id}" not found.', "NOT_EXISTS")
1067
+ enc = rec.get("encrypted")
1068
+ if enc and enc.get("status") == "failed" and enc.get("reason") == "DATA_UNAVAILABLE":
1069
+ raise _err(f'Cannot change sharing on record "{record_id}": its data could not be read, '
1070
+ "so whether it is encrypted is unknown. Retry once the record reads normally.", "ENCRYPTION_DATA_UNAVAILABLE")
1071
+ if not enc:
1072
+ return None
1073
+ if rec.get("user_id") != self._me():
1074
+ raise _err("Only the record owner can share an encrypted record, because adding a key wrap means writing the record.", "ENCRYPTION_GRANT_REQUIRES_OWNER")
1075
+ entry = s.deks.get(rec["record_id"])
1076
+ if not entry:
1077
+ raise _err(f'Cannot change sharing on record "{record_id}": its data could not be decrypted ({enc.get("reason")}).', "ENCRYPTION_LOCKED")
1078
+ return entry
1079
+
1080
+ def _read_stored_envelope(self, record_id: str) -> Optional[Dict[str, Any]]:
1081
+ """
1082
+ The record's stored envelope, as the server holds it (None when it is not one). Its own read,
1083
+ never decrypted: an instance-wide "read raw" switch handed raw envelopes to any read another
1084
+ thread made at the same moment. As skapi-js readStoredEnvelope.
1085
+ """
1086
+ import re
1087
+ q, _ = self._build_query({"record_id": record_id} if re.match(r"^[a-zA-Z0-9]+$", record_id) else {"unique_id": record_id}, False)
1088
+ signed_in = self._signed_in()
1089
+ res = self._call("get-records", q, auth=signed_in, method="POST" if signed_in else "GET", fetch_options={"limit": 1})
1090
+ raw = res["list"][0] if isinstance(res, dict) and res.get("list") else None
1091
+ if not isinstance(raw, dict):
1092
+ return None
1093
+ rec = self._normalize_record(raw, skip_bin_resolve=True, skip_decrypt=True)
1094
+ return rec.get("data") if is_envelope(rec.get("data")) else None
1095
+
1096
+ def _write_recipients(self, record_id: str, recipients: Dict[str, Any]) -> None:
1097
+ stored = self._read_stored_envelope(record_id)
1098
+ if not is_envelope(stored):
1099
+ raise _err(f'Cannot change sharing on record "{record_id}": its stored envelope could not be read.', "ENCRYPTION_DATA_UNAVAILABLE")
1100
+ self._enc.deks[record_id]["recipients"] = dict(recipients)
1101
+ self._enc.passthrough[record_id] = dict(stored, k=recipients)
1102
+ self.post_record(config={"record_id": record_id})
1103
+
1104
+ def _enc_add_recipients(self, record_id: str, ids: List[str]) -> None:
1105
+ s = self._enc
1106
+ if s is None or not ids:
1107
+ return
1108
+ entry = self._load_for_rewrap(record_id)
1109
+ if entry is None:
1110
+ return
1111
+ me = self._me()
1112
+ if entry["own"] != me:
1113
+ raise _err("Only the record owner can share an encrypted record, because adding a key wrap means writing the record.", "ENCRYPTION_GRANT_REQUIRES_OWNER")
1114
+ targets = [i for i in ids if i != me]
1115
+ keys = self._peer_keys(targets)
1116
+ missing = [i for i in targets if not keys.get(i)]
1117
+ if missing:
1118
+ raise _err(f"These users have no encryption key yet, so they cannot be given access: {', '.join(missing)}. "
1119
+ "A user's key is created the first time they log in with encryption enabled.", "ENCRYPTION_RECIPIENT_HAS_NO_KEY")
1120
+ recipients = dict(entry["recipients"])
1121
+ anchor = self._anchor_of(entry)
1122
+ aad = self._payload_aad(entry["own"], entry["anch"], anchor)
1123
+ for u in targets:
1124
+ pub, fpr = keys[u]
1125
+ recipients[u] = {"t": "ecdh", **ecdh_wrap(entry["bytes"], pub, self._wrap_info(anchor, entry["own"], u, fpr), self._recipient_aad(aad, u, fpr)), "fpr": fpr}
1126
+ self._write_recipients(record_id, recipients)
1127
+
1128
+ def _enc_drop_and_roll(self, record_id: str, ids: Optional[List[str]]) -> None:
1129
+ s = self._enc
1130
+ if s is None:
1131
+ return
1132
+ entry = self._load_for_rewrap(record_id)
1133
+ if entry is None:
1134
+ return
1135
+ me = self._me()
1136
+ if entry["own"] != me:
1137
+ raise _err("Only the record owner can revoke access to an encrypted record.", "ENCRYPTION_GRANT_REQUIRES_OWNER")
1138
+ # the plaintext FIRST, while the current key is still usable
1139
+ rec = self._read_own_record(record_id)
1140
+ if rec is None or (rec.get("encrypted") or {}).get("status") == "failed":
1141
+ raise _err(f'Cannot change sharing on record "{record_id}": its current data could not be read '
1142
+ f'({((rec or {}).get("encrypted") or {}).get("reason")}), so re-writing the record would destroy it.', "ENCRYPTION_DATA_UNAVAILABLE")
1143
+ rid = rec.get("record_id") or record_id
1144
+ # who keeps access, from the record just read rather than an older cached map
1145
+ current = s.deks.get(rid) or entry
1146
+ keep = [] if ids is None else [u for u in current["recipients"] if u != me and u not in ids]
1147
+ keys = self._peer_keys(keep) if keep else {}
1148
+ missing = [u for u in keep if not keys.get(u)]
1149
+ if missing:
1150
+ raise _err(f'Cannot revoke on record "{record_id}": these users keep access but their encryption keys could not be read, '
1151
+ f"so re-sharing after the key roll would fail and lock them out: {', '.join(missing)}.", "ENCRYPTION_RECIPIENT_HAS_NO_KEY")
1152
+ # The new data key, minted now so the record's sealed attachments are sealed again under it
1153
+ # BEFORE the roll: each one is opened with the current key, sealed with the new one and
1154
+ # uploaded, and the roll write retires the old copies. Interrupted before the roll, the
1155
+ # record still reads exactly as before. Until the roll lands the new copies are sealed under a
1156
+ # key the record does not hold, so a failure on the way removes the ones already stored.
1157
+ import mimetypes
1158
+ from urllib.parse import urlsplit
1159
+ next_key = os.urandom(32)
1160
+ ctx = {"service": self.service, "owner": self.owner, "recordOwner": me, "recordId": rid}
1161
+ reseal, retire = [], []
1162
+ for form_key, entries in (rec.get("bin") or {}).items():
1163
+ for f in entries:
1164
+ if not f.get("encrypted"):
1165
+ continue
1166
+ try:
1167
+ content, meta = self._decrypt_file_for(f["url"], self.get_file(f["url"], {"dataType": "bytes", "_raw": True}))
1168
+ except SkapiError as err:
1169
+ if err.code == "ENCRYPTION_FILE_STALE_KEY":
1170
+ continue # sealed under a key an earlier roll retired: nobody can open it, and it must not block this revoke
1171
+ raise _err(f'Cannot revoke on record "{record_id}": its encrypted file "{f.get("filename")}" could not be read, '
1172
+ f"so rolling the key would lock it: {err}", "ENCRYPTION_DATA_UNAVAILABLE") from err
1173
+ except Exception as err:
1174
+ raise _err(f'Cannot revoke on record "{record_id}": its encrypted file "{f.get("filename")}" could not be read, '
1175
+ f"so rolling the key would lock it: {err}", "ENCRYPTION_DATA_UNAVAILABLE") from err
1176
+ content_type = meta.get("t") or mimetypes.guess_type(f["filename"])[0] or "application/octet-stream"
1177
+ reseal.append({"name": f"{form_key}{FILE_MARKER}{b62(len(content))}", "filename": f["filename"],
1178
+ "content": encrypt_file(next_key, ctx, content, f["filename"], content_type, meta.get("lm") or 0),
1179
+ "content_type": "application/octet-stream", "_presealed": True})
1180
+ u = urlsplit(f["url"])
1181
+ retire.append(f"{u.scheme}://{u.netloc}/{f['path']}")
1182
+ copies: List[str] = []
1183
+ if reseal:
1184
+ result = self._upload_prepared(reseal, rid)
1185
+ copies = [u for u in result.get("landed") or [] if u]
1186
+ if result["failed"]:
1187
+ if copies:
1188
+ try:
1189
+ self._remove_landed_copies(rid, copies)
1190
+ except Exception as err:
1191
+ warnings.warn(f"skapi encryption: the re-sealed copies could not be removed: {err}", RuntimeWarning, stacklevel=3)
1192
+ raise result["errors"][0]["error"]
1193
+ s.roll.add(rid)
1194
+ s.roll_key[rid] = next_key
1195
+ config: Dict[str, Any] = {"record_id": rid, "table": {"name": rec["table"]["name"], "access_group": "private"}}
1196
+ if retire:
1197
+ config["remove_bin"] = retire
1198
+ try:
1199
+ self.post_record(rec.get("data"), config)
1200
+ except Exception:
1201
+ if copies:
1202
+ try:
1203
+ self._drop_unrolled_copies(rid, next_key, copies)
1204
+ except Exception as err:
1205
+ warnings.warn(f"skapi encryption: the re-sealed copies could not be removed: {err}", RuntimeWarning, stacklevel=3)
1206
+ raise
1207
+ finally:
1208
+ # never left for a later write: a pending roll writes a key wrapped for the owner only
1209
+ s.roll.discard(rid)
1210
+ s.roll_key.pop(rid, None)
1211
+ if keep:
1212
+ self._enc_add_recipients(rid, keep)
1213
+
1214
+ def _drop_unrolled_copies(self, record_id: str, next_key: bytes, copies: List[str]) -> None:
1215
+ """
1216
+ After a failed roll write: removes the re-sealed attachment copies, unless the write landed
1217
+ after all (only its answer was lost), in which case they are the record's files now. Which
1218
+ one it was is read off the stored envelope: the owner's wrap opens to the new key or the old
1219
+ one. When that cannot be told, the copies are left alone. As skapi-js dropUnrolledCopies.
1220
+ """
1221
+ s = self._enc
1222
+ raw = self._read_stored_envelope(record_id)
1223
+ me = self._me()
1224
+ w = (raw.get("k") or {}).get(me) if raw and me else None
1225
+ if not raw or not isinstance(w, dict) or w.get("t") != "mk" or not s.mk or raw.get("own") != me:
1226
+ return
1227
+ try:
1228
+ stored = open_(s.mk, b64u_dec(w["iv"]), b64u_dec(w["ct"]),
1229
+ self._recipient_aad(self._payload_aad(raw["own"], raw["anch"], self._anchor_of(raw)), me, "mk"))
1230
+ except Exception:
1231
+ return
1232
+ if stored != next_key:
1233
+ self._remove_landed_copies(record_id, copies)
1234
+
1235
+ # ---- public methods ------------------------------------------------------------------------------
1236
+
1237
+ def get_encryption_status(self) -> Dict[str, Any]:
1238
+ s = self._enc
1239
+ if s is None:
1240
+ return {"status": "disabled"}
1241
+ out: Dict[str, Any] = {"status": s.status}
1242
+ if s.status != "unlocked":
1243
+ out["reason"] = s.reason
1244
+ if s.user_id:
1245
+ out["user_id"] = s.user_id
1246
+ if s.fpr:
1247
+ out["fingerprint"] = s.fpr
1248
+ return out
1249
+
1250
+ @staticmethod
1251
+ def is_withheld(value: Any) -> bool:
1252
+ return isinstance(value, dict) and value.get(WITHHELD) is True
1253
+
1254
+ def unlock_encryption(self, password: str) -> Dict[str, str]:
1255
+ if self._enc is None:
1256
+ raise _err("Encryption is not enabled for this instance.", "INVALID_REQUEST")
1257
+ if not self._signed_in():
1258
+ raise _err("User login is required.", "INVALID_REQUEST")
1259
+ if not password:
1260
+ raise _err('"password" is required.', "INVALID_PARAMETER")
1261
+ self._ensure_keyring(password, create=False) # opens an existing keyring only
1262
+ if self._enc.status != "unlocked":
1263
+ raise _err(f"Encryption could not be unlocked: {self._enc.reason}", "ENCRYPTION_LOCKED")
1264
+ return {"status": "unlocked"}
1265
+
1266
+ def lock_encryption(self) -> Dict[str, str]:
1267
+ if self._enc is None:
1268
+ return {"status": "disabled"}
1269
+ # keeps an encryption recovery code the app has not collected yet: it can never be shown
1270
+ # again, and losing it to a lock left the user without one they never knew existed
1271
+ self._enc.clear(keep_recovery=True)
1272
+ return {"status": "locked"}
1273
+
1274
+ def _encryption_recovery_info(self) -> Optional[Dict[str, Any]]:
1275
+ """The "encryption_recovery" entry of get_connection_info(), or None when encryption is off
1276
+ or nobody is signed in. The code is created once, when encryption is first set up for a user,
1277
+ and never stored readable, so the FIRST call after that returns it and forgets it; every later
1278
+ call returns code None and a message. As in skapi-js."""
1279
+ s = self._enc
1280
+ if s is None or not self._signed_in():
1281
+ return None
1282
+ if s.cfg["recovery"] != "code":
1283
+ return {"code": None, "message": 'Encryption recovery codes are turned off ("encryption.recovery" is "none").'}
1284
+ if s.pending_recovery_code and s.pending_recovery_user == self._me():
1285
+ code, s.pending_recovery_code, s.pending_recovery_user = s.pending_recovery_code, "", ""
1286
+ return {"code": code, "message": "This is your encryption recovery code. Save it now: it is shown only this once. "
1287
+ "If you forget your password, it is the only way to read your encrypted private data again."}
1288
+ if s.status != "unlocked":
1289
+ return {"code": None, "message": "Encryption is locked. Unlock it with unlock_encryption() or unlock_encryption_with_recovery_code(), "
1290
+ "then call regenerate_encryption_recovery_code() to get a new encryption recovery code."}
1291
+ return {"code": None, "message": "Your encryption recovery code was shown once and cannot be shown again. "
1292
+ "Call regenerate_encryption_recovery_code() to get a new one."}
1293
+
1294
+ def unlock_encryption_with_recovery_code(self, code: str, password: Optional[str] = None) -> Dict[str, Any]:
1295
+ s = self._enc
1296
+ if s is None:
1297
+ raise _err("Encryption is not enabled for this instance.", "INVALID_REQUEST")
1298
+ if not self._signed_in():
1299
+ raise _err("User login is required. Reset the password and log in first, then use the encryption recovery code.", "INVALID_REQUEST")
1300
+ if not code:
1301
+ raise _err('"code" is required.', "INVALID_PARAMETER")
1302
+ uid = self._me()
1303
+ keyring = self._find_keyring(uid)
1304
+ if not keyring:
1305
+ raise _err("This account has no encryption keyring, so there is nothing to recover.", "NOT_EXISTS")
1306
+ raw = decode_recovery_code(code)
1307
+ data = dict(keyring["data"])
1308
+ mk = None
1309
+ for w in sorted((w for w in data.get("wraps", []) if w.get("p") == "recovery"), key=lambda w: w.get("created", 0), reverse=True):
1310
+ try:
1311
+ rk = hkdf(raw, b64u_dec(w["kdf"]["s"]), self._e_s("recovery", uid))
1312
+ mk = open_(rk, b64u_dec(w["iv"]), b64u_dec(w["ct"]), utf8(f"{self._e_s('rk', uid)}|HKDF-SHA256|{w['kdf']['s']}"))
1313
+ break
1314
+ except Exception:
1315
+ continue
1316
+ if mk is None:
1317
+ raise _err("That encryption recovery code did not open the keyring. Check it against the copy you saved when encryption was set up.", "ENCRYPTION_BAD_RECOVERY_CODE")
1318
+ self._adopt_keyring(keyring, mk, uid)
1319
+ wraps = list(data.get("wraps", []))
1320
+ repaired, new_code = False, None
1321
+ if password:
1322
+ wraps = [w for w in wraps if w.get("p") != "password"] + [self._password_wrap(mk, password, uid)]
1323
+ repaired = True
1324
+ if s.cfg["recovery"] == "code":
1325
+ w, new_code = self._recovery_wrap(mk, uid)
1326
+ wraps = [x for x in wraps if x.get("p") != "recovery"] + [w]
1327
+ data["wraps"], data["updated"] = wraps, int(time.time() * 1000)
1328
+ self.post_record(data, {"record_id": keyring["record_id"]})
1329
+ return {"status": "unlocked", "repaired": repaired, "encryptionRecoveryCode": new_code}
1330
+
1331
+ def regenerate_encryption_recovery_code(self) -> Dict[str, str]:
1332
+ s = self._enc
1333
+ if s is None:
1334
+ raise _err("Encryption is not enabled for this instance.", "INVALID_REQUEST")
1335
+ if s.status != "unlocked" or not s.mk:
1336
+ raise _err("Encryption must be unlocked to issue an encryption recovery code. Only someone who can already decrypt can create one.", "ENCRYPTION_LOCKED")
1337
+ if s.cfg["recovery"] == "none":
1338
+ raise _err('Encryption recovery codes are turned off for this instance ("encryption.recovery" is "none").', "INVALID_REQUEST")
1339
+ res = self.get_records({"record_id": s.keyring_record_id}, {"limit": 1})
1340
+ if not res.get("list"):
1341
+ raise _err("The encryption keyring could not be read.", "ENCRYPTION_KEYRING_CORRUPT")
1342
+ data = dict(res["list"][0]["data"])
1343
+ if not (data.get("self") or {}).get("ct"):
1344
+ raise _err("This keyring predates encryption recovery code rotation and cannot issue a new code. "
1345
+ "Use unlock_encryption_with_recovery_code() with the existing code, which issues a replacement.", "ENCRYPTION_KEYRING_CORRUPT")
1346
+ mk = open_(s.mk, b64u_dec(data["self"]["iv"]), b64u_dec(data["self"]["ct"]), utf8(self._e_s("self", s.user_id)))
1347
+ w, code = self._recovery_wrap(mk, s.user_id)
1348
+ data["wraps"] = [x for x in data.get("wraps", []) if x.get("p") != "recovery"] + [w]
1349
+ data["updated"] = int(time.time() * 1000)
1350
+ self.post_record(data, {"record_id": s.keyring_record_id})
1351
+ return {"encryptionRecoveryCode": code}
1352
+
1353
+ def pin_peer_key(self, user_id: str, fingerprint_: str) -> None:
1354
+ s = self._enc
1355
+ if s is None or s.status != "unlocked":
1356
+ raise _err("Encryption is locked.", "ENCRYPTION_LOCKED")
1357
+ s.pins[user_id] = fingerprint_
1358
+ s.peer_pub.pop(user_id, None)
1359
+ self._persist_pins()