flask-deck 0.3.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 (57) hide show
  1. flask_deck/__init__.py +184 -0
  2. flask_deck/adapters/__init__.py +23 -0
  3. flask_deck/adapters/sqlalchemy.py +272 -0
  4. flask_deck/audit.py +363 -0
  5. flask_deck/auth.py +462 -0
  6. flask_deck/branding.py +217 -0
  7. flask_deck/charts.py +514 -0
  8. flask_deck/cli.py +135 -0
  9. flask_deck/config.py +81 -0
  10. flask_deck/dashboard.py +416 -0
  11. flask_deck/deck.py +4153 -0
  12. flask_deck/demo.py +1066 -0
  13. flask_deck/events.py +309 -0
  14. flask_deck/exceptions.py +34 -0
  15. flask_deck/exporter.py +240 -0
  16. flask_deck/formatters.py +386 -0
  17. flask_deck/i18n.py +399 -0
  18. flask_deck/icons.py +92 -0
  19. flask_deck/importer.py +612 -0
  20. flask_deck/introspection.py +376 -0
  21. flask_deck/jobs.py +382 -0
  22. flask_deck/mfa.py +670 -0
  23. flask_deck/model_view.py +1097 -0
  24. flask_deck/py.typed +0 -0
  25. flask_deck/query.py +1220 -0
  26. flask_deck/schema_graph.py +137 -0
  27. flask_deck/security.py +373 -0
  28. flask_deck/sql_console.py +391 -0
  29. flask_deck/sso.py +293 -0
  30. flask_deck/static/css/deck.css +1333 -0
  31. flask_deck/static/js/deck.js +1433 -0
  32. flask_deck/storage.py +669 -0
  33. flask_deck/templates/flask_deck/audit_list.html +117 -0
  34. flask_deck/templates/flask_deck/base.html +454 -0
  35. flask_deck/templates/flask_deck/custom_page.html +12 -0
  36. flask_deck/templates/flask_deck/dashboard.html +32 -0
  37. flask_deck/templates/flask_deck/diagnostics.html +80 -0
  38. flask_deck/templates/flask_deck/error.html +15 -0
  39. flask_deck/templates/flask_deck/import_wizard.html +143 -0
  40. flask_deck/templates/flask_deck/jobs_list.html +95 -0
  41. flask_deck/templates/flask_deck/login.html +93 -0
  42. flask_deck/templates/flask_deck/login_mfa.html +59 -0
  43. flask_deck/templates/flask_deck/mfa_setup.html +121 -0
  44. flask_deck/templates/flask_deck/model_detail.html +124 -0
  45. flask_deck/templates/flask_deck/model_form.html +389 -0
  46. flask_deck/templates/flask_deck/model_list.html +489 -0
  47. flask_deck/templates/flask_deck/partials/drawer_detail.html +93 -0
  48. flask_deck/templates/flask_deck/partials/widget_grid.html +207 -0
  49. flask_deck/templates/flask_deck/rbac_matrix.html +59 -0
  50. flask_deck/templates/flask_deck/record_history.html +102 -0
  51. flask_deck/templates/flask_deck/schema_inspector.html +83 -0
  52. flask_deck/templates/flask_deck/sql_console.html +87 -0
  53. flask_deck-0.3.0.dist-info/METADATA +382 -0
  54. flask_deck-0.3.0.dist-info/RECORD +57 -0
  55. flask_deck-0.3.0.dist-info/WHEEL +4 -0
  56. flask_deck-0.3.0.dist-info/entry_points.txt +5 -0
  57. flask_deck-0.3.0.dist-info/licenses/LICENSE +21 -0
