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/deck.py ADDED
@@ -0,0 +1,4153 @@
1
+ from __future__ import annotations
2
+
3
+ import enum
4
+ import gzip
5
+ import hashlib
6
+ import io
7
+ import json
8
+ import logging
9
+ import time
10
+ from collections.abc import Callable, Iterator, Mapping, Sequence
11
+ from dataclasses import dataclass
12
+ from datetime import datetime, timezone
13
+ from pathlib import Path
14
+ from typing import Any
15
+ from urllib.parse import urlencode
16
+
17
+ import sqlalchemy as sa
18
+ from flask import (
19
+ Blueprint,
20
+ Flask,
21
+ Response,
22
+ abort,
23
+ flash,
24
+ g,
25
+ jsonify,
26
+ redirect,
27
+ render_template,
28
+ request,
29
+ session,
30
+ stream_with_context,
31
+ url_for,
32
+ )
33
+ from markupsafe import Markup
34
+ from sqlalchemy.engine import Engine
35
+ from sqlalchemy.exc import IntegrityError, SQLAlchemyError
36
+ from sqlalchemy.orm import Session, sessionmaker
37
+
38
+ from flask_deck.adapters.sqlalchemy import (
39
+ ORMAdapter,
40
+ decode_pk,
41
+ encode_pk,
42
+ extract_pk,
43
+ resolve_adapter,
44
+ )
45
+ from flask_deck.audit import (
46
+ AuditEntry,
47
+ AuditStore,
48
+ SQLAlchemyAuditStore,
49
+ compute_diff,
50
+ make_audit_entry,
51
+ )
52
+ from flask_deck.auth import AuthProvider, DeckUser, OpenAuthProvider, RBACAuthProvider
53
+ from flask_deck.branding import render_brand_css, render_safe_slot
54
+ from flask_deck.config import DeckConfig
55
+ from flask_deck.dashboard import (
56
+ ActivityWidget,
57
+ DashboardBuilder,
58
+ DashboardContext,
59
+ Widget,
60
+ build_default_dashboard,
61
+ )
62
+ from flask_deck.events import DeckEvent, DeckEventBus, EventListener, WebhookSink
63
+ from flask_deck.exceptions import (
64
+ ImportLimitError,
65
+ InvalidPKError,
66
+ PermissionDeniedError,
67
+ ReadOnlyError,
68
+ SecurityConfigurationError,
69
+ ValidationError,
70
+ )
71
+ from flask_deck.exporter import iter_export_chunks, stream_export_response
72
+ from flask_deck.i18n import (
73
+ CURATED_TIMEZONES,
74
+ LOCALE_LABELS,
75
+ LOCALE_SESSION_KEY,
76
+ TZ_SESSION_KEY,
77
+ DictTranslator,
78
+ Translator,
79
+ is_valid_timezone,
80
+ normalize_locale,
81
+ set_request_locale_tz,
82
+ to_user_timezone,
83
+ )
84
+ from flask_deck.icons import render_icon
85
+ from flask_deck.importer import (
86
+ ImportPreviewStore,
87
+ commit_dry_run_import,
88
+ run_dry_run_import,
89
+ )
90
+ from flask_deck.introspection import ModelMeta
91
+ from flask_deck.jobs import (
92
+ TERMINAL_JOB_STATUSES,
93
+ JobBackend,
94
+ JobContext,
95
+ JobRecord,
96
+ ThreadPoolJobBackend,
97
+ )
98
+ from flask_deck.mfa import (
99
+ MFA_PENDING_AT_KEY,
100
+ MFA_PENDING_NEXT_KEY,
101
+ MFA_PENDING_SSO_KEY,
102
+ MFA_PENDING_USER_KEY,
103
+ MFA_VERIFIED_KEY,
104
+ InMemoryMFAStore,
105
+ MFAEnrollment,
106
+ MFAStore,
107
+ SQLAlchemyMFAStore,
108
+ build_otpauth_uri,
109
+ generate_recovery_codes,
110
+ generate_totp_secret,
111
+ render_qr_svg,
112
+ verify_totp,
113
+ )
114
+ from flask_deck.model_view import ModelView, coerce_form_value
115
+ from flask_deck.query import (
116
+ apply_list_load_options,
117
+ attach_sql_telemetry,
118
+ begin_request_telemetry,
119
+ build_filter_condition,
120
+ build_search_clause,
121
+ compute_page_aggregates,
122
+ execute_kanban_query,
123
+ execute_list_query,
124
+ get_request_telemetry,
125
+ soft_delete_predicate,
126
+ )
127
+ from flask_deck.schema_graph import render_schema_erd_svg
128
+ from flask_deck.security import (
129
+ CSRF_FORM_FIELD,
130
+ CSRF_SESSION_KEY,
131
+ LoginRateLimiter,
132
+ apply_security_headers,
133
+ generate_nonce,
134
+ get_csrf_token,
135
+ is_safe_redirect_url,
136
+ is_sensitive_field,
137
+ rotate_csrf_token,
138
+ validate_csrf,
139
+ )
140
+ from flask_deck.sql_console import (
141
+ SQLQueryResult,
142
+ execute_readonly_sql,
143
+ format_sql_result_csv,
144
+ )
145
+ from flask_deck.sso import OIDCAuthProvider
146
+ from flask_deck.storage import (
147
+ RASTER_INLINE_MIMES,
148
+ MemoryFileStorage,
149
+ StorageBackend,
150
+ build_storage_key,
151
+ sanitize_filename,
152
+ )
153
+
154
+ IMPERSONATOR_USER_KEY = "_deck_impersonator_id"
155
+ IMPERSONATED_USER_KEY = "_deck_impersonated_id"
156
+ IMPERSONATE_RO_KEY = "_deck_impersonate_ro"
157
+ MFA_SETUP_SECRET_KEY = "_deck_mfa_setup_secret"
158
+ MFA_PENDING_TTL_SECONDS = 300
159
+ _RESERVED_MODEL_SLUGS: frozenset[str] = frozenset(
160
+ {"login", "logout", "static", "_audit", "_rbac", "_schema", "_diagnostics", "_sql", "_jobs", "_page", "_api", "_media", "_theme.css", "_preferences", "_security", "_impersonate", "_demo"}
161
+ )
162
+
163
+ logger = logging.getLogger("flask_deck")
164
+
165
+ _PKG_DIR = Path(__file__).resolve().parent
166
+ _STATIC_DIR = _PKG_DIR / "static"
167
+ _TEMPLATE_DIR = _PKG_DIR / "templates"
168
+
169
+
170
+ def _file_hash(path: Path) -> str:
171
+ if not path.is_file():
172
+ return "dev"
173
+ return hashlib.sha256(path.read_bytes()).hexdigest()[:10]
174
+
175
+
176
+ def _client_ip() -> str:
177
+ # Do not trust spoofable X-Forwarded-For unless ProxyFix is explicitly configured on app.
178
+ return str(request.remote_addr or "127.0.0.1")
179
+
180
+
181
+ @dataclass(frozen=True, slots=True)
182
+ class PageSpec:
183
+ """Declarative custom operational page registered via ``@deck.page``."""
184
+
185
+ slug: str
186
+ title: str
187
+ handler: Callable[[DashboardContext], Sequence[Widget]]
188
+ icon: str = "terminal"
189
+ category: str = "Operations"
190
+ subtitle: str = ""
191
+ permission: str | None = None
192
+
193
+
194
+ class Deck:
195
+ """Modern Carbon Dark & Swiss Light admin panel and operations workbench for Flask."""
196
+
197
+ def __init__(
198
+ self,
199
+ app: Flask | None = None,
200
+ db: Any | None = None,
201
+ *,
202
+ session_factory: sessionmaker[Session] | Callable[[], Session] | None = None,
203
+ engine: Engine | None = None,
204
+ binds: Mapping[str, Engine] | None = None,
205
+ auth: AuthProvider | None = None,
206
+ audit_store: AuditStore | bool | None = None,
207
+ mfa_store: MFAStore | bool | None = None,
208
+ translator: Translator | None = None,
209
+ job_backend: JobBackend | None = None,
210
+ job_storage: StorageBackend | None = None,
211
+ config: DeckConfig | None = None,
212
+ demo_credentials: Sequence[tuple[str, str, str]] = (),
213
+ sql_presets: Sequence[tuple[str, str]] = (),
214
+ **config_kwargs: Any,
215
+ ) -> None:
216
+ if config is not None and config_kwargs:
217
+ raise ValueError("Pass either config=DeckConfig(...) or keyword arguments, not both")
218
+ self.config: DeckConfig = config or DeckConfig(**config_kwargs)
219
+ self._explicit_auth: AuthProvider | None = auth
220
+ self.auth: AuthProvider = auth or OpenAuthProvider()
221
+ self._audit_store_arg: AuditStore | bool | None = audit_store
222
+ self.audit_store: AuditStore | None = (
223
+ audit_store if isinstance(audit_store, AuditStore) else None
224
+ )
225
+ self._mfa_store_arg: MFAStore | bool | None = mfa_store
226
+ self.mfa_store: MFAStore | None = mfa_store if isinstance(mfa_store, MFAStore) else None
227
+ self.translator: Translator = translator or DictTranslator(
228
+ default_locale=self.config.default_locale
229
+ )
230
+ self.job_backend: JobBackend | None = job_backend or (
231
+ ThreadPoolJobBackend() if self.config.enable_jobs else None
232
+ )
233
+ self.job_storage: StorageBackend = job_storage or MemoryFileStorage()
234
+ if isinstance(self.job_backend, ThreadPoolJobBackend):
235
+ self.job_backend.set_on_evict(self._cleanup_evicted_job_artifact)
236
+ self.events: DeckEventBus = DeckEventBus()
237
+ self._brand_css_bytes, self._brand_css_hash = render_brand_css(self.config.brand)
238
+ self.adapter: ORMAdapter | None = None
239
+ self.app: Flask | None = None
240
+ self.blueprint: Blueprint | None = None
241
+ self.views: dict[str, ModelView] = {}
242
+ self._views_by_model: dict[type[Any], ModelView] = {}
243
+ self.custom_pages: dict[str, PageSpec] = {}
244
+ self._dashboard_builder: DashboardBuilder | None = None
245
+ self._rate_limiter = LoginRateLimiter(
246
+ max_attempts=self.config.login_rate_limit_attempts,
247
+ window_seconds=self.config.login_rate_limit_window_seconds,
248
+ lockout_seconds=self.config.login_rate_limit_lockout_seconds,
249
+ )
250
+ self._preview_store = ImportPreviewStore(
251
+ ttl_seconds=self.config.import_preview_ttl_seconds,
252
+ max_entries=self.config.import_preview_max_entries,
253
+ )
254
+ self._asset_hashes: dict[str, str] = {}
255
+ self._demo_credentials = tuple(demo_credentials)
256
+ self._sql_presets = tuple(sql_presets)
257
+
258
+ if db is not None or session_factory is not None or engine is not None:
259
+ self.adapter = resolve_adapter(
260
+ db, session_factory=session_factory, engine=engine, binds=binds
261
+ )
262
+
263
+ if app is not None:
264
+ self.init_app(app)
265
+
266
+ def _cleanup_evicted_job_artifact(self, rec: JobRecord) -> None:
267
+ if rec.artifact_key:
268
+ try:
269
+ self.job_storage.delete(rec.artifact_key)
270
+ except Exception as exc:
271
+ logger.warning("Failed to delete evicted job artifact %s: %s", rec.artifact_key, exc)
272
+
273
+ def close(self) -> None:
274
+ """Dispose database engine pools and stop background job worker threads cleanly."""
275
+ if isinstance(self.job_backend, ThreadPoolJobBackend):
276
+ self.job_backend.shutdown(wait=False, cancel_futures=True)
277
+ if self.adapter is not None:
278
+ self.adapter.dispose()
279
+
280
+ def init_app(
281
+ self,
282
+ app: Flask,
283
+ db: Any | None = None,
284
+ *,
285
+ session_factory: sessionmaker[Session] | Callable[[], Session] | None = None,
286
+ engine: Engine | None = None,
287
+ binds: Mapping[str, Engine] | None = None,
288
+ ) -> None:
289
+ """Bind Deck to a Flask application (supports Flask App Factory pattern)."""
290
+ if db is not None or session_factory is not None or engine is not None:
291
+ self.adapter = resolve_adapter(
292
+ db, session_factory=session_factory, engine=engine, binds=binds
293
+ )
294
+ if self.adapter is None:
295
+ raise ValueError("Deck requires a Flask-SQLAlchemy db, sessionmaker, engine, or ORMAdapter.")
296
+
297
+ # Fail-closed security check: refuse silent unauthenticated production mounts!
298
+ if self._explicit_auth is None:
299
+ if self.config.allow_insecure_open:
300
+ self.auth = OpenAuthProvider()
301
+ elif app.debug or app.testing:
302
+ self.auth = OpenAuthProvider()
303
+ if not app.testing:
304
+ logger.warning(
305
+ "Flask-Deck running with OpenAuthProvider in debug mode. "
306
+ "Configure an explicit AuthProvider before deploying."
307
+ )
308
+ else:
309
+ raise SecurityConfigurationError(
310
+ "Refusing to mount Flask-Deck without an explicit AuthProvider while "
311
+ "app.debug is False. Pass auth=BasicAuthProvider(...), RBACAuthProvider(...), "
312
+ "FlaskLoginAuthProvider(...), or explicitly allow_insecure_open=True for local dev."
313
+ )
314
+
315
+ if not app.secret_key:
316
+ if not (app.debug or app.testing):
317
+ raise SecurityConfigurationError(
318
+ "Flask app.secret_key must be configured for CSRF and session security."
319
+ )
320
+ logger.warning("Flask app.secret_key is unset; sessions and CSRF require a secret key.")
321
+
322
+ self.app = app
323
+ self.adapter.register_teardown(app)
324
+
325
+ # Initialize default SQLAlchemyAuditStore when auto_audit is enabled and not read_only.
326
+ if (
327
+ self.config.auto_audit
328
+ and not self.config.read_only
329
+ and self._audit_store_arg is None
330
+ and self.audit_store is None
331
+ ):
332
+ with app.app_context():
333
+ self.audit_store = SQLAlchemyAuditStore(self.adapter.get_engine())
334
+ elif self._audit_store_arg is False:
335
+ self.audit_store = None
336
+
337
+ # Initialize default MFAStore independently of auto_audit (avoid DDL when read_only=True)
338
+ if self._mfa_store_arg is False:
339
+ self.mfa_store = None
340
+ elif self.mfa_store is None:
341
+ if not self.config.read_only:
342
+ with app.app_context():
343
+ self.mfa_store = SQLAlchemyMFAStore(self.adapter.get_engine())
344
+ else:
345
+ self.mfa_store = InMemoryMFAStore()
346
+
347
+ if self.config.enable_sql_telemetry:
348
+ with app.app_context():
349
+ for eng in self.adapter.get_engines().values():
350
+ attach_sql_telemetry(eng)
351
+
352
+ self._asset_hashes = {
353
+ "css/deck.css": _file_hash(_STATIC_DIR / "css" / "deck.css"),
354
+ "js/deck.js": _file_hash(_STATIC_DIR / "js" / "deck.js"),
355
+ }
356
+
357
+ bp = self._build_blueprint()
358
+ self.blueprint = bp
359
+ app.register_blueprint(bp, url_prefix=self.config.url_prefix)
360
+
361
+ decks: dict[str, Deck] = app.extensions.setdefault("flask_deck", {})
362
+ decks[self.config.name] = self
363
+
364
+ # ------------------------------------------------------------------
365
+ # Registration API
366
+ # ------------------------------------------------------------------
367
+
368
+ def register(self, *models_or_views: type[Any] | ModelView) -> Deck:
369
+ """Register one or more SQLAlchemy model classes or ModelView classes/instances."""
370
+ for item in models_or_views:
371
+ if isinstance(item, ModelView):
372
+ self.register_view(item)
373
+ elif isinstance(item, type) and issubclass(item, ModelView):
374
+ self.register_view(
375
+ item(extra_sensitive_patterns=self.config.extra_sensitive_patterns)
376
+ )
377
+ else:
378
+ view = ModelView(
379
+ item,
380
+ extra_sensitive_patterns=self.config.extra_sensitive_patterns,
381
+ )
382
+ self.register_view(view)
383
+ return self
384
+
385
+ def register_view(self, view: ModelView) -> Deck:
386
+ """Register a concrete ModelView instance."""
387
+ if view.meta.slug in _RESERVED_MODEL_SLUGS:
388
+ raise ValueError(f"Model slug {view.meta.slug!r} conflicts with a built-in Deck route.")
389
+ if view.meta.slug in self.views:
390
+ raise ValueError(f"Duplicate Deck model slug: {view.meta.slug!r}")
391
+ self.views[view.meta.slug] = view
392
+ self._views_by_model[view.model] = view
393
+ return self
394
+
395
+ def dashboard(self, fn: DashboardBuilder) -> DashboardBuilder:
396
+ """Decorator registering a custom dashboard widget builder callback."""
397
+ self._dashboard_builder = fn
398
+ return fn
399
+
400
+ def page(
401
+ self,
402
+ slug: str,
403
+ *,
404
+ title: str,
405
+ icon: str = "terminal",
406
+ category: str = "Operations",
407
+ subtitle: str = "",
408
+ permission: str | None = None,
409
+ ) -> Callable[[Callable[[DashboardContext], Sequence[Widget]]], Callable[[DashboardContext], Sequence[Widget]]]:
410
+ """Decorator registering a custom widget-composed operational page in the workbench."""
411
+ clean_slug = slug.strip().strip("/").lower()
412
+ if not clean_slug or "/" in clean_slug:
413
+ raise ValueError("Custom page slug must be a single non-empty URL segment")
414
+
415
+ def decorator(
416
+ fn: Callable[[DashboardContext], Sequence[Widget]],
417
+ ) -> Callable[[DashboardContext], Sequence[Widget]]:
418
+ self.custom_pages[clean_slug] = PageSpec(
419
+ slug=clean_slug,
420
+ title=title,
421
+ handler=fn,
422
+ icon=icon,
423
+ category=category,
424
+ subtitle=subtitle,
425
+ permission=permission,
426
+ )
427
+ return fn
428
+
429
+ return decorator
430
+
431
+ def on(self, event_name: str) -> Callable[[EventListener], EventListener]:
432
+ """Decorator subscribing a lifecycle event listener (e.g. 'record.created', '*')."""
433
+
434
+ def decorator(fn: EventListener) -> EventListener:
435
+ self.events.subscribe(event_name, fn)
436
+ return fn
437
+
438
+ return decorator
439
+
440
+ def add_webhook(self, sink: WebhookSink) -> Deck:
441
+ """Register an SSRF-hardened HMAC-signed WebhookSink on the event bus."""
442
+ self.events.subscribe("*", sink)
443
+ return self
444
+
445
+ def url_for_model(self, model_or_slug: type[Any] | str) -> str | None:
446
+ slug = (
447
+ model_or_slug
448
+ if isinstance(model_or_slug, str)
449
+ else (
450
+ self._views_by_model[model_or_slug].meta.slug
451
+ if model_or_slug in self._views_by_model
452
+ else None
453
+ )
454
+ )
455
+ if slug is None or slug not in self.views:
456
+ return None
457
+ return url_for(f"{self.config.name}.model_list", slug=slug)
458
+
459
+ def get_view(self, slug: str) -> ModelView:
460
+ view = self.views.get(slug)
461
+ if view is None:
462
+ abort(404)
463
+ return view
464
+
465
+ def get_session(self, bind_key: str | None = None) -> Session:
466
+ assert self.adapter is not None
467
+ return self.adapter.get_session_for_bind(bind_key)
468
+
469
+ # ------------------------------------------------------------------
470
+ # Helpers
471
+ # ------------------------------------------------------------------
472
+
473
+ def _current_user(self) -> DeckUser | None:
474
+ user: DeckUser | None = getattr(g, "_deck_user", None)
475
+ return user
476
+
477
+ def _real_user(self) -> DeckUser | None:
478
+ real: DeckUser | None = getattr(g, "_deck_real_user", None)
479
+ return real or self._current_user()
480
+
481
+ def _cursor_secret(self) -> bytes:
482
+ raw = self.app.secret_key if self.app is not None else None
483
+ if isinstance(raw, bytes):
484
+ return raw
485
+ if isinstance(raw, str) and raw:
486
+ return raw.encode()
487
+ return b"flask-deck-default-cursor-key"
488
+
489
+ def _media_url_builder(self, view: ModelView) -> Callable[[str, Any], str | None]:
490
+ bp_name = self.config.name
491
+ slug = view.meta.slug
492
+
493
+ def _build(field_name: str, obj: Any) -> str | None:
494
+ if field_name not in view.file_fields or obj is None:
495
+ return None
496
+ if not getattr(obj, field_name, None):
497
+ return None
498
+ pk_str = encode_pk(extract_pk(obj, view.meta))
499
+ return url_for(f"{bp_name}.serve_media", slug=slug, field_name=field_name, raw_pk=pk_str)
500
+
501
+ return _build
502
+
503
+ def _rel_repr(self, target_model: type[Any], item: Any) -> str:
504
+ """Render a related ORM instance while honoring RBAC masked/hidden field policies."""
505
+ user = self._current_user()
506
+ target_view = self._views_by_model.get(target_model)
507
+ if target_view is not None:
508
+ return target_view.format_record_repr(item, auth=self.auth, user=user)
509
+ return str(item)
510
+
511
+ def _is_soft_deleted(self, view: ModelView, obj: Any) -> bool:
512
+ if not view.soft_delete_column:
513
+ return False
514
+ sd_val = getattr(obj, view.soft_delete_column, None)
515
+ return bool(sd_val) if isinstance(sd_val, bool) else (sd_val is not None)
516
+
517
+ def _sanitize_audit_entry(self, entry: AuditEntry, user: DeckUser | None) -> AuditEntry:
518
+ """Strip RBAC hidden fields and redact masked/sensitive fields from an AuditEntry for viewer."""
519
+ if not entry.changes:
520
+ return entry
521
+ view = self.views.get(entry.model_slug)
522
+ hidden = self.auth.hidden_fields_for(user, entry.model_slug)
523
+ masked = self.auth.masked_fields_for(user, entry.model_slug)
524
+ sensitive = view.meta.sensitive_fields if view is not None else frozenset()
525
+ if not hidden and not masked and not sensitive:
526
+ return entry
527
+ clean_changes: dict[str, dict[str, Any]] = {}
528
+ for fname, delta in entry.changes.items():
529
+ if fname in hidden:
530
+ continue
531
+ if fname in masked or fname in sensitive or is_sensitive_field(
532
+ fname, self.config.extra_sensitive_patterns
533
+ ):
534
+ clean_changes[fname] = {
535
+ "old": "[REDACTED]" if delta.get("old") is not None else None,
536
+ "new": "[REDACTED]" if delta.get("new") is not None else None,
537
+ }
538
+ else:
539
+ clean_changes[fname] = delta
540
+ return AuditEntry(
541
+ id=entry.id,
542
+ timestamp=entry.timestamp,
543
+ actor_id=entry.actor_id,
544
+ actor_name=entry.actor_name,
545
+ actor_ip=entry.actor_ip,
546
+ action=entry.action,
547
+ model_slug=entry.model_slug,
548
+ model_label=entry.model_label,
549
+ record_pk=entry.record_pk,
550
+ record_repr=entry.record_repr,
551
+ changes=clean_changes,
552
+ metadata=entry.metadata,
553
+ )
554
+
555
+ def _allowed_query_fields(
556
+ self, view: ModelView, user: DeckUser | None
557
+ ) -> tuple[tuple[str, ...], frozenset[str], frozenset[str]]:
558
+ """Filter searchable, filterable, and sortable columns by viewer's hidden/masked RBAC rules."""
559
+ restricted = self.auth.hidden_fields_for(user, view.meta.slug) | self.auth.masked_fields_for(
560
+ user, view.meta.slug
561
+ )
562
+ searchable: list[str] = []
563
+ for col_spec in view.resolved_searchable:
564
+ if "." in col_spec:
565
+ rel_name, target_col = col_spec.split(".", 1)
566
+ if rel_name in restricted:
567
+ continue
568
+ rel_meta = view.meta.relationships_by_name.get(rel_name)
569
+ if rel_meta is not None:
570
+ t_view = self._views_by_model.get(rel_meta.target_model)
571
+ if t_view is not None:
572
+ t_restricted = self.auth.hidden_fields_for(
573
+ user, t_view.meta.slug
574
+ ) | self.auth.masked_fields_for(user, t_view.meta.slug)
575
+ if target_col in t_restricted or target_col in t_view.meta.sensitive_fields:
576
+ continue
577
+ searchable.append(col_spec)
578
+ elif col_spec not in restricted:
579
+ searchable.append(col_spec)
580
+ return (
581
+ tuple(searchable),
582
+ view.resolved_filterable - restricted,
583
+ view.resolved_sortable - restricted,
584
+ )
585
+
586
+ def _collect_orphan_files(self, view: ModelView, obj: Any) -> list[tuple[Any, str]]:
587
+ """Return (FileFieldConfig, key) pairs marked delete_orphan=True on a record."""
588
+ out: list[tuple[Any, str]] = []
589
+ for field_name, cfg in view.file_fields.items():
590
+ if not cfg.delete_orphan:
591
+ continue
592
+ key = getattr(obj, field_name, None)
593
+ if isinstance(key, str) and key:
594
+ out.append((cfg, key))
595
+ return out
596
+
597
+ def _delete_orphan_files_best_effort(self, orphans: Sequence[tuple[Any, str]]) -> None:
598
+ for fcfg, old_key in orphans:
599
+ try:
600
+ fcfg.storage.delete(old_key)
601
+ except Exception as exc:
602
+ logger.warning("Failed to delete orphan storage object %s: %s", old_key, exc)
603
+
604
+ def _emit_event(
605
+ self,
606
+ name: str,
607
+ *,
608
+ model_slug: str = "",
609
+ record_pk: str = "",
610
+ payload: dict[str, Any] | None = None,
611
+ actor: DeckUser | None = None,
612
+ ) -> None:
613
+ user = actor if actor is not None else self._current_user()
614
+ event_payload = dict(payload or {})
615
+ real = getattr(g, "_deck_real_user", None)
616
+ if real is not None and (user is None or real.id != user.id):
617
+ event_payload.setdefault("impersonated_by", real.id)
618
+ event_payload.setdefault("impersonated_by_name", real.label)
619
+ self.events.emit(
620
+ DeckEvent(
621
+ name=name,
622
+ actor_id=user.id if user else "system",
623
+ actor_name=user.label if user else "System",
624
+ model_slug=model_slug,
625
+ record_pk=record_pk,
626
+ payload=event_payload,
627
+ )
628
+ )
629
+
630
+ def _require_perm(self, permission: str, *, model_slug: str | None = None, obj: Any = None) -> None:
631
+ user = self._current_user()
632
+ if not self.auth.has_permission(user, permission, model_slug=model_slug, obj=obj):
633
+ raise PermissionDeniedError(f"Missing permission: {permission}")
634
+
635
+ def _fetch_scoped_record(self, view: ModelView, raw_pk: str) -> tuple[Any, tuple[Any, ...]]:
636
+ pk_values = decode_pk(raw_pk, view.meta)
637
+ stmt = view.scope_query(sa.select(view.model), self._current_user())
638
+ for pk_field, val in zip(view.meta.primary_keys, pk_values, strict=True):
639
+ stmt = stmt.where(getattr(view.model, pk_field.name) == val)
640
+ stmt = apply_list_load_options(
641
+ stmt,
642
+ view.meta,
643
+ tuple(r.name for r in view.meta.relationships),
644
+ defer_unshown_heavy=False,
645
+ )
646
+ obj = self.get_session(view.bind_key).scalars(stmt).unique().first()
647
+ if obj is None:
648
+ abort(404)
649
+ return obj, pk_values
650
+
651
+ def _record_audit(
652
+ self,
653
+ *,
654
+ action_name: str,
655
+ view: ModelView,
656
+ record_pk: str,
657
+ record_repr: str,
658
+ changes: dict[str, dict[str, Any]] | None = None,
659
+ metadata: dict[str, Any] | None = None,
660
+ ) -> AuditEntry | None:
661
+ if self.audit_store is None or not self.config.auto_audit:
662
+ return None
663
+ user = self._current_user()
664
+ meta = dict(metadata or {})
665
+ real = getattr(g, "_deck_real_user", None)
666
+ if real is not None and (user is None or real.id != user.id):
667
+ meta["impersonated_by"] = real.id
668
+ meta["impersonated_by_name"] = real.label
669
+ entry = make_audit_entry(
670
+ actor_id=user.id if user else "system",
671
+ actor_name=user.label if user else "System",
672
+ actor_ip=_client_ip(),
673
+ action=action_name,
674
+ model_slug=view.meta.slug,
675
+ model_label=view.label,
676
+ record_pk=record_pk,
677
+ record_repr=record_repr,
678
+ changes=changes,
679
+ metadata=meta,
680
+ )
681
+ return self.audit_store.record(entry)
682
+
683
+ def _sidebar_groups(self) -> list[dict[str, Any]]:
684
+ """Build grouped sidebar navigation with ALL primary-bind row counts in ONE SQL query."""
685
+ user = self._current_user()
686
+ authorized: list[ModelView] = [
687
+ v
688
+ for v in self.views.values()
689
+ if v.can_view and self.auth.has_permission(user, f"{v.meta.slug}:view", model_slug=v.meta.slug)
690
+ ]
691
+
692
+ counts: dict[str, int] = {}
693
+ by_bind: dict[str | None, list[ModelView]] = {}
694
+ for v in authorized:
695
+ by_bind.setdefault(v.bind_key, []).append(v)
696
+
697
+ for bk, b_views in by_bind.items():
698
+ subqueries = []
699
+ for v in b_views:
700
+ scoped = v.scope_query(sa.select(sa.func.count()).select_from(v.model), user)
701
+ sd_pred = soft_delete_predicate(v.meta, v.soft_delete_column, trashed=False)
702
+ if sd_pred is not None:
703
+ scoped = scoped.where(sd_pred)
704
+ subqueries.append(scoped.scalar_subquery().label(v.meta.slug))
705
+ row = self.get_session(bk).execute(sa.select(*subqueries)).first()
706
+ if row is not None:
707
+ for idx, v in enumerate(b_views):
708
+ counts[v.meta.slug] = int(row[idx] or 0)
709
+
710
+ groups_map: dict[str, list[dict[str, Any]]] = {}
711
+ for v in authorized:
712
+ groups_map.setdefault(v.category, []).append(
713
+ {
714
+ "slug": v.meta.slug,
715
+ "label": v.plural_label,
716
+ "icon": v.icon,
717
+ "count": counts.get(v.meta.slug, 0),
718
+ "url": url_for(f"{self.config.name}.model_list", slug=v.meta.slug),
719
+ "is_page": False,
720
+ }
721
+ )
722
+ for p in self.custom_pages.values():
723
+ page_allowed = (
724
+ self.auth.has_permission(user, p.permission)
725
+ if p.permission
726
+ else (
727
+ self.auth.has_permission(user, f"page:{p.slug}:view")
728
+ or self.auth.has_permission(user, "*:view")
729
+ )
730
+ )
731
+ if page_allowed:
732
+ groups_map.setdefault(p.category, []).append(
733
+ {
734
+ "slug": f"_page:{p.slug}",
735
+ "label": p.title,
736
+ "icon": p.icon,
737
+ "count": None,
738
+ "url": url_for(f"{self.config.name}.custom_page", page_slug=p.slug),
739
+ "is_page": True,
740
+ }
741
+ )
742
+ return [{"name": cat, "links": items} for cat, items in groups_map.items()]
743
+
744
+ def _asset_url(self, filename: str) -> str:
745
+ ver = self._asset_hashes.get(filename) or _file_hash(_STATIC_DIR / filename)
746
+ return url_for(f"{self.config.name}.static", filename=filename, v=ver)
747
+
748
+ def _base_context(self, **extra: Any) -> dict[str, Any]:
749
+ user = self._current_user()
750
+ real_user = getattr(g, "_deck_real_user", None)
751
+ is_impersonating = real_user is not None
752
+ tel = get_request_telemetry()
753
+ bp_name = self.config.name
754
+ can_audit = self.audit_store is not None and self.auth.has_permission(user, "audit:view")
755
+ can_rbac = bool(self.auth.get_roles()) and self.auth.has_permission(user, "rbac:view")
756
+ can_schema = self.auth.has_permission(user, "schema:view") or self.auth.has_permission(
757
+ user, "*:view"
758
+ )
759
+ can_diagnostics = self.auth.has_permission(user, "diagnostics:view") or (
760
+ user is not None and user.is_superuser
761
+ )
762
+ can_sql = self.config.enable_sql_console and self.auth.has_permission(user, "sql:query")
763
+ can_jobs = self.job_backend is not None and user is not None
764
+ can_mfa = self.mfa_store is not None and user is not None and self.auth.supports_login_form
765
+ demo_accounts: Sequence[DeckUser] = ()
766
+ if (
767
+ self.config.demo_role_switcher
768
+ and self.config.environment != "production"
769
+ and isinstance(self.auth, RBACAuthProvider)
770
+ ):
771
+ demo_accounts = self.auth.get_demo_accounts()
772
+
773
+ impersonate_targets: Sequence[DeckUser] = ()
774
+ if (
775
+ self.config.enable_impersonation
776
+ and not is_impersonating
777
+ and user is not None
778
+ and user.is_superuser
779
+ and isinstance(self.auth, RBACAuthProvider)
780
+ ):
781
+ impersonate_targets = tuple(
782
+ acc
783
+ for acc in self.auth.get_demo_accounts()
784
+ if acc.id != user.id and not acc.is_superuser
785
+ )
786
+
787
+ active_locale = self.translator.get_locale()
788
+ active_tz = str(getattr(g, "_flask_deck_tz", self.config.default_timezone))
789
+ text_dir = "rtl" if self.translator.is_rtl(active_locale) else "ltr"
790
+
791
+ ctx: dict[str, Any] = {
792
+ "deck": self,
793
+ "config": self.config,
794
+ "brand": self.config.brand,
795
+ "brand_css_hash": self._brand_css_hash,
796
+ "bp_name": bp_name,
797
+ "current_user": user,
798
+ "impersonator": real_user,
799
+ "is_impersonating": is_impersonating,
800
+ "impersonate_read_only": bool(
801
+ session.get(IMPERSONATE_RO_KEY, self.config.impersonate_read_only)
802
+ )
803
+ if is_impersonating
804
+ else False,
805
+ "impersonate_targets": impersonate_targets,
806
+ "csrf_token": get_csrf_token(),
807
+ "csrf_field": CSRF_FORM_FIELD,
808
+ "csp_nonce": getattr(g, "_deck_csp_nonce", ""),
809
+ "sidebar_groups": self._sidebar_groups() if user is not None else [],
810
+ "deck_icon": render_icon,
811
+ "asset_url": self._asset_url,
812
+ "can_view_audit": can_audit,
813
+ "can_view_rbac": can_rbac,
814
+ "can_view_schema": can_schema,
815
+ "can_view_diagnostics": can_diagnostics,
816
+ "can_view_sql": can_sql,
817
+ "can_view_jobs": can_jobs,
818
+ "can_manage_mfa": can_mfa,
819
+ "demo_accounts": demo_accounts,
820
+ "supports_logout": self.auth.supports_login_form,
821
+ "sso_providers": (
822
+ self.auth.get_sso_providers() if isinstance(self.auth, OIDCAuthProvider) else ()
823
+ ),
824
+ "telemetry": tel,
825
+ "encode_pk": encode_pk,
826
+ "extract_pk": extract_pk,
827
+ "is_insecure_open": isinstance(self.auth, OpenAuthProvider),
828
+ "_": self.translator.translate,
829
+ "active_locale": active_locale,
830
+ "active_timezone": active_tz,
831
+ "text_dir": text_dir,
832
+ "available_locales": self.config.available_locales,
833
+ "locale_labels": LOCALE_LABELS,
834
+ "curated_timezones": CURATED_TIMEZONES,
835
+ "rel_repr": self._rel_repr,
836
+ "format_dt": lambda dt, fmt="%Y-%m-%d %H:%M": (
837
+ to_user_timezone(dt, active_tz).strftime(fmt) if isinstance(dt, datetime) else str(dt)
838
+ ),
839
+ }
840
+ ctx.update(extra)
841
+ ctx["render_slot"] = lambda slot_name: render_safe_slot(
842
+ self.config.brand, slot_name, ctx, template_renderer=render_template
843
+ )
844
+ return ctx
845
+
846
+ def _fk_options_for_field(
847
+ self,
848
+ target_model: type[Any],
849
+ limit: int = 50,
850
+ *,
851
+ fallback_bind_key: str | None = None,
852
+ current_value: Any = None,
853
+ ) -> list[dict[str, str]]:
854
+ user = self._current_user()
855
+ target_view = self._views_by_model.get(target_model)
856
+ stmt = sa.select(target_model)
857
+ bind_key = fallback_bind_key
858
+ if target_view is not None:
859
+ stmt = target_view.scope_query(stmt, user)
860
+ sd_pred = soft_delete_predicate(
861
+ target_view.meta, target_view.soft_delete_column, trashed=False
862
+ )
863
+ if sd_pred is not None:
864
+ stmt = stmt.where(sd_pred)
865
+ meta = target_view.meta
866
+ bind_key = target_view.bind_key
867
+ else:
868
+ from flask_deck.introspection import introspect_model
869
+
870
+ meta = introspect_model(target_model)
871
+ sess = self.get_session(bind_key)
872
+ stmt = stmt.order_by(getattr(target_model, meta.primary_keys[0].name).asc()).limit(limit)
873
+ items = list(sess.scalars(stmt).all())
874
+ options: list[dict[str, str]] = []
875
+ seen_ids: set[str] = set()
876
+ for item in items:
877
+ pk_val = encode_pk(extract_pk(item, meta))
878
+ seen_ids.add(pk_val)
879
+ label = (
880
+ target_view.format_record_repr(item, auth=self.auth, user=user)
881
+ if target_view
882
+ else str(item)
883
+ )
884
+ options.append({"id": pk_val, "label": label})
885
+
886
+ # Ensure currently selected FK value beyond row `limit` is still loaded and labelled cleanly
887
+ if current_value is not None and str(current_value) not in seen_ids and len(meta.primary_keys) == 1:
888
+ try:
889
+ cur_pk = decode_pk(str(current_value), meta)
890
+ cur_stmt = sa.select(target_model).where(
891
+ getattr(target_model, meta.primary_keys[0].name) == cur_pk[0]
892
+ )
893
+ if target_view is not None:
894
+ cur_stmt = target_view.scope_query(cur_stmt, user)
895
+ cur_obj = sess.scalars(cur_stmt).first()
896
+ if cur_obj is not None:
897
+ pk_str = encode_pk(extract_pk(cur_obj, meta))
898
+ lbl = (
899
+ target_view.format_record_repr(cur_obj, auth=self.auth, user=user)
900
+ if target_view
901
+ else str(cur_obj)
902
+ )
903
+ options.insert(0, {"id": pk_str, "label": lbl})
904
+ except InvalidPKError:
905
+ pass
906
+ return options
907
+
908
+ def _build_form_context(
909
+ self,
910
+ view: ModelView,
911
+ *,
912
+ obj: Any | None,
913
+ mode: str,
914
+ errors: dict[str, list[str]] | None = None,
915
+ submitted: Mapping[str, Any] | None = None,
916
+ ) -> dict[str, Any]:
917
+ user = self._current_user()
918
+ visible = view.visible_form_fields(self.auth, user)
919
+ readonly = self.auth.readonly_fields_for(user, view.meta.slug)
920
+ masked = self.auth.masked_fields_for(user, view.meta.slug)
921
+
922
+ # Resolve fieldsets (either declarative or single default group)
923
+ if view.fieldsets:
924
+ fieldsets: list[tuple[str, list[str]]] = []
925
+ used: set[str] = set()
926
+ for title, cols in view.fieldsets:
927
+ kept = [c for c in cols if c in visible]
928
+ if kept:
929
+ fieldsets.append((title, kept))
930
+ used.update(kept)
931
+ remaining = [c for c in visible if c not in used]
932
+ if remaining:
933
+ fieldsets.append(("Additional Fields", remaining))
934
+ else:
935
+ fieldsets = [(f"{view.label} Details", list(visible))]
936
+
937
+ field_specs: dict[str, dict[str, Any]] = {}
938
+ for col_name in visible:
939
+ fmeta = view.meta.fields_by_name.get(col_name)
940
+ rel_meta = view.meta.relationships_by_name.get(col_name)
941
+ is_ro = (
942
+ (col_name in readonly or col_name in masked) and mode == "edit"
943
+ ) or (fmeta is not None and fmeta.primary_key and mode == "edit")
944
+
945
+ if fmeta is not None:
946
+ if col_name in masked and mode == "edit":
947
+ raw_val = self.auth.mask_field_value(
948
+ user,
949
+ view.meta.slug,
950
+ col_name,
951
+ getattr(obj, col_name, None) if obj is not None else None,
952
+ )
953
+ elif submitted is not None:
954
+ if fmeta.field_type == "boolean":
955
+ raw_val = str(submitted.get(col_name, "")).strip().lower() in {
956
+ "1",
957
+ "true",
958
+ "yes",
959
+ "on",
960
+ }
961
+ elif col_name in submitted:
962
+ raw_val = submitted.get(col_name)
963
+ else:
964
+ raw_val = getattr(obj, col_name, None) if obj is not None else None
965
+ else:
966
+ raw_val = getattr(obj, col_name, None) if obj is not None else None
967
+ if (
968
+ raw_val is not None
969
+ and fmeta.enum_class is not None
970
+ and isinstance(raw_val, fmeta.enum_class)
971
+ ):
972
+ raw_val = raw_val.value
973
+ elif isinstance(raw_val, datetime):
974
+ raw_val = to_user_timezone(raw_val).strftime("%Y-%m-%dT%H:%M")
975
+ elif fmeta.field_type == "json" and isinstance(raw_val, (dict, list)):
976
+ raw_val = json.dumps(raw_val, indent=2)
977
+ elif fmeta.field_type == "array" and isinstance(raw_val, (list, tuple)):
978
+ raw_val = json.dumps(list(raw_val))
979
+
980
+ fk_options: list[dict[str, str]] = []
981
+ fk_search_url: str | None = None
982
+ fk_current_label = ""
983
+ if fmeta.fk_target_model is not None:
984
+ fk_options = self._fk_options_for_field(
985
+ fmeta.fk_target_model,
986
+ fallback_bind_key=view.bind_key,
987
+ current_value=raw_val,
988
+ )
989
+ target_v = self._views_by_model.get(fmeta.fk_target_model)
990
+ if target_v is not None:
991
+ fk_search_url = url_for(f"{self.config.name}.api_fk", slug=target_v.meta.slug)
992
+ if raw_val is not None:
993
+ for opt in fk_options:
994
+ if opt["id"] == str(raw_val):
995
+ fk_current_label = opt["label"]
996
+ break
997
+
998
+ file_cfg = view.file_fields.get(col_name)
999
+ media_url: str | None = None
1000
+ if file_cfg is not None and obj is not None and raw_val:
1001
+ pk_str_cur = encode_pk(extract_pk(obj, view.meta))
1002
+ media_url = url_for(
1003
+ f"{self.config.name}.serve_media",
1004
+ slug=view.meta.slug,
1005
+ field_name=col_name,
1006
+ raw_pk=pk_str_cur,
1007
+ )
1008
+
1009
+ cond_rule = view.field_conditions.get(col_name)
1010
+ show_when_json = (
1011
+ json.dumps({"field": cond_rule[0], "op": cond_rule[1], "value": cond_rule[2]})
1012
+ if cond_rule is not None
1013
+ else ""
1014
+ )
1015
+ dep_rule = view.dependent_fields.get(col_name)
1016
+ dependent_json = (
1017
+ json.dumps({"parent": dep_rule[0], "filter_col": dep_rule[1]})
1018
+ if dep_rule is not None
1019
+ else ""
1020
+ )
1021
+
1022
+ widget_override = view.field_widgets.get(col_name, "")
1023
+ kind = (
1024
+ "file"
1025
+ if file_cfg is not None
1026
+ else ("fk" if fmeta.fk_target_model is not None else fmeta.field_type)
1027
+ )
1028
+ field_specs[col_name] = {
1029
+ "kind": kind,
1030
+ "widget": widget_override,
1031
+ "file_kind": file_cfg.kind if file_cfg is not None else "",
1032
+ "file_accept": ",".join(sorted(file_cfg.resolved_allowed_mimes()))
1033
+ if file_cfg is not None
1034
+ else "",
1035
+ "media_url": media_url,
1036
+ "show_when_json": show_when_json,
1037
+ "dependent_json": dependent_json,
1038
+ "name": col_name,
1039
+ "label": view.get_column_label(col_name),
1040
+ "required": (not fmeta.nullable and not fmeta.has_default and not fmeta.autoincrement),
1041
+ "readonly": is_ro,
1042
+ "masked": col_name in masked,
1043
+ "value": "" if raw_val is None else raw_val,
1044
+ "choices": fmeta.choices,
1045
+ "max_length": fmeta.max_length,
1046
+ "fk_options": fk_options,
1047
+ "fk_search_url": fk_search_url,
1048
+ "fk_current_label": fk_current_label,
1049
+ }
1050
+ elif rel_meta is not None and rel_meta.direction == "MANYTOMANY":
1051
+ options = self._fk_options_for_field(
1052
+ rel_meta.target_model,
1053
+ limit=100,
1054
+ fallback_bind_key=view.bind_key,
1055
+ )
1056
+ selected_ids: set[str] = set()
1057
+ if submitted is not None and hasattr(submitted, "getlist"):
1058
+ selected_ids = {str(v) for v in submitted.getlist(col_name) if v}
1059
+ elif obj is not None:
1060
+ from flask_deck.introspection import introspect_model
1061
+
1062
+ t_meta = introspect_model(rel_meta.target_model)
1063
+ for item in getattr(obj, col_name, []) or []:
1064
+ selected_ids.add(encode_pk(extract_pk(item, t_meta)))
1065
+ field_specs[col_name] = {
1066
+ "kind": "m2m",
1067
+ "name": col_name,
1068
+ "label": view.get_column_label(col_name),
1069
+ "required": False,
1070
+ "readonly": is_ro,
1071
+ "masked": False,
1072
+ "options": options,
1073
+ "selected_ids": selected_ids,
1074
+ }
1075
+
1076
+ # Inline child rows (routed to view.bind_key!)
1077
+ inlines_ctx: list[dict[str, Any]] = []
1078
+ parent_pk = (
1079
+ getattr(obj, view.meta.primary_keys[0].name, None) if obj is not None else None
1080
+ )
1081
+ for inline in view.inline_views:
1082
+ fk_col = inline.resolve_fk_column(view.meta)
1083
+ existing_rows: list[Any] = []
1084
+ if parent_pk is not None:
1085
+ existing_rows = list(
1086
+ self.get_session(view.bind_key)
1087
+ .scalars(
1088
+ sa.select(inline.model)
1089
+ .where(getattr(inline.model, fk_col) == parent_pk)
1090
+ .order_by(getattr(inline.model, inline.meta.primary_keys[0].name).asc())
1091
+ )
1092
+ .all()
1093
+ )
1094
+ col_specs = []
1095
+ for col in inline.editable_columns:
1096
+ fm = inline.meta.fields_by_name[col]
1097
+ fk_opts = (
1098
+ self._fk_options_for_field(
1099
+ fm.fk_target_model, fallback_bind_key=view.bind_key
1100
+ )
1101
+ if fm.fk_target_model is not None
1102
+ else []
1103
+ )
1104
+ col_specs.append(
1105
+ {
1106
+ "name": col,
1107
+ "label": fm.label,
1108
+ "kind": "fk" if fm.fk_target_model is not None else fm.field_type,
1109
+ "choices": fm.choices,
1110
+ "fk_options": fk_opts,
1111
+ }
1112
+ )
1113
+ rows_data = []
1114
+ pk_name = inline.meta.primary_keys[0].name
1115
+ for r in existing_rows:
1116
+ vals: dict[str, Any] = {}
1117
+ for col in inline.editable_columns:
1118
+ v = getattr(r, col, None)
1119
+ if isinstance(v, enum.Enum):
1120
+ v = v.value
1121
+ vals[col] = "" if v is None else v
1122
+ rows_data.append({"pk": str(getattr(r, pk_name)), "values": vals})
1123
+
1124
+ inlines_ctx.append(
1125
+ {
1126
+ "slug": inline.meta.slug,
1127
+ "label": inline.display_label,
1128
+ "columns": col_specs,
1129
+ "rows": rows_data,
1130
+ "can_create": inline.can_create,
1131
+ "can_delete": inline.can_delete,
1132
+ }
1133
+ )
1134
+
1135
+ return {
1136
+ "view": view,
1137
+ "obj": obj,
1138
+ "mode": mode,
1139
+ "fieldsets": fieldsets,
1140
+ "field_specs": field_specs,
1141
+ "inlines": inlines_ctx,
1142
+ "errors": errors or {},
1143
+ "has_file_fields": any(c in view.file_fields for c in visible),
1144
+ }
1145
+
1146
+ # ------------------------------------------------------------------
1147
+ # Blueprint & Routes
1148
+ # ------------------------------------------------------------------
1149
+
1150
+ def _build_blueprint(self) -> Blueprint:
1151
+ bp = Blueprint(
1152
+ self.config.name,
1153
+ __name__,
1154
+ template_folder=str(_TEMPLATE_DIR),
1155
+ static_folder=str(_STATIC_DIR),
1156
+ static_url_path="/static",
1157
+ )
1158
+ deck = self
1159
+ bp_name = self.config.name
1160
+
1161
+ @bp.before_request
1162
+ def _before_deck_request() -> Response | None:
1163
+ endpoint = request.endpoint or ""
1164
+ if endpoint in {f"{bp_name}.static", f"{bp_name}.brand_theme_css"}:
1165
+ return None
1166
+
1167
+ nonce = (
1168
+ deck.config.csp_nonce_getter()
1169
+ if deck.config.csp_nonce_getter is not None
1170
+ else generate_nonce()
1171
+ )
1172
+ g._deck_csp_nonce = nonce
1173
+ if deck.config.enable_sql_telemetry:
1174
+ begin_request_telemetry()
1175
+
1176
+ # Resolve request locale & timezone safely
1177
+ raw_loc = (
1178
+ deck.config.locale_selector()
1179
+ if deck.config.locale_selector is not None
1180
+ else str(session.get(LOCALE_SESSION_KEY, deck.config.default_locale))
1181
+ )
1182
+ norm_loc = normalize_locale(raw_loc, deck.config.default_locale)
1183
+ if deck.config.available_locales and norm_loc not in deck.config.available_locales:
1184
+ norm_loc = deck.config.default_locale
1185
+ raw_tz = (
1186
+ deck.config.timezone_selector()
1187
+ if deck.config.timezone_selector is not None
1188
+ else str(session.get(TZ_SESSION_KEY, deck.config.default_timezone))
1189
+ )
1190
+ valid_tz = raw_tz if is_valid_timezone(raw_tz) else deck.config.default_timezone
1191
+ set_request_locale_tz(norm_loc, valid_tz)
1192
+
1193
+ is_public_auth = endpoint in {
1194
+ f"{bp_name}.login",
1195
+ f"{bp_name}.login_mfa",
1196
+ f"{bp_name}.sso_login",
1197
+ f"{bp_name}.sso_callback",
1198
+ }
1199
+ is_logout = endpoint == f"{bp_name}.logout"
1200
+ is_readonly_post = endpoint in {
1201
+ f"{bp_name}.sql_console",
1202
+ f"{bp_name}.demo_switch_role",
1203
+ f"{bp_name}.update_preferences",
1204
+ f"{bp_name}.impersonate_stop",
1205
+ f"{bp_name}.model_export_async",
1206
+ }
1207
+ is_api = endpoint.startswith(f"{bp_name}.api_")
1208
+
1209
+ # 1. Server-side read_only guard
1210
+ if (
1211
+ deck.config.read_only
1212
+ and request.method not in {"GET", "HEAD", "OPTIONS"}
1213
+ and not (is_public_auth or is_logout or is_readonly_post)
1214
+ ):
1215
+ if is_api:
1216
+ return jsonify({"error": "Flask-Deck is running in read-only mode."}), 403 # type: ignore[return-value]
1217
+ abort(403, description="Flask-Deck is running in read-only mode.")
1218
+
1219
+ # 2. Strict CSRF + Origin/Sec-Fetch-Site validation on EVERY mutation
1220
+ if request.method in {"POST", "PUT", "PATCH", "DELETE"} and not validate_csrf(request):
1221
+ if is_api:
1222
+ return jsonify({"error": "Invalid or missing CSRF token."}), 403 # type: ignore[return-value]
1223
+ abort(403, description="Invalid or missing CSRF token.")
1224
+
1225
+ # 3. Authentication, session timeout & audited impersonation resolution
1226
+ real_user = deck.auth.get_current_user(
1227
+ idle_timeout=deck.config.session_idle_timeout_seconds,
1228
+ absolute_timeout=deck.config.session_absolute_timeout_seconds,
1229
+ )
1230
+ effective_user = real_user
1231
+ g._deck_real_user = None
1232
+ imp_target_id = session.get(IMPERSONATED_USER_KEY)
1233
+ imp_actor_id = session.get(IMPERSONATOR_USER_KEY)
1234
+ if (
1235
+ real_user is not None
1236
+ and real_user.is_superuser
1237
+ and isinstance(imp_target_id, str)
1238
+ and imp_target_id
1239
+ and imp_actor_id == real_user.id
1240
+ and isinstance(deck.auth, RBACAuthProvider)
1241
+ ):
1242
+ target = deck.auth.get_account_by_id(imp_target_id)
1243
+ if target is not None and not target.is_superuser:
1244
+ g._deck_real_user = real_user
1245
+ effective_user = target
1246
+ # Server config impersonate_read_only=True can never be weakened by a stale session cookie
1247
+ enforced_imp_ro = deck.config.impersonate_read_only or bool(
1248
+ session.get(IMPERSONATE_RO_KEY, True)
1249
+ )
1250
+ if (
1251
+ enforced_imp_ro
1252
+ and request.method not in {"GET", "HEAD", "OPTIONS"}
1253
+ and not (is_logout or is_readonly_post)
1254
+ ):
1255
+ if is_api:
1256
+ return (
1257
+ jsonify({"error": "Mutations are disabled during read-only impersonation."}),
1258
+ 403,
1259
+ ) # type: ignore[return-value]
1260
+ raise ReadOnlyError(
1261
+ "Mutations are disabled during read-only impersonation. Exit impersonation first."
1262
+ )
1263
+ else:
1264
+ session.pop(IMPERSONATED_USER_KEY, None)
1265
+ session.pop(IMPERSONATOR_USER_KEY, None)
1266
+
1267
+ g._deck_user = effective_user
1268
+
1269
+ if is_public_auth:
1270
+ return None
1271
+
1272
+ if effective_user is None:
1273
+ if is_api:
1274
+ return jsonify({"error": "Authentication required."}), 401 # type: ignore[return-value]
1275
+ if deck.auth.supports_login_form:
1276
+ next_target = request.full_path.rstrip("?")
1277
+ if not is_safe_redirect_url(next_target):
1278
+ next_target = url_for(f"{bp_name}.index")
1279
+ return redirect(url_for(f"{bp_name}.login", next=next_target)) # type: ignore[return-value]
1280
+ abort(403, description="Authentication required.")
1281
+
1282
+ # 4. Enforce require_mfa_for_superusers whenever configured with an active MFA store
1283
+ if (
1284
+ deck.config.require_mfa_for_superusers
1285
+ and deck.mfa_store is not None
1286
+ and real_user is not None
1287
+ and real_user.is_superuser
1288
+ and endpoint not in {f"{bp_name}.security_mfa", f"{bp_name}.logout", f"{bp_name}.update_preferences"}
1289
+ ):
1290
+ enr = deck.mfa_store.get(real_user.id)
1291
+ enrolled = enr is not None and enr.enabled
1292
+ if not enrolled:
1293
+ if is_api:
1294
+ return jsonify({"error": "MFA enrollment is required for superusers."}), 403 # type: ignore[return-value]
1295
+ flash("Superuser accounts must enroll in Two-Factor Authentication before continuing.", "warn")
1296
+ return redirect(url_for(f"{bp_name}.security_mfa")) # type: ignore[return-value]
1297
+ if deck.auth.supports_login_form and not bool(session.get(MFA_VERIFIED_KEY)):
1298
+ if is_api:
1299
+ return jsonify({"error": "MFA verification required."}), 401 # type: ignore[return-value]
1300
+ session[MFA_PENDING_USER_KEY] = real_user.id
1301
+ session[MFA_PENDING_AT_KEY] = int(time.time())
1302
+ return redirect(url_for(f"{bp_name}.login_mfa")) # type: ignore[return-value]
1303
+ return None
1304
+
1305
+ @bp.after_request
1306
+ def _after_deck_request(response: Response) -> Response:
1307
+ ep = request.endpoint or ""
1308
+ is_static = ep in {f"{bp_name}.static", f"{bp_name}.brand_theme_css"}
1309
+ nonce = getattr(g, "_deck_csp_nonce", "") or generate_nonce()
1310
+ return apply_security_headers(
1311
+ response,
1312
+ nonce=nonce,
1313
+ is_static=is_static,
1314
+ has_version_hash=bool(request.args.get("v")),
1315
+ extra_img_sources=deck.config.csp_img_sources,
1316
+ )
1317
+
1318
+ @bp.errorhandler(PermissionDeniedError)
1319
+ def _handle_perm(exc: PermissionDeniedError) -> tuple[Any, int]:
1320
+ if (request.endpoint or "").startswith(f"{bp_name}.api_"):
1321
+ return jsonify({"error": str(exc)}), 403
1322
+ return (
1323
+ render_template(
1324
+ "flask_deck/error.html",
1325
+ **deck._base_context(
1326
+ status_code=403,
1327
+ error_title="Access Denied",
1328
+ error_message=str(exc),
1329
+ ),
1330
+ ),
1331
+ 403,
1332
+ )
1333
+
1334
+ @bp.errorhandler(ReadOnlyError)
1335
+ def _handle_ro(exc: ReadOnlyError) -> tuple[Any, int]:
1336
+ if (request.endpoint or "").startswith(f"{bp_name}.api_"):
1337
+ return jsonify({"error": str(exc)}), 403
1338
+ return (
1339
+ render_template(
1340
+ "flask_deck/error.html",
1341
+ **deck._base_context(
1342
+ status_code=403,
1343
+ error_title="Read-Only Mode",
1344
+ error_message=str(exc),
1345
+ ),
1346
+ ),
1347
+ 403,
1348
+ )
1349
+
1350
+ @bp.errorhandler(InvalidPKError)
1351
+ def _handle_invalid_pk(_exc: InvalidPKError) -> tuple[Any, int]:
1352
+ if (request.endpoint or "").startswith(f"{bp_name}.api_"):
1353
+ return jsonify({"error": "Record not found."}), 404
1354
+ return (
1355
+ render_template(
1356
+ "flask_deck/error.html",
1357
+ **deck._base_context(
1358
+ status_code=404,
1359
+ error_title="Record Not Found",
1360
+ error_message="The requested identifier is invalid or does not exist.",
1361
+ ),
1362
+ ),
1363
+ 404,
1364
+ )
1365
+
1366
+ # ---- Authentication ----
1367
+
1368
+ @bp.route("/login", methods=["GET", "POST"])
1369
+ def login() -> Any:
1370
+ if not deck.auth.supports_login_form:
1371
+ abort(404)
1372
+ if deck._current_user() is not None:
1373
+ return redirect(url_for(f"{bp_name}.index"))
1374
+
1375
+ next_url = request.args.get("next") or request.form.get("next") or ""
1376
+ error_msg = ""
1377
+ retry_after = 0
1378
+
1379
+ if request.method == "POST":
1380
+ username = request.form.get("username", "").strip()
1381
+ password = request.form.get("password", "")
1382
+ ip = _client_ip()
1383
+ locked, retry_after = deck._rate_limiter.is_locked(ip, username)
1384
+ if locked:
1385
+ error_msg = f"Too many failed attempts. Try again in {retry_after}s."
1386
+ resp = Response(
1387
+ render_template(
1388
+ "flask_deck/login.html",
1389
+ **deck._base_context(
1390
+ next_url=next_url,
1391
+ error_msg=error_msg,
1392
+ demo_credentials=deck._demo_credentials,
1393
+ ),
1394
+ ),
1395
+ status=429,
1396
+ )
1397
+ resp.headers["Retry-After"] = str(retry_after)
1398
+ return resp
1399
+
1400
+ user = deck.auth.authenticate(username, password)
1401
+ if user is not None:
1402
+ deck._rate_limiter.record_success(ip, username)
1403
+ dest = next_url if is_safe_redirect_url(next_url) else url_for(f"{bp_name}.index")
1404
+ if deck.mfa_store is not None:
1405
+ enrollment = deck.mfa_store.get(user.id)
1406
+ if enrollment is not None and enrollment.enabled:
1407
+ session.clear()
1408
+ session[MFA_PENDING_USER_KEY] = user.id
1409
+ session[MFA_PENDING_NEXT_KEY] = dest
1410
+ session[MFA_PENDING_AT_KEY] = int(time.time())
1411
+ rotate_csrf_token()
1412
+ return redirect(url_for(f"{bp_name}.login_mfa"))
1413
+ deck.auth.login_user(user)
1414
+ return redirect(dest)
1415
+
1416
+ deck._rate_limiter.record_failure(ip, username)
1417
+ deck._emit_event("login.failed", payload={"username": username, "ip": ip})
1418
+ error_msg = "Invalid username or password."
1419
+
1420
+ return render_template(
1421
+ "flask_deck/login.html",
1422
+ **deck._base_context(
1423
+ next_url=next_url,
1424
+ error_msg=error_msg,
1425
+ demo_credentials=deck._demo_credentials,
1426
+ ),
1427
+ )
1428
+
1429
+ @bp.route("/login/mfa", methods=["GET", "POST"])
1430
+ def login_mfa() -> Any:
1431
+ if deck.mfa_store is None:
1432
+ abort(404)
1433
+ pending_uid = session.get(MFA_PENDING_USER_KEY)
1434
+ pending_at = session.get(MFA_PENDING_AT_KEY)
1435
+ if not isinstance(pending_uid, str) or not pending_uid:
1436
+ return redirect(url_for(f"{bp_name}.login"))
1437
+ if isinstance(pending_at, int) and (int(time.time()) - pending_at) > MFA_PENDING_TTL_SECONDS:
1438
+ session.pop(MFA_PENDING_USER_KEY, None)
1439
+ session.pop(MFA_PENDING_NEXT_KEY, None)
1440
+ session.pop(MFA_PENDING_AT_KEY, None)
1441
+ session.pop(MFA_PENDING_SSO_KEY, None)
1442
+ flash("MFA verification window expired. Please sign in again.", "warn")
1443
+ return redirect(url_for(f"{bp_name}.login"))
1444
+
1445
+ error_msg = ""
1446
+ if request.method == "POST":
1447
+ ip = _client_ip()
1448
+ locked, retry_after = deck._rate_limiter.is_locked(ip, f"mfa:{pending_uid}")
1449
+ if locked:
1450
+ resp = Response(
1451
+ render_template(
1452
+ "flask_deck/login_mfa.html",
1453
+ **deck._base_context(
1454
+ error_msg=f"Too many failed MFA attempts. Retry in {retry_after}s."
1455
+ ),
1456
+ ),
1457
+ status=429,
1458
+ )
1459
+ resp.headers["Retry-After"] = str(retry_after)
1460
+ return resp
1461
+
1462
+ code = request.form.get("code", "").strip()
1463
+ if deck.mfa_store.verify_and_record(pending_uid, code):
1464
+ deck._rate_limiter.record_success(ip, f"mfa:{pending_uid}")
1465
+ dest_raw = str(session.pop(MFA_PENDING_NEXT_KEY, ""))
1466
+ pending_sso = session.pop(MFA_PENDING_SSO_KEY, None)
1467
+ session.pop(MFA_PENDING_USER_KEY, None)
1468
+ session.pop(MFA_PENDING_AT_KEY, None)
1469
+ target_user: DeckUser | None = None
1470
+ if isinstance(pending_sso, Mapping) and str(pending_sso.get("id")) == pending_uid:
1471
+ target_user = DeckUser(
1472
+ id=pending_uid,
1473
+ username=str(pending_sso.get("username", pending_uid)),
1474
+ display_name=str(pending_sso.get("display_name", "")),
1475
+ email=str(pending_sso.get("email", "")),
1476
+ roles=tuple(str(r) for r in pending_sso.get("roles", ())),
1477
+ is_superuser=bool(pending_sso.get("is_superuser", False)),
1478
+ )
1479
+ else:
1480
+ target_user = deck.auth.get_user_by_id(pending_uid)
1481
+ if target_user is None:
1482
+ return redirect(url_for(f"{bp_name}.login"))
1483
+ deck.auth.login_user(target_user)
1484
+ session[MFA_VERIFIED_KEY] = True
1485
+ dest = dest_raw if is_safe_redirect_url(dest_raw) else url_for(f"{bp_name}.index")
1486
+ return redirect(dest)
1487
+
1488
+ deck._rate_limiter.record_failure(ip, f"mfa:{pending_uid}")
1489
+ deck._emit_event("mfa.failed", payload={"user_id": pending_uid, "ip": ip})
1490
+ error_msg = "Invalid or already-used verification code."
1491
+
1492
+ return render_template(
1493
+ "flask_deck/login_mfa.html",
1494
+ **deck._base_context(error_msg=error_msg),
1495
+ )
1496
+
1497
+ @bp.route("/login/sso/<provider_name>")
1498
+ def sso_login(provider_name: str) -> Any:
1499
+ if not isinstance(deck.auth, OIDCAuthProvider):
1500
+ abort(404)
1501
+ if deck.auth.get_sso_provider(provider_name) is None:
1502
+ abort(404)
1503
+ next_url = request.args.get("next", "").strip()
1504
+ callback_uri = url_for(
1505
+ f"{bp_name}.sso_callback",
1506
+ provider_name=provider_name,
1507
+ _external=True,
1508
+ )
1509
+ auth_url = deck.auth.build_authorize_redirect(
1510
+ provider_name,
1511
+ redirect_uri=callback_uri,
1512
+ next_url=next_url if is_safe_redirect_url(next_url) else "",
1513
+ )
1514
+ return redirect(auth_url)
1515
+
1516
+ @bp.route("/login/sso/<provider_name>/callback")
1517
+ def sso_callback(provider_name: str) -> Any:
1518
+ if not isinstance(deck.auth, OIDCAuthProvider):
1519
+ abort(404)
1520
+ if deck.auth.get_sso_provider(provider_name) is None:
1521
+ abort(404)
1522
+ callback_uri = url_for(
1523
+ f"{bp_name}.sso_callback",
1524
+ provider_name=provider_name,
1525
+ _external=True,
1526
+ )
1527
+ try:
1528
+ sso_user, next_url = deck.auth.complete_callback(
1529
+ provider_name,
1530
+ code=request.args.get("code", "").strip(),
1531
+ state=request.args.get("state", "").strip(),
1532
+ redirect_uri=callback_uri,
1533
+ )
1534
+ except (PermissionError, ValueError, OSError) as exc:
1535
+ deck._emit_event(
1536
+ "login.failed",
1537
+ payload={"provider": provider_name, "error": str(exc)},
1538
+ )
1539
+ return (
1540
+ render_template(
1541
+ "flask_deck/login.html",
1542
+ **deck._base_context(
1543
+ next_url="",
1544
+ error_msg=f"SSO sign-in failed: {exc}",
1545
+ demo_credentials=deck._demo_credentials,
1546
+ ),
1547
+ ),
1548
+ 403,
1549
+ )
1550
+ dest = next_url if is_safe_redirect_url(next_url) else url_for(f"{bp_name}.index")
1551
+ if deck.mfa_store is not None:
1552
+ enrollment = deck.mfa_store.get(sso_user.id)
1553
+ if enrollment is not None and enrollment.enabled:
1554
+ session.clear()
1555
+ session[MFA_PENDING_USER_KEY] = sso_user.id
1556
+ session[MFA_PENDING_NEXT_KEY] = dest
1557
+ session[MFA_PENDING_AT_KEY] = int(time.time())
1558
+ session[MFA_PENDING_SSO_KEY] = {
1559
+ "id": sso_user.id,
1560
+ "username": sso_user.username,
1561
+ "display_name": sso_user.display_name,
1562
+ "email": sso_user.email,
1563
+ "roles": list(sso_user.roles),
1564
+ "is_superuser": sso_user.is_superuser,
1565
+ }
1566
+ rotate_csrf_token()
1567
+ return redirect(url_for(f"{bp_name}.login_mfa"))
1568
+ deck.auth.login_user(sso_user)
1569
+ return redirect(dest)
1570
+
1571
+ @bp.route("/logout", methods=["POST"])
1572
+ def logout() -> Any:
1573
+ deck.auth.logout_user()
1574
+ if deck.auth.supports_login_form:
1575
+ return redirect(url_for(f"{bp_name}.login"))
1576
+ return redirect(url_for(f"{bp_name}.index"))
1577
+
1578
+ # ---- Brand Theme CSS (strict style-src 'self'), Preferences & Authorized Media Proxy ----
1579
+
1580
+ @bp.route("/_theme.css")
1581
+ def brand_theme_css() -> Response:
1582
+ return Response(deck._brand_css_bytes, mimetype="text/css; charset=utf-8")
1583
+
1584
+ @bp.route("/_preferences", methods=["POST"])
1585
+ def update_preferences() -> Any:
1586
+ if not deck.config.enable_user_preferences:
1587
+ abort(404)
1588
+ req_locale = request.form.get("locale", "").strip()
1589
+ req_tz = request.form.get("timezone", "").strip()
1590
+ if req_locale:
1591
+ norm = normalize_locale(req_locale)
1592
+ if deck.config.available_locales and norm not in deck.config.available_locales:
1593
+ abort(400, description="Unsupported locale.")
1594
+ session[LOCALE_SESSION_KEY] = norm
1595
+ if req_tz:
1596
+ if not is_valid_timezone(req_tz):
1597
+ abort(400, description="Invalid IANA timezone.")
1598
+ session[TZ_SESSION_KEY] = req_tz
1599
+ nxt = request.form.get("next", "").strip()
1600
+ dest = nxt if is_safe_redirect_url(nxt) else url_for(f"{bp_name}.index")
1601
+ return redirect(dest)
1602
+
1603
+ @bp.route("/_media/<slug>/<field_name>/<raw_pk>")
1604
+ def serve_media(slug: str, field_name: str, raw_pk: str) -> Response:
1605
+ view = deck.get_view(slug)
1606
+ if not view.can_view:
1607
+ abort(404)
1608
+ deck._require_perm(f"{slug}:view", model_slug=slug)
1609
+ cfg = view.file_fields.get(field_name)
1610
+ if cfg is None:
1611
+ abort(404)
1612
+ user = deck._current_user()
1613
+ if (
1614
+ field_name in deck.auth.hidden_fields_for(user, slug)
1615
+ or field_name in deck.auth.masked_fields_for(user, slug)
1616
+ ):
1617
+ abort(403)
1618
+ obj, _ = deck._fetch_scoped_record(view, raw_pk)
1619
+ deck._require_perm(f"{slug}:view", model_slug=slug, obj=obj)
1620
+ if deck._is_soft_deleted(view, obj):
1621
+ abort(404)
1622
+ key = getattr(obj, field_name, None)
1623
+ if not key or not isinstance(key, str):
1624
+ abort(404)
1625
+ try:
1626
+ stream, detected_mime = cfg.storage.open(key)
1627
+ except (FileNotFoundError, ValueError):
1628
+ abort(404)
1629
+ try:
1630
+ data = stream.read()
1631
+ finally:
1632
+ stream.close()
1633
+
1634
+ mime = detected_mime or "application/octet-stream"
1635
+ is_inline_raster = mime in RASTER_INLINE_MIMES
1636
+ safe_name = sanitize_filename(key.rsplit("/", 1)[-1])
1637
+ disposition = "inline" if is_inline_raster else "attachment"
1638
+ resp = Response(data, mimetype=mime)
1639
+ resp.headers["Content-Disposition"] = f'{disposition}; filename="{safe_name}"'
1640
+ resp.headers["Content-Security-Policy"] = "default-src 'none'; sandbox"
1641
+ resp.headers["X-Content-Type-Options"] = "nosniff"
1642
+ resp.headers["Cache-Control"] = "private, max-age=300"
1643
+ return resp
1644
+
1645
+ # ---- TOTP 2FA Self-Service & Audited Impersonation ----
1646
+
1647
+ @bp.route("/_security/mfa", methods=["GET", "POST"])
1648
+ def security_mfa() -> Any:
1649
+ if deck.mfa_store is None:
1650
+ abort(404)
1651
+ if getattr(g, "_deck_real_user", None) is not None:
1652
+ raise PermissionDeniedError(
1653
+ "MFA settings cannot be modified while impersonating another user."
1654
+ )
1655
+ user = deck._current_user()
1656
+ if user is None:
1657
+ abort(403)
1658
+
1659
+ enrollment = deck.mfa_store.get(user.id)
1660
+ recovery_once: list[str] = []
1661
+ error_msg = ""
1662
+ mfa_required_for_user = bool(
1663
+ deck.config.require_mfa_for_superusers and user.is_superuser
1664
+ )
1665
+
1666
+ if request.method == "POST":
1667
+ act = request.form.get("action", "").strip()
1668
+ if act == "disable":
1669
+ if mfa_required_for_user:
1670
+ error_msg = "MFA cannot be disabled while superuser MFA enforcement is active."
1671
+ elif enrollment is not None and enrollment.enabled:
1672
+ verify_code = request.form.get("code", "").strip()
1673
+ if not verify_code or not deck.mfa_store.verify_and_record(user.id, verify_code):
1674
+ error_msg = "Enter a valid current 6-digit TOTP or recovery code to disable 2FA."
1675
+ else:
1676
+ deck.mfa_store.delete(user.id)
1677
+ session.pop(MFA_SETUP_SECRET_KEY, None)
1678
+ session.pop(MFA_VERIFIED_KEY, None)
1679
+ enrollment = None
1680
+ if deck.audit_store is not None and deck.config.auto_audit:
1681
+ deck.audit_store.record(
1682
+ make_audit_entry(
1683
+ actor_id=user.id,
1684
+ actor_name=user.label,
1685
+ actor_ip=_client_ip(),
1686
+ action="mfa_disabled",
1687
+ model_slug="_auth",
1688
+ model_label="MFA Security",
1689
+ record_pk=user.id,
1690
+ record_repr=user.label,
1691
+ )
1692
+ )
1693
+ deck._emit_event("mfa.disabled", record_pk=user.id)
1694
+ flash("Two-factor authentication disabled.", "warn")
1695
+ elif act == "enable":
1696
+ secret = str(session.get(MFA_SETUP_SECRET_KEY, ""))
1697
+ code = request.form.get("code", "").strip()
1698
+ if not secret:
1699
+ error_msg = "Setup session expired. Refresh to generate a new secret."
1700
+ else:
1701
+ step = verify_totp(secret, code)
1702
+ if step is None:
1703
+ error_msg = "Invalid 6-digit code. Check your authenticator clock and retry."
1704
+ else:
1705
+ plain_codes, hashed_codes = generate_recovery_codes(8)
1706
+ enrollment = MFAEnrollment(
1707
+ user_id=user.id,
1708
+ secret=secret,
1709
+ enabled=True,
1710
+ last_step=step,
1711
+ recovery_hashes=hashed_codes,
1712
+ created_at=datetime.now(timezone.utc),
1713
+ )
1714
+ deck.mfa_store.save(enrollment)
1715
+ session.pop(MFA_SETUP_SECRET_KEY, None)
1716
+ session[MFA_VERIFIED_KEY] = True
1717
+ recovery_once = plain_codes
1718
+ if deck.audit_store is not None and deck.config.auto_audit:
1719
+ deck.audit_store.record(
1720
+ make_audit_entry(
1721
+ actor_id=user.id,
1722
+ actor_name=user.label,
1723
+ actor_ip=_client_ip(),
1724
+ action="mfa_enabled",
1725
+ model_slug="_auth",
1726
+ model_label="MFA Security",
1727
+ record_pk=user.id,
1728
+ record_repr=user.label,
1729
+ )
1730
+ )
1731
+ deck._emit_event("mfa.enabled", record_pk=user.id)
1732
+ flash("Two-factor authentication enabled. Save your recovery codes now.", "ok")
1733
+
1734
+ setup_secret = ""
1735
+ qr_svg = Markup("")
1736
+ otpauth_uri = ""
1737
+ if enrollment is None or not enrollment.enabled:
1738
+ setup_secret = str(session.get(MFA_SETUP_SECRET_KEY, ""))
1739
+ if not setup_secret:
1740
+ setup_secret = generate_totp_secret()
1741
+ session[MFA_SETUP_SECRET_KEY] = setup_secret
1742
+ otpauth_uri = build_otpauth_uri(
1743
+ secret=setup_secret,
1744
+ account_name=user.email or user.username,
1745
+ issuer=deck.config.title,
1746
+ )
1747
+ try:
1748
+ qr_svg = render_qr_svg(otpauth_uri, pixel_size=184)
1749
+ except ValueError:
1750
+ qr_svg = Markup(
1751
+ '<div class="dk-chart-empty">Enter the manual Base32 secret below in your authenticator app.</div>'
1752
+ )
1753
+
1754
+ return render_template(
1755
+ "flask_deck/mfa_setup.html",
1756
+ **deck._base_context(
1757
+ page_title="Two-Factor Authentication (TOTP)",
1758
+ active_nav="_mfa",
1759
+ enrollment=enrollment,
1760
+ mfa_required_for_user=mfa_required_for_user,
1761
+ setup_secret=setup_secret,
1762
+ otpauth_uri=otpauth_uri,
1763
+ qr_svg=qr_svg,
1764
+ recovery_once=recovery_once,
1765
+ error_msg=error_msg,
1766
+ ),
1767
+ )
1768
+
1769
+ @bp.route("/_impersonate/start", methods=["POST"])
1770
+ def impersonate_start() -> Any:
1771
+ if not deck.config.enable_impersonation or not isinstance(deck.auth, RBACAuthProvider):
1772
+ abort(404)
1773
+ real = deck._real_user()
1774
+ if real is None or not real.is_superuser:
1775
+ raise PermissionDeniedError("Only superusers may impersonate accounts.")
1776
+ if not deck.auth.has_permission(real, "impersonate:use"):
1777
+ raise PermissionDeniedError("Missing permission: impersonate:use")
1778
+ target_id = request.form.get("target_user_id", "").strip()
1779
+ target = deck.auth.get_account_by_id(target_id)
1780
+ if target is None or target.id == real.id or target.is_superuser:
1781
+ flash("Cannot impersonate this account (superusers cannot be impersonated).", "danger")
1782
+ return redirect(url_for(f"{bp_name}.index"))
1783
+ session[IMPERSONATOR_USER_KEY] = real.id
1784
+ session[IMPERSONATED_USER_KEY] = target.id
1785
+ session[IMPERSONATE_RO_KEY] = deck.config.impersonate_read_only
1786
+ if deck.audit_store is not None and deck.config.auto_audit:
1787
+ deck.audit_store.record(
1788
+ make_audit_entry(
1789
+ actor_id=real.id,
1790
+ actor_name=real.label,
1791
+ actor_ip=_client_ip(),
1792
+ action="impersonate_start",
1793
+ model_slug="_auth",
1794
+ model_label="Impersonation",
1795
+ record_pk=target.id,
1796
+ record_repr=target.label,
1797
+ metadata={"read_only": deck.config.impersonate_read_only},
1798
+ )
1799
+ )
1800
+ flash(f"Now viewing as {target.label} ({', '.join(target.roles)}).", "warn")
1801
+ return redirect(url_for(f"{bp_name}.index"))
1802
+
1803
+ @bp.route("/_impersonate/stop", methods=["POST"])
1804
+ def impersonate_stop() -> Any:
1805
+ real = getattr(g, "_deck_real_user", None)
1806
+ imp_id = session.pop(IMPERSONATED_USER_KEY, None)
1807
+ session.pop(IMPERSONATOR_USER_KEY, None)
1808
+ session.pop(IMPERSONATE_RO_KEY, None)
1809
+ if real is not None and imp_id and deck.audit_store is not None and deck.config.auto_audit:
1810
+ deck.audit_store.record(
1811
+ make_audit_entry(
1812
+ actor_id=real.id,
1813
+ actor_name=real.label,
1814
+ actor_ip=_client_ip(),
1815
+ action="impersonate_stop",
1816
+ model_slug="_auth",
1817
+ model_label="Impersonation",
1818
+ record_pk=str(imp_id),
1819
+ record_repr=str(imp_id),
1820
+ )
1821
+ )
1822
+ flash("Exited impersonation mode.", "ok")
1823
+ return redirect(url_for(f"{bp_name}.index"))
1824
+
1825
+ # ---- Dashboard ----
1826
+
1827
+ @bp.route("/")
1828
+ def index() -> str:
1829
+ raw_range = request.args.get("range", "14d").strip().lower().rstrip("d")
1830
+ range_days = int(raw_range) if raw_range in {"7", "14", "30", "90"} else 14
1831
+ ctx = DashboardContext(
1832
+ deck, deck.get_session(), deck._current_user(), range_days=range_days
1833
+ )
1834
+ if deck._dashboard_builder is not None:
1835
+ raw_widgets = list(deck._dashboard_builder(ctx))
1836
+ # Hydrate ActivityWidget entries automatically if caller passed empty entries.
1837
+ widgets: list[Widget] = []
1838
+ for w in raw_widgets:
1839
+ if isinstance(w, ActivityWidget) and not w.entries:
1840
+ widgets.append(
1841
+ ActivityWidget(
1842
+ title=w.title,
1843
+ subtitle=w.subtitle,
1844
+ col_span=w.col_span,
1845
+ limit=w.limit,
1846
+ entries=ctx.recent_audit_entries(limit=w.limit),
1847
+ )
1848
+ )
1849
+ else:
1850
+ widgets.append(w)
1851
+ else:
1852
+ widgets = build_default_dashboard(deck, ctx)
1853
+ return render_template(
1854
+ "flask_deck/dashboard.html",
1855
+ **deck._base_context(
1856
+ page_title="Dashboard",
1857
+ active_nav="dashboard",
1858
+ widgets=widgets,
1859
+ range_days=range_days,
1860
+ ),
1861
+ )
1862
+
1863
+ # ---- Model List ----
1864
+
1865
+ @bp.route("/<slug>/")
1866
+ def model_list(slug: str) -> str:
1867
+ view = deck.get_view(slug)
1868
+ if not view.can_view:
1869
+ abort(404)
1870
+ deck._require_perm(f"{slug}:view", model_slug=slug)
1871
+
1872
+ user = deck._current_user()
1873
+ visible_cols = view.visible_list_columns(deck.auth, user)
1874
+ search_term = request.args.get("q", "").strip()
1875
+ active_tab = request.args.get("tab", "").strip() or (
1876
+ view.quick_tabs[0].key if view.quick_tabs else ""
1877
+ )
1878
+ sort_by = request.args.get("sort", "").strip() or None
1879
+ sort_dir = request.args.get("dir", "desc").strip()
1880
+ try:
1881
+ page = int(request.args.get("page", "1"))
1882
+ except ValueError:
1883
+ page = 1
1884
+ default_ps = view.page_size or deck.config.page_size
1885
+ try:
1886
+ page_size = int(request.args.get("page_size", str(default_ps)))
1887
+ except ValueError:
1888
+ page_size = default_ps
1889
+
1890
+ filter_pairs: list[tuple[str, str]] = []
1891
+ filter_params: dict[str, str] = {}
1892
+ for k, v in request.args.items(multi=True):
1893
+ if k.startswith("f_") and v.strip():
1894
+ fk = k[2:]
1895
+ fv = v.strip()
1896
+ filter_pairs.append((fk, fv))
1897
+ filter_params[fk] = fv
1898
+
1899
+ allowed_searchable, allowed_filterable, allowed_sortable = deck._allowed_query_fields(
1900
+ view, user
1901
+ )
1902
+ pag_mode = view.pagination_mode or deck.config.default_pagination_mode
1903
+ after_cursor = request.args.get("after", "").strip() or None
1904
+ before_cursor = request.args.get("before", "").strip() or None
1905
+ trashed = bool(view.soft_delete_column and request.args.get("trashed") == "1")
1906
+
1907
+ base_stmt = view.scope_query(sa.select(view.model), user)
1908
+ result = execute_list_query(
1909
+ deck.get_session(view.bind_key),
1910
+ view.meta,
1911
+ base_stmt=base_stmt,
1912
+ displayed_columns=visible_cols,
1913
+ searchable_columns=allowed_searchable,
1914
+ filterable_columns=allowed_filterable,
1915
+ sortable_columns=allowed_sortable,
1916
+ quick_tabs=view.quick_tabs,
1917
+ active_tab_key=active_tab or None,
1918
+ search_term=search_term,
1919
+ filter_params=filter_pairs,
1920
+ sort_by=sort_by,
1921
+ sort_dir=sort_dir,
1922
+ default_sort=view.default_sort,
1923
+ page=page,
1924
+ page_size=page_size,
1925
+ max_page_size=deck.config.max_page_size,
1926
+ pagination_mode=pag_mode,
1927
+ count_mode=view.count_mode,
1928
+ after_cursor=after_cursor,
1929
+ before_cursor=before_cursor,
1930
+ cursor_secret=deck._cursor_secret(),
1931
+ soft_delete_column=view.soft_delete_column,
1932
+ trashed=trashed,
1933
+ )
1934
+
1935
+ # Build filter panel specifications (only for visible, non-masked, non-sensitive cols)
1936
+ hidden_fields = deck.auth.hidden_fields_for(user, slug)
1937
+ masked_fields = deck.auth.masked_fields_for(user, slug)
1938
+ filter_specs: list[dict[str, Any]] = []
1939
+ for fname in sorted(allowed_filterable):
1940
+ if fname in hidden_fields or fname in masked_fields:
1941
+ continue
1942
+ fm = view.meta.fields_by_name.get(fname)
1943
+ if fm is None:
1944
+ continue
1945
+ spec: dict[str, Any] = {
1946
+ "name": fname,
1947
+ "label": view.get_column_label(fname),
1948
+ "type": "fk" if fm.fk_target_model is not None else fm.field_type,
1949
+ "choices": fm.choices,
1950
+ "value": filter_params.get(fname, ""),
1951
+ "gte": filter_params.get(f"{fname}__gte", ""),
1952
+ "lte": filter_params.get(f"{fname}__lte", ""),
1953
+ "preset": filter_params.get(f"{fname}__preset", ""),
1954
+ "has_key": filter_params.get(f"{fname}__has_key", ""),
1955
+ "path": filter_params.get(f"{fname}__path", ""),
1956
+ "array_contains": filter_params.get(f"{fname}__array_contains", ""),
1957
+ "array_any": filter_params.get(f"{fname}__array_any", ""),
1958
+ }
1959
+ if fm.fk_target_model is not None:
1960
+ spec["fk_options"] = deck._fk_options_for_field(
1961
+ fm.fk_target_model, limit=40, fallback_bind_key=view.bind_key
1962
+ )
1963
+ filter_specs.append(spec)
1964
+
1965
+ # Authorized actions
1966
+ can_create = (
1967
+ view.can_create
1968
+ and not deck.config.read_only
1969
+ and deck.auth.has_permission(user, f"{slug}:create", model_slug=slug)
1970
+ )
1971
+ can_edit = (
1972
+ view.can_edit
1973
+ and not deck.config.read_only
1974
+ and deck.auth.has_permission(user, f"{slug}:edit", model_slug=slug)
1975
+ )
1976
+ can_delete = (
1977
+ view.can_delete
1978
+ and not deck.config.read_only
1979
+ and deck.auth.has_permission(user, f"{slug}:delete", model_slug=slug)
1980
+ )
1981
+ can_export = view.can_export and deck.auth.has_permission(
1982
+ user, f"{slug}:export", model_slug=slug
1983
+ )
1984
+ can_import = (
1985
+ view.can_import
1986
+ and not deck.config.read_only
1987
+ and deck.auth.has_permission(user, f"{slug}:import", model_slug=slug)
1988
+ )
1989
+
1990
+ readonly_fields = deck.auth.readonly_fields_for(user, slug)
1991
+ inline_editable = (
1992
+ (view.resolved_inline_editable - readonly_fields - hidden_fields)
1993
+ if can_edit
1994
+ else frozenset()
1995
+ )
1996
+
1997
+ bulk_actions = [
1998
+ spec
1999
+ for spec in view.actions.values()
2000
+ if spec.bulk_action
2001
+ and not deck.config.read_only
2002
+ and not (spec.async_job and deck.job_backend is None)
2003
+ and deck.auth.has_permission(
2004
+ user,
2005
+ spec.permission or f"{slug}:action:{spec.name}",
2006
+ model_slug=slug,
2007
+ )
2008
+ ]
2009
+ bulk_action_fields_json = {
2010
+ spec.name: json.dumps(
2011
+ [
2012
+ {
2013
+ "name": f.name,
2014
+ "type": f.field_type,
2015
+ "label": f.display_label,
2016
+ "choices": list(f.choices),
2017
+ "placeholder": f.placeholder,
2018
+ "required": f.required,
2019
+ "default": f.default,
2020
+ }
2021
+ for f in spec.fields
2022
+ ]
2023
+ )
2024
+ for spec in bulk_actions
2025
+ if spec.fields
2026
+ }
2027
+
2028
+ # Optional Kanban Board mode when ModelView declares kanban_column
2029
+ supports_kanban = bool(
2030
+ view.kanban_column
2031
+ and view.kanban_column in view.meta.fields_by_name
2032
+ and view.meta.fields_by_name[view.kanban_column].choices
2033
+ )
2034
+ view_mode = (
2035
+ "board"
2036
+ if (supports_kanban and request.args.get("view", "table").strip().lower() == "board")
2037
+ else "table"
2038
+ )
2039
+ kanban_columns: list[dict[str, Any]] = []
2040
+ can_drag_kanban = False
2041
+ kanban_card_fields: tuple[str, ...] = ()
2042
+ if view_mode == "board" and view.kanban_column is not None:
2043
+ kanban_card_fields = tuple(
2044
+ c
2045
+ for c in (view.kanban_card_fields or visible_cols[:4])
2046
+ if c not in hidden_fields
2047
+ )
2048
+ kanban_columns = execute_kanban_query(
2049
+ deck.get_session(view.bind_key),
2050
+ view.meta,
2051
+ base_stmt=base_stmt,
2052
+ kanban_column=view.kanban_column,
2053
+ card_fields=kanban_card_fields,
2054
+ searchable_columns=allowed_searchable,
2055
+ filterable_columns=allowed_filterable,
2056
+ search_term=search_term,
2057
+ filter_params=filter_pairs,
2058
+ soft_delete_column=view.soft_delete_column,
2059
+ )
2060
+ writable_set = set(view.allowed_form_fields(deck.auth, user, mode="edit"))
2061
+ can_drag_kanban = can_edit and view.kanban_column in writable_set
2062
+
2063
+ allowed_agg_spec = {
2064
+ k: v
2065
+ for k, v in view.column_aggregates.items()
2066
+ if k not in hidden_fields and k not in masked_fields
2067
+ }
2068
+ page_aggregates = (
2069
+ compute_page_aggregates(result.items, allowed_agg_spec)
2070
+ if view_mode == "table" and allowed_agg_spec
2071
+ else {}
2072
+ )
2073
+
2074
+ def _qs(**overrides: Any) -> str:
2075
+ params = [(k, v) for k, v in request.args.items(multi=True) if k not in overrides]
2076
+ for k, v in overrides.items():
2077
+ if v is not None and v != "":
2078
+ params.append((k, str(v)))
2079
+ encoded = urlencode(params)
2080
+ return f"?{encoded}" if encoded else ""
2081
+
2082
+ return render_template(
2083
+ "flask_deck/model_list.html",
2084
+ **deck._base_context(
2085
+ page_title=view.plural_label,
2086
+ active_nav=slug,
2087
+ view=view,
2088
+ result=result,
2089
+ visible_cols=visible_cols,
2090
+ search_term=search_term,
2091
+ active_tab=active_tab,
2092
+ sort_by=sort_by or (view.default_sort[0] if view.default_sort else view.meta.primary_keys[0].name),
2093
+ sort_dir=sort_dir,
2094
+ filter_specs=filter_specs,
2095
+ can_create=can_create,
2096
+ can_edit=can_edit,
2097
+ can_delete=can_delete,
2098
+ can_export=can_export,
2099
+ can_import=can_import,
2100
+ inline_editable=inline_editable,
2101
+ bulk_actions=bulk_actions,
2102
+ bulk_action_fields_json=bulk_action_fields_json,
2103
+ supports_kanban=supports_kanban,
2104
+ view_mode=view_mode,
2105
+ kanban_columns=kanban_columns,
2106
+ kanban_card_fields=kanban_card_fields,
2107
+ can_drag_kanban=can_drag_kanban,
2108
+ page_aggregates=page_aggregates,
2109
+ supports_soft_delete=bool(view.soft_delete_column),
2110
+ trashed=trashed,
2111
+ media_url_builder=deck._media_url_builder(view),
2112
+ qs=_qs,
2113
+ ),
2114
+ )
2115
+
2116
+ # ---- Create ----
2117
+
2118
+ @bp.route("/<slug>/new", methods=["GET", "POST"])
2119
+ def model_create(slug: str) -> Any:
2120
+ view = deck.get_view(slug)
2121
+ if not view.can_create:
2122
+ abort(403)
2123
+ deck._require_perm(f"{slug}:create", model_slug=slug)
2124
+
2125
+ errors: dict[str, list[str]] = {}
2126
+ submitted: Mapping[str, Any] | None = None
2127
+ clone_pk = request.args.get("clone", "").strip()
2128
+ if request.method == "GET" and clone_pk:
2129
+ deck._require_perm(f"{slug}:view", model_slug=slug)
2130
+ source_obj, _ = deck._fetch_scoped_record(view, clone_pk)
2131
+ if deck._is_soft_deleted(view, source_obj):
2132
+ abort(404)
2133
+ user = deck._current_user()
2134
+ hidden = deck.auth.hidden_fields_for(user, slug)
2135
+ masked = deck.auth.masked_fields_for(user, slug)
2136
+ cloned: dict[str, Any] = {}
2137
+ for f in view.meta.fields:
2138
+ if (
2139
+ f.primary_key
2140
+ or f.unique
2141
+ or f.is_sensitive
2142
+ or f.name in hidden
2143
+ or f.name in masked
2144
+ or f.name in view.file_fields
2145
+ or f.name == view.soft_delete_column
2146
+ ):
2147
+ continue
2148
+ val = getattr(source_obj, f.name, None)
2149
+ if isinstance(val, enum.Enum):
2150
+ val = val.value
2151
+ elif isinstance(val, datetime):
2152
+ val = to_user_timezone(val).strftime("%Y-%m-%dT%H:%M")
2153
+ elif f.field_type == "json" and isinstance(val, (dict, list)):
2154
+ val = json.dumps(val, indent=2)
2155
+ if val is not None:
2156
+ cloned[f.name] = val
2157
+ submitted = cloned
2158
+
2159
+ if request.method == "POST":
2160
+ submitted = request.form
2161
+ sess = deck.get_session(view.bind_key)
2162
+ obj = view.model()
2163
+ newly_stored: list[tuple[Any, str]] = []
2164
+ cur_user = deck._current_user()
2165
+
2166
+ def _scope_m2m(target_cls: type[Any], s: sa.Select[Any]) -> sa.Select[Any]:
2167
+ tv = deck._views_by_model.get(target_cls)
2168
+ return tv.scope_query(s, cur_user) if tv is not None else s
2169
+
2170
+ try:
2171
+ view.apply_form_data(
2172
+ sess,
2173
+ obj,
2174
+ request.form,
2175
+ auth=deck.auth,
2176
+ user=cur_user,
2177
+ mode="create",
2178
+ max_json_depth=deck.config.max_json_depth,
2179
+ m2m_getter=request.form.getlist,
2180
+ m2m_scope=_scope_m2m,
2181
+ )
2182
+ newly_stored, _ = view.apply_file_uploads(
2183
+ obj,
2184
+ request.files,
2185
+ request.form,
2186
+ auth=deck.auth,
2187
+ user=cur_user,
2188
+ mode="create",
2189
+ default_max_bytes=deck.config.max_upload_bytes,
2190
+ )
2191
+ view.on_model_change(obj, is_created=True, user=cur_user)
2192
+ sess.add(obj)
2193
+ sess.flush()
2194
+ view.apply_inline_forms(
2195
+ sess,
2196
+ obj,
2197
+ request.form,
2198
+ auth=deck.auth,
2199
+ user=cur_user,
2200
+ max_json_depth=deck.config.max_json_depth,
2201
+ )
2202
+ sess.commit()
2203
+ pk_str = encode_pk(extract_pk(obj, view.meta))
2204
+ safe_repr = view.format_record_repr(obj, auth=deck.auth, user=cur_user)
2205
+ snap = view.extract_snapshot(obj)
2206
+ diff = compute_diff(
2207
+ {},
2208
+ snap,
2209
+ sensitive_fields=view.meta.sensitive_fields,
2210
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
2211
+ )
2212
+ deck._record_audit(
2213
+ action_name="create",
2214
+ view=view,
2215
+ record_pk=pk_str,
2216
+ record_repr=safe_repr,
2217
+ changes=diff,
2218
+ )
2219
+ deck._emit_event(
2220
+ "record.created",
2221
+ model_slug=slug,
2222
+ record_pk=pk_str,
2223
+ payload={"repr": safe_repr},
2224
+ )
2225
+ flash(f"Created {view.label} ({safe_repr}).", "ok")
2226
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2227
+ except ValidationError as exc:
2228
+ sess.rollback()
2229
+ deck._delete_orphan_files_best_effort(newly_stored)
2230
+ errors = exc.errors
2231
+ except IntegrityError as exc:
2232
+ sess.rollback()
2233
+ deck._delete_orphan_files_best_effort(newly_stored)
2234
+ errors = {"__all__": [f"Database integrity constraint failed: {exc.orig}"]}
2235
+ except SQLAlchemyError as exc:
2236
+ sess.rollback()
2237
+ deck._delete_orphan_files_best_effort(newly_stored)
2238
+ errors = {"__all__": [f"Database error: {exc.__class__.__name__}"]}
2239
+ except Exception:
2240
+ sess.rollback()
2241
+ deck._delete_orphan_files_best_effort(newly_stored)
2242
+ raise
2243
+
2244
+ form_ctx = deck._build_form_context(
2245
+ view, obj=None, mode="create", errors=errors, submitted=submitted
2246
+ )
2247
+ return render_template(
2248
+ "flask_deck/model_form.html",
2249
+ **deck._base_context(
2250
+ page_title=f"New {view.label}",
2251
+ active_nav=slug,
2252
+ **form_ctx,
2253
+ ),
2254
+ )
2255
+
2256
+ # ---- Detail ----
2257
+
2258
+ @bp.route("/<slug>/<raw_pk>")
2259
+ def model_detail(slug: str, raw_pk: str) -> str:
2260
+ view = deck.get_view(slug)
2261
+ if not view.can_view:
2262
+ abort(404)
2263
+ deck._require_perm(f"{slug}:view", model_slug=slug)
2264
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
2265
+ deck._require_perm(f"{slug}:view", model_slug=slug, obj=obj)
2266
+ pk_str = encode_pk(pk_vals)
2267
+ user = deck._current_user()
2268
+ hidden = deck.auth.hidden_fields_for(user, slug)
2269
+
2270
+ media_builder = deck._media_url_builder(view)
2271
+ fields_display = []
2272
+ for f in view.meta.fields:
2273
+ if f.name in hidden or f.is_sensitive:
2274
+ continue
2275
+ fk_rel = view.meta.fk_column_to_rel.get(f.name)
2276
+ col_key = fk_rel.name if (fk_rel is not None and fk_rel.name not in hidden) else f.name
2277
+ fields_display.append(
2278
+ {
2279
+ "name": f.name,
2280
+ "label": view.get_column_label(f.name),
2281
+ "formatted": view.format_cell(
2282
+ col_key,
2283
+ obj,
2284
+ auth=deck.auth,
2285
+ user=user,
2286
+ media_url_builder=media_builder,
2287
+ rel_repr=deck._rel_repr,
2288
+ ),
2289
+ }
2290
+ )
2291
+
2292
+ relations_display = []
2293
+ for rel in view.meta.relationships:
2294
+ if rel.name in hidden:
2295
+ continue
2296
+ val = getattr(obj, rel.name, None)
2297
+ items = list(val) if (rel.uselist and val is not None) else ([val] if val is not None else [])
2298
+ relations_display.append(
2299
+ {
2300
+ "name": rel.name,
2301
+ "label": rel.label,
2302
+ "uselist": rel.uselist,
2303
+ "count": len(items),
2304
+ "records": [deck._rel_repr(rel.target_model, it) for it in items[:25]],
2305
+ }
2306
+ )
2307
+
2308
+ history: list[AuditEntry] = []
2309
+ if deck.audit_store is not None and deck.auth.has_permission(user, "audit:view"):
2310
+ raw_history, _ = deck.audit_store.list_entries(
2311
+ model_slug=slug, record_pk=pk_str, limit=25
2312
+ )
2313
+ history = [deck._sanitize_audit_entry(e, user) for e in raw_history]
2314
+
2315
+ can_create = (
2316
+ view.can_create
2317
+ and not deck.config.read_only
2318
+ and deck.auth.has_permission(user, f"{slug}:create", model_slug=slug)
2319
+ )
2320
+ can_edit = (
2321
+ view.can_edit
2322
+ and not deck.config.read_only
2323
+ and deck.auth.has_permission(user, f"{slug}:edit", model_slug=slug, obj=obj)
2324
+ )
2325
+ can_delete = (
2326
+ view.can_delete
2327
+ and not deck.config.read_only
2328
+ and deck.auth.has_permission(user, f"{slug}:delete", model_slug=slug, obj=obj)
2329
+ )
2330
+ can_force_delete = (
2331
+ can_delete
2332
+ and deck.auth.has_permission(user, f"{slug}:force_delete", model_slug=slug, obj=obj)
2333
+ )
2334
+
2335
+ is_soft_deleted = deck._is_soft_deleted(view, obj)
2336
+
2337
+ return render_template(
2338
+ "flask_deck/model_detail.html",
2339
+ **deck._base_context(
2340
+ page_title=view.format_record_repr(obj, auth=deck.auth, user=user),
2341
+ active_nav=slug,
2342
+ view=view,
2343
+ obj=obj,
2344
+ pk_str=pk_str,
2345
+ record_repr=view.format_record_repr(obj, auth=deck.auth, user=user),
2346
+ fields_display=fields_display,
2347
+ relations_display=relations_display,
2348
+ history=history,
2349
+ can_create=can_create,
2350
+ can_edit=can_edit,
2351
+ can_delete=can_delete,
2352
+ can_force_delete=can_force_delete,
2353
+ is_soft_deleted=is_soft_deleted,
2354
+ ),
2355
+ )
2356
+
2357
+ # ---- Side-by-Side Revision Diff & Time-Travel History ----
2358
+
2359
+ @bp.route("/<slug>/<raw_pk>/history")
2360
+ def model_history(slug: str, raw_pk: str) -> str:
2361
+ if deck.audit_store is None:
2362
+ abort(404)
2363
+ view = deck.get_view(slug)
2364
+ if not view.can_view:
2365
+ abort(404)
2366
+ deck._require_perm(f"{slug}:view", model_slug=slug)
2367
+ deck._require_perm("audit:view")
2368
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
2369
+ deck._require_perm(f"{slug}:view", model_slug=slug, obj=obj)
2370
+ pk_str = encode_pk(pk_vals)
2371
+ user = deck._current_user()
2372
+ entries, _ = deck.audit_store.list_entries(
2373
+ model_slug=slug, record_pk=pk_str, limit=50
2374
+ )
2375
+ selected_id = request.args.get("rev", "").strip()
2376
+ selected_entry = next((e for e in entries if e.id == selected_id), None) or (
2377
+ entries[0] if entries else None
2378
+ )
2379
+ current_snap = view.extract_snapshot(obj)
2380
+ hidden = deck.auth.hidden_fields_for(user, slug)
2381
+ masked = deck.auth.masked_fields_for(user, slug)
2382
+ diff_rows: list[dict[str, Any]] = []
2383
+ if selected_entry is not None:
2384
+ for fname, delta in selected_entry.changes.items():
2385
+ if fname in hidden:
2386
+ continue
2387
+ old_v = delta.get("old")
2388
+ new_v = delta.get("new")
2389
+ live_v = current_snap.get(fname)
2390
+ if isinstance(live_v, enum.Enum):
2391
+ live_v = live_v.value
2392
+ elif isinstance(live_v, datetime):
2393
+ live_v = to_user_timezone(live_v).strftime("%Y-%m-%d %H:%M")
2394
+ if fname in view.meta.sensitive_fields or fname in masked:
2395
+ old_v = "[REDACTED]" if old_v is not None else None
2396
+ new_v = "[REDACTED]" if new_v is not None else None
2397
+ live_v = "[REDACTED]" if live_v is not None else None
2398
+ diff_rows.append(
2399
+ {
2400
+ "field": fname,
2401
+ "label": view.get_column_label(fname),
2402
+ "old": old_v,
2403
+ "new": new_v,
2404
+ "live": live_v,
2405
+ }
2406
+ )
2407
+
2408
+ can_revert = (
2409
+ deck.config.enable_audit_revert
2410
+ and not deck.config.read_only
2411
+ and deck.auth.has_permission(user, "audit:revert")
2412
+ )
2413
+ return render_template(
2414
+ "flask_deck/record_history.html",
2415
+ **deck._base_context(
2416
+ page_title=f"Revision History · {view.format_record_repr(obj, auth=deck.auth, user=user)}",
2417
+ active_nav=slug,
2418
+ view=view,
2419
+ pk_str=pk_str,
2420
+ record_repr=view.format_record_repr(obj, auth=deck.auth, user=user),
2421
+ entries=entries,
2422
+ selected_entry=selected_entry,
2423
+ diff_rows=diff_rows,
2424
+ can_revert=can_revert,
2425
+ ),
2426
+ )
2427
+
2428
+ # ---- Edit ----
2429
+
2430
+ @bp.route("/<slug>/<raw_pk>/edit", methods=["GET", "POST"])
2431
+ def model_edit(slug: str, raw_pk: str) -> Any:
2432
+ view = deck.get_view(slug)
2433
+ if not view.can_edit:
2434
+ abort(403)
2435
+ deck._require_perm(f"{slug}:edit", model_slug=slug)
2436
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
2437
+ deck._require_perm(f"{slug}:edit", model_slug=slug, obj=obj)
2438
+ if deck._is_soft_deleted(view, obj):
2439
+ flash(
2440
+ f"Restore {view.label} from Trash before editing.",
2441
+ "warn",
2442
+ )
2443
+ return redirect(url_for(f"{bp_name}.model_detail", slug=slug, raw_pk=encode_pk(pk_vals)))
2444
+ pk_str = encode_pk(pk_vals)
2445
+ cur_user = deck._current_user()
2446
+
2447
+ errors: dict[str, list[str]] = {}
2448
+ submitted: Mapping[str, Any] | None = None
2449
+ if request.method == "POST":
2450
+ submitted = request.form
2451
+ sess = deck.get_session(view.bind_key)
2452
+ before_snap = view.extract_snapshot(obj)
2453
+ newly_stored: list[tuple[Any, str]] = []
2454
+ orphans: list[tuple[Any, str]] = []
2455
+
2456
+ def _scope_m2m(target_cls: type[Any], s: sa.Select[Any]) -> sa.Select[Any]:
2457
+ tv = deck._views_by_model.get(target_cls)
2458
+ return tv.scope_query(s, cur_user) if tv is not None else s
2459
+
2460
+ try:
2461
+ view.apply_form_data(
2462
+ sess,
2463
+ obj,
2464
+ request.form,
2465
+ auth=deck.auth,
2466
+ user=cur_user,
2467
+ mode="edit",
2468
+ max_json_depth=deck.config.max_json_depth,
2469
+ m2m_getter=request.form.getlist,
2470
+ m2m_scope=_scope_m2m,
2471
+ )
2472
+ newly_stored, orphans = view.apply_file_uploads(
2473
+ obj,
2474
+ request.files,
2475
+ request.form,
2476
+ auth=deck.auth,
2477
+ user=cur_user,
2478
+ mode="edit",
2479
+ default_max_bytes=deck.config.max_upload_bytes,
2480
+ )
2481
+ view.on_model_change(obj, is_created=False, user=cur_user)
2482
+ sess.flush()
2483
+ view.apply_inline_forms(
2484
+ sess,
2485
+ obj,
2486
+ request.form,
2487
+ auth=deck.auth,
2488
+ user=cur_user,
2489
+ max_json_depth=deck.config.max_json_depth,
2490
+ )
2491
+ sess.commit()
2492
+ deck._delete_orphan_files_best_effort(orphans)
2493
+ after_snap = view.extract_snapshot(obj)
2494
+ safe_repr = view.format_record_repr(obj, auth=deck.auth, user=cur_user)
2495
+ diff = compute_diff(
2496
+ before_snap,
2497
+ after_snap,
2498
+ sensitive_fields=view.meta.sensitive_fields,
2499
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
2500
+ )
2501
+ if diff:
2502
+ deck._record_audit(
2503
+ action_name="update",
2504
+ view=view,
2505
+ record_pk=pk_str,
2506
+ record_repr=safe_repr,
2507
+ changes=diff,
2508
+ )
2509
+ deck._emit_event(
2510
+ "record.updated",
2511
+ model_slug=slug,
2512
+ record_pk=pk_str,
2513
+ payload={"fields": sorted(diff.keys())},
2514
+ )
2515
+ flash(f"Saved changes to {safe_repr}.", "ok")
2516
+ return redirect(url_for(f"{bp_name}.model_detail", slug=slug, raw_pk=pk_str))
2517
+ except ValidationError as exc:
2518
+ sess.rollback()
2519
+ deck._delete_orphan_files_best_effort(newly_stored)
2520
+ errors = exc.errors
2521
+ except IntegrityError as exc:
2522
+ sess.rollback()
2523
+ deck._delete_orphan_files_best_effort(newly_stored)
2524
+ errors = {"__all__": [f"Database integrity constraint failed: {exc.orig}"]}
2525
+ except SQLAlchemyError as exc:
2526
+ sess.rollback()
2527
+ deck._delete_orphan_files_best_effort(newly_stored)
2528
+ errors = {"__all__": [f"Database error: {exc.__class__.__name__}"]}
2529
+ except Exception:
2530
+ sess.rollback()
2531
+ deck._delete_orphan_files_best_effort(newly_stored)
2532
+ raise
2533
+
2534
+ form_ctx = deck._build_form_context(
2535
+ view, obj=obj, mode="edit", errors=errors, submitted=submitted
2536
+ )
2537
+ return render_template(
2538
+ "flask_deck/model_form.html",
2539
+ **deck._base_context(
2540
+ page_title=f"Edit {view.format_record_repr(obj, auth=deck.auth, user=cur_user)}",
2541
+ active_nav=slug,
2542
+ pk_str=pk_str,
2543
+ **form_ctx,
2544
+ ),
2545
+ )
2546
+
2547
+ # ---- Delete (Soft-Delete Aware + Force Delete) & Restore ----
2548
+
2549
+ @bp.route("/<slug>/<raw_pk>/delete", methods=["POST"])
2550
+ def model_delete(slug: str, raw_pk: str) -> Any:
2551
+ view = deck.get_view(slug)
2552
+ if not view.can_delete:
2553
+ abort(403)
2554
+ deck._require_perm(f"{slug}:delete", model_slug=slug)
2555
+ force_delete = request.form.get("force", "").strip() == "1"
2556
+ if view.soft_delete_column and force_delete:
2557
+ deck._require_perm(f"{slug}:force_delete", model_slug=slug)
2558
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
2559
+ deck._require_perm(f"{slug}:delete", model_slug=slug, obj=obj)
2560
+ cur_user = deck._current_user()
2561
+ pk_str = encode_pk(pk_vals)
2562
+ repr_str = view.format_record_repr(obj, auth=deck.auth, user=cur_user)
2563
+ before_snap = view.extract_snapshot(obj)
2564
+
2565
+ sess = deck.get_session(view.bind_key)
2566
+ if view.soft_delete_column and not force_delete:
2567
+ fmeta = view.meta.fields_by_name.get(view.soft_delete_column)
2568
+ if fmeta is not None:
2569
+ try:
2570
+ view.on_model_delete(obj, user=cur_user)
2571
+ setattr(
2572
+ obj,
2573
+ view.soft_delete_column,
2574
+ True if fmeta.field_type == "boolean" else datetime.now(timezone.utc),
2575
+ )
2576
+ sess.commit()
2577
+ except SQLAlchemyError:
2578
+ sess.rollback()
2579
+ flash(f"Could not move {repr_str} to Trash.", "danger")
2580
+ return redirect(url_for(f"{bp_name}.model_detail", slug=slug, raw_pk=pk_str))
2581
+ after_snap = view.extract_snapshot(obj)
2582
+ deck._record_audit(
2583
+ action_name="soft_delete",
2584
+ view=view,
2585
+ record_pk=pk_str,
2586
+ record_repr=repr_str,
2587
+ changes=compute_diff(
2588
+ before_snap,
2589
+ after_snap,
2590
+ sensitive_fields=view.meta.sensitive_fields,
2591
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
2592
+ ),
2593
+ )
2594
+ deck._emit_event(
2595
+ "record.deleted",
2596
+ model_slug=slug,
2597
+ record_pk=pk_str,
2598
+ payload={"soft": True, "repr": repr_str},
2599
+ )
2600
+ flash(f"Moved {view.label} ({repr_str}) to Trash.", "ok")
2601
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2602
+
2603
+ if view.soft_delete_column and force_delete:
2604
+ deck._require_perm(f"{slug}:force_delete", model_slug=slug, obj=obj)
2605
+
2606
+ orphan_files = deck._collect_orphan_files(view, obj)
2607
+ try:
2608
+ view.on_model_delete(obj, user=cur_user)
2609
+ sess.delete(obj)
2610
+ sess.commit()
2611
+ except IntegrityError:
2612
+ sess.rollback()
2613
+ flash(
2614
+ f"Cannot delete {repr_str}: referenced by dependent records.",
2615
+ "danger",
2616
+ )
2617
+ return redirect(url_for(f"{bp_name}.model_detail", slug=slug, raw_pk=pk_str))
2618
+
2619
+ deck._delete_orphan_files_best_effort(orphan_files)
2620
+ deck._record_audit(
2621
+ action_name="delete",
2622
+ view=view,
2623
+ record_pk=pk_str,
2624
+ record_repr=repr_str,
2625
+ changes=compute_diff(
2626
+ before_snap,
2627
+ {},
2628
+ sensitive_fields=view.meta.sensitive_fields,
2629
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
2630
+ ),
2631
+ )
2632
+ deck._emit_event(
2633
+ "record.deleted",
2634
+ model_slug=slug,
2635
+ record_pk=pk_str,
2636
+ payload={"soft": False, "repr": repr_str},
2637
+ )
2638
+ flash(f"Deleted {view.label} ({repr_str}).", "ok")
2639
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2640
+
2641
+ @bp.route("/<slug>/<raw_pk>/restore", methods=["POST"])
2642
+ def model_restore(slug: str, raw_pk: str) -> Any:
2643
+ view = deck.get_view(slug)
2644
+ if not view.soft_delete_column:
2645
+ abort(404)
2646
+ if not view.can_edit:
2647
+ abort(403)
2648
+ deck._require_perm(f"{slug}:edit", model_slug=slug)
2649
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
2650
+ deck._require_perm(f"{slug}:edit", model_slug=slug, obj=obj)
2651
+ fmeta = view.meta.fields_by_name.get(view.soft_delete_column)
2652
+ if fmeta is None:
2653
+ abort(404)
2654
+ pk_str = encode_pk(pk_vals)
2655
+ cur_user = deck._current_user()
2656
+ repr_str = view.format_record_repr(obj, auth=deck.auth, user=cur_user)
2657
+ if not deck._is_soft_deleted(view, obj):
2658
+ flash(f"{view.label} ({repr_str}) is already active.", "neutral")
2659
+ return redirect(url_for(f"{bp_name}.model_detail", slug=slug, raw_pk=pk_str))
2660
+ before_snap = view.extract_snapshot(obj)
2661
+ sess = deck.get_session(view.bind_key)
2662
+ try:
2663
+ setattr(obj, view.soft_delete_column, False if fmeta.field_type == "boolean" else None)
2664
+ view.on_model_change(obj, is_created=False, user=cur_user)
2665
+ sess.commit()
2666
+ except (ValidationError, SQLAlchemyError) as exc:
2667
+ sess.rollback()
2668
+ flash(f"Restore failed: {exc}", "danger")
2669
+ return redirect(url_for(f"{bp_name}.model_detail", slug=slug, raw_pk=pk_str))
2670
+ after_snap = view.extract_snapshot(obj)
2671
+ deck._record_audit(
2672
+ action_name="restore",
2673
+ view=view,
2674
+ record_pk=pk_str,
2675
+ record_repr=repr_str,
2676
+ changes=compute_diff(
2677
+ before_snap,
2678
+ after_snap,
2679
+ sensitive_fields=view.meta.sensitive_fields,
2680
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
2681
+ ),
2682
+ )
2683
+ deck._emit_event(
2684
+ "record.restored",
2685
+ model_slug=slug,
2686
+ record_pk=pk_str,
2687
+ payload={"repr": repr_str},
2688
+ )
2689
+ flash(f"Restored {view.label} ({repr_str}) from Trash.", "ok")
2690
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2691
+
2692
+ # ---- Bulk & Custom Actions ----
2693
+
2694
+ @bp.route("/<slug>/action/<action_name>", methods=["POST"])
2695
+ def model_action(slug: str, action_name: str) -> Any:
2696
+ view = deck.get_view(slug)
2697
+ user = deck._current_user()
2698
+ raw_pks = [p for p in request.form.getlist("selected_pks") if p.strip()]
2699
+ if not raw_pks:
2700
+ flash("Select at least one record.", "warn")
2701
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2702
+
2703
+ decoded_pks = [decode_pk(p, view.meta) for p in raw_pks]
2704
+ stmt = view.scope_query(sa.select(view.model), user)
2705
+ sd_active = soft_delete_predicate(view.meta, view.soft_delete_column, trashed=False)
2706
+ if sd_active is not None:
2707
+ stmt = stmt.where(sd_active)
2708
+ if len(view.meta.primary_keys) == 1:
2709
+ pk_col = getattr(view.model, view.meta.primary_keys[0].name)
2710
+ stmt = stmt.where(pk_col.in_([pk[0] for pk in decoded_pks]))
2711
+ else:
2712
+ pk_cols = [getattr(view.model, pk.name) for pk in view.meta.primary_keys]
2713
+ stmt = stmt.where(sa.tuple_(*pk_cols).in_(decoded_pks))
2714
+ records = list(deck.get_session(view.bind_key).scalars(stmt).all())
2715
+
2716
+ if not records:
2717
+ flash("No matching authorized records found.", "warn")
2718
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2719
+
2720
+ sess = deck.get_session(view.bind_key)
2721
+
2722
+ if action_name == "delete":
2723
+ if not view.can_delete:
2724
+ abort(403)
2725
+ deck._require_perm(f"{slug}:delete", model_slug=slug)
2726
+ if (
2727
+ deck.config.environment == "production"
2728
+ and deck.config.require_confirm_text_in_prod
2729
+ ):
2730
+ expected_phrase = f"DELETE {len(records)}"
2731
+ confirm_input = request.form.get("confirm_text", "").strip()
2732
+ if confirm_input != expected_phrase:
2733
+ flash(
2734
+ f"Production safeguard: enter '{expected_phrase}' to confirm bulk delete.",
2735
+ "danger",
2736
+ )
2737
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2738
+ orphan_files: list[tuple[Any, str]] = []
2739
+ try:
2740
+ sd_col = view.soft_delete_column
2741
+ sd_fmeta = view.meta.fields_by_name.get(sd_col) if sd_col else None
2742
+ for rec in records:
2743
+ if sd_col and sd_fmeta is not None:
2744
+ view.on_model_delete(rec, user=user)
2745
+ setattr(
2746
+ rec,
2747
+ sd_col,
2748
+ True if sd_fmeta.field_type == "boolean" else datetime.now(timezone.utc),
2749
+ )
2750
+ else:
2751
+ orphan_files.extend(deck._collect_orphan_files(view, rec))
2752
+ view.on_model_delete(rec, user=user)
2753
+ sess.delete(rec)
2754
+ sess.commit()
2755
+ except IntegrityError:
2756
+ sess.rollback()
2757
+ flash("Bulk delete failed due to foreign key references.", "danger")
2758
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2759
+
2760
+ deck._delete_orphan_files_best_effort(orphan_files)
2761
+ deck._record_audit(
2762
+ action_name="bulk_action",
2763
+ view=view,
2764
+ record_pk=",".join(raw_pks[:10]),
2765
+ record_repr=f"Bulk delete ({len(records)} {view.plural_label})",
2766
+ metadata={"action": "delete", "count": len(records)},
2767
+ )
2768
+ deck._emit_event(
2769
+ "record.deleted",
2770
+ model_slug=slug,
2771
+ record_pk=",".join(raw_pks[:10]),
2772
+ payload={"soft": bool(view.soft_delete_column), "count": len(records)},
2773
+ )
2774
+ flash(
2775
+ f"Moved {len(records)} {view.plural_label} to Trash."
2776
+ if view.soft_delete_column
2777
+ else f"Deleted {len(records)} {view.plural_label}.",
2778
+ "ok",
2779
+ )
2780
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2781
+
2782
+ spec = view.actions.get(action_name)
2783
+ if spec is None:
2784
+ abort(404)
2785
+ deck._require_perm(spec.permission or f"{slug}:action:{action_name}", model_slug=slug)
2786
+
2787
+ if (
2788
+ spec.require_confirm_text
2789
+ and deck.config.environment == "production"
2790
+ and deck.config.require_confirm_text_in_prod
2791
+ ):
2792
+ expected = f"CONFIRM {len(records)}"
2793
+ if request.form.get("confirm_text", "").strip() != expected:
2794
+ flash(f"Production safeguard: enter '{expected}' to confirm.", "danger")
2795
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2796
+
2797
+ action_params: dict[str, Any] = {}
2798
+ form_snapshot: dict[str, str] = {}
2799
+ for af in spec.fields:
2800
+ raw_v = request.form.get(af.name, "").strip()
2801
+ if af.required and not raw_v:
2802
+ flash(f"Action '{spec.label}' requires '{af.display_label}'.", "danger")
2803
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2804
+ if raw_v and af.choices:
2805
+ valid_choices = {str(c[0]) for c in af.choices}
2806
+ if raw_v not in valid_choices:
2807
+ flash(
2808
+ f"Invalid value for '{af.display_label}' in action '{spec.label}'.",
2809
+ "danger",
2810
+ )
2811
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2812
+ if raw_v and af.field_type == "number":
2813
+ try:
2814
+ float(raw_v)
2815
+ except ValueError:
2816
+ flash(f"'{af.display_label}' must be a valid number.", "danger")
2817
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2818
+ form_snapshot[af.name] = raw_v
2819
+ action_params[af.name] = (
2820
+ "[REDACTED]"
2821
+ if is_sensitive_field(af.name, deck.config.extra_sensitive_patterns)
2822
+ else raw_v
2823
+ )
2824
+
2825
+ handler = getattr(view, spec.handler_name)
2826
+
2827
+ # Background async job execution when @action(..., async_job=True)
2828
+ if spec.async_job:
2829
+ if deck.job_backend is None:
2830
+ flash(
2831
+ f"Action '{spec.label}' requires background jobs (enable_jobs=True).",
2832
+ "danger",
2833
+ )
2834
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2835
+ pk_list_copy = list(decoded_pks)
2836
+
2837
+ def _run_async_action(job_ctx: JobContext) -> str | None:
2838
+ job_sess = deck.get_session(view.bind_key)
2839
+ q_stmt = view.scope_query(sa.select(view.model), user)
2840
+ if sd_active is not None:
2841
+ q_stmt = q_stmt.where(sd_active)
2842
+ if len(view.meta.primary_keys) == 1:
2843
+ col_pk = getattr(view.model, view.meta.primary_keys[0].name)
2844
+ q_stmt = q_stmt.where(col_pk.in_([p[0] for p in pk_list_copy]))
2845
+ else:
2846
+ cols_pk = [getattr(view.model, pk.name) for pk in view.meta.primary_keys]
2847
+ q_stmt = q_stmt.where(sa.tuple_(*cols_pk).in_(pk_list_copy))
2848
+ fresh_recs = list(job_sess.scalars(q_stmt).all())
2849
+ job_ctx.log(f"Loaded {len(fresh_recs)} authorized {view.plural_label} record(s).")
2850
+ res_msg = handler(fresh_recs, form_snapshot, user, job_ctx)
2851
+ job_sess.commit()
2852
+ return str(res_msg or f"Processed {len(fresh_recs)} {view.plural_label}.")
2853
+
2854
+ def _on_job_done(rec: JobRecord) -> None:
2855
+ ev_name = (
2856
+ "job.completed"
2857
+ if rec.status == "succeeded"
2858
+ else ("job.cancelled" if rec.status == "cancelled" else "job.failed")
2859
+ )
2860
+ deck._emit_event(
2861
+ ev_name,
2862
+ model_slug=slug,
2863
+ record_pk=rec.id,
2864
+ payload={"label": rec.label, "status": rec.status, "error": rec.error},
2865
+ actor=user,
2866
+ )
2867
+
2868
+ # Release request read transaction before spawning worker thread (prevents StaticPool lock/rollback race).
2869
+ sess.close()
2870
+ job = deck.job_backend.submit(
2871
+ name=f"{slug}:{action_name}",
2872
+ label=f"{spec.label} ({len(records)} {view.plural_label})",
2873
+ actor_id=user.id if user else "system",
2874
+ actor_name=user.label if user else "System",
2875
+ model_slug=slug,
2876
+ fn=_run_async_action,
2877
+ app=deck.app,
2878
+ on_complete=_on_job_done,
2879
+ )
2880
+ deck._record_audit(
2881
+ action_name="async_job",
2882
+ view=view,
2883
+ record_pk=job.id,
2884
+ record_repr=job.label,
2885
+ metadata={"action": action_name, "count": len(records), "job_id": job.id},
2886
+ )
2887
+ flash(f"Queued background job '{spec.label}' (#{job.id}).", "ok")
2888
+ return redirect(url_for(f"{bp_name}.jobs_list", focus=job.id))
2889
+
2890
+ try:
2891
+ msg = handler(records, request.form, user)
2892
+ sess.commit()
2893
+ except (ValueError, ValidationError, SQLAlchemyError) as exc:
2894
+ sess.rollback()
2895
+ flash(f"Action '{spec.label}' failed: {exc}", "danger")
2896
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2897
+ meta_payload: dict[str, Any] = {"action": action_name, "count": len(records)}
2898
+ if action_params:
2899
+ meta_payload["params"] = action_params
2900
+ deck._record_audit(
2901
+ action_name="bulk_action",
2902
+ view=view,
2903
+ record_pk=",".join(raw_pks[:10]),
2904
+ record_repr=f"{spec.label} ({len(records)} {view.plural_label})",
2905
+ metadata=meta_payload,
2906
+ )
2907
+ flash(str(msg or f"Executed '{spec.label}' on {len(records)} records."), "ok")
2908
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
2909
+
2910
+ # ---- Export (Streaming O(1) RAM + Background Async Export) ----
2911
+
2912
+ @bp.route("/<slug>/export.<fmt>")
2913
+ def model_export(slug: str, fmt: str) -> Response:
2914
+ if fmt.lower() not in {"csv", "json", "jsonl"}:
2915
+ abort(404)
2916
+ view = deck.get_view(slug)
2917
+ if not view.can_export:
2918
+ abort(403)
2919
+ deck._require_perm(f"{slug}:export", model_slug=slug)
2920
+
2921
+ filter_pairs = [
2922
+ (k[2:], v.strip())
2923
+ for k, v in request.args.items(multi=True)
2924
+ if k.startswith("f_") and v.strip()
2925
+ ]
2926
+ raw_ids = [p for p in request.args.get("ids", "").split(",") if p.strip()]
2927
+ selected_pks = [decode_pk(p, view.meta) for p in raw_ids]
2928
+ trashed = bool(view.soft_delete_column and request.args.get("trashed") == "1")
2929
+
2930
+ return stream_export_response(
2931
+ deck.get_session(view.bind_key),
2932
+ view,
2933
+ fmt=fmt,
2934
+ auth=deck.auth,
2935
+ user=deck._current_user(),
2936
+ search_term=request.args.get("q", "").strip(),
2937
+ filter_params=filter_pairs,
2938
+ active_tab_key=request.args.get("tab", "").strip() or None,
2939
+ selected_pks=selected_pks,
2940
+ sanitize_csv=deck.config.sanitize_csv,
2941
+ trashed=trashed,
2942
+ )
2943
+
2944
+ @bp.route("/<slug>/export-async", methods=["POST"])
2945
+ def model_export_async(slug: str) -> Any:
2946
+ if deck.job_backend is None:
2947
+ abort(404)
2948
+ view = deck.get_view(slug)
2949
+ if not view.can_export:
2950
+ abort(403)
2951
+ deck._require_perm(f"{slug}:export", model_slug=slug)
2952
+ fmt = request.form.get("fmt", "csv").strip().lower()
2953
+ if fmt not in {"csv", "json", "jsonl"}:
2954
+ abort(400)
2955
+ user = deck._current_user()
2956
+ search_q = request.form.get("q", "").strip()
2957
+ active_tab = request.form.get("tab", "").strip() or None
2958
+ trashed = bool(view.soft_delete_column and request.form.get("trashed") == "1")
2959
+ filter_pairs = [
2960
+ (k[2:], v.strip())
2961
+ for k, v in request.form.items(multi=True)
2962
+ if k.startswith("f_") and v.strip()
2963
+ ]
2964
+
2965
+ def _run_export(job_ctx: JobContext) -> str:
2966
+ job_ctx.set_progress(15, f"Streaming {view.plural_label} as {fmt.upper()}…")
2967
+ chunks, mimetype, fname = iter_export_chunks(
2968
+ deck.get_session(view.bind_key),
2969
+ view,
2970
+ fmt=fmt,
2971
+ auth=deck.auth,
2972
+ user=user,
2973
+ search_term=search_q,
2974
+ filter_params=filter_pairs,
2975
+ active_tab_key=active_tab,
2976
+ sanitize_csv=deck.config.sanitize_csv,
2977
+ trashed=trashed,
2978
+ )
2979
+ buf = io.BytesIO()
2980
+ for chunk in chunks:
2981
+ if job_ctx.is_cancelled():
2982
+ return "Export cancelled"
2983
+ buf.write(chunk.encode("utf-8"))
2984
+ payload = buf.getvalue()
2985
+ mime_base = mimetype.split(";", 1)[0].strip()
2986
+ key = build_storage_key(f"exports/{slug}", mime_base)
2987
+ deck.job_storage.save(payload, key=key, content_type=mime_base)
2988
+ job_ctx.attach_artifact(key=key, filename=fname, content_type=mime_base)
2989
+ job_ctx.log(f"Exported {len(payload):,} bytes to {fname}.")
2990
+ return f"Ready: {fname} ({len(payload) / 1024:.1f} KB)"
2991
+
2992
+ def _on_export_done(rec: JobRecord) -> None:
2993
+ ev_name = (
2994
+ "job.completed"
2995
+ if rec.status == "succeeded"
2996
+ else ("job.cancelled" if rec.status == "cancelled" else "job.failed")
2997
+ )
2998
+ deck._emit_event(
2999
+ ev_name,
3000
+ model_slug=slug,
3001
+ record_pk=rec.id,
3002
+ payload={"label": rec.label, "status": rec.status, "error": rec.error},
3003
+ actor=user,
3004
+ )
3005
+
3006
+ job = deck.job_backend.submit(
3007
+ name=f"{slug}:export:{fmt}",
3008
+ label=f"Export {view.plural_label} ({fmt.upper()})",
3009
+ actor_id=user.id if user else "system",
3010
+ actor_name=user.label if user else "System",
3011
+ model_slug=slug,
3012
+ fn=_run_export,
3013
+ app=deck.app,
3014
+ on_complete=_on_export_done,
3015
+ )
3016
+ deck._record_audit(
3017
+ action_name="async_job",
3018
+ view=view,
3019
+ record_pk=job.id,
3020
+ record_repr=job.label,
3021
+ metadata={"action": f"export_{fmt}", "job_id": job.id},
3022
+ )
3023
+ flash(f"Queued background export job #{job.id}.", "ok")
3024
+ return redirect(url_for(f"{bp_name}.jobs_list", focus=job.id))
3025
+
3026
+ # ---- Dry-Run Diff Import Wizard ----
3027
+
3028
+ @bp.route("/<slug>/import", methods=["GET", "POST"])
3029
+ def model_import(slug: str) -> Any:
3030
+ view = deck.get_view(slug)
3031
+ if not view.can_import:
3032
+ abort(403)
3033
+ deck._require_perm(f"{slug}:import", model_slug=slug)
3034
+
3035
+ user = deck._current_user()
3036
+ user_id = user.id if user else "anonymous"
3037
+ sess_token = str(session.get(CSRF_SESSION_KEY, ""))
3038
+
3039
+ # Candidate upsert keys (unique columns + PKs, never hidden/masked/sensitive)
3040
+ hidden = deck.auth.hidden_fields_for(user, slug)
3041
+ masked = deck.auth.masked_fields_for(user, slug)
3042
+ upsert_candidates = [
3043
+ f.name
3044
+ for f in view.meta.fields
3045
+ if (f.unique or f.primary_key or f.name in view.import_key_columns)
3046
+ and f.name not in hidden
3047
+ and f.name not in masked
3048
+ and not f.is_sensitive
3049
+ ]
3050
+
3051
+ report = None
3052
+ error_msg = ""
3053
+ bind_sess = deck.get_session(view.bind_key)
3054
+
3055
+ if request.method == "POST":
3056
+ step = request.form.get("step", "preview")
3057
+ if step == "commit":
3058
+ token = request.form.get("preview_token", "").strip()
3059
+ skip_errors = request.form.get("skip_errors") in {"1", "true", "on"}
3060
+ cached = deck._preview_store.consume(
3061
+ token,
3062
+ user_id=user_id,
3063
+ session_token=sess_token,
3064
+ model_slug=slug,
3065
+ )
3066
+ if cached is None:
3067
+ error_msg = "Preview token expired, already used, or invalid. Please re-run dry-run preview."
3068
+ elif cached.errors > 0 and not skip_errors:
3069
+ # Re-store token so operator can tick 'Skip errored rows' without re-uploading
3070
+ deck._preview_store.put(cached, user_id=user_id, session_token=sess_token)
3071
+ report = cached
3072
+ error_msg = (
3073
+ f"Import contains {cached.errors} errored row(s). "
3074
+ "Fix errors or enable 'Skip errored rows'."
3075
+ )
3076
+ else:
3077
+ try:
3078
+ created, updated = commit_dry_run_import(
3079
+ bind_sess,
3080
+ view,
3081
+ cached,
3082
+ user=user,
3083
+ skip_errors=skip_errors,
3084
+ )
3085
+ deck._record_audit(
3086
+ action_name="import",
3087
+ view=view,
3088
+ record_pk=f"batch:{created + updated}",
3089
+ record_repr=f"Imported {cached.filename} (+{created} / ~{updated})",
3090
+ metadata={
3091
+ "filename": cached.filename,
3092
+ "format": cached.format,
3093
+ "created": created,
3094
+ "updated": updated,
3095
+ "skipped_errors": cached.errors if skip_errors else 0,
3096
+ },
3097
+ )
3098
+ deck._emit_event(
3099
+ "import.committed",
3100
+ model_slug=slug,
3101
+ record_pk=f"batch:{created + updated}",
3102
+ payload={
3103
+ "filename": cached.filename,
3104
+ "created": created,
3105
+ "updated": updated,
3106
+ },
3107
+ )
3108
+ flash(
3109
+ f"Import committed: {created} created, {updated} updated.",
3110
+ "ok",
3111
+ )
3112
+ return redirect(url_for(f"{bp_name}.model_list", slug=slug))
3113
+ except (ImportLimitError, SQLAlchemyError) as exc:
3114
+ bind_sess.rollback()
3115
+ error_msg = str(exc)
3116
+ else:
3117
+ upload = request.files.get("file")
3118
+ raw_upsert = request.form.get("upsert_key", "").strip() or None
3119
+ upsert_key = raw_upsert if (raw_upsert and raw_upsert in upsert_candidates) else None
3120
+ if upload is None or not upload.filename:
3121
+ error_msg = "Select a CSV or JSON file to preview."
3122
+ else:
3123
+ # Bounded read: read max_upload_bytes + 1 so huge uploads fail fast without OOM.
3124
+ raw_bytes = upload.stream.read(deck.config.max_upload_bytes + 1)
3125
+ try:
3126
+ report = run_dry_run_import(
3127
+ bind_sess,
3128
+ view,
3129
+ raw_bytes=raw_bytes,
3130
+ filename=upload.filename,
3131
+ auth=deck.auth,
3132
+ user=user,
3133
+ upsert_key=upsert_key,
3134
+ max_bytes=deck.config.max_upload_bytes,
3135
+ max_rows=deck.config.max_import_rows,
3136
+ max_columns=deck.config.max_import_columns,
3137
+ max_json_depth=deck.config.max_json_depth,
3138
+ )
3139
+ deck._preview_store.put(
3140
+ report,
3141
+ user_id=user_id,
3142
+ session_token=sess_token,
3143
+ )
3144
+ except ImportLimitError as exc:
3145
+ error_msg = str(exc)
3146
+
3147
+ return render_template(
3148
+ "flask_deck/import_wizard.html",
3149
+ **deck._base_context(
3150
+ page_title=f"Import {view.plural_label}",
3151
+ active_nav=slug,
3152
+ view=view,
3153
+ report=report,
3154
+ error_msg=error_msg,
3155
+ upsert_candidates=upsert_candidates,
3156
+ ),
3157
+ )
3158
+
3159
+ # ---- Audit Log & Safe Revert ----
3160
+
3161
+ @bp.route("/_audit")
3162
+ def audit_list() -> str:
3163
+ if deck.audit_store is None:
3164
+ abort(404)
3165
+ deck._require_perm("audit:view")
3166
+ user = deck._current_user()
3167
+ model_filter = request.args.get("model", "").strip() or None
3168
+ action_filter = request.args.get("action", "").strip() or None
3169
+ actor_filter = request.args.get("actor", "").strip() or None
3170
+ q = request.args.get("q", "").strip() or None
3171
+ try:
3172
+ page = max(1, min(1_000_000, int(request.args.get("page", "1"))))
3173
+ except ValueError:
3174
+ page = 1
3175
+ limit = 40
3176
+ raw_entries, total = deck.audit_store.list_entries(
3177
+ model_slug=model_filter,
3178
+ action=action_filter,
3179
+ actor=actor_filter,
3180
+ search=q,
3181
+ limit=limit,
3182
+ offset=(page - 1) * limit,
3183
+ )
3184
+ entries = [
3185
+ deck._sanitize_audit_entry(e, user)
3186
+ for e in raw_entries
3187
+ if e.model_slug.startswith("_")
3188
+ or e.model_slug not in deck.views
3189
+ or deck.auth.has_permission(user, f"{e.model_slug}:view", model_slug=e.model_slug)
3190
+ ]
3191
+ pages = max(1, (total + limit - 1) // limit)
3192
+ can_revert = (
3193
+ deck.config.enable_audit_revert
3194
+ and not deck.config.read_only
3195
+ and deck.auth.has_permission(user, "audit:revert")
3196
+ )
3197
+ return render_template(
3198
+ "flask_deck/audit_list.html",
3199
+ **deck._base_context(
3200
+ page_title="Audit Ledger",
3201
+ active_nav="_audit",
3202
+ entries=entries,
3203
+ total=total,
3204
+ page=page,
3205
+ pages=pages,
3206
+ model_filter=model_filter or "",
3207
+ action_filter=action_filter or "",
3208
+ actor_filter=actor_filter or "",
3209
+ search_term=q or "",
3210
+ can_revert=can_revert,
3211
+ ),
3212
+ )
3213
+
3214
+ @bp.route("/_audit/<entry_id>/revert", methods=["POST"])
3215
+ def audit_revert(entry_id: str) -> Any:
3216
+ if deck.audit_store is None or not deck.config.enable_audit_revert:
3217
+ abort(404)
3218
+ deck._require_perm("audit:revert")
3219
+ entry = deck.audit_store.get_entry(entry_id)
3220
+ if entry is None or not entry.is_revertible:
3221
+ abort(404)
3222
+ view = deck.get_view(entry.model_slug)
3223
+ if not view.can_edit:
3224
+ abort(403)
3225
+ deck._require_perm(f"{view.meta.slug}:edit", model_slug=view.meta.slug)
3226
+ obj, pk_vals = deck._fetch_scoped_record(view, entry.record_pk)
3227
+ deck._require_perm(f"{view.meta.slug}:edit", model_slug=view.meta.slug, obj=obj)
3228
+
3229
+ if (
3230
+ deck.config.environment == "production"
3231
+ and deck.config.require_confirm_text_in_prod
3232
+ and request.form.get("confirm_text", "").strip() != "REVERT"
3233
+ ):
3234
+ flash("Production safeguard: enter 'REVERT' to confirm rollback.", "danger")
3235
+ return redirect(url_for(f"{bp_name}.audit_list"))
3236
+
3237
+ user = deck._current_user()
3238
+ writable = set(view.allowed_form_fields(deck.auth, user, mode="edit"))
3239
+ masked = deck.auth.masked_fields_for(user, view.meta.slug)
3240
+ before_snap = view.extract_snapshot(obj)
3241
+ sess = deck.get_session(view.bind_key)
3242
+ reverted_values: dict[str, Any] = {}
3243
+
3244
+ try:
3245
+ for fname, delta in entry.changes.items():
3246
+ if (
3247
+ fname not in writable
3248
+ or fname in masked
3249
+ or fname in view.meta.sensitive_fields
3250
+ or fname in view.file_fields
3251
+ ):
3252
+ continue
3253
+ old_val = delta.get("old")
3254
+ if old_val == "[REDACTED]":
3255
+ continue
3256
+ fmeta = view.meta.fields_by_name.get(fname)
3257
+ if fmeta is None or fmeta.field_type == "binary":
3258
+ continue
3259
+ coerced = (
3260
+ None
3261
+ if old_val is None
3262
+ else coerce_form_value(
3263
+ old_val,
3264
+ fmeta,
3265
+ max_json_depth=deck.config.max_json_depth,
3266
+ utc_passthrough=True,
3267
+ )
3268
+ )
3269
+ reverted_values[fname] = coerced
3270
+ if not reverted_values:
3271
+ flash("No revertible fields remain writable on this record.", "warn")
3272
+ return redirect(url_for(f"{bp_name}.audit_list"))
3273
+ custom_errs = view.validate(reverted_values, obj=obj)
3274
+ if custom_errs:
3275
+ raise ValidationError(custom_errs)
3276
+ val_fn = view.get_form_validator()
3277
+ if val_fn is not None:
3278
+ ext_errs = val_fn({**before_snap, **reverted_values}, obj, False)
3279
+ if ext_errs:
3280
+ raise ValidationError(dict(ext_errs))
3281
+ for fname, coerced in reverted_values.items():
3282
+ setattr(obj, fname, coerced)
3283
+ view.on_model_change(obj, is_created=False, user=user)
3284
+ sess.commit()
3285
+ except (ValueError, ValidationError, SQLAlchemyError) as exc:
3286
+ sess.rollback()
3287
+ flash(f"Revert failed: {exc}", "danger")
3288
+ return redirect(url_for(f"{bp_name}.audit_list"))
3289
+
3290
+ reverted_fields = len(reverted_values)
3291
+ pk_str = encode_pk(pk_vals)
3292
+ safe_repr = view.format_record_repr(obj, auth=deck.auth, user=user)
3293
+ after_snap = view.extract_snapshot(obj)
3294
+ diff = compute_diff(
3295
+ before_snap,
3296
+ after_snap,
3297
+ sensitive_fields=view.meta.sensitive_fields,
3298
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
3299
+ )
3300
+ deck._record_audit(
3301
+ action_name="revert",
3302
+ view=view,
3303
+ record_pk=pk_str,
3304
+ record_repr=safe_repr,
3305
+ changes=diff,
3306
+ metadata={"reverted_entry_id": entry.id, "fields": reverted_fields},
3307
+ )
3308
+ deck._emit_event(
3309
+ "record.updated",
3310
+ model_slug=view.meta.slug,
3311
+ record_pk=pk_str,
3312
+ payload={"reverted_entry_id": entry.id, "fields": sorted(reverted_values.keys())},
3313
+ )
3314
+ flash(f"Reverted {reverted_fields} field(s) on {safe_repr}.", "ok")
3315
+ return redirect(url_for(f"{bp_name}.audit_list"))
3316
+
3317
+ # ---- RBAC Matrix ----
3318
+
3319
+ @bp.route("/_rbac")
3320
+ def rbac_matrix() -> str:
3321
+ roles = list(deck.auth.get_roles())
3322
+ if not roles:
3323
+ abort(404)
3324
+ deck._require_perm("rbac:view")
3325
+ actions = ("view", "create", "edit", "delete", "export", "import")
3326
+ matrix: list[dict[str, Any]] = []
3327
+ for role in roles:
3328
+ model_rows = []
3329
+ for v in deck.views.values():
3330
+ slug = v.meta.slug
3331
+ grants = {act: role.grants(f"{slug}:{act}") for act in actions}
3332
+ hidden = sorted(
3333
+ set(role.hidden_fields.get("*", ())) | set(role.hidden_fields.get(slug, ()))
3334
+ )
3335
+ readonly = sorted(
3336
+ set(role.readonly_fields.get("*", ()))
3337
+ | set(role.readonly_fields.get(slug, ()))
3338
+ )
3339
+ masked = sorted(
3340
+ set(role.masked_fields.get("*", ())) | set(role.masked_fields.get(slug, ()))
3341
+ )
3342
+ model_rows.append(
3343
+ {
3344
+ "slug": slug,
3345
+ "label": v.plural_label,
3346
+ "grants": grants,
3347
+ "hidden": hidden,
3348
+ "readonly": readonly,
3349
+ "masked": masked,
3350
+ }
3351
+ )
3352
+ matrix.append(
3353
+ {
3354
+ "role": role,
3355
+ "audit_view": role.grants("audit:view"),
3356
+ "audit_revert": role.grants("audit:revert"),
3357
+ "models": model_rows,
3358
+ }
3359
+ )
3360
+ return render_template(
3361
+ "flask_deck/rbac_matrix.html",
3362
+ **deck._base_context(
3363
+ page_title="RBAC Policy Matrix",
3364
+ active_nav="_rbac",
3365
+ actions=actions,
3366
+ matrix=matrix,
3367
+ ),
3368
+ )
3369
+
3370
+ # ---- JSON & Partial APIs (⌘K Search, FK Combobox, Quick-Peek Drawer, Quick-Edit) ----
3371
+
3372
+ @bp.route("/_api/search")
3373
+ def api_search() -> Response:
3374
+ q = request.args.get("q", "").strip()
3375
+ user = deck._current_user()
3376
+ results: list[dict[str, Any]] = []
3377
+
3378
+ # Always include matching navigation models & commands
3379
+ q_lower = q.lower()
3380
+ for v in deck.views.values():
3381
+ if not v.can_view or not deck.auth.has_permission(
3382
+ user, f"{v.meta.slug}:view", model_slug=v.meta.slug
3383
+ ):
3384
+ continue
3385
+ if not q_lower or q_lower in v.plural_label.lower() or q_lower in v.meta.slug:
3386
+ results.append(
3387
+ {
3388
+ "kind": "model",
3389
+ "title": v.plural_label,
3390
+ "subtitle": f"Open {v.plural_label} table",
3391
+ "badge": "Model",
3392
+ "url": url_for(f"{bp_name}.model_list", slug=v.meta.slug),
3393
+ }
3394
+ )
3395
+
3396
+ # Live cross-model record search when query meets min length (multi-bind & soft-delete safe!)
3397
+ if len(q) >= deck.config.search_min_chars:
3398
+ for v in deck.views.values():
3399
+ if not v.can_view or not v.resolved_searchable:
3400
+ continue
3401
+ if not deck.auth.has_permission(
3402
+ user, f"{v.meta.slug}:view", model_slug=v.meta.slug
3403
+ ):
3404
+ continue
3405
+ allowed_search, _, _ = deck._allowed_query_fields(v, user)
3406
+ clause, joins = build_search_clause(v.meta, allowed_search, q)
3407
+ if clause is None:
3408
+ continue
3409
+ stmt = v.scope_query(sa.select(v.model), user)
3410
+ sd_pred = soft_delete_predicate(v.meta, v.soft_delete_column, trashed=False)
3411
+ if sd_pred is not None:
3412
+ stmt = stmt.where(sd_pred)
3413
+ for rel_attr in joins:
3414
+ stmt = stmt.outerjoin(rel_attr)
3415
+ stmt = stmt.where(clause).limit(deck.config.search_limit_per_model)
3416
+ for item in deck.get_session(v.bind_key).scalars(stmt).unique().all():
3417
+ pk_str = encode_pk(extract_pk(item, v.meta))
3418
+ results.append(
3419
+ {
3420
+ "kind": "record",
3421
+ "title": v.format_record_repr(item, auth=deck.auth, user=user),
3422
+ "subtitle": f"{v.label} #{pk_str}",
3423
+ "badge": v.label,
3424
+ "url": url_for(f"{bp_name}.model_detail", slug=v.meta.slug, raw_pk=pk_str),
3425
+ }
3426
+ )
3427
+
3428
+ return jsonify({"query": q, "results": results[:24]})
3429
+
3430
+ @bp.route("/_api/fk/<slug>")
3431
+ def api_fk(slug: str) -> Response:
3432
+ view = deck.get_view(slug)
3433
+ if not view.can_view:
3434
+ abort(404)
3435
+ deck._require_perm(f"{slug}:view", model_slug=slug)
3436
+ q = request.args.get("q", "").strip()
3437
+ dep_col = request.args.get("dep_col", "").strip()
3438
+ dep_val = request.args.get("dep_val", "").strip()
3439
+ user = deck._current_user()
3440
+ restricted = deck.auth.hidden_fields_for(user, slug) | deck.auth.masked_fields_for(
3441
+ user, slug
3442
+ )
3443
+ allowed_search, _, _ = deck._allowed_query_fields(view, user)
3444
+ stmt = view.scope_query(sa.select(view.model), user)
3445
+ sd_pred = soft_delete_predicate(view.meta, view.soft_delete_column, trashed=False)
3446
+ if sd_pred is not None:
3447
+ stmt = stmt.where(sd_pred)
3448
+ if (
3449
+ dep_col
3450
+ and dep_val
3451
+ and dep_col in view.meta.fields_by_name
3452
+ and dep_col not in restricted
3453
+ and not view.meta.fields_by_name[dep_col].is_sensitive
3454
+ ):
3455
+ cond = build_filter_condition(view.meta, dep_col, dep_val)
3456
+ if cond is not None:
3457
+ stmt = stmt.where(cond)
3458
+ if q and allowed_search:
3459
+ clause, joins = build_search_clause(view.meta, allowed_search, q)
3460
+ for rel_attr in joins:
3461
+ stmt = stmt.outerjoin(rel_attr)
3462
+ if clause is not None:
3463
+ stmt = stmt.where(clause)
3464
+ stmt = stmt.order_by(getattr(view.model, view.meta.primary_keys[0].name).asc()).limit(25)
3465
+ items = list(deck.get_session(view.bind_key).scalars(stmt).unique().all())
3466
+ return jsonify(
3467
+ {
3468
+ "items": [
3469
+ {
3470
+ "id": encode_pk(extract_pk(it, view.meta)),
3471
+ "label": view.format_record_repr(it, auth=deck.auth, user=user),
3472
+ }
3473
+ for it in items
3474
+ ]
3475
+ }
3476
+ )
3477
+
3478
+ @bp.route("/_api/<slug>/<raw_pk>/drawer")
3479
+ def api_drawer(slug: str, raw_pk: str) -> str:
3480
+ view = deck.get_view(slug)
3481
+ if not view.can_view:
3482
+ abort(404)
3483
+ deck._require_perm(f"{slug}:view", model_slug=slug)
3484
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
3485
+ deck._require_perm(f"{slug}:view", model_slug=slug, obj=obj)
3486
+ pk_str = encode_pk(pk_vals)
3487
+ user = deck._current_user()
3488
+ hidden = deck.auth.hidden_fields_for(user, slug)
3489
+ is_soft_deleted = deck._is_soft_deleted(view, obj)
3490
+
3491
+ media_builder = deck._media_url_builder(view)
3492
+ fields_display = []
3493
+ for f in view.meta.fields:
3494
+ if f.name in hidden or f.is_sensitive:
3495
+ continue
3496
+ fk_rel = view.meta.fk_column_to_rel.get(f.name)
3497
+ col_key = fk_rel.name if (fk_rel is not None and fk_rel.name not in hidden) else f.name
3498
+ fields_display.append(
3499
+ {
3500
+ "name": f.name,
3501
+ "label": view.get_column_label(f.name),
3502
+ "formatted": view.format_cell(
3503
+ col_key,
3504
+ obj,
3505
+ auth=deck.auth,
3506
+ user=user,
3507
+ media_url_builder=media_builder,
3508
+ rel_repr=deck._rel_repr,
3509
+ ),
3510
+ }
3511
+ )
3512
+ relations_display = []
3513
+ for rel in view.meta.relationships:
3514
+ if rel.name in hidden:
3515
+ continue
3516
+ val = getattr(obj, rel.name, None)
3517
+ rel_items = (
3518
+ list(val)
3519
+ if (rel.uselist and val is not None)
3520
+ else ([val] if val is not None else [])
3521
+ )
3522
+ relations_display.append(
3523
+ {
3524
+ "name": rel.name,
3525
+ "label": rel.label,
3526
+ "count": len(rel_items),
3527
+ "records": [deck._rel_repr(rel.target_model, it) for it in rel_items[:20]],
3528
+ }
3529
+ )
3530
+ history: list[AuditEntry] = []
3531
+ if deck.audit_store is not None and deck.auth.has_permission(user, "audit:view"):
3532
+ raw_hist, _ = deck.audit_store.list_entries(
3533
+ model_slug=slug, record_pk=pk_str, limit=10
3534
+ )
3535
+ history = [deck._sanitize_audit_entry(e, user) for e in raw_hist]
3536
+ can_edit = (
3537
+ view.can_edit
3538
+ and not is_soft_deleted
3539
+ and not deck.config.read_only
3540
+ and deck.auth.has_permission(user, f"{slug}:edit", model_slug=slug, obj=obj)
3541
+ )
3542
+ can_create = (
3543
+ view.can_create
3544
+ and not is_soft_deleted
3545
+ and not deck.config.read_only
3546
+ and deck.auth.has_permission(user, f"{slug}:create", model_slug=slug)
3547
+ )
3548
+ can_revert = (
3549
+ deck.config.enable_audit_revert
3550
+ and not deck.config.read_only
3551
+ and deck.auth.has_permission(user, "audit:revert")
3552
+ )
3553
+ active_tz = str(getattr(g, "_flask_deck_tz", deck.config.default_timezone))
3554
+ return render_template(
3555
+ "flask_deck/partials/drawer_detail.html",
3556
+ view=view,
3557
+ bp_name=bp_name,
3558
+ pk_str=pk_str,
3559
+ record_repr=view.format_record_repr(obj, auth=deck.auth, user=user),
3560
+ fields_display=fields_display,
3561
+ relations_display=relations_display,
3562
+ history=history,
3563
+ can_edit=can_edit,
3564
+ can_create=can_create,
3565
+ can_revert=can_revert,
3566
+ csrf_field=CSRF_FORM_FIELD,
3567
+ csrf_token=get_csrf_token(),
3568
+ config=deck.config,
3569
+ deck_icon=render_icon,
3570
+ _=deck.translator.translate,
3571
+ format_dt=lambda dt, fmt="%Y-%m-%d %H:%M": (
3572
+ to_user_timezone(dt, active_tz).strftime(fmt)
3573
+ if isinstance(dt, datetime)
3574
+ else str(dt)
3575
+ ),
3576
+ )
3577
+
3578
+ @bp.route("/_api/<slug>/<raw_pk>/quick-edit", methods=["PATCH"])
3579
+ def api_quick_edit(slug: str, raw_pk: str) -> tuple[Response, int]:
3580
+ view = deck.get_view(slug)
3581
+ if not view.can_edit:
3582
+ return jsonify({"error": "Editing is disabled for this model."}), 403
3583
+ deck._require_perm(f"{slug}:edit", model_slug=slug)
3584
+ obj, pk_vals = deck._fetch_scoped_record(view, raw_pk)
3585
+ deck._require_perm(f"{slug}:edit", model_slug=slug, obj=obj)
3586
+ if deck._is_soft_deleted(view, obj):
3587
+ return jsonify({"error": "Restore record from Trash before editing."}), 409
3588
+
3589
+ payload = request.get_json(silent=True)
3590
+ if not isinstance(payload, Mapping):
3591
+ return jsonify({"error": "Expected JSON object payload."}), 400
3592
+
3593
+ field_name = str(payload.get("field", "")).strip()
3594
+ user = deck._current_user()
3595
+ writable = set(view.allowed_form_fields(deck.auth, user, mode="edit")) - deck.auth.masked_fields_for(
3596
+ user, slug
3597
+ )
3598
+ quick_allowed = set(view.resolved_inline_editable)
3599
+ if view.kanban_column:
3600
+ quick_allowed.add(view.kanban_column)
3601
+ if field_name not in quick_allowed or field_name not in writable:
3602
+ return jsonify({"error": f"Field '{field_name}' is not inline-editable."}), 403
3603
+
3604
+ fmeta = view.meta.fields_by_name[field_name]
3605
+ before_snap = view.extract_snapshot(obj)
3606
+ try:
3607
+ coerced = coerce_form_value(
3608
+ payload.get("value"), fmeta, max_json_depth=deck.config.max_json_depth
3609
+ )
3610
+ except ValueError as exc:
3611
+ return jsonify({"error": str(exc)}), 422
3612
+
3613
+ custom_errs = view.validate({field_name: coerced}, obj=obj)
3614
+ if custom_errs:
3615
+ return jsonify({"error": "; ".join(custom_errs.get(field_name, ["Invalid value"]))}), 422
3616
+ val_fn = view.get_form_validator()
3617
+ if val_fn is not None:
3618
+ ext_errs = val_fn({**before_snap, field_name: coerced}, obj, False)
3619
+ if ext_errs:
3620
+ first_msgs = next(iter(ext_errs.values()), ["Validation failed."])
3621
+ return jsonify({"error": "; ".join(first_msgs)}), 422
3622
+
3623
+ sess = deck.get_session(view.bind_key)
3624
+ try:
3625
+ setattr(obj, field_name, coerced)
3626
+ view.on_model_change(obj, is_created=False, user=user)
3627
+ sess.commit()
3628
+ except ValidationError as exc:
3629
+ sess.rollback()
3630
+ first_msgs = next(iter(exc.errors.values()), ["Validation failed."])
3631
+ return jsonify({"error": "; ".join(first_msgs)}), 422
3632
+ except SQLAlchemyError as exc:
3633
+ sess.rollback()
3634
+ return jsonify({"error": f"Database error: {exc.__class__.__name__}"}), 400
3635
+
3636
+ pk_str = encode_pk(pk_vals)
3637
+ safe_repr = view.format_record_repr(obj, auth=deck.auth, user=user)
3638
+ after_snap = view.extract_snapshot(obj)
3639
+ diff = compute_diff(
3640
+ before_snap,
3641
+ after_snap,
3642
+ sensitive_fields=view.meta.sensitive_fields,
3643
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
3644
+ )
3645
+ if diff:
3646
+ deck._record_audit(
3647
+ action_name="inline_edit",
3648
+ view=view,
3649
+ record_pk=pk_str,
3650
+ record_repr=safe_repr,
3651
+ changes=diff,
3652
+ )
3653
+ deck._emit_event(
3654
+ "record.updated",
3655
+ model_slug=slug,
3656
+ record_pk=pk_str,
3657
+ payload={"fields": sorted(diff.keys()), "inline": True},
3658
+ )
3659
+ rendered = view.format_cell(
3660
+ field_name, obj, auth=deck.auth, user=user, rel_repr=deck._rel_repr
3661
+ )
3662
+ return (
3663
+ jsonify(
3664
+ {
3665
+ "ok": True,
3666
+ "field": field_name,
3667
+ "value": coerced.value if hasattr(coerced, "value") else coerced,
3668
+ "display": str(Markup.escape(rendered)),
3669
+ }
3670
+ ),
3671
+ 200,
3672
+ )
3673
+
3674
+ # ---- Governance: Schema ERD, Security Diagnostics, Read-Only SQL Console, Custom Pages ----
3675
+
3676
+ @bp.route("/_schema")
3677
+ def schema_inspector() -> str:
3678
+ user = deck._current_user()
3679
+ if not (
3680
+ deck.auth.has_permission(user, "schema:view")
3681
+ or deck.auth.has_permission(user, "*:view")
3682
+ ):
3683
+ raise PermissionDeniedError("Missing permission: schema:view")
3684
+
3685
+ authorized_views = [
3686
+ v
3687
+ for v in deck.views.values()
3688
+ if v.can_view
3689
+ and deck.auth.has_permission(user, f"{v.meta.slug}:view", model_slug=v.meta.slug)
3690
+ ]
3691
+ row_counts: dict[str, int] = {}
3692
+ by_bind: dict[str | None, list[ModelView]] = {}
3693
+ for v in authorized_views:
3694
+ by_bind.setdefault(v.bind_key, []).append(v)
3695
+ for bk, b_views in by_bind.items():
3696
+ subs = []
3697
+ for v in b_views:
3698
+ q = v.scope_query(sa.select(sa.func.count()).select_from(v.model), user)
3699
+ sd_pred = soft_delete_predicate(v.meta, v.soft_delete_column, trashed=False)
3700
+ if sd_pred is not None:
3701
+ q = q.where(sd_pred)
3702
+ subs.append(q.scalar_subquery().label(v.meta.slug))
3703
+ row = deck.get_session(bk).execute(sa.select(*subs)).first()
3704
+ if row is not None:
3705
+ for idx, v in enumerate(b_views):
3706
+ row_counts[v.meta.slug] = int(row[idx] or 0)
3707
+
3708
+ metas = [v.meta for v in authorized_views]
3709
+ erd_svg = render_schema_erd_svg(metas, row_counts)
3710
+ return render_template(
3711
+ "flask_deck/schema_inspector.html",
3712
+ **deck._base_context(
3713
+ page_title="Schema ERD & Index Inspector",
3714
+ active_nav="_schema",
3715
+ erd_svg=erd_svg,
3716
+ views=authorized_views,
3717
+ row_counts=row_counts,
3718
+ ),
3719
+ )
3720
+
3721
+ @bp.route("/_diagnostics")
3722
+ def diagnostics() -> str:
3723
+ user = deck._current_user()
3724
+ if not (
3725
+ deck.auth.has_permission(user, "diagnostics:view")
3726
+ or (user is not None and user.is_superuser)
3727
+ ):
3728
+ raise PermissionDeniedError("Missing permission: diagnostics:view")
3729
+
3730
+ assert deck.app is not None
3731
+ findings = run_security_audit(deck.app, deck)
3732
+ css_path = _STATIC_DIR / "css" / "deck.css"
3733
+ js_path = _STATIC_DIR / "js" / "deck.js"
3734
+ css_gz = len(gzip.compress(css_path.read_bytes(), 9)) if css_path.is_file() else 0
3735
+ js_gz = len(gzip.compress(js_path.read_bytes(), 9)) if js_path.is_file() else 0
3736
+ total_cols = sum(len(v.meta.fields) for v in deck.views.values())
3737
+ total_idx = sum(len(v.meta.indexed_fields) for v in deck.views.values())
3738
+ total_redacted = sum(len(v.meta.sensitive_fields) for v in deck.views.values())
3739
+
3740
+ checks = [
3741
+ ("Strict Nonce CSP (0 unsafe-inline)", "PASS", "ok"),
3742
+ ("Double-Layer CSRF + Sec-Fetch-Site", "PASS", "ok"),
3743
+ (
3744
+ "Authentication Provider",
3745
+ deck.auth.__class__.__name__,
3746
+ "warn" if isinstance(deck.auth, OpenAuthProvider) else "ok",
3747
+ ),
3748
+ (
3749
+ "Audit Ledger Backend",
3750
+ deck.audit_store.__class__.__name__ if deck.audit_store else "Disabled",
3751
+ "ok" if deck.audit_store else "warn",
3752
+ ),
3753
+ (
3754
+ "Read-Only SQL Console",
3755
+ "Enabled (SELECT/WITH/EXPLAIN)" if deck.config.enable_sql_console else "Disabled",
3756
+ "info" if deck.config.enable_sql_console else "neutral",
3757
+ ),
3758
+ (
3759
+ "TOTP 2FA Store",
3760
+ deck.mfa_store.__class__.__name__ if deck.mfa_store else "Disabled",
3761
+ "ok" if deck.mfa_store else "warn",
3762
+ ),
3763
+ (
3764
+ "Brand Theme Engine",
3765
+ f"{deck.config.brand.accent} (/_theme.css, 0 inline style)",
3766
+ "ok",
3767
+ ),
3768
+ (
3769
+ "SQLAlchemy Engine Binds",
3770
+ ", ".join(sorted(deck.adapter.get_engines().keys())) if deck.adapter else "default",
3771
+ "info",
3772
+ ),
3773
+ ]
3774
+ return render_template(
3775
+ "flask_deck/diagnostics.html",
3776
+ **deck._base_context(
3777
+ page_title="Security & Index Diagnostics",
3778
+ active_nav="_diagnostics",
3779
+ findings=findings,
3780
+ checks=checks,
3781
+ asset_kb=round((css_gz + js_gz) / 1024.0, 2),
3782
+ css_kb=round(css_gz / 1024.0, 2),
3783
+ js_kb=round(js_gz / 1024.0, 2),
3784
+ total_cols=total_cols,
3785
+ total_idx=total_idx,
3786
+ total_redacted=total_redacted,
3787
+ ),
3788
+ )
3789
+
3790
+ @bp.route("/_sql", methods=["GET", "POST"])
3791
+ def sql_console() -> Any:
3792
+ if not deck.config.enable_sql_console:
3793
+ abort(404)
3794
+ deck._require_perm("sql:query")
3795
+
3796
+ default_sql = (
3797
+ deck._sql_presets[0][1]
3798
+ if deck._sql_presets
3799
+ else (
3800
+ f"SELECT * FROM {next(iter(deck.views.values())).meta.table_name} LIMIT 25"
3801
+ if deck.views
3802
+ else "SELECT 1 AS ok"
3803
+ )
3804
+ )
3805
+ sql_text = default_sql
3806
+ result: SQLQueryResult | None = None
3807
+
3808
+ if request.method == "POST":
3809
+ sql_text = request.form.get("sql", "").strip()
3810
+ out_mode = request.form.get("output", "table").strip().lower()
3811
+ assert deck.adapter is not None
3812
+ result = execute_readonly_sql(
3813
+ deck.adapter.get_engine(),
3814
+ sql_text,
3815
+ max_rows=deck.config.sql_console_max_rows,
3816
+ extra_sensitive_patterns=deck.config.extra_sensitive_patterns,
3817
+ )
3818
+ if deck.audit_store is not None and deck.config.auto_audit:
3819
+ user = deck._current_user()
3820
+ sql_meta: dict[str, Any] = {
3821
+ "rows": result.row_count,
3822
+ "ms": round(result.duration_ms, 2),
3823
+ "status": "blocked" if result.error else "ok",
3824
+ }
3825
+ real = getattr(g, "_deck_real_user", None)
3826
+ if real is not None and (user is None or real.id != user.id):
3827
+ sql_meta["impersonated_by"] = real.id
3828
+ sql_meta["impersonated_by_name"] = real.label
3829
+ deck.audit_store.record(
3830
+ make_audit_entry(
3831
+ actor_id=user.id if user else "system",
3832
+ actor_name=user.label if user else "System",
3833
+ actor_ip=_client_ip(),
3834
+ action="sql_query",
3835
+ model_slug="_sql",
3836
+ model_label="SQL Console",
3837
+ record_pk="readonly",
3838
+ record_repr=sql_text[:120],
3839
+ metadata=sql_meta,
3840
+ )
3841
+ )
3842
+ if out_mode == "csv" and result.error is None and result.columns:
3843
+ csv_data = format_sql_result_csv(
3844
+ result.columns,
3845
+ result.rows,
3846
+ sanitize_csv=deck.config.sanitize_csv,
3847
+ )
3848
+ resp = Response(csv_data, mimetype="text/csv; charset=utf-8")
3849
+ resp.headers["Content-Disposition"] = 'attachment; filename="sql-query-result.csv"'
3850
+ return resp
3851
+
3852
+ return render_template(
3853
+ "flask_deck/sql_console.html",
3854
+ **deck._base_context(
3855
+ page_title="Read-Only SQL Console",
3856
+ active_nav="_sql",
3857
+ sql_text=sql_text,
3858
+ result=result,
3859
+ sql_presets=deck._sql_presets,
3860
+ tables=[v.meta.table_name for v in deck.views.values() if not v.bind_key],
3861
+ ),
3862
+ )
3863
+
3864
+ @bp.route("/_page/<page_slug>")
3865
+ def custom_page(page_slug: str) -> str:
3866
+ spec = deck.custom_pages.get(page_slug)
3867
+ if spec is None:
3868
+ abort(404)
3869
+ user = deck._current_user()
3870
+ if spec.permission:
3871
+ if not deck.auth.has_permission(user, spec.permission):
3872
+ raise PermissionDeniedError(f"Missing permission: {spec.permission}")
3873
+ else:
3874
+ perm = f"page:{spec.slug}:view"
3875
+ if not (
3876
+ deck.auth.has_permission(user, perm)
3877
+ or deck.auth.has_permission(user, "*:view")
3878
+ ):
3879
+ raise PermissionDeniedError(f"Missing permission: {perm}")
3880
+
3881
+ ctx = DashboardContext(deck, deck.get_session(), user)
3882
+ raw_widgets = list(spec.handler(ctx))
3883
+ widgets: list[Widget] = []
3884
+ for w in raw_widgets:
3885
+ if isinstance(w, ActivityWidget) and not w.entries:
3886
+ widgets.append(
3887
+ ActivityWidget(
3888
+ title=w.title,
3889
+ subtitle=w.subtitle,
3890
+ col_span=w.col_span,
3891
+ limit=w.limit,
3892
+ entries=ctx.recent_audit_entries(limit=w.limit),
3893
+ )
3894
+ )
3895
+ else:
3896
+ widgets.append(w)
3897
+ return render_template(
3898
+ "flask_deck/custom_page.html",
3899
+ **deck._base_context(
3900
+ page_title=spec.title,
3901
+ active_nav=f"_page:{spec.slug}",
3902
+ page_spec=spec,
3903
+ widgets=widgets,
3904
+ ),
3905
+ )
3906
+
3907
+ @bp.route("/_api/notifications")
3908
+ def api_notifications() -> Response:
3909
+ user = deck._current_user()
3910
+ active_tz = str(getattr(g, "_flask_deck_tz", deck.config.default_timezone))
3911
+ items: list[dict[str, str]] = []
3912
+ if deck.audit_store is not None and deck.auth.has_permission(user, "audit:view"):
3913
+ entries, _ = deck.audit_store.list_entries(limit=24)
3914
+ for e in entries:
3915
+ if e.model_slug in deck.views and not deck.auth.has_permission(
3916
+ user, f"{e.model_slug}:view", model_slug=e.model_slug
3917
+ ):
3918
+ continue
3919
+ safe_e = deck._sanitize_audit_entry(e, user)
3920
+ items.append(
3921
+ {
3922
+ "action": safe_e.action,
3923
+ "title": f"{safe_e.model_label} · {safe_e.record_repr}",
3924
+ "actor": safe_e.actor_name,
3925
+ "time": to_user_timezone(safe_e.timestamp, active_tz).strftime("%m-%d %H:%M"),
3926
+ "url": url_for(f"{bp_name}.audit_list"),
3927
+ }
3928
+ )
3929
+ if len(items) >= 8:
3930
+ break
3931
+ return jsonify({"items": items})
3932
+
3933
+ @bp.route("/_jobs")
3934
+ def jobs_list() -> str:
3935
+ if deck.job_backend is None:
3936
+ abort(404)
3937
+ user = deck._current_user()
3938
+ can_all = deck.auth.has_permission(user, "jobs:view_all") or (
3939
+ user is not None and user.is_superuser
3940
+ )
3941
+ actor_filter = None if can_all else (user.id if user else "__none__")
3942
+ jobs = deck.job_backend.list_jobs(actor_id=actor_filter, limit=50)
3943
+ focus_id = request.args.get("focus", "").strip()
3944
+ return render_template(
3945
+ "flask_deck/jobs_list.html",
3946
+ **deck._base_context(
3947
+ page_title="Background Jobs",
3948
+ active_nav="_jobs",
3949
+ jobs=jobs,
3950
+ focus_id=focus_id,
3951
+ ),
3952
+ )
3953
+
3954
+ def _get_authorized_job(job_id: str, *, mode: str = "view") -> JobRecord:
3955
+ if deck.job_backend is None:
3956
+ abort(404)
3957
+ rec = deck.job_backend.get(job_id)
3958
+ if rec is None:
3959
+ abort(404)
3960
+ user = deck._current_user()
3961
+ is_owner = user is not None and rec.actor_id == user.id
3962
+ is_super = user is not None and user.is_superuser
3963
+ if mode == "artifact":
3964
+ allowed = is_owner or is_super
3965
+ elif mode == "cancel":
3966
+ allowed = is_owner or is_super or deck.auth.has_permission(user, "jobs:cancel_all")
3967
+ else:
3968
+ allowed = is_owner or is_super or deck.auth.has_permission(user, "jobs:view_all")
3969
+ if not allowed:
3970
+ raise PermissionDeniedError("Not authorized to access this background job.")
3971
+ return rec
3972
+
3973
+ @bp.route("/_api/jobs/<job_id>")
3974
+ def api_job_status(job_id: str) -> Any:
3975
+ if deck.job_backend is None or deck.job_backend.get(job_id) is None:
3976
+ return jsonify({"error": "Job not found."}), 404
3977
+ rec = _get_authorized_job(job_id, mode="view")
3978
+ return jsonify(rec.to_dict())
3979
+
3980
+ @bp.route("/_api/jobs/<job_id>/stream")
3981
+ def api_job_stream(job_id: str) -> Any:
3982
+ if deck.job_backend is None or deck.job_backend.get(job_id) is None:
3983
+ return jsonify({"error": "Job not found."}), 404
3984
+ rec = _get_authorized_job(job_id, mode="view")
3985
+ backend = deck.job_backend
3986
+ assert backend is not None
3987
+
3988
+ def _gen() -> Iterator[str]:
3989
+ yield "retry: 1500\n"
3990
+ for _ in range(40):
3991
+ cur = backend.get(rec.id)
3992
+ if cur is None:
3993
+ break
3994
+ yield f"data: {json.dumps(cur.to_dict())}\n\n"
3995
+ if cur.status in TERMINAL_JOB_STATUSES:
3996
+ break
3997
+ time.sleep(0.25)
3998
+
3999
+ resp = Response(stream_with_context(_gen()), mimetype="text/event-stream")
4000
+ resp.headers["Cache-Control"] = "no-cache, no-store"
4001
+ resp.headers["X-Accel-Buffering"] = "no"
4002
+ return resp
4003
+
4004
+ @bp.route("/_jobs/<job_id>/cancel", methods=["POST"])
4005
+ def job_cancel(job_id: str) -> Any:
4006
+ rec = _get_authorized_job(job_id, mode="cancel")
4007
+ assert deck.job_backend is not None
4008
+ if deck.job_backend.cancel(rec.id):
4009
+ flash(f"Cancellation requested for job #{rec.id}.", "warn")
4010
+ else:
4011
+ flash(f"Job #{rec.id} is already finished.", "neutral")
4012
+ return redirect(url_for(f"{bp_name}.jobs_list", focus=rec.id))
4013
+
4014
+ @bp.route("/_jobs/<job_id>/artifact")
4015
+ def job_artifact(job_id: str) -> Response:
4016
+ rec = _get_authorized_job(job_id, mode="artifact")
4017
+ if not rec.artifact_key or not rec.artifact_filename:
4018
+ abort(404)
4019
+ try:
4020
+ stream, detected = deck.job_storage.open(rec.artifact_key)
4021
+ except (FileNotFoundError, ValueError):
4022
+ abort(404)
4023
+ try:
4024
+ data = stream.read()
4025
+ finally:
4026
+ stream.close()
4027
+ mime = rec.artifact_mime or detected or "application/octet-stream"
4028
+ safe_name = sanitize_filename(rec.artifact_filename)
4029
+ resp = Response(data, mimetype=mime)
4030
+ resp.headers["Content-Disposition"] = f'attachment; filename="{safe_name}"'
4031
+ resp.headers["Content-Security-Policy"] = "default-src 'none'; sandbox"
4032
+ resp.headers["X-Content-Type-Options"] = "nosniff"
4033
+ return resp
4034
+
4035
+ @bp.route("/_demo/switch-role", methods=["POST"])
4036
+ def demo_switch_role() -> Any:
4037
+ if (
4038
+ not deck.config.demo_role_switcher
4039
+ or deck.config.environment == "production"
4040
+ or not isinstance(deck.auth, RBACAuthProvider)
4041
+ ):
4042
+ abort(404)
4043
+ target_id = request.form.get("account_id", "").strip()
4044
+ target_user = deck.auth.get_account_by_id(target_id)
4045
+ if target_user is None:
4046
+ abort(404)
4047
+ deck.auth.login_user(target_user)
4048
+ flash(
4049
+ f"Switched demo session role to {target_user.label} ({', '.join(target_user.roles)}).",
4050
+ "ok",
4051
+ )
4052
+ nxt = request.form.get("next", "").strip()
4053
+ dest = nxt if is_safe_redirect_url(nxt) else url_for(f"{bp_name}.index")
4054
+ return redirect(dest)
4055
+
4056
+ return bp
4057
+
4058
+
4059
+ def run_security_audit(app: Flask, deck: Deck) -> list[dict[str, str]]:
4060
+ """Inspect Flask + Deck configuration and SQLAlchemy indexes for security/performance findings."""
4061
+ findings: list[dict[str, str]] = []
4062
+
4063
+ secret = app.secret_key
4064
+ if not secret:
4065
+ findings.append(
4066
+ {"severity": "CRITICAL", "category": "security", "message": "app.secret_key is not set."}
4067
+ )
4068
+ elif isinstance(secret, (str, bytes)) and len(secret) < 32:
4069
+ findings.append(
4070
+ {
4071
+ "severity": "WARN",
4072
+ "category": "security",
4073
+ "message": f"app.secret_key length is {len(secret)} bytes (recommended >= 32 bytes).",
4074
+ }
4075
+ )
4076
+
4077
+ if not app.config.get("SESSION_COOKIE_HTTPONLY", True):
4078
+ findings.append(
4079
+ {
4080
+ "severity": "HIGH",
4081
+ "category": "security",
4082
+ "message": "SESSION_COOKIE_HTTPONLY is False; session cookies are readable by JS.",
4083
+ }
4084
+ )
4085
+ if not app.config.get("SESSION_COOKIE_SAMESITE"):
4086
+ findings.append(
4087
+ {
4088
+ "severity": "WARN",
4089
+ "category": "security",
4090
+ "message": "SESSION_COOKIE_SAMESITE is unset (recommended 'Lax' or 'Strict').",
4091
+ }
4092
+ )
4093
+ if deck.config.environment == "production" and not app.config.get("SESSION_COOKIE_SECURE", False):
4094
+ findings.append(
4095
+ {
4096
+ "severity": "HIGH",
4097
+ "category": "security",
4098
+ "message": "SESSION_COOKIE_SECURE is False in production environment.",
4099
+ }
4100
+ )
4101
+ if isinstance(deck.auth, OpenAuthProvider):
4102
+ findings.append(
4103
+ {
4104
+ "severity": "CRITICAL" if deck.config.environment == "production" else "WARN",
4105
+ "category": "auth",
4106
+ "message": "Deck is using OpenAuthProvider (unauthenticated access).",
4107
+ }
4108
+ )
4109
+ if deck.config.environment == "production" and not deck.config.require_mfa_for_superusers:
4110
+ findings.append(
4111
+ {
4112
+ "severity": "WARN",
4113
+ "category": "auth",
4114
+ "message": "require_mfa_for_superusers is False in production (enable TOTP 2FA enforcement).",
4115
+ }
4116
+ )
4117
+ if deck.config.environment == "production" and deck.config.demo_role_switcher:
4118
+ findings.append(
4119
+ {
4120
+ "severity": "HIGH",
4121
+ "category": "security",
4122
+ "message": "demo_role_switcher is enabled in config (locked out in production, set False).",
4123
+ }
4124
+ )
4125
+
4126
+ # Schema performance & sensitive-column checks
4127
+ for view in deck.views.values():
4128
+ meta: ModelMeta = view.meta
4129
+ for col_spec in view.resolved_searchable:
4130
+ if "." in col_spec:
4131
+ continue
4132
+ if col_spec not in meta.indexed_fields:
4133
+ findings.append(
4134
+ {
4135
+ "severity": "INFO",
4136
+ "category": "performance",
4137
+ "message": (
4138
+ f"{meta.name}.{col_spec} is in searchable_columns without a DB index "
4139
+ "(consider adding index=True for large tables)."
4140
+ ),
4141
+ }
4142
+ )
4143
+ for col in view.columns or view.list_columns:
4144
+ if col in meta.sensitive_fields:
4145
+ findings.append(
4146
+ {
4147
+ "severity": "HIGH",
4148
+ "category": "privacy",
4149
+ "message": f"Sensitive column {meta.name}.{col} appears in declared columns.",
4150
+ }
4151
+ )
4152
+
4153
+ return findings