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
@@ -0,0 +1,391 @@
1
+ from __future__ import annotations
2
+
3
+ import contextlib
4
+ import csv
5
+ import io
6
+ import re
7
+ import time
8
+ from collections.abc import Iterable, Sequence
9
+ from dataclasses import dataclass
10
+ from typing import Any
11
+
12
+ import sqlalchemy as sa
13
+ from sqlalchemy.engine import Engine
14
+ from sqlalchemy.exc import SQLAlchemyError
15
+
16
+ from flask_deck.security import is_sensitive_field, sanitize_csv_cell
17
+
18
+ _ALLOWED_LEADING = frozenset({"SELECT", "WITH", "EXPLAIN"})
19
+
20
+ # Defense-in-depth denylist of mutating / administrative / side-effect keywords & functions.
21
+ _FORBIDDEN_KEYWORDS_RE = re.compile(
22
+ r"\b(?:INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|REPLACE|TRUNCATE|MERGE|UPSERT|"
23
+ r"GRANT|REVOKE|ATTACH|DETACH|PRAGMA|VACUUM|REINDEX|COPY|CALL|EXEC|EXECUTE|"
24
+ r"COMMIT|ROLLBACK|BEGIN|SAVEPOINT|RELEASE|SET|RESET|"
25
+ r"LOAD_EXTENSION|INTO\s+OUTFILE|INTO\s+DUMPFILE|"
26
+ r"PG_READ_FILE|PG_READ_BINARY_FILE|PG_WRITE_FILE|PG_LS_DIR|PG_STAT_FILE|"
27
+ r"PG_SLEEP|PG_TERMINATE_BACKEND|PG_CANCEL_BACKEND|PG_RELOAD_CONF|"
28
+ r"SET_CONFIG|DBLINK|DBLINK_EXEC|QUERY_TO_XML|"
29
+ r"LO_IMPORT|LO_EXPORT|LO_FROM_BYTEA|LO_UNLINK)\b",
30
+ re.IGNORECASE,
31
+ )
32
+
33
+ # Internal security & database credential tables that must never be queried via the console.
34
+ _FORBIDDEN_TABLES_RE = re.compile(
35
+ r"\b(?:_flask_deck_mfa|pg_authid|pg_shadow|pg_roles|mysql\.user|sqlite_temp_master)\b",
36
+ re.IGNORECASE,
37
+ )
38
+
39
+ _IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
40
+
41
+
42
+ @dataclass(frozen=True, slots=True)
43
+ class SQLQueryResult:
44
+ """Result returned by the read-only SQL Console."""
45
+
46
+ sql: str
47
+ columns: tuple[str, ...]
48
+ rows: tuple[tuple[Any, ...], ...]
49
+ row_count: int
50
+ truncated: bool
51
+ redacted_columns: tuple[str, ...]
52
+ duration_ms: float
53
+ error: str | None = None
54
+
55
+
56
+ def _strip_sql_comments_and_literals(sql: str) -> tuple[str, list[str]]:
57
+ """Single-pass SQL lexer removing comments & replacing string literals without regex order bugs.
58
+
59
+ Returns ``(normalized_sql, quoted_identifiers)`` where comments become spaces,
60
+ string literals become ``''``, and double-quoted identifiers remain inspectable.
61
+ Raises ``ValueError`` on unterminated strings or comments.
62
+ """
63
+ out: list[str] = []
64
+ quoted_idents: list[str] = []
65
+ n = len(sql)
66
+ i = 0
67
+
68
+ while i < n:
69
+ ch = sql[i]
70
+ nxt = sql[i + 1] if i + 1 < n else ""
71
+
72
+ # Line comment: -- ...
73
+ if ch == "-" and nxt == "-":
74
+ i += 2
75
+ while i < n and sql[i] != "\n":
76
+ i += 1
77
+ out.append(" ")
78
+ continue
79
+
80
+ # MySQL line comment: # ...
81
+ if ch == "#":
82
+ i += 1
83
+ while i < n and sql[i] != "\n":
84
+ i += 1
85
+ out.append(" ")
86
+ continue
87
+
88
+ # Block comment: /* ... */ (supports PostgreSQL nested block comments)
89
+ if ch == "/" and nxt == "*":
90
+ depth = 1
91
+ i += 2
92
+ while i < n and depth > 0:
93
+ if i + 1 < n and sql[i] == "/" and sql[i + 1] == "*":
94
+ depth += 1
95
+ i += 2
96
+ elif i + 1 < n and sql[i] == "*" and sql[i + 1] == "/":
97
+ depth -= 1
98
+ i += 2
99
+ else:
100
+ i += 1
101
+ if depth != 0:
102
+ raise ValueError("Unterminated block comment in SQL query.")
103
+ out.append(" ")
104
+ continue
105
+
106
+ # Single-quoted string literal ('...' with '' or \' escapes)
107
+ if ch == "'":
108
+ i += 1
109
+ closed = False
110
+ while i < n:
111
+ if sql[i] == "\\" and i + 1 < n:
112
+ i += 2
113
+ continue
114
+ if sql[i] == "'":
115
+ if i + 1 < n and sql[i + 1] == "'":
116
+ i += 2
117
+ continue
118
+ i += 1
119
+ closed = True
120
+ break
121
+ i += 1
122
+ if not closed:
123
+ raise ValueError("Unterminated string literal in SQL query.")
124
+ out.append(" '' ")
125
+ continue
126
+
127
+ # PostgreSQL dollar-quoted string literal ($tag$...$tag$)
128
+ if ch == "$":
129
+ tag_end = i + 1
130
+ while tag_end < n and (sql[tag_end].isalnum() or sql[tag_end] == "_"):
131
+ tag_end += 1
132
+ if tag_end < n and sql[tag_end] == "$":
133
+ tag = sql[i : tag_end + 1]
134
+ close_pos = sql.find(tag, tag_end + 1)
135
+ if close_pos == -1:
136
+ raise ValueError("Unterminated dollar-quoted string in SQL query.")
137
+ i = close_pos + len(tag)
138
+ out.append(" '' ")
139
+ continue
140
+
141
+ # Double-quoted or backtick-quoted identifier — keep identifier text inspectable
142
+ if ch in {'"', "`"}:
143
+ quote_ch = ch
144
+ i += 1
145
+ buf: list[str] = []
146
+ closed = False
147
+ while i < n:
148
+ if sql[i] == quote_ch:
149
+ if i + 1 < n and sql[i + 1] == quote_ch:
150
+ buf.append(quote_ch)
151
+ i += 2
152
+ continue
153
+ i += 1
154
+ closed = True
155
+ break
156
+ buf.append(sql[i])
157
+ i += 1
158
+ if not closed:
159
+ raise ValueError("Unterminated quoted identifier in SQL query.")
160
+ ident = "".join(buf)
161
+ quoted_idents.append(ident)
162
+ # Emit space-padded identifier so forbidden table/keyword checks inspect it too
163
+ out.append(f" {ident} ")
164
+ continue
165
+
166
+ out.append(ch)
167
+ i += 1
168
+
169
+ return "".join(out), quoted_idents
170
+
171
+
172
+ def _split_top_level_select_items(normalized_sql: str) -> list[str]:
173
+ """Extract top-level SELECT projection expressions from a normalized SQL string."""
174
+ upper = normalized_sql.upper()
175
+ m = re.match(r"^\s*SELECT\s+(?:DISTINCT\s+|ALL\s+)?", upper)
176
+ if not m:
177
+ return []
178
+ pos = m.end()
179
+ depth = 0
180
+ items: list[str] = []
181
+ start = pos
182
+ n = len(normalized_sql)
183
+ i = pos
184
+ while i < n:
185
+ ch = normalized_sql[i]
186
+ if ch == "(":
187
+ depth += 1
188
+ elif ch == ")":
189
+ depth = max(0, depth - 1)
190
+ elif depth == 0:
191
+ if ch == ",":
192
+ items.append(normalized_sql[start:i].strip())
193
+ start = i + 1
194
+ elif upper[i:].startswith("FROM") and (
195
+ (i == 0 or not upper[i - 1].isalnum())
196
+ and (i + 4 >= n or not (upper[i + 4].isalnum() or upper[i + 4] == "_"))
197
+ ):
198
+ items.append(normalized_sql[start:i].strip())
199
+ return items
200
+ i += 1
201
+ tail = normalized_sql[start:].strip()
202
+ if tail:
203
+ items.append(tail)
204
+ return items
205
+
206
+
207
+ def _find_sensitive_indices_from_sql(
208
+ normalized_sql: str,
209
+ col_names: tuple[str, ...],
210
+ extra_sensitive_patterns: Iterable[re.Pattern[str]],
211
+ ) -> set[int]:
212
+ """Identify output column positions whose SELECT expressions reference sensitive columns."""
213
+ patterns = tuple(extra_sensitive_patterns)
214
+ indices: set[int] = set()
215
+ for idx, cname in enumerate(col_names):
216
+ if is_sensitive_field(cname, patterns):
217
+ indices.add(idx)
218
+
219
+ select_items = _split_top_level_select_items(normalized_sql)
220
+ if select_items and len(select_items) == len(col_names):
221
+ for idx, expr in enumerate(select_items):
222
+ for ident in _IDENT_RE.findall(expr):
223
+ if is_sensitive_field(ident, patterns):
224
+ indices.add(idx)
225
+ break
226
+ return indices
227
+
228
+
229
+ def validate_readonly_sql(
230
+ raw_sql: str,
231
+ *,
232
+ extra_sensitive_patterns: Iterable[re.Pattern[str]] = (),
233
+ ) -> str:
234
+ """Strictly validate that raw_sql is a single read-only SELECT/WITH/EXPLAIN statement."""
235
+ sql = raw_sql.strip()
236
+ if not sql:
237
+ raise ValueError("Enter a SQL query to run.")
238
+ if len(sql) > 10_000:
239
+ raise ValueError("Query exceeds 10,000-character limit.")
240
+
241
+ # Strip trailing single semicolon only
242
+ if sql.endswith(";"):
243
+ sql = sql[:-1].rstrip()
244
+
245
+ # Single-pass lexer strips comments & string literals cleanly (blocks '/*' / '--' smuggling)
246
+ normalized, _quoted = _strip_sql_comments_and_literals(sql)
247
+
248
+ # Disallow statement stacking (semicolons anywhere outside string literals)
249
+ if ";" in normalized:
250
+ raise ValueError("Multiple SQL statements are not permitted in the read-only console.")
251
+
252
+ tokens = normalized.strip().split()
253
+ if not tokens:
254
+ raise ValueError("Enter a SQL query to run.")
255
+
256
+ lead = tokens[0].upper().lstrip("(")
257
+ if lead not in _ALLOWED_LEADING:
258
+ raise ValueError(
259
+ f"Only read-only SELECT, WITH, or EXPLAIN queries are permitted (got '{lead}')."
260
+ )
261
+
262
+ match = _FORBIDDEN_KEYWORDS_RE.search(normalized)
263
+ if match is not None:
264
+ raise ValueError(
265
+ f"Blocked mutating or privileged SQL keyword: '{match.group(0).upper()}'."
266
+ )
267
+
268
+ tbl_match = _FORBIDDEN_TABLES_RE.search(normalized)
269
+ if tbl_match is not None:
270
+ raise ValueError(
271
+ f"Access to internal security table '{tbl_match.group(0)}' is blocked."
272
+ )
273
+
274
+ # Block sensitive column references inside CTEs / subqueries so they cannot be aliased away.
275
+ upper_norm = normalized.upper()
276
+ has_cte_or_subquery = lead == "WITH" or len(re.findall(r"\bSELECT\b", upper_norm)) > 1
277
+ if has_cte_or_subquery:
278
+ patterns = tuple(extra_sensitive_patterns)
279
+ for ident in _IDENT_RE.findall(normalized):
280
+ if is_sensitive_field(ident, patterns):
281
+ raise ValueError(
282
+ f"Referencing sensitive column '{ident}' inside a CTE or subquery is blocked."
283
+ )
284
+
285
+ return sql
286
+
287
+
288
+ def execute_readonly_sql(
289
+ engine: Engine,
290
+ raw_sql: str,
291
+ *,
292
+ max_rows: int = 200,
293
+ extra_sensitive_patterns: Iterable[re.Pattern[str]] = (),
294
+ ) -> SQLQueryResult:
295
+ """Execute a validated read-only SQL query inside a read-only rolled-back transaction."""
296
+ patterns = tuple(extra_sensitive_patterns)
297
+ try:
298
+ clean_sql = validate_readonly_sql(raw_sql, extra_sensitive_patterns=patterns)
299
+ normalized_sql, _ = _strip_sql_comments_and_literals(clean_sql)
300
+ except ValueError as exc:
301
+ return SQLQueryResult(
302
+ sql=raw_sql,
303
+ columns=(),
304
+ rows=(),
305
+ row_count=0,
306
+ truncated=False,
307
+ redacted_columns=(),
308
+ duration_ms=0.0,
309
+ error=str(exc),
310
+ )
311
+
312
+ safe_limit = max(1, min(int(max_rows), 1000))
313
+ t0 = time.perf_counter()
314
+ dialect_name = engine.dialect.name
315
+ try:
316
+ with engine.connect() as conn:
317
+ tx = conn.begin()
318
+ sqlite_ro_set = False
319
+ try:
320
+ # Defense-in-depth DB-level read-only enforcement + timeout
321
+ if dialect_name == "sqlite":
322
+ conn.execute(sa.text("PRAGMA query_only = ON"))
323
+ sqlite_ro_set = True
324
+ elif dialect_name == "postgresql":
325
+ conn.execute(sa.text("SET TRANSACTION READ ONLY"))
326
+ conn.execute(sa.text("SET LOCAL statement_timeout = '5000ms'"))
327
+ elif dialect_name in {"mysql", "mariadb"}:
328
+ conn.execute(sa.text("SET TRANSACTION READ ONLY"))
329
+
330
+ result = conn.execute(sa.text(clean_sql))
331
+ col_names = tuple(map(str, result.keys()))
332
+ raw_rows = result.fetchmany(safe_limit + 1)
333
+ finally:
334
+ # Unconditional rollback guarantees zero persisted side-effects even on SQLite/PG.
335
+ tx.rollback()
336
+ if sqlite_ro_set:
337
+ # Restore connection state before returning to SQLAlchemy connection pool!
338
+ with contextlib.suppress(SQLAlchemyError):
339
+ conn.execute(sa.text("PRAGMA query_only = OFF"))
340
+ except SQLAlchemyError as exc:
341
+ elapsed = (time.perf_counter() - t0) * 1000.0
342
+ detail = str(getattr(exc, "orig", exc))
343
+ return SQLQueryResult(
344
+ sql=clean_sql,
345
+ columns=(),
346
+ rows=(),
347
+ row_count=0,
348
+ truncated=False,
349
+ redacted_columns=(),
350
+ duration_ms=elapsed,
351
+ error=f"SQL execution error: {detail}",
352
+ )
353
+
354
+ elapsed = (time.perf_counter() - t0) * 1000.0
355
+ truncated = len(raw_rows) > safe_limit
356
+ kept = raw_rows[:safe_limit]
357
+
358
+ sensitive_indices = _find_sensitive_indices_from_sql(normalized_sql, col_names, patterns)
359
+ redacted_names = [col_names[idx] for idx in sorted(sensitive_indices)]
360
+
361
+ sanitized_rows: list[tuple[Any, ...]] = []
362
+ for row in kept:
363
+ cells = tuple(
364
+ "[REDACTED]" if idx in sensitive_indices else val for idx, val in enumerate(row)
365
+ )
366
+ sanitized_rows.append(cells)
367
+
368
+ return SQLQueryResult(
369
+ sql=clean_sql,
370
+ columns=col_names,
371
+ rows=tuple(sanitized_rows),
372
+ row_count=len(sanitized_rows),
373
+ truncated=truncated,
374
+ redacted_columns=tuple(redacted_names),
375
+ duration_ms=elapsed,
376
+ )
377
+
378
+
379
+ def format_sql_result_csv(
380
+ columns: Sequence[str],
381
+ rows: Sequence[Sequence[Any]],
382
+ *,
383
+ sanitize_csv: bool = True,
384
+ ) -> str:
385
+ """Serialize SQL Console output to formula-safe CSV text."""
386
+ buf = io.StringIO()
387
+ writer = csv.writer(buf)
388
+ writer.writerow([sanitize_csv_cell(col, enabled=sanitize_csv) for col in columns])
389
+ for row in rows:
390
+ writer.writerow([sanitize_csv_cell(v, enabled=sanitize_csv) for v in row])
391
+ return buf.getvalue()
flask_deck/sso.py ADDED
@@ -0,0 +1,293 @@
1
+ from __future__ import annotations
2
+
3
+ import base64
4
+ import hashlib
5
+ import hmac
6
+ import json
7
+ import secrets
8
+ import urllib.error
9
+ import urllib.parse
10
+ import urllib.request
11
+ from collections.abc import Callable, Mapping, Sequence
12
+ from dataclasses import dataclass, field
13
+ from typing import Any
14
+
15
+ from flask import session
16
+
17
+ from flask_deck.auth import DeckUser, RBACAccount, RBACAuthProvider, Role
18
+ from flask_deck.events import _NoRedirectHandler
19
+
20
+ SSO_STATE_KEY = "_deck_sso_state"
21
+ SSO_VERIFIER_KEY = "_deck_sso_verifier"
22
+ SSO_NONCE_KEY = "_deck_sso_nonce"
23
+ SSO_NEXT_KEY = "_deck_sso_next"
24
+ SSO_USER_SESSION_KEY = "_deck_sso_user"
25
+
26
+ HTTPTransport = Callable[
27
+ [str, str, Mapping[str, str], bytes | None, float],
28
+ tuple[int, dict[str, Any]],
29
+ ]
30
+
31
+
32
+ def _default_http_transport(
33
+ method: str,
34
+ url: str,
35
+ headers: Mapping[str, str],
36
+ body: bytes | None,
37
+ timeout: float,
38
+ ) -> tuple[int, dict[str, Any]]:
39
+ parsed = urllib.parse.urlsplit(url)
40
+ if parsed.scheme.lower() != "https":
41
+ raise ValueError("OIDC endpoints must use https://")
42
+ req = urllib.request.Request(url, data=body, headers=dict(headers), method=method)
43
+ opener = urllib.request.build_opener(_NoRedirectHandler())
44
+ try:
45
+ with opener.open(req, timeout=timeout) as resp:
46
+ raw = resp.read(256 * 1024).decode("utf-8")
47
+ parsed_json = json.loads(raw)
48
+ if not isinstance(parsed_json, dict):
49
+ raise PermissionError("OIDC provider returned non-object JSON payload.")
50
+ return int(resp.status), parsed_json
51
+ except urllib.error.HTTPError as exc:
52
+ try:
53
+ err_body = exc.read(16 * 1024).decode("utf-8", errors="ignore")
54
+ err_json = json.loads(err_body)
55
+ payload = err_json if isinstance(err_json, dict) else {"error": err_body}
56
+ except Exception:
57
+ payload = {"error": str(exc)}
58
+ return int(exc.code), payload
59
+ except (urllib.error.URLError, OSError, ValueError) as exc:
60
+ raise PermissionError(f"OIDC provider communication failed: {exc}") from exc
61
+
62
+
63
+ def generate_pkce_pair() -> tuple[str, str]:
64
+ """Generate RFC 7636 PKCE (code_verifier, S256 code_challenge)."""
65
+ verifier = secrets.token_urlsafe(48)
66
+ digest = hashlib.sha256(verifier.encode("ascii")).digest()
67
+ challenge = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
68
+ return verifier, challenge
69
+
70
+
71
+ @dataclass(frozen=True, slots=True)
72
+ class OIDCProviderConfig:
73
+ """Declarative OAuth2 / OIDC identity provider configuration (Google, GitHub, Okta, Keycloak)."""
74
+
75
+ name: str
76
+ label: str
77
+ client_id: str
78
+ client_secret: str
79
+ authorize_url: str
80
+ token_url: str
81
+ userinfo_url: str
82
+ scopes: tuple[str, ...] = ("openid", "email", "profile")
83
+ role_claim: str = "groups"
84
+ role_mapping: Mapping[str, str] = field(default_factory=dict)
85
+ default_role: str = "viewer"
86
+ superuser_groups: frozenset[str] = field(default_factory=frozenset)
87
+ allowed_domains: frozenset[str] = field(default_factory=frozenset)
88
+ require_verified_email: bool = False
89
+ timeout: float = 8.0
90
+
91
+ def __post_init__(self) -> None:
92
+ for attr in ("authorize_url", "token_url", "userinfo_url"):
93
+ val = getattr(self, attr)
94
+ if urllib.parse.urlsplit(val).scheme.lower() != "https":
95
+ raise ValueError(f"OIDCProviderConfig.{attr} must use https://")
96
+
97
+
98
+ class OIDCAuthProvider(RBACAuthProvider):
99
+ """RBAC auth provider adding OAuth2 / OIDC PKCE S256 SSO login alongside optional passwords."""
100
+
101
+ def __init__(
102
+ self,
103
+ *,
104
+ roles: Sequence[Role],
105
+ providers: Sequence[OIDCProviderConfig],
106
+ accounts: Sequence[RBACAccount] = (),
107
+ http_transport: HTTPTransport | None = None,
108
+ ) -> None:
109
+ super().__init__(roles=roles, accounts=accounts)
110
+ self._providers: dict[str, OIDCProviderConfig] = {p.name: p for p in providers}
111
+ self._transport: HTTPTransport = http_transport or _default_http_transport
112
+ self.supports_login_form = True
113
+
114
+ def get_sso_providers(self) -> Sequence[OIDCProviderConfig]:
115
+ return tuple(self._providers.values())
116
+
117
+ def get_sso_provider(self, name: str) -> OIDCProviderConfig | None:
118
+ return self._providers.get(name)
119
+
120
+ def build_authorize_redirect(
121
+ self,
122
+ provider_name: str,
123
+ *,
124
+ redirect_uri: str,
125
+ next_url: str = "",
126
+ ) -> str:
127
+ """Create PKCE S256 challenge + CSRF state in session and return provider authorize URL."""
128
+ cfg = self._providers.get(provider_name)
129
+ if cfg is None:
130
+ raise ValueError(f"Unknown OIDC provider: {provider_name!r}")
131
+
132
+ state = secrets.token_urlsafe(32)
133
+ nonce = secrets.token_urlsafe(24)
134
+ verifier, challenge = generate_pkce_pair()
135
+
136
+ session[SSO_STATE_KEY] = f"{provider_name}:{state}"
137
+ session[SSO_VERIFIER_KEY] = verifier
138
+ session[SSO_NONCE_KEY] = nonce
139
+ session[SSO_NEXT_KEY] = next_url
140
+
141
+ params = {
142
+ "response_type": "code",
143
+ "client_id": cfg.client_id,
144
+ "redirect_uri": redirect_uri,
145
+ "scope": " ".join(cfg.scopes),
146
+ "state": state,
147
+ "nonce": nonce,
148
+ "code_challenge": challenge,
149
+ "code_challenge_method": "S256",
150
+ }
151
+ sep = "&" if "?" in cfg.authorize_url else "?"
152
+ return f"{cfg.authorize_url}{sep}{urllib.parse.urlencode(params)}"
153
+
154
+ def complete_callback(
155
+ self,
156
+ provider_name: str,
157
+ *,
158
+ code: str,
159
+ state: str,
160
+ redirect_uri: str,
161
+ ) -> tuple[DeckUser, str]:
162
+ """Validate state CSRF, exchange PKCE code for token, fetch userinfo, and map RBAC roles."""
163
+ cfg = self._providers.get(provider_name)
164
+ if cfg is None:
165
+ raise ValueError(f"Unknown OIDC provider: {provider_name!r}")
166
+
167
+ expected_state_raw = str(session.pop(SSO_STATE_KEY, ""))
168
+ verifier = str(session.pop(SSO_VERIFIER_KEY, ""))
169
+ session.pop(SSO_NONCE_KEY, None)
170
+ next_url = str(session.pop(SSO_NEXT_KEY, ""))
171
+
172
+ expected_state = f"{provider_name}:{state}"
173
+ if not state or not expected_state_raw or not hmac.compare_digest(expected_state_raw, expected_state):
174
+ raise PermissionError("Invalid or expired SSO state parameter.")
175
+ if not code or not verifier:
176
+ raise PermissionError("Missing SSO authorization code or PKCE verifier.")
177
+
178
+ token_body = urllib.parse.urlencode(
179
+ {
180
+ "grant_type": "authorization_code",
181
+ "code": code,
182
+ "redirect_uri": redirect_uri,
183
+ "client_id": cfg.client_id,
184
+ "client_secret": cfg.client_secret,
185
+ "code_verifier": verifier,
186
+ }
187
+ ).encode("utf-8")
188
+ status, token_data = self._transport(
189
+ "POST",
190
+ cfg.token_url,
191
+ {
192
+ "Content-Type": "application/x-www-form-urlencoded",
193
+ "Accept": "application/json",
194
+ },
195
+ token_body,
196
+ cfg.timeout,
197
+ )
198
+ if status >= 400 or not token_data.get("access_token"):
199
+ raise PermissionError("SSO token exchange failed.")
200
+
201
+ access_token = str(token_data["access_token"])
202
+ u_status, profile = self._transport(
203
+ "GET",
204
+ cfg.userinfo_url,
205
+ {
206
+ "Authorization": f"Bearer {access_token}",
207
+ "Accept": "application/json",
208
+ },
209
+ None,
210
+ cfg.timeout,
211
+ )
212
+ if u_status >= 400:
213
+ raise PermissionError("SSO userinfo lookup failed.")
214
+
215
+ email = str(profile.get("email") or "").strip().lower()
216
+ email_verified = profile.get("email_verified")
217
+ sub = str(profile.get("sub") or profile.get("id") or "")
218
+ if not sub:
219
+ if email and email_verified is not False:
220
+ sub = email
221
+ else:
222
+ raise PermissionError("SSO profile did not return a user identifier.")
223
+
224
+ if cfg.allowed_domains:
225
+ if email_verified is False or (
226
+ cfg.require_verified_email and email_verified is not True
227
+ ):
228
+ raise PermissionError("SSO account email address is not verified.")
229
+ domain = email.split("@", 1)[1] if "@" in email else ""
230
+ if domain not in {d.lower() for d in cfg.allowed_domains}:
231
+ raise PermissionError(f"Email domain '{domain or 'unknown'}' is not permitted.")
232
+
233
+ raw_groups = profile.get(cfg.role_claim, ())
234
+ if isinstance(raw_groups, str):
235
+ groups = [raw_groups]
236
+ elif isinstance(raw_groups, Sequence):
237
+ groups = [str(g) for g in raw_groups]
238
+ else:
239
+ groups = []
240
+
241
+ mapped_roles = [cfg.role_mapping[g] for g in groups if g in cfg.role_mapping]
242
+ roles = tuple(dict.fromkeys(mapped_roles)) or (cfg.default_role,)
243
+ is_super = any(g in cfg.superuser_groups for g in groups)
244
+
245
+ user = DeckUser(
246
+ id=f"sso:{cfg.name}:{sub}",
247
+ username=email or sub,
248
+ display_name=str(profile.get("name") or email or sub),
249
+ email=email,
250
+ roles=roles,
251
+ is_superuser=is_super,
252
+ metadata={"sso_provider": cfg.name},
253
+ )
254
+ return user, next_url
255
+
256
+ def login_user(self, user: DeckUser) -> None:
257
+ super().login_user(user)
258
+ if user.id.startswith("sso:"):
259
+ session[SSO_USER_SESSION_KEY] = {
260
+ "id": user.id,
261
+ "username": user.username,
262
+ "display_name": user.display_name,
263
+ "email": user.email,
264
+ "roles": list(user.roles),
265
+ "is_superuser": user.is_superuser,
266
+ }
267
+
268
+ def get_current_user(
269
+ self,
270
+ *,
271
+ idle_timeout: int = 1800,
272
+ absolute_timeout: int = 43200,
273
+ ) -> DeckUser | None:
274
+ user_id = self._validate_session_timestamps(
275
+ idle_timeout=idle_timeout,
276
+ absolute_timeout=absolute_timeout,
277
+ )
278
+ if user_id is None:
279
+ return None
280
+ if user_id.startswith("sso:"):
281
+ raw = session.get(SSO_USER_SESSION_KEY)
282
+ if isinstance(raw, Mapping) and str(raw.get("id")) == user_id:
283
+ return DeckUser(
284
+ id=user_id,
285
+ username=str(raw.get("username", user_id)),
286
+ display_name=str(raw.get("display_name", "")),
287
+ email=str(raw.get("email", "")),
288
+ roles=tuple(str(r) for r in raw.get("roles", ())),
289
+ is_superuser=bool(raw.get("is_superuser", False)),
290
+ )
291
+ return None
292
+ acc = self._accounts_by_id.get(user_id)
293
+ return acc.user if acc is not None else None