flask_deck/mfa.py ADDED
@@ -0,0 +1,670 @@
1
+ from __future__ import annotations
2
+
3
+ import base64
4
+ import hashlib
5
+ import hmac
6
+ import json
7
+ import secrets
8
+ import struct
9
+ import threading
10
+ import time
11
+ from abc import ABC, abstractmethod
12
+ from dataclasses import dataclass
13
+ from datetime import datetime, timezone
14
+ from urllib.parse import quote
15
+
16
+ import sqlalchemy as sa
17
+ from markupsafe import Markup
18
+ from sqlalchemy.engine import Engine
19
+ from sqlalchemy.orm import Session
20
+ from werkzeug.security import check_password_hash, generate_password_hash
21
+
22
+ MFA_PENDING_USER_KEY = "_deck_mfa_pending_user"
23
+ MFA_PENDING_NEXT_KEY = "_deck_mfa_pending_next"
24
+ MFA_PENDING_AT_KEY = "_deck_mfa_pending_at"
25
+ MFA_PENDING_SSO_KEY = "_deck_mfa_pending_sso"
26
+ MFA_VERIFIED_KEY = "_deck_mfa_verified"
27
+
28
+
29
+ @dataclass(frozen=True, slots=True)
30
+ class MFAEnrollment:
31
+ """Persisted TOTP enrollment record for one DeckUser."""
32
+
33
+ user_id: str
34
+ secret: str
35
+ enabled: bool = True
36
+ last_step: int | None = None
37
+ recovery_hashes: tuple[str, ...] = ()
38
+ created_at: datetime | None = None
39
+
40
+
41
+ def generate_totp_secret(num_bytes: int = 20) -> str:
42
+ """Generate a 160-bit RFC 6238 Base32 secret (unpadded)."""
43
+ return base64.b32encode(secrets.token_bytes(max(16, num_bytes))).decode("ascii").rstrip("=")
44
+
45
+
46
+ def _decode_base32(secret: str) -> bytes:
47
+ cleaned = secret.strip().replace(" ", "").replace("-", "").upper()
48
+ pad = "=" * (-len(cleaned) % 8)
49
+ return base64.b32decode(cleaned + pad, casefold=True)
50
+
51
+
52
+ def compute_totp(
53
+ secret: str,
54
+ *,
55
+ timestamp: float | None = None,
56
+ step_seconds: int = 30,
57
+ digits: int = 6,
58
+ ) -> str:
59
+ """Compute an RFC 6238 HMAC-SHA1 TOTP code using Python stdlib only."""
60
+ now = time.time() if timestamp is None else float(timestamp)
61
+ counter = int(now // step_seconds)
62
+ key = _decode_base32(secret)
63
+ msg = struct.pack(">Q", counter)
64
+ digest = hmac.new(key, msg, hashlib.sha1).digest()
65
+ offset = digest[-1] & 0x0F
66
+ code_int = struct.unpack(">I", digest[offset : offset + 4])[0] & 0x7FFFFFFF
67
+ return str(code_int % (10**digits)).zfill(digits)
68
+
69
+
70
+ def verify_totp(
71
+ secret: str,
72
+ candidate: str,
73
+ *,
74
+ timestamp: float | None = None,
75
+ step_seconds: int = 30,
76
+ digits: int = 6,
77
+ window: int = 1,
78
+ last_step: int | None = None,
79
+ ) -> int | None:
80
+ """Verify TOTP with replay prevention. Returns accepted time-step or None."""
81
+ clean = candidate.strip().replace(" ", "").replace("-", "")
82
+ if not clean.isdigit() or len(clean) != digits:
83
+ return None
84
+ now = time.time() if timestamp is None else float(timestamp)
85
+ base_step = int(now // step_seconds)
86
+ for delta in range(-window, window + 1):
87
+ step = base_step + delta
88
+ if step < 0:
89
+ continue
90
+ if last_step is not None and step <= last_step:
91
+ continue
92
+ expected = compute_totp(
93
+ secret,
94
+ timestamp=step * step_seconds,
95
+ step_seconds=step_seconds,
96
+ digits=digits,
97
+ )
98
+ if hmac.compare_digest(expected, clean):
99
+ return step
100
+ return None
101
+
102
+
103
+ def generate_recovery_codes(count: int = 8) -> tuple[list[str], tuple[str, ...]]:
104
+ """Return (plaintext_codes_to_show_once, pbkdf2_hashed_codes_to_store)."""
105
+ plain: list[str] = []
106
+ hashed: list[str] = []
107
+ for _ in range(max(4, count)):
108
+ raw = secrets.token_hex(4).upper()
109
+ code = f"{raw[:4]}-{raw[4:]}"
110
+ plain.append(code)
111
+ hashed.append(generate_password_hash(code, method="pbkdf2:sha256:200000"))
112
+ return plain, tuple(hashed)
113
+
114
+
115
+ def build_otpauth_uri(
116
+ *,
117
+ secret: str,
118
+ account_name: str,
119
+ issuer: str = "Flask-Deck",
120
+ ) -> str:
121
+ """Build standard otpauth://totp URI compatible with Google/Apple/1Password Authenticators."""
122
+ safe_issuer = issuer.strip()[:36] or "Flask-Deck"
123
+ safe_account = account_name.strip()[:64] or "user"
124
+ label = f"{quote(safe_issuer, safe='')}:{quote(safe_account, safe='')}"
125
+ return (
126
+ f"otpauth://totp/{label}"
127
+ f"?secret={quote(secret, safe='')}"
128
+ f"&issuer={quote(safe_issuer, safe='')}"
129
+ "&algorithm=SHA1&digits=6&period=30"
130
+ )
131
+
132
+
133
+ # ---------------------------------------------------------------------------
134
+ # Pure-Python ISO/IEC 18004 QR Code Generator (Byte mode, ECC Level L, V1-V8)
135
+ # Zero external dependencies, zero inline style=, strict CSP safe SVG output.
136
+ # ---------------------------------------------------------------------------
137
+
138
+ # (version, size, total_data_cw, ec_per_block, blocks, alignment_centers)
139
+ _QR_SPECS: tuple[tuple[int, int, int, int, int, tuple[int, ...]], ...] = (
140
+ (1, 21, 19, 7, 1, ()),
141
+ (2, 25, 34, 10, 1, (6, 18)),
142
+ (3, 29, 55, 15, 1, (6, 22)),
143
+ (4, 33, 80, 20, 1, (6, 26)),
144
+ (5, 37, 108, 26, 1, (6, 30)),
145
+ (6, 41, 136, 18, 2, (6, 34)),
146
+ (7, 45, 156, 20, 2, (6, 22, 38)),
147
+ (8, 49, 194, 24, 2, (6, 24, 42)),
148
+ )
149
+
150
+ # Precomputed 15-bit format strings for ECC Level L (01) and masks 0..7
151
+ _QR_FORMAT_L: tuple[int, ...] = (
152
+ 0x77C4,
153
+ 0x72F3,
154
+ 0x7DAA,
155
+ 0x789D,
156
+ 0x662F,
157
+ 0x6318,
158
+ 0x6C41,
159
+ 0x6976,
160
+ )
161
+ _QR_VERSION_INFO: dict[int, int] = {7: 0x07C94, 8: 0x085BC}
162
+
163
+
164
+ def _gf_mul(a: int, b: int) -> int:
165
+ res = 0
166
+ for _ in range(8):
167
+ if b & 1:
168
+ res ^= a
169
+ hi = a & 0x80
170
+ a = (a << 1) & 0xFF
171
+ if hi:
172
+ a ^= 0x1D
173
+ b >>= 1
174
+ return res
175
+
176
+
177
+ def _rs_generator(degree: int) -> list[int]:
178
+ poly = [1]
179
+ root = 1
180
+ for _ in range(degree):
181
+ nxt = [0] * (len(poly) + 1)
182
+ for i, coeff in enumerate(poly):
183
+ nxt[i] ^= coeff
184
+ nxt[i + 1] ^= _gf_mul(coeff, root)
185
+ poly = nxt
186
+ root = _gf_mul(root, 2)
187
+ return poly
188
+
189
+
190
+ def _rs_remainder(data: list[int], ec_len: int) -> list[int]:
191
+ gen = _rs_generator(ec_len)
192
+ rem = [0] * ec_len
193
+ for byte in data:
194
+ factor = byte ^ rem[0]
195
+ rem = [*rem[1:], 0]
196
+ if factor != 0:
197
+ for i in range(ec_len):
198
+ rem[i] ^= _gf_mul(gen[i + 1], factor)
199
+ return rem
200
+
201
+
202
+ def build_qr_matrix(text: str) -> list[list[bool]]:
203
+ """Encode UTF-8 payload into a valid ISO/IEC 18004 QR boolean matrix (ECC-L, V1-V8)."""
204
+ payload = text.encode("utf-8")
205
+ spec = None
206
+ for cand in _QR_SPECS:
207
+ # 4-bit mode + 8-bit length = 2 bytes header overhead
208
+ if len(payload) + 2 <= cand[2]:
209
+ spec = cand
210
+ break
211
+ if spec is None:
212
+ raise ValueError("Payload exceeds pure-Python QR V8 capacity (192 bytes)")
213
+
214
+ ver, size, total_data_cw, ec_per_block, num_blocks, align_centers = spec
215
+
216
+ # 1. Build bit stream: Byte mode (0100) + 8-bit length + payload + terminator + pad bytes
217
+ bits: list[int] = [0, 1, 0, 0]
218
+ for shift in range(7, -1, -1):
219
+ bits.append((len(payload) >> shift) & 1)
220
+ for b in payload:
221
+ for shift in range(7, -1, -1):
222
+ bits.append((b >> shift) & 1)
223
+
224
+ total_bits = total_data_cw * 8
225
+ term_len = min(4, total_bits - len(bits))
226
+ bits.extend([0] * term_len)
227
+ while len(bits) % 8 != 0:
228
+ bits.append(0)
229
+
230
+ data_cw: list[int] = []
231
+ for i in range(0, len(bits), 8):
232
+ val = 0
233
+ for bit in bits[i : i + 8]:
234
+ val = (val << 1) | bit
235
+ data_cw.append(val)
236
+
237
+ pad_bytes = (0xEC, 0x11)
238
+ pad_idx = 0
239
+ while len(data_cw) < total_data_cw:
240
+ data_cw.append(pad_bytes[pad_idx % 2])
241
+ pad_idx += 1
242
+
243
+ # 2. Split into blocks, compute Reed-Solomon EC, interleave codewords
244
+ block_size = total_data_cw // num_blocks
245
+ data_blocks: list[list[int]] = []
246
+ ec_blocks: list[list[int]] = []
247
+ pos = 0
248
+ for _ in range(num_blocks):
249
+ blk = data_cw[pos : pos + block_size]
250
+ pos += block_size
251
+ data_blocks.append(blk)
252
+ ec_blocks.append(_rs_remainder(blk, ec_per_block))
253
+
254
+ interleaved: list[int] = []
255
+ for i in range(block_size):
256
+ for blk in data_blocks:
257
+ interleaved.append(blk[i])
258
+ for i in range(ec_per_block):
259
+ for ec in ec_blocks:
260
+ interleaved.append(ec[i])
261
+
262
+ code_bits: list[int] = []
263
+ for cw in interleaved:
264
+ for shift in range(7, -1, -1):
265
+ code_bits.append((cw >> shift) & 1)
266
+
267
+ # 3. Initialize module grid + function pattern reservation mask
268
+ grid: list[list[bool]] = [[False] * size for _ in range(size)]
269
+ is_func: list[list[bool]] = [[False] * size for _ in range(size)]
270
+
271
+ def _set_func(r: int, c: int, val: bool) -> None:
272
+ if 0 <= r < size and 0 <= c < size:
273
+ grid[r][c] = val
274
+ is_func[r][c] = True
275
+
276
+ def _draw_finder(top: int, left: int) -> None:
277
+ for dr in range(-1, 8):
278
+ for dc in range(-1, 8):
279
+ r, c = top + dr, left + dc
280
+ if not (0 <= r < size and 0 <= c < size):
281
+ continue
282
+ if dr in {-1, 7} or dc in {-1, 7}:
283
+ _set_func(r, c, False)
284
+ else:
285
+ dark = dr in {0, 6} or dc in {0, 6} or (2 <= dr <= 4 and 2 <= dc <= 4)
286
+ _set_func(r, c, dark)
287
+
288
+ _draw_finder(0, 0)
289
+ _draw_finder(0, size - 7)
290
+ _draw_finder(size - 7, 0)
291
+
292
+ # Timing patterns
293
+ for i in range(8, size - 8):
294
+ _set_func(6, i, i % 2 == 0)
295
+ _set_func(i, 6, i % 2 == 0)
296
+
297
+ # Alignment patterns
298
+ for r0 in align_centers:
299
+ for c0 in align_centers:
300
+ if is_func[r0][c0]:
301
+ continue
302
+ for dr in range(-2, 3):
303
+ for dc in range(-2, 3):
304
+ dark = max(abs(dr), abs(dc)) != 1
305
+ _set_func(r0 + dr, c0 + dc, dark)
306
+
307
+ # Dark module + reserve format info areas
308
+ _set_func(size - 8, 8, True)
309
+ for i in range(9):
310
+ if i != 6:
311
+ is_func[8][i] = True
312
+ is_func[i][8] = True
313
+ for i in range(8):
314
+ is_func[8][size - 1 - i] = True
315
+ is_func[size - 1 - i][8] = True
316
+
317
+ # Version info for V7+
318
+ if ver in _QR_VERSION_INFO:
319
+ vbits = _QR_VERSION_INFO[ver]
320
+ for i in range(18):
321
+ bit_val = bool((vbits >> i) & 1)
322
+ a = size - 11 + (i % 3)
323
+ b = i // 3
324
+ _set_func(a, b, bit_val)
325
+ _set_func(b, a, bit_val)
326
+
327
+ # 4. Place data bits in upward/downward zigzag columns
328
+ bit_idx = 0
329
+ upward = True
330
+ col = size - 1
331
+ while col > 0:
332
+ if col == 6:
333
+ col -= 1
334
+ rows = range(size - 1, -1, -1) if upward else range(size)
335
+ for row in rows:
336
+ for dc in (0, -1):
337
+ c = col + dc
338
+ if not is_func[row][c]:
339
+ grid[row][c] = bool(code_bits[bit_idx]) if bit_idx < len(code_bits) else False
340
+ bit_idx += 1
341
+ upward = not upward
342
+ col -= 2
343
+
344
+ # 5. Apply mask 0 ((r + c) % 2 == 0) — deterministic & clean, write format bits
345
+ mask_id = 0
346
+ for r in range(size):
347
+ for c in range(size):
348
+ if not is_func[r][c] and (r + c) % 2 == 0:
349
+ grid[r][c] = not grid[r][c]
350
+
351
+ fmt = _QR_FORMAT_L[mask_id]
352
+ # Place format bits around top-left and split bottom-left/top-right
353
+ for i in range(6):
354
+ bit_val = bool((fmt >> (14 - i)) & 1)
355
+ grid[8][i] = bit_val
356
+ grid[size - 1 - i][8] = bit_val
357
+ grid[8][7] = bool((fmt >> 8) & 1)
358
+ grid[8][8] = bool((fmt >> 7) & 1)
359
+ grid[7][8] = bool((fmt >> 6) & 1)
360
+ for i in range(6):
361
+ grid[5 - i][8] = bool((fmt >> (5 - i)) & 1)
362
+ grid[size - 7][8] = bool((fmt >> 8) & 1)
363
+ for i in range(8):
364
+ grid[8][size - 8 + i] = bool((fmt >> (7 - i)) & 1)
365
+
366
+ return grid
367
+
368
+
369
+ def render_qr_svg(data: str, *, pixel_size: int = 184) -> Markup:
370
+ """Render a scannable strict-CSP monochrome SVG QR code with a 4-module quiet zone."""
371
+ matrix = build_qr_matrix(data)
372
+ n = len(matrix)
373
+ quiet = 4
374
+ total = n + quiet * 2
375
+ path_parts: list[str] = []
376
+ for r, row in enumerate(matrix):
377
+ y = r + quiet
378
+ c = 0
379
+ while c < n:
380
+ if row[c]:
381
+ start = c
382
+ while c < n and row[c]:
383
+ c += 1
384
+ width = c - start
385
+ path_parts.append(f"M{start + quiet} {y}h{width}v1h-{width}z")
386
+ else:
387
+ c += 1
388
+ d_attr = "".join(path_parts)
389
+ safe_px = max(120, min(320, int(pixel_size)))
390
+ return Markup(
391
+ f'<svg class="dk-qr-svg" xmlns="http://www.w3.org/2000/svg" '
392
+ f'viewBox="0 0 {total} {total}" width="{safe_px}" height="{safe_px}" '
393
+ f'role="img" aria-label="Authenticator QR code" shape-rendering="crispEdges">'
394
+ f'<rect width="{total}" height="{total}" fill="#ffffff"/>'
395
+ f'<path d="{d_attr}" fill="#09090b"/>'
396
+ "</svg>"
397
+ )
398
+
399
+
400
+ # ---------------------------------------------------------------------------
401
+ # MFA Persistence Stores
402
+ # ---------------------------------------------------------------------------
403
+
404
+
405
+ class MFAStore(ABC):
406
+ """Pluggable store persisting TOTP secrets, replay steps, and hashed recovery codes."""
407
+
408
+ @abstractmethod
409
+ def get(self, user_id: str) -> MFAEnrollment | None:
410
+ """Return enrollment for user_id or None."""
411
+
412
+ @abstractmethod
413
+ def save(self, enrollment: MFAEnrollment) -> None:
414
+ """Upsert enrollment record."""
415
+
416
+ @abstractmethod
417
+ def delete(self, user_id: str) -> None:
418
+ """Remove enrollment (disable MFA)."""
419
+
420
+ def verify_and_record(
421
+ self,
422
+ user_id: str,
423
+ code: str,
424
+ *,
425
+ timestamp: float | None = None,
426
+ ) -> bool:
427
+ """Verify TOTP or single-use recovery code and update replay/consumption state."""
428
+ enrollment = self.get(user_id)
429
+ if enrollment is None or not enrollment.enabled:
430
+ return False
431
+
432
+ step = verify_totp(
433
+ enrollment.secret,
434
+ code,
435
+ timestamp=timestamp,
436
+ last_step=enrollment.last_step,
437
+ )
438
+ if step is not None:
439
+ self.save(
440
+ MFAEnrollment(
441
+ user_id=enrollment.user_id,
442
+ secret=enrollment.secret,
443
+ enabled=True,
444
+ last_step=step,
445
+ recovery_hashes=enrollment.recovery_hashes,
446
+ created_at=enrollment.created_at,
447
+ )
448
+ )
449
+ return True
450
+
451
+ # Check single-use recovery codes
452
+ cleaned = code.strip().upper()
453
+ for idx, hashed in enumerate(enrollment.recovery_hashes):
454
+ if check_password_hash(hashed, cleaned):
455
+ remaining = enrollment.recovery_hashes[:idx] + enrollment.recovery_hashes[idx + 1 :]
456
+ self.save(
457
+ MFAEnrollment(
458
+ user_id=enrollment.user_id,
459
+ secret=enrollment.secret,
460
+ enabled=True,
461
+ last_step=enrollment.last_step,
462
+ recovery_hashes=remaining,
463
+ created_at=enrollment.created_at,
464
+ )
465
+ )
466
+ return True
467
+ return False
468
+
469
+
470
+ class InMemoryMFAStore(MFAStore):
471
+ """Thread-safe in-memory MFA store suitable for demos and tests."""
472
+
473
+ __slots__ = ("_lock", "_records")
474
+
475
+ def __init__(self) -> None:
476
+ self._records: dict[str, MFAEnrollment] = {}
477
+ self._lock = threading.Lock()
478
+
479
+ def get(self, user_id: str) -> MFAEnrollment | None:
480
+ with self._lock:
481
+ return self._records.get(user_id)
482
+
483
+ def save(self, enrollment: MFAEnrollment) -> None:
484
+ with self._lock:
485
+ self._records[enrollment.user_id] = enrollment
486
+
487
+ def delete(self, user_id: str) -> None:
488
+ with self._lock:
489
+ self._records.pop(user_id, None)
490
+
491
+ def verify_and_record(
492
+ self,
493
+ user_id: str,
494
+ code: str,
495
+ *,
496
+ timestamp: float | None = None,
497
+ ) -> bool:
498
+ """Atomically verify and record TOTP / recovery usage under the store lock."""
499
+ with self._lock:
500
+ enrollment = self._records.get(user_id)
501
+ if enrollment is None or not enrollment.enabled:
502
+ return False
503
+
504
+ step = verify_totp(
505
+ enrollment.secret,
506
+ code,
507
+ timestamp=timestamp,
508
+ last_step=enrollment.last_step,
509
+ )
510
+ if step is not None:
511
+ self._records[user_id] = MFAEnrollment(
512
+ user_id=enrollment.user_id,
513
+ secret=enrollment.secret,
514
+ enabled=True,
515
+ last_step=step,
516
+ recovery_hashes=enrollment.recovery_hashes,
517
+ created_at=enrollment.created_at,
518
+ )
519
+ return True
520
+
521
+ cleaned = code.strip().upper()
522
+ for idx, hashed in enumerate(enrollment.recovery_hashes):
523
+ if check_password_hash(hashed, cleaned):
524
+ remaining = (
525
+ enrollment.recovery_hashes[:idx]
526
+ + enrollment.recovery_hashes[idx + 1 :]
527
+ )
528
+ self._records[user_id] = MFAEnrollment(
529
+ user_id=enrollment.user_id,
530
+ secret=enrollment.secret,
531
+ enabled=True,
532
+ last_step=enrollment.last_step,
533
+ recovery_hashes=remaining,
534
+ created_at=enrollment.created_at,
535
+ )
536
+ return True
537
+ return False
538
+
539
+
540
+ class SQLAlchemyMFAStore(MFAStore):
541
+ """Persistent SQLAlchemy 2.0 MFA enrollment store (auto-creates `_flask_deck_mfa`)."""
542
+
543
+ __slots__ = ("_engine", "_table")
544
+
545
+ def __init__(self, engine: Engine, *, table_name: str = "_flask_deck_mfa") -> None:
546
+ self._engine = engine
547
+ metadata = sa.MetaData()
548
+ self._table = sa.Table(
549
+ table_name,
550
+ metadata,
551
+ sa.Column("user_id", sa.String(128), primary_key=True),
552
+ sa.Column("secret", sa.String(128), nullable=False),
553
+ sa.Column("enabled", sa.Boolean, nullable=False, default=True),
554
+ sa.Column("last_step", sa.Integer, nullable=True),
555
+ sa.Column("recovery_hashes_json", sa.Text, nullable=False, default="[]"),
556
+ sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
557
+ )
558
+ metadata.create_all(engine, checkfirst=True)
559
+
560
+ def get(self, user_id: str) -> MFAEnrollment | None:
561
+ with Session(self._engine) as sess:
562
+ row = sess.execute(
563
+ sa.select(self._table).where(self._table.c.user_id == user_id)
564
+ ).mappings().first()
565
+ if row is None:
566
+ return None
567
+ raw_hashes = json.loads(str(row["recovery_hashes_json"] or "[]"))
568
+ return MFAEnrollment(
569
+ user_id=str(row["user_id"]),
570
+ secret=str(row["secret"]),
571
+ enabled=bool(row["enabled"]),
572
+ last_step=int(row["last_step"]) if row["last_step"] is not None else None,
573
+ recovery_hashes=tuple(str(h) for h in raw_hashes),
574
+ created_at=row["created_at"],
575
+ )
576
+
577
+ def save(self, enrollment: MFAEnrollment) -> None:
578
+ now = enrollment.created_at or datetime.now(timezone.utc)
579
+ hashes_json = json.dumps(list(enrollment.recovery_hashes))
580
+ with Session(self._engine) as sess:
581
+ existing = sess.execute(
582
+ sa.select(self._table.c.user_id).where(self._table.c.user_id == enrollment.user_id)
583
+ ).first()
584
+ if existing is None:
585
+ sess.execute(
586
+ self._table.insert().values(
587
+ user_id=enrollment.user_id,
588
+ secret=enrollment.secret,
589
+ enabled=enrollment.enabled,
590
+ last_step=enrollment.last_step,
591
+ recovery_hashes_json=hashes_json,
592
+ created_at=now,
593
+ )
594
+ )
595
+ else:
596
+ sess.execute(
597
+ self._table.update()
598
+ .where(self._table.c.user_id == enrollment.user_id)
599
+ .values(
600
+ secret=enrollment.secret,
601
+ enabled=enrollment.enabled,
602
+ last_step=enrollment.last_step,
603
+ recovery_hashes_json=hashes_json,
604
+ )
605
+ )
606
+ sess.commit()
607
+
608
+ def delete(self, user_id: str) -> None:
609
+ with Session(self._engine) as sess:
610
+ sess.execute(self._table.delete().where(self._table.c.user_id == user_id))
611
+ sess.commit()
612
+
613
+ def verify_and_record(
614
+ self,
615
+ user_id: str,
616
+ code: str,
617
+ *,
618
+ timestamp: float | None = None,
619
+ ) -> bool:
620
+ """Atomically verify TOTP / recovery code with compare-and-swap SQL updates."""
621
+ with Session(self._engine) as sess:
622
+ row = (
623
+ sess.execute(
624
+ sa.select(self._table).where(self._table.c.user_id == user_id)
625
+ )
626
+ .mappings()
627
+ .first()
628
+ )
629
+ if row is None or not bool(row["enabled"]):
630
+ return False
631
+
632
+ secret = str(row["secret"])
633
+ last_step = int(row["last_step"]) if row["last_step"] is not None else None
634
+ old_hashes_json = str(row["recovery_hashes_json"] or "[]")
635
+ raw_hashes = tuple(str(h) for h in json.loads(old_hashes_json))
636
+
637
+ step = verify_totp(secret, code, timestamp=timestamp, last_step=last_step)
638
+ if step is not None:
639
+ res = sess.execute(
640
+ self._table.update()
641
+ .where(
642
+ self._table.c.user_id == user_id,
643
+ self._table.c.enabled.is_(True),
644
+ sa.or_(
645
+ self._table.c.last_step.is_(None),
646
+ self._table.c.last_step < step,
647
+ ),
648
+ )
649
+ .values(last_step=step)
650
+ )
651
+ sess.commit()
652
+ return bool(getattr(res, "rowcount", 0) == 1)
653
+
654
+ cleaned = code.strip().upper()
655
+ for idx, hashed in enumerate(raw_hashes):
656
+ if check_password_hash(hashed, cleaned):
657
+ remaining = raw_hashes[:idx] + raw_hashes[idx + 1 :]
658
+ new_hashes_json = json.dumps(list(remaining))
659
+ res = sess.execute(
660
+ self._table.update()
661
+ .where(
662
+ self._table.c.user_id == user_id,
663
+ self._table.c.enabled.is_(True),
664
+ self._table.c.recovery_hashes_json == old_hashes_json,
665
+ )
666
+ .values(recovery_hashes_json=new_hashes_json)
667
+ )
668
+ sess.commit()
669
+ return bool(getattr(res, "rowcount", 0) == 1)
670
+ return False