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.
- flask_deck/__init__.py +184 -0
- flask_deck/adapters/__init__.py +23 -0
- flask_deck/adapters/sqlalchemy.py +272 -0
- flask_deck/audit.py +363 -0
- flask_deck/auth.py +462 -0
- flask_deck/branding.py +217 -0
- flask_deck/charts.py +514 -0
- flask_deck/cli.py +135 -0
- flask_deck/config.py +81 -0
- flask_deck/dashboard.py +416 -0
- flask_deck/deck.py +4153 -0
- flask_deck/demo.py +1066 -0
- flask_deck/events.py +309 -0
- flask_deck/exceptions.py +34 -0
- flask_deck/exporter.py +240 -0
- flask_deck/formatters.py +386 -0
- flask_deck/i18n.py +399 -0
- flask_deck/icons.py +92 -0
- flask_deck/importer.py +612 -0
- flask_deck/introspection.py +376 -0
- flask_deck/jobs.py +382 -0
- flask_deck/mfa.py +670 -0
- flask_deck/model_view.py +1097 -0
- flask_deck/py.typed +0 -0
- flask_deck/query.py +1220 -0
- flask_deck/schema_graph.py +137 -0
- flask_deck/security.py +373 -0
- flask_deck/sql_console.py +391 -0
- flask_deck/sso.py +293 -0
- flask_deck/static/css/deck.css +1333 -0
- flask_deck/static/js/deck.js +1433 -0
- flask_deck/storage.py +669 -0
- flask_deck/templates/flask_deck/audit_list.html +117 -0
- flask_deck/templates/flask_deck/base.html +454 -0
- flask_deck/templates/flask_deck/custom_page.html +12 -0
- flask_deck/templates/flask_deck/dashboard.html +32 -0
- flask_deck/templates/flask_deck/diagnostics.html +80 -0
- flask_deck/templates/flask_deck/error.html +15 -0
- flask_deck/templates/flask_deck/import_wizard.html +143 -0
- flask_deck/templates/flask_deck/jobs_list.html +95 -0
- flask_deck/templates/flask_deck/login.html +93 -0
- flask_deck/templates/flask_deck/login_mfa.html +59 -0
- flask_deck/templates/flask_deck/mfa_setup.html +121 -0
- flask_deck/templates/flask_deck/model_detail.html +124 -0
- flask_deck/templates/flask_deck/model_form.html +389 -0
- flask_deck/templates/flask_deck/model_list.html +489 -0
- flask_deck/templates/flask_deck/partials/drawer_detail.html +93 -0
- flask_deck/templates/flask_deck/partials/widget_grid.html +207 -0
- flask_deck/templates/flask_deck/rbac_matrix.html +59 -0
- flask_deck/templates/flask_deck/record_history.html +102 -0
- flask_deck/templates/flask_deck/schema_inspector.html +83 -0
- flask_deck/templates/flask_deck/sql_console.html +87 -0
- flask_deck-0.3.0.dist-info/METADATA +382 -0
- flask_deck-0.3.0.dist-info/RECORD +57 -0
- flask_deck-0.3.0.dist-info/WHEEL +4 -0
- flask_deck-0.3.0.dist-info/entry_points.txt +5 -0
- flask_deck-0.3.0.dist-info/licenses/LICENSE +21 -0
flask_deck/storage.py
ADDED
|
@@ -0,0 +1,669 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import hashlib
|
|
4
|
+
import io
|
|
5
|
+
import os
|
|
6
|
+
import re
|
|
7
|
+
import struct
|
|
8
|
+
import tempfile
|
|
9
|
+
import threading
|
|
10
|
+
import uuid
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from datetime import datetime, timezone
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
from typing import Any, BinaryIO, Literal, Protocol, runtime_checkable
|
|
15
|
+
|
|
16
|
+
DEFAULT_IMAGE_MIMES: frozenset[str] = frozenset(
|
|
17
|
+
{"image/png", "image/jpeg", "image/webp", "image/gif"}
|
|
18
|
+
)
|
|
19
|
+
DEFAULT_FILE_MIMES: frozenset[str] = frozenset(
|
|
20
|
+
{
|
|
21
|
+
"image/png",
|
|
22
|
+
"image/jpeg",
|
|
23
|
+
"image/webp",
|
|
24
|
+
"image/gif",
|
|
25
|
+
"application/pdf",
|
|
26
|
+
"text/plain",
|
|
27
|
+
"text/csv",
|
|
28
|
+
"application/json",
|
|
29
|
+
"application/zip",
|
|
30
|
+
"application/gzip",
|
|
31
|
+
}
|
|
32
|
+
)
|
|
33
|
+
RASTER_INLINE_MIMES: frozenset[str] = frozenset(
|
|
34
|
+
{"image/png", "image/jpeg", "image/webp", "image/gif"}
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
_MIME_TO_EXT: dict[str, str] = {
|
|
38
|
+
"image/png": "png",
|
|
39
|
+
"image/jpeg": "jpg",
|
|
40
|
+
"image/webp": "webp",
|
|
41
|
+
"image/gif": "gif",
|
|
42
|
+
"image/svg+xml": "svg",
|
|
43
|
+
"application/pdf": "pdf",
|
|
44
|
+
"text/plain": "txt",
|
|
45
|
+
"text/csv": "csv",
|
|
46
|
+
"application/json": "json",
|
|
47
|
+
"application/zip": "zip",
|
|
48
|
+
"application/gzip": "gz",
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
_PREFIX_SAFE_RE = re.compile(r"[^a-zA-Z0-9/_-]+")
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass(frozen=True, slots=True)
|
|
55
|
+
class StoredFile:
|
|
56
|
+
"""Immutable metadata returned after storing an uploaded artifact."""
|
|
57
|
+
|
|
58
|
+
key: str
|
|
59
|
+
filename: str
|
|
60
|
+
content_type: str
|
|
61
|
+
size_bytes: int
|
|
62
|
+
sha256: str
|
|
63
|
+
width: int | None = None
|
|
64
|
+
height: int | None = None
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@runtime_checkable
|
|
68
|
+
class StorageBackend(Protocol):
|
|
69
|
+
"""Storage-agnostic contract implemented by Local, S3/R2, and Memory backends."""
|
|
70
|
+
|
|
71
|
+
def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
|
|
72
|
+
"""Persist validated bytes at opaque key."""
|
|
73
|
+
|
|
74
|
+
def open(self, key: str) -> tuple[BinaryIO, str | None]:
|
|
75
|
+
"""Return (readable binary stream, optional content_type) for key."""
|
|
76
|
+
|
|
77
|
+
def delete(self, key: str) -> None:
|
|
78
|
+
"""Delete object if present (idempotent)."""
|
|
79
|
+
|
|
80
|
+
def exists(self, key: str) -> bool:
|
|
81
|
+
"""Return True if key exists in storage."""
|
|
82
|
+
|
|
83
|
+
def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
|
|
84
|
+
"""Optionally return a short-lived signed URL (None for private proxy-only backends)."""
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@dataclass(frozen=True, slots=True)
|
|
88
|
+
class FileFieldConfig:
|
|
89
|
+
"""Declarative configuration for one file or image upload column on a ModelView."""
|
|
90
|
+
|
|
91
|
+
storage: StorageBackend
|
|
92
|
+
kind: Literal["file", "image"] = "file"
|
|
93
|
+
allowed_mimes: frozenset[str] = field(default_factory=frozenset)
|
|
94
|
+
max_bytes: int | None = None
|
|
95
|
+
max_image_pixels: int = 25_000_000 # 25 MP decompression-bomb cap
|
|
96
|
+
prefix: str = "uploads"
|
|
97
|
+
delete_orphan: bool = False
|
|
98
|
+
allow_svg: bool = False
|
|
99
|
+
|
|
100
|
+
def resolved_allowed_mimes(self) -> frozenset[str]:
|
|
101
|
+
base = self.allowed_mimes or (
|
|
102
|
+
DEFAULT_IMAGE_MIMES if self.kind == "image" else DEFAULT_FILE_MIMES
|
|
103
|
+
)
|
|
104
|
+
if not self.allow_svg:
|
|
105
|
+
return base - {"image/svg+xml"}
|
|
106
|
+
return base | {"image/svg+xml"}
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def sanitize_filename(filename: str) -> str:
|
|
110
|
+
"""Extract a clean basename without path separators or control characters."""
|
|
111
|
+
base = filename.replace("\\", "/").rsplit("/", 1)[-1]
|
|
112
|
+
cleaned = "".join(ch for ch in base if 32 <= ord(ch) < 127 and ch not in {'"', "'", "<", ">"})
|
|
113
|
+
cleaned = cleaned.strip().lstrip(".")
|
|
114
|
+
return cleaned[:120] or "file"
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def build_storage_key(prefix: str, mime: str) -> str:
|
|
118
|
+
"""Build a collision-free opaque storage key never trusting user filenames."""
|
|
119
|
+
clean_prefix = _PREFIX_SAFE_RE.sub("", prefix.strip("/")) or "uploads"
|
|
120
|
+
now = datetime.now(timezone.utc)
|
|
121
|
+
ext = _MIME_TO_EXT.get(mime, "bin")
|
|
122
|
+
return f"{clean_prefix}/{now.year:04d}/{now.month:02d}/{uuid.uuid4().hex}.{ext}"
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
_XML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
|
|
126
|
+
_HTML_ACTIVE_TAG_RE = re.compile(
|
|
127
|
+
r"<\s*(?:!doctype\s+html|html|script|iframe|object|embed|body|head|meta|link|style|img|form)\b",
|
|
128
|
+
re.IGNORECASE,
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _decode_utf8_prefix(data: bytes, limit: int = 4096) -> str | None:
|
|
133
|
+
"""Decode up to ``limit`` bytes of UTF-8 without failing on a split trailing multibyte char."""
|
|
134
|
+
chunk = data[:limit]
|
|
135
|
+
if len(data) > limit:
|
|
136
|
+
# Trim up to 3 trailing UTF-8 continuation/incomplete lead bytes at the slice boundary
|
|
137
|
+
for trim in range(4):
|
|
138
|
+
sub = chunk[: len(chunk) - trim] if trim else chunk
|
|
139
|
+
try:
|
|
140
|
+
return sub.decode("utf-8")
|
|
141
|
+
except UnicodeDecodeError:
|
|
142
|
+
continue
|
|
143
|
+
return None
|
|
144
|
+
try:
|
|
145
|
+
return chunk.decode("utf-8")
|
|
146
|
+
except UnicodeDecodeError:
|
|
147
|
+
return None
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def detect_mime_from_bytes(data: bytes, filename: str = "") -> str | None:
|
|
151
|
+
"""Pure-Python magic-byte MIME sniffer (zero libmagic dependency)."""
|
|
152
|
+
if not data:
|
|
153
|
+
return None
|
|
154
|
+
head = data[:64]
|
|
155
|
+
|
|
156
|
+
if head.startswith(b"\x89PNG\r\n\x1a\n"):
|
|
157
|
+
return "image/png"
|
|
158
|
+
if head.startswith(b"\xff\xd8\xff"):
|
|
159
|
+
return "image/jpeg"
|
|
160
|
+
if head.startswith((b"GIF87a", b"GIF89a")):
|
|
161
|
+
return "image/gif"
|
|
162
|
+
if len(head) >= 12 and head[:4] == b"RIFF" and head[8:12] == b"WEBP":
|
|
163
|
+
return "image/webp"
|
|
164
|
+
if head.startswith(b"%PDF-"):
|
|
165
|
+
return "application/pdf"
|
|
166
|
+
if head.startswith((b"PK\x03\x04", b"PK\x05\x06")):
|
|
167
|
+
return "application/zip"
|
|
168
|
+
if head.startswith(b"\x1f\x8b"):
|
|
169
|
+
return "application/gzip"
|
|
170
|
+
|
|
171
|
+
# Reject binary blobs with NUL bytes before checking text/SVG/JSON/CSV
|
|
172
|
+
if b"\x00" in data[:4096]:
|
|
173
|
+
return None
|
|
174
|
+
|
|
175
|
+
sample = _decode_utf8_prefix(data, 4096)
|
|
176
|
+
if sample is None:
|
|
177
|
+
return None
|
|
178
|
+
|
|
179
|
+
# Strip UTF-8 BOM, leading whitespace, and XML comments before checking SVG / HTML payloads
|
|
180
|
+
stripped = sample.lstrip("\ufeff \t\r\n")
|
|
181
|
+
no_comments = _XML_COMMENT_RE.sub("", stripped).lstrip()
|
|
182
|
+
lower = no_comments.lower()
|
|
183
|
+
if (
|
|
184
|
+
lower.startswith("<svg")
|
|
185
|
+
or lower.startswith("<!doctype svg")
|
|
186
|
+
or (lower.startswith("<?xml") and "<svg" in lower[:2048])
|
|
187
|
+
or "<svg" in lower[:512]
|
|
188
|
+
):
|
|
189
|
+
return "image/svg+xml"
|
|
190
|
+
if _HTML_ACTIVE_TAG_RE.search(no_comments[:1024]):
|
|
191
|
+
# Never classify HTML/script payloads as safe text or image uploads.
|
|
192
|
+
return None
|
|
193
|
+
|
|
194
|
+
ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
|
|
195
|
+
if stripped.startswith(("{", "[")) and ext == "json":
|
|
196
|
+
return "application/json"
|
|
197
|
+
if ext == "csv":
|
|
198
|
+
return "text/csv"
|
|
199
|
+
if ext == "txt":
|
|
200
|
+
return "text/plain"
|
|
201
|
+
if stripped.startswith(("{", "[")):
|
|
202
|
+
return "application/json"
|
|
203
|
+
return "text/plain"
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _parse_gif_max_dimensions(data: bytes) -> tuple[int, int] | None:
|
|
207
|
+
"""Return max (width, height) across the GIF logical screen and all 0x2C image descriptors."""
|
|
208
|
+
if len(data) < 13:
|
|
209
|
+
return None
|
|
210
|
+
max_w, max_h = struct.unpack("<HH", data[6:10])
|
|
211
|
+
packed = data[10]
|
|
212
|
+
idx = 13
|
|
213
|
+
if packed & 0x80:
|
|
214
|
+
gct_size = 3 * (1 << ((packed & 0x07) + 1))
|
|
215
|
+
idx += gct_size
|
|
216
|
+
n = len(data)
|
|
217
|
+
while idx < n:
|
|
218
|
+
block = data[idx]
|
|
219
|
+
idx += 1
|
|
220
|
+
if block == 0x3B: # Trailer
|
|
221
|
+
break
|
|
222
|
+
if block == 0x2C: # Image Descriptor
|
|
223
|
+
if idx + 9 > n:
|
|
224
|
+
break
|
|
225
|
+
_left, _top, fw, fh, ipacked = struct.unpack("<HHHHB", data[idx : idx + 9])
|
|
226
|
+
max_w = max(max_w, fw)
|
|
227
|
+
max_h = max(max_h, fh)
|
|
228
|
+
idx += 9
|
|
229
|
+
if ipacked & 0x80:
|
|
230
|
+
idx += 3 * (1 << ((ipacked & 0x07) + 1))
|
|
231
|
+
if idx >= n:
|
|
232
|
+
break
|
|
233
|
+
idx += 1 # LZW minimum code size
|
|
234
|
+
while idx < n:
|
|
235
|
+
sub_len = data[idx]
|
|
236
|
+
idx += 1
|
|
237
|
+
if sub_len == 0:
|
|
238
|
+
break
|
|
239
|
+
idx += sub_len
|
|
240
|
+
elif block == 0x21: # Extension
|
|
241
|
+
if idx >= n:
|
|
242
|
+
break
|
|
243
|
+
idx += 1 # Extension label
|
|
244
|
+
while idx < n:
|
|
245
|
+
sub_len = data[idx]
|
|
246
|
+
idx += 1
|
|
247
|
+
if sub_len == 0:
|
|
248
|
+
break
|
|
249
|
+
idx += sub_len
|
|
250
|
+
else:
|
|
251
|
+
break
|
|
252
|
+
return int(max_w), int(max_h)
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def parse_image_dimensions(data: bytes, mime: str) -> tuple[int, int] | None:
|
|
256
|
+
"""Parse image (width, height) directly from binary headers to stop decompression bombs."""
|
|
257
|
+
try:
|
|
258
|
+
if mime == "image/png" and len(data) >= 24 and data[12:16] == b"IHDR":
|
|
259
|
+
w, h = struct.unpack(">II", data[16:24])
|
|
260
|
+
return int(w), int(h)
|
|
261
|
+
if mime == "image/gif" and len(data) >= 10:
|
|
262
|
+
return _parse_gif_max_dimensions(data)
|
|
263
|
+
if mime == "image/webp" and len(data) >= 25:
|
|
264
|
+
chunk = data[12:16]
|
|
265
|
+
if chunk == b"VP8L" and data[20] == 0x2F:
|
|
266
|
+
bits = struct.unpack("<I", data[21:25])[0]
|
|
267
|
+
return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
|
|
268
|
+
if chunk == b"VP8X" and len(data) >= 30:
|
|
269
|
+
w = 1 + int.from_bytes(data[24:27], "little")
|
|
270
|
+
h = 1 + int.from_bytes(data[27:30], "little")
|
|
271
|
+
return w, h
|
|
272
|
+
if chunk == b"VP8 " and len(data) >= 30 and data[23:26] == b"\x9d\x01\x2a":
|
|
273
|
+
w = struct.unpack("<H", data[26:28])[0] & 0x3FFF
|
|
274
|
+
h = struct.unpack("<H", data[28:30])[0] & 0x3FFF
|
|
275
|
+
return int(w), int(h)
|
|
276
|
+
if mime == "image/jpeg" and len(data) >= 4:
|
|
277
|
+
idx = 2
|
|
278
|
+
length = len(data)
|
|
279
|
+
while idx + 4 < length:
|
|
280
|
+
if data[idx] != 0xFF:
|
|
281
|
+
break
|
|
282
|
+
while idx < length and data[idx] == 0xFF:
|
|
283
|
+
idx += 1
|
|
284
|
+
if idx >= length:
|
|
285
|
+
break
|
|
286
|
+
marker = data[idx]
|
|
287
|
+
idx += 1
|
|
288
|
+
if marker in {0xD8, 0xD9, 0x01} or (0xD0 <= marker <= 0xD7):
|
|
289
|
+
continue
|
|
290
|
+
if idx + 2 > length:
|
|
291
|
+
break
|
|
292
|
+
seg_len = struct.unpack(">H", data[idx : idx + 2])[0]
|
|
293
|
+
if seg_len < 2 or idx + seg_len > length:
|
|
294
|
+
break
|
|
295
|
+
if marker in {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB}:
|
|
296
|
+
if idx + 7 <= length:
|
|
297
|
+
h, w = struct.unpack(">HH", data[idx + 3 : idx + 7])
|
|
298
|
+
return int(w), int(h)
|
|
299
|
+
break
|
|
300
|
+
idx += seg_len
|
|
301
|
+
except (struct.error, ValueError, IndexError):
|
|
302
|
+
return None
|
|
303
|
+
return None
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def validate_and_read_upload(
|
|
307
|
+
stream: BinaryIO,
|
|
308
|
+
*,
|
|
309
|
+
filename: str,
|
|
310
|
+
config: FileFieldConfig,
|
|
311
|
+
default_max_bytes: int,
|
|
312
|
+
) -> tuple[bytes, str, int | None, int | None]:
|
|
313
|
+
"""Read upload with strict byte ceiling, magic-byte MIME sniff, and pixel bomb check."""
|
|
314
|
+
limit = config.max_bytes if config.max_bytes is not None else default_max_bytes
|
|
315
|
+
chunks: list[bytes] = []
|
|
316
|
+
total = 0
|
|
317
|
+
while True:
|
|
318
|
+
chunk = stream.read(65536)
|
|
319
|
+
if not chunk:
|
|
320
|
+
break
|
|
321
|
+
total += len(chunk)
|
|
322
|
+
if total > limit:
|
|
323
|
+
mb = limit / (1024 * 1024)
|
|
324
|
+
raise ValueError(f"File exceeds maximum allowed size ({mb:.1f} MiB).")
|
|
325
|
+
chunks.append(chunk)
|
|
326
|
+
|
|
327
|
+
data = b"".join(chunks)
|
|
328
|
+
if not data:
|
|
329
|
+
raise ValueError("Uploaded file is empty.")
|
|
330
|
+
|
|
331
|
+
detected = detect_mime_from_bytes(data, filename)
|
|
332
|
+
allowed = config.resolved_allowed_mimes()
|
|
333
|
+
if detected is None or detected not in allowed:
|
|
334
|
+
if detected == "image/svg+xml" and not config.allow_svg:
|
|
335
|
+
raise ValueError("SVG uploads are disabled by security policy.")
|
|
336
|
+
raise ValueError(
|
|
337
|
+
f"Unsupported or disallowed file content ({detected or 'unknown'})."
|
|
338
|
+
)
|
|
339
|
+
|
|
340
|
+
width: int | None = None
|
|
341
|
+
height: int | None = None
|
|
342
|
+
if detected in RASTER_INLINE_MIMES:
|
|
343
|
+
dims = parse_image_dimensions(data, detected)
|
|
344
|
+
if dims is None:
|
|
345
|
+
raise ValueError("Malformed or unreadable image header.")
|
|
346
|
+
width, height = dims
|
|
347
|
+
if width <= 0 or height <= 0 or (width * height) > config.max_image_pixels:
|
|
348
|
+
raise ValueError(
|
|
349
|
+
f"Image dimensions ({width}x{height}) exceed safety limit "
|
|
350
|
+
f"({config.max_image_pixels:,} pixels)."
|
|
351
|
+
)
|
|
352
|
+
|
|
353
|
+
return data, detected, width, height
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
def store_validated_upload(
|
|
357
|
+
stream: BinaryIO,
|
|
358
|
+
*,
|
|
359
|
+
filename: str,
|
|
360
|
+
config: FileFieldConfig,
|
|
361
|
+
default_max_bytes: int,
|
|
362
|
+
) -> StoredFile:
|
|
363
|
+
"""Validate an uploaded file stream and persist it cleanly to config.storage."""
|
|
364
|
+
data, mime, width, height = validate_and_read_upload(
|
|
365
|
+
stream,
|
|
366
|
+
filename=filename,
|
|
367
|
+
config=config,
|
|
368
|
+
default_max_bytes=default_max_bytes,
|
|
369
|
+
)
|
|
370
|
+
key = build_storage_key(config.prefix, mime)
|
|
371
|
+
stored = config.storage.save(data, key=key, content_type=mime)
|
|
372
|
+
return StoredFile(
|
|
373
|
+
key=stored.key,
|
|
374
|
+
filename=sanitize_filename(filename),
|
|
375
|
+
content_type=mime,
|
|
376
|
+
size_bytes=len(data),
|
|
377
|
+
sha256=stored.sha256,
|
|
378
|
+
width=width,
|
|
379
|
+
height=height,
|
|
380
|
+
)
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
def _validate_opaque_key(key: str) -> str:
|
|
384
|
+
clean = key.strip().lstrip("/")
|
|
385
|
+
if not clean or "\\" in clean or "\x00" in clean:
|
|
386
|
+
raise ValueError("Invalid storage key")
|
|
387
|
+
parts = clean.split("/")
|
|
388
|
+
if any(p in {"", ".", ".."} for p in parts):
|
|
389
|
+
raise ValueError("Invalid storage key")
|
|
390
|
+
return clean
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
class LocalFileStorage:
|
|
394
|
+
"""Path-traversal-proof local filesystem storage backend with atomic writes."""
|
|
395
|
+
|
|
396
|
+
__slots__ = ("root_dir",)
|
|
397
|
+
|
|
398
|
+
def __init__(self, root_dir: str | Path) -> None:
|
|
399
|
+
self.root_dir = Path(root_dir).resolve()
|
|
400
|
+
self.root_dir.mkdir(parents=True, exist_ok=True)
|
|
401
|
+
|
|
402
|
+
def _resolve_path(self, key: str) -> Path:
|
|
403
|
+
clean = _validate_opaque_key(key)
|
|
404
|
+
candidate = (self.root_dir / clean).resolve()
|
|
405
|
+
if candidate == self.root_dir or not candidate.is_relative_to(self.root_dir):
|
|
406
|
+
raise ValueError("Storage key escapes root directory")
|
|
407
|
+
return candidate
|
|
408
|
+
|
|
409
|
+
def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
|
|
410
|
+
target = self._resolve_path(key)
|
|
411
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
412
|
+
digest = hashlib.sha256(data).hexdigest()
|
|
413
|
+
fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=".dk_tmp_")
|
|
414
|
+
try:
|
|
415
|
+
with os.fdopen(fd, "wb") as fh:
|
|
416
|
+
fh.write(data)
|
|
417
|
+
os.replace(tmp_name, target)
|
|
418
|
+
except Exception:
|
|
419
|
+
if os.path.exists(tmp_name):
|
|
420
|
+
os.unlink(tmp_name)
|
|
421
|
+
raise
|
|
422
|
+
return StoredFile(
|
|
423
|
+
key=_validate_opaque_key(key),
|
|
424
|
+
filename=target.name,
|
|
425
|
+
content_type=content_type,
|
|
426
|
+
size_bytes=len(data),
|
|
427
|
+
sha256=digest,
|
|
428
|
+
)
|
|
429
|
+
|
|
430
|
+
def open(self, key: str) -> tuple[BinaryIO, str | None]:
|
|
431
|
+
target = self._resolve_path(key)
|
|
432
|
+
if not target.is_file():
|
|
433
|
+
raise FileNotFoundError(key)
|
|
434
|
+
fh: BinaryIO = target.open("rb")
|
|
435
|
+
head = fh.read(4096)
|
|
436
|
+
fh.seek(0)
|
|
437
|
+
return fh, detect_mime_from_bytes(head, target.name)
|
|
438
|
+
|
|
439
|
+
def delete(self, key: str) -> None:
|
|
440
|
+
try:
|
|
441
|
+
target = self._resolve_path(key)
|
|
442
|
+
except ValueError:
|
|
443
|
+
return
|
|
444
|
+
if target.is_file():
|
|
445
|
+
target.unlink(missing_ok=True)
|
|
446
|
+
|
|
447
|
+
def exists(self, key: str) -> bool:
|
|
448
|
+
try:
|
|
449
|
+
return self._resolve_path(key).is_file()
|
|
450
|
+
except ValueError:
|
|
451
|
+
return False
|
|
452
|
+
|
|
453
|
+
def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
|
|
454
|
+
_ = (key, expires_in)
|
|
455
|
+
return None
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
class MemoryFileStorage:
|
|
459
|
+
"""Thread-safe in-memory storage backend ideal for demos and test suites."""
|
|
460
|
+
|
|
461
|
+
__slots__ = ("_entries", "_lock")
|
|
462
|
+
|
|
463
|
+
def __init__(self) -> None:
|
|
464
|
+
self._entries: dict[str, tuple[bytes, str]] = {}
|
|
465
|
+
self._lock = threading.Lock()
|
|
466
|
+
|
|
467
|
+
def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
|
|
468
|
+
clean = _validate_opaque_key(key)
|
|
469
|
+
digest = hashlib.sha256(data).hexdigest()
|
|
470
|
+
with self._lock:
|
|
471
|
+
self._entries[clean] = (bytes(data), content_type)
|
|
472
|
+
return StoredFile(
|
|
473
|
+
key=clean,
|
|
474
|
+
filename=clean.rsplit("/", 1)[-1],
|
|
475
|
+
content_type=content_type,
|
|
476
|
+
size_bytes=len(data),
|
|
477
|
+
sha256=digest,
|
|
478
|
+
)
|
|
479
|
+
|
|
480
|
+
def open(self, key: str) -> tuple[BinaryIO, str | None]:
|
|
481
|
+
clean = _validate_opaque_key(key)
|
|
482
|
+
with self._lock:
|
|
483
|
+
entry = self._entries.get(clean)
|
|
484
|
+
if entry is None:
|
|
485
|
+
raise FileNotFoundError(key)
|
|
486
|
+
payload, ctype = entry
|
|
487
|
+
return io.BytesIO(payload), ctype
|
|
488
|
+
|
|
489
|
+
def delete(self, key: str) -> None:
|
|
490
|
+
try:
|
|
491
|
+
clean = _validate_opaque_key(key)
|
|
492
|
+
except ValueError:
|
|
493
|
+
return
|
|
494
|
+
with self._lock:
|
|
495
|
+
self._entries.pop(clean, None)
|
|
496
|
+
|
|
497
|
+
def exists(self, key: str) -> bool:
|
|
498
|
+
try:
|
|
499
|
+
clean = _validate_opaque_key(key)
|
|
500
|
+
except ValueError:
|
|
501
|
+
return False
|
|
502
|
+
with self._lock:
|
|
503
|
+
return clean in self._entries
|
|
504
|
+
|
|
505
|
+
def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
|
|
506
|
+
_ = (key, expires_in)
|
|
507
|
+
return None
|
|
508
|
+
|
|
509
|
+
|
|
510
|
+
class S3StorageBackend:
|
|
511
|
+
"""AWS S3 / Cloudflare R2 / MinIO storage backend (lazy optional boto3 or injected client)."""
|
|
512
|
+
|
|
513
|
+
__slots__ = ("_bucket", "_client", "_endpoint_url", "_prefix", "_presign_ttl", "_region_name")
|
|
514
|
+
|
|
515
|
+
def __init__(
|
|
516
|
+
self,
|
|
517
|
+
bucket: str,
|
|
518
|
+
*,
|
|
519
|
+
prefix: str = "",
|
|
520
|
+
client: Any | None = None,
|
|
521
|
+
endpoint_url: str | None = None,
|
|
522
|
+
region_name: str | None = None,
|
|
523
|
+
presign_ttl: int = 300,
|
|
524
|
+
) -> None:
|
|
525
|
+
if not bucket.strip():
|
|
526
|
+
raise ValueError("S3StorageBackend requires a non-empty bucket name")
|
|
527
|
+
self._bucket = bucket.strip()
|
|
528
|
+
self._prefix = prefix.strip("/")
|
|
529
|
+
self._client = client
|
|
530
|
+
self._endpoint_url = endpoint_url
|
|
531
|
+
self._region_name = region_name
|
|
532
|
+
self._presign_ttl = max(30, int(presign_ttl))
|
|
533
|
+
|
|
534
|
+
def _get_client(self) -> Any:
|
|
535
|
+
if self._client is None:
|
|
536
|
+
try:
|
|
537
|
+
import boto3 # type: ignore[import-not-found]
|
|
538
|
+
except ImportError as exc:
|
|
539
|
+
raise RuntimeError(
|
|
540
|
+
"boto3 is required for S3StorageBackend. Install with: pip install 'flask-deck[s3]'"
|
|
541
|
+
) from exc
|
|
542
|
+
self._client = boto3.client(
|
|
543
|
+
"s3",
|
|
544
|
+
endpoint_url=self._endpoint_url,
|
|
545
|
+
region_name=self._region_name,
|
|
546
|
+
)
|
|
547
|
+
return self._client
|
|
548
|
+
|
|
549
|
+
def _full_key(self, key: str) -> str:
|
|
550
|
+
clean = _validate_opaque_key(key)
|
|
551
|
+
return f"{self._prefix}/{clean}" if self._prefix else clean
|
|
552
|
+
|
|
553
|
+
def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
|
|
554
|
+
clean = _validate_opaque_key(key)
|
|
555
|
+
full = self._full_key(clean)
|
|
556
|
+
digest = hashlib.sha256(data).hexdigest()
|
|
557
|
+
put_kwargs: dict[str, Any] = {
|
|
558
|
+
"Bucket": self._bucket,
|
|
559
|
+
"Key": full,
|
|
560
|
+
"Body": data,
|
|
561
|
+
"ContentType": content_type,
|
|
562
|
+
}
|
|
563
|
+
if content_type not in RASTER_INLINE_MIMES:
|
|
564
|
+
put_kwargs["ContentDisposition"] = "attachment"
|
|
565
|
+
self._get_client().put_object(**put_kwargs)
|
|
566
|
+
return StoredFile(
|
|
567
|
+
key=clean,
|
|
568
|
+
filename=clean.rsplit("/", 1)[-1],
|
|
569
|
+
content_type=content_type,
|
|
570
|
+
size_bytes=len(data),
|
|
571
|
+
sha256=digest,
|
|
572
|
+
)
|
|
573
|
+
|
|
574
|
+
def open(self, key: str) -> tuple[BinaryIO, str | None]:
|
|
575
|
+
full = self._full_key(key)
|
|
576
|
+
try:
|
|
577
|
+
resp = self._get_client().get_object(Bucket=self._bucket, Key=full)
|
|
578
|
+
except FileNotFoundError:
|
|
579
|
+
raise
|
|
580
|
+
except Exception as exc:
|
|
581
|
+
err_resp = getattr(exc, "response", None)
|
|
582
|
+
if isinstance(err_resp, dict):
|
|
583
|
+
code = str(err_resp.get("Error", {}).get("Code", ""))
|
|
584
|
+
status = err_resp.get("ResponseMetadata", {}).get("HTTPStatusCode")
|
|
585
|
+
if code in {"NoSuchKey", "404", "NotFound"} or status == 404:
|
|
586
|
+
raise FileNotFoundError(key) from exc
|
|
587
|
+
raise
|
|
588
|
+
body = resp["Body"]
|
|
589
|
+
try:
|
|
590
|
+
raw: bytes = body.read()
|
|
591
|
+
finally:
|
|
592
|
+
if hasattr(body, "close"):
|
|
593
|
+
body.close()
|
|
594
|
+
ctype = resp.get("ContentType")
|
|
595
|
+
return io.BytesIO(raw), str(ctype) if isinstance(ctype, str) else None
|
|
596
|
+
|
|
597
|
+
def delete(self, key: str) -> None:
|
|
598
|
+
try:
|
|
599
|
+
full = self._full_key(key)
|
|
600
|
+
except ValueError:
|
|
601
|
+
return
|
|
602
|
+
self._get_client().delete_object(Bucket=self._bucket, Key=full)
|
|
603
|
+
|
|
604
|
+
def exists(self, key: str) -> bool:
|
|
605
|
+
try:
|
|
606
|
+
full = self._full_key(key)
|
|
607
|
+
except ValueError:
|
|
608
|
+
return False
|
|
609
|
+
try:
|
|
610
|
+
self._get_client().head_object(Bucket=self._bucket, Key=full)
|
|
611
|
+
return True
|
|
612
|
+
except Exception:
|
|
613
|
+
return False
|
|
614
|
+
|
|
615
|
+
def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
|
|
616
|
+
full = self._full_key(key)
|
|
617
|
+
ttl = max(30, min(int(expires_in or self._presign_ttl), 3600))
|
|
618
|
+
params: dict[str, Any] = {"Bucket": self._bucket, "Key": full}
|
|
619
|
+
if not full.lower().endswith((".png", ".jpg", ".jpeg", ".webp", ".gif")):
|
|
620
|
+
params["ResponseContentDisposition"] = "attachment"
|
|
621
|
+
url = self._get_client().generate_presigned_url(
|
|
622
|
+
"get_object",
|
|
623
|
+
Params=params,
|
|
624
|
+
ExpiresIn=ttl,
|
|
625
|
+
)
|
|
626
|
+
return str(url) if url else None
|
|
627
|
+
|
|
628
|
+
|
|
629
|
+
def make_demo_png(
|
|
630
|
+
width: int = 64,
|
|
631
|
+
height: int = 64,
|
|
632
|
+
*,
|
|
633
|
+
bg: tuple[int, int, int] = (24, 24, 27),
|
|
634
|
+
fg: tuple[int, int, int] = (244, 244, 245),
|
|
635
|
+
accent: tuple[int, int, int] = (74, 222, 128),
|
|
636
|
+
) -> bytes:
|
|
637
|
+
"""Synthesize a crisp valid PNG thumbnail in pure Python stdlib (zero Pillow needed)."""
|
|
638
|
+
import zlib
|
|
639
|
+
|
|
640
|
+
def _chunk(tag: bytes, payload: bytes) -> bytes:
|
|
641
|
+
crc = zlib.crc32(tag + payload) & 0xFFFFFFFF
|
|
642
|
+
return struct.pack(">I", len(payload)) + tag + payload + struct.pack(">I", crc)
|
|
643
|
+
|
|
644
|
+
raw_rows = bytearray()
|
|
645
|
+
for y in range(height):
|
|
646
|
+
raw_rows.append(0) # filter byte None
|
|
647
|
+
for x in range(width):
|
|
648
|
+
border = x in {0, width - 1} or y in {0, height - 1}
|
|
649
|
+
diag = abs((x - width // 2) + (y - height // 2)) <= 3
|
|
650
|
+
bar = (height - 14 <= y <= height - 10) and (10 <= x <= width - 10)
|
|
651
|
+
dot = ((x - 14) ** 2 + (y - 14) ** 2) <= 20
|
|
652
|
+
if border:
|
|
653
|
+
r, g_c, b = (50, 50, 61)
|
|
654
|
+
elif dot:
|
|
655
|
+
r, g_c, b = accent
|
|
656
|
+
elif bar or diag:
|
|
657
|
+
r, g_c, b = fg
|
|
658
|
+
else:
|
|
659
|
+
r, g_c, b = bg
|
|
660
|
+
raw_rows.extend((r, g_c, b))
|
|
661
|
+
|
|
662
|
+
ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
|
|
663
|
+
idat = zlib.compress(bytes(raw_rows), 9)
|
|
664
|
+
return (
|
|
665
|
+
b"\x89PNG\r\n\x1a\n"
|
|
666
|
+
+ _chunk(b"IHDR", ihdr)
|
|
667
|
+
+ _chunk(b"IDAT", idat)
|
|
668
|
+
+ _chunk(b"IEND", b"")
|
|
669
|
+
)
|