Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_server.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
object_server.py · 474.1 KB · 13646 lines
1"""Minimal ASGI app for DBBASIC Object Server.
2
3This is the first public server slice. Source writes are disabled by default
4while the production auth and mutation paths are extracted.
5"""
6
7from __future__ import annotations
8
9import asyncio
10import contextlib
11import base64
12import binascii
13import hashlib
14import hmac
15import html
16import json
17import mimetypes
18import os
19import re
20import shutil
21import sys
22import tempfile
23import threading
24import time
25import urllib.error
26import urllib.parse
27import urllib.request
28from collections import Counter, deque
29from datetime import datetime, timezone
30from importlib import metadata as importlib_metadata
31from pathlib import Path
32from typing import Any, Callable, Mapping
33
34import http_api_contract
35import object_activity
36import object_backup
37import object_analytics
38import object_api_keys
39import object_signup
40import object_webdav
41import object_collections
42import object_correlation
43import object_credentials
44import object_daemon_control
45import object_daemon_status
46import object_events
47import object_execution
48import object_field_permissions
49import object_file_changes
50import object_files
51import object_handlers
52import object_identity
53import object_ids
54import object_logs
55import object_mcp
56import object_metadata
57import object_metrics_history
58import object_multipart
59import object_ops_log
60import object_package_changes
61import object_permission_audit
62import object_permission_store
63import object_permission_status
64import object_permissions
65import object_packages
66import object_rate_limit
67import object_reader
68import object_reconciles
69import object_record_changes
70import object_finance
71import object_records
72import object_schema_versions
73import object_stock
74import object_ai
75import object_backup_index
76import object_realtime
77import object_schemas
78import object_search
79import object_service_keys
80import object_stt
81import object_tts
82import object_user_files
83import object_site_routes
84import object_source
85import object_source_changes
86import object_state
87import object_versions
88import object_worker_pool
89import object_namespace
90from object_namespace import (
91 get_base_object_roots,
92 get_object_roots,
93 get_override_root,
94 iter_object_sources,
95 parse_user_object_id,
96 resolve_object_id,
97 validate_object_id,
98)
99from object_versions import InvalidObjectIdError
100from python_object_runtime import MethodNotSupportedError, PythonObjectRuntime
101
102SOURCE_WRITES_ENV = "DBBASIC_ENABLE_SOURCE_WRITES"
103FILE_WRITES_ENV = "DBBASIC_ENABLE_FILE_WRITES"
104ADMIN_TOKEN_ENV = "DBBASIC_ADMIN_TOKEN"
105DATA_DIR_ENV = "DBBASIC_DATA_DIR"
106MAX_REQUEST_BYTES_ENV = "DBBASIC_MAX_REQUEST_BYTES"
107MAX_OBJECT_FILE_BYTES_ENV = "DBBASIC_MAX_OBJECT_FILE_BYTES"
108MAX_CONCURRENT_REQUESTS_ENV = "DBBASIC_MAX_CONCURRENT_REQUESTS"
109MAX_CONCURRENT_EXECUTIONS_ENV = "DBBASIC_MAX_CONCURRENT_EXECUTIONS"
110RATE_LIMIT_REQUESTS_ENV = "DBBASIC_RATE_LIMIT_REQUESTS"
111RATE_LIMIT_WINDOW_SECONDS_ENV = "DBBASIC_RATE_LIMIT_WINDOW_SECONDS"
112RATE_LIMIT_TRUST_PROXY_HEADERS_ENV = "DBBASIC_RATE_LIMIT_TRUST_PROXY_HEADERS"
113OBJECT_TIMEOUT_SECONDS_ENV = "DBBASIC_OBJECT_TIMEOUT_SECONDS"
114TRUSTED_IN_PROCESS_OBJECTS_ENV = "DBBASIC_TRUSTED_IN_PROCESS_OBJECTS"
115PERMISSION_ENFORCEMENT_ENV = "DBBASIC_ENABLE_PERMISSION_ENFORCEMENT"
116PERMISSION_UNREADY_ENFORCEMENT_ENV = "DBBASIC_ALLOW_UNREADY_PERMISSION_ENFORCEMENT"
117PERMISSION_AUDIT_ENV = "DBBASIC_ENABLE_PERMISSION_AUDIT"
118PERMISSION_TRUST_HEADERS_ENV = "DBBASIC_PERMISSION_TRUST_HEADERS"
119REQUIRE_KNOWN_IDENTITY_USERS_ENV = "DBBASIC_REQUIRE_KNOWN_IDENTITY_USERS"
120SESSION_LOGIN_ENV = "DBBASIC_ENABLE_SESSION_LOGIN"
121SESSION_LOGIN_TOKEN_ENV = "DBBASIC_SESSION_LOGIN_TOKEN"
122SESSION_ADMIN_GATES_ENV = "DBBASIC_ENABLE_SESSION_ADMIN_GATES"
123PASSWORD_LOGIN_ENV = "DBBASIC_ENABLE_PASSWORD_LOGIN"
124PASSWORD_LOGIN_FAILURE_DELAY_SECONDS = 0.5
125LOGIN_LOCKOUT_ATTEMPTS_ENV = "DBBASIC_LOGIN_LOCKOUT_ATTEMPTS"
126LOGIN_LOCKOUT_WINDOW_SECONDS_ENV = "DBBASIC_LOGIN_LOCKOUT_WINDOW_SECONDS"
127DEFAULT_LOGIN_LOCKOUT_ATTEMPTS = 5
128DEFAULT_LOGIN_LOCKOUT_WINDOW_SECONDS = 900
129LOGIN_LOCKED_MESSAGE = "Too many failed attempts. Try again later."
130LANDING_PATH_ENV = "DBBASIC_AUTH_LANDING_PATH"
131SIGNUP_ATTEMPTS_PER_HOUR_PER_IP = 5
132RESET_ATTEMPTS_PER_HOUR_PER_IP = 10
133EMAILS_PER_HOUR_PER_ADDRESS = 3
134SESSION_COOKIE_NAME = "dbbasic_session"
135COOKIE_SECURE_ENV = "DBBASIC_COOKIE_SECURE"
136SITE_ROUTES_ENV = "DBBASIC_ENABLE_SITE_ROUTES"
137METRICS_SNAPSHOT_SECONDS_ENV = "DBBASIC_METRICS_SNAPSHOT_SECONDS"
138DEFAULT_METRICS_SNAPSHOT_SECONDS = 60
139RECORD_EVENTS_ENV = "DBBASIC_ENABLE_RECORD_EVENTS"
140EVENT_KEEP_COUNT_ENV = "DBBASIC_EVENT_KEEP_COUNT"
141EVENT_KEEP_SECONDS_ENV = "DBBASIC_EVENT_KEEP_SECONDS"
142# 58's <block>_enabled kill switch, default ON: field-filter query params are
143# read and applied unless explicitly disabled. Off degrades to "ignore the
144# filter params" (unfiltered, same as before this feature), never to a 400 --
145# see _handle_collection_records_get and 58's Degradation section.
146FILTERING_ENABLED_ENV = "DBBASIC_ENABLE_FILTERING"
147# 63 optimistic concurrency: gates whether an update's If-Match/expected_rev
148# precondition is honored. Default on; flipping it off makes writes carrying
149# a precondition behave as last-write-wins rather than turning a working
150# write path into an error path under brownout (same posture as filtering).
151CONCURRENCY_ENABLED_ENV = "DBBASIC_ENABLE_CONCURRENCY"
152# 64 (feed): the <block>_enabled kill switch for GET /api/feed and the
153# get_feed MCP verb. Default on; off degrades to an empty, non-error
154# response (spec's Degradation section) -- `follows` itself, and the
155# follow button, are untouched by this flag, only the composed read is.
156FEED_ENABLED_ENV = "DBBASIC_ENABLE_FEED"
157# Query params the collection-records GET route reserves for pagination/
158# sort/search rather than treating as a field filter (58's Encoding
159# section); every other param is a `field` or `field.op` filter condition.
160FILTER_RESERVED_PARAMS = frozenset({"limit", "offset", "sort", "q"})
161# `field.in=a,b,c,...` cap (58's Open Questions: bound the list so `in`
162# can't become an unbounded OR by the back door).
163FILTER_IN_MAX_VALUES = 50
164PACKAGES_DIR_ENV = "DBBASIC_PACKAGES_DIR"
165PRIVATE_PACKAGES_DIR_ENV = "DBBASIC_PRIVATE_PACKAGES_DIR"
166DEFAULT_PRIVATE_PACKAGES_DIR = "packages-private"
167PACKAGE_INSTALLS_ENABLED_ENV = "DBBASIC_ENABLE_PACKAGE_INSTALLS"
168PACKAGE_RESTORE_ENABLED_ENV = "DBBASIC_ENABLE_PACKAGE_RESTORE"
169DEFAULT_MAX_REQUEST_BYTES = 1_048_576
170DEFAULT_MAX_OBJECT_FILE_BYTES = DEFAULT_MAX_REQUEST_BYTES
171DEFAULT_MAX_CONCURRENT_REQUESTS = 64
172DEFAULT_MAX_CONCURRENT_EXECUTIONS = 8
173DEFAULT_RATE_LIMIT_REQUESTS = 0
174DEFAULT_RATE_LIMIT_WINDOW_SECONDS = 60
175DEFAULT_OBJECT_TIMEOUT_SECONDS = 0.0
176TRUE_VALUES = {"1", "true", "yes", "on"}
177SENSITIVE_GET_FLAGS = {
178 "source",
179 "source_changes",
180 "changes",
181 "state",
182 "logs",
183 "metadata",
184 "versions",
185 "files",
186 "file",
187}
188RECORD_EVENT_TYPES = {
189 "create": "collection.record.created",
190 "update": "collection.record.updated",
191 "delete": "collection.record.deleted",
192}
193ADMIN_CHANGE_KINDS = frozenset({"source", "file", "record", "package"})
194
195REALTIME_ENABLED_ENV = "DBBASIC_ENABLE_REALTIME"
196REALTIME_QUEUE_MAX_ENV = "DBBASIC_REALTIME_QUEUE_MAX"
197WEBSOCKET_PATH = "/ws"
198MAX_WS_SUBSCRIPTIONS = 64
199_realtime_hub = object_realtime.RealtimeHub()
200
201_runtime = PythonObjectRuntime()
202
203
204class RequestMetrics:
205 """Thread-safe, in-process request metrics for health and Scroll."""
206
207 def __init__(self) -> None:
208 self._lock = threading.Lock()
209 self._start_time = time.time()
210 self._total_requests = 0
211 self._total_errors = 0
212 self._total_4xx = 0
213 self._response_times_ms: deque[float] = deque(maxlen=1000)
214 self._methods: Counter[str] = Counter()
215 self._status_codes: Counter[int] = Counter()
216 self._paths: Counter[str] = Counter()
217 self._path_errors: Counter[str] = Counter()
218 self._recent_errors: deque[dict[str, Any]] = deque(maxlen=50)
219
220 def record_request(self, method: str, path: str, status: int, duration_ms: float) -> None:
221 with self._lock:
222 self._total_requests += 1
223 self._methods[method] += 1
224 self._status_codes[status] += 1
225 self._paths[path] += 1
226 self._response_times_ms.append(duration_ms)
227
228 if status >= 500:
229 self._total_errors += 1
230 self._path_errors[path] += 1
231 if 400 <= status < 500:
232 self._total_4xx += 1
233 self._path_errors[path] += 1
234 if status >= 400:
235 self._recent_errors.append(
236 {
237 "timestamp": _utc_timestamp(),
238 "method": method,
239 "path": path,
240 "status": status,
241 "duration_ms": round(duration_ms, 2),
242 }
243 )
244
245 def snapshot(self) -> dict[str, Any]:
246 with self._lock:
247 uptime_seconds = max(time.time() - self._start_time, 0.001)
248 response_times = list(self._response_times_ms)
249 total_requests = self._total_requests
250 total_errors = self._total_errors
251 total_4xx = self._total_4xx
252 methods = dict(self._methods)
253 status_codes = {str(code): count for code, count in self._status_codes.items()}
254 top_paths = [
255 {
256 "path": path,
257 "requests": count,
258 "errors": self._path_errors.get(path, 0),
259 }
260 for path, count in self._paths.most_common(10)
261 ]
262 recent_errors = list(self._recent_errors)
263
264 return {
265 "uptime_seconds": round(uptime_seconds, 3),
266 "uptime_human": _human_duration(uptime_seconds),
267 "total_requests": total_requests,
268 "total_errors": total_errors,
269 "total_4xx": total_4xx,
270 "requests_per_second": round(total_requests / uptime_seconds, 2),
271 "error_rate": round((total_errors / total_requests * 100) if total_requests else 0, 2),
272 "response_time_ms": _response_time_summary(response_times),
273 "methods": methods,
274 "status_codes": status_codes,
275 "top_paths": top_paths,
276 "recent_errors": recent_errors,
277 }
278
279
280class RequestBodyTooLargeError(ValueError):
281 """Raised when an inbound HTTP request body exceeds the configured cap."""
282
283 def __init__(self, *, max_bytes: int, actual_bytes: int):
284 self.max_bytes = max_bytes
285 self.actual_bytes = actual_bytes
286 super().__init__("Request body too large")
287
288
289class ConcurrencyToken:
290 """Release handle for a claimed concurrency slot."""
291
292 def __init__(self, limiter: "ConcurrencyLimiter | None"):
293 self._limiter = limiter
294 self._released = False
295
296 def release(self) -> None:
297 if self._released:
298 return
299
300 self._released = True
301 if self._limiter is not None:
302 self._limiter.release()
303
304
305class ConcurrencyLimiter:
306 """Small per-process non-queueing concurrency limiter."""
307
308 def __init__(self) -> None:
309 self._lock = threading.Lock()
310 self._in_flight = 0
311
312 def try_acquire(self, limit: int) -> ConcurrencyToken | None:
313 if limit <= 0:
314 return ConcurrencyToken(None)
315
316 with self._lock:
317 if self._in_flight >= limit:
318 return None
319 self._in_flight += 1
320
321 return ConcurrencyToken(self)
322
323 def release(self) -> None:
324 with self._lock:
325 if self._in_flight > 0:
326 self._in_flight -= 1
327
328 def snapshot(self, limit: int) -> dict[str, Any]:
329 with self._lock:
330 in_flight = self._in_flight
331
332 if limit <= 0:
333 return {
334 "in_flight": in_flight,
335 "max": limit,
336 "available": None,
337 "limited": False,
338 }
339
340 return {
341 "in_flight": in_flight,
342 "max": limit,
343 "available": max(limit - in_flight, 0),
344 "limited": True,
345 }
346
347
348_request_limiter = ConcurrencyLimiter()
349_execution_limiter = ConcurrencyLimiter()
350_metrics = RequestMetrics()
351
352_worker_pool: object_worker_pool.WorkerPool | None = None
353_worker_pool_size_used: int = 0
354_worker_pool_lock = asyncio.Lock()
355
356
357async def app(scope: dict[str, Any], receive, send) -> None:
358 """ASGI application entry point."""
359 if scope["type"] == "lifespan":
360 await _handle_lifespan(receive, send)
361 return
362
363 if scope["type"] == "websocket":
364 await _handle_websocket(scope, receive, send)
365 return
366
367 if scope["type"] != "http":
368 return
369
370 method = scope.get("method", "GET").upper()
371 path = scope.get("path", "/")
372 status_code = 500
373 started_at = time.perf_counter()
374 request_headers = _parse_headers(scope.get("headers", []))
375 correlation_id = object_correlation.ensure_correlation_id(
376 request_headers.get(object_correlation.CORRELATION_ID_HEADER)
377 )
378 correlation_token = object_correlation.set_current_correlation_id(correlation_id)
379 minted_visitor_token = _mint_visitor_token(path, request_headers)
380
381 async def send_with_metrics(message):
382 nonlocal status_code
383 if message["type"] == "http.response.start":
384 status_code = int(message.get("status", status_code))
385 headers = list(message.get("headers", []))
386 if not any(
387 name.lower() == object_correlation.CORRELATION_ID_HEADER.encode("latin-1")
388 for name, _value in headers
389 ):
390 headers.append(
391 (
392 object_correlation.CORRELATION_ID_HEADER.encode("latin-1"),
393 correlation_id.encode("latin-1"),
394 )
395 )
396 if minted_visitor_token:
397 headers.append((
398 b"set-cookie",
399 object_analytics.visitor_cookie_header(
400 minted_visitor_token,
401 secure=_cookie_secure_enabled(),
402 ).encode("latin-1"),
403 ))
404 message = {**message, "headers": headers}
405 await send(message)
406
407 try:
408 await _handle_http(scope, receive, send_with_metrics)
409 finally:
410 object_correlation.reset_current_correlation_id(correlation_token)
411 duration_ms = (time.perf_counter() - started_at) * 1000
412 _metrics.record_request(method, path, status_code, duration_ms)
413 await _capture_page_view(scope, method, path, status_code, request_headers,
414 minted_visitor_token=minted_visitor_token)
415
416
417def _mint_visitor_token(path: str, headers: dict[str, str]) -> str:
418 """A new anonymous visitor token for this response, or "" for none.
419
420 Decided ONCE per request, before the response starts, because the same
421 answer is needed in two places: the `set-cookie` header on the way out
422 and the `page_views.session_id` stamp on the row that request writes.
423 Minting it twice would give a visitor a cookie whose value never
424 appears in the log.
425
426 Every refusal (analytics off, DNT, Sec-GPC, an existing cookie, a
427 non-page path) lives in object_analytics.should_set_visitor_cookie,
428 which is pure and tested; this function is the wiring and nothing
429 else. Best-effort like the rest of the analytics path: a visitor
430 counter may never be the reason a response fails.
431 """
432 try:
433 if not object_analytics.should_set_visitor_cookie(path, headers):
434 return ""
435 return object_analytics.new_visitor_token()
436 except Exception: # noqa: BLE001 -- analytics must never break a response
437 return ""
438
439
440async def _capture_page_view(
441 scope: dict[str, Any], method: str, path: str, status_code: int,
442 headers: dict[str, str], *, minted_visitor_token: str = "",
443) -> None:
444 """Append one page_views row for this request (analytics). Off unless
445 DBBASIC_ANALYTICS is set; skips asset/infra paths; the file write is
446 offloaded to a thread so it never blocks the event loop under load; and the
447 whole thing is best-effort -- analytics must NEVER break a response (a
448 missing page_views collection, a full disk, anything, is swallowed)."""
449 try:
450 if not object_analytics.analytics_enabled() or not object_analytics.should_capture(path):
451 return
452 record = object_analytics.build_page_view(
453 path=path, method=method, status=status_code,
454 ip=_client_ip(scope, headers), headers=headers,
455 owners=object_analytics.owner_ips(),
456 # The operator's own automation is not visitor traffic. This is a
457 # constant-time env compare, not an auth lookup -- the hot path
458 # stays cheap, and a signed-in member browsing is deliberately
459 # still counted as the real traffic it is.
460 is_operator=_request_is_operator(headers),
461 # The cookie this response is setting. The browser cannot have
462 # sent it back yet, so without it the first page of every visit
463 # is threadless and every funnel starts one step late.
464 minted_visitor_token=minted_visitor_token,
465 )
466 base_dir = _data_dir()
467
468 def _write() -> None:
469 try:
470 object_records.create_collection_record(
471 object_analytics.PAGE_VIEWS_COLLECTION, record,
472 base_dir=base_dir, actor="server:analytics",
473 )
474 except Exception: # noqa: BLE001 -- never surface an analytics write error
475 pass
476
477 await asyncio.to_thread(_write)
478 except Exception: # noqa: BLE001 -- belt and suspenders on the hot path
479 pass
480
481
482def _request_is_operator(headers: dict[str, str]) -> bool:
483 """True when this request carried the admin token.
484
485 Deliberately only the token, and deliberately constant-time: this runs
486 on every request, so it may not touch disk, and it must not leak the
487 token through timing. A session cookie is NOT resolved here -- that
488 would be a per-request identity lookup on the hot path, and a signed-in
489 member is traffic worth measuring anyway.
490 """
491 admin_token = os.environ.get(ADMIN_TOKEN_ENV, "")
492 if not admin_token:
493 return False
494 request_token = _authorization_token(headers)
495 if not request_token:
496 return False
497 return hmac.compare_digest(request_token, admin_token)
498
499
500def _realtime_enabled() -> bool:
501 value = os.environ.get(REALTIME_ENABLED_ENV)
502 if value is None:
503 return True
504 return value.strip().lower() in TRUE_VALUES
505
506
507def _realtime_queue_max() -> int:
508 return _env_int(REALTIME_QUEUE_MAX_ENV, object_realtime.DEFAULT_QUEUE_MAX)
509
510
511async def _handle_websocket(scope: dict[str, Any], receive, send) -> None:
512 """Live push transport: authenticated, permission-filtered record events.
513
514 A client connects to /ws with its session (cookie or bearer),
515 subscribes to collections it is allowed to read, and receives a small
516 signal ({type: record, collection, record_id, action}) whenever a
517 matching record it can see changes — never the record body, so no
518 surface can leak fields. The client refetches through the normal
519 permission-enforced API. The durable event log stays as the poll-based
520 fallback for missed events and multi-worker deployments.
521 """
522 headers = _parse_headers(scope.get("headers", []))
523
524 # Consume the connect frame first so we can accept or reject cleanly.
525 connect = await receive()
526 if connect.get("type") != "websocket.connect":
527 return
528
529 if not _realtime_enabled() or scope.get("path") != WEBSOCKET_PATH:
530 await send({"type": "websocket.close", "code": 1008})
531 return
532
533 subject = _permission_subject(headers)
534 if subject.user_id is None and "admin" not in subject.roles:
535 await send({"type": "websocket.close", "code": 1008})
536 return
537
538 await send({"type": "websocket.accept"})
539 queue: "asyncio.Queue[dict[str, Any]]" = asyncio.Queue(maxsize=_realtime_queue_max())
540 subscriber = object_realtime.Subscriber(subject=subject, queue=queue)
541 _realtime_hub.add(subscriber)
542 await _ws_send(send, {"type": "welcome", "user": subject.user_id})
543
544 reader = asyncio.ensure_future(_ws_reader(receive, send, subscriber))
545 writer = asyncio.ensure_future(_ws_writer(send, queue))
546 try:
547 done, pending = await asyncio.wait(
548 {reader, writer}, return_when=asyncio.FIRST_COMPLETED
549 )
550 for task in pending:
551 task.cancel()
552 for task in done:
553 with contextlib.suppress(Exception):
554 task.result()
555 finally:
556 _realtime_hub.remove(subscriber)
557 with contextlib.suppress(Exception):
558 await send({"type": "websocket.close"})
559
560
561async def _ws_reader(receive, send, subscriber) -> None:
562 while True:
563 message = await receive()
564 kind = message.get("type")
565 if kind == "websocket.disconnect":
566 return
567 if kind != "websocket.receive":
568 continue
569 text = message.get("text")
570 if not text:
571 continue
572 try:
573 data = json.loads(text)
574 except (ValueError, TypeError):
575 continue
576 if not isinstance(data, dict):
577 continue
578 action = data.get("action")
579 if action == "subscribe":
580 for collection in _ws_clean_collections(data.get("collections")):
581 if len(subscriber.collections) >= MAX_WS_SUBSCRIPTIONS:
582 break
583 if _ws_can_subscribe(subscriber.subject, collection):
584 subscriber.collections.add(collection)
585 await _ws_send(
586 send, {"type": "subscribed", "collections": sorted(subscriber.collections)}
587 )
588 elif action == "unsubscribe":
589 for collection in _ws_clean_collections(data.get("collections")):
590 subscriber.collections.discard(collection)
591 await _ws_send(
592 send, {"type": "subscribed", "collections": sorted(subscriber.collections)}
593 )
594 elif action == "ping":
595 await _ws_send(send, {"type": "pong"})
596
597
598async def _ws_writer(send, queue) -> None:
599 while True:
600 event = await queue.get()
601 await _ws_send(send, event)
602
603
604async def _ws_send(send, payload: dict[str, Any]) -> None:
605 await send({"type": "websocket.send", "text": json.dumps(payload, default=str)})
606
607
608def _ws_clean_collections(value: Any) -> list[str]:
609 if not isinstance(value, list):
610 return []
611 out: list[str] = []
612 for item in value:
613 if isinstance(item, str) and object_collections.validate_collection_name(item):
614 out.append(item)
615 if len(out) >= MAX_WS_SUBSCRIPTIONS:
616 break
617 return out
618
619
620def _ws_can_subscribe(subject, collection: str) -> bool:
621 """A subject may follow a collection only if it may read it."""
622 if not _permission_checks_enabled() or not _permission_enforcement_enabled():
623 return True
624 try:
625 policy = object_permission_store.load_policy(_data_dir())
626 except ValueError:
627 return False
628 decision = object_permissions.check_permission(
629 subject, object_permissions.READ, policy=policy, collection=collection
630 )
631 return decision.allowed
632
633
634def _realtime_publish(collection: str, record_id: str, action: str, record) -> None:
635 """Push a record-change signal to permitted live subscribers.
636
637 Runs the same read decision as a GET: with enforcement on, a
638 subscriber only hears about a record its row filter would let it see.
639 Only the id and action travel — never the record body.
640 """
641 if not _realtime_enabled() or not collection:
642 return
643 subscribers = _realtime_hub.wanting(collection)
644 if not subscribers:
645 return
646
647 enforced = _permission_checks_enabled() and _permission_enforcement_enabled()
648 policy = None
649 if enforced:
650 try:
651 policy = object_permission_store.load_policy(_data_dir())
652 except ValueError:
653 return # cannot filter safely -> do not push
654
655 event = {
656 "type": "record",
657 "collection": collection,
658 "record_id": record_id,
659 "action": action,
660 }
661 for subscriber in subscribers:
662 if enforced and record is not None:
663 decision = object_permissions.check_permission(
664 subscriber.subject,
665 object_permissions.READ,
666 policy=policy,
667 collection=collection,
668 record=record,
669 )
670 if not decision.allowed:
671 continue
672 subscriber.deliver(dict(event))
673
674
675async def _handle_http(scope: dict[str, Any], receive, send) -> None:
676 method = scope.get("method", "GET").upper()
677 path = scope.get("path", "/")
678 query = _parse_query(scope.get("query_string", b""))
679 headers = _parse_headers(scope.get("headers", []))
680 correlation_id = object_correlation.current_correlation_id()
681 if correlation_id is not None:
682 headers[object_correlation.CORRELATION_ID_HEADER] = correlation_id
683
684 _maybe_append_metrics_snapshot()
685
686 if path == "/health":
687 if _is_detailed_health(query) and await _send_rate_limit_if_needed(scope, headers, send):
688 return
689 await _handle_health(send, query, headers)
690 return
691
692 if await _send_rate_limit_if_needed(scope, headers, send):
693 return
694
695 if (
696 method not in {"GET", "HEAD", "OPTIONS"}
697 and _authorization_token(headers) is None
698 and _session_cookie_token(headers) is not None
699 and not _cookie_request_origin_allowed(headers)
700 ):
701 await _send_json(
702 send,
703 {"status": "error", "error": "Cross-origin cookie request rejected"},
704 status=403,
705 )
706 return
707
708 request_limit = _max_concurrent_requests()
709 request_token = _request_limiter.try_acquire(request_limit)
710 if request_token is None:
711 await _send_capacity_error(send, limit_name="requests", max_concurrent=request_limit)
712 return
713
714 try:
715 try:
716 body = await _read_body(
717 receive, headers=headers, max_bytes=_webdav_body_limit(method, path)
718 )
719 except RequestBodyTooLargeError as exc:
720 await _send_request_too_large(send, exc)
721 return
722
723 if path == http_api_contract.MCP_PATH:
724 await _handle_mcp(send, method, body, headers)
725 return
726
727 webhooks_prefix = http_api_contract.WEBHOOKS_PATH + "/"
728 if path.startswith(webhooks_prefix):
729 await _handle_webhook(send, method, path.removeprefix(webhooks_prefix),
730 body, query, headers)
731 return
732
733 if path == http_api_contract.SEARCH_PATH:
734 await _handle_search(send, method, query, headers)
735 return
736
737 if path == http_api_contract.AI_CHAT_PATH:
738 await _handle_ai_chat(send, method, body, headers)
739 return
740
741 if path == http_api_contract.TTS_PATH:
742 await _handle_tts(send, method, body, headers)
743 return
744
745 if path == http_api_contract.STT_PATH:
746 await _handle_stt(send, method, body, headers)
747 return
748
749 if path == http_api_contract.READ_PATH:
750 await _handle_read(send, method, body, headers)
751 return
752
753 schema_meta_prefix = f"{http_api_contract.SCHEMA_META_PATH}/"
754 if path.startswith(schema_meta_prefix):
755 await _handle_schema_meta(send, method, path.removeprefix(schema_meta_prefix))
756 return
757
758 if path == http_api_contract.FLAGS_PATH:
759 await _handle_flags(send, method, headers)
760 return
761
762 if path == http_api_contract.ACTIVITY_PATH:
763 await _handle_activity(send, method, query, headers)
764 return
765
766 # 64 (feed): the composed follow-graph read. Lives at /api/feed, not
767 # bare /feed, because /feed is this feature's own PAGE route (site_feed,
768 # packages/app-feed), resolved further down by the site-route
769 # convention -- the same /api/{x} (data) vs /{x} (page) split
770 # /api/activity above already uses opposite site_activity, so the two
771 # surfaces never collide on one path.
772 if path == "/api/feed":
773 await _handle_feed(send, method, query, headers)
774 return
775
776 # Stage 7 derived-read verbs: folded/computed data an agent can't get
777 # as a plain collection read. Owner-scoped (the caller's own books/
778 # stock), thin wrappers over object_stock/object_finance's own pure
779 # fold functions -- the MCP get_stock_levels/get_finance_summary verbs
780 # route here.
781 if path == "/api/stock":
782 await _handle_stock_levels(send, method, headers)
783 return
784 if path == "/api/finance/summary":
785 await _handle_finance_summary(send, method, headers)
786 return
787
788 if path == http_api_contract.PREFS_PATH:
789 await _handle_prefs(send, method, headers)
790 return
791
792 prefs_prefix = http_api_contract.PREFS_PATH + "/"
793 if path.startswith(prefs_prefix):
794 await _handle_pref(send, method, path[len(prefs_prefix):], body, headers)
795 return
796
797 if path == http_api_contract.WEBDAV_PATH or path.startswith(http_api_contract.WEBDAV_PATH + "/"):
798 await _handle_webdav(send, method, path, body, headers)
799 return
800
801 if path == http_api_contract.USER_FILES_PATH:
802 await _handle_user_file_upload(send, method, body, headers)
803 return
804
805 user_file_prefix = http_api_contract.USER_FILES_PATH + "/"
806 if path.startswith(user_file_prefix):
807 await _handle_user_file(send, method, path[len(user_file_prefix):], headers)
808 return
809
810 if path == "/api/share":
811 await _handle_share(send, method, query, body, headers)
812 return
813 if path.startswith("/api/share/"):
814 await _handle_share_revoke(send, method, path[len("/api/share/"):], headers)
815 return
816
817 if path == http_api_contract.LOGIN_PATH:
818 await _handle_login(send, method, query, body, headers)
819 return
820
821 if path == http_api_contract.LOGOUT_PATH:
822 await _handle_logout(send, method, headers)
823 return
824
825 if path == http_api_contract.SIGNUP_PATH:
826 await _handle_signup(scope, send, method, query, body, headers)
827 return
828
829 if path == http_api_contract.VERIFY_EMAIL_PATH:
830 await _handle_verify_email(send, method, query, body, headers)
831 return
832
833 if path == http_api_contract.PASSWORD_RESET_PATH:
834 await _handle_password_reset(scope, send, method, query, body, headers)
835 return
836
837 if path == http_api_contract.PASSWORD_RESET_CONFIRM_PATH:
838 await _handle_password_reset_confirm(send, method, query, body, headers)
839 return
840
841 if path == http_api_contract.IDENTITY_ACCOUNTS_PATH:
842 await _handle_identity_accounts(send, method, body, headers)
843 return
844
845 identity_account_prefix = http_api_contract.IDENTITY_ACCOUNTS_PATH + "/"
846 if path.startswith(identity_account_prefix):
847 account_id = path[len(identity_account_prefix):]
848 await _handle_identity_account(send, method, account_id, headers)
849 return
850
851 if path == http_api_contract.IDENTITY_USERS_PATH:
852 await _handle_identity_users(send, method, query, body, headers)
853 return
854
855 identity_user_prefix = http_api_contract.IDENTITY_USERS_PATH + "/"
856 if path.startswith(identity_user_prefix):
857 user_id = path[len(identity_user_prefix):]
858 await _handle_identity_user(send, method, user_id, body, headers)
859 return
860
861 if path == http_api_contract.IDENTITY_SESSIONS_PATH:
862 await _handle_identity_sessions(send, method, body, headers)
863 return
864
865 identity_session_prefix = http_api_contract.IDENTITY_SESSIONS_PATH + "/"
866 if path.startswith(identity_session_prefix):
867 session_id = path[len(identity_session_prefix):]
868 await _handle_identity_session(send, method, session_id, headers)
869 return
870
871 if path == http_api_contract.IDENTITY_CURRENT_SESSION_PATH:
872 await _handle_identity_current_session(send, method, body, headers)
873 return
874
875 if path == http_api_contract.IDENTITY_PATH:
876 await _handle_identity(send, method, headers)
877 return
878
879 if path == http_api_contract.PERMISSIONS_POLICY_PATH:
880 await _handle_permissions_policy(send, method, body, headers)
881 return
882
883 if path == http_api_contract.PERMISSIONS_STATUS_PATH:
884 await _handle_permissions_status(send, method, headers)
885 return
886
887 if path == http_api_contract.PERMISSIONS_CHECK_PATH:
888 await _handle_permissions_check(send, method, body, headers)
889 return
890
891 if path == http_api_contract.PERMISSIONS_AUDIT_PATH:
892 await _handle_permissions_audit(send, method, query, headers)
893 return
894
895 if path == http_api_contract.EVENTS_PATH:
896 await _handle_events(send, method, query, body, headers)
897 return
898
899 if path == http_api_contract.EVENT_DELIVERIES_PATH:
900 await _handle_event_deliveries(send, method, query, headers)
901 return
902
903 if path == http_api_contract.EVENT_SUBSCRIPTIONS_PATH:
904 await _handle_event_subscriptions(send, method, query, body, headers)
905 return
906
907 if path == http_api_contract.ADMIN_STATUS_PATH:
908 await _handle_admin_status(send, method, headers)
909 return
910
911 if path == http_api_contract.ADMIN_STORAGE_PATH:
912 await _handle_admin_storage(send, method, headers)
913 return
914
915 if path == http_api_contract.ADMIN_CHANGES_PATH:
916 await _handle_admin_changes(send, method, query, headers)
917 return
918
919 if path == http_api_contract.ADMIN_OPS_PATH:
920 await _handle_admin_ops(send, method, query, headers)
921 return
922
923 if path == http_api_contract.ADMIN_BACKUPS_PATH:
924 await _handle_admin_backups(send, method, headers)
925 return
926
927 admin_backups_prefix = f"{http_api_contract.ADMIN_BACKUPS_PATH}/"
928 if path.startswith(admin_backups_prefix):
929 tail = path.removeprefix(admin_backups_prefix)
930 if tail.endswith("/download"):
931 backup_id = tail.removesuffix("/download")
932 await _handle_admin_backup_download(send, method, backup_id, headers)
933 return
934 if tail.endswith("/preview"):
935 backup_id = tail.removesuffix("/preview")
936 await _handle_admin_backup_preview(send, method, backup_id, query, headers)
937 return
938 if tail.endswith("/record"):
939 backup_id = tail.removesuffix("/record")
940 await _handle_admin_backup_record(send, method, backup_id, query, headers)
941 return
942 await _send_json(send, {"status": "error", "error": "Not found"}, status=404)
943 return
944
945 if path == http_api_contract.ADMIN_FILES_PATH:
946 await _handle_admin_files(send, method, query, headers)
947 return
948
949 admin_files_prefix = f"{http_api_contract.ADMIN_FILES_PATH}/"
950 if path.startswith(admin_files_prefix):
951 object_id = path.removeprefix(admin_files_prefix)
952 await _handle_admin_object_files(send, method, object_id, query, body, headers)
953 return
954
955 if path == http_api_contract.ADMIN_RECONCILES_PATH:
956 await _handle_admin_reconciles(send, method, query, headers)
957 return
958
959 admin_reconciles_prefix = f"{http_api_contract.ADMIN_RECONCILES_PATH}/"
960 if path.startswith(admin_reconciles_prefix):
961 reconcile_tail = path.removeprefix(admin_reconciles_prefix)
962 if reconcile_tail.endswith("/resolve"):
963 reconcile_id = reconcile_tail.removesuffix("/resolve")
964 await _handle_admin_reconcile_resolve(send, method, reconcile_id, body, headers)
965 else:
966 await _handle_admin_reconcile(send, method, reconcile_tail, headers)
967 return
968
969 if path == http_api_contract.ADMIN_OBJECTS_PATH:
970 await _handle_admin_objects(send, method, body, headers)
971 return
972
973 admin_objects_prefix = f"{http_api_contract.ADMIN_OBJECTS_PATH}/"
974 if path.startswith(admin_objects_prefix):
975 object_tail = path.removeprefix(admin_objects_prefix)
976 if object_tail.endswith("/execute"):
977 object_id = object_tail.removesuffix("/execute")
978 await _handle_admin_object_execute(send, method, object_id, body, headers)
979 return
980
981 if object_tail.endswith("/override"):
982 object_id = object_tail.removesuffix("/override")
983 await _handle_admin_object_override(send, method, object_id, headers)
984 return
985
986 object_id = object_tail
987 await _handle_admin_object(send, method, object_id, query, body, headers)
988 return
989
990 if path == http_api_contract.ADMIN_COLLECTIONS_PATH:
991 await _handle_admin_collections(send, method, headers)
992 return
993
994 admin_collections_prefix = f"{http_api_contract.ADMIN_COLLECTIONS_PATH}/"
995 if path.startswith(admin_collections_prefix):
996 collection_tail = path.removeprefix(admin_collections_prefix)
997 await _handle_admin_collection(send, method, collection_tail, query, body, headers)
998 return
999
1000 if path == http_api_contract.ADMIN_SCHEMAS_PATH:
1001 await _handle_admin_schemas(send, method, headers)
1002 return
1003
1004 admin_schemas_prefix = f"{http_api_contract.ADMIN_SCHEMAS_PATH}/"
1005 if path.startswith(admin_schemas_prefix):
1006 schema = path.removeprefix(admin_schemas_prefix)
1007 await _handle_admin_schema(send, method, schema, query, body, headers)
1008 return
1009
1010 if path == http_api_contract.ADMIN_IDENTITY_ACCOUNTS_PATH:
1011 await _handle_admin_identity_accounts(send, method, headers)
1012 return
1013
1014 admin_identity_accounts_prefix = f"{http_api_contract.ADMIN_IDENTITY_ACCOUNTS_PATH}/"
1015 if path.startswith(admin_identity_accounts_prefix):
1016 account_id = path.removeprefix(admin_identity_accounts_prefix)
1017 await _handle_admin_identity_account(send, method, account_id, headers)
1018 return
1019
1020 if path == http_api_contract.ADMIN_IDENTITY_USERS_PATH:
1021 await _handle_admin_identity_users(send, method, query, headers)
1022 return
1023
1024 admin_identity_users_prefix = f"{http_api_contract.ADMIN_IDENTITY_USERS_PATH}/"
1025 if path.startswith(admin_identity_users_prefix):
1026 user_id = path.removeprefix(admin_identity_users_prefix)
1027 await _handle_admin_identity_user(send, method, user_id, body, headers)
1028 return
1029
1030 if path == http_api_contract.ADMIN_IDENTITY_SESSIONS_PATH:
1031 await _handle_admin_identity_sessions(send, method, headers)
1032 return
1033
1034 admin_identity_sessions_prefix = f"{http_api_contract.ADMIN_IDENTITY_SESSIONS_PATH}/"
1035 if path.startswith(admin_identity_sessions_prefix):
1036 session_id = path.removeprefix(admin_identity_sessions_prefix)
1037 await _handle_admin_identity_session(send, method, session_id, headers)
1038 return
1039
1040 if path == http_api_contract.DAEMON_STATUS_PATH:
1041 await _handle_daemon_status(send, method, headers)
1042 return
1043
1044 if path == http_api_contract.DAEMON_SCHEDULER_TASKS_PATH:
1045 await _handle_daemon_scheduler_tasks(send, method, query, body, headers)
1046 return
1047
1048 daemon_scheduler_prefix = http_api_contract.DAEMON_SCHEDULER_TASKS_PATH + "/"
1049 if path.startswith(daemon_scheduler_prefix):
1050 task_id = path[len(daemon_scheduler_prefix):]
1051 await _handle_daemon_scheduler_task(send, method, task_id, body, headers)
1052 return
1053
1054 if path == http_api_contract.DAEMON_QUEUE_MESSAGES_PATH:
1055 await _handle_daemon_queue_messages(send, method, query, body, headers)
1056 return
1057
1058 daemon_queue_prefix = http_api_contract.DAEMON_QUEUE_MESSAGES_PATH + "/"
1059 if path.startswith(daemon_queue_prefix):
1060 message_id = path[len(daemon_queue_prefix):]
1061 await _handle_daemon_queue_message(send, method, message_id, body, headers)
1062 return
1063
1064 if path == http_api_contract.PACKAGES_PATH:
1065 await _handle_packages(send, method, headers)
1066 return
1067
1068 if path.startswith(f"{http_api_contract.PACKAGES_PATH}/"):
1069 package_tail = path.removeprefix(f"{http_api_contract.PACKAGES_PATH}/")
1070 package_parts = package_tail.split("/")
1071 if len(package_parts) == 2 and package_parts[1] == "install":
1072 await _handle_package_install(send, method, package_parts[0], body, headers)
1073 elif len(package_parts) == 2 and package_parts[1] == "restore":
1074 await _handle_package_restore(send, method, package_parts[0], body, headers)
1075 elif len(package_parts) == 2 and package_parts[1] == "changes":
1076 await _handle_package_changes(send, method, package_parts[0], query, headers)
1077 else:
1078 await _handle_package(send, method, package_tail, query, headers)
1079 return
1080
1081 if path == http_api_contract.OBJECTS_PATH:
1082 if method == "GET":
1083 gate_error = _admin_token_gate_error(
1084 headers,
1085 f"Object listing requires {ADMIN_TOKEN_ENV}.",
1086 )
1087 if gate_error is not None:
1088 status, message = gate_error
1089 await _send_json(send, {"status": "error", "error": message}, status=status)
1090 return
1091
1092 await _send_json(send, _list_objects_payload())
1093 return
1094
1095 if method == "POST":
1096 await _handle_objects_post(send, body, headers)
1097 return
1098
1099 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1100 return
1101
1102 if path == http_api_contract.COLLECTIONS_PATH:
1103 await _handle_collections(send, method, headers)
1104 return
1105
1106 if path.startswith(f"{http_api_contract.COLLECTIONS_PATH}/"):
1107 collection_path = path.removeprefix(f"{http_api_contract.COLLECTIONS_PATH}/")
1108 collection_parts = collection_path.split("/")
1109 if len(collection_parts) == 2 and collection_parts[1] == "changes":
1110 await _handle_collection_changes(
1111 send,
1112 method,
1113 collection_parts[0],
1114 query,
1115 headers,
1116 )
1117 return
1118
1119 if len(collection_parts) == 2 and collection_parts[1] == "records":
1120 await _handle_collection_records(
1121 send,
1122 method,
1123 collection_parts[0],
1124 query,
1125 body,
1126 headers,
1127 )
1128 return
1129
1130 if (
1131 len(collection_parts) == 4
1132 and collection_parts[1] == "records"
1133 and collection_parts[3] == "changes"
1134 ):
1135 await _handle_collection_record_changes(
1136 send,
1137 method,
1138 collection_parts[0],
1139 collection_parts[2],
1140 query,
1141 headers,
1142 )
1143 return
1144
1145 if len(collection_parts) == 3 and collection_parts[1] == "records":
1146 await _handle_collection_record(
1147 send,
1148 method,
1149 collection_parts[0],
1150 collection_parts[2],
1151 body,
1152 headers,
1153 )
1154 return
1155
1156 collection = collection_path
1157 await _handle_collection_get(send, method, collection, headers)
1158 return
1159
1160 if path == http_api_contract.SCHEMAS_PATH:
1161 await _handle_schemas(send, method, headers)
1162 return
1163
1164 if path.startswith(f"{http_api_contract.SCHEMAS_PATH}/"):
1165 schema = path.removeprefix(f"{http_api_contract.SCHEMAS_PATH}/")
1166 await _handle_schema(send, method, schema, query, body, headers)
1167 return
1168
1169 if path.startswith(f"{http_api_contract.OBJECTS_PATH}/"):
1170 object_id = path.removeprefix(f"{http_api_contract.OBJECTS_PATH}/")
1171 if method == "GET":
1172 await _handle_object_get(send, object_id, query, headers)
1173 return
1174
1175 if method == "POST":
1176 await _handle_object_post(send, object_id, body, query, headers)
1177 return
1178
1179 if method == "PUT" and query.get("source") == "true":
1180 await _handle_object_source_put(send, object_id, body, headers)
1181 return
1182
1183 if method == "PUT":
1184 await _handle_object_body_method(send, object_id, "PUT", body, query, headers)
1185 return
1186
1187 if method == "DELETE":
1188 await _handle_object_body_method(send, object_id, "DELETE", body, query, headers)
1189 return
1190
1191 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1192 return
1193
1194 if await _handle_site_route(send, method, path, query, body, headers):
1195 return
1196
1197 await _send_json(send, {"status": "error", "error": "Not found"}, status=404)
1198 finally:
1199 request_token.release()
1200
1201
1202async def _handle_site_route(
1203 send,
1204 method: str,
1205 path: str,
1206 query: dict[str, str],
1207 body: bytes,
1208 headers: dict[str, str],
1209) -> bool:
1210 """Serve clean public URLs by resolving them to objects.
1211
1212 Runs only after every built-in route family has declined the path, so
1213 reserved surfaces can never be shadowed. Resolution order: convention
1214 (`/about` -> `site_about`), then `site_routes` records patterns, then the
1215 `site_404` object. The resolved object executes through the normal
1216 execution path, so permission policy, audit, timeouts, and correlation
1217 ids all apply. Returns False when site routing is disabled or nothing
1218 resolves, leaving the plain JSON 404.
1219 """
1220 if not _env_enabled(SITE_ROUTES_ENV):
1221 return False
1222
1223 if method not in {"GET", "POST", "PUT", "DELETE"}:
1224 return False
1225
1226 site = object_site_routes.resolve_host(headers.get("host"), _site_host_records())
1227 params: dict[str, str] = {}
1228 target_id = object_site_routes.convention_object_id(
1229 path,
1230 prefix=site["prefix"],
1231 home=site["home"],
1232 )
1233 if target_id is None or resolve_object_id(target_id, get_object_roots()) is None:
1234 match = object_site_routes.match_records(
1235 path,
1236 _site_route_records(),
1237 host=site["host"],
1238 )
1239 if match is not None:
1240 target_id, params = match
1241 elif resolve_object_id(site["not_found"], get_object_roots()) is not None:
1242 target_id = site["not_found"]
1243 params = {"path": path}
1244 elif (
1245 site["not_found"] != object_site_routes.NOT_FOUND_OBJECT_ID
1246 and resolve_object_id(object_site_routes.NOT_FOUND_OBJECT_ID, get_object_roots())
1247 is not None
1248 ):
1249 target_id = object_site_routes.NOT_FOUND_OBJECT_ID
1250 params = {"path": path}
1251 else:
1252 return False
1253
1254 try:
1255 if method == "GET":
1256 payload: dict[str, Any] = dict(query)
1257 else:
1258 payload = _parse_post_payload(body, query, headers)
1259 except ValueError as exc:
1260 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1261 return True
1262
1263 payload.update(params)
1264 # The raw matched path, so a routed object can resolve a capture-LESS
1265 # route (an index/list view like /entities, whose views.route has no
1266 # {param}) -- route captures alone can only identify detail views. A
1267 # reserved, underscore-prefixed key (like _identity); objects that don't
1268 # need it ignore it. See view_render._resolve_view_and_record.
1269 payload["_path"] = path
1270 # App cookies, minus the identity session -- see _object_visible_cookies.
1271 # Without this a public page has no way to recognise a returning visitor:
1272 # the shop minted a new basket on every GET because the `cart` cookie the
1273 # browser was faithfully sending never reached the object.
1274 payload["_cookies"] = _object_visible_cookies(headers)
1275
1276 permission_action = object_permissions.EXECUTE
1277 if method == "PUT":
1278 permission_action = object_permissions.UPDATE
1279 elif method == "DELETE":
1280 permission_action = object_permissions.DELETE
1281
1282 await _execute_object_method(
1283 send,
1284 target_id,
1285 method,
1286 payload,
1287 headers,
1288 permission_action=permission_action,
1289 )
1290 return True
1291
1292
1293def _site_route_records() -> list[dict[str, Any]]:
1294 try:
1295 return object_records.read_collection_records(
1296 object_site_routes.SITE_ROUTES_COLLECTION,
1297 base_dir=_data_dir(),
1298 )
1299 except (ValueError, LookupError, OSError):
1300 return []
1301
1302
1303def _site_host_records() -> list[dict[str, Any]]:
1304 try:
1305 return object_records.read_collection_records(
1306 object_site_routes.SITE_HOSTS_COLLECTION,
1307 base_dir=_data_dir(),
1308 )
1309 except (ValueError, LookupError, OSError):
1310 return []
1311
1312
1313async def _handle_health(
1314 send,
1315 query: dict[str, str],
1316 headers: dict[str, str],
1317) -> None:
1318 if not _is_detailed_health(query):
1319 await _send_json(send, {"status": "ok"})
1320 return
1321
1322 gate_error = _admin_token_gate_error(
1323 headers,
1324 f"Health capacity requires {ADMIN_TOKEN_ENV}.",
1325 )
1326 if gate_error is not None:
1327 status, message = gate_error
1328 await _send_json(send, {"status": "error", "error": message}, status=status)
1329 return
1330
1331 payload = _health_payload(include_metrics=query.get("metrics") == "true")
1332 if query.get("metrics") == "true" and query.get("history") == "true":
1333 try:
1334 payload["history"] = object_metrics_history.read_history(
1335 base_dir=_data_dir(),
1336 limit=_query_int(query, "history_limit", default=360, minimum=1, maximum=2000),
1337 )
1338 except (OSError, ValueError):
1339 payload["history"] = []
1340 status_code = 503 if payload["status"] == "degraded" else 200
1341 await _send_json(send, payload, status=status_code)
1342
1343
1344def _is_detailed_health(query: dict[str, str]) -> bool:
1345 return query.get("capacity") == "true" or query.get("metrics") == "true"
1346
1347
1348async def _handle_identity(send, method: str, headers: dict[str, str]) -> None:
1349 if method != "GET":
1350 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1351 return
1352
1353 subject, auth_method = _permission_identity(headers)
1354 await _send_json(
1355 send,
1356 {
1357 "status": "ok",
1358 "subject": _permission_subject_payload(subject),
1359 "auth": {
1360 "method": auth_method,
1361 "trusted_headers_enabled": _env_enabled(PERMISSION_TRUST_HEADERS_ENV),
1362 "trusted_headers_present": _trusted_identity_headers_present(headers),
1363 },
1364 "permissions": {
1365 "enforcement_enabled": _permission_enforcement_enabled(),
1366 "enforcement_requested": _permission_enforcement_requested(),
1367 "enforcement_blocked": _permission_enforcement_blocked(),
1368 "audit_enabled": _permission_audit_enabled(),
1369 },
1370 },
1371 )
1372
1373
1374async def _handle_identity_accounts(
1375 send,
1376 method: str,
1377 body: bytes,
1378 headers: dict[str, str],
1379) -> None:
1380 gate_error = _admin_token_gate_error(headers, f"Identity accounts require {ADMIN_TOKEN_ENV}.")
1381 if gate_error is not None:
1382 status, message = gate_error
1383 await _send_json(send, {"status": "error", "error": message}, status=status)
1384 return
1385
1386 if method == "GET":
1387 accounts = object_identity.list_accounts(base_dir=_data_dir())
1388 await _send_json(
1389 send,
1390 {
1391 "status": "ok",
1392 "accounts": accounts,
1393 "count": len(accounts),
1394 },
1395 )
1396 return
1397
1398 if method == "POST":
1399 try:
1400 payload = _parse_json_body(body)
1401 account = object_identity.create_account(payload, base_dir=_data_dir())
1402 except ValueError as exc:
1403 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1404 return
1405
1406 await _send_json(send, {"status": "ok", "account": account}, status=201)
1407 return
1408
1409 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1410
1411
1412async def _handle_identity_account(
1413 send,
1414 method: str,
1415 account_id: str,
1416 headers: dict[str, str],
1417) -> None:
1418 gate_error = _admin_token_gate_error(headers, f"Identity accounts require {ADMIN_TOKEN_ENV}.")
1419 if gate_error is not None:
1420 status, message = gate_error
1421 await _send_json(send, {"status": "error", "error": message}, status=status)
1422 return
1423
1424 if "/" in account_id or not account_id:
1425 await _send_json(send, {"status": "error", "error": "Invalid account id"}, status=400)
1426 return
1427
1428 if method != "GET":
1429 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1430 return
1431
1432 try:
1433 account = object_identity.get_account(account_id, base_dir=_data_dir())
1434 except object_identity.InvalidIdentityPayloadError as exc:
1435 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1436 return
1437 except object_identity.AccountNotFoundError as exc:
1438 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1439 return
1440
1441 await _send_json(send, {"status": "ok", "account": account})
1442
1443
1444async def _handle_identity_users(
1445 send,
1446 method: str,
1447 query: dict[str, str],
1448 body: bytes,
1449 headers: dict[str, str],
1450) -> None:
1451 gate_error = _admin_token_gate_error(headers, f"Identity users require {ADMIN_TOKEN_ENV}.")
1452 if gate_error is not None:
1453 status, message = gate_error
1454 await _send_json(send, {"status": "error", "error": message}, status=status)
1455 return
1456
1457 if method == "GET":
1458 try:
1459 users = object_identity.list_users(
1460 account_id=query.get("account_id"),
1461 base_dir=_data_dir(),
1462 )
1463 except object_identity.InvalidIdentityPayloadError as exc:
1464 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1465 return
1466
1467 await _send_json(
1468 send,
1469 {
1470 "status": "ok",
1471 "users": users,
1472 "count": len(users),
1473 },
1474 )
1475 return
1476
1477 if method == "POST":
1478 try:
1479 payload = _parse_json_body(body)
1480 user = object_identity.create_user(payload, base_dir=_data_dir())
1481 except object_identity.AccountNotFoundError as exc:
1482 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1483 return
1484 except ValueError as exc:
1485 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1486 return
1487
1488 await _send_json(send, {"status": "ok", "user": user}, status=201)
1489 return
1490
1491 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1492
1493
1494def _service_keys_route_parts(user_id: str) -> tuple[str | None, str | None]:
1495 """Split '{user}/service-keys[/{service}]' route tails; (None, None) otherwise."""
1496 if "/service-keys" not in user_id:
1497 return None, None
1498 target, _, tail = user_id.partition("/service-keys")
1499 if "/" in target or not target:
1500 return None, None
1501 if tail == "":
1502 return target, None
1503 if tail.startswith("/") and tail.count("/") == 1 and len(tail) > 1:
1504 return target, tail[1:]
1505 return None, None
1506
1507
1508def _api_keys_route_parts(user_id: str) -> tuple[str | None, str | None]:
1509 """Split '{user}/api-keys[/{key_id}]' route tails; (None, None) otherwise."""
1510 if "/api-keys" not in user_id:
1511 return None, None
1512 target, _, tail = user_id.partition("/api-keys")
1513 if "/" in target or not target:
1514 return None, None
1515 if tail == "":
1516 return target, None
1517 if tail.startswith("/") and tail.count("/") == 1 and len(tail) > 1:
1518 return target, tail[1:]
1519 return None, None
1520
1521
1522async def _handle_identity_user_api_keys(
1523 send,
1524 method: str,
1525 user_id: str,
1526 key_id: str | None,
1527 body: bytes,
1528 headers: dict[str, str],
1529) -> None:
1530 """Self-service per-user API keys: create (raw token returned ONCE), list
1531 status, revoke. The token never appears again -- only its hash is stored.
1532 A signed-in user manages their own; the admin gate covers operator use."""
1533 session = _current_identity_session(headers)
1534 self_service = session is not None and session.user_id == user_id
1535 if not self_service:
1536 gate_error = _admin_token_gate_error(
1537 headers, "API keys require the account owner's session or the admin gate."
1538 )
1539 if gate_error is not None:
1540 status, message = gate_error
1541 await _send_json(send, {"status": "error", "error": message}, status=status)
1542 return
1543
1544 if (
1545 method in {"PUT", "POST", "DELETE"}
1546 and _session_cookie_token(headers)
1547 and not _authorization_token(headers)
1548 and not _cookie_request_origin_allowed(headers)
1549 ):
1550 await _send_json(
1551 send, {"status": "error", "error": "Cross-origin cookie writes are not allowed."}, status=403,
1552 )
1553 return
1554
1555 if method == "GET" and key_id is None:
1556 try:
1557 keys = object_api_keys.list_api_keys(user_id, base_dir=_data_dir())
1558 except object_api_keys.InvalidApiKeyError as exc:
1559 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1560 return
1561 await _send_json(send, {"status": "ok", "user_id": user_id, "keys": keys})
1562 return
1563
1564 if method in {"POST", "PUT"} and key_id is None:
1565 try:
1566 payload = _parse_json_body(body)
1567 except ValueError as exc:
1568 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1569 return
1570 try:
1571 meta, raw_token = object_api_keys.create_api_key(
1572 user_id, payload.get("name"), base_dir=_data_dir()
1573 )
1574 except object_api_keys.InvalidApiKeyError as exc:
1575 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1576 return
1577 _append_ops_auth_event(event="api_key_created", identifier=user_id, label=meta["key_id"])
1578 # The ONLY time the raw token is ever returned.
1579 await _send_json(send, {"status": "ok", "token": raw_token, **meta})
1580 return
1581
1582 if method == "DELETE" and key_id is not None:
1583 try:
1584 deleted = object_api_keys.revoke_api_key(user_id, key_id, base_dir=_data_dir())
1585 except object_api_keys.InvalidApiKeyError as exc:
1586 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1587 return
1588 if not deleted:
1589 await _send_json(send, {"status": "error", "error": "No such API key"}, status=404)
1590 return
1591 _append_ops_auth_event(event="api_key_revoked", identifier=user_id, label=key_id)
1592 await _send_json(send, {"status": "ok", "deleted": True, "key_id": key_id})
1593 return
1594
1595 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1596
1597
1598async def _handle_identity_user_service_keys(
1599 send,
1600 method: str,
1601 user_id: str,
1602 service: str | None,
1603 body: bytes,
1604 headers: dict[str, str],
1605) -> None:
1606 """Write-only per-user service keys: set, list status, delete — never read.
1607
1608 A signed-in user manages their own keys; the admin gate covers operator
1609 use. Key material never appears in any response.
1610 """
1611 session = _current_identity_session(headers)
1612 self_service = session is not None and session.user_id == user_id
1613 if not self_service:
1614 gate_error = _admin_token_gate_error(
1615 headers, "Service keys require the account owner's session or the admin gate."
1616 )
1617 if gate_error is not None:
1618 status, message = gate_error
1619 await _send_json(send, {"status": "error", "error": message}, status=status)
1620 return
1621
1622 if (
1623 method in {"PUT", "POST", "DELETE"}
1624 and _session_cookie_token(headers)
1625 and not _authorization_token(headers)
1626 and not _cookie_request_origin_allowed(headers)
1627 ):
1628 await _send_json(
1629 send,
1630 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
1631 status=403,
1632 )
1633 return
1634
1635 if method == "GET" and service is None:
1636 try:
1637 statuses = object_service_keys.list_service_key_status(
1638 user_id, base_dir=_data_dir()
1639 )
1640 except object_service_keys.InvalidServiceKeyError as exc:
1641 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1642 return
1643 await _send_json(send, {"status": "ok", "user_id": user_id, "services": statuses})
1644 return
1645
1646 if method in {"PUT", "POST"} and service is None:
1647 try:
1648 payload = _parse_json_body(body)
1649 except ValueError as exc:
1650 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1651 return
1652 if object_service_keys.is_reserved_service(payload.get("service")):
1653 await _send_json(
1654 send,
1655 {"status": "error", "error": "That service name is reserved for platform-owned secrets."},
1656 status=403,
1657 )
1658 return
1659 try:
1660 result = object_service_keys.set_service_key(
1661 user_id,
1662 payload.get("service"),
1663 payload.get("key"),
1664 base_dir=_data_dir(),
1665 )
1666 except object_service_keys.InvalidServiceKeyError as exc:
1667 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1668 return
1669 _append_ops_auth_event(
1670 event="service_key_set",
1671 identifier=user_id,
1672 label=result["service"],
1673 )
1674 await _send_json(send, {"status": "ok", **result})
1675 return
1676
1677 if method == "DELETE" and service is not None:
1678 if object_service_keys.is_reserved_service(service):
1679 await _send_json(
1680 send,
1681 {"status": "error", "error": "That service name is reserved for platform-owned secrets."},
1682 status=403,
1683 )
1684 return
1685 try:
1686 deleted = object_service_keys.remove_service_key(
1687 user_id, service, base_dir=_data_dir()
1688 )
1689 except object_service_keys.InvalidServiceKeyError as exc:
1690 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1691 return
1692 if not deleted:
1693 await _send_json(
1694 send, {"status": "error", "error": "No key stored for that service"}, status=404
1695 )
1696 return
1697 _append_ops_auth_event(
1698 event="service_key_removed",
1699 identifier=user_id,
1700 label=service,
1701 )
1702 await _send_json(send, {"status": "ok", "deleted": True, "service": service})
1703 return
1704
1705 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1706
1707
1708async def _handle_identity_user(
1709 send,
1710 method: str,
1711 user_id: str,
1712 body: bytes,
1713 headers: dict[str, str],
1714) -> None:
1715 service_keys_target, service_name = _service_keys_route_parts(user_id)
1716 if service_keys_target is not None:
1717 await _handle_identity_user_service_keys(
1718 send, method, service_keys_target, service_name, body, headers
1719 )
1720 return
1721
1722 api_keys_target, api_key_id = _api_keys_route_parts(user_id)
1723 if api_keys_target is not None:
1724 await _handle_identity_user_api_keys(
1725 send, method, api_keys_target, api_key_id, body, headers
1726 )
1727 return
1728
1729 gate_error = _admin_token_gate_error(headers, f"Identity users require {ADMIN_TOKEN_ENV}.")
1730 if gate_error is not None:
1731 status, message = gate_error
1732 await _send_json(send, {"status": "error", "error": message}, status=status)
1733 return
1734
1735 if user_id.endswith("/password"):
1736 target_user_id = user_id.removesuffix("/password")
1737 if "/" in target_user_id or not target_user_id:
1738 await _send_json(send, {"status": "error", "error": "Invalid user id"}, status=400)
1739 return
1740 await _handle_identity_user_password(send, method, target_user_id, body)
1741 return
1742
1743 if "/" in user_id or not user_id:
1744 await _send_json(send, {"status": "error", "error": "Invalid user id"}, status=400)
1745 return
1746
1747 if method != "GET":
1748 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1749 return
1750
1751 try:
1752 user = object_identity.get_user(user_id, base_dir=_data_dir())
1753 except object_identity.InvalidIdentityPayloadError as exc:
1754 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1755 return
1756 except object_identity.UserNotFoundError as exc:
1757 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1758 return
1759
1760 await _send_json(send, {"status": "ok", "user": user})
1761
1762
1763async def _handle_identity_user_password(
1764 send,
1765 method: str,
1766 user_id: str,
1767 body: bytes,
1768) -> None:
1769 try:
1770 user = object_identity.get_user(user_id, base_dir=_data_dir())
1771 except object_identity.InvalidIdentityPayloadError as exc:
1772 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1773 return
1774 except object_identity.UserNotFoundError as exc:
1775 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1776 return
1777
1778 if method == "POST":
1779 try:
1780 payload = _parse_json_body(body)
1781 password = payload.get("password")
1782 result = object_credentials.set_password(
1783 user["user_id"],
1784 password,
1785 base_dir=_data_dir(),
1786 )
1787 except object_credentials.InvalidPasswordError as exc:
1788 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1789 return
1790 except ValueError as exc:
1791 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1792 return
1793 except OSError as exc:
1794 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
1795 return
1796
1797 await _send_json(
1798 send,
1799 {
1800 "status": "ok",
1801 "user_id": result["user_id"],
1802 "operation": result["operation"],
1803 "updated_at": result["updated_at"],
1804 },
1805 )
1806 return
1807
1808 if method == "DELETE":
1809 try:
1810 removed = object_credentials.remove_password(user["user_id"], base_dir=_data_dir())
1811 except object_credentials.InvalidPasswordError as exc:
1812 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1813 return
1814 except OSError as exc:
1815 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
1816 return
1817
1818 await _send_json(
1819 send,
1820 {
1821 "status": "ok",
1822 "user_id": user["user_id"],
1823 "removed": removed,
1824 },
1825 )
1826 return
1827
1828 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1829
1830
1831async def _handle_identity_sessions(
1832 send,
1833 method: str,
1834 body: bytes,
1835 headers: dict[str, str],
1836) -> None:
1837 gate_error = _admin_token_gate_error(headers, f"Identity sessions require {ADMIN_TOKEN_ENV}.")
1838 if gate_error is not None:
1839 status, message = gate_error
1840 await _send_json(send, {"status": "error", "error": message}, status=status)
1841 return
1842
1843 if method == "GET":
1844 sessions = object_identity.list_sessions(base_dir=_data_dir())
1845 await _send_json(
1846 send,
1847 {
1848 "status": "ok",
1849 "sessions": sessions,
1850 "count": len(sessions),
1851 },
1852 )
1853 return
1854
1855 if method == "POST":
1856 try:
1857 payload = _parse_json_body(body)
1858 result = object_identity.create_session(
1859 payload,
1860 base_dir=_data_dir(),
1861 require_known_user=_env_enabled(REQUIRE_KNOWN_IDENTITY_USERS_ENV),
1862 )
1863 except object_identity.UserNotFoundError as exc:
1864 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1865 return
1866 except object_identity.AccountNotFoundError as exc:
1867 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1868 return
1869 except ValueError as exc:
1870 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1871 return
1872
1873 await _send_json(send, {"status": "ok", **result}, status=201)
1874 return
1875
1876 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1877
1878
1879async def _handle_identity_session(
1880 send,
1881 method: str,
1882 session_id: str,
1883 headers: dict[str, str],
1884) -> None:
1885 gate_error = _admin_token_gate_error(headers, f"Identity sessions require {ADMIN_TOKEN_ENV}.")
1886 if gate_error is not None:
1887 status, message = gate_error
1888 await _send_json(send, {"status": "error", "error": message}, status=status)
1889 return
1890
1891 if "/" in session_id or not session_id:
1892 await _send_json(send, {"status": "error", "error": "Invalid session id"}, status=400)
1893 return
1894
1895 if method == "GET":
1896 try:
1897 session = object_identity.get_session(session_id, base_dir=_data_dir())
1898 except object_identity.InvalidSessionPayloadError as exc:
1899 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1900 return
1901 except object_identity.SessionNotFoundError as exc:
1902 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1903 return
1904
1905 await _send_json(send, {"status": "ok", "session": session})
1906 return
1907
1908 if method == "DELETE":
1909 try:
1910 session = object_identity.revoke_session(session_id, base_dir=_data_dir())
1911 except object_identity.InvalidSessionPayloadError as exc:
1912 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1913 return
1914 except object_identity.SessionNotFoundError as exc:
1915 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1916 return
1917
1918 await _send_json(send, {"status": "ok", "session": session})
1919 return
1920
1921 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1922
1923
1924async def _handle_identity_current_session(
1925 send,
1926 method: str,
1927 body: bytes,
1928 headers: dict[str, str],
1929) -> None:
1930 if method not in {"GET", "POST", "DELETE"}:
1931 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
1932 return
1933
1934 if method == "POST":
1935 try:
1936 peeked_payload = _parse_json_body(body)
1937 except ValueError:
1938 peeked_payload = None
1939 if isinstance(peeked_payload, dict) and "password" in peeked_payload:
1940 await _handle_identity_password_login(send, peeked_payload)
1941 return
1942
1943 gate_error = _session_login_gate_error(headers)
1944 if gate_error is not None:
1945 status, message = gate_error
1946 await _send_json(send, {"status": "error", "error": message}, status=status)
1947 return
1948
1949 try:
1950 payload = _parse_json_body(body)
1951 result = object_identity.create_session(
1952 _identity_session_login_payload(payload),
1953 base_dir=_data_dir(),
1954 require_known_user=True,
1955 )
1956 except object_identity.UserNotFoundError as exc:
1957 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1958 return
1959 except object_identity.AccountNotFoundError as exc:
1960 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1961 return
1962 except ValueError as exc:
1963 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
1964 return
1965
1966 _append_ops_auth_event(
1967 "session_minted",
1968 user_id=result["session"]["user_id"],
1969 method="session_login",
1970 label=result["session"].get("label"),
1971 )
1972 await _send_json(send, {"status": "ok", **result}, status=201)
1973 return
1974
1975 session = _current_identity_session(headers)
1976 if session is None:
1977 await _send_json(
1978 send,
1979 {"status": "error", "error": "Active session token required"},
1980 status=401,
1981 )
1982 return
1983
1984 if method == "GET":
1985 await _send_json(send, {"status": "ok", "session": session.public_payload()})
1986 return
1987
1988 try:
1989 revoked = object_identity.revoke_session(session.session_id, base_dir=_data_dir())
1990 except (object_identity.InvalidSessionPayloadError, object_identity.SessionNotFoundError) as exc:
1991 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
1992 return
1993
1994 await _send_json(send, {"status": "ok", "session": revoked})
1995
1996
1997async def _handle_identity_password_login(
1998 send,
1999 payload: dict[str, Any],
2000) -> None:
2001 if not _env_enabled(PASSWORD_LOGIN_ENV):
2002 await _send_json(
2003 send,
2004 {
2005 "status": "error",
2006 "error": f"Password login is disabled. Set {PASSWORD_LOGIN_ENV}=true.",
2007 },
2008 status=403,
2009 )
2010 return
2011
2012 try:
2013 login = _identity_password_login_payload(payload)
2014 except ValueError as exc:
2015 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
2016 return
2017
2018 attempted = login["user_id"] or login["email"] or ""
2019 if _login_locked(attempted):
2020 _append_ops_auth_event("login_locked", identifier=attempted, method="password")
2021 await _send_json(
2022 send,
2023 {"status": "error", "error": LOGIN_LOCKED_MESSAGE},
2024 status=429,
2025 )
2026 return
2027
2028 user = _password_login_user(login)
2029 lookup_user_id = user["user_id"] if user is not None else "__unknown_password_login__"
2030 verified = object_credentials.verify_password(
2031 lookup_user_id,
2032 login["password"],
2033 base_dir=_data_dir(),
2034 )
2035
2036 if user is None or not verified:
2037 _append_ops_auth_event("login_failed", identifier=attempted, method="password")
2038 await asyncio.sleep(PASSWORD_LOGIN_FAILURE_DELAY_SECONDS)
2039 await _send_json(send, {"status": "error", "error": "Invalid credentials"}, status=401)
2040 return
2041
2042 try:
2043 result = object_identity.create_session(
2044 {
2045 "user_id": user["user_id"],
2046 "label": login["label"],
2047 "ttl_seconds": login["ttl_seconds"],
2048 },
2049 base_dir=_data_dir(),
2050 require_known_user=True,
2051 )
2052 except ValueError:
2053 _append_ops_auth_event("login_failed", identifier=attempted, method="password")
2054 await asyncio.sleep(PASSWORD_LOGIN_FAILURE_DELAY_SECONDS)
2055 await _send_json(send, {"status": "error", "error": "Invalid credentials"}, status=401)
2056 return
2057
2058 _append_ops_auth_event(
2059 "login_succeeded",
2060 identifier=attempted,
2061 user_id=user["user_id"],
2062 method="password",
2063 label=login["label"],
2064 )
2065 await _send_json(send, {"status": "ok", **result}, status=201)
2066
2067
2068def _identity_password_login_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
2069 allowed_keys = {"user_id", "email", "password", "label", "ttl_seconds"}
2070 unexpected = sorted(set(payload) - allowed_keys)
2071 if unexpected:
2072 raise ValueError(f"Unsupported password login fields: {', '.join(unexpected)}")
2073
2074 password = payload.get("password")
2075 if not isinstance(password, str) or not password:
2076 raise ValueError("password must be a non-empty string")
2077
2078 user_id = payload.get("user_id")
2079 email = payload.get("email")
2080 if (user_id is None) == (email is None):
2081 raise ValueError("Provide exactly one of user_id or email")
2082
2083 label = payload.get("label")
2084 if label is not None and not isinstance(label, str):
2085 raise ValueError("label must be a string")
2086
2087 return {
2088 "user_id": user_id,
2089 "email": email,
2090 "password": password,
2091 "label": label or "password login",
2092 "ttl_seconds": payload.get("ttl_seconds"),
2093 }
2094
2095
2096# Request headers a webhook object may see. A deliberate SAFELIST rather
2097# than everything-minus-secrets: providers sign with headers like
2098# stripe-signature / x-hub-signature-256, and content negotiation needs
2099# content-type -- but authorization and cookie belong to OUR callers, and
2100# handing them to package code would turn a webhook object into a
2101# credential tap. Extending this list is a conscious act, not a default.
2102_WEBHOOK_HEADER_SAFELIST = (
2103 "content-type",
2104 "user-agent",
2105 "stripe-signature",
2106 "x-hub-signature-256",
2107 "x-signature",
2108 "x-request-id",
2109 "idempotency-key",
2110)
2111
2112
2113async def _handle_webhook(
2114 send,
2115 method: str,
2116 name: str,
2117 body: bytes,
2118 query: dict[str, str],
2119 headers: dict[str, str],
2120) -> None:
2121 """POST /webhooks/{name} -> execute the `webhook_{name}` object with the
2122 RAW request body.
2123
2124 The one thing webhook objects need that no other route provides:
2125 provider signatures (Stripe, GitHub, Twilio) are HMACs over the exact
2126 bytes on the wire, and every other path parses the body before the
2127 object runs, destroying the thing that must be verified. This endpoint
2128 is deliberately provider-neutral core plumbing -- it knows nothing
2129 about Stripe; it delivers bytes and safelisted headers to an object a
2130 package ships, and the object owns verification and meaning.
2131
2132 Security posture: webhooks are unauthenticated BY NATURE (the caller
2133 is a payment processor, not a user), so authenticity comes from the
2134 object verifying a signature over the raw body -- which is exactly why
2135 the body must arrive unparsed. The object still needs an explicit
2136 public-execute permission rule (no rule, no execution), the body-size
2137 limit already applied upstream holds, and the response is always JSON
2138 with no reflection of the input.
2139 """
2140 if method != "POST":
2141 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2142 return
2143 clean = name.strip("/")
2144 if not clean or "/" in clean or not clean.replace("-", "_").replace("_", "a").isalnum():
2145 await _send_json(send, {"status": "error", "error": "Unknown webhook"}, status=404)
2146 return
2147 object_id = f"webhook_{clean.replace('-', '_')}"
2148 if resolve_object_id(object_id, get_object_roots()) is None:
2149 await _send_json(send, {"status": "error", "error": "Unknown webhook"}, status=404)
2150 return
2151
2152 payload: dict[str, Any] = dict(query)
2153 payload["_raw_body"] = body.decode("utf-8", "replace")
2154 payload["_headers"] = {
2155 key: value for key, value in headers.items()
2156 if key.lower() in _WEBHOOK_HEADER_SAFELIST
2157 }
2158 await _execute_object_method(
2159 send,
2160 object_id,
2161 "POST",
2162 payload,
2163 headers,
2164 permission_action=object_permissions.EXECUTE,
2165 )
2166
2167
2168async def _handle_mcp(
2169 send,
2170 method: str,
2171 body: bytes,
2172 headers: dict[str, str],
2173) -> None:
2174 if method != "POST":
2175 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2176 return
2177
2178 protocol_header = headers.get("mcp-protocol-version", "").strip()
2179 if protocol_header and protocol_header not in object_mcp.SUPPORTED_MCP_PROTOCOL_VERSIONS:
2180 await _send_json(
2181 send,
2182 object_mcp.jsonrpc_error(
2183 -32600, f"Unsupported MCP protocol version: {protocol_header}"
2184 ),
2185 status=400,
2186 )
2187 return
2188
2189 gate_error = _admin_token_gate_error(headers, f"MCP requires {ADMIN_TOKEN_ENV}.")
2190 if gate_error is not None:
2191 status, message = gate_error
2192 await _send_json(send, object_mcp.jsonrpc_error(-32000, message), status=status)
2193 return
2194
2195 try:
2196 message = json.loads(body.decode("utf-8"))
2197 except (UnicodeDecodeError, json.JSONDecodeError):
2198 await _send_json(send, object_mcp.jsonrpc_error(-32700, "Parse error"))
2199 return
2200
2201 if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
2202 await _send_json(
2203 send,
2204 object_mcp.jsonrpc_error(-32600, "Invalid Request: missing jsonrpc 2.0"),
2205 )
2206 return
2207
2208 rpc_method = message.get("method")
2209 params = message.get("params") or {}
2210 request_id = message.get("id")
2211
2212 if not isinstance(rpc_method, str) or not rpc_method:
2213 await _send_json(
2214 send,
2215 object_mcp.jsonrpc_error(-32600, "Invalid Request: missing method", request_id),
2216 )
2217 return
2218
2219 if rpc_method.startswith("notifications/"):
2220 await _send_response(send, status=202, headers=[], body=b"")
2221 return
2222
2223 if rpc_method == "initialize":
2224 session_id = headers.get("mcp-session-id", "").strip() or object_ids.new_uuid4()
2225 await _send_json(
2226 send,
2227 object_mcp.jsonrpc_response(object_mcp.handle_initialize(params), request_id),
2228 headers=[("mcp-session-id", session_id)],
2229 )
2230 return
2231
2232 if rpc_method == "tools/list":
2233 await _send_json(
2234 send,
2235 object_mcp.jsonrpc_response(object_mcp.handle_tools_list(), request_id),
2236 )
2237 return
2238
2239 if rpc_method == "tools/call":
2240 tool_name = params.get("name")
2241 arguments = params.get("arguments") or {}
2242 try:
2243 route_method, path, query_string, route_body = object_mcp.tool_route(
2244 tool_name, arguments
2245 )
2246 except ValueError as exc:
2247 await _send_json(
2248 send,
2249 object_mcp.jsonrpc_response(
2250 {
2251 "content": [
2252 {"type": "text", "text": json.dumps({"error": str(exc)})}
2253 ],
2254 "isError": True,
2255 },
2256 request_id,
2257 ),
2258 )
2259 return
2260
2261 status, payload = await _internal_request(
2262 route_method,
2263 path,
2264 query_string,
2265 route_body,
2266 authorization=headers.get("authorization", ""),
2267 )
2268 await _send_json(
2269 send,
2270 object_mcp.jsonrpc_response(
2271 object_mcp.tool_result_content(status, payload), request_id
2272 ),
2273 )
2274 return
2275
2276 await _send_json(
2277 send,
2278 object_mcp.jsonrpc_error(-32601, f"Method not found: {rpc_method}", request_id),
2279 )
2280
2281
2282async def _internal_request(
2283 method: str,
2284 path: str,
2285 query_string: str,
2286 body: bytes,
2287 *,
2288 authorization: str,
2289) -> tuple[int, Any]:
2290 """Dispatch one request through the server's own routing.
2291
2292 Used by the MCP layer so tool calls hit the exact same gates, permission
2293 checks, audit trail, and correlation ids as external HTTP callers.
2294 """
2295 messages: list[dict[str, Any]] = []
2296 sent = False
2297
2298 async def receive() -> dict[str, Any]:
2299 nonlocal sent
2300 if not sent:
2301 sent = True
2302 return {"type": "http.request", "body": body, "more_body": False}
2303 return {"type": "http.disconnect"}
2304
2305 async def send(message: dict[str, Any]) -> None:
2306 messages.append(message)
2307
2308 scope_headers = [(b"content-type", b"application/json")]
2309 if authorization:
2310 scope_headers.append((b"authorization", authorization.encode("latin-1")))
2311
2312 scope = {
2313 "type": "http",
2314 "method": method,
2315 "path": path,
2316 "query_string": query_string.encode("utf-8"),
2317 "headers": scope_headers,
2318 "client": ("127.0.0.1", 0),
2319 }
2320 await app(scope, receive, send)
2321
2322 status = 500
2323 for message in messages:
2324 if message["type"] == "http.response.start":
2325 status = message["status"]
2326 break
2327 raw = b"".join(
2328 message.get("body", b"")
2329 for message in messages
2330 if message["type"] == "http.response.body"
2331 )
2332 try:
2333 payload: Any = json.loads(raw.decode("utf-8"))
2334 except (UnicodeDecodeError, json.JSONDecodeError):
2335 payload = raw.decode("utf-8", errors="replace")
2336 return status, payload
2337
2338
2339async def _handle_login(
2340 send,
2341 method: str,
2342 query: dict[str, str],
2343 body: bytes,
2344 headers: dict[str, str],
2345) -> None:
2346 if method == "GET":
2347 if not _env_enabled(PASSWORD_LOGIN_ENV):
2348 await _send_login_page(send, error="Password login is disabled on this server.", status=403)
2349 return
2350 if _current_identity_session(headers) is not None:
2351 await _send_redirect(send, _safe_next_path(query.get("next")))
2352 return
2353 error = None
2354 notice = None
2355 if query.get("error") == "locked":
2356 error = LOGIN_LOCKED_MESSAGE
2357 elif query.get("error"):
2358 error = "Invalid email or password."
2359 elif query.get("reset"):
2360 notice = "Your password was changed. Sign in with the new one."
2361 elif query.get("verified"):
2362 notice = "Your email address is confirmed. Sign in to continue."
2363 await _send_login_page(send, error=error, notice=notice, next_path=_safe_next_path(query.get("next")))
2364 return
2365
2366 if method != "POST":
2367 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2368 return
2369
2370 if not _env_enabled(PASSWORD_LOGIN_ENV):
2371 await _send_json(
2372 send,
2373 {
2374 "status": "error",
2375 "error": f"Password login is disabled. Set {PASSWORD_LOGIN_ENV}=true.",
2376 },
2377 status=403,
2378 )
2379 return
2380
2381 form = _parse_form_body(body, headers)
2382 if form is None:
2383 await _send_json(
2384 send,
2385 {
2386 "status": "error",
2387 "error": "Login form must be application/x-www-form-urlencoded; JSON clients should use POST /identity/session.",
2388 },
2389 status=400,
2390 )
2391 return
2392
2393 next_path = _safe_next_path(form.get("next"))
2394 email = (form.get("email") or "").strip()
2395 password = form.get("password") or ""
2396 failure_location = f"{http_api_contract.LOGIN_PATH}?error=1"
2397 if next_path != "/":
2398 failure_location += f"&next={urllib.parse.quote(next_path)}"
2399
2400 if not email or not password:
2401 await _send_redirect(send, failure_location)
2402 return
2403
2404 if _login_locked(email):
2405 _append_ops_auth_event("login_locked", identifier=email, method="password_form")
2406 locked_location = f"{http_api_contract.LOGIN_PATH}?error=locked"
2407 if next_path != "/":
2408 locked_location += f"&next={urllib.parse.quote(next_path)}"
2409 await _send_redirect(send, locked_location)
2410 return
2411
2412 login = {"user_id": None, "email": email, "password": password}
2413 user = _password_login_user(login)
2414 lookup_user_id = user["user_id"] if user is not None else "__unknown_password_login__"
2415 verified = object_credentials.verify_password(lookup_user_id, password, base_dir=_data_dir())
2416
2417 if user is None or not verified:
2418 _append_ops_auth_event("login_failed", identifier=email, method="password_form")
2419 await asyncio.sleep(PASSWORD_LOGIN_FAILURE_DELAY_SECONDS)
2420 await _send_redirect(send, failure_location)
2421 return
2422
2423 try:
2424 result = object_identity.create_session(
2425 {"user_id": user["user_id"], "label": "browser login"},
2426 base_dir=_data_dir(),
2427 require_known_user=True,
2428 )
2429 except ValueError:
2430 _append_ops_auth_event("login_failed", identifier=email, method="password_form")
2431 await asyncio.sleep(PASSWORD_LOGIN_FAILURE_DELAY_SECONDS)
2432 await _send_redirect(send, failure_location)
2433 return
2434
2435 _append_ops_auth_event(
2436 "login_succeeded",
2437 identifier=email,
2438 user_id=user["user_id"],
2439 method="password_form",
2440 label="browser login",
2441 )
2442 await _send_redirect(
2443 send,
2444 next_path if next_path != "/" else _landing_path(),
2445 extra_headers=[
2446 _session_cookie_header(
2447 result["token"],
2448 max_age=object_identity.DEFAULT_SESSION_TTL_SECONDS,
2449 )
2450 ],
2451 )
2452
2453
2454def _landing_path_blockers() -> list[str]:
2455 value = (os.environ.get(LANDING_PATH_ENV) or "").strip()
2456 if value and _safe_next_path(value) != value:
2457 return [f"{LANDING_PATH_ENV} must be a path on this site, starting with a single /; it is ignored and the homepage is used."]
2458 return []
2459
2460
2461def _signup_blockers() -> list[str]:
2462 try:
2463 policy = object_permission_store.load_policy(_data_dir())
2464 except (OSError, ValueError):
2465 return ["The permission policy could not be read."]
2466 return _landing_path_blockers() + object_signup.signup_blockers(
2467 policy=policy,
2468 enforcement_enabled=_permission_enforcement_enabled(),
2469 password_login_enabled=_env_enabled(PASSWORD_LOGIN_ENV),
2470 base_dir=_data_dir(),
2471 )
2472
2473
2474def _password_reset_blockers() -> list[str]:
2475 return object_signup.reset_blockers(
2476 password_login_enabled=_env_enabled(PASSWORD_LOGIN_ENV),
2477 base_dir=_data_dir(),
2478 )
2479
2480
2481def _signup_available() -> bool:
2482 return object_signup.env_enabled(object_signup.SIGNUP_ENV) and not _signup_blockers()
2483
2484
2485def _password_reset_available() -> bool:
2486 return object_signup.env_enabled(object_signup.PASSWORD_RESET_ENV) and not _password_reset_blockers()
2487
2488
2489def _signup_rate_limited(identity: str, limit: int) -> bool:
2490 """One hourly bucket per identity; fails closed, as a public write should."""
2491 result = object_rate_limit.check_rate_limit(
2492 directory=_rate_limit_dir(),
2493 identity=identity,
2494 limit=limit,
2495 window_seconds=3600,
2496 fail_closed=True,
2497 )
2498 return not result.allowed
2499
2500
2501def _email_address_rate_limited(email: str) -> bool:
2502 return _signup_rate_limited(f"signup-email:{email.strip().casefold()}", EMAILS_PER_HOUR_PER_ADDRESS)
2503
2504
2505def _send_verification_link(user: Mapping[str, Any]) -> bool:
2506 """Email a fresh confirmation link; False when email can't go out or the address hit its hourly limit."""
2507 email = user.get("email") or ""
2508 base_url = object_signup.public_url()
2509 if not email or base_url is None or object_signup.email_blockers(base_dir=_data_dir()):
2510 return False
2511 if _email_address_rate_limited(email):
2512 return False
2513 token = object_signup.issue_token(object_signup.VERIFY_EMAIL, user["user_id"], email, base_dir=_data_dir())
2514 object_signup.send(email, object_signup.verification_email(base_url, token), base_dir=_data_dir())
2515 return True
2516
2517
2518def _same_origin_form(headers: dict[str, str]) -> bool:
2519 """These forms sign a browser in or change a password, so a POST from
2520 another site is refused whether or not a session cookie is present."""
2521 return _cookie_request_origin_allowed(headers)
2522
2523
2524async def _send_signup_unavailable(send) -> None:
2525 inner = """<div class="panel"><h1>Sign up</h1>
2526<p>New accounts can't be created on this server.</p>
2527<p class="links"><a href="/login">Sign in</a></p></div>"""
2528 await _send_auth_page(send, "Sign up", inner, status=403)
2529
2530
2531async def _send_signup_page(send, *, error: str | None = None, email: str = "", status: int = 200) -> None:
2532 inner = f"""<form method="post" action="{html.escape(http_api_contract.SIGNUP_PATH, quote=True)}">
2533<h1>Create an account</h1>
2534{_message_block(error)}
2535<label for="email">Email</label>
2536<input id="email" name="email" type="email" autocomplete="email" required autofocus value="{html.escape(email, quote=True)}">
2537<p>We'll email you a link. You choose your password there, once the link shows the address is yours.</p>
2538<button type="submit">Create account</button>
2539<p class="links"><a href="{html.escape(http_api_contract.LOGIN_PATH, quote=True)}">Already have an account? Sign in</a></p>
2540</form>"""
2541 await _send_auth_page(send, "Create an account", inner, status=status)
2542
2543
2544async def _send_check_email_page(send, title: str, message: str) -> None:
2545 inner = f"""<div class="panel"><h1>{html.escape(title)}</h1>
2546<p>{html.escape(message)}</p>
2547<p>Nothing there? Check your spam folder. The link works once.</p>
2548<p class="links"><a href="{html.escape(http_api_contract.LOGIN_PATH, quote=True)}">Back to sign in</a></p></div>"""
2549 await _send_auth_page(send, title, inner)
2550
2551
2552async def _handle_signup(scope, send, method: str, query: dict[str, str], body: bytes, headers: dict[str, str]) -> None:
2553 if method not in ("GET", "POST"):
2554 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2555 return
2556 if not _signup_available():
2557 await _send_signup_unavailable(send)
2558 return
2559 if method == "GET":
2560 if query.get("sent"):
2561 await _send_check_email_page(
2562 send,
2563 "Check your email",
2564 "We've sent a link to the address you gave. Open it to confirm the address and choose your password.",
2565 )
2566 return
2567 await _send_signup_page(send)
2568 return
2569
2570 form = _parse_form_body(body, headers)
2571 if form is None or not _same_origin_form(headers):
2572 await _send_signup_page(send, error="That form couldn't be read. Please try again.", status=400)
2573 return
2574 email = (form.get("email") or "").strip()
2575
2576 if _signup_rate_limited(f"signup-ip:{_client_ip(scope, headers)}", SIGNUP_ATTEMPTS_PER_HOUR_PER_IP):
2577 await _send_signup_page(send, error="Too many sign-ups from here. Try again in an hour.", email=email, status=429)
2578 return
2579 try:
2580 result = object_signup.register(email, base_dir=_data_dir())
2581 except object_signup.SignupError as exc:
2582 await _send_signup_page(send, error=str(exc), email=email, status=400)
2583 return
2584
2585 user = result["user"]
2586 _append_ops_auth_event(f"signup_{result['outcome']}", identifier=email, user_id=user["user_id"], method="signup_form")
2587 # every outcome looks the same from here; only the mailbox learns which it was
2588 if result["outcome"] in ("created", "pending"):
2589 _send_verification_link(user)
2590 elif not _email_address_rate_limited(email):
2591 object_signup.send(
2592 user["email"],
2593 object_signup.already_registered_email(object_signup.public_url() or "", _password_reset_available()),
2594 base_dir=_data_dir(),
2595 )
2596 await _send_redirect(send, f"{http_api_contract.SIGNUP_PATH}?sent=1")
2597
2598
2599async def _send_link_problem_page(
2600 send, title: str, message: str, retry_path: str, retry_label: str, *, also: tuple[str, str] | None = None
2601) -> None:
2602 also_link = f' <a href="{html.escape(also[0], quote=True)}">{html.escape(also[1])}</a>' if also else ""
2603 inner = f"""<div class="panel"><h1>{html.escape(title)}</h1>
2604<p class="error">{html.escape(message)}</p>
2605<p class="links"><a href="{html.escape(retry_path, quote=True)}">{html.escape(retry_label)}</a>{also_link}</p></div>"""
2606 await _send_auth_page(send, title, inner, status=400)
2607
2608
2609async def _send_confirm_page(send, token: str, *, error: str | None = None, display_name: str = "", status: int = 200) -> None:
2610 inner = f"""<form method="post" action="{html.escape(http_api_contract.VERIFY_EMAIL_PATH, quote=True)}">
2611<h1>Confirm your email</h1>
2612{_message_block(error)}
2613<p>One more step: choose a password to finish creating your account.</p>
2614<input type="hidden" name="token" value="{html.escape(token, quote=True)}">
2615<label for="display_name">Name <small>(optional)</small></label>
2616<input id="display_name" name="display_name" type="text" autocomplete="name" maxlength="{object_signup.MAX_DISPLAY_NAME_LENGTH}" value="{html.escape(display_name, quote=True)}">
2617<label for="password">Password</label>
2618<input id="password" name="password" type="password" autocomplete="new-password" minlength="{object_credentials.MIN_PASSWORD_LENGTH}" required autofocus>
2619<button type="submit">Confirm my email</button>
2620</form>"""
2621 await _send_auth_page(send, "Confirm your email", inner, status=status)
2622
2623
2624async def _send_confirm_link_problem(send, message: str) -> None:
2625 await _send_link_problem_page(
2626 send, "Confirm your email", message,
2627 http_api_contract.SIGNUP_PATH, "Sign up again for a new link",
2628 also=(http_api_contract.LOGIN_PATH, "Sign in"),
2629 )
2630
2631
2632async def _handle_verify_email(send, method: str, query: dict[str, str], body: bytes, headers: dict[str, str]) -> None:
2633 expired = "This link has expired or was already used. If you haven't finished creating your account, sign up again and we'll send a new link."
2634 if method == "GET":
2635 # the link only shows the form: mail scanners open links on their own,
2636 # and must not use the token up (or sign anyone in)
2637 token = query.get("token") or ""
2638 if object_signup.peek_token(token, object_signup.VERIFY_EMAIL, base_dir=_data_dir()) is None:
2639 await _send_confirm_link_problem(send, expired)
2640 return
2641 await _send_confirm_page(send, token)
2642 return
2643 if method != "POST":
2644 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2645 return
2646
2647 form = _parse_form_body(body, headers)
2648 if form is None or not _same_origin_form(headers):
2649 await _send_confirm_link_problem(send, "That form couldn't be read. Open the link from the email again.")
2650 return
2651 token = form.get("token") or ""
2652 try:
2653 user = object_signup.confirm_signup(token, form.get("password"), form.get("display_name"), base_dir=_data_dir())
2654 except object_signup.SignupError as exc:
2655 await _send_confirm_page(send, token, error=str(exc), display_name=form.get("display_name") or "", status=400)
2656 return
2657 if user is None:
2658 await _send_confirm_link_problem(send, expired)
2659 return
2660 _append_ops_auth_event("email_verified", identifier=user.get("email"), user_id=user["user_id"], method="verify_link")
2661 try:
2662 result = object_identity.create_session(
2663 {"user_id": user["user_id"], "label": "email verified"},
2664 base_dir=_data_dir(),
2665 require_known_user=True,
2666 )
2667 except ValueError:
2668 await _send_redirect(send, f"{http_api_contract.LOGIN_PATH}?verified=1")
2669 return
2670 _append_ops_auth_event("session_minted", identifier=user.get("email"), user_id=user["user_id"], method="verify_link", label="email verified")
2671 await _send_redirect(
2672 send,
2673 _landing_path(),
2674 extra_headers=[_session_cookie_header(result["token"], max_age=object_identity.DEFAULT_SESSION_TTL_SECONDS)],
2675 )
2676
2677
2678async def _send_reset_request_page(send, *, error: str | None = None, email: str = "", status: int = 200) -> None:
2679 inner = f"""<form method="post" action="{html.escape(http_api_contract.PASSWORD_RESET_PATH, quote=True)}">
2680<h1>Reset your password</h1>
2681{_message_block(error)}
2682<p>Enter your account's email address and we'll send you a link to choose a new password.</p>
2683<label for="email">Email</label>
2684<input id="email" name="email" type="email" autocomplete="email" required autofocus value="{html.escape(email, quote=True)}">
2685<button type="submit">Send the link</button>
2686<p class="links"><a href="{html.escape(http_api_contract.LOGIN_PATH, quote=True)}">Back to sign in</a></p>
2687</form>"""
2688 await _send_auth_page(send, "Reset your password", inner, status=status)
2689
2690
2691async def _handle_password_reset(scope, send, method: str, query: dict[str, str], body: bytes, headers: dict[str, str]) -> None:
2692 if method not in ("GET", "POST"):
2693 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2694 return
2695 if not _password_reset_available():
2696 inner = """<div class="panel"><h1>Reset your password</h1>
2697<p>Passwords can't be reset by email on this server. Ask the person who runs it.</p>
2698<p class="links"><a href="/login">Sign in</a></p></div>"""
2699 await _send_auth_page(send, "Reset your password", inner, status=403)
2700 return
2701 if method == "GET":
2702 if query.get("sent"):
2703 await _send_check_email_page(
2704 send,
2705 "Check your email",
2706 "If that address has an account here, we've sent it a link to choose a new password. The link works for an hour.",
2707 )
2708 return
2709 await _send_reset_request_page(send)
2710 return
2711
2712 form = _parse_form_body(body, headers)
2713 if form is None or not _same_origin_form(headers):
2714 await _send_reset_request_page(send, error="That form couldn't be read. Please try again.", status=400)
2715 return
2716 email = (form.get("email") or "").strip()
2717 if _signup_rate_limited(f"reset-ip:{_client_ip(scope, headers)}", RESET_ATTEMPTS_PER_HOUR_PER_IP):
2718 await _send_reset_request_page(send, error="Too many requests from here. Try again in an hour.", email=email, status=429)
2719 return
2720 try:
2721 object_signup.normalize_email(email)
2722 except object_signup.SignupError as exc:
2723 await _send_reset_request_page(send, error=str(exc), email=email, status=400)
2724 return
2725
2726 user = object_signup.reset_candidate(email, base_dir=_data_dir())
2727 _append_ops_auth_event("password_reset_requested", identifier=email, user_id=user["user_id"] if user else None, method="reset_form")
2728 # the same answer whether or not the address has an account
2729 if user is not None and not _email_address_rate_limited(email):
2730 token = object_signup.issue_token(object_signup.PASSWORD_RESET, user["user_id"], user["email"], base_dir=_data_dir())
2731 object_signup.send(user["email"], object_signup.reset_email(object_signup.public_url() or "", token), base_dir=_data_dir())
2732 await _send_redirect(send, f"{http_api_contract.PASSWORD_RESET_PATH}?sent=1")
2733
2734
2735async def _send_new_password_page(send, token: str, *, error: str | None = None, status: int = 200) -> None:
2736 inner = f"""<form method="post" action="{html.escape(http_api_contract.PASSWORD_RESET_CONFIRM_PATH, quote=True)}">
2737<h1>Choose a new password</h1>
2738{_message_block(error)}
2739<input type="hidden" name="token" value="{html.escape(token, quote=True)}">
2740<label for="password">New password</label>
2741<input id="password" name="password" type="password" autocomplete="new-password" minlength="{object_credentials.MIN_PASSWORD_LENGTH}" required autofocus>
2742<button type="submit">Save the new password</button>
2743<p>You'll be signed out everywhere else.</p>
2744</form>"""
2745 await _send_auth_page(send, "Choose a new password", inner, status=status)
2746
2747
2748async def _handle_password_reset_confirm(send, method: str, query: dict[str, str], body: bytes, headers: dict[str, str]) -> None:
2749 expired = "This link has expired or was already used. Ask for a new one."
2750 if method == "GET":
2751 token = query.get("token") or ""
2752 if object_signup.peek_token(token, object_signup.PASSWORD_RESET, base_dir=_data_dir()) is None:
2753 await _send_link_problem_page(send, "Choose a new password", expired, http_api_contract.PASSWORD_RESET_PATH, "Send a new link")
2754 return
2755 await _send_new_password_page(send, token)
2756 return
2757 if method != "POST":
2758 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2759 return
2760
2761 form = _parse_form_body(body, headers)
2762 if form is None or not _same_origin_form(headers):
2763 await _send_link_problem_page(send, "Choose a new password", "That form couldn't be read. Open the link from the email again.", http_api_contract.PASSWORD_RESET_PATH, "Send a new link")
2764 return
2765 token = form.get("token") or ""
2766 try:
2767 user = object_signup.reset_password(token, form.get("password"), base_dir=_data_dir())
2768 except object_signup.SignupError as exc:
2769 await _send_new_password_page(send, token, error=str(exc), status=400)
2770 return
2771 if user is None:
2772 await _send_link_problem_page(send, "Choose a new password", expired, http_api_contract.PASSWORD_RESET_PATH, "Send a new link")
2773 return
2774 _append_ops_auth_event("password_reset", identifier=user.get("email"), user_id=user["user_id"], method="reset_link")
2775 await _send_redirect(
2776 send,
2777 f"{http_api_contract.LOGIN_PATH}?reset=1",
2778 extra_headers=[_session_cookie_header("", max_age=0)],
2779 )
2780
2781
2782async def _handle_logout(send, method: str, headers: dict[str, str]) -> None:
2783 if method != "POST":
2784 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
2785 return
2786
2787 session = _current_identity_session(headers)
2788 if session is not None:
2789 try:
2790 object_identity.revoke_session(session.session_id, base_dir=_data_dir())
2791 except (OSError, ValueError, LookupError):
2792 pass
2793 _append_ops_auth_event("logout", user_id=session.user_id)
2794
2795 await _send_redirect(
2796 send,
2797 http_api_contract.LOGIN_PATH,
2798 extra_headers=[_session_cookie_header("", max_age=0)],
2799 )
2800
2801
2802def _parse_form_body(body: bytes, headers: dict[str, str]) -> dict[str, str] | None:
2803 content_type = headers.get("content-type", "").split(";")[0].strip().lower()
2804 if content_type and content_type != "application/x-www-form-urlencoded":
2805 return None
2806 try:
2807 pairs = urllib.parse.parse_qsl(body.decode("utf-8"), keep_blank_values=True)
2808 except (UnicodeDecodeError, ValueError):
2809 return None
2810 return {name: value for name, value in pairs}
2811
2812
2813def _safe_next_path(value: str | None) -> str:
2814 candidate = (value or "").strip()
2815 if (
2816 not candidate.startswith("/")
2817 or candidate.startswith("//")
2818 or "\\" in candidate
2819 or any(ord(char) < 32 for char in candidate)
2820 ):
2821 return "/"
2822 return candidate
2823
2824
2825def _landing_path() -> str:
2826 """Where a browser goes after confirming an email address: the site's own page for new accounts
2827 (DBBASIC_AUTH_LANDING_PATH, a local path), else the homepage."""
2828 return _safe_next_path(os.environ.get(LANDING_PATH_ENV))
2829
2830
2831def _session_cookie_header(token: str, *, max_age: int) -> tuple[str, str]:
2832 attributes = [
2833 f"{SESSION_COOKIE_NAME}={token}",
2834 "Path=/",
2835 "HttpOnly",
2836 "SameSite=Lax",
2837 f"Max-Age={max_age}",
2838 ]
2839 if _cookie_secure_enabled():
2840 attributes.append("Secure")
2841 return ("set-cookie", "; ".join(attributes))
2842
2843
2844def _cookie_secure_enabled() -> bool:
2845 value = os.environ.get(COOKIE_SECURE_ENV, "").strip().lower()
2846 if not value:
2847 return True
2848 return value in TRUE_VALUES
2849
2850
2851async def _send_redirect(
2852 send,
2853 location: str,
2854 *,
2855 extra_headers: list[tuple[str, str]] | None = None,
2856) -> None:
2857 headers = [
2858 ("location", location),
2859 ("content-type", "text/html; charset=utf-8"),
2860 ]
2861 if extra_headers:
2862 headers.extend(extra_headers)
2863 body = f'<a href="{html.escape(location, quote=True)}">Continue</a>'.encode("utf-8")
2864 await _send_response(send, status=303, headers=headers, body=body)
2865
2866
2867_AUTH_PAGE_STYLE = """
2868body { font-family: system-ui, sans-serif; background: #f5f5f4; margin: 0;
2869 display: flex; min-height: 100vh; align-items: center; justify-content: center; }
2870form, .panel { background: #fff; border: 1px solid #d6d3d1; border-radius: 8px;
2871 padding: 2rem; width: 20rem; max-width: calc(100vw - 2rem); box-sizing: border-box; }
2872h1 { font-size: 1.1rem; margin: 0 0 1rem; }
2873label { display: block; font-size: 0.85rem; margin: 0.75rem 0 0.25rem; }
2874input { width: 100%; box-sizing: border-box; padding: 0.5rem; font-size: 1rem;
2875 border: 1px solid #d6d3d1; border-radius: 4px; }
2876button { margin-top: 1.25rem; width: 100%; padding: 0.6rem; border: 0; font-size: 1rem;
2877 border-radius: 4px; background: #1c1917; color: #fff; cursor: pointer; }
2878p { font-size: 0.9rem; line-height: 1.4; }
2879.error { background: #fef2f2; border: 1px solid #fecaca; color: #991b1b;
2880 border-radius: 4px; padding: 0.5rem; font-size: 0.85rem; }
2881.notice { background: #f0fdf4; border: 1px solid #bbf7d0; color: #166534;
2882 border-radius: 4px; padding: 0.5rem; font-size: 0.85rem; }
2883.links { margin: 1rem 0 0; font-size: 0.85rem; display: flex; flex-wrap: wrap; justify-content: space-between; gap: 0.5rem 1rem; }
2884.links a { white-space: nowrap; }
2885a { color: #1c1917; }
2886"""
2887
2888
2889def _auth_page_html(title: str, inner: str) -> str:
2890 return f"""<!doctype html>
2891<html lang="en">
2892<head>
2893<meta charset="utf-8">
2894<meta name="viewport" content="width=device-width, initial-scale=1">
2895<meta name="referrer" content="strict-origin">
2896<title>{html.escape(title)}</title>
2897<style>{_AUTH_PAGE_STYLE}</style>
2898</head>
2899<body>
2900{inner}
2901</body>
2902</html>"""
2903
2904
2905async def _send_auth_page(send, title: str, inner: str, *, status: int = 200) -> None:
2906 await _send_response(
2907 send,
2908 status=status,
2909 headers=[
2910 ("content-type", "text/html; charset=utf-8"),
2911 ("cache-control", "no-store"),
2912 ],
2913 body=_auth_page_html(title, inner).encode("utf-8"),
2914 )
2915
2916
2917def _message_block(error: str | None = None, notice: str | None = None) -> str:
2918 if error:
2919 return f'<p class="error">{html.escape(error)}</p>'
2920 if notice:
2921 return f'<p class="notice">{html.escape(notice)}</p>'
2922 return ""
2923
2924
2925async def _send_login_page(
2926 send,
2927 *,
2928 error: str | None = None,
2929 notice: str | None = None,
2930 next_path: str = "/",
2931 status: int = 200,
2932) -> None:
2933 links = []
2934 if _signup_available():
2935 links.append(f'<a href="{html.escape(http_api_contract.SIGNUP_PATH, quote=True)}">Create an account</a>')
2936 if _password_reset_available():
2937 links.append(f'<a href="{html.escape(http_api_contract.PASSWORD_RESET_PATH, quote=True)}">Forgot your password?</a>')
2938 links_block = f'<p class="links">{" ".join(links)}</p>' if links else ""
2939 if _signup_available():
2940 links_block += "<p>Just signed up? Open the link we emailed you: you choose your password there.</p>"
2941 inner = f"""<form method="post" action="{html.escape(http_api_contract.LOGIN_PATH, quote=True)}">
2942<h1>Sign in</h1>
2943{_message_block(error, notice)}
2944<label for="email">Email</label>
2945<input id="email" name="email" type="email" autocomplete="username" required autofocus>
2946<label for="password">Password</label>
2947<input id="password" name="password" type="password" autocomplete="current-password" required>
2948<input type="hidden" name="next" value="{html.escape(next_path, quote=True)}">
2949<button type="submit">Sign in</button>
2950{links_block}
2951</form>"""
2952 await _send_auth_page(send, "Sign in", inner, status=status)
2953
2954
2955def _password_login_user(login: Mapping[str, Any]) -> dict[str, Any] | None:
2956 if login["user_id"] is not None:
2957 if not isinstance(login["user_id"], str):
2958 return None
2959 try:
2960 user = object_identity.get_user(login["user_id"], base_dir=_data_dir())
2961 except (ValueError, LookupError):
2962 return None
2963 return user if user.get("status") == "active" else None
2964
2965 email = login["email"]
2966 if not isinstance(email, str) or not email.strip():
2967 return None
2968 normalized_email = email.strip().casefold()
2969 try:
2970 users = object_identity.list_users(base_dir=_data_dir())
2971 except ValueError:
2972 return None
2973 matches = [
2974 user
2975 for user in users
2976 if (user.get("email") or "").casefold() == normalized_email
2977 and user.get("status") == "active"
2978 ]
2979 if len(matches) != 1:
2980 return None
2981 return matches[0]
2982
2983
2984async def _send_rate_limit_if_needed(
2985 scope: dict[str, Any],
2986 headers: dict[str, str],
2987 send,
2988) -> bool:
2989 limit = _rate_limit_requests()
2990 if limit <= 0:
2991 return False
2992
2993 # This is the GLOBAL per-request DoS limiter, so it stays fail-open on
2994 # storage failure (fail_closed=False): a broken ratelimit dir must not
2995 # take the whole site down. But the degradation is no longer silent --
2996 # check_rate_limit flags it and we log it, because an invisibly-degraded
2997 # limiter is a security hole. Public-write surfaces get their own check
2998 # with fail_closed=True (see object_rate_limit.check_rate_limit).
2999 result = object_rate_limit.check_rate_limit(
3000 directory=_rate_limit_dir(),
3001 identity=_rate_limit_identity(scope, headers),
3002 limit=limit,
3003 window_seconds=_rate_limit_window_seconds(),
3004 )
3005
3006 if result.degraded:
3007 try:
3008 object_logs.append_object_log(
3009 "object_rate_limit",
3010 "WARNING",
3011 "rate limiter degraded (storage unavailable); "
3012 f"failing {'open' if result.allowed else 'closed'} for this request",
3013 base_dir=_data_dir(),
3014 )
3015 except Exception:
3016 pass
3017
3018 if result.allowed:
3019 return False
3020
3021 await _send_rate_limit_error(send, result)
3022 return True
3023
3024
3025def _health_payload(*, include_metrics: bool) -> dict[str, Any]:
3026 metrics = _metrics.snapshot()
3027 storage_check = _storage_check()
3028 status = "ok" if storage_check["status"] == "ok" else "degraded"
3029 payload: dict[str, Any] = {
3030 "status": status,
3031 "timestamp": _utc_timestamp(),
3032 "version": _package_version(),
3033 "station_id": _station_id(),
3034 "pid": os.getpid(),
3035 "threads": _thread_count(),
3036 "uptime": metrics["uptime_human"],
3037 "uptime_seconds": metrics["uptime_seconds"],
3038 "requests": metrics["total_requests"],
3039 "errors": metrics["total_errors"],
3040 "rps": metrics["requests_per_second"],
3041 "error_rate": metrics["error_rate"],
3042 "response_time_ms": metrics["response_time_ms"],
3043 "objects": {
3044 "count": _object_count(),
3045 },
3046 "capacity": {
3047 "requests": _request_limiter.snapshot(_max_concurrent_requests()),
3048 "object_executions": _execution_limiter.snapshot(_max_concurrent_executions()),
3049 },
3050 "config": {
3051 "source_writes_enabled": _env_enabled(SOURCE_WRITES_ENV),
3052 "file_writes_enabled": _env_enabled(FILE_WRITES_ENV),
3053 "max_request_bytes": _max_request_bytes(),
3054 "max_object_file_bytes": _max_object_file_bytes(),
3055 "max_concurrent_requests": _max_concurrent_requests(),
3056 "max_concurrent_executions": _max_concurrent_executions(),
3057 "rate_limit_requests": _rate_limit_requests(),
3058 "rate_limit_window_seconds": _rate_limit_window_seconds(),
3059 "rate_limit_trust_proxy_headers": _env_enabled(RATE_LIMIT_TRUST_PROXY_HEADERS_ENV),
3060 "object_timeout_seconds": _object_timeout_seconds(),
3061 "trusted_in_process_objects": sorted(_trusted_in_process_object_ids()),
3062 "permission_enforcement_enabled": _permission_enforcement_enabled(),
3063 "permission_enforcement_requested": _permission_enforcement_requested(),
3064 "permission_enforcement_blocked": _permission_enforcement_blocked(),
3065 "permission_allow_unready_enforcement": _permission_unready_enforcement_allowed(),
3066 "permission_audit_enabled": _permission_audit_enabled(),
3067 "permission_trust_headers": _env_enabled(PERMISSION_TRUST_HEADERS_ENV),
3068 "require_known_identity_users": _env_enabled(REQUIRE_KNOWN_IDENTITY_USERS_ENV),
3069 "event_keep_count": _event_keep_count(),
3070 "event_keep_seconds": _event_keep_seconds(),
3071 },
3072 "checks": {
3073 "storage": storage_check,
3074 },
3075 "system": _system_snapshot(),
3076 }
3077
3078 if include_metrics:
3079 payload["metrics"] = metrics
3080
3081 return payload
3082
3083
3084async def _handle_admin_status(
3085 send,
3086 method: str,
3087 headers: dict[str, str],
3088) -> None:
3089 if method != "GET":
3090 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3091 return
3092
3093 gate_error = _admin_token_gate_error(
3094 headers,
3095 f"Admin status requires {ADMIN_TOKEN_ENV}.",
3096 )
3097 if gate_error is not None:
3098 status, message = gate_error
3099 await _send_json(send, {"status": "error", "error": message}, status=status)
3100 return
3101
3102 try:
3103 payload = _admin_status_payload()
3104 except object_packages.InvalidPackageManifestError as exc:
3105 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
3106 return
3107 except OSError as exc:
3108 await _send_json(
3109 send,
3110 {"status": "error", "error": f"Could not build admin status: {exc}"},
3111 status=500,
3112 )
3113 return
3114
3115 status_code = 503 if payload["status"] == "degraded" else 200
3116 await _send_json(send, payload, status=status_code)
3117
3118
3119async def _handle_admin_storage(
3120 send,
3121 method: str,
3122 headers: dict[str, str],
3123) -> None:
3124 """GET /admin/storage: compaction-observability stats for every
3125 append-mode collection (docs/storage-modes.md "Compaction").
3126
3127 Must stay fast regardless of collection size or cache/sidecar state --
3128 passes allow_fold=False so no single collection's stats call can turn
3129 this into an O(file) scan; a collection whose cheap sources (warm
3130 _RECORDS_CACHE, coherent id->offset sidecar) can't answer comes back
3131 as an "estimated" entry (file_bytes only) instead of triggering a full
3132 fold. See object_records.append_collection_stats.
3133 """
3134 if method != "GET":
3135 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3136 return
3137
3138 gate_error = _admin_token_gate_error(
3139 headers,
3140 f"Admin storage requires {ADMIN_TOKEN_ENV}.",
3141 )
3142 if gate_error is not None:
3143 status, message = gate_error
3144 await _send_json(send, {"status": "error", "error": message}, status=status)
3145 return
3146
3147 append_collections = object_records.list_append_collection_stats(
3148 base_dir=_data_dir(),
3149 allow_fold=False,
3150 )
3151 await _send_json(
3152 send,
3153 {"status": "ok", "append_collections": append_collections},
3154 )
3155
3156
3157async def _handle_admin_collection_compact(
3158 send,
3159 collection: str,
3160 headers: dict[str, str],
3161) -> None:
3162 """POST /admin/collections/{collection}/compact: run
3163 object_records.compact_collection under the same gates that protect
3164 other mutating admin record routes (admin token, then the same
3165 collection-level write-permission check _record_write_denied_before_
3166 lookup applies to record create/update/delete -- there is no single
3167 record here, so the collection-level check is the whole check, same
3168 as it is for those routes before their own per-record lookup runs).
3169
3170 404 for an unknown collection, 400 for a collection not currently in
3171 append storage mode (nothing to compact -- compact_collection itself
3172 tolerates being called on a classic collection as a no-op, but this
3173 endpoint reports that as a client error instead of a silent 200, so
3174 "I asked to compact X" never comes back "ok" for a collection that
3175 was never compactable to begin with).
3176 """
3177 if await _record_write_denied_before_lookup(
3178 send,
3179 headers,
3180 object_permissions.UPDATE,
3181 collection=collection,
3182 ):
3183 return
3184
3185 try:
3186 mode_stats = object_records.append_collection_stats(collection, base_dir=_data_dir())
3187 except object_collections.InvalidCollectionNameError as exc:
3188 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3189 return
3190 except object_collections.CollectionNotFoundError as exc:
3191 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
3192 return
3193
3194 if mode_stats is None:
3195 await _send_json(
3196 send,
3197 {
3198 "status": "error",
3199 "error": f"Collection is not in append storage mode: {collection}",
3200 },
3201 status=400,
3202 )
3203 return
3204
3205 started_at = time.perf_counter()
3206 try:
3207 summary = object_records.compact_collection(collection, base_dir=_data_dir())
3208 except OSError as exc:
3209 await _send_json(
3210 send,
3211 {"status": "error", "error": f"Could not compact collection: {exc}"},
3212 status=500,
3213 )
3214 return
3215 duration_ms = (time.perf_counter() - started_at) * 1000
3216
3217 await _send_json(
3218 send,
3219 {
3220 "status": "ok",
3221 "collection": collection,
3222 **summary,
3223 "duration_ms": duration_ms,
3224 },
3225 )
3226
3227
3228async def _handle_admin_changes(
3229 send,
3230 method: str,
3231 query: dict[str, str],
3232 headers: dict[str, str],
3233) -> None:
3234 if method != "GET":
3235 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3236 return
3237
3238 gate_error = _admin_token_gate_error(
3239 headers,
3240 f"Admin change history requires {ADMIN_TOKEN_ENV}.",
3241 )
3242 if gate_error is not None:
3243 status, message = gate_error
3244 await _send_json(send, {"status": "error", "error": message}, status=status)
3245 return
3246
3247 try:
3248 limit = _query_int(
3249 query,
3250 "limit",
3251 default=100,
3252 minimum=1,
3253 maximum=object_source_changes.MAX_CHANGE_LIMIT,
3254 )
3255 offset = _query_int(
3256 query,
3257 "offset",
3258 default=0,
3259 minimum=0,
3260 maximum=object_source_changes.MAX_CHANGE_LIMIT,
3261 )
3262 payload = _admin_changes_payload(query, limit=limit, offset=offset)
3263 except ValueError as exc:
3264 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3265 return
3266 except (InvalidObjectIdError, object_collections.InvalidCollectionNameError) as exc:
3267 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3268 return
3269 except (object_records.InvalidRecordIdError, object_packages.InvalidPackageIdError) as exc:
3270 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3271 return
3272 except object_file_changes.InvalidFileChangeError as exc:
3273 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3274 return
3275 except OSError as exc:
3276 await _send_json(
3277 send,
3278 {"status": "error", "error": f"Could not list admin changes: {exc}"},
3279 status=500,
3280 )
3281 return
3282
3283 await _send_json(send, {"status": "ok", **payload})
3284
3285
3286async def _handle_admin_objects(
3287 send,
3288 method: str,
3289 body: bytes,
3290 headers: dict[str, str],
3291) -> None:
3292 if method == "POST":
3293 await _handle_objects_post(send, body, headers)
3294 return
3295
3296 if method != "GET":
3297 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3298 return
3299
3300 gate_error = _admin_token_gate_error(
3301 headers,
3302 f"Admin object listing requires {ADMIN_TOKEN_ENV}.",
3303 )
3304 if gate_error is not None:
3305 status, message = gate_error
3306 await _send_json(send, {"status": "error", "error": message}, status=status)
3307 return
3308
3309 await _send_json(send, _list_objects_payload())
3310
3311
3312async def _handle_admin_object(
3313 send,
3314 method: str,
3315 object_id: str,
3316 query: dict[str, str],
3317 body: bytes,
3318 headers: dict[str, str],
3319) -> None:
3320 if method == "PUT" and query.get("source") == "true":
3321 await _handle_object_source_put(send, object_id, body, headers)
3322 return
3323
3324 if method != "GET":
3325 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3326 return
3327
3328 gate_error = _admin_token_gate_error(
3329 headers,
3330 f"Admin object inspection requires {ADMIN_TOKEN_ENV}.",
3331 )
3332 if gate_error is not None:
3333 status, message = gate_error
3334 await _send_json(send, {"status": "error", "error": message}, status=status)
3335 return
3336
3337 if "@" in object_id:
3338 await _send_json(
3339 send,
3340 {"status": "error", "error": "Station routing is not available in admin inspection"},
3341 status=400,
3342 )
3343 return
3344
3345 if query.get("source") == "true":
3346 await _handle_object_source_get(send, object_id)
3347 return
3348
3349 if query.get("state") == "true":
3350 await _handle_object_state_get(send, object_id)
3351 return
3352
3353 if query.get("logs") == "true":
3354 await _handle_object_logs_get(send, object_id, query)
3355 return
3356
3357 if query.get("versions") == "true":
3358 await _handle_object_versions_get(send, object_id, query)
3359 return
3360
3361 if "version" in query:
3362 await _handle_object_version_get(send, object_id, query)
3363 return
3364
3365 if query.get("source_changes") == "true":
3366 await _handle_object_source_changes_get(send, object_id, query)
3367 return
3368
3369 if query.get("changes") == "true":
3370 await _handle_object_changes_get(send, object_id, query)
3371 return
3372
3373 if query.get("files") == "true":
3374 await _handle_object_files_get(send, object_id)
3375 return
3376
3377 if "file" in query:
3378 await _handle_object_file_get(send, object_id, query)
3379 return
3380
3381 if query.get("metadata") == "true" or query.get("format") == "json" or not query:
3382 await _handle_object_metadata_get(send, object_id)
3383 return
3384
3385 await _send_json(
3386 send,
3387 {
3388 "status": "error",
3389 "error": "Unsupported admin object inspection query",
3390 "allowed_queries": [
3391 "metadata=true",
3392 "source=true",
3393 "state=true",
3394 "logs=true",
3395 "versions=true",
3396 "version=<id>",
3397 "source_changes=true",
3398 "changes=true",
3399 "files=true",
3400 "file=<name>",
3401 ],
3402 },
3403 status=400,
3404 )
3405
3406
3407async def _handle_admin_object_execute(
3408 send,
3409 method: str,
3410 object_id: str,
3411 body: bytes,
3412 headers: dict[str, str],
3413) -> None:
3414 if method != "POST":
3415 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3416 return
3417
3418 gate_error = _admin_token_gate_error(
3419 headers,
3420 f"Admin object execution requires {ADMIN_TOKEN_ENV}.",
3421 )
3422 if gate_error is not None:
3423 status, message = gate_error
3424 await _send_json(send, {"status": "error", "error": message}, status=status)
3425 return
3426
3427 if "@" in object_id:
3428 await _send_json(
3429 send,
3430 {"status": "error", "error": "Station routing is not available in admin execution"},
3431 status=400,
3432 )
3433 return
3434
3435 try:
3436 payload = _parse_json_body(body)
3437 execute_method = _admin_execute_method(payload)
3438 execute_payload = _admin_execute_payload(payload)
3439 except ValueError as exc:
3440 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3441 return
3442
3443 permission_action = object_permissions.EXECUTE
3444 if execute_method == "PUT":
3445 permission_action = object_permissions.UPDATE
3446 elif execute_method == "DELETE":
3447 permission_action = object_permissions.DELETE
3448
3449 await _execute_object_method(
3450 send,
3451 object_id,
3452 execute_method,
3453 execute_payload,
3454 headers,
3455 permission_action=permission_action,
3456 )
3457
3458
3459async def _handle_admin_object_override(
3460 send,
3461 method: str,
3462 object_id: str,
3463 headers: dict[str, str],
3464) -> None:
3465 """Create or remove an override that shadows a package object by id.
3466
3467 Overrides are the conflict-free customization path (Rule 2 in
3468 docs/upgrade-and-customization.md): creating an override here copies the
3469 *current package* source into the override root so execution and source
3470 reads/writes resolve to the override from now on, while install/upgrade
3471 logic keeps operating on the pristine package copy (see
3472 get_base_object_roots()). This endpoint requires DBBASIC_OVERRIDES_DIR to
3473 be configured; when it is unset the whole override subsystem is inert.
3474 """
3475 if method not in ("POST", "DELETE"):
3476 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3477 return
3478
3479 # Creating/removing an override mutates what a source read/write and
3480 # execution resolve to, so it is gated exactly like a direct source
3481 # write (admin token + DBBASIC_ENABLE_SOURCE_WRITES).
3482 gate_error = _source_write_gate_error(headers)
3483 if gate_error is not None:
3484 status, message = gate_error
3485 await _send_json(send, {"status": "error", "error": message}, status=status)
3486 return
3487
3488 if not validate_object_id(object_id):
3489 await _send_json(send, {"status": "error", "error": f"Invalid object id: {object_id}"}, status=400)
3490 return
3491
3492 if get_override_root() is None:
3493 await _send_json(
3494 send,
3495 {
3496 "status": "error",
3497 "error": f"Overrides are not enabled; set {object_namespace.OVERRIDES_DIR_ENV}",
3498 },
3499 status=400,
3500 )
3501 return
3502
3503 dest = object_namespace.override_path(object_id)
3504 if dest is None:
3505 await _send_json(
3506 send,
3507 {"status": "error", "error": f"Object id does not support overrides: {object_id}"},
3508 status=400,
3509 )
3510 return
3511
3512 if method == "POST":
3513 try:
3514 source = object_source.get_object_source(object_id, get_base_object_roots())
3515 except InvalidObjectIdError as exc:
3516 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3517 return
3518 except object_source.ObjectSourceNotFoundError as exc:
3519 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
3520 return
3521
3522 if dest.exists():
3523 await _send_json(
3524 send,
3525 {"status": "error", "error": f"Override already exists: {object_id}"},
3526 status=409,
3527 )
3528 return
3529
3530 _write_bytes_atomic(dest, source.encode("utf-8"))
3531 await _send_json(
3532 send,
3533 {
3534 "status": "ok",
3535 "object_id": object_id,
3536 "override_path": str(dest),
3537 "created": True,
3538 },
3539 )
3540 return
3541
3542 # DELETE: remove the override so resolution falls back to the package copy.
3543 if not dest.is_file():
3544 await _send_json(
3545 send,
3546 {"status": "error", "error": f"No override exists: {object_id}"},
3547 status=404,
3548 )
3549 return
3550
3551 dest.unlink()
3552 await _send_json(
3553 send,
3554 {
3555 "status": "ok",
3556 "object_id": object_id,
3557 "removed": True,
3558 },
3559 )
3560
3561
3562def _write_bytes_atomic(path: Path, content: bytes) -> None:
3563 path.parent.mkdir(parents=True, exist_ok=True)
3564 tmp_name = ""
3565 try:
3566 with tempfile.NamedTemporaryFile(
3567 "wb",
3568 dir=path.parent,
3569 prefix=f".{path.name}.",
3570 suffix=".tmp",
3571 delete=False,
3572 ) as tmp:
3573 tmp_name = tmp.name
3574 tmp.write(content)
3575 tmp.flush()
3576 os.fsync(tmp.fileno())
3577 os.replace(tmp_name, path)
3578 finally:
3579 if tmp_name:
3580 try:
3581 Path(tmp_name).unlink()
3582 except FileNotFoundError:
3583 pass
3584
3585
3586async def _handle_admin_files(
3587 send,
3588 method: str,
3589 query: dict[str, str],
3590 headers: dict[str, str],
3591) -> None:
3592 if method != "GET":
3593 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3594 return
3595
3596 gate_error = _admin_token_gate_error(
3597 headers,
3598 f"Admin file inspection requires {ADMIN_TOKEN_ENV}.",
3599 )
3600 if gate_error is not None:
3601 status, message = gate_error
3602 await _send_json(send, {"status": "error", "error": message}, status=status)
3603 return
3604
3605 object_id = _optional_query_text(query, "object_id")
3606 if "file" in query:
3607 if object_id is None:
3608 await _send_json(
3609 send,
3610 {"status": "error", "error": "Query parameter 'object_id' is required"},
3611 status=400,
3612 )
3613 return
3614 await _handle_object_file_get(send, object_id, query)
3615 return
3616
3617 try:
3618 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
3619 offset = _query_int(query, "offset", default=0, minimum=0)
3620 if object_id is not None:
3621 _ensure_object_source_exists(object_id)
3622 files = object_files.list_all_object_files(
3623 base_dir=_data_dir(),
3624 object_id=object_id,
3625 )
3626 except ValueError as exc:
3627 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3628 return
3629 except InvalidObjectIdError as exc:
3630 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3631 return
3632 except object_source.ObjectSourceNotFoundError as exc:
3633 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
3634 return
3635 except OSError as exc:
3636 await _send_json(
3637 send,
3638 {"status": "error", "error": f"Could not read object files: {exc}"},
3639 status=500,
3640 )
3641 return
3642
3643 page = files[offset : offset + limit]
3644 await _send_json(
3645 send,
3646 {
3647 "status": "ok",
3648 "files": page,
3649 "count": len(page),
3650 "total": len(files),
3651 },
3652 )
3653
3654
3655async def _handle_admin_object_files(
3656 send,
3657 method: str,
3658 object_id: str,
3659 query: dict[str, str],
3660 body: bytes,
3661 headers: dict[str, str],
3662) -> None:
3663 if method not in {"GET", "POST", "PUT", "DELETE"}:
3664 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3665 return
3666
3667 if "@" in object_id:
3668 await _send_json(
3669 send,
3670 {"status": "error", "error": "Station routing is not available in admin inspection"},
3671 status=400,
3672 )
3673 return
3674
3675 if method in {"POST", "PUT", "DELETE"}:
3676 await _handle_admin_object_file_write(send, method, object_id, query, body, headers)
3677 return
3678
3679 gate_error = _admin_token_gate_error(
3680 headers,
3681 f"Admin file inspection requires {ADMIN_TOKEN_ENV}.",
3682 )
3683 if gate_error is not None:
3684 status, message = gate_error
3685 await _send_json(send, {"status": "error", "error": message}, status=status)
3686 return
3687
3688 if "file" in query:
3689 await _handle_object_file_get(send, object_id, query)
3690 return
3691
3692 await _handle_object_files_get(send, object_id)
3693
3694
3695async def _handle_admin_object_file_write(
3696 send,
3697 method: str,
3698 object_id: str,
3699 query: dict[str, str],
3700 body: bytes,
3701 headers: dict[str, str],
3702) -> None:
3703 gate_error = _file_write_gate_error(headers)
3704 if gate_error is not None:
3705 status, message = gate_error
3706 await _send_json(send, {"status": "error", "error": message}, status=status)
3707 return
3708
3709 if await _send_permission_denied_if_needed(
3710 send,
3711 headers,
3712 object_permissions.FILES,
3713 object_id=object_id,
3714 method=method,
3715 ):
3716 return
3717
3718 try:
3719 _ensure_object_source_exists(object_id)
3720 if method in {"POST", "PUT"}:
3721 filename, content = _file_write_payload(body)
3722 metadata = object_files.write_object_file(
3723 object_id,
3724 filename,
3725 content,
3726 base_dir=_data_dir(),
3727 overwrite=method == "PUT",
3728 max_bytes=_max_object_file_bytes(),
3729 )
3730 operation = "created" if method == "POST" else "updated"
3731 status_code = 201 if method == "POST" else 200
3732 else:
3733 filename = _file_delete_filename(query, body)
3734 metadata = object_files.delete_object_file(
3735 object_id,
3736 filename,
3737 base_dir=_data_dir(),
3738 )
3739 operation = "deleted"
3740 status_code = 200
3741 except object_files.ObjectFileTooLargeError as exc:
3742 await _send_json(send, {"status": "error", "error": str(exc)}, status=413)
3743 return
3744 except ValueError as exc:
3745 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3746 return
3747 except InvalidObjectIdError as exc:
3748 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3749 return
3750 except object_files.InvalidObjectFilenameError as exc:
3751 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3752 return
3753 except object_source.ObjectSourceNotFoundError as exc:
3754 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
3755 return
3756 except object_files.ObjectFileExistsError as exc:
3757 await _send_json(send, {"status": "error", "error": str(exc)}, status=409)
3758 return
3759 except object_files.ObjectFileNotFoundError as exc:
3760 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
3761 return
3762 except OSError as exc:
3763 await _send_json(
3764 send,
3765 {"status": "error", "error": f"Could not write object file: {exc}"},
3766 status=500,
3767 )
3768 return
3769
3770 correlation_id = object_correlation.current_correlation_id()
3771 _append_file_log(object_id, operation=operation, metadata=metadata, method=method)
3772 change = _append_file_change_log(
3773 object_id,
3774 operation=operation,
3775 metadata=metadata,
3776 method=method,
3777 actor=_record_change_actor(headers),
3778 correlation_id=correlation_id,
3779 )
3780 payload = {
3781 "status": "ok",
3782 "message": f"File {operation}: {metadata['name']}",
3783 "object_id": object_id,
3784 "operation": operation,
3785 "file": {"object_id": object_id, **metadata},
3786 "correlation_id": correlation_id,
3787 }
3788 if change is not None:
3789 payload["change"] = change
3790
3791 await _send_json(send, payload, status=status_code)
3792
3793
3794async def _handle_admin_reconciles(
3795 send,
3796 method: str,
3797 query: dict[str, str],
3798 headers: dict[str, str],
3799) -> None:
3800 if method != "GET":
3801 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3802 return
3803
3804 gate_error = _admin_token_gate_error(
3805 headers,
3806 f"Reconcile listing requires {ADMIN_TOKEN_ENV}.",
3807 )
3808 if gate_error is not None:
3809 status, message = gate_error
3810 await _send_json(send, {"status": "error", "error": message}, status=status)
3811 return
3812
3813 reconciles = object_reconciles.list_reconciles(
3814 base_dir=_data_dir(),
3815 status=_optional_query_text(query, "status"),
3816 package=_optional_query_text(query, "package"),
3817 )
3818 await _send_json(
3819 send,
3820 {
3821 "status": "ok",
3822 "reconciles": reconciles,
3823 "count": len(reconciles),
3824 },
3825 )
3826
3827
3828async def _handle_admin_reconcile(
3829 send,
3830 method: str,
3831 reconcile_id: str,
3832 headers: dict[str, str],
3833) -> None:
3834 if method != "GET":
3835 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3836 return
3837
3838 gate_error = _admin_token_gate_error(
3839 headers,
3840 f"Reconcile detail requires {ADMIN_TOKEN_ENV}.",
3841 )
3842 if gate_error is not None:
3843 status, message = gate_error
3844 await _send_json(send, {"status": "error", "error": message}, status=status)
3845 return
3846
3847 if not object_reconciles.validate_reconcile_id(reconcile_id):
3848 await _send_json(send, {"status": "error", "error": f"Invalid reconcile id: {reconcile_id}"}, status=400)
3849 return
3850
3851 reconcile = object_reconciles.get_reconcile(reconcile_id, base_dir=_data_dir())
3852 if reconcile is None:
3853 await _send_json(send, {"status": "error", "error": f"Reconcile not found: {reconcile_id}"}, status=404)
3854 return
3855
3856 await _send_json(send, {"status": "ok", "reconcile": reconcile})
3857
3858
3859async def _handle_admin_reconcile_resolve(
3860 send,
3861 method: str,
3862 reconcile_id: str,
3863 body: bytes,
3864 headers: dict[str, str],
3865) -> None:
3866 if method != "POST":
3867 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3868 return
3869
3870 gate_error = _admin_token_gate_error(
3871 headers,
3872 f"Reconcile resolution requires {ADMIN_TOKEN_ENV}.",
3873 )
3874 if gate_error is not None:
3875 status, message = gate_error
3876 await _send_json(send, {"status": "error", "error": message}, status=status)
3877 return
3878
3879 # Resolving "take theirs" can write to live object source, so it needs the
3880 # same gate as any other source write, in addition to the admin gate above.
3881 gate_error = _source_write_gate_error(headers)
3882 if gate_error is not None:
3883 status, message = gate_error
3884 await _send_json(send, {"status": "error", "error": message}, status=status)
3885 return
3886
3887 if not object_reconciles.validate_reconcile_id(reconcile_id):
3888 await _send_json(send, {"status": "error", "error": f"Invalid reconcile id: {reconcile_id}"}, status=400)
3889 return
3890
3891 try:
3892 payload = _parse_json_body(body)
3893 except ValueError as exc:
3894 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3895 return
3896
3897 choice = payload.get("choice")
3898 if not isinstance(choice, str) or choice not in object_reconciles.RECONCILE_CHOICES:
3899 await _send_json(
3900 send,
3901 {
3902 "status": "error",
3903 "error": "Request JSON field 'choice' must be one of: "
3904 + ", ".join(object_reconciles.RECONCILE_CHOICES),
3905 },
3906 status=400,
3907 )
3908 return
3909
3910 try:
3911 reconcile = object_reconciles.resolve_reconcile(
3912 reconcile_id,
3913 choice,
3914 base_dir=_data_dir(),
3915 object_roots=get_base_object_roots(),
3916 resolved_at=_utc_timestamp(),
3917 )
3918 except object_source.ObjectSourceNotFoundError as exc:
3919 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
3920 return
3921 except (InvalidObjectIdError, object_schemas.InvalidSchemaNameError, ValueError) as exc:
3922 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
3923 return
3924
3925 await _send_json(send, {"status": "ok", "reconcile": reconcile})
3926
3927
3928async def _handle_admin_collections(
3929 send,
3930 method: str,
3931 headers: dict[str, str],
3932) -> None:
3933 if method != "GET":
3934 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3935 return
3936
3937 gate_error = _admin_token_gate_error(
3938 headers,
3939 f"Admin collection listing requires {ADMIN_TOKEN_ENV}.",
3940 )
3941 if gate_error is not None:
3942 status, message = gate_error
3943 await _send_json(send, {"status": "error", "error": message}, status=status)
3944 return
3945
3946 await _handle_collections(send, method, headers)
3947
3948
3949async def _handle_admin_collection(
3950 send,
3951 method: str,
3952 collection_tail: str,
3953 query: dict[str, str],
3954 body: bytes,
3955 headers: dict[str, str],
3956) -> None:
3957 parts = collection_tail.split("/")
3958
3959 if method == "POST" and len(parts) == 2 and parts[1] == "records":
3960 await _handle_collection_record_create(send, parts[0], body, headers)
3961 return
3962
3963 if method == "PUT" and len(parts) == 3 and parts[1] == "records":
3964 await _handle_collection_record_update(send, parts[0], parts[2], body, headers)
3965 return
3966
3967 if method == "DELETE" and len(parts) == 3 and parts[1] == "records":
3968 await _handle_collection_record_delete(send, parts[0], parts[2], headers)
3969 return
3970
3971 if method == "POST" and len(parts) == 2 and parts[1] == "compact":
3972 await _handle_admin_collection_compact(send, parts[0], headers)
3973 return
3974
3975 if method != "GET":
3976 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
3977 return
3978
3979 gate_error = _admin_token_gate_error(
3980 headers,
3981 f"Admin collection inspection requires {ADMIN_TOKEN_ENV}.",
3982 )
3983 if gate_error is not None:
3984 status, message = gate_error
3985 await _send_json(send, {"status": "error", "error": message}, status=status)
3986 return
3987
3988 if len(parts) == 2 and parts[1] == "changes":
3989 await _handle_collection_changes(send, method, parts[0], query, headers)
3990 return
3991
3992 if len(parts) == 2 and parts[1] == "records":
3993 await _handle_collection_records_get(send, parts[0], query, headers)
3994 return
3995
3996 if len(parts) == 4 and parts[1] == "records" and parts[3] == "changes":
3997 await _handle_collection_record_changes(send, method, parts[0], parts[2], query, headers)
3998 return
3999
4000 if len(parts) == 3 and parts[1] == "records":
4001 await _handle_collection_record_get(send, parts[0], parts[2], headers)
4002 return
4003
4004 if len(parts) == 1:
4005 await _handle_collection_get(send, method, collection_tail, headers)
4006 return
4007
4008 await _send_json(
4009 send,
4010 {
4011 "status": "error",
4012 "error": "Unsupported admin collection inspection path",
4013 "allowed_paths": [
4014 "/admin/collections/{collection}",
4015 "/admin/collections/{collection}/records",
4016 "/admin/collections/{collection}/records/{record_id}",
4017 "/admin/collections/{collection}/changes",
4018 "/admin/collections/{collection}/records/{record_id}/changes",
4019 "/admin/collections/{collection}/compact",
4020 ],
4021 },
4022 status=400,
4023 )
4024
4025
4026async def _handle_admin_schemas(
4027 send,
4028 method: str,
4029 headers: dict[str, str],
4030) -> None:
4031 if method != "GET":
4032 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4033 return
4034
4035 gate_error = _admin_token_gate_error(
4036 headers,
4037 f"Admin schema listing requires {ADMIN_TOKEN_ENV}.",
4038 )
4039 if gate_error is not None:
4040 status, message = gate_error
4041 await _send_json(send, {"status": "error", "error": message}, status=status)
4042 return
4043
4044 await _handle_schemas(send, method, headers)
4045
4046
4047async def _handle_admin_schema(
4048 send,
4049 method: str,
4050 schema: str,
4051 query: dict[str, str],
4052 body: bytes,
4053 headers: dict[str, str],
4054) -> None:
4055 if method == "PUT":
4056 await _handle_schema_put(send, schema, body, headers)
4057 return
4058
4059 if method == "POST":
4060 await _handle_schema_post(send, schema, body, headers)
4061 return
4062
4063 if method != "GET":
4064 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4065 return
4066
4067 gate_error = _admin_token_gate_error(
4068 headers,
4069 f"Admin schema inspection requires {ADMIN_TOKEN_ENV}.",
4070 )
4071 if gate_error is not None:
4072 status, message = gate_error
4073 await _send_json(send, {"status": "error", "error": message}, status=status)
4074 return
4075
4076 supported_schema_keys = {"format", "limit", "version", "versions"}
4077 only_format = set(query).issubset({"format"})
4078 supported = set(query).issubset(supported_schema_keys) and (
4079 not query or only_format or query.get("versions") == "true" or "version" in query
4080 )
4081 if not supported:
4082 await _send_json(
4083 send,
4084 {
4085 "status": "error",
4086 "error": "Unsupported admin schema inspection query",
4087 "allowed_queries": ["versions=true", "version=<id>"],
4088 },
4089 status=400,
4090 )
4091 return
4092
4093 await _handle_schema(send, method, schema, query, b"", headers)
4094
4095
4096async def _handle_admin_identity_accounts(
4097 send,
4098 method: str,
4099 headers: dict[str, str],
4100) -> None:
4101 if method != "GET":
4102 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4103 return
4104
4105 await _handle_identity_accounts(send, method, b"", headers)
4106
4107
4108async def _handle_admin_identity_account(
4109 send,
4110 method: str,
4111 account_id: str,
4112 headers: dict[str, str],
4113) -> None:
4114 if method != "GET":
4115 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4116 return
4117
4118 await _handle_identity_account(send, method, account_id, headers)
4119
4120
4121async def _handle_admin_identity_users(
4122 send,
4123 method: str,
4124 query: dict[str, str],
4125 headers: dict[str, str],
4126) -> None:
4127 if method != "GET":
4128 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4129 return
4130
4131 await _handle_identity_users(send, method, query, b"", headers)
4132
4133
4134async def _handle_admin_identity_user(
4135 send,
4136 method: str,
4137 user_id: str,
4138 body: bytes,
4139 headers: dict[str, str],
4140) -> None:
4141 if user_id.endswith("/password") and method in {"POST", "DELETE"}:
4142 await _handle_identity_user(send, method, user_id, body, headers)
4143 return
4144
4145 if method != "GET":
4146 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4147 return
4148
4149 await _handle_identity_user(send, method, user_id, b"", headers)
4150
4151
4152async def _handle_admin_identity_sessions(
4153 send,
4154 method: str,
4155 headers: dict[str, str],
4156) -> None:
4157 if method != "GET":
4158 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4159 return
4160
4161 await _handle_identity_sessions(send, method, b"", headers)
4162
4163
4164async def _handle_admin_identity_session(
4165 send,
4166 method: str,
4167 session_id: str,
4168 headers: dict[str, str],
4169) -> None:
4170 if method != "GET":
4171 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4172 return
4173
4174 await _handle_identity_session(send, method, session_id, headers)
4175
4176
4177async def _handle_daemon_status(
4178 send,
4179 method: str,
4180 headers: dict[str, str],
4181) -> None:
4182 if method != "GET":
4183 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4184 return
4185
4186 gate_error = _admin_token_gate_error(
4187 headers,
4188 f"Daemon status requires {ADMIN_TOKEN_ENV}.",
4189 )
4190 if gate_error is not None:
4191 status, message = gate_error
4192 await _send_json(send, {"status": "error", "error": message}, status=status)
4193 return
4194
4195 try:
4196 payload = object_daemon_status.daemon_status(
4197 base_dir=_data_dir(),
4198 rate_limit_dir=_rate_limit_dir(),
4199 event_keep_count=_event_keep_count(),
4200 event_keep_seconds=_event_keep_seconds(),
4201 )
4202 except OSError as exc:
4203 await _send_json(
4204 send,
4205 {"status": "error", "error": f"Could not build daemon status: {exc}"},
4206 status=500,
4207 )
4208 return
4209
4210 await _send_json(send, payload)
4211
4212
4213async def _handle_daemon_scheduler_tasks(
4214 send,
4215 method: str,
4216 query: dict[str, str],
4217 body: bytes,
4218 headers: dict[str, str],
4219) -> None:
4220 gate_error = _admin_token_gate_error(headers, f"Daemon scheduler controls require {ADMIN_TOKEN_ENV}.")
4221 if gate_error is not None:
4222 status, message = gate_error
4223 await _send_json(send, {"status": "error", "error": message}, status=status)
4224 return
4225
4226 if method == "GET":
4227 try:
4228 tasks = object_daemon_control.list_scheduler_tasks(
4229 base_dir=_data_dir(),
4230 status=_optional_query_text(query, "status"),
4231 limit=_query_int(query, "limit", default=100, minimum=1, maximum=1000),
4232 offset=_query_int(query, "offset", default=0, minimum=0),
4233 include_payload=_optional_query_bool(query, "include_payload") is True,
4234 )
4235 except (object_daemon_control.DaemonControlError, ValueError) as exc:
4236 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4237 return
4238 except OSError as exc:
4239 await _send_json(
4240 send,
4241 {"status": "error", "error": f"Could not read scheduler tasks: {exc}"},
4242 status=500,
4243 )
4244 return
4245
4246 await _send_json(send, {"status": "ok", **tasks})
4247 return
4248
4249 if method == "POST":
4250 try:
4251 task = object_daemon_control.create_scheduler_task(
4252 _parse_json_body(body),
4253 actor=_record_change_actor(headers),
4254 base_dir=_data_dir(),
4255 include_payload=_optional_query_bool(query, "include_payload") is True,
4256 )
4257 except (
4258 object_daemon_control.DaemonControlError,
4259 InvalidObjectIdError,
4260 ValueError,
4261 ) as exc:
4262 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4263 return
4264 except OSError as exc:
4265 await _send_json(
4266 send,
4267 {"status": "error", "error": f"Could not create scheduler task: {exc}"},
4268 status=500,
4269 )
4270 return
4271
4272 await _send_json(send, {"status": "ok", "task": task}, status=201)
4273 return
4274
4275 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4276
4277
4278async def _handle_daemon_scheduler_task(
4279 send,
4280 method: str,
4281 task_id: str,
4282 body: bytes,
4283 headers: dict[str, str],
4284) -> None:
4285 gate_error = _admin_token_gate_error(headers, f"Daemon scheduler controls require {ADMIN_TOKEN_ENV}.")
4286 if gate_error is not None:
4287 status, message = gate_error
4288 await _send_json(send, {"status": "error", "error": message}, status=status)
4289 return
4290
4291 clean_task_id = urllib.parse.unquote(task_id)
4292 if method in {"PATCH", "PUT"}:
4293 try:
4294 task = object_daemon_control.update_scheduler_task(
4295 clean_task_id,
4296 _parse_json_body(body),
4297 actor=_record_change_actor(headers),
4298 base_dir=_data_dir(),
4299 )
4300 except (
4301 object_daemon_control.DaemonControlError,
4302 InvalidObjectIdError,
4303 ValueError,
4304 ) as exc:
4305 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4306 return
4307 except object_daemon_control.DaemonItemNotFoundError as exc:
4308 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
4309 return
4310 except OSError as exc:
4311 await _send_json(
4312 send,
4313 {"status": "error", "error": f"Could not update scheduler task: {exc}"},
4314 status=500,
4315 )
4316 return
4317
4318 await _send_json(send, {"status": "ok", "task": task})
4319 return
4320
4321 if method == "DELETE":
4322 try:
4323 task = object_daemon_control.delete_scheduler_task(clean_task_id, base_dir=_data_dir())
4324 except object_daemon_control.DaemonControlError as exc:
4325 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4326 return
4327 except object_daemon_control.DaemonItemNotFoundError as exc:
4328 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
4329 return
4330 except OSError as exc:
4331 await _send_json(
4332 send,
4333 {"status": "error", "error": f"Could not delete scheduler task: {exc}"},
4334 status=500,
4335 )
4336 return
4337
4338 await _send_json(send, {"status": "ok", "deleted": True, "task": task})
4339 return
4340
4341 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4342
4343
4344async def _handle_daemon_queue_messages(
4345 send,
4346 method: str,
4347 query: dict[str, str],
4348 body: bytes,
4349 headers: dict[str, str],
4350) -> None:
4351 gate_error = _admin_token_gate_error(headers, f"Daemon queue controls require {ADMIN_TOKEN_ENV}.")
4352 if gate_error is not None:
4353 status, message = gate_error
4354 await _send_json(send, {"status": "error", "error": message}, status=status)
4355 return
4356
4357 if method == "GET":
4358 try:
4359 messages = object_daemon_control.list_queue_messages(
4360 base_dir=_data_dir(),
4361 status=_optional_query_text(query, "status"),
4362 queue_name=_optional_query_text(query, "queue_name"),
4363 limit=_query_int(query, "limit", default=100, minimum=1, maximum=1000),
4364 offset=_query_int(query, "offset", default=0, minimum=0),
4365 include_payload=_optional_query_bool(query, "include_payload") is True,
4366 )
4367 except (object_daemon_control.DaemonControlError, ValueError) as exc:
4368 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4369 return
4370 except OSError as exc:
4371 await _send_json(
4372 send,
4373 {"status": "error", "error": f"Could not read queue messages: {exc}"},
4374 status=500,
4375 )
4376 return
4377
4378 await _send_json(send, {"status": "ok", **messages})
4379 return
4380
4381 if method == "POST":
4382 try:
4383 message = object_daemon_control.enqueue_message(
4384 _parse_json_body(body),
4385 actor=_record_change_actor(headers),
4386 base_dir=_data_dir(),
4387 include_payload=_optional_query_bool(query, "include_payload") is True,
4388 )
4389 except (
4390 object_daemon_control.DaemonControlError,
4391 InvalidObjectIdError,
4392 ValueError,
4393 ) as exc:
4394 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4395 return
4396 except OSError as exc:
4397 await _send_json(
4398 send,
4399 {"status": "error", "error": f"Could not enqueue message: {exc}"},
4400 status=500,
4401 )
4402 return
4403
4404 await _send_json(send, {"status": "ok", "message": message}, status=201)
4405 return
4406
4407 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4408
4409
4410async def _handle_daemon_queue_message(
4411 send,
4412 method: str,
4413 message_id: str,
4414 body: bytes,
4415 headers: dict[str, str],
4416) -> None:
4417 gate_error = _admin_token_gate_error(headers, f"Daemon queue controls require {ADMIN_TOKEN_ENV}.")
4418 if gate_error is not None:
4419 status, message = gate_error
4420 await _send_json(send, {"status": "error", "error": message}, status=status)
4421 return
4422
4423 clean_message_id = urllib.parse.unquote(message_id)
4424 if method in {"PATCH", "PUT"}:
4425 try:
4426 message = object_daemon_control.update_queue_message(
4427 clean_message_id,
4428 _parse_json_body(body),
4429 actor=_record_change_actor(headers),
4430 base_dir=_data_dir(),
4431 )
4432 except (object_daemon_control.DaemonControlError, ValueError) as exc:
4433 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4434 return
4435 except object_daemon_control.DaemonItemNotFoundError as exc:
4436 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
4437 return
4438 except OSError as exc:
4439 await _send_json(
4440 send,
4441 {"status": "error", "error": f"Could not update queue message: {exc}"},
4442 status=500,
4443 )
4444 return
4445
4446 await _send_json(send, {"status": "ok", "message": message})
4447 return
4448
4449 if method == "DELETE":
4450 try:
4451 message = object_daemon_control.delete_queue_message(clean_message_id, base_dir=_data_dir())
4452 except object_daemon_control.DaemonControlError as exc:
4453 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4454 return
4455 except object_daemon_control.DaemonItemNotFoundError as exc:
4456 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
4457 return
4458 except OSError as exc:
4459 await _send_json(
4460 send,
4461 {"status": "error", "error": f"Could not delete queue message: {exc}"},
4462 status=500,
4463 )
4464 return
4465
4466 await _send_json(send, {"status": "ok", "deleted": True, "message": message})
4467 return
4468
4469 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4470
4471
4472def _admin_status_payload() -> dict[str, Any]:
4473 health = _health_payload(include_metrics=True)
4474 collections = object_collections.list_collections(base_dir=_data_dir())
4475 schemas = object_schemas.list_schemas(base_dir=_data_dir())
4476 packages = _admin_package_summaries()
4477 permissions = _permissions_status_payload()
4478
4479 return {
4480 "status": health["status"],
4481 "timestamp": health["timestamp"],
4482 "version": health["version"],
4483 "station_id": health["station_id"],
4484 "health": health,
4485 "inventory": {
4486 "objects": health["objects"]["count"],
4487 "collections": len(collections),
4488 "schemas": len(schemas),
4489 "packages": len(packages),
4490 },
4491 "capabilities": _admin_capabilities_payload(),
4492 "packages": packages,
4493 "permissions": {
4494 "enforcement_enabled": permissions["permissions"]["enforcement_enabled"],
4495 "audit_enabled": permissions["permissions"]["audit_enabled"],
4496 "readiness": permissions["readiness"],
4497 "warnings": permissions["warnings"],
4498 },
4499 }
4500
4501
4502def _admin_capabilities_payload() -> dict[str, Any]:
4503 return {
4504 "source_writes": {
4505 "enabled": _env_enabled(SOURCE_WRITES_ENV),
4506 "env": SOURCE_WRITES_ENV,
4507 },
4508 "file_writes": {
4509 "enabled": _env_enabled(FILE_WRITES_ENV),
4510 "env": FILE_WRITES_ENV,
4511 "max_bytes": _max_object_file_bytes(),
4512 "max_bytes_env": MAX_OBJECT_FILE_BYTES_ENV,
4513 },
4514 "package_installs": {
4515 "enabled": _env_enabled(PACKAGE_INSTALLS_ENABLED_ENV),
4516 "env": PACKAGE_INSTALLS_ENABLED_ENV,
4517 },
4518 "package_restore": {
4519 "enabled": _env_enabled(PACKAGE_RESTORE_ENABLED_ENV),
4520 "env": PACKAGE_RESTORE_ENABLED_ENV,
4521 },
4522 "overrides": {
4523 "enabled": get_override_root() is not None,
4524 "env": object_namespace.OVERRIDES_DIR_ENV,
4525 },
4526 "packages": {
4527 "available": True,
4528 "can_install": _env_enabled(PACKAGE_INSTALLS_ENABLED_ENV),
4529 "can_restore": _env_enabled(PACKAGE_RESTORE_ENABLED_ENV),
4530 "install_env": PACKAGE_INSTALLS_ENABLED_ENV,
4531 },
4532 "backups": {
4533 "available": True,
4534 "can_create": True,
4535 "can_download": True,
4536 "can_preview": True,
4537 "can_restore": False,
4538 **_backup_schedule_payload(),
4539 },
4540 "storage": {
4541 "append_collections": len(
4542 object_schemas.list_append_storage_collections(base_dir=_data_dir())
4543 ),
4544 },
4545 "permission_enforcement": {
4546 "enabled": _permission_enforcement_enabled(),
4547 "requested": _permission_enforcement_requested(),
4548 "blocked": _permission_enforcement_blocked(),
4549 "env": PERMISSION_ENFORCEMENT_ENV,
4550 },
4551 "permission_audit": {
4552 "enabled": _permission_audit_enabled(),
4553 "env": PERMISSION_AUDIT_ENV,
4554 },
4555 "record_events": {
4556 "enabled": _record_events_enabled(),
4557 "env": RECORD_EVENTS_ENV,
4558 "keep_count": _event_keep_count(),
4559 "keep_seconds": _event_keep_seconds(),
4560 },
4561 "filtering": {
4562 "enabled": _filtering_enabled(),
4563 "env": FILTERING_ENABLED_ENV,
4564 },
4565 "event_handlers": {
4566 "enabled": object_handlers.handlers_enabled(),
4567 "env": object_handlers.HANDLERS_ENABLED_ENV,
4568 },
4569 "worker_pool": {
4570 "enabled": _worker_pool_size() > 0,
4571 "size": _worker_pool_size(),
4572 "env": object_worker_pool.WORKER_POOL_SIZE_ENV,
4573 },
4574 "identity": {
4575 "trusted_headers_enabled": _env_enabled(PERMISSION_TRUST_HEADERS_ENV),
4576 "require_known_identity_users": _env_enabled(REQUIRE_KNOWN_IDENTITY_USERS_ENV),
4577 "session_login_enabled": _env_enabled(SESSION_LOGIN_ENV),
4578 "session_login_token_configured": bool(os.environ.get(SESSION_LOGIN_TOKEN_ENV, "")),
4579 "session_admin_gates_enabled": _env_enabled(SESSION_ADMIN_GATES_ENV),
4580 "session_admin_gates_env": SESSION_ADMIN_GATES_ENV,
4581 "password_login_enabled": _env_enabled(PASSWORD_LOGIN_ENV),
4582 "password_login_env": PASSWORD_LOGIN_ENV,
4583 "signup_enabled": _signup_available(),
4584 "signup_env": object_signup.SIGNUP_ENV,
4585 "signup_blockers": _signup_blockers(),
4586 "password_reset_enabled": _password_reset_available(),
4587 "password_reset_env": object_signup.PASSWORD_RESET_ENV,
4588 "password_reset_blockers": _password_reset_blockers(),
4589 "public_url": object_signup.public_url(),
4590 "public_url_env": object_signup.PUBLIC_URL_ENV,
4591 },
4592 "limits": {
4593 "max_request_bytes": _max_request_bytes(),
4594 "max_object_file_bytes": _max_object_file_bytes(),
4595 "max_concurrent_requests": _max_concurrent_requests(),
4596 "max_concurrent_executions": _max_concurrent_executions(),
4597 "rate_limit_requests": _rate_limit_requests(),
4598 "rate_limit_window_seconds": _rate_limit_window_seconds(),
4599 "object_timeout_seconds": _object_timeout_seconds(),
4600 },
4601 }
4602
4603
4604def _admin_package_summaries() -> list[dict[str, Any]]:
4605 packages = _list_all_packages()
4606 return [_admin_package_summary(package) for package in packages]
4607
4608
4609def _admin_package_summary(package: Mapping[str, Any]) -> dict[str, Any]:
4610 package_id = str(package["id"])
4611 plan = object_packages.dry_run_package(
4612 package_id,
4613 root=_root_for_package(package_id),
4614 base_dir=_data_dir(),
4615 )
4616 changes = object_package_changes.list_package_changes(
4617 package_id,
4618 base_dir=_data_dir(),
4619 limit=1,
4620 )
4621 installed = _package_plan_installed_count(plan)
4622 total = _package_plan_installable_count(plan)
4623 summary = dict(package)
4624 summary["status"] = _package_install_status(installed=installed, total=total)
4625 summary["install"] = {
4626 "installed_count": installed,
4627 "installable_count": total,
4628 "safe_to_install": bool(plan.get("safe_to_install")),
4629 "install_enabled": _env_enabled(PACKAGE_INSTALLS_ENABLED_ENV),
4630 "warnings": list(plan.get("warnings", [])),
4631 }
4632 summary["changes"] = {
4633 "total": changes["total"],
4634 "latest": changes["changes"][0] if changes["changes"] else None,
4635 }
4636 return summary
4637
4638
4639def _package_plan_installed_count(plan: Mapping[str, Any]) -> int:
4640 count = 0
4641 for section in ("objects", "schemas", "seed"):
4642 count += sum(1 for entry in plan.get(section, []) if entry.get("installed"))
4643 count += sum(1 for entry in plan.get("migrations", []) if entry.get("applied"))
4644 return count
4645
4646
4647def _package_plan_installable_count(plan: Mapping[str, Any]) -> int:
4648 return sum(
4649 len(plan.get(section, []))
4650 for section in ("objects", "schemas", "seed", "migrations")
4651 )
4652
4653
4654def _package_install_status(*, installed: int, total: int) -> str:
4655 if total == 0:
4656 return "available"
4657 if installed == total:
4658 return "installed"
4659 if installed > 0:
4660 return "partial"
4661 return "available"
4662
4663
4664async def _handle_permissions_status(
4665 send,
4666 method: str,
4667 headers: dict[str, str],
4668) -> None:
4669 gate_error = _permissions_gate_error(headers)
4670 if gate_error is not None:
4671 status, message = gate_error
4672 await _send_json(send, {"status": "error", "error": message}, status=status)
4673 return
4674
4675 if method != "GET":
4676 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4677 return
4678
4679 await _send_json(send, _permissions_status_payload())
4680
4681
4682def _permissions_status_payload() -> dict[str, Any]:
4683 permissions = {
4684 **_permission_readiness_inputs(),
4685 "enforcement_enabled": _permission_enforcement_enabled(),
4686 "enforcement_requested": _permission_enforcement_requested(),
4687 "enforcement_blocked": _permission_enforcement_blocked(),
4688 "allow_unready_enforcement": _permission_unready_enforcement_allowed(),
4689 "audit_enabled": _permission_audit_enabled(),
4690 }
4691 return object_permission_status.build_permissions_status(
4692 base_dir=_data_dir(),
4693 permissions=permissions,
4694 require_known_identity_users_env=REQUIRE_KNOWN_IDENTITY_USERS_ENV,
4695 )
4696
4697
4698def _permission_readiness_inputs() -> dict[str, Any]:
4699 return {
4700 "admin_token_configured": bool(os.environ.get(ADMIN_TOKEN_ENV, "")),
4701 "trusted_headers_enabled": _env_enabled(PERMISSION_TRUST_HEADERS_ENV),
4702 "require_known_identity_users": _env_enabled(REQUIRE_KNOWN_IDENTITY_USERS_ENV),
4703 "session_login_enabled": _env_enabled(SESSION_LOGIN_ENV),
4704 "session_login_token_configured": bool(os.environ.get(SESSION_LOGIN_TOKEN_ENV, "")),
4705 "password_login_enabled": _env_enabled(PASSWORD_LOGIN_ENV),
4706 }
4707
4708
4709async def _handle_permissions_policy(
4710 send,
4711 method: str,
4712 body: bytes,
4713 headers: dict[str, str],
4714) -> None:
4715 gate_error = _permissions_gate_error(headers)
4716 if gate_error is not None:
4717 status, message = gate_error
4718 await _send_json(send, {"status": "error", "error": message}, status=status)
4719 return
4720
4721 if method == "GET":
4722 try:
4723 policy = object_permission_store.load_policy(_data_dir())
4724 except ValueError as exc:
4725 await _send_json(
4726 send,
4727 {"status": "error", "error": f"Permission policy is invalid: {exc}"},
4728 status=500,
4729 )
4730 return
4731
4732 await _send_json(
4733 send,
4734 {
4735 "status": "ok",
4736 "policy": object_permissions.policy_to_dict(policy),
4737 },
4738 )
4739 return
4740
4741 if method == "PUT":
4742 try:
4743 payload = _parse_json_body(body)
4744 policy_payload = _policy_payload_from_request(payload)
4745 policy = object_permission_store.replace_policy(policy_payload, _data_dir())
4746 except ValueError as exc:
4747 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4748 return
4749 except OSError as exc:
4750 await _send_json(
4751 send,
4752 {"status": "error", "error": f"Could not save permission policy: {exc}"},
4753 status=500,
4754 )
4755 return
4756
4757 await _send_json(
4758 send,
4759 {
4760 "status": "ok",
4761 "policy": object_permissions.policy_to_dict(policy),
4762 },
4763 )
4764 return
4765
4766 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4767
4768
4769async def _handle_permissions_check(
4770 send,
4771 method: str,
4772 body: bytes,
4773 headers: dict[str, str],
4774) -> None:
4775 gate_error = _permissions_gate_error(headers)
4776 if gate_error is not None:
4777 status, message = gate_error
4778 await _send_json(send, {"status": "error", "error": message}, status=status)
4779 return
4780
4781 if method != "POST":
4782 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4783 return
4784
4785 try:
4786 payload = _parse_json_body(body)
4787 policy = _policy_for_check_request(payload)
4788 subject = object_permissions.subject_from_dict(payload.get("subject", payload.get("user")))
4789 action = _required_payload_text(payload, "action")
4790 collection = _optional_payload_text(payload, "collection")
4791 object_id = _optional_payload_text(payload, "object_id")
4792 record = _optional_record_payload(payload)
4793 checked_at = _optional_datetime_payload(payload, "now")
4794 except ValueError as exc:
4795 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4796 return
4797
4798 decision = object_permissions.check_permission(
4799 subject,
4800 action,
4801 policy=policy,
4802 collection=collection,
4803 object_id=object_id,
4804 record=record,
4805 now=checked_at,
4806 )
4807 await _send_json(
4808 send,
4809 {
4810 "status": "ok",
4811 "decision": object_permissions.decision_to_dict(decision),
4812 },
4813 )
4814
4815
4816async def _handle_permissions_audit(
4817 send,
4818 method: str,
4819 query: dict[str, str],
4820 headers: dict[str, str],
4821) -> None:
4822 gate_error = _permissions_gate_error(headers)
4823 if gate_error is not None:
4824 status, message = gate_error
4825 await _send_json(send, {"status": "error", "error": message}, status=status)
4826 return
4827
4828 if method != "GET":
4829 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4830 return
4831
4832 try:
4833 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
4834 entries = object_permission_audit.get_permission_audit(
4835 _data_dir(),
4836 limit=limit,
4837 action=_optional_query_text(query, "action"),
4838 object_id=_optional_query_text(query, "object_id"),
4839 collection=_optional_query_text(query, "collection"),
4840 allowed=_optional_query_bool(query, "allowed"),
4841 enforced=_optional_query_bool(query, "enforced"),
4842 )
4843 except ValueError as exc:
4844 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4845 return
4846 except OSError as exc:
4847 await _send_json(
4848 send,
4849 {"status": "error", "error": f"Could not read permission audit: {exc}"},
4850 status=500,
4851 )
4852 return
4853
4854 await _send_json(
4855 send,
4856 {
4857 "status": "ok",
4858 "entries": entries,
4859 "count": len(entries),
4860 },
4861 )
4862
4863
4864async def _handle_events(
4865 send,
4866 method: str,
4867 query: dict[str, str],
4868 body: bytes,
4869 headers: dict[str, str],
4870) -> None:
4871 gate_error = _admin_token_gate_error(headers, f"Events API requires {ADMIN_TOKEN_ENV}.")
4872 if gate_error is not None:
4873 status, message = gate_error
4874 await _send_json(send, {"status": "error", "error": message}, status=status)
4875 return
4876
4877 if method == "GET":
4878 try:
4879 since = None
4880 if "since" in query:
4881 since = _query_int(query, "since", minimum=0)
4882 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
4883 offset = _query_int(query, "offset", default=0, minimum=0)
4884 events = object_events.list_events(
4885 event_type=_optional_query_text(query, "event_type"),
4886 since=since,
4887 base_dir=_data_dir(),
4888 limit=limit,
4889 offset=offset,
4890 )
4891 except (object_events.InvalidEventTypeError, ValueError) as exc:
4892 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4893 return
4894 except OSError as exc:
4895 await _send_json(
4896 send,
4897 {"status": "error", "error": f"Could not read events: {exc}"},
4898 status=500,
4899 )
4900 return
4901
4902 await _send_json(send, {"status": "ok", **events})
4903 return
4904
4905 if method == "POST":
4906 try:
4907 payload = _parse_json_body(body)
4908 event = object_events.publish_event(
4909 _required_payload_text(payload, "event_type"),
4910 payload=payload.get("payload", {}),
4911 source=_payload_text(payload, "source", "api"),
4912 actor=_record_change_actor(headers),
4913 base_dir=_data_dir(),
4914 keep_count=_event_keep_count(),
4915 keep_seconds=_event_keep_seconds(),
4916 )
4917 except (object_events.InvalidEventTypeError, ValueError) as exc:
4918 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4919 return
4920 except OSError as exc:
4921 await _send_json(
4922 send,
4923 {"status": "error", "error": f"Could not publish event: {exc}"},
4924 status=500,
4925 )
4926 return
4927
4928 await _send_json(send, {"status": "ok", "event": event}, status=201)
4929 return
4930
4931 if method == "DELETE":
4932 try:
4933 keep_count = _event_retention_query_int(
4934 query,
4935 "keep_count",
4936 default=_event_keep_count(),
4937 maximum=object_events.MAX_EVENT_KEEP_COUNT,
4938 )
4939 keep_seconds = _event_retention_query_int(
4940 query,
4941 "keep_seconds",
4942 default=_event_keep_seconds(),
4943 )
4944 result = object_events.prune_events(
4945 base_dir=_data_dir(),
4946 keep_count=keep_count,
4947 keep_seconds=keep_seconds,
4948 )
4949 except ValueError as exc:
4950 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4951 return
4952 except OSError as exc:
4953 await _send_json(
4954 send,
4955 {"status": "error", "error": f"Could not prune events: {exc}"},
4956 status=500,
4957 )
4958 return
4959
4960 await _send_json(send, {"status": "ok", "retention": result})
4961 return
4962
4963 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
4964
4965
4966async def _handle_event_subscriptions(
4967 send,
4968 method: str,
4969 query: dict[str, str],
4970 body: bytes,
4971 headers: dict[str, str],
4972) -> None:
4973 gate_error = _admin_token_gate_error(headers, f"Events API requires {ADMIN_TOKEN_ENV}.")
4974 if gate_error is not None:
4975 status, message = gate_error
4976 await _send_json(send, {"status": "error", "error": message}, status=status)
4977 return
4978
4979 if method == "GET":
4980 try:
4981 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
4982 offset = _query_int(query, "offset", default=0, minimum=0)
4983 subscriptions = object_events.list_subscriptions(
4984 event_type=_optional_query_text(query, "event_type"),
4985 base_dir=_data_dir(),
4986 limit=limit,
4987 offset=offset,
4988 )
4989 except (object_events.InvalidEventTypeError, ValueError) as exc:
4990 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
4991 return
4992 except OSError as exc:
4993 await _send_json(
4994 send,
4995 {"status": "error", "error": f"Could not read event subscriptions: {exc}"},
4996 status=500,
4997 )
4998 return
4999
5000 await _send_json(send, {"status": "ok", **subscriptions})
5001 return
5002
5003 if method == "POST":
5004 try:
5005 payload = _parse_json_body(body)
5006 subscription = object_events.subscribe_event(
5007 _required_payload_text(payload, "event_type"),
5008 subscriber_id=_optional_payload_text(payload, "subscriber_id"),
5009 callback_url=_payload_text(payload, "callback_url", ""),
5010 actor=_record_change_actor(headers),
5011 base_dir=_data_dir(),
5012 )
5013 except (
5014 object_events.InvalidEventTypeError,
5015 object_events.InvalidSubscriberIdError,
5016 ValueError,
5017 ) as exc:
5018 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5019 return
5020 except OSError as exc:
5021 await _send_json(
5022 send,
5023 {"status": "error", "error": f"Could not save event subscription: {exc}"},
5024 status=500,
5025 )
5026 return
5027
5028 await _send_json(send, {"status": "ok", "subscription": subscription}, status=201)
5029 return
5030
5031 if method == "DELETE":
5032 try:
5033 subscription = object_events.delete_subscription(
5034 _required_query_text(query, "event_type"),
5035 _required_query_text(query, "subscriber_id"),
5036 base_dir=_data_dir(),
5037 )
5038 except (
5039 object_events.InvalidEventTypeError,
5040 object_events.InvalidSubscriberIdError,
5041 ValueError,
5042 ) as exc:
5043 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5044 return
5045 except object_events.SubscriptionNotFoundError as exc:
5046 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5047 return
5048 except OSError as exc:
5049 await _send_json(
5050 send,
5051 {"status": "error", "error": f"Could not delete event subscription: {exc}"},
5052 status=500,
5053 )
5054 return
5055
5056 await _send_json(
5057 send,
5058 {
5059 "status": "ok",
5060 "deleted": True,
5061 "subscription": subscription,
5062 },
5063 )
5064 return
5065
5066 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5067
5068
5069async def _handle_event_deliveries(
5070 send,
5071 method: str,
5072 query: dict[str, str],
5073 headers: dict[str, str],
5074) -> None:
5075 gate_error = _admin_token_gate_error(headers, f"Events API requires {ADMIN_TOKEN_ENV}.")
5076 if gate_error is not None:
5077 status, message = gate_error
5078 await _send_json(send, {"status": "error", "error": message}, status=status)
5079 return
5080
5081 if method != "GET":
5082 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5083 return
5084
5085 try:
5086 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
5087 offset = _query_int(query, "offset", default=0, minimum=0)
5088 event_limit = _query_int(query, "event_limit", default=10, minimum=0, maximum=1000)
5089 deliveries = object_events.list_event_deliveries(
5090 event_type=_optional_query_text(query, "event_type"),
5091 delivery_status=_optional_query_text(query, "delivery_status"),
5092 pending=_optional_query_bool(query, "pending"),
5093 include_callback_url=_optional_query_bool(query, "include_callback_url") is True,
5094 include_events=_optional_query_bool(query, "include_events") is True,
5095 event_limit=event_limit,
5096 base_dir=_data_dir(),
5097 limit=limit,
5098 offset=offset,
5099 )
5100 except (object_events.InvalidEventTypeError, ValueError) as exc:
5101 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5102 return
5103 except OSError as exc:
5104 await _send_json(
5105 send,
5106 {"status": "error", "error": f"Could not read event deliveries: {exc}"},
5107 status=500,
5108 )
5109 return
5110
5111 await _send_json(send, {"status": "ok", **deliveries})
5112
5113
5114async def _handle_packages(
5115 send,
5116 method: str,
5117 headers: dict[str, str],
5118) -> None:
5119 if method != "GET":
5120 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5121 return
5122
5123 gate_error = _admin_token_gate_error(
5124 headers,
5125 f"Package listing requires {ADMIN_TOKEN_ENV}.",
5126 )
5127 if gate_error is not None:
5128 status, message = gate_error
5129 await _send_json(send, {"status": "error", "error": message}, status=status)
5130 return
5131
5132 try:
5133 packages = _list_all_packages()
5134 except object_packages.InvalidPackageManifestError as exc:
5135 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
5136 return
5137
5138 await _send_json(
5139 send,
5140 {
5141 "status": "ok",
5142 "packages": packages,
5143 "count": len(packages),
5144 },
5145 )
5146
5147
5148async def _handle_package(
5149 send,
5150 method: str,
5151 package_id: str,
5152 query: dict[str, str],
5153 headers: dict[str, str],
5154) -> None:
5155 if method != "GET":
5156 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5157 return
5158
5159 gate_error = _admin_token_gate_error(
5160 headers,
5161 f"Package detail requires {ADMIN_TOKEN_ENV}.",
5162 )
5163 if gate_error is not None:
5164 status, message = gate_error
5165 await _send_json(send, {"status": "error", "error": message}, status=status)
5166 return
5167
5168 try:
5169 dry_run = _optional_query_bool(query, "dry_run") is True
5170 if dry_run:
5171 plan = object_packages.dry_run_package(
5172 package_id,
5173 root=_root_for_package(package_id),
5174 base_dir=_data_dir(),
5175 )
5176 change = object_package_changes.append_package_change(
5177 package_id=package_id,
5178 action="dry_run",
5179 package_version=plan["package"].get("version"),
5180 actor=_record_change_actor(headers),
5181 details=object_package_changes.dry_run_change_details(plan),
5182 base_dir=_data_dir(),
5183 )
5184 payload = {
5185 "status": "ok",
5186 "dry_run": plan,
5187 "change": change,
5188 }
5189 else:
5190 payload = {
5191 "status": "ok",
5192 "package": object_packages.get_package(
5193 package_id,
5194 root=_root_for_package(package_id),
5195 ),
5196 "provenance": object_packages.package_status(
5197 package_id,
5198 root=_root_for_package(package_id),
5199 base_dir=_data_dir(),
5200 object_roots=get_base_object_roots(),
5201 ),
5202 }
5203 except object_packages.InvalidPackageIdError as exc:
5204 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5205 return
5206 except object_packages.PackageNotFoundError as exc:
5207 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5208 return
5209 except object_packages.InvalidPackageManifestError as exc:
5210 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
5211 return
5212 except object_package_changes.InvalidPackageChangeError as exc:
5213 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
5214 return
5215 except ValueError as exc:
5216 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5217 return
5218 except OSError as exc:
5219 await _send_json(send, {"status": "error", "error": f"Could not record package change: {exc}"}, status=500)
5220 return
5221
5222 await _send_json(send, payload)
5223
5224
5225async def _handle_package_install(
5226 send,
5227 method: str,
5228 package_id: str,
5229 body: bytes,
5230 headers: dict[str, str],
5231) -> None:
5232 if method != "POST":
5233 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5234 return
5235
5236 gate_error = _admin_token_gate_error(
5237 headers,
5238 f"Package installs require {ADMIN_TOKEN_ENV}.",
5239 )
5240 if gate_error is not None:
5241 status, message = gate_error
5242 await _send_json(send, {"status": "error", "error": message}, status=status)
5243 return
5244
5245 if not _env_enabled(PACKAGE_INSTALLS_ENABLED_ENV):
5246 await _send_json(
5247 send,
5248 {
5249 "status": "error",
5250 "error": f"Package installs are disabled. Set {PACKAGE_INSTALLS_ENABLED_ENV}=true.",
5251 },
5252 status=403,
5253 )
5254 return
5255
5256 plan = None
5257 requested_change = None
5258
5259 try:
5260 payload = _parse_json_body(body)
5261 allow_replace = _optional_payload_bool(payload, "allow_replace") is True
5262 plan = object_packages.dry_run_package(
5263 package_id,
5264 root=_root_for_package(package_id),
5265 base_dir=_data_dir(),
5266 )
5267 requested_change = object_package_changes.append_package_change(
5268 package_id=package_id,
5269 action="install_requested",
5270 package_version=plan["package"].get("version"),
5271 actor=_record_change_actor(headers),
5272 details=object_package_changes.dry_run_change_details(plan),
5273 base_dir=_data_dir(),
5274 )
5275
5276 restore_point: dict[str, Any] | None = None
5277
5278 def create_restore_point(_: Mapping[str, Any]) -> dict[str, Any]:
5279 nonlocal restore_point
5280 summary = object_backup.create_runtime_restore_point(
5281 f"package-{package_id}",
5282 data_dir=_data_dir(),
5283 )
5284 restore_point = _backup_summary_payload(summary)
5285 return restore_point
5286
5287 install_result = object_packages.install_package(
5288 package_id,
5289 root=_root_for_package(package_id),
5290 base_dir=_data_dir(),
5291 object_roots=get_base_object_roots(),
5292 allow_replace=allow_replace,
5293 before_write=create_restore_point,
5294 )
5295 restore_point = install_result.get("restore_point", restore_point)
5296 installed_change = object_package_changes.append_package_change(
5297 package_id=package_id,
5298 action="installed",
5299 package_version=install_result["package"].get("version"),
5300 actor=_record_change_actor(headers),
5301 details=_package_change_details(install_result, restore_point=restore_point),
5302 base_dir=_data_dir(),
5303 )
5304 except object_packages.InvalidPackageIdError as exc:
5305 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5306 return
5307 except object_packages.PackageNotFoundError as exc:
5308 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5309 return
5310 except object_packages.PackageInstallError as exc:
5311 failed_change = _try_append_package_install_failure(
5312 package_id=package_id,
5313 plan=plan,
5314 headers=headers,
5315 error=str(exc),
5316 )
5317 changes = _package_install_changes(requested_change, failed=failed_change)
5318 await _send_json(
5319 send,
5320 {
5321 "status": "error",
5322 "error": str(exc),
5323 "changes": changes,
5324 },
5325 status=409,
5326 )
5327 return
5328 except object_packages.InvalidPackageManifestError as exc:
5329 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
5330 return
5331 except object_package_changes.InvalidPackageChangeError as exc:
5332 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
5333 return
5334 except ValueError as exc:
5335 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5336 return
5337 except OSError as exc:
5338 failed_change = _try_append_package_install_failure(
5339 package_id=package_id,
5340 plan=plan,
5341 headers=headers,
5342 error=str(exc),
5343 )
5344 await _send_json(
5345 send,
5346 {
5347 "status": "error",
5348 "error": f"Package install failed: {exc}",
5349 "changes": _package_install_changes(requested_change, failed=failed_change),
5350 },
5351 status=500,
5352 )
5353 return
5354
5355 await _send_json(
5356 send,
5357 {
5358 "status": "ok",
5359 "install": install_result,
5360 "changes": {
5361 "requested": requested_change,
5362 "installed": installed_change,
5363 },
5364 "restore_point": restore_point,
5365 },
5366 status=201,
5367 )
5368
5369
5370async def _handle_package_restore(
5371 send,
5372 method: str,
5373 package_id: str,
5374 body: bytes,
5375 headers: dict[str, str],
5376) -> None:
5377 if method != "POST":
5378 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5379 return
5380
5381 gate_error = _admin_token_gate_error(
5382 headers,
5383 f"Package restore requires {ADMIN_TOKEN_ENV}.",
5384 )
5385 if gate_error is not None:
5386 status, message = gate_error
5387 await _send_json(send, {"status": "error", "error": message}, status=status)
5388 return
5389
5390 if not _env_enabled(PACKAGE_RESTORE_ENABLED_ENV):
5391 await _send_json(
5392 send,
5393 {
5394 "status": "error",
5395 "error": f"Package restore is disabled. Set {PACKAGE_RESTORE_ENABLED_ENV}=true.",
5396 },
5397 status=403,
5398 )
5399 return
5400
5401 from_change: dict[str, Any] | None = None
5402 restore_point: dict[str, Any] | None = None
5403
5404 try:
5405 payload = _parse_json_body(body)
5406 if _required_payload_text(payload, "confirm") != "restore-runtime":
5407 raise ValueError("Request JSON field 'confirm' must be 'restore-runtime'")
5408 change_id = _required_payload_text(payload, "change_id")
5409 from_change = object_package_changes.get_package_change(
5410 package_id,
5411 change_id,
5412 base_dir=_data_dir(),
5413 )
5414 if from_change is None:
5415 await _send_json(
5416 send,
5417 {"status": "error", "error": f"Package change not found: {change_id}"},
5418 status=404,
5419 )
5420 return
5421
5422 restore_point = _restore_point_from_package_change(from_change)
5423 restore_summary = object_backup.restore_runtime_backup(
5424 restore_point["path"],
5425 objects_dir=_primary_objects_dir(),
5426 data_dir=_data_dir(),
5427 overwrite=True,
5428 prune_extra=True,
5429 )
5430 requested_change = object_package_changes.append_package_change(
5431 package_id=package_id,
5432 action="restore_requested",
5433 package_version=from_change.get("package_version"),
5434 actor=_record_change_actor(headers),
5435 details=_package_restore_change_details(
5436 from_change,
5437 restore_point,
5438 restore=restore_summary.to_dict(),
5439 ),
5440 base_dir=_data_dir(),
5441 )
5442 rolled_back_change = object_package_changes.append_package_change(
5443 package_id=package_id,
5444 action="rolled_back",
5445 package_version=from_change.get("package_version"),
5446 actor=_record_change_actor(headers),
5447 details=_package_restore_change_details(
5448 from_change,
5449 restore_point,
5450 restore=restore_summary.to_dict(),
5451 ),
5452 base_dir=_data_dir(),
5453 )
5454 except (object_packages.InvalidPackageIdError, object_package_changes.InvalidPackageChangeError) as exc:
5455 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5456 return
5457 except (ValueError, object_backup.BackupRestoreError) as exc:
5458 failed_change = _try_append_package_restore_failure(
5459 package_id=package_id,
5460 from_change=from_change,
5461 restore_point=restore_point,
5462 headers=headers,
5463 error=str(exc),
5464 )
5465 await _send_json(
5466 send,
5467 {
5468 "status": "error",
5469 "error": str(exc),
5470 "changes": _package_restore_changes(failed=failed_change),
5471 },
5472 status=400,
5473 )
5474 return
5475 except OSError as exc:
5476 failed_change = _try_append_package_restore_failure(
5477 package_id=package_id,
5478 from_change=from_change,
5479 restore_point=restore_point,
5480 headers=headers,
5481 error=str(exc),
5482 )
5483 await _send_json(
5484 send,
5485 {
5486 "status": "error",
5487 "error": f"Package restore failed: {exc}",
5488 "changes": _package_restore_changes(failed=failed_change),
5489 },
5490 status=500,
5491 )
5492 return
5493
5494 await _send_json(
5495 send,
5496 {
5497 "status": "ok",
5498 "restore": restore_summary.to_dict(),
5499 "restore_point": restore_point,
5500 "from_change": from_change,
5501 "changes": {
5502 "requested": requested_change,
5503 "rolled_back": rolled_back_change,
5504 },
5505 },
5506 )
5507
5508
5509async def _handle_package_changes(
5510 send,
5511 method: str,
5512 package_id: str,
5513 query: dict[str, str],
5514 headers: dict[str, str],
5515) -> None:
5516 if method != "GET":
5517 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
5518 return
5519
5520 gate_error = _admin_token_gate_error(
5521 headers,
5522 f"Package change history requires {ADMIN_TOKEN_ENV}.",
5523 )
5524 if gate_error is not None:
5525 status, message = gate_error
5526 await _send_json(send, {"status": "error", "error": message}, status=status)
5527 return
5528
5529 try:
5530 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
5531 offset = _query_int(query, "offset", default=0, minimum=0)
5532 changes = object_package_changes.list_package_changes(
5533 package_id,
5534 base_dir=_data_dir(),
5535 limit=limit,
5536 offset=offset,
5537 )
5538 except object_packages.InvalidPackageIdError as exc:
5539 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5540 return
5541 except ValueError as exc:
5542 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5543 return
5544
5545 await _send_json(send, {"status": "ok", **changes})
5546
5547
5548def _backup_summary_payload(summary: object_backup.BackupSummary) -> dict[str, Any]:
5549 return {
5550 "path": summary.path,
5551 "format_version": summary.format_version,
5552 "created_at": summary.created_at,
5553 "files": summary.files,
5554 "bytes": summary.bytes,
5555 "warnings": summary.warnings,
5556 }
5557
5558
5559def _package_change_details(
5560 plan: Mapping[str, Any],
5561 *,
5562 restore_point: Mapping[str, Any] | None = None,
5563 error: str | None = None,
5564) -> dict[str, Any]:
5565 details = object_package_changes.dry_run_change_details(plan)
5566 if restore_point is not None:
5567 details["restore_point"] = dict(restore_point)
5568 if error:
5569 details["error"] = error
5570 return details
5571
5572
5573def _try_append_package_install_failure(
5574 *,
5575 package_id: str,
5576 plan: Mapping[str, Any] | None,
5577 headers: dict[str, str],
5578 error: str,
5579) -> dict[str, Any] | None:
5580 failed_details: dict[str, Any] = {"error": error}
5581 failed_version = None
5582 if plan is not None:
5583 failed_details = _package_change_details(plan, error=error)
5584 failed_version = plan["package"].get("version")
5585
5586 try:
5587 return object_package_changes.append_package_change(
5588 package_id=package_id,
5589 action="failed",
5590 package_version=failed_version,
5591 actor=_record_change_actor(headers),
5592 message=error,
5593 details=failed_details,
5594 base_dir=_data_dir(),
5595 )
5596 except Exception:
5597 return None
5598
5599
5600def _package_install_changes(
5601 requested_change: Mapping[str, Any] | None,
5602 *,
5603 failed: Mapping[str, Any] | None = None,
5604) -> dict[str, Any | None]:
5605 changes: dict[str, Any | None] = {}
5606 if requested_change is not None:
5607 changes["requested"] = dict(requested_change)
5608 changes["failed"] = dict(failed) if failed is not None else None
5609 return changes
5610
5611
5612def _restore_point_from_package_change(change: Mapping[str, Any]) -> dict[str, Any]:
5613 details = change.get("details")
5614 if not isinstance(details, Mapping):
5615 raise object_backup.BackupRestoreError("Package change has no restore point details")
5616
5617 restore_point = details.get("restore_point")
5618 if not isinstance(restore_point, Mapping):
5619 raise object_backup.BackupRestoreError("Package change has no restore point")
5620
5621 restore_path = restore_point.get("path")
5622 if not isinstance(restore_path, str) or not restore_path.strip() or "\x00" in restore_path:
5623 raise object_backup.BackupRestoreError("Package restore point path is not safe")
5624
5625 candidate = Path(restore_path)
5626 allowed_root = Path(
5627 os.environ.get(object_backup.BACKUPS_DIR_ENV)
5628 or (Path(_data_dir()) / object_backup.BACKUPS_DIR)
5629 )
5630 resolved_candidate = candidate.resolve(strict=False)
5631 resolved_allowed = allowed_root.resolve(strict=False)
5632 try:
5633 resolved_candidate.relative_to(resolved_allowed)
5634 except ValueError as exc:
5635 raise object_backup.BackupRestoreError(
5636 "Package restore point is outside the configured backup directory"
5637 ) from exc
5638
5639 payload = dict(restore_point)
5640 payload["path"] = str(candidate)
5641 return payload
5642
5643
5644def _package_restore_change_details(
5645 from_change: Mapping[str, Any],
5646 restore_point: Mapping[str, Any],
5647 *,
5648 restore: Mapping[str, Any] | None = None,
5649 error: str | None = None,
5650) -> dict[str, Any]:
5651 details: dict[str, Any] = {
5652 "from_change": {
5653 "change_id": from_change.get("change_id"),
5654 "timestamp": from_change.get("timestamp"),
5655 "action": from_change.get("action"),
5656 "package_version": from_change.get("package_version"),
5657 },
5658 "restore_mode": "runtime_snapshot",
5659 "restore_point": dict(restore_point),
5660 }
5661 if restore is not None:
5662 details["restore"] = dict(restore)
5663 if error:
5664 details["error"] = error
5665 return details
5666
5667
5668def _try_append_package_restore_failure(
5669 *,
5670 package_id: str,
5671 from_change: Mapping[str, Any] | None,
5672 restore_point: Mapping[str, Any] | None,
5673 headers: dict[str, str],
5674 error: str,
5675) -> dict[str, Any] | None:
5676 details: dict[str, Any] = {"error": error}
5677 package_version = None
5678 if from_change is not None:
5679 package_version = from_change.get("package_version")
5680 details = _package_restore_change_details(
5681 from_change,
5682 restore_point or {},
5683 error=error,
5684 )
5685
5686 try:
5687 return object_package_changes.append_package_change(
5688 package_id=package_id,
5689 action="failed",
5690 package_version=package_version,
5691 actor=_record_change_actor(headers),
5692 message=error,
5693 details=details,
5694 base_dir=_data_dir(),
5695 )
5696 except Exception:
5697 return None
5698
5699
5700def _package_restore_changes(
5701 *,
5702 failed: Mapping[str, Any] | None = None,
5703) -> dict[str, Any | None]:
5704 return {"failed": dict(failed) if failed is not None else None}
5705
5706
5707async def _handle_object_get(
5708 send,
5709 object_id: str,
5710 query: dict[str, str],
5711 headers: dict[str, str],
5712) -> None:
5713 if "@" in object_id:
5714 await _send_json(
5715 send,
5716 {"status": "error", "error": "Station routing is not available in this server"},
5717 status=400,
5718 )
5719 return
5720
5721 if _is_sensitive_get(query):
5722 gate_error = _admin_token_gate_error(
5723 headers,
5724 f"Object introspection requires {ADMIN_TOKEN_ENV}.",
5725 )
5726 if gate_error is not None:
5727 status, message = gate_error
5728 await _send_json(send, {"status": "error", "error": message}, status=status)
5729 return
5730
5731 if query.get("versions") == "true":
5732 if await _send_permission_denied_if_needed(
5733 send,
5734 headers,
5735 object_permissions.VERSIONS,
5736 object_id=object_id,
5737 method="GET",
5738 ):
5739 return
5740 await _handle_object_versions_get(send, object_id, query)
5741 return
5742
5743 if "version" in query:
5744 if await _send_permission_denied_if_needed(
5745 send,
5746 headers,
5747 object_permissions.VERSIONS,
5748 object_id=object_id,
5749 method="GET",
5750 ):
5751 return
5752 await _handle_object_version_get(send, object_id, query)
5753 return
5754
5755 if query.get("state") == "true":
5756 if await _send_permission_denied_if_needed(
5757 send,
5758 headers,
5759 object_permissions.STATE,
5760 object_id=object_id,
5761 method="GET",
5762 ):
5763 return
5764 await _handle_object_state_get(send, object_id)
5765 return
5766
5767 if query.get("logs") == "true":
5768 if await _send_permission_denied_if_needed(
5769 send,
5770 headers,
5771 object_permissions.LOGS,
5772 object_id=object_id,
5773 method="GET",
5774 ):
5775 return
5776 await _handle_object_logs_get(send, object_id, query)
5777 return
5778
5779 if query.get("source_changes") == "true":
5780 if await _send_permission_denied_if_needed(
5781 send,
5782 headers,
5783 object_permissions.SOURCE,
5784 object_id=object_id,
5785 method="GET",
5786 ):
5787 return
5788 await _handle_object_source_changes_get(send, object_id, query)
5789 return
5790
5791 if query.get("changes") == "true":
5792 if await _send_permission_denied_if_needed(
5793 send,
5794 headers,
5795 object_permissions.SOURCE,
5796 object_id=object_id,
5797 method="GET",
5798 ):
5799 return
5800 await _handle_object_changes_get(send, object_id, query)
5801 return
5802
5803 if query.get("files") == "true":
5804 if await _send_permission_denied_if_needed(
5805 send,
5806 headers,
5807 object_permissions.FILES,
5808 object_id=object_id,
5809 method="GET",
5810 ):
5811 return
5812 await _handle_object_files_get(send, object_id)
5813 return
5814
5815 if "file" in query:
5816 if await _send_permission_denied_if_needed(
5817 send,
5818 headers,
5819 object_permissions.FILES,
5820 object_id=object_id,
5821 method="GET",
5822 ):
5823 return
5824 await _handle_object_file_get(send, object_id, query)
5825 return
5826
5827 if query.get("metadata") == "true":
5828 if await _send_permission_denied_if_needed(
5829 send,
5830 headers,
5831 object_permissions.READ,
5832 object_id=object_id,
5833 method="GET",
5834 ):
5835 return
5836 await _handle_object_metadata_get(send, object_id)
5837 return
5838
5839 if query.get("source") == "true":
5840 if await _send_permission_denied_if_needed(
5841 send,
5842 headers,
5843 object_permissions.SOURCE,
5844 object_id=object_id,
5845 method="GET",
5846 ):
5847 return
5848 await _handle_object_source_get(send, object_id)
5849 return
5850
5851 await _execute_object_method(
5852 send,
5853 object_id,
5854 "GET",
5855 query,
5856 headers,
5857 permission_action=object_permissions.EXECUTE,
5858 )
5859
5860
5861async def _handle_object_source_get(send, object_id: str) -> None:
5862 try:
5863 source = object_source.get_object_source(object_id)
5864 except InvalidObjectIdError as exc:
5865 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5866 return
5867 except object_source.ObjectSourceNotFoundError as exc:
5868 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5869 return
5870
5871 await _send_json(
5872 send,
5873 {
5874 "status": "ok",
5875 "object_id": object_id,
5876 "source": source,
5877 },
5878 )
5879
5880
5881async def _handle_object_state_get(send, object_id: str) -> None:
5882 try:
5883 _ensure_object_source_exists(object_id)
5884 state = object_state.get_object_state(object_id, base_dir=_data_dir())
5885 except InvalidObjectIdError as exc:
5886 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5887 return
5888 except object_source.ObjectSourceNotFoundError as exc:
5889 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5890 return
5891
5892 await _send_json(
5893 send,
5894 {
5895 "status": "ok",
5896 "object_id": object_id,
5897 "state": state,
5898 },
5899 )
5900
5901
5902async def _handle_object_metadata_get(send, object_id: str) -> None:
5903 try:
5904 metadata = object_metadata.get_object_metadata(object_id, base_dir=_data_dir())
5905 except InvalidObjectIdError as exc:
5906 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5907 return
5908 except object_source.ObjectSourceNotFoundError as exc:
5909 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5910 return
5911
5912 await _send_json(
5913 send,
5914 {
5915 "status": "ok",
5916 "object_id": object_id,
5917 "metadata": metadata,
5918 },
5919 )
5920
5921
5922async def _handle_object_logs_get(
5923 send,
5924 object_id: str,
5925 query: dict[str, str],
5926) -> None:
5927 try:
5928 _ensure_object_source_exists(object_id)
5929 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
5930 logs = object_logs.get_object_logs(
5931 object_id,
5932 base_dir=_data_dir(),
5933 level=query.get("level"),
5934 limit=limit,
5935 )
5936 except ValueError as exc:
5937 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5938 return
5939 except InvalidObjectIdError as exc:
5940 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5941 return
5942 except object_source.ObjectSourceNotFoundError as exc:
5943 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5944 return
5945
5946 await _send_json(
5947 send,
5948 {
5949 "status": "ok",
5950 "object_id": object_id,
5951 "logs": logs,
5952 "count": len(logs),
5953 },
5954 )
5955
5956
5957async def _handle_object_source_changes_get(
5958 send,
5959 object_id: str,
5960 query: dict[str, str],
5961) -> None:
5962 try:
5963 _ensure_object_source_exists(object_id)
5964 limit = _query_int(
5965 query,
5966 "limit",
5967 default=100,
5968 minimum=1,
5969 maximum=object_source_changes.MAX_CHANGE_LIMIT,
5970 )
5971 offset = _query_int(
5972 query,
5973 "offset",
5974 default=0,
5975 minimum=0,
5976 maximum=object_source_changes.MAX_CHANGE_LIMIT,
5977 )
5978 payload = object_source_changes.list_source_changes(
5979 object_id,
5980 base_dir=_data_dir(),
5981 limit=limit,
5982 offset=offset,
5983 )
5984 except ValueError as exc:
5985 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5986 return
5987 except InvalidObjectIdError as exc:
5988 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
5989 return
5990 except object_source.ObjectSourceNotFoundError as exc:
5991 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
5992 return
5993
5994 await _send_json(send, {"status": "ok", **payload})
5995
5996
5997async def _handle_object_changes_get(
5998 send,
5999 object_id: str,
6000 query: dict[str, str],
6001) -> None:
6002 try:
6003 _ensure_object_source_exists(object_id)
6004 limit = _query_int(
6005 query,
6006 "limit",
6007 default=100,
6008 minimum=1,
6009 maximum=object_source_changes.MAX_CHANGE_LIMIT,
6010 )
6011 offset = _query_int(
6012 query,
6013 "offset",
6014 default=0,
6015 minimum=0,
6016 maximum=object_source_changes.MAX_CHANGE_LIMIT,
6017 )
6018 payload = _object_changes_payload(object_id, query, limit=limit, offset=offset)
6019 except ValueError as exc:
6020 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6021 return
6022 except InvalidObjectIdError as exc:
6023 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6024 return
6025 except object_file_changes.InvalidFileChangeError as exc:
6026 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6027 return
6028 except object_source.ObjectSourceNotFoundError as exc:
6029 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6030 return
6031 except OSError as exc:
6032 await _send_json(
6033 send,
6034 {"status": "error", "error": f"Could not list object changes: {exc}"},
6035 status=500,
6036 )
6037 return
6038
6039 await _send_json(send, {"status": "ok", **payload})
6040
6041
6042def _object_changes_payload(
6043 object_id: str,
6044 query: dict[str, str],
6045 *,
6046 limit: int,
6047 offset: int,
6048) -> dict[str, Any]:
6049 kind = _admin_change_kind_filter(query)
6050 if kind not in {None, "source", "file"}:
6051 raise ValueError("Object changes only support kind=source or kind=file")
6052
6053 entries: list[dict[str, Any]] = []
6054 if kind in {None, "source"}:
6055 entries.extend(_source_admin_changes(object_id=object_id))
6056 if kind in {None, "file"}:
6057 entries.extend(
6058 _file_admin_changes(
6059 object_id=object_id,
6060 file_name=_admin_change_file_filter(query),
6061 )
6062 )
6063
6064 entries = _sort_admin_changes(entries)
6065 total = len(entries)
6066 window = entries[offset:offset + limit]
6067 return {
6068 "object_id": object_id,
6069 "changes": window,
6070 "count": len(window),
6071 "total": total,
6072 "limit": limit,
6073 "offset": offset,
6074 "has_more": offset + len(window) < total,
6075 }
6076
6077
6078def _admin_changes_payload(
6079 query: dict[str, str],
6080 *,
6081 limit: int,
6082 offset: int,
6083) -> dict[str, Any]:
6084 kind = _admin_change_kind_filter(query)
6085 object_id = _admin_change_object_filter(query)
6086 collection = _admin_change_collection_filter(query)
6087 record_id = _admin_change_record_filter(query)
6088 package_id = _admin_change_package_filter(query)
6089 file_name = _admin_change_file_filter(query)
6090
6091 entries: list[dict[str, Any]] = []
6092 if kind in {None, "source"}:
6093 entries.extend(_source_admin_changes(object_id=object_id))
6094 if kind in {None, "file"}:
6095 entries.extend(_file_admin_changes(object_id=object_id, file_name=file_name))
6096 if kind in {None, "record"}:
6097 entries.extend(_record_admin_changes(collection=collection, record_id=record_id))
6098 if kind in {None, "package"}:
6099 entries.extend(_package_admin_changes(package_id=package_id))
6100
6101 entries = [
6102 entry
6103 for entry in entries
6104 if _admin_change_matches(
6105 entry,
6106 object_id=object_id,
6107 collection=collection,
6108 record_id=record_id,
6109 package_id=package_id,
6110 file_name=file_name,
6111 )
6112 ]
6113 entries = _sort_admin_changes(entries)
6114 total = len(entries)
6115 window = entries[offset:offset + limit]
6116 return {
6117 "changes": window,
6118 "count": len(window),
6119 "total": total,
6120 "limit": limit,
6121 "offset": offset,
6122 "has_more": offset + len(window) < total,
6123 "filters": {
6124 "kind": kind,
6125 "object_id": object_id,
6126 "collection": collection,
6127 "record_id": record_id,
6128 "package_id": package_id,
6129 "file": file_name,
6130 },
6131 }
6132
6133
6134def _source_admin_changes(object_id: str | None = None) -> list[dict[str, Any]]:
6135 changes: list[dict[str, Any]] = []
6136 for candidate in _admin_change_object_ids(
6137 object_source_changes.SOURCE_CHANGES_DIR,
6138 object_id=object_id,
6139 ):
6140 payload = object_source_changes.list_source_changes(
6141 candidate,
6142 base_dir=_data_dir(),
6143 limit=object_source_changes.MAX_CHANGE_LIMIT,
6144 )
6145 changes.extend(_normalize_source_admin_change(change) for change in payload["changes"])
6146 return changes
6147
6148
6149def _file_admin_changes(
6150 object_id: str | None = None,
6151 file_name: str | None = None,
6152) -> list[dict[str, Any]]:
6153 changes: list[dict[str, Any]] = []
6154 for candidate in _admin_change_object_ids(
6155 object_file_changes.FILE_CHANGES_DIR,
6156 object_id=object_id,
6157 ):
6158 payload = object_file_changes.list_file_changes(
6159 candidate,
6160 file_name=file_name,
6161 base_dir=_data_dir(),
6162 limit=object_file_changes.MAX_CHANGE_LIMIT,
6163 )
6164 changes.extend(_normalize_file_admin_change(change) for change in payload["changes"])
6165 return changes
6166
6167
6168def _record_admin_changes(
6169 collection: str | None = None,
6170 record_id: str | None = None,
6171) -> list[dict[str, Any]]:
6172 changes: list[dict[str, Any]] = []
6173 for candidate in _admin_change_collections(collection=collection):
6174 payload = object_record_changes.list_record_changes(
6175 candidate,
6176 record_id=record_id,
6177 base_dir=_data_dir(),
6178 limit=object_record_changes.MAX_CHANGE_LIMIT,
6179 )
6180 changes.extend(_normalize_record_admin_change(change) for change in payload["changes"])
6181 return changes
6182
6183
6184def _package_admin_changes(package_id: str | None = None) -> list[dict[str, Any]]:
6185 changes: list[dict[str, Any]] = []
6186 for candidate in _admin_change_package_ids(package_id=package_id):
6187 payload = object_package_changes.list_package_changes(
6188 candidate,
6189 base_dir=_data_dir(),
6190 limit=object_package_changes.MAX_CHANGE_LIMIT,
6191 )
6192 changes.extend(_normalize_package_admin_change(change) for change in payload["changes"])
6193 return changes
6194
6195
6196def _admin_change_object_ids(
6197 change_dir: str,
6198 *,
6199 object_id: str | None,
6200) -> list[str]:
6201 if object_id is not None:
6202 if not validate_object_id(object_id):
6203 raise InvalidObjectIdError(f"Invalid object ID: {object_id}")
6204 return [object_id]
6205
6206 root = Path(_data_dir()) / change_dir
6207 if not root.exists():
6208 return []
6209 if not root.is_dir():
6210 raise OSError(f"Change root is not a directory: {root}")
6211 return sorted(
6212 path.name
6213 for path in root.iterdir()
6214 if path.is_dir() and validate_object_id(path.name)
6215 )
6216
6217
6218def _admin_change_collections(*, collection: str | None) -> list[str]:
6219 if collection is not None:
6220 if not object_collections.validate_collection_name(collection):
6221 raise object_collections.InvalidCollectionNameError(
6222 f"Invalid collection name: {collection}"
6223 )
6224 return [collection]
6225
6226 root = Path(_data_dir()) / object_record_changes.RECORD_CHANGES_DIR
6227 if not root.exists():
6228 return []
6229 if not root.is_dir():
6230 raise OSError(f"Change root is not a directory: {root}")
6231 return sorted(
6232 path.name
6233 for path in root.iterdir()
6234 if path.is_dir() and object_collections.validate_collection_name(path.name)
6235 )
6236
6237
6238def _admin_change_package_ids(*, package_id: str | None) -> list[str]:
6239 if package_id is not None:
6240 if not object_packages.validate_package_id(package_id):
6241 raise object_packages.InvalidPackageIdError(f"Invalid package id: {package_id}")
6242 return [package_id]
6243
6244 root = Path(_data_dir()) / object_package_changes.PACKAGE_CHANGES_DIR
6245 if not root.exists():
6246 return []
6247 if not root.is_dir():
6248 raise OSError(f"Change root is not a directory: {root}")
6249 return sorted(
6250 path.name
6251 for path in root.iterdir()
6252 if path.is_dir() and object_packages.validate_package_id(path.name)
6253 )
6254
6255
6256def _admin_change_kind_filter(query: dict[str, str]) -> str | None:
6257 kind = _optional_query_text(query, "kind")
6258 if kind is None:
6259 return None
6260 if kind not in ADMIN_CHANGE_KINDS:
6261 allowed = ", ".join(sorted(ADMIN_CHANGE_KINDS))
6262 raise ValueError(f"Query parameter 'kind' must be one of: {allowed}")
6263 return kind
6264
6265
6266def _admin_change_object_filter(query: dict[str, str]) -> str | None:
6267 object_id = _optional_query_text(query, "object_id")
6268 if object_id is not None and not validate_object_id(object_id):
6269 raise InvalidObjectIdError(f"Invalid object ID: {object_id}")
6270 return object_id
6271
6272
6273def _admin_change_collection_filter(query: dict[str, str]) -> str | None:
6274 collection = _optional_query_text(query, "collection")
6275 if collection is not None and not object_collections.validate_collection_name(collection):
6276 raise object_collections.InvalidCollectionNameError(
6277 f"Invalid collection name: {collection}"
6278 )
6279 return collection
6280
6281
6282def _admin_change_record_filter(query: dict[str, str]) -> str | None:
6283 record_id = _optional_query_text(query, "record_id")
6284 if record_id is not None and not object_records.validate_record_id(record_id):
6285 raise object_records.InvalidRecordIdError(f"Invalid record id: {record_id}")
6286 return record_id
6287
6288
6289def _admin_change_package_filter(query: dict[str, str]) -> str | None:
6290 package_id = _optional_query_text(query, "package_id")
6291 if package_id is not None and not object_packages.validate_package_id(package_id):
6292 raise object_packages.InvalidPackageIdError(f"Invalid package id: {package_id}")
6293 return package_id
6294
6295
6296def _admin_change_file_filter(query: dict[str, str]) -> str | None:
6297 file_name = _optional_query_text(query, "file")
6298 if file_name is None:
6299 return None
6300 if "\x00" in file_name or file_name.startswith("/") or ".." in file_name:
6301 raise object_file_changes.InvalidFileChangeError(f"Invalid file name: {file_name!r}")
6302 path = Path(file_name)
6303 if path.is_absolute() or any(part in {"", ".", ".."} for part in path.parts):
6304 raise object_file_changes.InvalidFileChangeError(f"Invalid file name: {file_name!r}")
6305 return path.as_posix()
6306
6307
6308def _admin_change_matches(
6309 entry: dict[str, Any],
6310 *,
6311 object_id: str | None,
6312 collection: str | None,
6313 record_id: str | None,
6314 package_id: str | None,
6315 file_name: str | None,
6316) -> bool:
6317 target = entry.get("target", {})
6318 if not isinstance(target, dict):
6319 return False
6320 if object_id is not None and target.get("object_id") != object_id:
6321 return False
6322 if collection is not None and target.get("collection") != collection:
6323 return False
6324 if record_id is not None and target.get("record_id") != record_id:
6325 return False
6326 if package_id is not None and target.get("package_id") != package_id:
6327 return False
6328 if file_name is not None and target.get("file_name") != file_name:
6329 return False
6330 return True
6331
6332
6333def _sort_admin_changes(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
6334 return sorted(
6335 entries,
6336 key=lambda entry: (
6337 str(entry.get("timestamp") or ""),
6338 str(entry.get("change_id") or ""),
6339 ),
6340 reverse=True,
6341 )
6342
6343
6344def _normalize_source_admin_change(change: Mapping[str, Any]) -> dict[str, Any]:
6345 return {
6346 "kind": "source",
6347 "change_id": change.get("change_id"),
6348 "timestamp": change.get("timestamp"),
6349 "action": change.get("action"),
6350 "actor": change.get("actor"),
6351 "summary": change.get("message") or _source_change_summary(change),
6352 "correlation_id": change.get("correlation_id"),
6353 "target": {
6354 "object_id": change.get("object_id"),
6355 "version_id": change.get("version_id"),
6356 "from_version_id": change.get("from_version_id"),
6357 },
6358 "change": dict(change),
6359 }
6360
6361
6362def _normalize_file_admin_change(change: Mapping[str, Any]) -> dict[str, Any]:
6363 return {
6364 "kind": "file",
6365 "change_id": change.get("change_id"),
6366 "timestamp": change.get("timestamp"),
6367 "action": change.get("action"),
6368 "actor": change.get("actor"),
6369 "summary": change.get("message") or _file_change_summary(change),
6370 "correlation_id": change.get("correlation_id"),
6371 "target": {
6372 "object_id": change.get("object_id"),
6373 "file_name": change.get("file_name"),
6374 "file_size": change.get("file_size"),
6375 },
6376 "change": dict(change),
6377 }
6378
6379
6380def _normalize_record_admin_change(change: Mapping[str, Any]) -> dict[str, Any]:
6381 return {
6382 "kind": "record",
6383 "change_id": change.get("change_id"),
6384 "timestamp": change.get("timestamp"),
6385 "action": change.get("action"),
6386 "actor": change.get("actor"),
6387 "summary": change.get("message") or _record_change_summary(change),
6388 "correlation_id": change.get("correlation_id"),
6389 "target": {
6390 "collection": change.get("collection"),
6391 "record_id": change.get("record_id"),
6392 "changed_fields": change.get("changed_fields", []),
6393 },
6394 "change": dict(change),
6395 }
6396
6397
6398def _normalize_package_admin_change(change: Mapping[str, Any]) -> dict[str, Any]:
6399 return {
6400 "kind": "package",
6401 "change_id": change.get("change_id"),
6402 "timestamp": change.get("timestamp"),
6403 "action": change.get("action"),
6404 "actor": change.get("actor"),
6405 "summary": change.get("message") or _package_change_summary(change),
6406 "correlation_id": change.get("correlation_id"),
6407 "target": {
6408 "package_id": change.get("package_id"),
6409 "package_version": change.get("package_version"),
6410 },
6411 "change": dict(change),
6412 }
6413
6414
6415def _source_change_summary(change: Mapping[str, Any]) -> str:
6416 return f"{change.get('action', 'source_change')} {change.get('object_id', '')}".strip()
6417
6418
6419def _file_change_summary(change: Mapping[str, Any]) -> str:
6420 return f"{change.get('action', 'file_change')} {change.get('file_name', '')}".strip()
6421
6422
6423def _record_change_summary(change: Mapping[str, Any]) -> str:
6424 return (
6425 f"{change.get('action', 'record_change')} "
6426 f"{change.get('collection', '')}/{change.get('record_id', '')}"
6427 ).strip()
6428
6429
6430def _package_change_summary(change: Mapping[str, Any]) -> str:
6431 return f"{change.get('action', 'package_change')} {change.get('package_id', '')}".strip()
6432
6433
6434async def _handle_object_files_get(send, object_id: str) -> None:
6435 try:
6436 _ensure_object_source_exists(object_id)
6437 files = object_files.list_object_files(object_id, base_dir=_data_dir())
6438 except InvalidObjectIdError as exc:
6439 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6440 return
6441 except object_source.ObjectSourceNotFoundError as exc:
6442 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6443 return
6444 except OSError as exc:
6445 await _send_json(
6446 send,
6447 {"status": "error", "error": f"Could not read object files: {exc}"},
6448 status=500,
6449 )
6450 return
6451
6452 await _send_json(
6453 send,
6454 {
6455 "status": "ok",
6456 "object_id": object_id,
6457 "files": files,
6458 "count": len(files),
6459 },
6460 )
6461
6462
6463async def _handle_object_file_get(
6464 send,
6465 object_id: str,
6466 query: dict[str, str],
6467) -> None:
6468 filename = query.get("file", "")
6469 try:
6470 _ensure_object_source_exists(object_id)
6471 content, metadata = object_files.read_object_file(
6472 object_id,
6473 filename,
6474 base_dir=_data_dir(),
6475 )
6476 except object_files.InvalidObjectFilenameError as exc:
6477 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6478 return
6479 except InvalidObjectIdError as exc:
6480 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6481 return
6482 except object_source.ObjectSourceNotFoundError as exc:
6483 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6484 return
6485 except object_files.ObjectFileNotFoundError as exc:
6486 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6487 return
6488 except OSError as exc:
6489 await _send_json(
6490 send,
6491 {"status": "error", "error": f"Could not read object file: {exc}"},
6492 status=500,
6493 )
6494 return
6495
6496 content_type, _ = mimetypes.guess_type(metadata["name"])
6497 if content_type is None:
6498 content_type = "application/octet-stream"
6499
6500 disposition = "inline" if content_type.startswith("image/") else "attachment"
6501 download_name = _download_filename(metadata["name"])
6502 await _send_response(
6503 send,
6504 status=200,
6505 headers=[
6506 ("content-type", content_type),
6507 ("content-length", str(len(content))),
6508 ("content-disposition", f'{disposition}; filename="{download_name}"'),
6509 ],
6510 body=content,
6511 )
6512
6513
6514async def _handle_object_versions_get(
6515 send,
6516 object_id: str,
6517 query: dict[str, str],
6518) -> None:
6519 try:
6520 _ensure_object_source_exists(object_id)
6521 limit = _query_int(query, "limit", default=10, minimum=1, maximum=100)
6522 versions = _version_manager().get_history(object_id, limit=limit)
6523 except ValueError as exc:
6524 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6525 return
6526 except InvalidObjectIdError as exc:
6527 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6528 return
6529 except object_source.ObjectSourceNotFoundError as exc:
6530 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6531 return
6532
6533 await _send_json(
6534 send,
6535 {
6536 "status": "ok",
6537 "object_id": object_id,
6538 "versions": versions,
6539 "count": len(versions),
6540 },
6541 )
6542
6543
6544async def _handle_object_version_get(
6545 send,
6546 object_id: str,
6547 query: dict[str, str],
6548) -> None:
6549 try:
6550 _ensure_object_source_exists(object_id)
6551 version_id = _query_int(query, "version", minimum=1)
6552 version = _version_manager().get_version(object_id, version_id)
6553 except ValueError as exc:
6554 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6555 return
6556 except InvalidObjectIdError as exc:
6557 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6558 return
6559 except object_source.ObjectSourceNotFoundError as exc:
6560 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6561 return
6562
6563 if version is None:
6564 await _send_json(
6565 send,
6566 {"status": "error", "error": f"Version {version_id} not found for object {object_id}"},
6567 status=404,
6568 )
6569 return
6570
6571 await _send_json(
6572 send,
6573 {
6574 "status": "ok",
6575 "object_id": object_id,
6576 "version": version,
6577 },
6578 )
6579
6580
6581async def _handle_object_post(
6582 send,
6583 object_id: str,
6584 body: bytes,
6585 query: dict[str, str],
6586 headers: dict[str, str],
6587) -> None:
6588 if "@" in object_id:
6589 await _send_json(
6590 send,
6591 {"status": "error", "error": "Station routing is not available in this server"},
6592 status=400,
6593 )
6594 return
6595
6596 try:
6597 payload = _parse_post_payload(body, query, headers)
6598 except ValueError as exc:
6599 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6600 return
6601
6602 if payload.get("action") == "rollback":
6603 await _handle_object_rollback_post(send, object_id, payload, headers)
6604 return
6605
6606 await _execute_object_method(
6607 send,
6608 object_id,
6609 "POST",
6610 payload,
6611 headers,
6612 permission_action=object_permissions.EXECUTE,
6613 )
6614
6615
6616async def _handle_object_body_method(
6617 send,
6618 object_id: str,
6619 method: str,
6620 body: bytes,
6621 query: dict[str, str],
6622 headers: dict[str, str],
6623) -> None:
6624 if "@" in object_id:
6625 await _send_json(
6626 send,
6627 {"status": "error", "error": "Station routing is not available in this server"},
6628 status=400,
6629 )
6630 return
6631
6632 try:
6633 if body.strip() and _is_form_content_type(headers):
6634 payload: dict[str, Any] = _form_fields_payload(body)
6635 elif body.strip() and _is_multipart_content_type(headers):
6636 payload = object_multipart.parse_multipart(body, headers.get("content-type", ""))
6637 elif body.strip():
6638 payload = _parse_json_body(body)
6639 else:
6640 payload = dict(query)
6641 except ValueError as exc:
6642 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6643 return
6644
6645 permission_action = object_permissions.EXECUTE
6646 if method == "PUT":
6647 permission_action = object_permissions.UPDATE
6648 elif method == "DELETE":
6649 permission_action = object_permissions.DELETE
6650
6651 await _execute_object_method(
6652 send,
6653 object_id,
6654 method,
6655 payload,
6656 headers,
6657 permission_action=permission_action,
6658 )
6659
6660
6661async def _handle_object_rollback_post(
6662 send,
6663 object_id: str,
6664 payload: dict[str, Any],
6665 headers: dict[str, str],
6666) -> None:
6667 gate_error = _source_write_gate_error(headers)
6668 if gate_error is not None:
6669 status, message = gate_error
6670 await _send_json(send, {"status": "error", "error": message}, status=status)
6671 return
6672
6673 if await _send_permission_denied_if_needed(
6674 send,
6675 headers,
6676 object_permissions.SOURCE,
6677 object_id=object_id,
6678 method="POST",
6679 ):
6680 return
6681
6682 try:
6683 version_id = _payload_int(payload, "version_id", minimum=1)
6684 author = _payload_text(payload, "author", _source_actor_from_headers(headers))
6685 message = _payload_text(payload, "message", f"Rollback to version {version_id}")
6686 correlation_id = object_correlation.current_correlation_id()
6687 new_version_id = object_source.rollback_object_source(
6688 object_id=object_id,
6689 to_version=version_id,
6690 author=author,
6691 message=message,
6692 version_manager=_version_manager(),
6693 correlation_id=correlation_id,
6694 )
6695 except ValueError as exc:
6696 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6697 return
6698 except InvalidObjectIdError as exc:
6699 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6700 return
6701 except object_source.ObjectSourceNotFoundError as exc:
6702 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6703 return
6704 except object_versions.VersionNotFoundError as exc:
6705 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6706 return
6707
6708 object_handlers.invalidate()
6709
6710 await _send_json(
6711 send,
6712 {
6713 "status": "ok",
6714 "message": f"Rolled back to version {version_id}",
6715 "version_id": version_id,
6716 "new_version_id": new_version_id,
6717 "object_id": object_id,
6718 "correlation_id": object_correlation.current_correlation_id(),
6719 },
6720 )
6721 _append_source_change_log(
6722 object_id,
6723 action="source_rollback",
6724 version_id=new_version_id,
6725 from_version_id=version_id,
6726 actor=author,
6727 message=message,
6728 correlation_id=correlation_id,
6729 )
6730
6731
6732async def _handle_object_source_put(
6733 send,
6734 object_id: str,
6735 body: bytes,
6736 headers: dict[str, str],
6737) -> None:
6738 if "@" in object_id:
6739 await _send_json(
6740 send,
6741 {"status": "error", "error": "Station routing is not available in this server"},
6742 status=400,
6743 )
6744 return
6745
6746 gate_error = _source_write_gate_error(headers)
6747 if gate_error is not None:
6748 status, message = gate_error
6749 await _send_json(send, {"status": "error", "error": message}, status=status)
6750 return
6751
6752 if await _send_permission_denied_if_needed(
6753 send,
6754 headers,
6755 object_permissions.SOURCE,
6756 object_id=object_id,
6757 method="PUT",
6758 ):
6759 return
6760
6761 try:
6762 payload = _parse_json_body(body)
6763 except ValueError as exc:
6764 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6765 return
6766
6767 code = payload.get("code")
6768 if not isinstance(code, str):
6769 await _send_json(
6770 send,
6771 {"status": "error", "error": "Request JSON field 'code' must be a string"},
6772 status=400,
6773 )
6774 return
6775
6776 author = _payload_text(payload, "author", _source_actor_from_headers(headers))
6777 message = _payload_text(payload, "message", "Updated via API")
6778 correlation_id = object_correlation.current_correlation_id()
6779
6780 try:
6781 version_id = object_source.update_object_source(
6782 object_id=object_id,
6783 new_code=code,
6784 author=author,
6785 message=message,
6786 version_manager=_version_manager(),
6787 correlation_id=correlation_id,
6788 )
6789 except InvalidObjectIdError as exc:
6790 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6791 return
6792 except object_source.ObjectSourceNotFoundError as exc:
6793 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
6794 return
6795
6796 object_handlers.invalidate()
6797
6798 methods, method_warnings = object_source.source_method_report(code)
6799 await _send_json(
6800 send,
6801 {
6802 "status": "ok",
6803 "message": f"Code updated to version {version_id}",
6804 "version_id": version_id,
6805 "object_id": object_id,
6806 "methods": methods,
6807 "warnings": method_warnings,
6808 "correlation_id": object_correlation.current_correlation_id(),
6809 },
6810 )
6811 _append_source_change_log(
6812 object_id,
6813 action="source_update",
6814 version_id=version_id,
6815 actor=author,
6816 message=message,
6817 correlation_id=correlation_id,
6818 )
6819
6820
6821async def _execute_object_method(
6822 send,
6823 object_id: str,
6824 method: str,
6825 payload: dict[str, Any],
6826 headers: dict[str, str],
6827 *,
6828 permission_action: str,
6829) -> None:
6830 if await _send_permission_denied_if_needed(
6831 send,
6832 headers,
6833 permission_action,
6834 object_id=object_id,
6835 method=method,
6836 ):
6837 return
6838
6839 execution_limit = _max_concurrent_executions()
6840 execution_token = _execution_limiter.try_acquire(execution_limit)
6841 if execution_token is None:
6842 await _send_capacity_error(
6843 send,
6844 limit_name="object_executions",
6845 max_concurrent=execution_limit,
6846 )
6847 return
6848
6849 execution_request = object_execution.ObjectExecutionRequest(
6850 object_id=object_id,
6851 method=method,
6852 payload=_payload_with_identity(payload, headers),
6853 correlation_id=object_correlation.current_correlation_id(),
6854 )
6855 timeout_seconds = _object_timeout_seconds()
6856
6857 try:
6858 if timeout_seconds > 0 and not _object_runs_in_process(object_id):
6859 pool = await _get_worker_pool()
6860 if pool is not None:
6861 result = await pool.execute(
6862 execution_request,
6863 timeout_seconds=timeout_seconds,
6864 )
6865 else:
6866 result = object_execution.execute_python_object_subprocess(
6867 execution_request,
6868 timeout_seconds=timeout_seconds,
6869 )
6870 else:
6871 result = object_execution.execute_object(_runtime, execution_request)
6872 _append_execution_log(result)
6873 finally:
6874 execution_token.release()
6875
6876 if result.ok:
6877 await _send_object_response(send, result.result)
6878 return
6879
6880 _append_ops_execution_error(object_id, method, result, headers)
6881 await _send_execution_error(send, result)
6882
6883
6884def _payload_with_identity(
6885 payload: dict[str, Any],
6886 headers: dict[str, str],
6887) -> dict[str, Any]:
6888 subject, auth_method = _permission_identity(headers)
6889 request_payload = dict(payload)
6890 request_payload["_identity"] = {
6891 "user_id": subject.user_id,
6892 "account_id": subject.account_id,
6893 "roles": list(subject.roles),
6894 "subscriptions": list(subject.subscriptions),
6895 "auth_method": auth_method,
6896 }
6897 return request_payload
6898
6899
6900def _list_objects_payload() -> dict[str, Any]:
6901 objects = [_object_source_payload(source) for source in iter_object_sources()]
6902 return {
6903 "status": "ok",
6904 "objects": objects,
6905 "count": len(objects),
6906 }
6907
6908
6909async def _handle_objects_post(send, body: bytes, headers: dict[str, str]) -> None:
6910 gate_error = _source_write_gate_error(headers)
6911 if gate_error is not None:
6912 status, message = gate_error
6913 await _send_json(send, {"status": "error", "error": message}, status=status)
6914 return
6915
6916 try:
6917 payload = _parse_json_body(body)
6918 object_id = _created_object_id(payload, headers)
6919 except ValueError as exc:
6920 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6921 return
6922
6923 if await _send_permission_denied_if_needed(
6924 send,
6925 headers,
6926 object_permissions.SOURCE,
6927 object_id=object_id,
6928 method="POST",
6929 ):
6930 return
6931
6932 code = payload.get("code")
6933 if not isinstance(code, str):
6934 await _send_json(
6935 send,
6936 {"status": "error", "error": "Request JSON field 'code' must be a string"},
6937 status=400,
6938 )
6939 return
6940
6941 author = _payload_text(payload, "author", _source_actor_from_headers(headers))
6942 message = _payload_text(payload, "message", "Created via API")
6943 correlation_id = object_correlation.current_correlation_id()
6944
6945 try:
6946 version_id = object_source.create_object_source(
6947 object_id=object_id,
6948 code=code,
6949 author=author,
6950 message=message,
6951 version_manager=_version_manager(),
6952 correlation_id=correlation_id,
6953 )
6954 except InvalidObjectIdError as exc:
6955 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
6956 return
6957 except object_source.ObjectSourceExistsError as exc:
6958 await _send_json(send, {"status": "error", "error": str(exc)}, status=409)
6959 return
6960
6961 object_handlers.invalidate()
6962
6963 _append_source_change_log(
6964 object_id,
6965 action="source_create",
6966 version_id=version_id,
6967 actor=author,
6968 message=message,
6969 correlation_id=correlation_id,
6970 details={"description": _payload_text(payload, "description", "")},
6971 )
6972
6973 methods, method_warnings = object_source.source_method_report(code)
6974 await _send_json(
6975 send,
6976 {
6977 "status": "ok",
6978 "message": f"Object created: {object_id}",
6979 "object_id": object_id,
6980 "version_id": version_id,
6981 "methods": methods,
6982 "warnings": method_warnings,
6983 "correlation_id": object_correlation.current_correlation_id(),
6984 },
6985 status=201,
6986 )
6987
6988
6989USER_FILES_ENABLED_ENV = "DBBASIC_ENABLE_USER_FILES"
6990USER_FILES_QUOTA_ENV = "DBBASIC_USER_FILES_QUOTA_BYTES"
6991DEFAULT_USER_FILES_QUOTA = 104_857_600
6992USER_FILES_COLLECTION = "files"
6993_INLINE_CONTENT_TYPES = frozenset(
6994 {"image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf", "text/plain"}
6995)
6996
6997
6998async def _handle_user_file_upload(
6999 send,
7000 method: str,
7001 body: bytes,
7002 headers: dict[str, str],
7003) -> None:
7004 """Accept one multipart upload; bytes to disk, metadata to the files collection.
7005
7006 The metadata record is the authority: owner_id comes from the session
7007 (unspoofable), size and content type are measured server-side, and the
7008 create is permission-checked like any record write. Quotas count real
7009 bytes on disk.
7010 """
7011 if method != "POST":
7012 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
7013 return
7014 if not _env_enabled(USER_FILES_ENABLED_ENV):
7015 await _send_json(
7016 send,
7017 {"status": "error", "error": f"User files are disabled. Set {USER_FILES_ENABLED_ENV}=true."},
7018 status=403,
7019 )
7020 return
7021 session = _current_identity_session(headers)
7022 if session is None:
7023 await _send_json(
7024 send, {"status": "error", "error": "File uploads require a signed-in session."}, status=401
7025 )
7026 return
7027 if (
7028 _session_cookie_token(headers)
7029 and not _authorization_token(headers)
7030 and not _cookie_request_origin_allowed(headers)
7031 ):
7032 await _send_json(
7033 send,
7034 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
7035 status=403,
7036 )
7037 return
7038
7039 content_type = headers.get("content-type", "")
7040 if not object_multipart.is_multipart_content_type(content_type):
7041 await _send_json(
7042 send,
7043 {"status": "error", "error": "Upload must be multipart/form-data with a file field."},
7044 status=400,
7045 )
7046 return
7047 try:
7048 payload = object_multipart.parse_multipart(body, content_type)
7049 except object_multipart.InvalidMultipartError as exc:
7050 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
7051 return
7052
7053 uploads = payload.get("_files") or {}
7054 upload = uploads.get("file") or next(iter(uploads.values()), None)
7055 if upload is None:
7056 await _send_json(
7057 send, {"status": "error", "error": "Upload needs a file form field."}, status=400
7058 )
7059 return
7060
7061 content = base64.b64decode(upload.get("content_base64", ""))
7062 fields = {
7063 "description": str(payload.get("description") or "")[:300],
7064 "is_public": str(payload.get("is_public") or "false"),
7065 }
7066 if payload.get("project_id"):
7067 fields["project_id"] = str(payload["project_id"])
7068 # Polymorphic attachment: a file uploaded from a record's detail carries
7069 # the (parent_collection, parent_id) pair the attachments capability uses,
7070 # so any collection can hold files without a dedicated FK column. Set from
7071 # the upload form (the widget supplies them); owner_id stays session-set.
7072 for _pk in ("parent_collection", "parent_id"):
7073 if payload.get(_pk):
7074 fields[_pk] = str(payload[_pk])[:120]
7075
7076 stored = await _create_user_file(
7077 send,
7078 headers,
7079 owner_id=session.user_id,
7080 filename=upload.get("filename") or "unnamed",
7081 content=content,
7082 content_type=upload.get("content_type") or "application/octet-stream",
7083 fields=fields,
7084 )
7085 if stored is None:
7086 return
7087 await _send_json(send, {"status": "ok", "file": stored, "url": f"/api/files/{stored['id']}"}, status=201)
7088
7089
7090def _user_files_quota_error(owner_id: str, adding: int, freeing: int = 0) -> str | None:
7091 """The quota refusal for storing ``adding`` bytes (after ``freeing`` the
7092 bytes being replaced), or None when it fits. Counts bytes on disk."""
7093 quota = _env_int(USER_FILES_QUOTA_ENV, DEFAULT_USER_FILES_QUOTA)
7094 used = object_user_files.usage_bytes(owner_id, base_dir=_data_dir())
7095 total = used - freeing + adding
7096 if total > quota:
7097 return f"Storage quota exceeded: {total} of {quota} bytes."
7098 return None
7099
7100
7101async def _create_user_file(
7102 send,
7103 headers: dict[str, str],
7104 *,
7105 owner_id: str,
7106 filename: str,
7107 content: bytes,
7108 content_type: str,
7109 fields: dict[str, str] | None = None,
7110) -> dict[str, Any] | None:
7111 """Store one new file: quota, the metadata record (permission-checked
7112 and hooked like any create), then the bytes.
7113
7114 Returns the stored record, or None when a response has already been
7115 sent. Shared by the multipart upload and WebDAV PUT/COPY, so the two
7116 ways in cannot drift apart on quota, gates or what a record holds.
7117 """
7118 quota_error = _user_files_quota_error(owner_id, len(content))
7119 if quota_error is not None:
7120 await _send_json(
7121 send,
7122 {"status": "error", "error": quota_error, "code": "quota_exceeded"},
7123 status=413,
7124 )
7125 return None
7126
7127 file_id = object_ids.new_uuid4()
7128 record = {
7129 "id": file_id,
7130 "filename": filename[:255],
7131 "content_type": content_type or "application/octet-stream",
7132 "size": str(len(content)),
7133 "description": "",
7134 "is_public": "false",
7135 "owner_id": owner_id,
7136 }
7137 record.update(fields or {})
7138
7139 permission_check = await _authorize_collection_write(
7140 send,
7141 headers,
7142 object_permissions.CREATE,
7143 collection=USER_FILES_COLLECTION,
7144 method="POST",
7145 record=record,
7146 gate_message=f"Collection record writes require {ADMIN_TOKEN_ENV}.",
7147 )
7148 if permission_check is None:
7149 return None
7150
7151 hooked = await _apply_before_write_hook(
7152 send,
7153 headers,
7154 collection=USER_FILES_COLLECTION,
7155 action="create",
7156 record=record,
7157 existing=None,
7158 changes=record,
7159 )
7160 if hooked is None:
7161 return None
7162 record = hooked
7163
7164 try:
7165 stored = object_records.create_collection_record(
7166 USER_FILES_COLLECTION, record, base_dir=_data_dir(), actor=_record_change_actor(headers)
7167 )
7168 except object_collections.CollectionNotFoundError:
7169 await _send_json(
7170 send,
7171 {"status": "error", "error": "The files collection is not installed (app-files package)."},
7172 status=404,
7173 )
7174 return None
7175 except ValueError as exc:
7176 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
7177 return None
7178
7179 object_user_files.save_file(owner_id, file_id, content, base_dir=_data_dir())
7180 return stored
7181
7182
7183def _share_target_record(collection: str, record_id: str) -> dict[str, str] | None:
7184 try:
7185 return object_records.get_collection_record(collection, record_id, base_dir=_data_dir())
7186 except (LookupError, ValueError, object_collections.CollectionNotFoundError,
7187 object_collections.InvalidCollectionNameError):
7188 return None
7189
7190
7191async def _handle_share(send, method: str, query, body: bytes, headers: dict[str, str]) -> None:
7192 """List or create record-access grants.
7193
7194 The authorization that a row_filter can't express: creating a grant is
7195 checked against the TARGET record's ownership (a cross-collection fact), so
7196 only the record's owner (or an admin) can share it. Grants are written here,
7197 server-side -- there is no create rule on record_shares, so this is the ONLY
7198 path that mints one. That's what keeps sharing from being self-serve
7199 privilege escalation.
7200 """
7201 subject = _permission_subject(headers)
7202 requester = subject.user_id
7203 if requester is None:
7204 await _send_json(send, {"status": "error", "error": "Sharing requires a signed-in session."}, status=401)
7205 return
7206 is_admin = "admin" in (subject.roles or ())
7207
7208 if method == "GET":
7209 collection = str(query.get("collection") or "").strip()
7210 record_id = str(query.get("record_id") or "").strip()
7211 if not collection or not record_id:
7212 await _send_json(send, {"status": "error", "error": "collection and record_id are required."}, status=400)
7213 return
7214 target = _share_target_record(collection, record_id)
7215 if target is None:
7216 await _send_json(send, {"status": "error", "error": "Record not found."}, status=404)
7217 return
7218 if not is_admin and target.get("owner_id") != requester:
7219 await _send_json(send, {"status": "error", "error": "Only the record's owner can view its shares."}, status=403)
7220 return
7221 grants = [
7222 r for r in _read_records_or_empty(RECORD_SHARES_COLLECTION)
7223 if r.get("collection") == collection and r.get("record_id") == record_id
7224 ]
7225 await _send_json(send, {"status": "ok", "shares": grants})
7226 return
7227
7228 if method != "POST":
7229 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
7230 return
7231
7232 if (
7233 _session_cookie_token(headers)
7234 and not _authorization_token(headers)
7235 and not _cookie_request_origin_allowed(headers)
7236 ):
7237 await _send_json(send, {"status": "error", "error": "Cross-origin cookie writes are not allowed."}, status=403)
7238 return
7239
7240 payload = _parse_json_body(body) or {}
7241 collection = str(payload.get("collection") or "").strip()
7242 record_id = str(payload.get("record_id") or "").strip()
7243 grantee = str(payload.get("user_id") or "").strip()
7244 permission = "write" if str(payload.get("permission") or "read").strip() == "write" else "read"
7245 if not collection or not record_id or not grantee:
7246 await _send_json(send, {"status": "error", "error": "collection, record_id and user_id are required."}, status=400)
7247 return
7248 target = _share_target_record(collection, record_id)
7249 if target is None:
7250 await _send_json(send, {"status": "error", "error": "Record not found."}, status=404)
7251 return
7252 if not is_admin and target.get("owner_id") != requester:
7253 await _send_json(send, {"status": "error", "error": "Only the record's owner can share it."}, status=403)
7254 return
7255 grant = {
7256 "id": object_ids.new_uuid4(),
7257 "collection": collection,
7258 "record_id": record_id,
7259 "user_id": grantee,
7260 "permission": permission,
7261 "granted_by": requester,
7262 }
7263 try:
7264 stored = object_records.create_collection_record(
7265 RECORD_SHARES_COLLECTION, grant, base_dir=_data_dir(),
7266 actor=_record_change_actor(headers), preserve_read_only=True,
7267 )
7268 except object_collections.CollectionNotFoundError:
7269 await _send_json(send, {"status": "error", "error": "The record_shares collection is not installed (app-share)."}, status=404)
7270 return
7271 except ValueError as exc:
7272 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
7273 return
7274 await _send_json(send, {"status": "ok", "share": stored}, status=201)
7275
7276
7277async def _handle_share_revoke(send, method: str, grant_id: str, headers: dict[str, str]) -> None:
7278 """Revoke one grant. Authorized for the record's owner, the original
7279 granter, or an admin -- the same target-ownership check as creating one."""
7280 if method != "DELETE":
7281 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
7282 return
7283 subject = _permission_subject(headers)
7284 requester = subject.user_id
7285 if requester is None:
7286 await _send_json(send, {"status": "error", "error": "Sharing requires a signed-in session."}, status=401)
7287 return
7288 if (
7289 _session_cookie_token(headers)
7290 and not _authorization_token(headers)
7291 and not _cookie_request_origin_allowed(headers)
7292 ):
7293 await _send_json(send, {"status": "error", "error": "Cross-origin cookie writes are not allowed."}, status=403)
7294 return
7295 if not grant_id or "/" in grant_id:
7296 await _send_json(send, {"status": "error", "error": "Invalid grant id"}, status=400)
7297 return
7298 try:
7299 grant = object_records.get_collection_record(RECORD_SHARES_COLLECTION, grant_id, base_dir=_data_dir())
7300 except (LookupError, ValueError):
7301 grant = None
7302 if grant is None:
7303 await _send_json(send, {"status": "error", "error": "Grant not found."}, status=404)
7304 return
7305 is_admin = "admin" in (subject.roles or ())
7306 target = _share_target_record(grant.get("collection", ""), grant.get("record_id", ""))
7307 owns_target = target is not None and target.get("owner_id") == requester
7308 if not (is_admin or owns_target or grant.get("granted_by") == requester):
7309 await _send_json(send, {"status": "error", "error": "Not allowed to revoke this grant."}, status=403)
7310 return
7311 object_records.delete_collection_record(
7312 RECORD_SHARES_COLLECTION, grant_id, base_dir=_data_dir(), actor=_record_change_actor(headers)
7313 )
7314 await _send_json(send, {"status": "ok"})
7315
7316
7317async def _handle_user_file(
7318 send,
7319 method: str,
7320 file_id: str,
7321 headers: dict[str, str],
7322) -> None:
7323 """Serve or delete one file, authorized against its metadata record."""
7324 if not _env_enabled(USER_FILES_ENABLED_ENV):
7325 await _send_json(
7326 send,
7327 {"status": "error", "error": f"User files are disabled. Set {USER_FILES_ENABLED_ENV}=true."},
7328 status=403,
7329 )
7330 return
7331 if "/" in file_id or not file_id:
7332 await _send_json(send, {"status": "error", "error": "Invalid file id"}, status=400)
7333 return
7334
7335 try:
7336 record = object_records.get_collection_record(
7337 USER_FILES_COLLECTION, file_id, base_dir=_data_dir()
7338 )
7339 except (LookupError, ValueError):
7340 record = None
7341
7342 action = object_permissions.READ if method == "GET" else object_permissions.DELETE
7343 if not await _user_file_allowed(send, headers, action, record=record, method=method):
7344 return
7345
7346 if record is None:
7347 await _send_json(send, {"status": "error", "error": "File not found"}, status=404)
7348 return
7349 owner_id = record.get("owner_id", "")
7350
7351 if method == "GET":
7352 try:
7353 content = object_user_files.read_file(owner_id, file_id, base_dir=_data_dir())
7354 except (object_user_files.UserFileNotFoundError, object_user_files.InvalidUserFileError):
7355 await _send_json(send, {"status": "error", "error": "File bytes missing"}, status=404)
7356 return
7357 content_type = record.get("content_type") or "application/octet-stream"
7358 disposition = "inline" if content_type in _INLINE_CONTENT_TYPES else "attachment"
7359 filename = (record.get("filename") or "download").replace('"', "")
7360 await _send_bytes(
7361 send,
7362 content,
7363 content_type=content_type,
7364 extra_headers=[
7365 (b"content-disposition", f'{disposition}; filename="{filename}"'.encode("latin-1", "replace")),
7366 (b"x-content-type-options", b"nosniff"),
7367 ],
7368 )
7369 return
7370
7371 if method == "DELETE":
7372 if (
7373 _session_cookie_token(headers)
7374 and not _authorization_token(headers)
7375 and not _cookie_request_origin_allowed(headers)
7376 ):
7377 await _send_json(
7378 send,
7379 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
7380 status=403,
7381 )
7382 return
7383 if not await _remove_user_file(send, headers, record):
7384 return
7385 await _send_json(send, {"status": "ok", "deleted": True, "file_id": file_id})
7386 return
7387
7388 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
7389
7390
7391async def _user_file_allowed(
7392 send,
7393 headers: dict[str, str],
7394 action: str,
7395 *,
7396 record: dict[str, Any] | None,
7397 method: str,
7398) -> bool:
7399 """The permission decision for one file (a policy check, or the admin
7400 token when permission checks are off). Sends the refusal and returns
7401 False when not allowed."""
7402 if _permission_checks_enabled():
7403 permission_check = await _collection_permission_check(
7404 send,
7405 headers,
7406 action,
7407 collection=USER_FILES_COLLECTION,
7408 method=method,
7409 record=record,
7410 )
7411 return permission_check is not None
7412 gate_error = _admin_token_gate_error(headers, f"Files require {ADMIN_TOKEN_ENV}.")
7413 if gate_error is not None:
7414 status, message = gate_error
7415 await _send_json(send, {"status": "error", "error": message}, status=status)
7416 return False
7417 return True
7418
7419
7420async def _remove_user_file(send, headers: dict[str, str], record: dict[str, Any]) -> bool:
7421 """Delete a file's record, then its bytes (already authorized). Sends
7422 the error and returns False when the record is gone or unreadable."""
7423 file_id = str(record.get("id") or "")
7424 try:
7425 object_records.delete_collection_record(
7426 USER_FILES_COLLECTION, file_id, base_dir=_data_dir(), actor=_record_change_actor(headers)
7427 )
7428 except (LookupError, ValueError) as exc:
7429 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
7430 return False
7431 try:
7432 object_user_files.delete_file(str(record.get("owner_id") or ""), file_id, base_dir=_data_dir())
7433 except object_user_files.InvalidUserFileError:
7434 pass
7435 return True
7436
7437
7438# ---------------------------------------------------------------------------
7439# WebDAV: a person's files as a folder any desktop can mount (/dav/files/).
7440# The pure half (names, paths, XML, ranges) and the decisions behind it are in
7441# object_webdav.py. Every write goes through the same helpers as /api/files and
7442# the collection routes, so a file stored or renamed here passes the same
7443# quota, permission and hook gates.
7444# ---------------------------------------------------------------------------
7445
7446WEBDAV_ENABLED_ENV = "DBBASIC_ENABLE_WEBDAV"
7447WEBDAV_MAX_FILE_BYTES_ENV = "DBBASIC_WEBDAV_MAX_FILE_BYTES"
7448# One PUT is read into memory whole, like every request here: this bounds it.
7449DEFAULT_WEBDAV_MAX_FILE_BYTES = 52_428_800
7450_WEBDAV_ALLOW = "OPTIONS, PROPFIND, PROPPATCH, GET, HEAD, PUT, DELETE, MOVE, COPY"
7451_WEBDAV_REALM = 'Basic realm="DBBASIC files", charset="UTF-8"'
7452
7453
7454def _webdav_enabled() -> bool:
7455 return _env_enabled(WEBDAV_ENABLED_ENV) and _env_enabled(USER_FILES_ENABLED_ENV)
7456
7457
7458def _webdav_body_limit(method: str, path: str) -> int | None:
7459 """A PUT under /dav/ is a whole file, so it may be bigger than the
7460 general request cap; everything else keeps that cap."""
7461 if method != "PUT" or not path.startswith(http_api_contract.WEBDAV_PATH + "/") or not _webdav_enabled():
7462 return None
7463 return max(_max_request_bytes(), _env_int(WEBDAV_MAX_FILE_BYTES_ENV, DEFAULT_WEBDAV_MAX_FILE_BYTES))
7464
7465
7466def _webdav_identity(headers: dict[str, str]) -> tuple[dict[str, str], str] | None:
7467 """(headers to authorize with, user id) for a request carrying an API key.
7468
7469 Desktops speak HTTP Basic, so the key comes as the password (any user
7470 name). Only API keys are accepted, never an account password: a password
7471 here would be a second login with none of /identity/login's rate limits,
7472 and a key can be revoked alone. Cookies are dropped, not just ignored: a
7473 folder mounted by a desktop has none, and a browser's session cookie must
7474 not turn a cross-site PUT or DELETE into the signed-in user's.
7475 """
7476 authorization = headers.get("authorization", "")
7477 scheme, _, value = authorization.partition(" ")
7478 token = None
7479 if scheme.lower() == "basic":
7480 try:
7481 decoded = base64.b64decode(value.strip(), validate=True).decode("utf-8")
7482 except (ValueError, UnicodeDecodeError):
7483 return None
7484 token = decoded.partition(":")[2]
7485 elif scheme.lower() in {"bearer", "token"}:
7486 token = value.strip()
7487 if not token or not token.startswith(object_api_keys.TOKEN_PREFIX):
7488 return None
7489 user_id = object_api_keys.resolve_api_key(token, base_dir=_data_dir())
7490 if not user_id:
7491 return None
7492 dav_headers = {k: v for k, v in headers.items() if k not in {"authorization", "cookie"}}
7493 dav_headers["authorization"] = f"Bearer {token}"
7494 return dav_headers, user_id
7495
7496
7497def _webdav_timestamp(value: Any) -> float | None:
7498 text = str(value or "").strip()
7499 if not text:
7500 return None
7501 try:
7502 parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
7503 except ValueError:
7504 return None
7505 if parsed.tzinfo is None:
7506 parsed = parsed.replace(tzinfo=timezone.utc)
7507 return parsed.timestamp()
7508
7509
7510def _webdav_folder(dav_headers: dict[str, str], user_id: str) -> dict[str, object_webdav.DavFile]:
7511 """The caller's own files, as the folder shows them (name -> file).
7512
7513 Own files only: a public file or one shared through a project belongs to
7514 someone else's folder, and listing it here would let a rename or delete
7515 from a desktop reach it. With enforcement on, each is also checked for
7516 read like any GET.
7517 """
7518 subject = _permission_subject(dav_headers)
7519 enforced = _permission_checks_enabled() and _permission_enforcement_enabled()
7520 policy = None
7521 if enforced:
7522 try:
7523 policy = object_permission_store.load_policy(_data_dir())
7524 except ValueError:
7525 return {}
7526 mine = []
7527 for record in _read_records_or_empty(USER_FILES_COLLECTION):
7528 if record.get("owner_id") != user_id:
7529 continue
7530 if enforced and not object_permissions.check_permission(
7531 subject, object_permissions.READ, policy=policy,
7532 collection=USER_FILES_COLLECTION, record=record,
7533 ).allowed:
7534 continue
7535 mine.append(record)
7536
7537 folder: dict[str, object_webdav.DavFile] = {}
7538 for name, record in object_webdav.folder_names(mine).items():
7539 created = _webdav_timestamp(record.get("created_at"))
7540 try:
7541 stat = object_user_files.file_path(
7542 user_id, str(record.get("id") or ""), base_dir=_data_dir()
7543 ).stat()
7544 size, modified = stat.st_size, stat.st_mtime
7545 except (OSError, object_user_files.InvalidUserFileError):
7546 # the bytes are missing: still listed (the record exists), and
7547 # a GET says so with a 404 rather than the file vanishing
7548 try:
7549 size = int(record.get("size") or 0)
7550 except ValueError:
7551 size = 0
7552 modified = created or 0.0
7553 folder[name] = object_webdav.DavFile(
7554 name=name, record=record, size=size, modified=modified, created=created or modified
7555 )
7556 return folder
7557
7558
7559def _webdav_folder_modified(folder: dict[str, object_webdav.DavFile]) -> float:
7560 """When the folder last changed: the files collection's own file moves
7561 on every create, rename and delete, which the files' times alone miss."""
7562 records = Path(_data_dir()) / "collections" / USER_FILES_COLLECTION / "records.tsv"
7563 try:
7564 return records.stat().st_mtime
7565 except OSError:
7566 return max((f.modified for f in folder.values()), default=0.0)
7567
7568
7569async def _send_webdav_error(send, status: int, message: str, extra: list[tuple[str, str]] | None = None) -> None:
7570 await _send_response(
7571 send,
7572 status=status,
7573 headers=[("content-type", "text/plain; charset=utf-8")] + (extra or []),
7574 body=(message + "\n").encode("utf-8"),
7575 )
7576
7577
7578async def _handle_webdav(send, method: str, path: str, body: bytes, headers: dict[str, str]) -> None:
7579 """Serve /dav/: a person's files as a folder (WebDAV class 1)."""
7580 if not _webdav_enabled():
7581 await _send_json(
7582 send,
7583 {
7584 "status": "error",
7585 "error": f"WebDAV is disabled. Set {WEBDAV_ENABLED_ENV}=true and {USER_FILES_ENABLED_ENV}=true.",
7586 },
7587 status=404,
7588 )
7589 return
7590 if method == "OPTIONS":
7591 await _send_response(
7592 send,
7593 status=200,
7594 headers=[("dav", "1"), ("allow", _WEBDAV_ALLOW), ("ms-author-via", "DAV"), ("content-length", "0")],
7595 body=b"",
7596 )
7597 return
7598 identity = _webdav_identity(headers)
7599 if identity is None:
7600 await _send_webdav_error(
7601 send, 401,
7602 "Sign in with any user name and one of your API keys (dbk_...) as the password.",
7603 [("www-authenticate", _WEBDAV_REALM)],
7604 )
7605 return
7606 dav_headers, user_id = identity
7607 try:
7608 kind, name = object_webdav.split_path(path)
7609 if method == "PROPFIND":
7610 await _webdav_propfind(send, dav_headers, user_id, kind, name, body)
7611 elif method in {"GET", "HEAD"}:
7612 await _webdav_get(send, dav_headers, user_id, kind, name, head=method == "HEAD")
7613 elif method == "PUT":
7614 await _webdav_put(send, dav_headers, user_id, kind, name, body)
7615 elif method == "DELETE":
7616 await _webdav_delete(send, dav_headers, user_id, kind, name)
7617 elif method in {"MOVE", "COPY"}:
7618 await _webdav_move_or_copy(send, dav_headers, user_id, kind, name, copy=method == "COPY")
7619 elif method == "PROPPATCH":
7620 await _webdav_proppatch(send, dav_headers, user_id, kind, name, body)
7621 elif method == "MKCOL":
7622 await _send_webdav_error(
7623 send, 405, "Folders are not supported here: your files are one list.",
7624 [("allow", _WEBDAV_ALLOW)],
7625 )
7626 else:
7627 # LOCK/UNLOCK included: see object_webdav on why there is no fake lock
7628 await _send_webdav_error(send, 405, f"{method} is not supported.", [("allow", _WEBDAV_ALLOW)])
7629 except object_webdav.DavRequestError as exc:
7630 await _send_webdav_error(send, exc.status, str(exc))
7631
7632
7633def _webdav_file(folder: dict[str, object_webdav.DavFile], name: str | None) -> object_webdav.DavFile:
7634 found = object_webdav.lookup(folder, name or "")
7635 if found is None:
7636 raise object_webdav.DavRequestError(404, "No such file.")
7637 return folder[found]
7638
7639
7640async def _webdav_propfind(send, dav_headers, user_id, kind, name, body) -> None:
7641 depth = object_webdav.parse_depth(dav_headers.get("depth"))
7642 wanted = object_webdav.parse_propfind(body)
7643 folder = _webdav_folder(dav_headers, user_id)
7644 folder_time = _webdav_folder_modified(folder)
7645 # the files quota, so a desktop shows real free space rather than its disk's
7646 used = object_user_files.usage_bytes(user_id, base_dir=_data_dir())
7647 quota = _env_int(USER_FILES_QUOTA_ENV, DEFAULT_USER_FILES_QUOTA)
7648 files_entry = (
7649 object_webdav.href(object_webdav.FILES_FOLDER, folder=True),
7650 object_webdav.folder_props(object_webdav.FILES_FOLDER, folder_time, used=used, available=quota - used),
7651 )
7652 file_entries = [
7653 (object_webdav.href(object_webdav.FILES_FOLDER, f.name), object_webdav.file_props(f))
7654 for f in folder.values()
7655 ]
7656 # The tree is two levels deep, so Depth: infinity is answered in full
7657 # rather than refused: it costs no more than Depth: 1 on the files folder.
7658 if kind == "root":
7659 responses = [(object_webdav.href(folder=True), object_webdav.folder_props("dav", folder_time))]
7660 if depth != "0":
7661 responses.append(files_entry)
7662 if depth == "infinity":
7663 responses.extend(file_entries)
7664 elif kind == "files":
7665 responses = [files_entry] + (file_entries if depth != "0" else [])
7666 else:
7667 f = _webdav_file(folder, name)
7668 responses = [(object_webdav.href(object_webdav.FILES_FOLDER, f.name), object_webdav.file_props(f))]
7669 await _send_response(
7670 send,
7671 status=207,
7672 headers=[("content-type", "application/xml; charset=utf-8")],
7673 body=object_webdav.multistatus(responses, wanted),
7674 )
7675
7676
7677async def _webdav_get(send, dav_headers, user_id, kind, name, *, head: bool) -> None:
7678 folder = _webdav_folder(dav_headers, user_id)
7679 if kind != "file":
7680 entries = (
7681 [(object_webdav.href(object_webdav.FILES_FOLDER, folder=True), object_webdav.FILES_FOLDER + "/")]
7682 if kind == "root"
7683 else [(object_webdav.href(object_webdav.FILES_FOLDER, n), n) for n in sorted(folder, key=str.lower)]
7684 )
7685 page = object_webdav.folder_html("Files" if kind == "files" else "dav", entries)
7686 await _send_response(
7687 send, status=200,
7688 headers=[("content-type", "text/html; charset=utf-8"), ("content-length", str(len(page)))],
7689 body=b"" if head else page,
7690 )
7691 return
7692 f = _webdav_file(folder, name)
7693 if not await _user_file_allowed(send, dav_headers, object_permissions.READ, record=f.record, method="GET"):
7694 return
7695 common = [
7696 ("etag", f.etag),
7697 ("last-modified", object_webdav.http_date(f.modified)),
7698 ("accept-ranges", "bytes"),
7699 ("x-content-type-options", "nosniff"),
7700 # served from the server's own origin: an uploaded page must not run
7701 ("content-security-policy", "sandbox"),
7702 ]
7703 if object_webdav.etag_matches(dav_headers.get("if-none-match"), f.etag):
7704 await _send_response(send, status=304, headers=common, body=b"")
7705 return
7706 try:
7707 content = object_user_files.read_file(user_id, f.record_id, base_dir=_data_dir())
7708 except (object_user_files.UserFileNotFoundError, object_user_files.InvalidUserFileError):
7709 raise object_webdav.DavRequestError(404, "File bytes missing.") from None
7710 content_type = f.content_type
7711 disposition = "inline" if content_type in _INLINE_CONTENT_TYPES else "attachment"
7712 headers = [("content-type", content_type), ("content-disposition", disposition)] + common
7713 try:
7714 wanted = object_webdav.parse_range(dav_headers.get("range"), len(content))
7715 except object_webdav.DavRequestError:
7716 await _send_response(
7717 send, status=416, headers=[("content-range", f"bytes */{len(content)}")], body=b""
7718 )
7719 return
7720 status = 200
7721 if wanted is not None:
7722 start, end = wanted
7723 content = content[start:end + 1]
7724 status = 206
7725 headers.append(("content-range", f"bytes {start}-{end}/{f.size}"))
7726 headers.append(("content-length", str(len(content))))
7727 await _send_response(send, status=status, headers=headers, body=b"" if head else content)
7728
7729
7730def _webdav_preconditions(dav_headers, existing: object_webdav.DavFile | None) -> None:
7731 """If-Match / If-None-Match against the file a write would touch: how a
7732 client that read a file makes sure it is not overwriting someone else's
7733 newer copy, and how "create, but only if new" is asked."""
7734 etag = existing.etag if existing else None
7735 if_match = dav_headers.get("if-match")
7736 if if_match and not object_webdav.etag_matches(if_match, etag):
7737 raise object_webdav.DavRequestError(412, "The file changed (If-Match).")
7738 if_none_match = dav_headers.get("if-none-match")
7739 if if_none_match and object_webdav.etag_matches(if_none_match, etag):
7740 raise object_webdav.DavRequestError(412, "The file exists (If-None-Match).")
7741
7742
7743def _webdav_content_type(name: str, sent: str | None) -> str:
7744 guessed = object_webdav.guess_type(name)
7745 sent = (sent or "").split(";")[0].strip().lower()
7746 if guessed == "application/octet-stream" and sent:
7747 return sent
7748 return guessed
7749
7750
7751async def _webdav_put(send, dav_headers, user_id, kind, name, body) -> None:
7752 if kind != "file":
7753 raise object_webdav.DavRequestError(405, "A folder cannot be written; PUT a file inside /dav/files/.")
7754 name = object_webdav.check_new_name(name or "")
7755 folder = _webdav_folder(dav_headers, user_id)
7756 found = object_webdav.lookup(folder, name)
7757 existing = folder[found] if found else None
7758 _webdav_preconditions(dav_headers, existing)
7759 content_type = _webdav_content_type(name, dav_headers.get("content-type"))
7760 if existing is None:
7761 stored = await _create_user_file(
7762 send, dav_headers, owner_id=user_id, filename=name, content=body, content_type=content_type
7763 )
7764 if stored is not None:
7765 await _send_response(send, status=201, headers=[("content-length", "0")], body=b"")
7766 return
7767 quota_error = _user_files_quota_error(user_id, len(body), freeing=existing.size)
7768 if quota_error is not None:
7769 raise object_webdav.DavRequestError(507, quota_error)
7770 if await _record_write_denied_before_lookup(
7771 send, dav_headers, object_permissions.UPDATE, collection=USER_FILES_COLLECTION
7772 ):
7773 return
7774 updated = await _gated_record_update(
7775 send,
7776 dav_headers,
7777 collection=USER_FILES_COLLECTION,
7778 record_id=existing.record_id,
7779 existing=existing.record,
7780 changes={"size": str(len(body)), "content_type": content_type},
7781 expected_rev=None,
7782 )
7783 if updated is None:
7784 return
7785 object_user_files.save_file(user_id, existing.record_id, body, base_dir=_data_dir())
7786 await _send_response(send, status=204, headers=[], body=b"")
7787
7788
7789async def _webdav_delete(send, dav_headers, user_id, kind, name) -> None:
7790 if kind != "file":
7791 raise object_webdav.DavRequestError(403, "The folder itself cannot be deleted.")
7792 f = _webdav_file(_webdav_folder(dav_headers, user_id), name)
7793 _webdav_preconditions(dav_headers, f)
7794 if not await _user_file_allowed(send, dav_headers, object_permissions.DELETE, record=f.record, method="DELETE"):
7795 return
7796 if await _remove_user_file(send, dav_headers, f.record):
7797 await _send_response(send, status=204, headers=[], body=b"")
7798
7799
7800async def _webdav_move_or_copy(send, dav_headers, user_id, kind, name, *, copy: bool) -> None:
7801 if kind != "file":
7802 raise object_webdav.DavRequestError(403, "Folders cannot be moved or copied.")
7803 dest_kind, dest_name = object_webdav.split_path(
7804 object_webdav.destination_path(dav_headers.get("destination"))
7805 )
7806 if dest_kind != "file":
7807 raise object_webdav.DavRequestError(403, "Files can only move or copy within /dav/files/.")
7808 dest_name = object_webdav.check_new_name(dest_name or "")
7809 overwrite = object_webdav.parse_overwrite(dav_headers.get("overwrite"))
7810 folder = _webdav_folder(dav_headers, user_id)
7811 source = _webdav_file(folder, name)
7812 found = object_webdav.lookup(folder, dest_name)
7813 target = folder[found] if found else None
7814 if target is not None and target.record_id == source.record_id:
7815 if copy or dest_name == source.name:
7816 raise object_webdav.DavRequestError(403, "Source and destination are the same file.")
7817 target = None # a rename that only changes case
7818 if target is not None:
7819 if not overwrite:
7820 raise object_webdav.DavRequestError(412, "The destination exists (Overwrite: F).")
7821 if not await _user_file_allowed(send, dav_headers, object_permissions.DELETE, record=target.record, method="DELETE"):
7822 return
7823 content_type = _webdav_content_type(dest_name, source.content_type)
7824
7825 if copy:
7826 if not await _user_file_allowed(send, dav_headers, object_permissions.READ, record=source.record, method="GET"):
7827 return
7828 try:
7829 content = object_user_files.read_file(user_id, source.record_id, base_dir=_data_dir())
7830 except (object_user_files.UserFileNotFoundError, object_user_files.InvalidUserFileError):
7831 raise object_webdav.DavRequestError(404, "File bytes missing.") from None
7832 if target is not None and not await _remove_user_file(send, dav_headers, target.record):
7833 return
7834 stored = await _create_user_file(
7835 send, dav_headers, owner_id=user_id, filename=dest_name, content=content, content_type=content_type
7836 )
7837 if stored is not None:
7838 await _send_response(send, status=204 if target else 201, headers=[], body=b"")
7839 return
7840
7841 if await _record_write_denied_before_lookup(
7842 send, dav_headers, object_permissions.UPDATE, collection=USER_FILES_COLLECTION
7843 ):
7844 return
7845 if target is not None and not await _remove_user_file(send, dav_headers, target.record):
7846 return
7847 updated = await _gated_record_update(
7848 send,
7849 dav_headers,
7850 collection=USER_FILES_COLLECTION,
7851 record_id=source.record_id,
7852 existing=source.record,
7853 changes={"filename": dest_name, "content_type": content_type},
7854 expected_rev=None,
7855 )
7856 if updated is not None:
7857 await _send_response(send, status=204 if target else 201, headers=[], body=b"")
7858
7859
7860async def _webdav_proppatch(send, dav_headers, user_id, kind, name, body) -> None:
7861 """No property here is writable (sizes and times are the file's own);
7862 each one a client tries to set is refused with 403, which clients that
7863 set times after an upload (Windows, Finder) accept and carry on."""
7864 names = object_webdav.parse_proppatch(body)
7865 if kind == "file":
7866 f = _webdav_file(_webdav_folder(dav_headers, user_id), name)
7867 target = object_webdav.href(object_webdav.FILES_FOLDER, f.name)
7868 else:
7869 target = object_webdav.href(*( [object_webdav.FILES_FOLDER] if kind == "files" else []), folder=True)
7870 await _send_response(
7871 send,
7872 status=207,
7873 headers=[("content-type", "application/xml; charset=utf-8")],
7874 body=object_webdav.proppatch_refused(target, names),
7875 )
7876
7877
7878async def _send_bytes(
7879 send,
7880 content: bytes,
7881 *,
7882 content_type: str,
7883 status: int = 200,
7884 extra_headers: list[tuple[bytes, bytes]] | None = None,
7885) -> None:
7886 response_headers = [
7887 (b"content-type", content_type.encode("latin-1", "replace")),
7888 (b"content-length", str(len(content)).encode("ascii")),
7889 ]
7890 response_headers.extend(extra_headers or [])
7891 await send(
7892 {"type": "http.response.start", "status": status, "headers": response_headers}
7893 )
7894 await send({"type": "http.response.body", "body": content})
7895
7896
7897def _env_int(name: str, default: int) -> int:
7898 raw = os.environ.get(name, "").strip()
7899 if not raw:
7900 return default
7901 try:
7902 value = int(raw)
7903 except ValueError:
7904 return default
7905 return value if value > 0 else default
7906
7907
7908AI_CHAT_ENABLED_ENV = "DBBASIC_ENABLE_AI_CHAT"
7909AI_CHAT_TIMEOUT_ENV = "DBBASIC_AI_TIMEOUT_SECONDS"
7910AI_DEFAULT_MODEL_ENV = "DBBASIC_AI_DEFAULT_MODEL"
7911DEFAULT_AI_MODEL = "anthropic:claude-haiku-4-5"
7912DEFAULT_AI_TIMEOUT_SECONDS = 60.0
7913AI_PRICES_COLLECTION = "ai_prices"
7914AI_USAGE_COLLECTION = "ai_usage"
7915
7916
7917def _text_field(value) -> str:
7918 return str(value if value is not None else "").strip()
7919
7920
7921def _utc_now_iso() -> str:
7922 from datetime import datetime, timezone
7923 return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
7924
7925
7926async def _handle_ai_chat(
7927 send,
7928 method: str,
7929 body: bytes,
7930 headers: dict[str, str],
7931) -> None:
7932 """One AI conversation turn using the caller's stored provider key.
7933
7934 The model may call a caller-chosen subset of the MCP tool catalog;
7935 every tool call dispatches through the server's own routing with the
7936 caller's credentials, so the AI can do exactly what the caller could
7937 do directly — nothing more — and it all lands in the audit trail.
7938 """
7939 if method != "POST":
7940 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
7941 return
7942
7943 if not _env_enabled(AI_CHAT_ENABLED_ENV):
7944 await _send_json(
7945 send,
7946 {"status": "error", "error": f"AI chat is disabled. Set {AI_CHAT_ENABLED_ENV}=true."},
7947 status=403,
7948 )
7949 return
7950
7951 session = _current_identity_session(headers)
7952 if session is None:
7953 await _send_json(
7954 send,
7955 {"status": "error", "error": "AI chat requires a signed-in session."},
7956 status=401,
7957 )
7958 return
7959
7960 cookie_token = _session_cookie_token(headers)
7961 if cookie_token and not _authorization_token(headers) and not _cookie_request_origin_allowed(headers):
7962 await _send_json(
7963 send,
7964 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
7965 status=403,
7966 )
7967 return
7968
7969 try:
7970 payload = _parse_json_body(body)
7971 except ValueError as exc:
7972 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
7973 return
7974
7975 message = payload.get("message")
7976 model = payload.get("model") or os.environ.get(AI_DEFAULT_MODEL_ENV, DEFAULT_AI_MODEL)
7977 tool_names = payload.get("tools") or []
7978 system = payload.get("system")
7979
7980 if not isinstance(tool_names, list) or not all(
7981 isinstance(name, str) and name for name in tool_names
7982 ):
7983 await _send_json(
7984 send,
7985 {"status": "error", "error": "tools must be a list of MCP tool names"},
7986 status=400,
7987 )
7988 return
7989
7990 try:
7991 service, model_name = object_ai.split_model(model)
7992 provider_tools = object_ai.mcp_tools_as_provider_tools(
7993 tool_names, object_mcp.TOOLS, service=service
7994 )
7995 max_rounds_raw = payload.get("max_rounds", object_ai.DEFAULT_MAX_ROUNDS)
7996 if isinstance(max_rounds_raw, bool) or not isinstance(max_rounds_raw, int):
7997 raise object_ai.InvalidChatRequestError("max_rounds must be an integer")
7998 max_rounds = max_rounds_raw
7999 except (object_ai.InvalidChatRequestError, ValueError) as exc:
8000 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8001 return
8002
8003 # --- chat attachments: file ids -> provider-neutral parts ----------------
8004 #
8005 # Resolved HERE, after the key check and before any provider call, so a
8006 # refused attachment costs nothing. The split of labour: this handler
8007 # does all the I/O (ownership, record lookup, blob read) and
8008 # object_ai.attachment_part does the pure classification, so the gate
8009 # logic is testable without a data directory.
8010 #
8011 # OWNERSHIP IS STRICT in v1: the caller may attach only files whose
8012 # record they own. Deliberately not consulting record_shares yet -- a
8013 # share grants READ of the record, and whether that extends to feeding
8014 # the blob into an AI provider is a real question (the provider sees
8015 # the content), so it waits to be decided rather than being implied.
8016 # The refusal says so.
8017 #
8018 # Every problem is reported at once (the blockers idiom): a user who
8019 # attached four files does not want them peeled back one error at a
8020 # time.
8021 attachment_ids = payload.get("attachments") or []
8022 attachment_parts: list[dict[str, Any]] = []
8023 if attachment_ids:
8024 if not isinstance(attachment_ids, list) or not all(
8025 isinstance(fid, str) and fid for fid in attachment_ids
8026 ):
8027 await _send_json(
8028 send,
8029 {"status": "error", "error": "attachments must be a list of file ids"},
8030 status=400,
8031 )
8032 return
8033 problems: list[str] = []
8034 for fid in attachment_ids[: object_ai.MAX_ATTACHMENTS_PER_TURN + 1]:
8035 try:
8036 record = object_records.get_collection_record(
8037 USER_FILES_COLLECTION, fid, base_dir=_data_dir()
8038 )
8039 except Exception:
8040 problems.append(f"{fid}: no such file")
8041 continue
8042 if str(record.get("owner_id") or "") != str(session.user_id):
8043 problems.append(
8044 f"{record.get('filename') or fid}: not your file. Chat "
8045 f"attachments are owner-only for now -- a share grants "
8046 f"read of the record, and whether that extends to sending "
8047 f"the content to an AI provider is deliberately not yet "
8048 f"decided."
8049 )
8050 continue
8051 try:
8052 blob = object_user_files.read_file(
8053 str(record.get("owner_id")), fid, base_dir=_data_dir()
8054 )
8055 except Exception:
8056 problems.append(f"{record.get('filename') or fid}: bytes are missing")
8057 continue
8058 try:
8059 attachment_parts.append(object_ai.attachment_part(
8060 str(record.get("filename") or fid),
8061 str(record.get("content_type") or ""),
8062 blob,
8063 ))
8064 except object_ai.InvalidChatRequestError as exc:
8065 problems.append(str(exc))
8066 if len(attachment_ids) > object_ai.MAX_ATTACHMENTS_PER_TURN:
8067 problems.append(
8068 f"{len(attachment_ids)} attachments; the limit is "
8069 f"{object_ai.MAX_ATTACHMENTS_PER_TURN} per message."
8070 )
8071 if problems:
8072 await _send_json(
8073 send,
8074 {"status": "error",
8075 "error": " ".join(problems), "problems": problems},
8076 status=400,
8077 )
8078 return
8079
8080 key = object_service_keys.get_service_key(session.user_id, service, base_dir=_data_dir())
8081 if key is None:
8082 await _send_json(
8083 send,
8084 {
8085 "status": "error",
8086 "error": (
8087 f"No {service} key stored. Set one with "
8088 f"PUT /identity/users/{session.user_id}/service-keys."
8089 ),
8090 },
8091 status=400,
8092 )
8093 return
8094
8095 authorization = headers.get("authorization") or f"Bearer {cookie_token}"
8096 allowed_tools = set(tool_names)
8097 loop = asyncio.get_running_loop()
8098 timeout = _env_float(AI_CHAT_TIMEOUT_ENV, DEFAULT_AI_TIMEOUT_SECONDS)
8099
8100 def send_http(url: str, request_headers, request_body: bytes) -> tuple[int, bytes]:
8101 request = urllib.request.Request(
8102 url, data=request_body, method="POST", headers=dict(request_headers)
8103 )
8104 try:
8105 with urllib.request.urlopen(request, timeout=timeout) as response:
8106 return response.status, response.read()
8107 except urllib.error.HTTPError as exc:
8108 return exc.code, exc.read()
8109
8110 def dispatch_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
8111 if name not in allowed_tools:
8112 return {"http_status": 400, "response": {"error": f"Tool not offered: {name}"}}
8113 try:
8114 tool_method, tool_path, tool_query, tool_body = object_mcp.tool_route(
8115 name, dict(arguments or {})
8116 )
8117 except ValueError as exc:
8118 return {"http_status": 400, "response": {"error": str(exc)}}
8119 future = asyncio.run_coroutine_threadsafe(
8120 _internal_request(
8121 tool_method, tool_path, tool_query, tool_body, authorization=authorization
8122 ),
8123 loop,
8124 )
8125 status, response_payload = future.result(timeout=timeout)
8126 return {"http_status": status, "response": response_payload}
8127
8128 turn_started = time.monotonic()
8129 try:
8130 result = await asyncio.to_thread(
8131 object_ai.run_chat,
8132 send_http=send_http,
8133 dispatch_tool=dispatch_tool,
8134 service=service,
8135 model=model_name,
8136 key=key,
8137 message=message,
8138 system=system if isinstance(system, str) else None,
8139 tools=provider_tools,
8140 history=payload.get("history"),
8141 attachments=attachment_parts or None,
8142 max_rounds=max_rounds,
8143 )
8144 except object_ai.InvalidChatRequestError as exc:
8145 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8146 return
8147 except object_ai.AIProviderError as exc:
8148 await _send_json(send, {"status": "error", "error": str(exc)}, status=502)
8149 return
8150 except (TimeoutError, OSError) as exc:
8151 await _send_json(
8152 send,
8153 {"status": "error", "error": f"AI provider request failed: {exc}"},
8154 status=502,
8155 )
8156 return
8157
8158 # Cost recording is server-authoritative: the client never sees this
8159 # write and cannot omit or falsify it. Prices live in the ai_prices
8160 # collection (editable live, never hardcoded) -- a missing price row
8161 # still records the turn's tokens, just with a null cost, so pricing
8162 # gaps never fail a chat that otherwise succeeded.
8163 usage = result.get("usage") or {}
8164 tokens_in = int(usage.get("input_tokens") or 0)
8165 tokens_out = int(usage.get("output_tokens") or 0)
8166 price_row = object_ai.select_price_row(
8167 _read_ai_prices_or_empty(), provider=service, model=model_name
8168 )
8169 cost_cents = object_ai.compute_cost_cents(tokens_in, tokens_out, price_row)
8170 usage["cost_cents"] = cost_cents
8171
8172 # The TURN record is server-authoritative for the same reason the cost
8173 # is: the client used to write its own history row after the reply,
8174 # fire-and-forget, which lost any turn whose page died first (a real
8175 # one vanished that way during live debugging -- billed in ai_usage,
8176 # absent from history) and stamped no timestamp at all. The server
8177 # writes it here, before the reply is even sent, so history survives
8178 # whatever the page does next. session_id is minted by the page and
8179 # merely recorded -- grouping is the client's claim, existence is the
8180 # server's fact. Best-effort by design: a history write must never
8181 # fail a chat that succeeded.
8182 turn_record = {
8183 "id": object_ids.new_uuid4(),
8184 "input": message[:8000],
8185 # run_chat's key is "reply" -- "text" was a straight typo, live
8186 # since this write was added, and every source-presence test
8187 # passed anyway because none of them checked the RECORDED VALUE,
8188 # only that the strings existed somewhere in the file. Every
8189 # turn recorded before this fix has output == "" regardless of
8190 # what the model actually said; the reply the USER saw was
8191 # correct the whole time (the HTTP response spreads **result
8192 # directly), so this was invisible everywhere except the log
8193 # meant to make turns inspectable -- exactly where a session
8194 # review found it.
8195 "output": _text_field(result.get("reply"))[:20000],
8196 "kind": "ai",
8197 "owner_id": session.user_id,
8198 "session_id": _text_field(payload.get("session_id"))[:64],
8199 "source": _text_field(payload.get("source"))[:16] or "api",
8200 "model": f"{service}:{model_name}",
8201 "duration_ms": str(int((time.monotonic() - turn_started) * 1000)),
8202 "tool_calls": json.dumps([c.get("name") for c in
8203 (result.get("tool_calls") or []) if c.get("name")]),
8204 "created_at": _utc_now_iso(),
8205 }
8206 try:
8207 object_records.create_collection_record(
8208 "shell_commands", turn_record, base_dir=_data_dir(), actor=session.user_id)
8209 except Exception:
8210 pass # the reply matters more than the record of it
8211
8212 usage_record = {
8213 "id": object_ids.new_uuid4(),
8214 "owner_id": session.user_id,
8215 "provider": service,
8216 "model": model_name,
8217 "tokens_in": tokens_in,
8218 "tokens_out": tokens_out,
8219 }
8220 if cost_cents is not None:
8221 usage_record["cost_cents"] = cost_cents
8222 object_records.create_collection_record(
8223 AI_USAGE_COLLECTION,
8224 usage_record,
8225 base_dir=_data_dir(),
8226 roots=get_object_roots(),
8227 actor=session.user_id,
8228 )
8229
8230 await _send_json(send, {"status": "ok", "model": model, **result})
8231
8232
8233def _read_ai_prices_or_empty() -> list[dict[str, str]]:
8234 try:
8235 return object_records.read_collection_records(
8236 AI_PRICES_COLLECTION, base_dir=_data_dir(), roots=get_object_roots()
8237 )
8238 except (
8239 object_collections.CollectionNotFoundError,
8240 object_collections.InvalidCollectionNameError,
8241 OSError,
8242 ValueError,
8243 ):
8244 return []
8245
8246
8247def _env_float(name: str, default: float) -> float:
8248 raw = os.environ.get(name, "").strip()
8249 if not raw:
8250 return default
8251 try:
8252 value = float(raw)
8253 except ValueError:
8254 return default
8255 return value if value > 0 else default
8256
8257
8258TTS_ENABLED_ENV = "DBBASIC_ENABLE_TTS"
8259TTS_MAX_CHARS = 800
8260TTS_CLOUD_TIMEOUT_ENV = "DBBASIC_TTS_CLOUD_TIMEOUT_SECONDS"
8261DEFAULT_TTS_CLOUD_TIMEOUT_SECONDS = 30.0
8262TTS_ENGINES = ("local", "openai")
8263
8264
8265async def _handle_tts(
8266 send,
8267 method: str,
8268 body: bytes,
8269 headers: dict[str, str],
8270) -> None:
8271 """Speak one line of text through whatever engine is installed.
8272
8273 Mirrors _handle_ai_chat's gating exactly: a feature flag first (off by
8274 default), then a signed-in session, then the same cross-origin cookie
8275 check every authenticated POST here uses. Successful audio is cached
8276 to disk (object_tts.cache_path) so a repeated line costs one
8277 synthesis, not one per request.
8278
8279 Two engines, chosen per request via the "engine" field ("local", the
8280 default, or "openai"): local shells out to whatever's on the box
8281 (espeak-ng in production, robotic but free and always available);
8282 openai calls the caller's own stored key against a real cloud TTS
8283 model for a real per-call cost. Neither silently falls back to the
8284 other -- a caller who asked for cloud quality and hits a provider
8285 error should see that error, not a surprise robot voice.
8286 """
8287 if method != "POST":
8288 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8289 return
8290
8291 if not _env_enabled(TTS_ENABLED_ENV):
8292 await _send_json(
8293 send,
8294 {"status": "error", "error": f"TTS is disabled. Set {TTS_ENABLED_ENV}=true."},
8295 status=403,
8296 )
8297 return
8298
8299 session = _current_identity_session(headers)
8300 if session is None:
8301 await _send_json(
8302 send, {"status": "error", "error": "TTS requires a signed-in session."}, status=401
8303 )
8304 return
8305
8306 cookie_token = _session_cookie_token(headers)
8307 if cookie_token and not _authorization_token(headers) and not _cookie_request_origin_allowed(headers):
8308 await _send_json(
8309 send,
8310 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
8311 status=403,
8312 )
8313 return
8314
8315 try:
8316 payload = _parse_json_body(body)
8317 except ValueError as exc:
8318 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8319 return
8320
8321 text = payload.get("text")
8322 if not isinstance(text, str) or not text.strip():
8323 await _send_json(send, {"status": "error", "error": "text is required"}, status=400)
8324 return
8325 if len(text) > TTS_MAX_CHARS:
8326 await _send_json(
8327 send,
8328 {"status": "error", "error": f"text exceeds {TTS_MAX_CHARS} characters"},
8329 status=413,
8330 )
8331 return
8332
8333 voice = payload.get("voice")
8334 if voice is not None and not isinstance(voice, str):
8335 await _send_json(send, {"status": "error", "error": "voice must be a string"}, status=400)
8336 return
8337
8338 engine = payload.get("engine") or "local"
8339 if engine not in TTS_ENGINES:
8340 await _send_json(
8341 send,
8342 {"status": "error", "error": f"engine must be one of {TTS_ENGINES}"},
8343 status=400,
8344 )
8345 return
8346
8347 if engine == "openai":
8348 key = object_service_keys.get_service_key(session.user_id, "openai", base_dir=_data_dir())
8349 if key is None:
8350 await _send_json(
8351 send,
8352 {
8353 "status": "error",
8354 "error": (
8355 "No openai key stored. Set one with "
8356 f"PUT /identity/users/{session.user_id}/service-keys."
8357 ),
8358 },
8359 status=400,
8360 )
8361 return
8362
8363 timeout = _env_float(TTS_CLOUD_TIMEOUT_ENV, DEFAULT_TTS_CLOUD_TIMEOUT_SECONDS)
8364
8365 def send_http(url: str, request_headers, request_body: bytes) -> tuple[int, bytes]:
8366 request = urllib.request.Request(
8367 url, data=request_body, method="POST", headers=dict(request_headers)
8368 )
8369 try:
8370 with urllib.request.urlopen(request, timeout=timeout) as response:
8371 return response.status, response.read()
8372 except urllib.error.HTTPError as exc:
8373 return exc.code, exc.read()
8374
8375 try:
8376 audio, content_type, _from_cache = await asyncio.to_thread(
8377 object_tts.synthesize_cloud, text, voice, key,
8378 send_http=send_http, base_dir=_data_dir(),
8379 )
8380 except object_tts.TTSProviderError as exc:
8381 await _send_json(send, {"status": "error", "error": str(exc)}, status=502)
8382 return
8383
8384 await _send_bytes(send, audio, content_type=content_type)
8385 return
8386
8387 try:
8388 audio, _from_cache = await asyncio.to_thread(
8389 object_tts.synthesize, text, voice, base_dir=_data_dir()
8390 )
8391 except object_tts.TTSEngineNotFoundError as exc:
8392 await _send_json(send, {"status": "error", "error": str(exc)}, status=503)
8393 return
8394 except object_tts.TTSNotSupportedError as exc:
8395 await _send_json(send, {"status": "error", "error": str(exc)}, status=501)
8396 return
8397 except object_tts.TTSSynthesisError as exc:
8398 await _send_json(send, {"status": "error", "error": str(exc)}, status=502)
8399 return
8400
8401 await _send_bytes(send, audio, content_type="audio/wav")
8402
8403
8404STT_ENABLED_ENV = "DBBASIC_ENABLE_STT"
8405STT_MAX_BYTES = 10_000_000
8406STT_TIMEOUT_ENV = "DBBASIC_STT_TIMEOUT_SECONDS"
8407DEFAULT_STT_TIMEOUT_SECONDS = 30.0
8408DEFAULT_STT_CONTENT_TYPE = "audio/webm"
8409
8410
8411async def _handle_stt(
8412 send,
8413 method: str,
8414 body: bytes,
8415 headers: dict[str, str],
8416) -> None:
8417 """Transcribe one recorded audio clip through OpenAI's cloud STT.
8418
8419 Mirrors _handle_tts's gating exactly (feature flag, session, the same
8420 cross-origin cookie check). There is no local-engine path here to fall
8421 back to -- see object_stt.py's docstring for why: voice input in this
8422 codebase is otherwise 100% browser-native SpeechRecognition, which
8423 never reaches the server at all. This is the "not on device"
8424 alternative, for browsers/devices that lack that API entirely.
8425
8426 The request body is the raw audio bytes themselves (whatever
8427 MediaRecorder produced client-side), not JSON -- the client's own
8428 Content-Type header says what format it is.
8429 """
8430 if method != "POST":
8431 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8432 return
8433
8434 if not _env_enabled(STT_ENABLED_ENV):
8435 await _send_json(
8436 send,
8437 {"status": "error", "error": f"STT is disabled. Set {STT_ENABLED_ENV}=true."},
8438 status=403,
8439 )
8440 return
8441
8442 session = _current_identity_session(headers)
8443 if session is None:
8444 await _send_json(
8445 send, {"status": "error", "error": "STT requires a signed-in session."}, status=401
8446 )
8447 return
8448
8449 cookie_token = _session_cookie_token(headers)
8450 if cookie_token and not _authorization_token(headers) and not _cookie_request_origin_allowed(headers):
8451 await _send_json(
8452 send,
8453 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
8454 status=403,
8455 )
8456 return
8457
8458 if not body:
8459 await _send_json(send, {"status": "error", "error": "audio body is required"}, status=400)
8460 return
8461 if len(body) > STT_MAX_BYTES:
8462 await _send_json(
8463 send,
8464 {"status": "error", "error": f"audio exceeds {STT_MAX_BYTES} bytes"},
8465 status=413,
8466 )
8467 return
8468
8469 key = object_service_keys.get_service_key(session.user_id, "openai", base_dir=_data_dir())
8470 if key is None:
8471 await _send_json(
8472 send,
8473 {
8474 "status": "error",
8475 "error": (
8476 "No openai key stored. Set one with "
8477 f"PUT /identity/users/{session.user_id}/service-keys."
8478 ),
8479 },
8480 status=400,
8481 )
8482 return
8483
8484 content_type = (headers.get("content-type") or DEFAULT_STT_CONTENT_TYPE).strip()
8485 timeout = _env_float(STT_TIMEOUT_ENV, DEFAULT_STT_TIMEOUT_SECONDS)
8486
8487 def send_http(url: str, request_headers, request_body: bytes) -> tuple[int, bytes]:
8488 request = urllib.request.Request(
8489 url, data=request_body, method="POST", headers=dict(request_headers)
8490 )
8491 try:
8492 with urllib.request.urlopen(request, timeout=timeout) as response:
8493 return response.status, response.read()
8494 except urllib.error.HTTPError as exc:
8495 return exc.code, exc.read()
8496
8497 try:
8498 text = await asyncio.to_thread(
8499 object_stt.transcribe_cloud, body, content_type, key, send_http=send_http,
8500 )
8501 except object_stt.STTProviderError as exc:
8502 await _send_json(send, {"status": "error", "error": str(exc)}, status=502)
8503 return
8504
8505 await _send_json(send, {"status": "ok", "text": text})
8506
8507
8508READER_ENABLED_ENV = "DBBASIC_ENABLE_READER"
8509READER_TIMEOUT_SECONDS_ENV = "DBBASIC_READER_TIMEOUT_SECONDS"
8510READER_MAX_BYTES_ENV = "DBBASIC_READER_MAX_BYTES"
8511DEFAULT_READER_TIMEOUT_SECONDS = 10.0
8512DEFAULT_READER_MAX_BYTES = 2_000_000
8513
8514
8515async def _handle_read(
8516 send,
8517 method: str,
8518 body: bytes,
8519 headers: dict[str, str],
8520) -> None:
8521 """Fetch one URL server-side and return {title, text, links}.
8522
8523 Mirrors _handle_tts's gating shape exactly: a feature flag first (off
8524 by default), then a signed-in session, then the same cross-origin
8525 cookie check every authenticated POST here uses -- the capability
8526 being gated is the server reaching outbound, not the fetched content
8527 (which is public web data either way). The global per-request rate
8528 limiter above already covers this path like every other route; the
8529 SSRF gate itself lives in object_reader and cannot be bypassed here.
8530 """
8531 if method != "POST":
8532 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8533 return
8534
8535 if not _env_enabled(READER_ENABLED_ENV):
8536 await _send_json(
8537 send,
8538 {"status": "error", "error": f"Reader is disabled. Set {READER_ENABLED_ENV}=true."},
8539 status=403,
8540 )
8541 return
8542
8543 session = _current_identity_session(headers)
8544 if session is None:
8545 await _send_json(
8546 send, {"status": "error", "error": "Reader requires a signed-in session."}, status=401
8547 )
8548 return
8549
8550 cookie_token = _session_cookie_token(headers)
8551 if cookie_token and not _authorization_token(headers) and not _cookie_request_origin_allowed(headers):
8552 await _send_json(
8553 send,
8554 {"status": "error", "error": "Cross-origin cookie writes are not allowed."},
8555 status=403,
8556 )
8557 return
8558
8559 try:
8560 payload = _parse_json_body(body)
8561 except ValueError as exc:
8562 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8563 return
8564
8565 url = payload.get("url")
8566 if not isinstance(url, str) or not url.strip():
8567 await _send_json(send, {"status": "error", "error": "url is required"}, status=400)
8568 return
8569
8570 timeout = _env_float(READER_TIMEOUT_SECONDS_ENV, DEFAULT_READER_TIMEOUT_SECONDS)
8571 max_bytes = _env_int(READER_MAX_BYTES_ENV, DEFAULT_READER_MAX_BYTES)
8572
8573 try:
8574 result = await asyncio.to_thread(
8575 object_reader.read_page, url.strip(), timeout=timeout, max_bytes=max_bytes
8576 )
8577 except object_reader.ReaderError as exc:
8578 try:
8579 object_logs.append_object_log(
8580 "object_reader", "WARNING", f"read_page refused/failed: {exc}", base_dir=_data_dir()
8581 )
8582 except Exception:
8583 pass
8584 await _send_json(send, {"status": "error", "error": str(exc)}, status=502)
8585 return
8586
8587 try:
8588 object_logs.append_object_log(
8589 "object_reader",
8590 "INFO",
8591 f"read_page fetched {url.strip()} -> {result['final_url']} "
8592 f"truncated={result['truncated']} actor={session.user_id}",
8593 base_dir=_data_dir(),
8594 )
8595 except Exception:
8596 pass
8597
8598 await _send_json(send, {"status": "ok", **result})
8599
8600
8601async def _handle_search(
8602 send,
8603 method: str,
8604 query: dict[str, str],
8605 headers: dict[str, str],
8606) -> None:
8607 if method != "GET":
8608 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8609 return
8610
8611 search_query = (query.get("q") or "").strip()
8612 if not search_query:
8613 await _send_json(
8614 send,
8615 {"status": "error", "error": "Search requires a q query parameter."},
8616 status=400,
8617 )
8618 return
8619
8620 try:
8621 limit = _query_int(
8622 query,
8623 "limit",
8624 default=object_search.DEFAULT_COLLECTION_LIMIT,
8625 minimum=1,
8626 maximum=object_search.MAX_COLLECTION_LIMIT,
8627 )
8628 except ValueError as exc:
8629 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8630 return
8631
8632 requested_raw = (query.get("collections") or "").strip()
8633 requested = {name.strip() for name in requested_raw.split(",") if name.strip()} or None
8634
8635 subject = None
8636 policy = None
8637 enforced = False
8638 if _permission_checks_enabled():
8639 subject = _permission_subject(headers)
8640 enforced = _permission_enforcement_enabled()
8641 try:
8642 policy = object_permission_store.load_policy(_data_dir())
8643 except ValueError as exc:
8644 await _send_json(
8645 send,
8646 {"status": "error", "error": f"Permission policy is invalid: {exc}"},
8647 status=500,
8648 )
8649 return
8650 else:
8651 gate_error = _admin_token_gate_error(headers, f"Search requires {ADMIN_TOKEN_ENV}.")
8652 if gate_error is not None:
8653 status, message = gate_error
8654 await _send_json(send, {"status": "error", "error": message}, status=status)
8655 return
8656
8657 results: dict[str, list[dict[str, str]]] = {}
8658 warnings: list[str] = []
8659 total = 0
8660 for summary in object_schemas.list_schemas(base_dir=_data_dir()):
8661 name = summary["name"]
8662 if requested is not None and name not in requested:
8663 continue
8664 try:
8665 schema = object_schemas.get_schema(name, base_dir=_data_dir())
8666 except (LookupError, ValueError):
8667 continue
8668
8669 try:
8670 config = object_search.search_config(schema)
8671 except object_search.InvalidSearchConfigError as exc:
8672 warnings.append(f"{name}: {exc}")
8673 continue
8674 if config is None:
8675 continue
8676
8677 if subject is not None and policy is not None:
8678 decision = object_permissions.check_permission(
8679 subject,
8680 object_permissions.READ,
8681 policy=policy,
8682 collection=name,
8683 )
8684 _append_permission_audit_entry(
8685 action=object_permissions.READ,
8686 object_id=None,
8687 collection=name,
8688 method="GET",
8689 subject=subject,
8690 enforced=enforced,
8691 decision=decision,
8692 )
8693 if enforced and not decision.allowed:
8694 continue
8695
8696 try:
8697 records = object_records.read_collection_records(name, base_dir=_data_dir())
8698 except (
8699 object_collections.CollectionNotFoundError,
8700 object_collections.InvalidCollectionNameError,
8701 ):
8702 records = []
8703 except ValueError:
8704 continue
8705
8706 if subject is not None and policy is not None and enforced:
8707 records = _filter_records_for_permission(
8708 records,
8709 collection=name,
8710 subject=subject,
8711 policy=policy,
8712 )
8713
8714 matches = object_search.search_records(records, search_query, config, limit=limit)
8715 results[name] = matches
8716 total += len(matches)
8717
8718 payload: dict[str, Any] = {
8719 "status": "ok",
8720 "query": search_query,
8721 "limit": limit,
8722 "results": results,
8723 "total_count": total,
8724 }
8725 if warnings:
8726 payload["warnings"] = warnings
8727 await _send_json(send, payload)
8728
8729
8730async def _handle_collections(
8731 send,
8732 method: str,
8733 headers: dict[str, str],
8734) -> None:
8735 if method != "GET":
8736 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8737 return
8738
8739 gate_error = _admin_token_gate_error(
8740 headers,
8741 f"Collection listing requires {ADMIN_TOKEN_ENV}.",
8742 )
8743 if gate_error is not None:
8744 status, message = gate_error
8745 await _send_json(send, {"status": "error", "error": message}, status=status)
8746 return
8747
8748 try:
8749 collections = object_collections.list_collections(base_dir=_data_dir())
8750 except ValueError as exc:
8751 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
8752 return
8753
8754 await _send_json(
8755 send,
8756 {
8757 "status": "ok",
8758 "collections": collections,
8759 "count": len(collections),
8760 },
8761 )
8762
8763
8764async def _handle_collection_get(
8765 send,
8766 method: str,
8767 collection: str,
8768 headers: dict[str, str],
8769) -> None:
8770 if method != "GET":
8771 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8772 return
8773
8774 gate_error = _admin_token_gate_error(
8775 headers,
8776 f"Collection detail requires {ADMIN_TOKEN_ENV}.",
8777 )
8778 if gate_error is not None:
8779 status, message = gate_error
8780 await _send_json(send, {"status": "error", "error": message}, status=status)
8781 return
8782
8783 try:
8784 summary = object_collections.get_collection(collection, base_dir=_data_dir())
8785 except object_collections.InvalidCollectionNameError as exc:
8786 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8787 return
8788 except object_collections.CollectionNotFoundError as exc:
8789 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
8790 return
8791 except ValueError as exc:
8792 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
8793 return
8794
8795 await _send_json(
8796 send,
8797 {
8798 "status": "ok",
8799 "collection": summary,
8800 },
8801 )
8802
8803
8804async def _handle_collection_records(
8805 send,
8806 method: str,
8807 collection: str,
8808 query: dict[str, str],
8809 body: bytes,
8810 headers: dict[str, str],
8811) -> None:
8812 if method == "GET":
8813 await _handle_collection_records_get(send, collection, query, headers)
8814 return
8815
8816 if method == "POST":
8817 await _handle_collection_record_create(send, collection, body, headers)
8818 return
8819
8820 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8821
8822
8823async def _handle_collection_records_get(
8824 send,
8825 collection: str,
8826 query: dict[str, str],
8827 headers: dict[str, str],
8828) -> None:
8829 permission_check = None
8830 if _permission_checks_enabled():
8831 permission_check = await _collection_permission_check(
8832 send,
8833 headers,
8834 object_permissions.READ,
8835 collection=collection,
8836 method="GET",
8837 )
8838 if permission_check is None:
8839 return
8840 else:
8841 gate_error = _admin_token_gate_error(
8842 headers,
8843 f"Collection records require {ADMIN_TOKEN_ENV}.",
8844 )
8845 if gate_error is not None:
8846 status, message = gate_error
8847 await _send_json(send, {"status": "error", "error": message}, status=status)
8848 return
8849
8850 try:
8851 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
8852 offset = _query_int(query, "offset", default=0, minimum=0)
8853 records = object_records.read_collection_records(collection, base_dir=_data_dir())
8854 except object_collections.InvalidCollectionNameError as exc:
8855 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8856 return
8857 except object_collections.CollectionNotFoundError as exc:
8858 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
8859 return
8860 except ValueError as exc:
8861 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
8862 return
8863
8864 enforced = permission_check is not None and permission_check["enforced"]
8865
8866 # 58's field filter (plan/vocabulary/58-query-filter-spec.md). Parsed
8867 # here, against the schema now known-valid (the read above already
8868 # confirmed the collection exists), but APPLIED below only after the
8869 # permission row filter has already run -- see the ordering note there.
8870 normalized_where: dict[str, list[dict[str, Any]]] = {}
8871 if _filtering_enabled():
8872 is_filterable = (
8873 _filterable_field_predicate(
8874 collection,
8875 subject=permission_check["subject"],
8876 policy=permission_check["policy"],
8877 decision=permission_check["decision"],
8878 )
8879 if enforced
8880 else _always_filterable
8881 )
8882 try:
8883 normalized_where = _parse_collection_record_filters(
8884 query,
8885 collection=collection,
8886 is_filterable=is_filterable,
8887 )
8888 except FilterParamError as exc:
8889 await _send_json(
8890 send,
8891 {
8892 "status": "error",
8893 "error": str(exc),
8894 "code": "invalid_filter",
8895 "param": exc.param,
8896 },
8897 status=400,
8898 )
8899 return
8900 elif any(key not in FILTER_RESERVED_PARAMS for key in query):
8901 _note_filtering_disabled_once()
8902
8903 if enforced:
8904 try:
8905 # The permission row filter: applied first, unconditionally,
8906 # over every record read above. redact=False: field redaction
8907 # is deferred past the field filter below, so a filter on a
8908 # field an admin may filter but not see (schema-hidden) can
8909 # still match against its real value -- see
8910 # _filter_records_for_permission's docstring.
8911 records = _filter_records_for_permission(
8912 records,
8913 collection=collection,
8914 subject=permission_check["subject"],
8915 policy=permission_check["policy"],
8916 redact=False,
8917 )
8918 except ValueError as exc:
8919 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
8920 return
8921
8922 if normalized_where:
8923 # The field filter: an ADDITIONAL AND over the row filter's own
8924 # output only (never the original `records`), which is what
8925 # structurally guarantees it can narrow the readable set but
8926 # never widen it -- see object_records.filter_records.
8927 records = object_records.filter_records(records, normalized_where)
8928
8929 # 63: a `_rev` per row, computed HERE -- after the row filter (so it
8930 # only covers rows the caller may see) and BEFORE field redaction (so
8931 # it is taken over the full surfaced record the write-side precondition
8932 # will compare against). Getting that order wrong is the whole subtlety:
8933 # a rev computed over a trimmed row can never match update's, and every
8934 # If-Match built from a list would 409 forever.
8935 #
8936 # WHY THIS EXISTS. Without it a claiming agent had to GET each candidate
8937 # individually just to obtain a rev before it could claim safely -- an
8938 # extra round trip per attempt on the one path 63 was written for
8939 # ("claim becomes race-safe"). A list that hands back rows you cannot
8940 # act on without re-reading them is a list that made the caller do the
8941 # work twice.
8942 #
8943 # Only the WINDOW is hashed, never the whole filtered set: the cost is
8944 # one sha256 per returned row (<=1000, default 100), not per matching
8945 # row, so a narrow page over a large collection stays cheap.
8946 revs = None
8947 if _concurrency_enabled():
8948 revs = {
8949 str(record["id"]): object_records.compute_record_rev(record)
8950 for record in records[offset:offset + limit]
8951 if record.get("id")
8952 }
8953
8954 if enforced:
8955 try:
8956 records = _redact_records_for_permission(
8957 records,
8958 collection=collection,
8959 subject=permission_check["subject"],
8960 policy=permission_check["policy"],
8961 )
8962 except ValueError as exc:
8963 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
8964 return
8965
8966 records_payload = object_records.collection_records_payload(
8967 collection,
8968 records,
8969 limit=limit,
8970 offset=offset,
8971 )
8972 # A parallel MAP rather than a `_rev` on each row, because the record
8973 # shape is a contract: the single-record read documents `_rev` as
8974 # "sibling metadata, never merged into record fields (must never
8975 # collide with a schema field or appear on write-back)". Merging it
8976 # into rows here would break that rule in the one place records are
8977 # most likely to be echoed straight back into a write.
8978 if revs is not None:
8979 records_payload["revs"] = revs
8980 await _send_json(send, {"status": "ok", **records_payload})
8981
8982
8983async def _handle_collection_changes(
8984 send,
8985 method: str,
8986 collection: str,
8987 query: dict[str, str],
8988 headers: dict[str, str],
8989) -> None:
8990 if method != "GET":
8991 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
8992 return
8993
8994 gate_error = _admin_token_gate_error(
8995 headers,
8996 f"Collection change history requires {ADMIN_TOKEN_ENV}.",
8997 )
8998 if gate_error is not None:
8999 status, message = gate_error
9000 await _send_json(send, {"status": "error", "error": message}, status=status)
9001 return
9002
9003 try:
9004 object_collections.get_collection(collection, base_dir=_data_dir())
9005 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
9006 offset = _query_int(query, "offset", default=0, minimum=0)
9007 changes = object_record_changes.list_record_changes(
9008 collection,
9009 base_dir=_data_dir(),
9010 limit=limit,
9011 offset=offset,
9012 )
9013 except object_collections.InvalidCollectionNameError as exc:
9014 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9015 return
9016 except object_collections.CollectionNotFoundError as exc:
9017 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9018 return
9019 except ValueError as exc:
9020 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9021 return
9022
9023 await _send_json(send, {"status": "ok", **changes})
9024
9025
9026async def _handle_collection_record_changes(
9027 send,
9028 method: str,
9029 collection: str,
9030 record_id: str,
9031 query: dict[str, str],
9032 headers: dict[str, str],
9033) -> None:
9034 if method != "GET":
9035 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
9036 return
9037
9038 gate_error = _admin_token_gate_error(
9039 headers,
9040 f"Collection record change history requires {ADMIN_TOKEN_ENV}.",
9041 )
9042 if gate_error is not None:
9043 status, message = gate_error
9044 await _send_json(send, {"status": "error", "error": message}, status=status)
9045 return
9046
9047 try:
9048 object_collections.get_collection(collection, base_dir=_data_dir())
9049 limit = _query_int(query, "limit", default=100, minimum=1, maximum=1000)
9050 offset = _query_int(query, "offset", default=0, minimum=0)
9051 changes = object_record_changes.list_record_changes(
9052 collection,
9053 record_id=record_id,
9054 base_dir=_data_dir(),
9055 limit=limit,
9056 offset=offset,
9057 )
9058 except object_collections.InvalidCollectionNameError as exc:
9059 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9060 return
9061 except object_records.InvalidRecordIdError as exc:
9062 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9063 return
9064 except object_collections.CollectionNotFoundError as exc:
9065 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9066 return
9067 except ValueError as exc:
9068 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9069 return
9070
9071 await _send_json(send, {"status": "ok", **changes})
9072
9073
9074def _collection_has_owner_field(collection: str) -> bool:
9075 """True if the collection's schema declares an owner_id field.
9076
9077 Used to decide whether a create should be stamped with the session's
9078 user as the owner. Schemaless or unknown collections return False (no
9079 field to stamp).
9080 """
9081 try:
9082 schema = object_schemas.get_schema(collection, base_dir=_data_dir())
9083 except Exception:
9084 return False
9085 return any(f.get("name") == "owner_id" for f in (schema.get("fields") or []))
9086
9087
9088_HOOK_METHOD = "BEFORE_WRITE"
9089
9090
9091def _before_write_hook_id(collection: str) -> str | None:
9092 """The collection's declared pre-write hook object id, if any.
9093
9094 Declared as `hooks: {"before_write": "<object_id>"}` at the schema root
9095 (whitelisted in object_schemas normalization; deliberately NOT exposed via
9096 /api/schema -- a server-side concern, never a client hint). Absent or
9097 blank -> no hook, and the write path pays one cached-schema dict lookup.
9098 """
9099 try:
9100 schema = object_schemas.get_schema(collection, base_dir=_data_dir())
9101 except (LookupError, OSError, ValueError):
9102 return None
9103 hooks = schema.get("hooks")
9104 if isinstance(hooks, dict):
9105 hook_id = hooks.get("before_write")
9106 if isinstance(hook_id, str) and hook_id.strip():
9107 return hook_id.strip()
9108 return None
9109
9110
9111def _hook_protected_fields(collection: str) -> set[str]:
9112 """Fields a hook transform may never change: identity/ownership plus every
9113 read-only/computed field. The hook has rejection power and transform power
9114 over ordinary fields only -- it cannot reassign a record or forge
9115 server-owned values."""
9116 protected = {"id", "owner_id"}
9117 try:
9118 schema = object_schemas.get_schema(collection, base_dir=_data_dir())
9119 except (LookupError, OSError, ValueError):
9120 return protected
9121 for field in schema.get("fields", []):
9122 if not isinstance(field, dict):
9123 continue
9124 field_type = str(field.get("type") or "").lower()
9125 if (
9126 field.get("read_only")
9127 or field.get("readonly")
9128 or field.get("computed")
9129 or field_type == "computed"
9130 ):
9131 name = field.get("name")
9132 if name:
9133 protected.add(str(name))
9134 return protected
9135
9136
9137async def _apply_before_write_hook(
9138 send,
9139 headers: dict[str, str],
9140 *,
9141 collection: str,
9142 action: str,
9143 record: dict[str, Any],
9144 existing: dict[str, Any] | None,
9145 changes: dict[str, Any],
9146) -> dict[str, Any] | None:
9147 """Run the collection's pre-write hook and return the record to persist.
9148
9149 Returns None when a response has already been sent (the hook rejected the
9150 write, or the hook itself failed). The contract
9151 (plan/pre-write-hook-spec.md): the hook object's BEFORE_WRITE(request)
9152 receives {collection, action, record, existing, changes, subject} and
9153 returns None/{} to allow, {"error", "status"?} to reject (4xx, its own
9154 message), or {"record": {...}} to transform.
9155
9156 Ordering and safety:
9157 - Runs AFTER permission/field checks -- a denied subject never reaches the
9158 hook, so a hook side effect can't leak that a write was attempted.
9159 - Fails CLOSED: declared-but-missing, raising, or non-contract hooks
9160 reject the write with 500 -- a validation gate that silently passes on
9161 error is not a gate.
9162 - Transforms cannot touch id/owner_id/read-only/computed fields
9163 (_hook_protected_fields), and the transformed record still goes through
9164 full schema validation in the persist call.
9165 - Executes in-process through the same path as any object
9166 (object_execution.execute_object + the execution log), so hook runs are
9167 observable like every other object run. Trusted server-side writers
9168 (daemon, migrations, seed-merge) call object_records directly and bypass
9169 hooks deliberately -- hooks gate the public write surface.
9170 """
9171 hook_id = _before_write_hook_id(collection)
9172 if hook_id is None:
9173 return record
9174
9175 subject = _permission_subject(headers)
9176 payload = {
9177 "collection": collection,
9178 "action": action,
9179 "record": dict(record),
9180 "existing": dict(existing) if existing is not None else None,
9181 "changes": dict(changes),
9182 "subject": {"user_id": subject.user_id, "roles": list(subject.roles or ())},
9183 }
9184 execution_request = object_execution.ObjectExecutionRequest(
9185 object_id=hook_id,
9186 method=_HOOK_METHOD,
9187 payload=payload,
9188 correlation_id=object_correlation.current_correlation_id(),
9189 )
9190 try:
9191 result = object_execution.execute_object(_runtime, execution_request)
9192 _append_execution_log(result)
9193 except Exception:
9194 result = None
9195
9196 async def _fail() -> None:
9197 await _send_json(
9198 send,
9199 {
9200 "status": "error",
9201 "error": f"Pre-write hook failed: {hook_id}",
9202 "code": "hook_failed",
9203 },
9204 status=500,
9205 )
9206
9207 if result is None or not result.ok:
9208 await _fail()
9209 return None
9210 outcome = result.result
9211 if outcome is None or outcome == {}:
9212 return record
9213 if not isinstance(outcome, dict):
9214 await _fail()
9215 return None
9216 error_message = outcome.get("error")
9217 if error_message:
9218 try:
9219 status = int(outcome.get("status") or 400)
9220 except (TypeError, ValueError):
9221 status = 400
9222 if not 400 <= status <= 499:
9223 status = 400
9224 await _send_json(
9225 send,
9226 {"status": "error", "error": str(error_message), "code": "hook_rejected"},
9227 status=status,
9228 )
9229 return None
9230 transformed = outcome.get("record")
9231 if transformed is None:
9232 return record
9233 if not isinstance(transformed, dict):
9234 await _fail()
9235 return None
9236 final = dict(transformed)
9237 for name in _hook_protected_fields(collection):
9238 if name in record:
9239 final[name] = record[name]
9240 else:
9241 final.pop(name, None)
9242 return final
9243
9244
9245async def _handle_collection_record_create(
9246 send,
9247 collection: str,
9248 body: bytes,
9249 headers: dict[str, str],
9250) -> None:
9251 try:
9252 record_payload = _record_payload_from_body(body, require_id=True)
9253 except ValueError as exc:
9254 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9255 return
9256
9257 permission_check = await _authorize_collection_write(
9258 send,
9259 headers,
9260 object_permissions.CREATE,
9261 collection=collection,
9262 method="POST",
9263 record=record_payload,
9264 gate_message=f"Collection record writes require {ADMIN_TOKEN_ENV}.",
9265 )
9266 if permission_check is None:
9267 return
9268 if permission_check["enforced"]:
9269 try:
9270 denied_fields = _schema_denied_write_fields(
9271 collection,
9272 record_payload.keys(),
9273 subject=permission_check["subject"],
9274 policy=permission_check["policy"],
9275 record=record_payload,
9276 )
9277 except ValueError as exc:
9278 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
9279 return
9280 if denied_fields:
9281 await _send_json(
9282 send,
9283 {
9284 "status": "error",
9285 "error": _field_write_denied_message(denied_fields),
9286 "code": "forbidden",
9287 "denied_fields": denied_fields,
9288 },
9289 status=403,
9290 )
9291 return
9292
9293 # Ownership is server-authoritative. For a signed-in create on a collection
9294 # that declares an owner_id field, stamp it from the session rather than
9295 # trusting the client -- a client could otherwise create a record owned by
9296 # someone else, or (as raw-API and agent/MCP creates did) leave it empty,
9297 # which silently breaks every owner-scoped rule and owner-gated transition
9298 # on that record. Admin-token writes (no session) keep any explicit
9299 # owner_id so seeding and migration can set ownership deliberately.
9300 # A per-user API key (the agent and script path) is that user as much as
9301 # a session is: it owns what it creates too. Before, only sessions were
9302 # stamped, so a record an API key created kept whatever owner_id the
9303 # client sent -- or none, leaving it outside its owner's own rules.
9304 owner = _signed_in_user_id(headers)
9305 if owner and _collection_has_owner_field(collection):
9306 record_payload = {**record_payload, "owner_id": owner}
9307
9308 hooked = await _apply_before_write_hook(
9309 send,
9310 headers,
9311 collection=collection,
9312 action="create",
9313 record=record_payload,
9314 existing=None,
9315 changes=record_payload,
9316 )
9317 if hooked is None:
9318 return
9319 record_payload = hooked
9320
9321 try:
9322 record = object_records.create_collection_record(
9323 collection,
9324 record_payload,
9325 base_dir=_data_dir(),
9326 actor=_record_change_actor(headers),
9327 )
9328 except object_collections.InvalidCollectionNameError as exc:
9329 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9330 return
9331 except object_collections.CollectionNotFoundError as exc:
9332 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9333 return
9334 except object_records.DuplicateRecordIdError as exc:
9335 await _send_json(send, {"status": "error", "error": str(exc)}, status=409)
9336 return
9337 except (object_records.InvalidRecordIdError, object_records.InvalidRecordPayloadError) as exc:
9338 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9339 return
9340 except ValueError as exc:
9341 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9342 return
9343 except OSError as exc:
9344 await _send_json(
9345 send,
9346 {"status": "error", "error": f"Could not save collection record: {exc}"},
9347 status=500,
9348 )
9349 return
9350
9351 # object_records.create_collection_record already durably appended the
9352 # attributed change (universal attribution); this only re-reads it so
9353 # realtime/handler/event-bus fan-out can use the real persisted
9354 # change_id/timestamp. A read failure here is not fatal -- the change
9355 # itself is already safely on disk -- so it only costs this one
9356 # best-effort publish.
9357 change = _record_change_for_publish(collection, record["id"])
9358 if change is not None:
9359 _publish_record_change_event(change, record=record)
9360
9361 await _send_json(
9362 send,
9363 {
9364 "status": "ok",
9365 "collection": collection,
9366 "record": record,
9367 },
9368 status=201,
9369 )
9370
9371
9372async def _handle_collection_record(
9373 send,
9374 method: str,
9375 collection: str,
9376 record_id: str,
9377 body: bytes,
9378 headers: dict[str, str],
9379) -> None:
9380 if method == "GET":
9381 await _handle_collection_record_get(send, collection, record_id, headers)
9382 return
9383
9384 if method == "PUT":
9385 await _handle_collection_record_update(send, collection, record_id, body, headers)
9386 return
9387
9388 if method == "DELETE":
9389 await _handle_collection_record_delete(send, collection, record_id, headers)
9390 return
9391
9392 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
9393
9394
9395async def _handle_collection_record_get(
9396 send,
9397 collection: str,
9398 record_id: str,
9399 headers: dict[str, str],
9400) -> None:
9401 if not _permission_checks_enabled():
9402 gate_error = _admin_token_gate_error(
9403 headers,
9404 f"Collection record detail requires {ADMIN_TOKEN_ENV}.",
9405 )
9406 if gate_error is not None:
9407 status, message = gate_error
9408 await _send_json(send, {"status": "error", "error": message}, status=status)
9409 return
9410
9411 try:
9412 record = object_records.get_collection_record(
9413 collection,
9414 record_id,
9415 base_dir=_data_dir(),
9416 )
9417 except object_collections.InvalidCollectionNameError as exc:
9418 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9419 return
9420 except object_records.InvalidRecordIdError as exc:
9421 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9422 return
9423 except (object_collections.CollectionNotFoundError, object_records.RecordNotFoundError) as exc:
9424 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9425 return
9426 except ValueError as exc:
9427 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9428 return
9429
9430 # 63: fingerprint the FULL stored record, before any field-visibility
9431 # policy trims it -- the write-side precondition (update_collection_record,
9432 # inside the lock) compares against the full surfaced row, so the token
9433 # a caller reads here must be computed over the same full record for the
9434 # two to agree. A caller who can't see a field still gets a `_rev` that
9435 # depends on it, which only ever fails CLOSED (a hidden-field change 409s
9436 # them conservatively); the hash discloses nothing about the field's value.
9437 rev = object_records.compute_record_rev(record)
9438
9439 if _permission_checks_enabled():
9440 permission_check = await _collection_permission_check(
9441 send,
9442 headers,
9443 object_permissions.READ,
9444 collection=collection,
9445 method="GET",
9446 record=record,
9447 )
9448 if permission_check is None:
9449 return
9450 if permission_check["enforced"]:
9451 try:
9452 record = _apply_record_field_policy(
9453 record,
9454 permission_check["decision"],
9455 collection=collection,
9456 subject=permission_check["subject"],
9457 policy=permission_check["policy"],
9458 )
9459 except ValueError as exc:
9460 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
9461 return
9462
9463 await _send_json(
9464 send,
9465 {
9466 "status": "ok",
9467 "collection": collection,
9468 "record": record,
9469 # Sibling metadata, never merged into record fields (must never
9470 # collide with a schema field or appear on write-back).
9471 object_records.REV_FIELD: rev,
9472 },
9473 )
9474
9475
9476async def _handle_collection_record_update(
9477 send,
9478 collection: str,
9479 record_id: str,
9480 body: bytes,
9481 headers: dict[str, str],
9482) -> None:
9483 if await _record_write_denied_before_lookup(
9484 send,
9485 headers,
9486 object_permissions.UPDATE,
9487 collection=collection,
9488 ):
9489 return
9490
9491 try:
9492 changes = _record_payload_from_body(body)
9493 existing = object_records.get_collection_record(
9494 collection,
9495 record_id,
9496 base_dir=_data_dir(),
9497 )
9498 except ValueError as exc:
9499 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9500 return
9501 except object_collections.InvalidCollectionNameError as exc:
9502 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9503 return
9504 except object_records.InvalidRecordIdError as exc:
9505 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9506 return
9507 except (object_collections.CollectionNotFoundError, object_records.RecordNotFoundError) as exc:
9508 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9509 return
9510
9511 # 63: resolve the optimistic-concurrency precondition. HTTP callers send
9512 # it as an `If-Match` header; the MCP bridge (no header channel) sends it
9513 # as a reserved `expected_rev` body key. Both are stripped here so neither
9514 # -- nor a `_rev` a client round-tripped back from a full-record read --
9515 # is ever treated as a field write. Header wins if both are present.
9516 expected_rev = headers.get("if-match")
9517 if isinstance(changes, dict):
9518 body_expected = changes.pop("expected_rev", None)
9519 changes.pop(object_records.REV_FIELD, None)
9520 if expected_rev is None and isinstance(body_expected, str):
9521 expected_rev = body_expected
9522 if expected_rev is not None:
9523 expected_rev = expected_rev.strip() or None
9524 if not _concurrency_enabled():
9525 expected_rev = None # flag off: precondition ignored, last-write-wins
9526
9527 record = await _gated_record_update(
9528 send,
9529 headers,
9530 collection=collection,
9531 record_id=record_id,
9532 existing=existing,
9533 changes=changes,
9534 expected_rev=expected_rev,
9535 )
9536 if record is None:
9537 return
9538
9539 await _send_json(
9540 send,
9541 {
9542 "status": "ok",
9543 "collection": collection,
9544 "record": record,
9545 # 63: the new fingerprint after this write -- a caller doing a
9546 # read-modify-write loop uses it as the If-Match for its next PUT
9547 # without a separate GET round-trip.
9548 object_records.REV_FIELD: object_records.compute_record_rev(record),
9549 },
9550 )
9551
9552
9553async def _gated_record_update(
9554 send,
9555 headers: dict[str, str],
9556 *,
9557 collection: str,
9558 record_id: str,
9559 existing: dict[str, Any],
9560 changes: dict[str, Any],
9561 expected_rev: str | None,
9562) -> dict[str, Any] | None:
9563 """Every gate an update passes, then the write and its publish.
9564
9565 Returns the stored record, or None when a response has already been
9566 sent (a gate refused, the hook rejected, the write failed). Extracted
9567 from _handle_collection_record_update so another surface that updates a
9568 record (WebDAV overwriting or renaming a file) cannot skip a gate by
9569 writing its own copy of them.
9570 """
9571 candidate = dict(existing)
9572 candidate.update(changes)
9573 candidate["id"] = record_id
9574
9575 permission_check = await _authorize_collection_write(
9576 send,
9577 headers,
9578 object_permissions.UPDATE,
9579 collection=collection,
9580 method="PUT",
9581 record=existing,
9582 gate_message=f"Collection record writes require {ADMIN_TOKEN_ENV}.",
9583 )
9584 if permission_check is None:
9585 return None
9586
9587 if _permission_enforcement_enabled():
9588 permission_check = await _authorize_collection_write(
9589 send,
9590 headers,
9591 object_permissions.UPDATE,
9592 collection=collection,
9593 method="PUT",
9594 record=candidate,
9595 gate_message=f"Collection record writes require {ADMIN_TOKEN_ENV}.",
9596 )
9597 if permission_check is None:
9598 return None
9599
9600 if permission_check["enforced"]:
9601 try:
9602 denied_fields = _schema_denied_write_fields(
9603 collection,
9604 changes.keys(),
9605 subject=permission_check["subject"],
9606 policy=permission_check["policy"],
9607 record=candidate,
9608 )
9609 except ValueError as exc:
9610 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
9611 return None
9612 if denied_fields:
9613 await _send_json(
9614 send,
9615 {
9616 "status": "error",
9617 "error": _field_write_denied_message(denied_fields),
9618 "code": "forbidden",
9619 "denied_fields": denied_fields,
9620 },
9621 status=403,
9622 )
9623 return None
9624
9625 hooked = await _apply_before_write_hook(
9626 send,
9627 headers,
9628 collection=collection,
9629 action="update",
9630 record=candidate,
9631 existing=existing,
9632 changes=changes,
9633 )
9634 if hooked is None:
9635 return None
9636 if hooked is not candidate:
9637 # Persist only the delta the hook produced on top of the caller's own
9638 # changes: update_collection_record treats every submitted key as a
9639 # field write, so echoing untouched read-only fields (created_at) back
9640 # through it would be rejected as read-only submissions. A change key
9641 # the hook dropped from its record is a cancelled change.
9642 final_changes = {k: v for k, v in changes.items() if k in hooked}
9643 for key, value in hooked.items():
9644 if key == "id":
9645 continue
9646 if key not in candidate or candidate.get(key) != value:
9647 final_changes[key] = value
9648 changes = final_changes
9649
9650 try:
9651 record = object_records.update_collection_record(
9652 collection,
9653 record_id,
9654 changes,
9655 base_dir=_data_dir(),
9656 actor=_record_change_actor(headers),
9657 transition_subject=permission_check["subject"],
9658 expected_rev=expected_rev,
9659 )
9660 except object_records.RecordNotFoundError as exc:
9661 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9662 return None
9663 except object_records.VersionConflictError as exc:
9664 # 63: the record changed since the caller read it -- no write, no
9665 # side effects. The caller re-GETs to see current state (and its new
9666 # `_rev`) and retries; the server does not echo the current row here.
9667 await _send_json(
9668 send,
9669 {"status": "error", "error": str(exc), "code": "conflict"},
9670 status=409,
9671 )
9672 return None
9673 except object_records.TransitionNotAllowedError as exc:
9674 await _send_json(
9675 send,
9676 {"status": "error", "error": str(exc), "code": "forbidden"},
9677 status=403,
9678 )
9679 return None
9680 except (object_records.InvalidRecordIdError, object_records.InvalidRecordPayloadError) as exc:
9681 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9682 return None
9683 except ValueError as exc:
9684 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9685 return None
9686 except OSError as exc:
9687 await _send_json(
9688 send,
9689 {"status": "error", "error": f"Could not save collection record: {exc}"},
9690 status=500,
9691 )
9692 return None
9693
9694 # See the matching comment in _handle_collection_record_create: the
9695 # attributed change is already durably appended by
9696 # object_records.update_collection_record; this just re-reads it for
9697 # publish.
9698 change = _record_change_for_publish(collection, record_id)
9699 if change is not None:
9700 _publish_record_change_event(change, record=record)
9701 return record
9702
9703
9704async def _handle_collection_record_delete(
9705 send,
9706 collection: str,
9707 record_id: str,
9708 headers: dict[str, str],
9709) -> None:
9710 if await _record_write_denied_before_lookup(
9711 send,
9712 headers,
9713 object_permissions.DELETE,
9714 collection=collection,
9715 ):
9716 return
9717
9718 try:
9719 existing = object_records.get_collection_record(
9720 collection,
9721 record_id,
9722 base_dir=_data_dir(),
9723 )
9724 except object_collections.InvalidCollectionNameError as exc:
9725 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9726 return
9727 except object_records.InvalidRecordIdError as exc:
9728 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9729 return
9730 except (object_collections.CollectionNotFoundError, object_records.RecordNotFoundError) as exc:
9731 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9732 return
9733 except ValueError as exc:
9734 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9735 return
9736
9737 permission_check = await _authorize_collection_write(
9738 send,
9739 headers,
9740 object_permissions.DELETE,
9741 collection=collection,
9742 method="DELETE",
9743 record=existing,
9744 gate_message=f"Collection record writes require {ADMIN_TOKEN_ENV}.",
9745 )
9746 if permission_check is None:
9747 return
9748
9749 try:
9750 record = object_records.delete_collection_record(
9751 collection,
9752 record_id,
9753 base_dir=_data_dir(),
9754 actor=_record_change_actor(headers),
9755 )
9756 except object_records.RecordNotFoundError as exc:
9757 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
9758 return
9759 except object_records.InvalidRecordIdError as exc:
9760 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9761 return
9762 except ValueError as exc:
9763 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9764 return
9765 except OSError as exc:
9766 await _send_json(
9767 send,
9768 {"status": "error", "error": f"Could not delete collection record: {exc}"},
9769 status=500,
9770 )
9771 return
9772
9773 # See the matching comment in _handle_collection_record_create: the
9774 # attributed change is already durably appended by
9775 # object_records.delete_collection_record; this just re-reads it for
9776 # publish.
9777 change = _record_change_for_publish(collection, record_id)
9778 if change is not None:
9779 _publish_record_change_event(change, record=record)
9780
9781 await _send_json(
9782 send,
9783 {
9784 "status": "ok",
9785 "collection": collection,
9786 "record": record,
9787 "deleted": True,
9788 },
9789 )
9790
9791
9792async def _record_write_denied_before_lookup(
9793 send,
9794 headers: dict[str, str],
9795 action: str,
9796 *,
9797 collection: str,
9798) -> bool:
9799 """Deny unauthorized record writes before any record existence lookup.
9800
9801 Without this, a 404 for a missing record would leak record-id existence to
9802 callers who are not allowed to write at all. Subjects allowed at the
9803 collection level (including row-filtered allows) proceed to the normal
9804 record-aware authorization.
9805 """
9806 if not _permission_enforcement_enabled():
9807 gate_error = _admin_token_gate_error(
9808 headers,
9809 f"Collection record writes require {ADMIN_TOKEN_ENV}.",
9810 )
9811 if gate_error is not None:
9812 status, message = gate_error
9813 await _send_json(send, {"status": "error", "error": message}, status=status)
9814 return True
9815 return False
9816
9817 subject = _permission_subject(headers)
9818 try:
9819 policy = object_permission_store.load_policy(_data_dir())
9820 decision = object_permissions.check_permission(
9821 subject,
9822 action,
9823 policy=policy,
9824 collection=collection,
9825 )
9826 except ValueError:
9827 return False
9828
9829 if decision.allowed:
9830 return False
9831
9832 await _send_json(
9833 send,
9834 {
9835 "status": "error",
9836 "error": decision.reason,
9837 "code": decision.code,
9838 },
9839 status=decision.http_status,
9840 )
9841 return True
9842
9843
9844async def _authorize_collection_write(
9845 send,
9846 headers: dict[str, str],
9847 action: str,
9848 *,
9849 collection: str,
9850 method: str,
9851 record: dict[str, Any],
9852 gate_message: str,
9853) -> dict[str, Any] | None:
9854 if _permission_enforcement_enabled():
9855 return await _collection_permission_check(
9856 send,
9857 headers,
9858 action,
9859 collection=collection,
9860 method=method,
9861 record=record,
9862 )
9863
9864 if _permission_audit_enabled():
9865 permission_check = await _collection_permission_check(
9866 send,
9867 headers,
9868 action,
9869 collection=collection,
9870 method=method,
9871 record=record,
9872 )
9873 if permission_check is None:
9874 return None
9875
9876 gate_error = _admin_token_gate_error(headers, gate_message)
9877 if gate_error is not None:
9878 status, message = gate_error
9879 await _send_json(send, {"status": "error", "error": message}, status=status)
9880 return None
9881
9882 return {
9883 "subject": _permission_subject(headers),
9884 "policy": object_permissions.PermissionPolicy(access_mode="public"),
9885 "decision": object_permissions.PermissionDecision.allow("admin token"),
9886 "enforced": False,
9887 }
9888
9889
9890async def _handle_schemas(
9891 send,
9892 method: str,
9893 headers: dict[str, str],
9894) -> None:
9895 if method != "GET":
9896 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
9897 return
9898
9899 gate_error = _admin_token_gate_error(
9900 headers,
9901 f"Schema listing requires {ADMIN_TOKEN_ENV}.",
9902 )
9903 if gate_error is not None:
9904 status, message = gate_error
9905 await _send_json(send, {"status": "error", "error": message}, status=status)
9906 return
9907
9908 try:
9909 schemas = object_schemas.list_schemas(base_dir=_data_dir())
9910 except ValueError as exc:
9911 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
9912 return
9913
9914 await _send_json(
9915 send,
9916 {
9917 "status": "ok",
9918 "schemas": schemas,
9919 "count": len(schemas),
9920 },
9921 )
9922
9923
9924async def _handle_schema_get(
9925 send,
9926 method: str,
9927 schema: str,
9928 headers: dict[str, str],
9929) -> None:
9930 await _handle_schema(send, method, schema, {}, b"", headers)
9931
9932
9933async def _handle_schema_meta(send, method: str, collection: str) -> None:
9934 """Public schema metadata for building UIs (form/list generators).
9935
9936 Returns the *structure* only — field types, labels, enums, relations,
9937 validation, forms, views, search — never data. Records stay
9938 permission-gated; knowing a collection's field shape is not a leak, and
9939 it lets any surface (web, anonymous public pages, agents) render itself
9940 from the schema.
9941 """
9942 if method != "GET":
9943 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
9944 return
9945 try:
9946 schema = object_schemas.get_schema(collection, base_dir=_data_dir())
9947 except object_schemas.InvalidSchemaNameError as exc:
9948 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
9949 return
9950 except (LookupError, ValueError):
9951 await _send_json(send, {"status": "error", "error": "Schema not found"}, status=404)
9952 return
9953
9954 meta = {key: schema.get(key)
9955 for key in ("name", "title", "fields", "forms", "views", "search", "flow", "capabilities")}
9956 await _send_json(send, {"status": "ok", "schema": meta})
9957
9958
9959USER_PREFS_COLLECTION = "user_prefs"
9960FEATURE_FLAGS_COLLECTION = "feature_flags"
9961FLAG_PREF_PREFIX = "flag:"
9962_PREF_KEY_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
9963
9964
9965def _valid_pref_key(key: str) -> bool:
9966 """Route-safe key charset: no slashes, no whitespace, bounded length."""
9967 return isinstance(key, str) and bool(_PREF_KEY_RE.fullmatch(key))
9968
9969
9970def _read_user_prefs_or_empty() -> list[dict[str, str]]:
9971 try:
9972 return object_records.read_collection_records(
9973 USER_PREFS_COLLECTION, base_dir=_data_dir(), roots=get_object_roots()
9974 )
9975 except (
9976 object_collections.CollectionNotFoundError,
9977 object_collections.InvalidCollectionNameError,
9978 OSError,
9979 ValueError,
9980 ):
9981 return []
9982
9983
9984def _read_feature_flags_or_empty() -> list[dict[str, str]]:
9985 try:
9986 return object_records.read_collection_records(
9987 FEATURE_FLAGS_COLLECTION, base_dir=_data_dir(), roots=get_object_roots()
9988 )
9989 except (
9990 object_collections.CollectionNotFoundError,
9991 object_collections.InvalidCollectionNameError,
9992 OSError,
9993 ValueError,
9994 ):
9995 return []
9996
9997
9998def _user_prefs_map(user_id: str) -> dict[str, str]:
9999 """Collapse one user's own user_prefs rows to a key -> value map."""
10000 prefs: dict[str, str] = {}
10001 for row in _read_user_prefs_or_empty():
10002 if row.get("owner_id") == user_id and row.get("key"):
10003 prefs[row["key"]] = row.get("value", "")
10004 return prefs
10005
10006
10007def _find_user_pref(user_id: str, key: str) -> dict[str, str] | None:
10008 for row in _read_user_prefs_or_empty():
10009 if row.get("owner_id") == user_id and row.get("key") == key:
10010 return row
10011 return None
10012
10013
10014def _upsert_user_pref(user_id: str, key: str, value: str) -> dict[str, str]:
10015 """Create or update the caller's own user_prefs row for ``key``.
10016
10017 ``user_id`` must come from the session-derived subject, never from
10018 client input -- this is the only thing that keeps prefs owner-scoped.
10019 """
10020 existing = _find_user_pref(user_id, key)
10021 if existing is not None:
10022 return object_records.update_collection_record(
10023 USER_PREFS_COLLECTION,
10024 existing["id"],
10025 {"value": value},
10026 base_dir=_data_dir(),
10027 roots=get_object_roots(),
10028 actor=user_id,
10029 )
10030 return object_records.create_collection_record(
10031 USER_PREFS_COLLECTION,
10032 {
10033 "id": object_ids.new_uuid4(),
10034 "owner_id": user_id,
10035 "key": key,
10036 "value": value,
10037 },
10038 base_dir=_data_dir(),
10039 roots=get_object_roots(),
10040 actor=user_id,
10041 )
10042
10043
10044def _resolve_flags(user_id: str | None) -> dict[str, str]:
10045 """Effective flag values: instance feature_flags overlaid by the
10046 caller's own ``flag:<name>`` user_prefs entries.
10047
10048 Resolution order is user override -> instance value, per
10049 docs/upgrade-and-customization.md Rule 5. Anonymous callers (user_id is
10050 None) only ever see the instance-wide values.
10051 """
10052 flags: dict[str, str] = {}
10053 for row in _read_feature_flags_or_empty():
10054 flag = row.get("flag")
10055 if flag:
10056 flags[flag] = row.get("value", "")
10057 if user_id is not None:
10058 for row in _read_user_prefs_or_empty():
10059 if row.get("owner_id") != user_id:
10060 continue
10061 key = row.get("key") or ""
10062 if key.startswith(FLAG_PREF_PREFIX):
10063 flags[key[len(FLAG_PREF_PREFIX):]] = row.get("value", "")
10064 return flags
10065
10066
10067async def _handle_prefs(send, method: str, headers: dict[str, str]) -> None:
10068 """GET /prefs -> the caller's own user_prefs rows collapsed to a map.
10069
10070 Session-scoped by construction: the owner filter always comes from the
10071 caller's own identity, so this never needs the general collection
10072 permission engine. Anonymous callers get an empty map rather than a
10073 401 -- reading your own (empty) preferences is harmless.
10074 """
10075 if method != "GET":
10076 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10077 return
10078 subject = _permission_subject(headers)
10079 prefs = _user_prefs_map(subject.user_id) if subject.user_id is not None else {}
10080 await _send_json(send, {"status": "ok", "prefs": prefs})
10081
10082
10083async def _handle_pref(
10084 send,
10085 method: str,
10086 key: str,
10087 body: bytes,
10088 headers: dict[str, str],
10089) -> None:
10090 """GET/PUT one preference for the caller, by key.
10091
10092 Never accepts owner_id/user_id from the client -- the row is always
10093 looked up and written against the session-derived subject.
10094 """
10095 if method not in {"GET", "PUT"}:
10096 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10097 return
10098 if not _valid_pref_key(key):
10099 await _send_json(send, {"status": "error", "error": "Invalid preference key"}, status=400)
10100 return
10101
10102 subject = _permission_subject(headers)
10103
10104 if method == "GET":
10105 row = _find_user_pref(subject.user_id, key) if subject.user_id is not None else None
10106 if row is None:
10107 await _send_json(send, {"status": "error", "error": "Preference not found"}, status=404)
10108 return
10109 await _send_json(send, {"status": "ok", "key": key, "value": row.get("value", "")})
10110 return
10111
10112 if subject.user_id is None:
10113 await _send_json(
10114 send,
10115 {"status": "error", "error": "Setting preferences requires a signed-in session."},
10116 status=401,
10117 )
10118 return
10119
10120 try:
10121 payload = _parse_json_body(body)
10122 except ValueError as exc:
10123 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10124 return
10125
10126 value = payload.get("value")
10127 if not isinstance(value, str):
10128 await _send_json(
10129 send,
10130 {"status": "error", "error": "Request JSON field 'value' must be a string"},
10131 status=400,
10132 )
10133 return
10134
10135 try:
10136 _upsert_user_pref(subject.user_id, key, value)
10137 except (
10138 object_collections.InvalidCollectionNameError,
10139 object_records.InvalidRecordIdError,
10140 object_records.InvalidRecordPayloadError,
10141 ValueError,
10142 ) as exc:
10143 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10144 return
10145 except object_collections.CollectionNotFoundError as exc:
10146 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
10147 return
10148 except OSError as exc:
10149 await _send_json(
10150 send,
10151 {"status": "error", "error": f"Could not save preference: {exc}"},
10152 status=500,
10153 )
10154 return
10155
10156 await _send_json(send, {"status": "ok", "key": key, "value": value})
10157
10158
10159async def _handle_flags(send, method: str, headers: dict[str, str]) -> None:
10160 """GET /api/flags -> effective feature flags for the caller.
10161
10162 Public/session-aware like /api/schema: works anonymously (instance
10163 values only) and overlays the caller's own per-user overrides when
10164 signed in.
10165 """
10166 if method != "GET":
10167 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10168 return
10169 subject = _permission_subject(headers)
10170 flags = _resolve_flags(subject.user_id)
10171 await _send_json(send, {"status": "ok", "flags": flags})
10172
10173
10174async def _handle_activity(
10175 send,
10176 method: str,
10177 query: dict[str, str],
10178 headers: dict[str, str],
10179) -> None:
10180 """GET /api/activity -> the caller's own recent activity feed.
10181
10182 A thin read-only wrapper over object_activity.recent_activity, scoped to
10183 the signed-in caller's own changes (see that module's docstring for why
10184 v1 only does "your activity"). Unlike /prefs, which hands anonymous
10185 callers an empty map because reading your own (empty) preferences is
10186 harmless, a feed endpoint rejects anonymous callers outright -- there is
10187 no legitimate empty-but-still-answerable case here, only "no session".
10188 """
10189 if method != "GET":
10190 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10191 return
10192
10193 session = _current_identity_session(headers)
10194 if session is None:
10195 await _send_json(
10196 send,
10197 {"status": "error", "error": "Activity requires a signed-in session."},
10198 status=401,
10199 )
10200 return
10201
10202 try:
10203 limit = _query_int(query, "limit", default=50, minimum=1, maximum=200)
10204 except ValueError as exc:
10205 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10206 return
10207
10208 entries = object_activity.recent_activity(
10209 base_dir=_data_dir(), actor=session.user_id, limit=limit
10210 )
10211 await _send_json(send, {"status": "ok", "activity": entries})
10212
10213
10214async def _handle_stock_levels(send, method: str, headers: dict[str, str]) -> None:
10215 """GET /api/stock -> Stage-7 get_stock_levels: the caller's on-hand stock,
10216 folded from stock_moves (object_stock.stock_levels). Owner-scoped -- the
10217 same fold the site_stock page uses, exposed as JSON for the MCP verb. A
10218 missing stock_moves collection or an anonymous caller returns an empty,
10219 non-error summary (nothing to fold), never a 500.
10220 """
10221 if method != "GET":
10222 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10223 return
10224 subject = _permission_subject(headers)
10225 if not subject.user_id:
10226 await _send_json(send, {"status": "ok", "levels": [], "totals": [], "authenticated": False})
10227 return
10228 try:
10229 levels = object_stock.stock_levels(base_dir=_data_dir(), owner=subject.user_id)
10230 except (object_collections.CollectionNotFoundError, object_collections.InvalidCollectionNameError):
10231 levels = {"levels": [], "totals": []}
10232 except (OSError, ValueError) as exc:
10233 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
10234 return
10235 await _send_json(send, {"status": "ok", **levels})
10236
10237
10238async def _handle_finance_summary(send, method: str, headers: dict[str, str]) -> None:
10239 """GET /api/finance/summary -> Stage-7 get_finance_summary: the caller's
10240 trial balance (per-account debit/credit totals over POSTED journals),
10241 folded by object_finance.trial_balance. Owner-scoped, same report the
10242 site_trial_balance page renders, as JSON for the MCP verb. No journals /
10243 anonymous -> empty rows, never a 500.
10244 """
10245 if method != "GET":
10246 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10247 return
10248 subject = _permission_subject(headers)
10249 if not subject.user_id:
10250 await _send_json(send, {"status": "ok", "rows": [], "authenticated": False})
10251 return
10252 try:
10253 rows = object_finance.trial_balance(base_dir=_data_dir(), owner=subject.user_id)
10254 except (object_collections.CollectionNotFoundError, object_collections.InvalidCollectionNameError):
10255 rows = []
10256 except (OSError, ValueError) as exc:
10257 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
10258 return
10259 await _send_json(send, {"status": "ok", "rows": rows})
10260
10261
10262async def _handle_feed(
10263 send,
10264 method: str,
10265 query: dict[str, str],
10266 headers: dict[str, str],
10267) -> None:
10268 """GET /api/feed -> 64's composed, permission-gated follow-graph read.
10269
10270 For the signed-in caller V: recent PUBLIC content authored by the
10271 accounts V follows, newest-first (plan/vocabulary/64-feed-spec.md).
10272 v1 is a pure filtered-read COMPOSITION -- two existing permission-gated
10273 /collections/{c}/records reads (58), riding V's own forwarded
10274 credentials through _internal_request -- never a direct read of the
10275 record layer. That is what guarantees the core privacy invariant: a
10276 followed account's PRIVATE content can never enter the feed, because
10277 every source read is subject to that collection's own row-filtered
10278 permission rule (e.g. articles' `public read where is_public=true`)
10279 exactly as if V had queried it directly. Following someone grants no
10280 additional read access -- it only adds an `owner_id IN (followed set)`
10281 predicate on top of the row filter that already applies.
10282
10283 No 401 for an anonymous caller (unlike /api/activity above): the spec's
10284 Surfaces section says the feed is simply "not rendered" for anonymous
10285 visitors, and Degradation asks for an empty, non-error response in
10286 every degraded case (feed disabled, no viewer, no follows) -- so every
10287 early-return here is a 200 with an empty `items` list plus a flag
10288 saying why, never a 4xx/5xx.
10289 """
10290 if method != "GET":
10291 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10292 return
10293
10294 subject = _permission_subject(headers)
10295 viewer_id = subject.user_id
10296 if not viewer_id:
10297 await _send_json(
10298 send,
10299 {"status": "ok", "items": [], "count": 0, "authenticated": False},
10300 )
10301 return
10302
10303 if not _feed_enabled():
10304 await _send_json(
10305 send,
10306 {"status": "ok", "items": [], "count": 0, "enabled": False},
10307 )
10308 return
10309
10310 try:
10311 limit = _query_int(query, "limit", default=50, minimum=1, maximum=200)
10312 offset = _query_int(query, "offset", default=0, minimum=0)
10313 except ValueError as exc:
10314 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10315 return
10316
10317 # Forward V's own credentials to every sub-read: a bearer/admin token
10318 # header if present, else the session cookie re-expressed as a bearer
10319 # token (_internal_request only carries an Authorization header, no
10320 # cookie jar) -- see _permission_identity for the same cookie-or-token
10321 # resolution order used to build `subject` above.
10322 authorization = headers.get("authorization") or ""
10323 if not authorization:
10324 cookie_token = _session_cookie_token(headers)
10325 if cookie_token:
10326 authorization = f"Bearer {cookie_token}"
10327
10328 follows_query = urllib.parse.urlencode([("follower_id.eq", viewer_id), ("limit", "500")])
10329 follows_status, follows_payload = await _internal_request(
10330 "GET",
10331 "/collections/follows/records",
10332 follows_query,
10333 b"",
10334 authorization=authorization,
10335 )
10336
10337 following_ids: list[str] = []
10338 if follows_status == 200 and isinstance(follows_payload, dict):
10339 for row in follows_payload.get("records") or []:
10340 following_id = row.get("following_id") if isinstance(row, dict) else None
10341 if following_id and following_id not in following_ids:
10342 following_ids.append(following_id)
10343
10344 # 58's `in` cap (FILTER_IN_MAX_VALUES) directly bounds how many followed
10345 # accounts one feed read can scan. Over the cap: truncate to the first
10346 # N and say so, rather than silently dropping accounts or raising 58's
10347 # cap on this call site's behalf -- the spec's Storage section names
10348 # this exact cap-hit as the forcing function for the materialized
10349 # feed_items path, not something to paper over here.
10350 truncated_following = len(following_ids) > FILTER_IN_MAX_VALUES
10351 if truncated_following:
10352 following_ids = following_ids[:FILTER_IN_MAX_VALUES]
10353
10354 response: dict[str, Any] = {"status": "ok", "authenticated": True}
10355 if truncated_following:
10356 response["truncated_following"] = True
10357
10358 if not following_ids:
10359 response.update({"items": [], "count": 0})
10360 await _send_json(send, response)
10361 return
10362
10363 items: list[dict[str, Any]] = []
10364 for source in _feed_sources():
10365 pairs = [(f"{source['owner_field']}.in", ",".join(following_ids))]
10366 if source["visibility_field"] and source["visibility_true_value"] is not None:
10367 pairs.append(
10368 (f"{source['visibility_field']}.eq", str(source["visibility_true_value"]))
10369 )
10370 pairs.append(("limit", "200"))
10371 source_status, source_payload = await _internal_request(
10372 "GET",
10373 f"/collections/{source['collection']}/records",
10374 urllib.parse.urlencode(pairs),
10375 b"",
10376 authorization=authorization,
10377 )
10378 if source_status != 200 or not isinstance(source_payload, dict):
10379 # One bad/missing/disallowed source degrades to fewer sources,
10380 # never an error -- same isolation 14's rollup definitions use
10381 # for "one bad definition is logged and skipped", applied here
10382 # to feed sources (spec's Degradation section).
10383 continue
10384 for record in source_payload.get("records") or []:
10385 if not isinstance(record, dict):
10386 continue
10387 items.append(
10388 {
10389 "source_collection": source["collection"],
10390 "source_id": record.get(source["link_field"]) or record.get("id"),
10391 "author_id": record.get(source["owner_field"]),
10392 "time": record.get(source["time_field"]) or "",
10393 "summary": _feed_item_summary(record, source["summary_fields"]),
10394 "record": record,
10395 }
10396 )
10397
10398 # Step 3 of the spec's read shape: merge every source's already-small,
10399 # already-filtered rows by time_field, newest first -- no server sort
10400 # param exists for /collections/{c}/records (58's own Open Questions),
10401 # so this handler does the k-way merge itself.
10402 items.sort(key=lambda item: item["time"], reverse=True)
10403 total = len(items)
10404 window = items[offset : offset + limit]
10405 response.update({"items": window, "count": len(window), "total": total})
10406 await _send_json(send, response)
10407
10408
10409def _feed_enabled() -> bool:
10410 value = os.environ.get(FEED_ENABLED_ENV)
10411 if value is None:
10412 return True
10413 return value.strip().lower() in TRUE_VALUES
10414
10415
10416def _feed_sources() -> list[dict[str, Any]]:
10417 """Discover feed-source collections via schema metadata (64's `blocks.feed`).
10418
10419 A collection opts into the feed by declaring `blocks.feed` in its
10420 schema (plan/vocabulary/64-feed-spec.md's Parameterization section) --
10421 additive-opt-in, same posture as every other block key in this
10422 vocabulary; nothing is swept in by default.
10423
10424 `blocks` is a first-class schema metadata key (whitelisted in
10425 object_schemas._normalize_schema alongside `flow`/`views`), so it
10426 survives normalization and install and is read through the ordinary,
10427 cached get_schema path -- never a raw side-channel file read.
10428 """
10429 sources: list[dict[str, Any]] = []
10430 try:
10431 summaries = object_schemas.list_schemas(base_dir=_data_dir())
10432 except (OSError, ValueError):
10433 return sources
10434
10435 for summary in summaries:
10436 if summary.get("source") != "manual":
10437 continue # blocks.feed can only be declared in a manual schema
10438 name = summary.get("name")
10439 if not name or not object_schemas.validate_schema_name(name):
10440 continue
10441 try:
10442 raw = object_schemas.get_schema(name, base_dir=_data_dir())
10443 except (object_schemas.SchemaNotFoundError, OSError, ValueError):
10444 continue
10445 if not isinstance(raw, dict):
10446 continue
10447
10448 blocks = raw.get("blocks")
10449 feed_block = blocks.get("feed") if isinstance(blocks, dict) else None
10450 if not isinstance(feed_block, dict):
10451 continue
10452
10453 owner_field = feed_block.get("owner_field")
10454 time_field = feed_block.get("time_field")
10455 if not isinstance(owner_field, str) or not owner_field:
10456 continue
10457 if not isinstance(time_field, str) or not time_field:
10458 continue
10459
10460 summary_fields = feed_block.get("summary_fields")
10461 if not isinstance(summary_fields, list) or not summary_fields:
10462 views = raw.get("views")
10463 summary_fields = views.get("list_fields") if isinstance(views, dict) else None
10464 if not isinstance(summary_fields, list):
10465 summary_fields = []
10466 summary_fields = [field for field in summary_fields if isinstance(field, str)]
10467
10468 link_field = feed_block.get("link_field")
10469 if not isinstance(link_field, str) or not link_field:
10470 link_field = "id"
10471
10472 visibility_field = feed_block.get("visibility_field")
10473 if not isinstance(visibility_field, str) or not visibility_field:
10474 visibility_field = None
10475
10476 sources.append(
10477 {
10478 "collection": name,
10479 "owner_field": owner_field,
10480 "visibility_field": visibility_field,
10481 "visibility_true_value": feed_block.get("visibility_true_value"),
10482 "time_field": time_field,
10483 "summary_fields": summary_fields,
10484 "link_field": link_field,
10485 }
10486 )
10487 return sources
10488
10489
10490def _feed_item_summary(record: dict[str, Any], summary_fields: list[str]) -> str:
10491 parts = [str(record[field]).strip() for field in summary_fields if record.get(field)]
10492 return " — ".join(part for part in parts if part)
10493
10494
10495async def _handle_schema(
10496 send,
10497 method: str,
10498 schema: str,
10499 query: dict[str, str],
10500 body: bytes,
10501 headers: dict[str, str],
10502) -> None:
10503 if method != "GET":
10504 if method == "PUT":
10505 await _handle_schema_put(send, schema, body, headers)
10506 return
10507 if method == "POST":
10508 await _handle_schema_post(send, schema, body, headers)
10509 return
10510 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10511 return
10512
10513 if query.get("versions") == "true":
10514 await _handle_schema_versions_get(send, schema, query, headers)
10515 return
10516
10517 if "version" in query:
10518 await _handle_schema_version_get(send, schema, query, headers)
10519 return
10520
10521 gate_error = _admin_token_gate_error(
10522 headers,
10523 f"Schema detail requires {ADMIN_TOKEN_ENV}.",
10524 )
10525 if gate_error is not None:
10526 status, message = gate_error
10527 await _send_json(send, {"status": "error", "error": message}, status=status)
10528 return
10529
10530 try:
10531 schema_payload = object_schemas.get_schema(schema, base_dir=_data_dir())
10532 except object_schemas.InvalidSchemaNameError as exc:
10533 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10534 return
10535 except object_schemas.SchemaNotFoundError as exc:
10536 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
10537 return
10538 except ValueError as exc:
10539 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
10540 return
10541
10542 await _send_json(
10543 send,
10544 {
10545 "status": "ok",
10546 "schema": schema_payload,
10547 },
10548 )
10549
10550
10551async def _handle_schema_put(
10552 send,
10553 schema: str,
10554 body: bytes,
10555 headers: dict[str, str],
10556) -> None:
10557 gate_error = _admin_token_gate_error(
10558 headers,
10559 f"Schema writes require {ADMIN_TOKEN_ENV}.",
10560 )
10561 if gate_error is not None:
10562 status, message = gate_error
10563 await _send_json(send, {"status": "error", "error": message}, status=status)
10564 return
10565
10566 try:
10567 payload = _parse_json_body(body)
10568 schema_payload = _schema_payload_from_request(payload)
10569 normalized_schema = object_schemas.normalize_schema(schema, schema_payload, source="manual")
10570 author = _payload_text(payload, "author", "api")
10571 message = _payload_text(payload, "message", "Updated schema via API")
10572 version_id = _schema_version_manager().save_version(
10573 schema=schema,
10574 content=object_schema_versions.schema_version_content(normalized_schema),
10575 author=author,
10576 message=message,
10577 )
10578 saved_schema = object_schemas.replace_schema(
10579 schema,
10580 normalized_schema,
10581 base_dir=_data_dir(),
10582 )
10583 except object_schemas.InvalidSchemaNameError as exc:
10584 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10585 return
10586 except object_schema_versions.InvalidSchemaNameError as exc:
10587 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10588 return
10589 except ValueError as exc:
10590 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10591 return
10592 except OSError as exc:
10593 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
10594 return
10595
10596 await _send_json(
10597 send,
10598 {
10599 "status": "ok",
10600 "message": f"Schema updated to version {version_id}",
10601 "version_id": version_id,
10602 "collection": schema,
10603 "schema": saved_schema,
10604 },
10605 )
10606
10607
10608async def _handle_schema_post(
10609 send,
10610 schema: str,
10611 body: bytes,
10612 headers: dict[str, str],
10613) -> None:
10614 try:
10615 payload = _parse_json_body(body)
10616 except ValueError as exc:
10617 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10618 return
10619
10620 if payload.get("action") != "rollback":
10621 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
10622 return
10623
10624 await _handle_schema_rollback_post(send, schema, payload, headers)
10625
10626
10627async def _handle_schema_versions_get(
10628 send,
10629 schema: str,
10630 query: dict[str, str],
10631 headers: dict[str, str],
10632) -> None:
10633 gate_error = _admin_token_gate_error(
10634 headers,
10635 f"Schema versions require {ADMIN_TOKEN_ENV}.",
10636 )
10637 if gate_error is not None:
10638 status, message = gate_error
10639 await _send_json(send, {"status": "error", "error": message}, status=status)
10640 return
10641
10642 try:
10643 object_schemas.get_schema(schema, base_dir=_data_dir())
10644 limit = _query_int(query, "limit", default=10, minimum=1, maximum=100)
10645 versions = _schema_version_manager().get_history(schema, limit=limit)
10646 except object_schemas.InvalidSchemaNameError as exc:
10647 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10648 return
10649 except object_schemas.SchemaNotFoundError as exc:
10650 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
10651 return
10652 except object_schema_versions.InvalidSchemaNameError as exc:
10653 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10654 return
10655 except ValueError as exc:
10656 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10657 return
10658
10659 await _send_json(
10660 send,
10661 {
10662 "status": "ok",
10663 "collection": schema,
10664 "versions": versions,
10665 "count": len(versions),
10666 },
10667 )
10668
10669
10670async def _handle_schema_version_get(
10671 send,
10672 schema: str,
10673 query: dict[str, str],
10674 headers: dict[str, str],
10675) -> None:
10676 gate_error = _admin_token_gate_error(
10677 headers,
10678 f"Schema version detail requires {ADMIN_TOKEN_ENV}.",
10679 )
10680 if gate_error is not None:
10681 status, message = gate_error
10682 await _send_json(send, {"status": "error", "error": message}, status=status)
10683 return
10684
10685 try:
10686 version_id = _query_int(query, "version", minimum=1)
10687 version = _schema_version_manager().get_version(schema, version_id)
10688 except object_schema_versions.InvalidSchemaNameError as exc:
10689 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10690 return
10691 except ValueError as exc:
10692 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10693 return
10694
10695 if version is None:
10696 await _send_json(
10697 send,
10698 {"status": "error", "error": f"Version {version_id} not found for schema {schema}"},
10699 status=404,
10700 )
10701 return
10702
10703 await _send_json(
10704 send,
10705 {
10706 "status": "ok",
10707 "collection": schema,
10708 "version": _schema_version_payload(version),
10709 },
10710 )
10711
10712
10713async def _handle_schema_rollback_post(
10714 send,
10715 schema: str,
10716 payload: dict[str, Any],
10717 headers: dict[str, str],
10718) -> None:
10719 gate_error = _admin_token_gate_error(
10720 headers,
10721 f"Schema rollback requires {ADMIN_TOKEN_ENV}.",
10722 )
10723 if gate_error is not None:
10724 status, message = gate_error
10725 await _send_json(send, {"status": "error", "error": message}, status=status)
10726 return
10727
10728 try:
10729 version_id = _payload_int(payload, "version_id", minimum=1)
10730 author = _payload_text(payload, "author", "api")
10731 message = _payload_text(payload, "message", f"Rollback schema to version {version_id}")
10732 new_version_id = _schema_version_manager().rollback(
10733 schema=schema,
10734 to_version=version_id,
10735 author=author,
10736 message=message,
10737 )
10738 new_version = _schema_version_manager().get_version(schema, new_version_id)
10739 if new_version is None:
10740 raise object_schema_versions.SchemaVersionNotFoundError(
10741 f"Version {new_version_id} not found for schema {schema}"
10742 )
10743 schema_payload = json.loads(new_version["content"])
10744 saved_schema = object_schemas.replace_schema(schema, schema_payload, base_dir=_data_dir())
10745 except object_schemas.InvalidSchemaNameError as exc:
10746 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10747 return
10748 except object_schema_versions.InvalidSchemaNameError as exc:
10749 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10750 return
10751 except object_schema_versions.SchemaVersionNotFoundError as exc:
10752 await _send_json(send, {"status": "error", "error": str(exc)}, status=404)
10753 return
10754 except (json.JSONDecodeError, ValueError) as exc:
10755 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
10756 return
10757 except OSError as exc:
10758 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
10759 return
10760
10761 await _send_json(
10762 send,
10763 {
10764 "status": "ok",
10765 "message": f"Rolled back schema to version {version_id}",
10766 "version_id": version_id,
10767 "new_version_id": new_version_id,
10768 "collection": schema,
10769 "schema": saved_schema,
10770 },
10771 )
10772
10773
10774def _object_source_payload(source) -> dict[str, str]:
10775 return {
10776 "object_id": source.object_id,
10777 "path": source.relative_path.as_posix(),
10778 "owner": _object_owner(source.object_id),
10779 }
10780
10781
10782def _schema_version_payload(version: dict[str, Any]) -> dict[str, Any]:
10783 payload = dict(version)
10784 content = payload.get("content")
10785 if isinstance(content, str):
10786 try:
10787 payload["schema"] = json.loads(content)
10788 except json.JSONDecodeError:
10789 pass
10790 return payload
10791
10792
10793def _object_owner(object_id: str) -> str:
10794 parsed = parse_user_object_id(object_id)
10795 if parsed is None:
10796 return "system"
10797 user_id, _ = parsed
10798 return str(user_id)
10799
10800
10801def _object_collection(object_id: str) -> str | None:
10802 parsed = parse_user_object_id(object_id)
10803 if parsed is not None:
10804 _, name = parsed
10805 return name.split("_", 1)[0] if name else None
10806
10807 return object_id.split("_", 1)[0] if object_id else None
10808
10809
10810def _append_execution_log(result: object_execution.ObjectExecutionResult) -> None:
10811 if result.path is None:
10812 return
10813
10814 try:
10815 if result.ok:
10816 object_logs.append_object_log(
10817 result.object_id,
10818 "DEBUG",
10819 f"{result.method} completed successfully",
10820 base_dir=_data_dir(),
10821 correlation_id=result.correlation_id,
10822 method=result.method,
10823 status="success",
10824 duration_ms=result.duration_ms,
10825 )
10826 return
10827
10828 error_type = result.error.type if result.error is not None else None
10829 error = result.error.message if result.error is not None else None
10830 object_logs.append_object_log(
10831 result.object_id,
10832 "ERROR",
10833 f"{result.method} failed: {error}",
10834 base_dir=_data_dir(),
10835 correlation_id=result.correlation_id,
10836 method=result.method,
10837 status="error",
10838 duration_ms=result.duration_ms,
10839 error_type=error_type,
10840 error=error,
10841 )
10842 except Exception:
10843 # Logging is feedback for the dev loop; it should not change the object response.
10844 pass
10845
10846
10847def _append_file_log(
10848 object_id: str,
10849 *,
10850 operation: str,
10851 metadata: Mapping[str, Any],
10852 method: str,
10853) -> None:
10854 try:
10855 object_logs.append_object_log(
10856 object_id,
10857 "INFO",
10858 f"File {operation}: {metadata['name']}",
10859 base_dir=_data_dir(),
10860 method=method,
10861 status="success",
10862 file_name=metadata.get("name"),
10863 file_size=metadata.get("size"),
10864 file_operation=operation,
10865 )
10866 except Exception:
10867 # File logs are operator feedback; file writes should not fail because logging failed.
10868 pass
10869
10870
10871def _append_file_change_log(
10872 object_id: str,
10873 *,
10874 operation: str,
10875 metadata: Mapping[str, Any],
10876 method: str,
10877 actor: str,
10878 correlation_id: str | None,
10879) -> dict[str, Any] | None:
10880 action = {
10881 "created": "file_create",
10882 "updated": "file_update",
10883 "deleted": "file_delete",
10884 }.get(operation)
10885 if action is None:
10886 return None
10887
10888 try:
10889 return object_file_changes.append_file_change(
10890 object_id=object_id,
10891 action=action,
10892 file_name=str(metadata.get("name") or ""),
10893 file_size=int(metadata["size"]) if "size" in metadata else None,
10894 actor=actor,
10895 message=f"File {operation}: {metadata.get('name')}",
10896 correlation_id=correlation_id,
10897 details={
10898 "method": method,
10899 "modified": metadata.get("modified"),
10900 },
10901 base_dir=_data_dir(),
10902 )
10903 except Exception:
10904 # File-change entries are operator feedback; file writes already succeeded.
10905 return None
10906
10907
10908def _append_source_change_log(
10909 object_id: str,
10910 *,
10911 action: str,
10912 version_id: int,
10913 from_version_id: int | None = None,
10914 actor: str = "api",
10915 message: str = "",
10916 correlation_id: str | None = None,
10917 details: Mapping[str, Any] | None = None,
10918) -> None:
10919 fields: dict[str, Any] = {
10920 "action": action,
10921 "version_id": version_id,
10922 }
10923 if from_version_id is not None:
10924 fields["from_version_id"] = from_version_id
10925
10926 try:
10927 object_source_changes.append_source_change(
10928 object_id=object_id,
10929 action=action,
10930 version_id=version_id,
10931 from_version_id=from_version_id,
10932 actor=actor,
10933 message=message,
10934 correlation_id=correlation_id,
10935 details=details,
10936 base_dir=_data_dir(),
10937 )
10938 object_logs.append_object_log(
10939 object_id,
10940 "INFO",
10941 f"{action} version {version_id}",
10942 base_dir=_data_dir(),
10943 correlation_id=correlation_id or object_correlation.current_correlation_id(),
10944 **fields,
10945 )
10946 except Exception:
10947 # Source-change entries are operator feedback; source writes already succeeded.
10948 pass
10949
10950
10951def _object_count() -> int:
10952 return sum(1 for _ in iter_object_sources())
10953
10954
10955def _package_version() -> str:
10956 try:
10957 return importlib_metadata.version("dbbasic-object-server")
10958 except importlib_metadata.PackageNotFoundError:
10959 return "0.0.1"
10960
10961
10962def _station_id() -> str:
10963 return os.environ.get("DBBASIC_STATION_ID") or os.environ.get("STATION_ID") or "standalone"
10964
10965
10966def _rate_limit_identity(scope: dict[str, Any], headers: dict[str, str]) -> str:
10967 token = _authorization_token(headers)
10968 admin_token = os.environ.get(ADMIN_TOKEN_ENV, "")
10969 if token and admin_token and hmac.compare_digest(token, admin_token):
10970 return f"token:{_hash_identity(token)}"
10971
10972 return f"ip:{_client_ip(scope, headers)}"
10973
10974
10975def _hash_identity(value: str) -> str:
10976 return hashlib.sha256(value.encode("utf-8")).hexdigest()[:32]
10977
10978
10979def _client_ip(scope: dict[str, Any], headers: dict[str, str]) -> str:
10980 if _env_enabled(RATE_LIMIT_TRUST_PROXY_HEADERS_ENV):
10981 forwarded = headers.get("x-forwarded-for", "")
10982 if forwarded:
10983 return forwarded.split(",", 1)[0].strip()
10984
10985 real_ip = headers.get("x-real-ip", "")
10986 if real_ip:
10987 return real_ip.strip()
10988
10989 client = scope.get("client")
10990 if isinstance(client, (list, tuple)) and client:
10991 return str(client[0])
10992
10993 return "127.0.0.1"
10994
10995
10996def _storage_check() -> dict[str, str]:
10997 check_path = os.path.join(_data_dir(), ".health_check")
10998 try:
10999 os.makedirs(_data_dir(), exist_ok=True)
11000 with open(check_path, "w", encoding="utf-8") as handle:
11001 handle.write("ok")
11002 with open(check_path, encoding="utf-8") as handle:
11003 handle.read()
11004 os.unlink(check_path)
11005 except OSError as exc:
11006 return {
11007 "status": "error",
11008 "message": str(exc),
11009 }
11010
11011 return {"status": "ok"}
11012
11013
11014async def _handle_admin_ops(
11015 send,
11016 method: str,
11017 query: dict[str, str],
11018 headers: dict[str, str],
11019) -> None:
11020 if method != "GET":
11021 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
11022 return
11023
11024 gate_error = _admin_token_gate_error(
11025 headers,
11026 f"Ops events require {ADMIN_TOKEN_ENV}.",
11027 )
11028 if gate_error is not None:
11029 status, message = gate_error
11030 await _send_json(send, {"status": "error", "error": message}, status=status)
11031 return
11032
11033 try:
11034 events = object_ops_log.read_events(
11035 base_dir=_data_dir(),
11036 limit=_query_int(query, "limit", default=100, minimum=1, maximum=1000),
11037 kind=_optional_query_text(query, "kind"),
11038 event=_optional_query_text(query, "event"),
11039 identifier=_optional_query_text(query, "identifier"),
11040 )
11041 except ValueError as exc:
11042 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
11043 return
11044 except OSError as exc:
11045 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
11046 return
11047
11048 await _send_json(
11049 send,
11050 {
11051 "status": "ok",
11052 "events": events,
11053 "count": len(events),
11054 },
11055 )
11056
11057
11058BACKUP_SCHEDULE_ENV = "DBBASIC_BACKUP_SCHEDULE"
11059
11060
11061def _backup_schedule_payload() -> dict[str, Any]:
11062 """Automatic backups are a config option; report whether one is set.
11063
11064 Scheduled runs are driven by an external timer (systemd/cron) calling
11065 `object_backup.py create`; DBBASIC_BACKUP_SCHEDULE records the operator's
11066 intent so clients can show it. On-demand create/download always work.
11067 """
11068 schedule = os.environ.get(BACKUP_SCHEDULE_ENV, "").strip()
11069 return {"scheduled": bool(schedule), "schedule": schedule or None, "env": BACKUP_SCHEDULE_ENV}
11070
11071
11072async def _handle_admin_backups(
11073 send,
11074 method: str,
11075 headers: dict[str, str],
11076) -> None:
11077 """List runtime backups (GET) or create one on demand (POST). Admin only."""
11078 gate_error = _admin_token_gate_error(headers, f"Backups require {ADMIN_TOKEN_ENV}.")
11079 if gate_error is not None:
11080 status, message = gate_error
11081 await _send_json(send, {"status": "error", "error": message}, status=status)
11082 return
11083
11084 if method == "GET":
11085 try:
11086 backups = object_backup_index.list_backups(data_dir=_data_dir())
11087 except (OSError, ValueError) as exc:
11088 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
11089 return
11090 await _send_json(
11091 send,
11092 {
11093 "status": "ok",
11094 "backups": backups,
11095 "count": len(backups),
11096 "schedule": _backup_schedule_payload(),
11097 },
11098 )
11099 return
11100
11101 if method == "POST":
11102 try:
11103 backup = object_backup_index.create_backup(data_dir=_data_dir())
11104 except object_backup.BackupError as exc:
11105 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
11106 return
11107 except OSError as exc:
11108 await _send_json(
11109 send, {"status": "error", "error": f"Could not create backup: {exc}"}, status=500
11110 )
11111 return
11112 _append_ops_auth_event(event="backup_created", identifier=_record_change_actor(headers),
11113 label=str(backup.get("id")))
11114 await _send_json(send, {"status": "ok", "backup": backup}, status=201)
11115 return
11116
11117 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
11118
11119
11120async def _handle_admin_backup_download(
11121 send,
11122 method: str,
11123 backup_id: str,
11124 headers: dict[str, str],
11125) -> None:
11126 """Stream one backup archive. Admin only — it contains all runtime data."""
11127 if method != "GET":
11128 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
11129 return
11130
11131 gate_error = _admin_token_gate_error(headers, f"Backups require {ADMIN_TOKEN_ENV}.")
11132 if gate_error is not None:
11133 status, message = gate_error
11134 await _send_json(send, {"status": "error", "error": message}, status=status)
11135 return
11136
11137 try:
11138 path = object_backup_index.backup_path(backup_id, data_dir=_data_dir())
11139 except ValueError as exc:
11140 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
11141 return
11142 if not path.is_file():
11143 await _send_json(send, {"status": "error", "error": "Backup not found"}, status=404)
11144 return
11145
11146 try:
11147 content = path.read_bytes()
11148 except OSError as exc:
11149 await _send_json(send, {"status": "error", "error": str(exc)}, status=500)
11150 return
11151
11152 _append_ops_auth_event(event="backup_downloaded", identifier=_record_change_actor(headers),
11153 label=backup_id)
11154 await _send_bytes(
11155 send,
11156 content,
11157 content_type="application/gzip",
11158 extra_headers=[
11159 (b"content-disposition", f'attachment; filename="{backup_id}"'.encode("latin-1", "replace")),
11160 (b"x-content-type-options", b"nosniff"),
11161 ],
11162 )
11163
11164
11165async def _handle_admin_backup_preview(
11166 send,
11167 method: str,
11168 backup_id: str,
11169 query: dict[str, str],
11170 headers: dict[str, str],
11171) -> None:
11172 """Preview what restoring part of a backup would change. Read-only, admin only."""
11173 if method != "GET":
11174 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
11175 return
11176
11177 gate_error = _admin_token_gate_error(headers, f"Backups require {ADMIN_TOKEN_ENV}.")
11178 if gate_error is not None:
11179 status, message = gate_error
11180 await _send_json(send, {"status": "error", "error": message}, status=status)
11181 return
11182
11183 try:
11184 path = object_backup_index.backup_path(backup_id, data_dir=_data_dir())
11185 except ValueError as exc:
11186 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
11187 return
11188 if not path.is_file():
11189 await _send_json(send, {"status": "error", "error": "Backup not found"}, status=404)
11190 return
11191
11192 kind = _optional_query_text(query, "kind")
11193 if kind != "collection":
11194 await _send_json(
11195 send, {"status": "error", "error": "unsupported preview kind"}, status=400
11196 )
11197 return
11198
11199 name = _optional_query_text(query, "name")
11200 if not name:
11201 await _send_json(
11202 send, {"status": "error", "error": "Query parameter 'name' is required"}, status=400
11203 )
11204 return
11205
11206 try:
11207 preview = object_backup_index.preview_collection(backup_id, name, data_dir=_data_dir())
11208 except ValueError as exc:
11209 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
11210 return
11211
11212 await _send_json(send, {"status": "ok", "preview": preview})
11213
11214
11215async def _handle_admin_backup_record(
11216 send,
11217 method: str,
11218 backup_id: str,
11219 query: dict[str, str],
11220 headers: dict[str, str],
11221) -> None:
11222 """Pull one record's backup-vs-live status, without restoring. Admin only."""
11223 if method != "GET":
11224 await _send_json(send, {"status": "error", "error": "Method not allowed"}, status=405)
11225 return
11226
11227 gate_error = _admin_token_gate_error(headers, f"Backups require {ADMIN_TOKEN_ENV}.")
11228 if gate_error is not None:
11229 status, message = gate_error
11230 await _send_json(send, {"status": "error", "error": message}, status=status)
11231 return
11232
11233 try:
11234 path = object_backup_index.backup_path(backup_id, data_dir=_data_dir())
11235 except ValueError as exc:
11236 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
11237 return
11238 if not path.is_file():
11239 await _send_json(send, {"status": "error", "error": "Backup not found"}, status=404)
11240 return
11241
11242 collection = _optional_query_text(query, "collection")
11243 if not collection:
11244 await _send_json(
11245 send,
11246 {"status": "error", "error": "Query parameter 'collection' is required"},
11247 status=400,
11248 )
11249 return
11250
11251 record_id = _optional_query_text(query, "id")
11252 if not record_id:
11253 await _send_json(
11254 send, {"status": "error", "error": "Query parameter 'id' is required"}, status=400
11255 )
11256 return
11257
11258 try:
11259 record = object_backup_index.preview_record(
11260 backup_id, collection, record_id, data_dir=_data_dir()
11261 )
11262 except ValueError as exc:
11263 await _send_json(send, {"status": "error", "error": str(exc)}, status=400)
11264 return
11265
11266 await _send_json(send, {"status": "ok", "record": record})
11267
11268
11269def _append_ops_execution_error(
11270 object_id: str,
11271 method: str,
11272 result: object_execution.ObjectExecutionResult,
11273 headers: dict[str, str],
11274) -> None:
11275 try:
11276 subject = _permission_subject(headers)
11277 object_ops_log.append_event(
11278 object_ops_log.EXECUTION_ERROR,
11279 {
11280 "object_id": object_id,
11281 "method": method,
11282 "error_type": result.error.type if result.error is not None else None,
11283 "message": (result.error.message if result.error is not None else "")[:500],
11284 "user_id": subject.user_id,
11285 "correlation_id": object_correlation.current_correlation_id(),
11286 },
11287 base_dir=_data_dir(),
11288 )
11289 except (OSError, ValueError):
11290 pass
11291
11292
11293def _login_lockout_attempts() -> int:
11294 value = os.environ.get(LOGIN_LOCKOUT_ATTEMPTS_ENV, "")
11295 try:
11296 return int(value) if value.strip() else DEFAULT_LOGIN_LOCKOUT_ATTEMPTS
11297 except ValueError:
11298 return DEFAULT_LOGIN_LOCKOUT_ATTEMPTS
11299
11300
11301def _login_lockout_window_seconds() -> int:
11302 value = os.environ.get(LOGIN_LOCKOUT_WINDOW_SECONDS_ENV, "")
11303 try:
11304 return int(value) if value.strip() else DEFAULT_LOGIN_LOCKOUT_WINDOW_SECONDS
11305 except ValueError:
11306 return DEFAULT_LOGIN_LOCKOUT_WINDOW_SECONDS
11307
11308
11309def _login_locked(identifier: str) -> bool:
11310 """Return whether recent failures lock this identifier out of login.
11311
11312 Counts `login_failed` ops events for the identifier that are newer than
11313 the lockout window and newer than the identifier's last successful login.
11314 Locked attempts are recorded as `login_locked`, so an attacker cannot
11315 extend the lockout window by hammering a locked identifier.
11316 """
11317 attempts = _login_lockout_attempts()
11318 if attempts <= 0 or not identifier:
11319 return False
11320
11321 window = _login_lockout_window_seconds()
11322 cutoff = datetime.now(timezone.utc).timestamp() - window
11323 try:
11324 events = object_ops_log.read_events(
11325 base_dir=_data_dir(),
11326 kind=object_ops_log.AUTH,
11327 identifier=identifier,
11328 limit=max(attempts * 3, 20),
11329 )
11330 except (OSError, ValueError):
11331 return False
11332
11333 failures = 0
11334 for entry in events:
11335 try:
11336 timestamp = datetime.fromisoformat(
11337 str(entry.get("timestamp", "")).replace("Z", "+00:00")
11338 ).timestamp()
11339 except ValueError:
11340 continue
11341 if timestamp < cutoff:
11342 break
11343 event = entry.get("event")
11344 if event in ("login_succeeded", "password_reset"):
11345 break
11346 if event == "login_failed":
11347 failures += 1
11348 if failures >= attempts:
11349 return True
11350 return False
11351
11352
11353def _append_ops_auth_event(
11354 event: str,
11355 *,
11356 identifier: str | None = None,
11357 user_id: str | None = None,
11358 method: str | None = None,
11359 label: str | None = None,
11360) -> None:
11361 try:
11362 object_ops_log.append_event(
11363 object_ops_log.AUTH,
11364 {
11365 "event": event,
11366 "identifier": identifier,
11367 "user_id": user_id,
11368 "auth_method": method,
11369 "label": label,
11370 "correlation_id": object_correlation.current_correlation_id(),
11371 },
11372 base_dir=_data_dir(),
11373 )
11374 except (OSError, ValueError):
11375 pass
11376
11377
11378_METRICS_SNAPSHOT_LOCK = threading.Lock()
11379_LAST_METRICS_SNAPSHOT = 0.0
11380
11381
11382def _maybe_append_metrics_snapshot() -> None:
11383 """Persist one metrics history row per interval while traffic flows."""
11384 global _LAST_METRICS_SNAPSHOT
11385 interval = _metrics_snapshot_seconds()
11386 if interval <= 0:
11387 return
11388
11389 now = time.time()
11390 with _METRICS_SNAPSHOT_LOCK:
11391 if now - _LAST_METRICS_SNAPSHOT < interval:
11392 return
11393 _LAST_METRICS_SNAPSHOT = now
11394
11395 try:
11396 metrics = _metrics.snapshot()
11397 system = _system_snapshot()
11398 object_metrics_history.append_snapshot(
11399 {
11400 "uptime_seconds": metrics["uptime_seconds"],
11401 "requests": metrics["total_requests"],
11402 "errors": metrics["total_errors"],
11403 "rps": metrics["requests_per_second"],
11404 "error_rate": metrics["error_rate"],
11405 "p50_ms": metrics["response_time_ms"].get("p50"),
11406 "p95_ms": metrics["response_time_ms"].get("p95"),
11407 "cpu_percent": system.get("cpu_percent"),
11408 "memory_used_percent": (system.get("memory") or {}).get("used_percent"),
11409 "disk_used_percent": (system.get("disk") or {}).get("used_percent"),
11410 },
11411 base_dir=_data_dir(),
11412 )
11413 except (OSError, ValueError, KeyError):
11414 pass
11415
11416
11417def _metrics_snapshot_seconds() -> int:
11418 value = os.environ.get(METRICS_SNAPSHOT_SECONDS_ENV, "")
11419 try:
11420 return int(value) if value.strip() else DEFAULT_METRICS_SNAPSHOT_SECONDS
11421 except ValueError:
11422 return DEFAULT_METRICS_SNAPSHOT_SECONDS
11423
11424
11425def _system_snapshot() -> dict[str, Any]:
11426 snapshot: dict[str, Any] = {
11427 "cpu_count": os.cpu_count(),
11428 }
11429
11430 try:
11431 snapshot["load_average"] = [round(value, 3) for value in os.getloadavg()]
11432 except OSError:
11433 snapshot["load_average"] = None
11434
11435 memory = _linux_memory_snapshot()
11436 if memory is not None:
11437 snapshot["memory"] = memory
11438
11439 cpu_percent = _cpu_percent_snapshot()
11440 if cpu_percent is not None:
11441 snapshot["cpu_percent"] = cpu_percent
11442
11443 disk = _disk_snapshot()
11444 if disk is not None:
11445 snapshot["disk"] = disk
11446
11447 return snapshot
11448
11449
11450_CPU_TIMES_LOCK = threading.Lock()
11451_LAST_CPU_TIMES: tuple[int, int] | None = None
11452
11453
11454def _cpu_percent_snapshot() -> float | None:
11455 """CPU utilization since the previous metrics call, from /proc/stat deltas."""
11456 global _LAST_CPU_TIMES
11457 try:
11458 with open("/proc/stat", encoding="utf-8") as handle:
11459 first_line = handle.readline()
11460 except OSError:
11461 return None
11462
11463 parts = first_line.split()
11464 if not parts or parts[0] != "cpu":
11465 return None
11466 try:
11467 values = [int(part) for part in parts[1:]]
11468 except ValueError:
11469 return None
11470
11471 idle = values[3] + (values[4] if len(values) > 4 else 0)
11472 total = sum(values)
11473
11474 with _CPU_TIMES_LOCK:
11475 previous = _LAST_CPU_TIMES
11476 _LAST_CPU_TIMES = (idle, total)
11477
11478 if previous is None:
11479 return None
11480
11481 idle_delta = idle - previous[0]
11482 total_delta = total - previous[1]
11483 if total_delta <= 0:
11484 return None
11485 return round(max(0.0, min(100.0, (1 - idle_delta / total_delta) * 100)), 2)
11486
11487
11488def _disk_snapshot() -> dict[str, Any] | None:
11489 """Capacity of the filesystem holding the runtime data directory."""
11490 try:
11491 usage = shutil.disk_usage(_data_dir())
11492 except OSError:
11493 return None
11494 if usage.total <= 0:
11495 return None
11496 return {
11497 "total_gb": round(usage.total / 1024**3, 2),
11498 "used_gb": round(usage.used / 1024**3, 2),
11499 "used_percent": round(usage.used / usage.total * 100, 2),
11500 }
11501
11502
11503def _linux_memory_snapshot() -> dict[str, Any] | None:
11504 try:
11505 with open("/proc/meminfo", encoding="utf-8") as handle:
11506 lines = handle.readlines()
11507 except OSError:
11508 return None
11509
11510 values_kb: dict[str, int] = {}
11511 for line in lines:
11512 key, _, value = line.partition(":")
11513 parts = value.strip().split()
11514 if not parts:
11515 continue
11516 try:
11517 values_kb[key] = int(parts[0])
11518 except ValueError:
11519 continue
11520
11521 total_kb = values_kb.get("MemTotal")
11522 available_kb = values_kb.get("MemAvailable")
11523 if not total_kb or available_kb is None:
11524 return None
11525
11526 used_kb = max(total_kb - available_kb, 0)
11527 return {
11528 "total_mb": round(total_kb / 1024, 2),
11529 "available_mb": round(available_kb / 1024, 2),
11530 "used_mb": round(used_kb / 1024, 2),
11531 "used_percent": round(used_kb / total_kb * 100, 2),
11532 }
11533
11534
11535def _thread_count() -> int:
11536 task_dir = f"/proc/{os.getpid()}/task"
11537 try:
11538 return len(os.listdir(task_dir))
11539 except OSError:
11540 return threading.active_count()
11541
11542
11543def _response_time_summary(values: list[float]) -> dict[str, float]:
11544 if not values:
11545 return {
11546 "avg": 0,
11547 "p50": 0,
11548 "p95": 0,
11549 "p99": 0,
11550 }
11551
11552 return {
11553 "avg": round(sum(values) / len(values), 2),
11554 "p50": round(_percentile(values, 50), 2),
11555 "p95": round(_percentile(values, 95), 2),
11556 "p99": round(_percentile(values, 99), 2),
11557 }
11558
11559
11560def _percentile(values: list[float], percentile: int) -> float:
11561 sorted_values = sorted(values)
11562 index = int((len(sorted_values) - 1) * percentile / 100)
11563 return sorted_values[index]
11564
11565
11566def _human_duration(seconds: float) -> str:
11567 remaining = int(seconds)
11568 days, remaining = divmod(remaining, 86400)
11569 hours, remaining = divmod(remaining, 3600)
11570 minutes, seconds = divmod(remaining, 60)
11571
11572 if days:
11573 return f"{days}d {hours}h {minutes}m"
11574 if hours:
11575 return f"{hours}h {minutes}m"
11576 if minutes:
11577 return f"{minutes}m {seconds}s"
11578 return f"{seconds}s"
11579
11580
11581def _utc_timestamp() -> str:
11582 return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
11583
11584
11585def _parse_query(query_string: bytes | str) -> dict[str, str]:
11586 if isinstance(query_string, bytes):
11587 query_string = query_string.decode("utf-8")
11588 return dict(urllib.parse.parse_qsl(query_string))
11589
11590
11591def _parse_headers(headers: list[tuple[bytes, bytes]]) -> dict[str, str]:
11592 parsed = {}
11593 for name, value in headers:
11594 parsed[name.decode("latin-1").lower()] = value.decode("latin-1")
11595 return parsed
11596
11597
11598def _parse_json_body(body: bytes) -> dict[str, Any]:
11599 if not body.strip():
11600 return {}
11601
11602 try:
11603 payload = json.loads(body.decode("utf-8"))
11604 except (UnicodeDecodeError, json.JSONDecodeError) as exc:
11605 raise ValueError("Invalid JSON body") from exc
11606
11607 if not isinstance(payload, dict):
11608 raise ValueError("JSON body must be an object")
11609
11610 return payload
11611
11612
11613def _identity_session_login_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
11614 allowed_fields = {"user_id", "label", "ttl_seconds"}
11615 unsupported = sorted(set(payload) - allowed_fields)
11616 if unsupported:
11617 fields = ", ".join(unsupported)
11618 raise ValueError(f"Unsupported session login field(s): {fields}")
11619
11620 return {key: payload[key] for key in allowed_fields if key in payload}
11621
11622
11623def _record_payload_from_body(body: bytes, *, require_id: bool = False) -> dict[str, str]:
11624 payload = _parse_json_body(body)
11625 if not payload:
11626 raise ValueError("Record payload must not be empty")
11627 return object_records.normalize_record_payload(payload, require_id=require_id)
11628
11629
11630def _parse_post_payload(
11631 body: bytes,
11632 query: dict[str, str],
11633 headers: dict[str, str] | None = None,
11634) -> dict[str, Any]:
11635 if not body.strip():
11636 return dict(query)
11637
11638 if headers is not None and _is_form_content_type(headers):
11639 payload: dict[str, Any] = _form_fields_payload(body)
11640 for key, value in query.items():
11641 payload.setdefault(key, value)
11642 return payload
11643
11644 if headers is not None and _is_multipart_content_type(headers):
11645 payload = object_multipart.parse_multipart(body, headers.get("content-type", ""))
11646 for key, value in query.items():
11647 payload.setdefault(key, value)
11648 return payload
11649
11650 try:
11651 payload = json.loads(body.decode("utf-8"))
11652 except (UnicodeDecodeError, json.JSONDecodeError):
11653 return {**query, "body": body}
11654
11655 if not isinstance(payload, dict):
11656 raise ValueError("JSON body must be an object")
11657
11658 for key, value in query.items():
11659 payload.setdefault(key, value)
11660
11661 return payload
11662
11663
11664def _is_form_content_type(headers: dict[str, str]) -> bool:
11665 content_type = headers.get("content-type", "").split(";")[0].strip().lower()
11666 return content_type == "application/x-www-form-urlencoded"
11667
11668
11669def _is_multipart_content_type(headers: dict[str, str]) -> bool:
11670 return object_multipart.is_multipart_content_type(headers.get("content-type", ""))
11671
11672
11673def _form_fields_payload(body: bytes) -> dict[str, str]:
11674 try:
11675 pairs = urllib.parse.parse_qsl(body.decode("utf-8"), keep_blank_values=True)
11676 except (UnicodeDecodeError, ValueError) as exc:
11677 raise ValueError("Form body must be valid UTF-8 form encoding") from exc
11678 return {name: value for name, value in pairs}
11679
11680
11681def _admin_execute_method(payload: dict[str, Any]) -> str:
11682 value = payload.get("method", "GET")
11683 if not isinstance(value, str) or not value.strip():
11684 raise ValueError("Request JSON field 'method' must be one of GET, POST, PUT, DELETE")
11685
11686 method = value.strip().upper()
11687 if method not in {"GET", "POST", "PUT", "DELETE"}:
11688 raise ValueError("Request JSON field 'method' must be one of GET, POST, PUT, DELETE")
11689 return method
11690
11691
11692def _admin_execute_payload(payload: dict[str, Any]) -> dict[str, Any]:
11693 value = payload.get("payload", {})
11694 if not isinstance(value, dict):
11695 raise ValueError("Request JSON field 'payload' must be an object")
11696 return value
11697
11698
11699def _optional_payload_bool(payload: dict[str, Any], key: str) -> bool | None:
11700 if key not in payload:
11701 return None
11702 value = payload[key]
11703 if isinstance(value, bool):
11704 return value
11705 raise ValueError(f"Request JSON field '{key}' must be a boolean")
11706
11707
11708def _payload_text(payload: dict[str, Any], key: str, default: str) -> str:
11709 value = payload.get(key, default)
11710 if not isinstance(value, str) or not value.strip():
11711 return default
11712 return value
11713
11714
11715def _required_payload_text(payload: dict[str, Any], key: str) -> str:
11716 value = payload.get(key)
11717 if not isinstance(value, str) or not value.strip():
11718 raise ValueError(f"Request JSON field '{key}' must be a non-empty string")
11719 return value
11720
11721
11722def _created_object_id(payload: dict[str, Any], headers: dict[str, str]) -> str:
11723 object_id = _optional_payload_text(payload, "object_id")
11724 if object_id is not None:
11725 if not validate_object_id(object_id):
11726 raise ValueError(f"Invalid object ID: {object_id}")
11727 return object_id
11728
11729 name = _required_payload_text(payload, "name")
11730 owner_user_id = _created_object_owner_user_id(payload, headers)
11731 if owner_user_id is not None:
11732 object_id = f"u_{owner_user_id}_{name}"
11733 if parse_user_object_id(object_id) is None:
11734 raise ValueError(
11735 "Request JSON field 'name' must start with a letter and contain only "
11736 "letters, numbers, and underscores for user-scoped objects"
11737 )
11738 return object_id
11739
11740 if not validate_object_id(name):
11741 raise ValueError(f"Invalid object ID: {name}")
11742 return name
11743
11744
11745def _created_object_owner_user_id(
11746 payload: dict[str, Any],
11747 headers: dict[str, str],
11748) -> str | None:
11749 if "owner_user_id" in payload:
11750 value = payload["owner_user_id"]
11751 if isinstance(value, int):
11752 owner_user_id = str(value)
11753 elif isinstance(value, str):
11754 owner_user_id = value.strip()
11755 else:
11756 raise ValueError("Request JSON field 'owner_user_id' must be a positive integer")
11757 if not owner_user_id.isdigit() or int(owner_user_id) <= 0:
11758 raise ValueError("Request JSON field 'owner_user_id' must be a positive integer")
11759 return owner_user_id
11760
11761 session = _current_identity_session(headers)
11762 if session is not None and session.user_id.isdigit():
11763 return session.user_id
11764 return None
11765
11766
11767def _source_actor_from_headers(headers: dict[str, str]) -> str:
11768 session = _current_identity_session(headers)
11769 if session is not None:
11770 return session.user_id
11771 return "api"
11772
11773
11774def _file_write_payload(body: bytes) -> tuple[str, bytes]:
11775 payload = _parse_json_body(body)
11776 filename = _optional_payload_text(payload, "name")
11777 if filename is None:
11778 filename = _optional_payload_text(payload, "filename")
11779 if filename is None:
11780 raise ValueError("Request JSON field 'name' is required")
11781
11782 content_base64 = payload.get("content_base64")
11783 if not isinstance(content_base64, str):
11784 raise ValueError("Request JSON field 'content_base64' must be a base64 string")
11785
11786 try:
11787 content = base64.b64decode(content_base64, validate=True)
11788 except (binascii.Error, ValueError) as exc:
11789 raise ValueError("Request JSON field 'content_base64' must be valid base64") from exc
11790
11791 max_bytes = _max_object_file_bytes()
11792 if len(content) > max_bytes:
11793 raise object_files.ObjectFileTooLargeError(
11794 f"Object file exceeds max size: {len(content)} bytes > {max_bytes} bytes"
11795 )
11796 return filename, content
11797
11798
11799def _file_delete_filename(query: dict[str, str], body: bytes) -> str:
11800 filename = _optional_query_text(query, "file")
11801 if filename is not None:
11802 return filename
11803
11804 payload = _parse_json_body(body)
11805 filename = _optional_payload_text(payload, "name")
11806 if filename is None:
11807 filename = _optional_payload_text(payload, "filename")
11808 if filename is None:
11809 raise ValueError("Query parameter 'file' or JSON field 'name' is required")
11810 return filename
11811
11812
11813def _optional_payload_text(payload: dict[str, Any], key: str) -> str | None:
11814 if key not in payload or payload[key] is None:
11815 return None
11816 value = payload[key]
11817 if not isinstance(value, str) or not value.strip():
11818 raise ValueError(f"Request JSON field '{key}' must be a non-empty string")
11819 return value
11820
11821
11822def _policy_payload_from_request(payload: dict[str, Any]) -> dict[str, Any]:
11823 policy_payload = payload.get("policy", payload)
11824 if not isinstance(policy_payload, dict):
11825 raise ValueError("Request JSON field 'policy' must be an object")
11826 return policy_payload
11827
11828
11829def _schema_payload_from_request(payload: dict[str, Any]) -> dict[str, Any]:
11830 schema_payload = payload.get("schema", payload)
11831 if not isinstance(schema_payload, dict):
11832 raise ValueError("Request JSON field 'schema' must be an object")
11833 return schema_payload
11834
11835
11836def _policy_for_check_request(payload: dict[str, Any]) -> object_permissions.PermissionPolicy:
11837 if "policy" in payload:
11838 policy_payload = _policy_payload_from_request(payload)
11839 return object_permissions.policy_from_dict(policy_payload)
11840
11841 return object_permission_store.load_policy(_data_dir())
11842
11843
11844def _optional_record_payload(payload: dict[str, Any]) -> dict[str, Any] | None:
11845 if "record" not in payload or payload["record"] is None:
11846 return None
11847 record = payload["record"]
11848 if not isinstance(record, dict):
11849 raise ValueError("Request JSON field 'record' must be an object")
11850 return record
11851
11852
11853def _optional_datetime_payload(payload: dict[str, Any], key: str) -> datetime | None:
11854 if key not in payload or payload[key] is None:
11855 return None
11856 value = payload[key]
11857 if not isinstance(value, str) or not value.strip():
11858 raise ValueError(f"Request JSON field '{key}' must be an ISO timestamp")
11859
11860 try:
11861 parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
11862 except ValueError as exc:
11863 raise ValueError(f"Request JSON field '{key}' must be an ISO timestamp") from exc
11864
11865 if parsed.tzinfo is None:
11866 return parsed.replace(tzinfo=timezone.utc)
11867 return parsed.astimezone(timezone.utc)
11868
11869
11870def _payload_int(payload: dict[str, Any], key: str, *, minimum: int | None = None) -> int:
11871 if key not in payload:
11872 raise ValueError(f"Request JSON field '{key}' is required")
11873
11874 value = payload[key]
11875 if isinstance(value, bool):
11876 raise ValueError(f"Request JSON field '{key}' must be an integer")
11877
11878 try:
11879 parsed = int(value)
11880 except (TypeError, ValueError) as exc:
11881 raise ValueError(f"Request JSON field '{key}' must be an integer") from exc
11882
11883 if minimum is not None and parsed < minimum:
11884 raise ValueError(f"Request JSON field '{key}' must be at least {minimum}")
11885
11886 return parsed
11887
11888
11889def _query_int(
11890 query: dict[str, str],
11891 key: str,
11892 *,
11893 default: int | None = None,
11894 minimum: int | None = None,
11895 maximum: int | None = None,
11896) -> int:
11897 value = query.get(key)
11898 if value is None:
11899 if default is None:
11900 raise ValueError(f"Query parameter '{key}' is required")
11901 parsed = default
11902 else:
11903 try:
11904 parsed = int(value)
11905 except ValueError as exc:
11906 raise ValueError(f"Query parameter '{key}' must be an integer") from exc
11907
11908 if minimum is not None and parsed < minimum:
11909 raise ValueError(f"Query parameter '{key}' must be at least {minimum}")
11910
11911 if maximum is not None and parsed > maximum:
11912 raise ValueError(f"Query parameter '{key}' must be at most {maximum}")
11913
11914 return parsed
11915
11916
11917def _optional_query_text(query: dict[str, str], key: str) -> str | None:
11918 if key not in query:
11919 return None
11920 value = query[key].strip()
11921 return value or None
11922
11923
11924def _required_query_text(query: dict[str, str], key: str) -> str:
11925 value = _optional_query_text(query, key)
11926 if value is None:
11927 raise ValueError(f"Query parameter '{key}' is required")
11928 return value
11929
11930
11931def _optional_query_bool(query: dict[str, str], key: str) -> bool | None:
11932 if key not in query:
11933 return None
11934
11935 value = query[key].strip().lower()
11936 if value in TRUE_VALUES:
11937 return True
11938 if value in {"0", "false", "no", "off"}:
11939 return False
11940 raise ValueError(f"Query parameter '{key}' must be a boolean")
11941
11942
11943def _ensure_object_source_exists(object_id: str) -> None:
11944 object_source.get_object_source(object_id)
11945
11946
11947def _source_write_gate_error(headers: dict[str, str]) -> tuple[int, str] | None:
11948 if not _env_enabled(SOURCE_WRITES_ENV):
11949 return (
11950 403,
11951 f"Source writes are disabled. Set {SOURCE_WRITES_ENV}=true and {ADMIN_TOKEN_ENV}.",
11952 )
11953
11954 return _admin_token_gate_error(headers, f"Source writes require {ADMIN_TOKEN_ENV}.")
11955
11956
11957def _file_write_gate_error(headers: dict[str, str]) -> tuple[int, str] | None:
11958 if not _env_enabled(FILE_WRITES_ENV):
11959 return (
11960 403,
11961 f"File writes are disabled. Set {FILE_WRITES_ENV}=true and {ADMIN_TOKEN_ENV}.",
11962 )
11963
11964 return _admin_token_gate_error(headers, f"File writes require {ADMIN_TOKEN_ENV}.")
11965
11966
11967def _permissions_gate_error(headers: dict[str, str]) -> tuple[int, str] | None:
11968 return _admin_token_gate_error(headers, f"Permissions API requires {ADMIN_TOKEN_ENV}.")
11969
11970
11971async def _send_permission_denied_if_needed(
11972 send,
11973 headers: dict[str, str],
11974 action: str,
11975 *,
11976 object_id: str,
11977 method: str,
11978) -> bool:
11979 if not _permission_checks_enabled():
11980 return False
11981
11982 subject = _permission_subject(headers)
11983 enforced = _permission_enforcement_enabled()
11984 collection = _object_collection(object_id)
11985
11986 try:
11987 policy = object_permission_store.load_policy(_data_dir())
11988 decision = object_permissions.check_permission(
11989 subject,
11990 action,
11991 policy=policy,
11992 collection=collection,
11993 object_id=object_id,
11994 )
11995 except ValueError as exc:
11996 _append_permission_audit_entry(
11997 action=action,
11998 object_id=object_id,
11999 collection=collection,
12000 method=method,
12001 subject=subject,
12002 enforced=enforced,
12003 error=f"Permission policy is invalid: {exc}",
12004 )
12005 if enforced:
12006 await _send_json(
12007 send,
12008 {"status": "error", "error": f"Permission policy is invalid: {exc}"},
12009 status=500,
12010 )
12011 return True
12012 return False
12013
12014 _append_permission_audit_entry(
12015 action=action,
12016 object_id=object_id,
12017 collection=collection,
12018 method=method,
12019 subject=subject,
12020 enforced=enforced,
12021 decision=decision,
12022 )
12023
12024 if not enforced or decision.allowed:
12025 return False
12026
12027 await _send_json(
12028 send,
12029 {
12030 "status": "error",
12031 "error": decision.reason,
12032 "code": decision.code,
12033 },
12034 status=decision.http_status,
12035 )
12036 return True
12037
12038
12039async def _collection_permission_check(
12040 send,
12041 headers: dict[str, str],
12042 action: str,
12043 *,
12044 collection: str,
12045 method: str,
12046 record: dict[str, Any] | None = None,
12047) -> dict[str, Any] | None:
12048 subject = _permission_subject(headers)
12049 enforced = _permission_enforcement_enabled()
12050
12051 try:
12052 policy = object_permission_store.load_policy(_data_dir())
12053 decision = object_permissions.check_permission(
12054 subject,
12055 action,
12056 policy=policy,
12057 collection=collection,
12058 record=record,
12059 )
12060 except ValueError as exc:
12061 _append_permission_audit_entry(
12062 action=action,
12063 object_id=None,
12064 collection=collection,
12065 method=method,
12066 subject=subject,
12067 enforced=enforced,
12068 error=f"Permission policy is invalid: {exc}",
12069 )
12070 if enforced:
12071 await _send_json(
12072 send,
12073 {"status": "error", "error": f"Permission policy is invalid: {exc}"},
12074 status=500,
12075 )
12076 return None
12077 return {
12078 "subject": subject,
12079 "policy": object_permissions.PermissionPolicy(access_mode="public"),
12080 "decision": object_permissions.PermissionDecision.deny(str(exc)),
12081 "enforced": enforced,
12082 }
12083
12084 _append_permission_audit_entry(
12085 action=action,
12086 object_id=None,
12087 collection=collection,
12088 method=method,
12089 subject=subject,
12090 enforced=enforced,
12091 decision=decision,
12092 )
12093
12094 if enforced and not decision.allowed:
12095 await _send_json(
12096 send,
12097 {
12098 "status": "error",
12099 "error": decision.reason,
12100 "code": decision.code,
12101 },
12102 status=decision.http_status,
12103 )
12104 return None
12105
12106 return {
12107 "subject": subject,
12108 "policy": policy,
12109 "decision": decision,
12110 "enforced": enforced,
12111 }
12112
12113
12114class FilterParamError(ValueError):
12115 """One 58 field-filter query param failed validation.
12116
12117 Covers every case 58's Degradation section calls out as a 400: an
12118 unknown field, a non-filterable (hidden) field, an unknown operator,
12119 an oversize `in` list, or a value that fails schema type validation.
12120 Carries the offending param name so the 400 response can point at it
12121 rather than making the caller guess which of several filter params
12122 was the problem.
12123 """
12124
12125 def __init__(self, param: str, message: str):
12126 super().__init__(message)
12127 self.param = param
12128
12129
12130def _split_filter_param(raw_key: str) -> tuple[str, str]:
12131 """Split one query param name into (field, op).
12132
12133 58's Encoding: `field=value` is an implicit `eq`; `field.op=value` is
12134 the dotted-suffix form (`status.in=open,assigned`,
12135 `created_at.gte=2026-07-01`). Schema field names never contain a dot
12136 (object_schemas._FIELD_NAME_RE), so splitting on the LAST dot is
12137 unambiguous.
12138 """
12139 if "." in raw_key:
12140 field_name, _, op = raw_key.rpartition(".")
12141 return field_name, op.strip().lower()
12142 return raw_key, "eq"
12143
12144
12145def _schema_field_defs(collection: str) -> dict[str, dict[str, Any]]:
12146 """Return {field_name: field_def} for a collection's declared schema.
12147
12148 Empty for a schemaless/derived collection (no manual schema file) --
12149 callers treat that the same way every other schema-optional check in
12150 this codebase does: permissive, since there is no declared field list
12151 to validate a filter's field name or hidden-ness against.
12152 """
12153 try:
12154 schema = object_schemas.get_schema(collection, base_dir=_data_dir())
12155 except (object_schemas.InvalidSchemaNameError, object_schemas.SchemaNotFoundError):
12156 return {}
12157 fields = schema.get("fields") if isinstance(schema, dict) else None
12158 if not isinstance(fields, list):
12159 return {}
12160 return {
12161 field["name"]: field
12162 for field in fields
12163 if isinstance(field, dict) and isinstance(field.get("name"), str)
12164 }
12165
12166
12167def _always_filterable(_name: str) -> bool:
12168 return True
12169
12170
12171def _filterable_field_predicate(
12172 collection: str,
12173 *,
12174 subject: object_permissions.PermissionSubject,
12175 policy: object_permissions.PermissionPolicy,
12176 decision: object_permissions.PermissionDecision,
12177) -> Callable[[str], bool]:
12178 """Return a predicate: may `subject` use field `name` in a 58 filter?
12179
12180 58's Permissions Posture: filterable fields = readable fields. A
12181 field this subject can't read is not filterable either, closing the
12182 inference channel where filtering a hidden field would probe its
12183 value via which already-readable rows come back. A field is unreadable
12184 here for either of two independent reasons, both checked:
12185
12186 - the matched row-permission rule scopes reads to an explicit
12187 `fields` allow-list, or denies specific fields via `denied_fields`
12188 (`decision.fields`/`decision.denied_fields`, from the same READ
12189 decision `_filter_records_for_permission` uses for row/field
12190 redaction -- this is the general, record-independent shape of that
12191 decision, from `_collection_permission_check`);
12192 - the schema marks the field `hidden` for this subject
12193 (`object_field_permissions.field_access`, the same check
12194 `redact_record` applies per record on the way out).
12195
12196 Admins bypass both, mirroring `check_permission`'s own admin
12197 short-circuit (an admin's decision already carries no row_filter/
12198 fields/denied_fields, and admins see every field here too).
12199 """
12200 if object_permissions.subject_has_admin_role(subject, policy):
12201 return _always_filterable
12202
12203 denied = set(decision.denied_fields)
12204 allowed = set(decision.fields) if decision.fields is not None else None
12205
12206 for name, field in _schema_field_defs(collection).items():
12207 access = object_field_permissions.field_access(
12208 field, subject=subject, policy=policy, record=None
12209 )
12210 if access == object_field_permissions.HIDDEN:
12211 denied.add(name)
12212
12213 def is_filterable(name: str) -> bool:
12214 if name in denied:
12215 return False
12216 if allowed is not None and name not in allowed:
12217 return False
12218 return True
12219
12220 return is_filterable
12221
12222
12223def _parse_collection_record_filters(
12224 query: dict[str, str],
12225 *,
12226 collection: str,
12227 is_filterable: Callable[[str], bool],
12228) -> dict[str, list[dict[str, Any]]]:
12229 """Parse a collection-records GET query string into a normalized 58
12230 field filter.
12231
12232 Returns {field: [condition, ...]} -- a LIST of conditions per field
12233 (each `object_permissions.filter_condition`-shaped) so a range
12234 (`created_at.gte=X&created_at.lte=Y`, two different query params that
12235 both name `created_at`) ANDs both conditions instead of the second
12236 silently overwriting the first. Raises FilterParamError -- caught by
12237 the caller and turned into a structured 400 -- on any of 58's
12238 Degradation cases: unknown field, non-filterable field, unknown
12239 operator, an oversize `in` list, or a value that fails schema type
12240 validation. Reserved params (FILTER_RESERVED_PARAMS) are skipped, not
12241 treated as filters.
12242 """
12243 field_defs = _schema_field_defs(collection)
12244 normalized: dict[str, list[dict[str, Any]]] = {}
12245
12246 for raw_key, raw_value in query.items():
12247 if raw_key in FILTER_RESERVED_PARAMS:
12248 continue
12249
12250 field_name, op = _split_filter_param(raw_key)
12251 if op not in object_permissions.FILTER_OPERATORS:
12252 raise FilterParamError(
12253 raw_key, f"Unknown filter operator '{op}' on field '{field_name}'"
12254 )
12255 if field_defs and field_name not in field_defs:
12256 raise FilterParamError(raw_key, f"Unknown filter field '{field_name}'")
12257 if not is_filterable(field_name):
12258 raise FilterParamError(
12259 raw_key, f"Field '{field_name}' is not filterable for this subject"
12260 )
12261
12262 field_def = field_defs.get(field_name)
12263 try:
12264 if op == "in":
12265 raw_values = [item.strip() for item in raw_value.split(",")]
12266 if not raw_values or any(item == "" for item in raw_values):
12267 raise FilterParamError(
12268 raw_key,
12269 "Filter operator 'in' requires a non-empty comma-separated list",
12270 )
12271 if len(raw_values) > FILTER_IN_MAX_VALUES:
12272 raise FilterParamError(
12273 raw_key,
12274 f"Filter operator 'in' supports at most {FILTER_IN_MAX_VALUES} values",
12275 )
12276 value: Any = tuple(
12277 object_records.normalize_filter_value(field_def, op, item)
12278 for item in raw_values
12279 )
12280 else:
12281 value = object_records.normalize_filter_value(field_def, op, raw_value)
12282 except object_records.InvalidRecordPayloadError as exc:
12283 raise FilterParamError(raw_key, str(exc)) from exc
12284
12285 normalized.setdefault(field_name, []).append(
12286 object_permissions.filter_condition(op, value)
12287 )
12288
12289 return normalized
12290
12291
12292def _filter_records_for_permission(
12293 records: list[dict[str, str]],
12294 *,
12295 collection: str,
12296 subject: object_permissions.PermissionSubject,
12297 policy: object_permissions.PermissionPolicy,
12298 redact: bool = True,
12299) -> list[dict[str, str]]:
12300 """Return the records `subject` may read from `collection` -- the
12301 permission ROW filter, applied first and unconditionally (58's
12302 Permissions Posture) ahead of any field filter a caller adds on top.
12303
12304 `redact=False` skips the per-record field-redaction step (schema
12305 hidden-field stripping plus the matched rule's fields/denied_fields)
12306 and returns the row-permitted records with every field still present.
12307 A 58 field filter MUST be applied to that unredacted form -- see
12308 _handle_collection_records_get -- so a filter an admin is allowed to
12309 use on an otherwise-hidden field (_filterable_field_predicate) can
12310 still see the value to match against; call
12311 _redact_records_for_permission once filtering is done to get the same
12312 caller-facing shape a plain read (redact=True, the default) already
12313 produces in one pass.
12314 """
12315 allowed_records: list[dict[str, str]] = []
12316 for record in records:
12317 decision = object_permissions.check_permission(
12318 subject,
12319 object_permissions.READ,
12320 policy=policy,
12321 collection=collection,
12322 record=record,
12323 )
12324 if not decision.allowed:
12325 continue
12326 if redact:
12327 allowed_records.append(
12328 _apply_record_field_policy(
12329 record,
12330 decision,
12331 collection=collection,
12332 subject=subject,
12333 policy=policy,
12334 )
12335 )
12336 else:
12337 allowed_records.append(dict(record))
12338 return allowed_records
12339
12340
12341def _redact_records_for_permission(
12342 records: list[dict[str, str]],
12343 *,
12344 collection: str,
12345 subject: object_permissions.PermissionSubject,
12346 policy: object_permissions.PermissionPolicy,
12347) -> list[dict[str, str]]:
12348 """Apply field redaction to an already row-permitted record list.
12349
12350 The other half of what _filter_records_for_permission's default
12351 (redact=True) does in one pass, split out so a 58 field filter can run
12352 BETWEEN row-permission filtering and redaction -- see there.
12353 """
12354 redacted: list[dict[str, str]] = []
12355 for record in records:
12356 decision = object_permissions.check_permission(
12357 subject,
12358 object_permissions.READ,
12359 policy=policy,
12360 collection=collection,
12361 record=record,
12362 )
12363 redacted.append(
12364 _apply_record_field_policy(
12365 record,
12366 decision,
12367 collection=collection,
12368 subject=subject,
12369 policy=policy,
12370 )
12371 )
12372 return redacted
12373
12374
12375def _apply_record_field_policy(
12376 record: dict[str, str],
12377 decision: object_permissions.PermissionDecision,
12378 *,
12379 collection: str | None = None,
12380 subject: object_permissions.PermissionSubject | None = None,
12381 policy: object_permissions.PermissionPolicy | None = None,
12382) -> dict[str, str]:
12383 filtered = dict(record)
12384 if decision.fields is not None:
12385 filtered = {key: value for key, value in filtered.items() if key in decision.fields}
12386 for field in decision.denied_fields:
12387 filtered.pop(field, None)
12388 if collection is not None and subject is not None and policy is not None:
12389 filtered = object_field_permissions.redact_record(
12390 collection,
12391 filtered,
12392 subject=subject,
12393 policy=policy,
12394 base_dir=_data_dir(),
12395 )
12396 return filtered
12397
12398
12399def _schema_denied_write_fields(
12400 collection: str,
12401 submitted_fields,
12402 *,
12403 subject: object_permissions.PermissionSubject,
12404 policy: object_permissions.PermissionPolicy,
12405 record: dict[str, Any],
12406) -> list[str]:
12407 return object_field_permissions.denied_write_fields(
12408 collection,
12409 submitted_fields,
12410 subject=subject,
12411 policy=policy,
12412 record=record,
12413 base_dir=_data_dir(),
12414 )
12415
12416
12417def _field_write_denied_message(fields: list[str]) -> str:
12418 if len(fields) == 1:
12419 return f"Record field '{fields[0]}' is not editable for this subject"
12420 return f"Record fields are not editable for this subject: {', '.join(fields)}"
12421
12422
12423def _permission_checks_enabled() -> bool:
12424 return _permission_enforcement_requested() or _permission_audit_enabled()
12425
12426
12427def _permission_enforcement_enabled() -> bool:
12428 if not _permission_enforcement_requested():
12429 return False
12430 if _permission_unready_enforcement_allowed():
12431 return True
12432 try:
12433 readiness = object_permission_status.enforcement_readiness(
12434 base_dir=_data_dir(),
12435 permissions=_permission_readiness_inputs(),
12436 )
12437 except (OSError, ValueError):
12438 return False
12439 return bool(readiness.get("can_enable_enforcement"))
12440
12441
12442def _permission_audit_enabled() -> bool:
12443 return _env_enabled(PERMISSION_AUDIT_ENV) or _permission_enforcement_requested()
12444
12445
12446def _permission_enforcement_requested() -> bool:
12447 return _env_enabled(PERMISSION_ENFORCEMENT_ENV)
12448
12449
12450def _permission_unready_enforcement_allowed() -> bool:
12451 return _env_enabled(PERMISSION_UNREADY_ENFORCEMENT_ENV)
12452
12453
12454def _permission_enforcement_blocked() -> bool:
12455 return _permission_enforcement_requested() and not _permission_enforcement_enabled()
12456
12457
12458def _permission_subject(headers: dict[str, str]) -> object_permissions.PermissionSubject:
12459 return _permission_identity(headers)[0]
12460
12461
12462def _subject_for_user(user_id: str) -> object_permissions.PermissionSubject:
12463 """Build a permission subject for a user id (used by the API-key auth path,
12464 which resolves only a user id and must reconstruct the same authority a
12465 session would). Reads the user's roles/account, then resolves project grants
12466 exactly like the session path."""
12467 try:
12468 user = object_identity.get_user(user_id, base_dir=_data_dir())
12469 except (object_identity.UserNotFoundError, OSError, ValueError):
12470 user = None
12471 if user is None:
12472 subject = object_permissions.PermissionSubject(user_id=user_id)
12473 else:
12474 subject = object_permissions.PermissionSubject(
12475 user_id=user_id,
12476 account_id=user.get("account_id"),
12477 roles=tuple(user.get("roles") or ()),
12478 subscriptions=tuple(user.get("subscriptions") or ()),
12479 )
12480 return _with_shared_records(_with_accessible_projects(subject))
12481
12482
12483def _permission_identity(
12484 headers: dict[str, str],
12485) -> tuple[object_permissions.PermissionSubject, str]:
12486 token = _authorization_token(headers)
12487 admin_token = os.environ.get(ADMIN_TOKEN_ENV, "")
12488 if token and admin_token and hmac.compare_digest(token, admin_token):
12489 return object_permissions.PermissionSubject(user_id="admin", roles=("admin",)), "admin_token"
12490
12491 # A durable per-user API key (Authorization: Bearer dbk_...). Prefix-routed
12492 # so a session token never reaches this path and vice versa. Resolves to the
12493 # owning user's full authority (roles/account/project grants).
12494 if token and token.startswith(object_api_keys.TOKEN_PREFIX):
12495 api_user_id = object_api_keys.resolve_api_key(token, base_dir=_data_dir())
12496 if api_user_id:
12497 return _subject_for_user(api_user_id), "api_key"
12498
12499 cookie_token = None if token else _session_cookie_token(headers)
12500 session_token = token or cookie_token
12501 if session_token:
12502 try:
12503 session = object_identity.resolve_session_token(session_token, base_dir=_data_dir())
12504 except (OSError, ValueError):
12505 session = None
12506 if session is not None:
12507 subject = _with_shared_records(_with_accessible_projects(session.subject()))
12508 return subject, "session_cookie" if cookie_token else "session_token"
12509
12510 if not _env_enabled(PERMISSION_TRUST_HEADERS_ENV):
12511 return object_permissions.PermissionSubject.anonymous(), "anonymous"
12512
12513 user_id = _optional_header_text(headers, "x-dbbasic-user-id")
12514 account_id = _optional_header_text(headers, "x-dbbasic-account-id")
12515 subject = _with_shared_records(
12516 _with_accessible_projects(
12517 object_permissions.PermissionSubject(
12518 user_id=user_id,
12519 account_id=account_id,
12520 roles=_csv_header(headers.get("x-dbbasic-roles", "")),
12521 subscriptions=_csv_header(headers.get("x-dbbasic-subscriptions", "")),
12522 )
12523 )
12524 )
12525 method = "trusted_headers" if _trusted_identity_headers_present(headers) else "anonymous"
12526 return subject, method
12527
12528
12529PROJECT_ACCESS_COLLECTION = "project_access"
12530PROJECTS_COLLECTION = "projects"
12531
12532
12533def _with_accessible_projects(
12534 subject: object_permissions.PermissionSubject,
12535) -> object_permissions.PermissionSubject:
12536 """Resolve the subject's project grants and ownership before checks run.
12537
12538 Grants live in the plain ``project_access`` records collection
12539 (project_id, user_id, permission), so sharing is data: browseable,
12540 audited, and versioned like every other record. Rules opt in with the
12541 ``$accessible_projects`` row-filter value; ``$owned_projects``
12542 resolves from the projects collection's owner_id, which is what lets
12543 "owners may share their own projects" stay a plain row filter.
12544 ``$writable_projects`` narrows accessible grants to rows whose
12545 ``permission`` is ``"write"``, for rules and transition guards that
12546 need more than read-only membership.
12547 """
12548 if subject.user_id is None:
12549 return subject
12550
12551 access_rows = [
12552 record
12553 for record in _read_records_or_empty(PROJECT_ACCESS_COLLECTION)
12554 if record.get("user_id") == subject.user_id and record.get("project_id")
12555 ]
12556 project_ids = [record["project_id"] for record in access_rows]
12557 writable_project_ids = [
12558 record["project_id"] for record in access_rows if record.get("permission") == "write"
12559 ]
12560 owned_project_ids = [
12561 record["id"]
12562 for record in _read_records_or_empty(PROJECTS_COLLECTION)
12563 if record.get("owner_id") == subject.user_id and record.get("id")
12564 ]
12565 if not project_ids and not owned_project_ids:
12566 return subject
12567 return subject.with_projects(
12568 dict.fromkeys(project_ids),
12569 dict.fromkeys(owned_project_ids),
12570 dict.fromkeys(writable_project_ids),
12571 )
12572
12573
12574RECORD_SHARES_COLLECTION = "record_shares"
12575
12576
12577def _with_shared_records(
12578 subject: object_permissions.PermissionSubject,
12579) -> object_permissions.PermissionSubject:
12580 """Resolve the subject's per-collection record shares before checks run.
12581
12582 The generic sibling of ``_with_accessible_projects``: grants live in the
12583 plain ``record_shares`` collection (collection, record_id, user_id,
12584 permission), written only by the owner-checked /api/share endpoint. A rule
12585 opts a collection into sharing with a ``{"id": "$shared_records"}`` row
12586 filter (or ``$writable_shared_records`` for write). Keyed by collection so
12587 the collection-aware resolver returns only this collection's shared ids.
12588 """
12589 if subject.user_id is None:
12590 return subject
12591 shared: dict[str, list[str]] = {}
12592 writable: dict[str, list[str]] = {}
12593 for row in _read_records_or_empty(RECORD_SHARES_COLLECTION):
12594 if row.get("user_id") != subject.user_id:
12595 continue
12596 coll, rid = row.get("collection"), row.get("record_id")
12597 if not coll or not rid:
12598 continue
12599 shared.setdefault(coll, []).append(rid)
12600 if row.get("permission") == "write":
12601 writable.setdefault(coll, []).append(rid)
12602 if not shared:
12603 return subject
12604 return subject.with_shares(
12605 {k: list(dict.fromkeys(v)) for k, v in shared.items()},
12606 {k: list(dict.fromkeys(v)) for k, v in writable.items()},
12607 )
12608
12609
12610def _read_records_or_empty(collection: str) -> list[dict[str, str]]:
12611 try:
12612 return object_records.read_collection_records(collection, base_dir=_data_dir())
12613 except (
12614 object_collections.CollectionNotFoundError,
12615 object_collections.InvalidCollectionNameError,
12616 OSError,
12617 ValueError,
12618 ):
12619 return []
12620
12621
12622def _signed_in_user_id(headers: dict[str, str]) -> str | None:
12623 """The user a request acts as when it is signed in as a person: a session
12624 (cookie or token) or one of their API keys. None for the admin token (an
12625 operator, who may set owner_id deliberately), trusted headers, or nobody."""
12626 session = _current_identity_session(headers)
12627 if session is not None and session.user_id:
12628 return session.user_id
12629 token = _authorization_token(headers)
12630 if token and token.startswith(object_api_keys.TOKEN_PREFIX):
12631 return object_api_keys.resolve_api_key(token, base_dir=_data_dir()) or None
12632 return None
12633
12634
12635def _current_identity_session(headers: dict[str, str]) -> object_identity.IdentitySession | None:
12636 token = _authorization_token(headers) or _session_cookie_token(headers)
12637 if not token:
12638 return None
12639
12640 admin_token = os.environ.get(ADMIN_TOKEN_ENV, "")
12641 if admin_token and hmac.compare_digest(token, admin_token):
12642 return None
12643
12644 try:
12645 return object_identity.resolve_session_token(token, base_dir=_data_dir())
12646 except (OSError, ValueError):
12647 return None
12648
12649
12650def _parse_cookie_header(cookie_header: str) -> dict[str, str]:
12651 """Split a `cookie:` request header into name -> value.
12652
12653 First occurrence wins, matching the single-cookie lookup this replaced:
12654 a duplicated name is either a browser sending both a host-scoped and a
12655 domain-scoped cookie or somebody trying to shadow one, and taking the
12656 first is the stable, non-surprising reading in either case.
12657 """
12658 cookies: dict[str, str] = {}
12659 for part in (cookie_header or "").split(";"):
12660 name, _, value = part.strip().partition("=")
12661 if name and value:
12662 cookies.setdefault(name, value)
12663 return cookies
12664
12665
12666def _session_cookie_token(headers: dict[str, str]) -> str | None:
12667 return _parse_cookie_header(headers.get("cookie", "")).get(SESSION_COOKIE_NAME) or None
12668
12669
12670def _object_visible_cookies(headers: dict[str, str]) -> dict[str, str]:
12671 """The cookies a routed object may see: everything EXCEPT the session
12672 and the analytics visitor token.
12673
12674 A page object has a real need for its own cookies -- a basket token, a
12675 display preference -- and no way to read them otherwise. It has no need
12676 at all for `dbbasic_session`, which is not data but an authentication
12677 CAPABILITY: anyone holding that string is the signed-in user. Handing it
12678 to every object a package installs would make each public page a place
12679 where a stranger's session can be read and posted somewhere else, and
12680 the shopper who lost their account would have done nothing but visit a
12681 shop. Same reasoning that keeps `cookie` and `authorization` out of
12682 _WEBHOOK_HEADER_SAFELIST: app state travels, the credential does not.
12683
12684 `dbbasic_visitor` is withheld for a different reason and just as
12685 firmly. It is not a credential -- it is an opaque analytics thread,
12686 and it is worth nothing to the object that would read it, because the
12687 server already stamps it into `page_views` itself. What an object
12688 COULD do with it is the problem: write it next to a `user_id` in some
12689 collection of its own, which is the join docs/analytics.md's cookie
12690 rule 4 forbids, performed by a package the operator installed rather
12691 than by anything in this repo. A token nobody but the capture hook
12692 can see cannot be joined to anything.
12693 """
12694 cookies = _parse_cookie_header(headers.get("cookie", ""))
12695 cookies.pop(SESSION_COOKIE_NAME, None)
12696 cookies.pop(object_analytics.VISITOR_COOKIE_NAME, None)
12697 return cookies
12698
12699
12700def _cookie_request_origin_allowed(headers: dict[str, str]) -> bool:
12701 source = headers.get("origin", "").strip() or headers.get("referer", "").strip()
12702 if not source:
12703 return True
12704 host = headers.get("host", "").strip().lower()
12705 if not host:
12706 return False
12707 return (urllib.parse.urlsplit(source).netloc or "").lower() == host
12708
12709
12710def _trusted_identity_headers_present(headers: dict[str, str]) -> bool:
12711 return any(
12712 _optional_header_text(headers, name) is not None
12713 for name in (
12714 "x-dbbasic-user-id",
12715 "x-dbbasic-account-id",
12716 "x-dbbasic-roles",
12717 "x-dbbasic-subscriptions",
12718 )
12719 )
12720
12721
12722def _optional_header_text(headers: dict[str, str], name: str) -> str | None:
12723 value = headers.get(name, "").strip()
12724 return value or None
12725
12726
12727def _csv_header(value: str) -> tuple[str, ...]:
12728 values = []
12729 seen = set()
12730 for item in value.split(","):
12731 normalized = item.strip()
12732 if normalized and normalized not in seen:
12733 values.append(normalized)
12734 seen.add(normalized)
12735 return tuple(values)
12736
12737
12738def _append_permission_audit_entry(
12739 *,
12740 action: str,
12741 object_id: str | None,
12742 collection: str | None,
12743 method: str,
12744 subject: object_permissions.PermissionSubject,
12745 enforced: bool,
12746 decision: object_permissions.PermissionDecision | None = None,
12747 error: str | None = None,
12748) -> None:
12749 if not _permission_audit_enabled():
12750 return
12751
12752 entry: dict[str, Any] = {
12753 "timestamp": _utc_timestamp(),
12754 "correlation_id": object_correlation.current_correlation_id(),
12755 "method": method,
12756 "object_id": object_id,
12757 "collection": collection,
12758 "action": action,
12759 "subject": _permission_subject_payload(subject),
12760 "enforced": enforced,
12761 "enforcement_requested": _permission_enforcement_requested(),
12762 }
12763 if entry["enforcement_requested"] and not enforced:
12764 entry["enforcement_blocked"] = True
12765 if decision is not None:
12766 entry["decision"] = object_permissions.decision_to_dict(decision)
12767 if error is not None:
12768 entry["error"] = error
12769
12770 try:
12771 object_permission_audit.append_permission_audit(entry, base_dir=_data_dir())
12772 except (OSError, ValueError):
12773 pass
12774
12775
12776def _permission_subject_payload(subject: object_permissions.PermissionSubject) -> dict[str, Any]:
12777 payload: dict[str, Any] = {
12778 "user_id": subject.user_id,
12779 "account_id": subject.account_id,
12780 "roles": list(subject.roles),
12781 "subscriptions": list(subject.subscriptions),
12782 "authenticated": subject.is_authenticated,
12783 }
12784 if subject.project_ids:
12785 payload["project_ids"] = list(subject.project_ids)
12786 if subject.owned_project_ids:
12787 payload["owned_project_ids"] = list(subject.owned_project_ids)
12788 if subject.writable_project_ids:
12789 payload["writable_project_ids"] = list(subject.writable_project_ids)
12790 return payload
12791
12792
12793def _record_change_actor(headers: dict[str, str]) -> str:
12794 subject = _permission_subject(headers)
12795 if subject.user_id:
12796 return subject.user_id
12797 if subject.account_id:
12798 return f"account:{subject.account_id}"
12799 if subject.roles:
12800 return ",".join(subject.roles)
12801 return "api"
12802
12803
12804def _record_change_for_publish(collection: str, record_id: str) -> dict[str, Any] | None:
12805 """Re-read the change object_records just durably appended, for publish.
12806
12807 object_records.create/update/delete_collection_record already emit the
12808 attributed change record as part of the write itself (universal
12809 attribution -- see object_record_changes). The HTTP handlers still want
12810 the real persisted change_id/timestamp/changed_fields for realtime and
12811 event-bus fan-out, so this fetches the newest entry back rather than
12812 emitting a second, separate change. Best-effort: a read failure here
12813 only costs the realtime/event-bus publish, not the write or its log
12814 entry, which are already safely on disk.
12815 """
12816 try:
12817 payload = object_record_changes.list_record_changes(
12818 collection, record_id=record_id, limit=1, base_dir=_data_dir()
12819 )
12820 except (OSError, ValueError):
12821 return None
12822 changes = payload.get("changes") or []
12823 return changes[0] if changes else None
12824
12825
12826def _publish_record_change_event(
12827 change: dict[str, Any], record: dict[str, Any] | None = None
12828) -> dict[str, Any] | None:
12829 action = str(change.get("action", ""))
12830 event_type = RECORD_EVENT_TYPES.get(action)
12831 if event_type is None:
12832 return None
12833
12834 collection = str(change.get("collection") or "")
12835 record_id = str(change.get("record_id") or "")
12836
12837 # Live push overlay (independent of the durable log's on/off flag).
12838 _realtime_publish(collection, record_id, action, record)
12839
12840 # HANDLES-declared event handler objects (Phase 5a; see
12841 # docs/event-hooks-decisions.md). Post-commit, best-effort, gated off by
12842 # default: fully guarded internally so it can never raise into the
12843 # write path.
12844 _dispatch_event_handlers(collection, record_id, action, record)
12845
12846 if not _record_events_enabled():
12847 return None
12848
12849 payload = {
12850 "change_id": change.get("change_id"),
12851 "collection": change.get("collection"),
12852 "record_id": change.get("record_id"),
12853 "action": change.get("action"),
12854 "actor": change.get("actor"),
12855 "timestamp": change.get("timestamp"),
12856 "changed_fields": change.get("changed_fields", []),
12857 }
12858
12859 try:
12860 return object_events.publish_event(
12861 event_type,
12862 payload=payload,
12863 source="record_changes",
12864 actor=str(change.get("actor") or "api"),
12865 base_dir=_data_dir(),
12866 keep_count=_event_keep_count(),
12867 keep_seconds=_event_keep_seconds(),
12868 )
12869 except (OSError, ValueError):
12870 return None
12871
12872
12873def _dispatch_event_handlers(
12874 collection: str, record_id: str, action: str, record: dict[str, Any] | None
12875) -> None:
12876 """Fire HANDLES-declared handler objects for a committed record write.
12877
12878 Post-commit, best-effort, system-objects-only (Phase 5a; see
12879 docs/event-hooks-decisions.md). One bad handler can never affect the
12880 write or any other handler: every failure mode here is caught and
12881 logged, never raised. Dispatch is synchronous in-process for v1; async
12882 dispatch is a future optimization.
12883 """
12884 try:
12885 if not object_handlers.handlers_enabled():
12886 return
12887
12888 event = object_handlers.event_name(collection, action)
12889 if event is None:
12890 return
12891
12892 if object_handlers.current_depth() >= object_handlers.MAX_DISPATCH_DEPTH:
12893 try:
12894 object_logs.append_object_log(
12895 "object_handlers",
12896 "WARNING",
12897 f"Event dispatch depth limit reached for {event}; skipping handlers",
12898 base_dir=_data_dir(),
12899 )
12900 except Exception:
12901 pass
12902 return
12903
12904 handler_ids = object_handlers.get_handlers(event, get_object_roots())
12905 if not handler_ids:
12906 return
12907
12908 # Signal-shaped payload, same posture as /ws: no full record body by
12909 # default. A handler that needs the record fetches it via the
12910 # record API using collection/record_id.
12911 event_payload = {
12912 "event": event,
12913 "collection": collection,
12914 "record_id": record_id,
12915 "action": action,
12916 }
12917
12918 for handler_id in handler_ids:
12919 try:
12920 with object_handlers.dispatch_guard():
12921 request = object_execution.ObjectExecutionRequest(
12922 object_id=handler_id,
12923 method="EVENT",
12924 payload=event_payload,
12925 correlation_id=object_correlation.current_correlation_id(),
12926 )
12927 result = object_execution.execute_object(_runtime, request)
12928 _append_execution_log(result)
12929 if not result.ok:
12930 _append_ops_execution_error(handler_id, "EVENT", result, {})
12931 except Exception:
12932 # One bad handler must never affect the write or its peers.
12933 continue
12934 except Exception:
12935 return
12936
12937
12938def _record_events_enabled() -> bool:
12939 value = os.environ.get(RECORD_EVENTS_ENV)
12940 if value is None:
12941 return True
12942 return value.strip().lower() in TRUE_VALUES
12943
12944
12945def _filtering_enabled() -> bool:
12946 value = os.environ.get(FILTERING_ENABLED_ENV)
12947 if value is None:
12948 return True
12949 return value.strip().lower() in TRUE_VALUES
12950
12951
12952def _concurrency_enabled() -> bool:
12953 """63: whether the If-Match/expected_rev precondition is enforced.
12954 Default on; off means the precondition is ignored (never a 409) and
12955 writes are last-write-wins, per the spec's Degradation section.
12956 """
12957 value = os.environ.get(CONCURRENCY_ENABLED_ENV)
12958 if value is None:
12959 return True
12960 return value.strip().lower() in TRUE_VALUES
12961
12962
12963_FILTERING_DISABLED_LOGGED = False
12964
12965
12966def _note_filtering_disabled_once() -> None:
12967 """Log once (not per-request) that filter params are being ignored
12968 because FILTERING_ENABLED_ENV is off -- 58's Degradation section asks
12969 for this so an operator who flipped the flag can find out why filters
12970 stopped narrowing results, without a log line on every list request.
12971 """
12972 global _FILTERING_DISABLED_LOGGED
12973 if _FILTERING_DISABLED_LOGGED:
12974 return
12975 _FILTERING_DISABLED_LOGGED = True
12976 print(
12977 f"[dbbasic] Filtering is disabled ({FILTERING_ENABLED_ENV}=false); "
12978 f"field-filter query params are being ignored.",
12979 file=sys.stderr,
12980 )
12981
12982
12983def _event_keep_count() -> int | None:
12984 value = _env_int(EVENT_KEEP_COUNT_ENV, object_events.DEFAULT_EVENT_KEEP_COUNT)
12985 if value <= 0:
12986 return None
12987 return min(value, object_events.MAX_EVENT_KEEP_COUNT)
12988
12989
12990def _event_keep_seconds() -> int | None:
12991 value = _env_int(EVENT_KEEP_SECONDS_ENV, object_events.DEFAULT_EVENT_KEEP_SECONDS)
12992 if value <= 0:
12993 return None
12994 return value
12995
12996
12997def _event_retention_query_int(
12998 query: dict[str, str],
12999 key: str,
13000 *,
13001 default: int | None,
13002 maximum: int | None = None,
13003) -> int | None:
13004 if key not in query:
13005 return default
13006 value = _query_int(query, key, default=0, minimum=0, maximum=maximum)
13007 return value or None
13008
13009
13010def _admin_token_gate_error(
13011 headers: dict[str, str],
13012 missing_token_message: str,
13013) -> tuple[int, str] | None:
13014 admin_token = os.environ.get(ADMIN_TOKEN_ENV, "")
13015 session_admin_gates = _env_enabled(SESSION_ADMIN_GATES_ENV)
13016 if not admin_token and not session_admin_gates:
13017 return (403, missing_token_message)
13018
13019 request_token = _authorization_token(headers)
13020 if request_token is None:
13021 # Browser pages authenticate with the session cookie. Only the
13022 # session-admin path accepts it; the raw admin token never does.
13023 if session_admin_gates:
13024 cookie_token = _session_cookie_token(headers)
13025 if cookie_token is not None and _admin_session_authorized(cookie_token):
13026 return None
13027 return (401, "Unauthorized")
13028
13029 if admin_token and hmac.compare_digest(request_token, admin_token):
13030 return None
13031
13032 if session_admin_gates and _admin_session_authorized(request_token):
13033 return None
13034
13035 return (401, "Unauthorized")
13036
13037
13038def _admin_session_authorized(token: str) -> bool:
13039 try:
13040 session = object_identity.resolve_session_token(token, base_dir=_data_dir())
13041 except (OSError, ValueError):
13042 return False
13043 if session is None:
13044 return False
13045
13046 try:
13047 policy = object_permission_store.load_policy(_data_dir())
13048 except ValueError:
13049 policy = object_permissions.PermissionPolicy()
13050
13051 return object_permissions.subject_has_admin_role(session.subject(), policy)
13052
13053
13054def _session_login_gate_error(headers: dict[str, str]) -> tuple[int, str] | None:
13055 if not _env_enabled(SESSION_LOGIN_ENV):
13056 return (403, f"Session login is disabled. Set {SESSION_LOGIN_ENV}=true.")
13057
13058 login_token = os.environ.get(SESSION_LOGIN_TOKEN_ENV, "")
13059 if not login_token:
13060 return (403, f"Session login token is not configured. Set {SESSION_LOGIN_TOKEN_ENV}.")
13061
13062 request_token = _authorization_token(headers)
13063 if request_token is None or not hmac.compare_digest(request_token, login_token):
13064 return (401, "Unauthorized")
13065
13066 return None
13067
13068
13069def _is_sensitive_get(query: dict[str, str]) -> bool:
13070 if "version" in query:
13071 return True
13072 if "file" in query:
13073 return True
13074
13075 return any(query.get(flag) == "true" for flag in SENSITIVE_GET_FLAGS)
13076
13077
13078def _authorization_token(headers: dict[str, str]) -> str | None:
13079 authorization = headers.get("authorization", "")
13080 scheme, _, token = authorization.partition(" ")
13081 if scheme.lower() not in {"token", "bearer"} or not token:
13082 return None
13083 return token
13084
13085
13086def _env_enabled(name: str) -> bool:
13087 return os.environ.get(name, "").strip().lower() in TRUE_VALUES
13088
13089
13090def _version_manager() -> object_versions.VersionManager:
13091 return object_versions.VersionManager(_data_dir())
13092
13093
13094def _schema_version_manager() -> object_schema_versions.SchemaVersionManager:
13095 return object_schema_versions.SchemaVersionManager(_data_dir())
13096
13097
13098def _data_dir() -> str:
13099 return os.environ.get(DATA_DIR_ENV, object_versions.DEFAULT_DATA_DIR)
13100
13101
13102def _packages_dir() -> str:
13103 return os.environ.get(PACKAGES_DIR_ENV, object_packages.PACKAGES_DIR)
13104
13105
13106def _private_packages_dir() -> str:
13107 # Default to a SIBLING of the active packages dir, not a fixed cwd-relative
13108 # path: this way overriding DBBASIC_PACKAGES_DIR (e.g. a hermetic test)
13109 # isolates the private overlay too, while a normal deploy (packages/ +
13110 # packages-private/ side by side) still finds it.
13111 explicit = os.environ.get(PRIVATE_PACKAGES_DIR_ENV)
13112 if explicit:
13113 return explicit
13114 return str(Path(_packages_dir()).parent / DEFAULT_PRIVATE_PACKAGES_DIR)
13115
13116
13117def _package_roots() -> list[str]:
13118 """Package source roots, highest precedence first. The private overlay
13119 (closed-source packages, gitignored -- see packages-private/README.md)
13120 is searched ahead of the open-core `packages/` dir, so a private package
13121 shadows an open one that shares its id. The private root is included only
13122 when it actually exists, so an open-only checkout behaves exactly as
13123 before."""
13124 roots: list[str] = []
13125 private = _private_packages_dir()
13126 if private and Path(private).is_dir():
13127 roots.append(private)
13128 roots.append(_packages_dir())
13129 return roots
13130
13131
13132def _root_for_package(package_id: str) -> str:
13133 """The root a specific package id resolves from (private overlay wins).
13134 Falls back to the open packages dir when neither root has it, so the
13135 caller still gets the normal PackageNotFoundError from downstream."""
13136 for root in _package_roots():
13137 if (Path(root) / package_id / object_packages.MANIFEST_FILE).is_file():
13138 return root
13139 return _packages_dir()
13140
13141
13142def _list_all_packages() -> list[dict[str, Any]]:
13143 """Package summaries merged across every root, private overlay first so a
13144 private package shadows an open one with the same id."""
13145 seen: dict[str, dict[str, Any]] = {}
13146 for root in _package_roots():
13147 for package in object_packages.list_packages(root=root):
13148 seen.setdefault(str(package["id"]), package)
13149 return list(seen.values())
13150
13151
13152def _primary_objects_dir() -> str:
13153 return str(get_object_roots()[0])
13154
13155
13156def _max_concurrent_requests() -> int:
13157 return _env_int(MAX_CONCURRENT_REQUESTS_ENV, DEFAULT_MAX_CONCURRENT_REQUESTS)
13158
13159
13160def _max_concurrent_executions() -> int:
13161 return _env_int(MAX_CONCURRENT_EXECUTIONS_ENV, DEFAULT_MAX_CONCURRENT_EXECUTIONS)
13162
13163
13164def _max_request_bytes() -> int:
13165 max_bytes = _env_int(MAX_REQUEST_BYTES_ENV, DEFAULT_MAX_REQUEST_BYTES)
13166 if max_bytes < 0:
13167 return DEFAULT_MAX_REQUEST_BYTES
13168 return max_bytes
13169
13170
13171def _max_object_file_bytes() -> int:
13172 max_bytes = _env_int(MAX_OBJECT_FILE_BYTES_ENV, DEFAULT_MAX_OBJECT_FILE_BYTES)
13173 if max_bytes < 0:
13174 return DEFAULT_MAX_OBJECT_FILE_BYTES
13175 return max_bytes
13176
13177
13178def _rate_limit_requests() -> int:
13179 requests = _env_int(RATE_LIMIT_REQUESTS_ENV, DEFAULT_RATE_LIMIT_REQUESTS)
13180 if requests < 0:
13181 return DEFAULT_RATE_LIMIT_REQUESTS
13182 return requests
13183
13184
13185def _rate_limit_window_seconds() -> int:
13186 seconds = _env_int(RATE_LIMIT_WINDOW_SECONDS_ENV, DEFAULT_RATE_LIMIT_WINDOW_SECONDS)
13187 if seconds <= 0:
13188 return DEFAULT_RATE_LIMIT_WINDOW_SECONDS
13189 return seconds
13190
13191
13192def _object_timeout_seconds() -> float:
13193 seconds = _env_float(OBJECT_TIMEOUT_SECONDS_ENV, DEFAULT_OBJECT_TIMEOUT_SECONDS)
13194 if seconds < 0:
13195 return DEFAULT_OBJECT_TIMEOUT_SECONDS
13196 return seconds
13197
13198
13199def _object_runs_in_process(object_id: str) -> bool:
13200 return object_id in _trusted_in_process_object_ids()
13201
13202
13203def _trusted_in_process_object_ids() -> frozenset[str]:
13204 value = os.environ.get(TRUSTED_IN_PROCESS_OBJECTS_ENV, "")
13205 return frozenset(part.strip() for part in value.split(",") if part.strip())
13206
13207
13208def _worker_pool_size() -> int:
13209 size = _env_int(object_worker_pool.WORKER_POOL_SIZE_ENV, 0)
13210 return size if size > 0 else 0
13211
13212
13213async def _get_worker_pool() -> object_worker_pool.WorkerPool | None:
13214 """Return the shared warm-worker pool, lazily creating/resizing it.
13215
13216 Disabled (size <= 0) is the default: returns None and the caller falls
13217 back to the existing spawn-per-request path. Reads the size fresh on
13218 every call so tests (and, in principle, an operator) can flip the
13219 feature by env var without a process restart; a pool already running at
13220 a different size is shut down and replaced.
13221 """
13222 global _worker_pool, _worker_pool_size_used
13223
13224 size = _worker_pool_size()
13225 if size <= 0:
13226 if _worker_pool is not None:
13227 async with _worker_pool_lock:
13228 stale = _worker_pool
13229 _worker_pool = None
13230 _worker_pool_size_used = 0
13231 if stale is not None:
13232 await stale.shutdown()
13233 return None
13234
13235 async with _worker_pool_lock:
13236 if _worker_pool is None or _worker_pool_size_used != size:
13237 stale = _worker_pool
13238 _worker_pool = object_worker_pool.WorkerPool(size=size)
13239 _worker_pool_size_used = size
13240 else:
13241 stale = None
13242 pool = _worker_pool
13243
13244 if stale is not None:
13245 await stale.shutdown()
13246 return pool
13247
13248
13249async def _shutdown_worker_pool() -> None:
13250 global _worker_pool, _worker_pool_size_used
13251
13252 async with _worker_pool_lock:
13253 pool = _worker_pool
13254 _worker_pool = None
13255 _worker_pool_size_used = 0
13256
13257 if pool is not None:
13258 await pool.shutdown()
13259
13260
13261def _rate_limit_dir() -> str:
13262 return os.path.join(_data_dir(), "ratelimit")
13263
13264
13265def _env_int(name: str, default: int) -> int:
13266 value = os.environ.get(name, "").strip()
13267 if not value:
13268 return default
13269
13270 try:
13271 return int(value)
13272 except ValueError:
13273 return default
13274
13275
13276def _env_float(name: str, default: float) -> float:
13277 value = os.environ.get(name, "").strip()
13278 if not value:
13279 return default
13280
13281 try:
13282 return float(value)
13283 except ValueError:
13284 return default
13285
13286
13287def _content_length(headers: dict[str, str]) -> int | None:
13288 value = headers.get("content-length")
13289 if value is None:
13290 return None
13291
13292 try:
13293 length = int(value)
13294 except ValueError:
13295 return None
13296
13297 if length < 0:
13298 return None
13299
13300 return length
13301
13302
13303async def _read_body(receive, *, headers: dict[str, str], max_bytes: int | None = None) -> bytes:
13304 if max_bytes is None:
13305 max_bytes = _max_request_bytes()
13306 content_length = _content_length(headers)
13307 if content_length is not None and content_length > max_bytes:
13308 raise RequestBodyTooLargeError(max_bytes=max_bytes, actual_bytes=content_length)
13309
13310 body_parts = []
13311 body_size = 0
13312 while True:
13313 message = await receive()
13314 if message["type"] == "http.disconnect":
13315 return b"".join(body_parts)
13316 if message["type"] != "http.request":
13317 continue
13318
13319 chunk = message.get("body", b"")
13320 body_size += len(chunk)
13321 if body_size > max_bytes:
13322 raise RequestBodyTooLargeError(max_bytes=max_bytes, actual_bytes=body_size)
13323
13324 body_parts.append(chunk)
13325 if not message.get("more_body", False):
13326 return b"".join(body_parts)
13327
13328
13329async def _send_request_too_large(send, error: RequestBodyTooLargeError) -> None:
13330 await _send_json(
13331 send,
13332 {
13333 "status": "error",
13334 "error": str(error),
13335 "max_bytes": error.max_bytes,
13336 },
13337 status=413,
13338 )
13339
13340
13341async def _send_capacity_error(send, *, limit_name: str, max_concurrent: int) -> None:
13342 await _send_json(
13343 send,
13344 {
13345 "status": "error",
13346 "error": "Server is busy",
13347 "limit": limit_name,
13348 "max_concurrent": max_concurrent,
13349 },
13350 status=503,
13351 )
13352
13353
13354async def _send_rate_limit_error(
13355 send,
13356 result: object_rate_limit.RateLimitResult,
13357) -> None:
13358 await _send_json(
13359 send,
13360 {
13361 "status": "error",
13362 "error": "Rate limit exceeded",
13363 "retry_after": result.retry_after,
13364 "limit": result.limit,
13365 "window_seconds": result.window_seconds,
13366 },
13367 status=429,
13368 headers=[("retry-after", str(result.retry_after))],
13369 )
13370
13371
13372async def _send_json(
13373 send,
13374 payload: Any,
13375 status: int = 200,
13376 headers: list[tuple[str, str]] | None = None,
13377) -> None:
13378 body = json.dumps(payload).encode("utf-8")
13379 response_headers = [("content-type", "application/json; charset=utf-8")]
13380 if headers:
13381 response_headers.extend(headers)
13382 await _send_response(
13383 send,
13384 status=status,
13385 headers=response_headers,
13386 body=body,
13387 )
13388
13389
13390async def _send_object_response(send, payload: Any) -> None:
13391 status, headers, body = _normalize_object_response(payload)
13392 await _send_response(send, status=status, headers=headers, body=body)
13393
13394
13395def _normalize_object_response(payload: Any) -> tuple[int, list[tuple[str, str]], bytes]:
13396 if _is_response_tuple(payload):
13397 status, headers, body = payload
13398 return _normalize_status(status), _normalize_headers(headers), _normalize_body(body)
13399
13400 if isinstance(payload, dict) and payload.get("content_type"):
13401 status = payload.get("status_code", payload.get("http_status", payload.get("status", 200)))
13402 headers = [("content-type", str(payload["content_type"]))]
13403 headers.extend(_html_cache_headers(str(payload["content_type"])))
13404 headers.extend(_object_set_cookie_headers(payload))
13405 return _normalize_status(status), headers, _normalize_body(payload.get("body", b""))
13406
13407 if isinstance(payload, str):
13408 return 200, [("content-type", "text/html; charset=utf-8"),
13409 ("cache-control", "no-store")], payload.encode("utf-8")
13410
13411 if isinstance(payload, bytes):
13412 return 200, [("content-type", "application/octet-stream")], payload
13413
13414 # A JSON-returning object may set the HTTP status too. Until now only
13415 # the content_type branch honored it, so an action answering
13416 # {"status": 409, "error": ...} was delivered as HTTP 200 with the
13417 # refusal hidden in the body -- invisible to any client that checks
13418 # the status line, and actively harmful for webhooks, where a
13419 # provider's retry logic reads nothing else (a signature failure
13420 # answered 200 is a forgery silently accepted forever).
13421 #
13422 # Only an INTEGER in HTTP range counts: collections legitimately carry
13423 # a `status` field of their own ("active", "posted", "draft"), and a
13424 # record echoed back must never be mistaken for a status line.
13425 if isinstance(payload, dict):
13426 for key in ("status_code", "http_status", "status"):
13427 candidate = payload.get(key)
13428 if isinstance(candidate, bool) or not isinstance(candidate, int):
13429 continue
13430 if 100 <= candidate <= 599:
13431 body = json.dumps(payload).encode("utf-8")
13432 return candidate, [("content-type", "application/json; charset=utf-8")], body
13433
13434 body = json.dumps(payload).encode("utf-8")
13435 return 200, [("content-type", "application/json; charset=utf-8")], body
13436
13437
13438def _html_cache_headers(content_type: str) -> list[tuple[str, str]]:
13439 """no-store for object-served HTML pages; nothing for anything else.
13440
13441 These pages are rendered per request -- the inline script IS the
13442 application -- and they shipped with no cache headers at all, which
13443 left the browser's heuristic cache in charge. Safari's heuristics bit
13444 for real: a fix deployed to /talk, verified live with curl, and an
13445 iPad kept reproducing the old bug because it was running the old
13446 page. "Did you deploy?" should never be a question the cache gets to
13447 answer.
13448
13449 Deliberately HTML-only. The generative widgets (/style, /list, /form)
13450 are separate objects with their own content types, and turning off
13451 caching for every asset on every page view is a heavier performance
13452 decision than this bug justifies -- the observed failure class is a
13453 stale page with stale inline script, so that is what is fixed. An
13454 object that takes full header control (the tuple form) is respected
13455 and untouched.
13456 """
13457 if content_type.split(";")[0].strip().lower() == "text/html":
13458 return [("cache-control", "no-store")]
13459 return []
13460
13461
13462def _object_set_cookie_headers(payload: dict[str, Any]) -> list[tuple[str, str]]:
13463 """The one response header an object may set: `set_cookie` (a string).
13464
13465 A SAFELIST OF ONE, and deliberately so. A page object has a legitimate
13466 need to remember something about this visitor across requests, and no
13467 other way to do it. It has no legitimate need to set `location`,
13468 `access-control-allow-origin`, `content-security-policy` or
13469 `cache-control` -- those are the SERVER's security posture, and a
13470 general headers passthrough would hand every installed package the
13471 ability to rewrite it. Widening this is a conscious act, not a default.
13472
13473 Cookie *attributes* are the object's business (Path, HttpOnly,
13474 SameSite, Max-Age); the server only refuses a value that would break
13475 out of the header itself.
13476 """
13477 value = payload.get("set_cookie")
13478 if not isinstance(value, str) or not value.strip():
13479 return []
13480 if "\r" in value or "\n" in value:
13481 # Response splitting: a newline lets the object append headers of its
13482 # own -- or a whole second response -- to the wire. Dropped rather
13483 # than raised: the page still renders, it just does not get a cookie.
13484 return []
13485 return [("set-cookie", value)]
13486
13487
13488async def _send_response(
13489 send,
13490 *,
13491 status: int,
13492 headers: list[tuple[str, str]],
13493 body: bytes,
13494) -> None:
13495 await send(
13496 {
13497 "type": "http.response.start",
13498 "status": status,
13499 "headers": [(name.encode("latin-1"), value.encode("latin-1")) for name, value in headers],
13500 }
13501 )
13502 await send({"type": "http.response.body", "body": body})
13503
13504
13505def _is_response_tuple(payload: Any) -> bool:
13506 return isinstance(payload, tuple) and len(payload) == 3
13507
13508
13509def _normalize_status(status: Any) -> int:
13510 if isinstance(status, bool):
13511 return 200
13512
13513 try:
13514 value = int(status)
13515 except (TypeError, ValueError):
13516 return 200
13517
13518 if value < 100 or value > 599:
13519 return 200
13520
13521 return value
13522
13523
13524def _normalize_headers(headers: Any) -> list[tuple[str, str]]:
13525 if headers is None:
13526 return []
13527
13528 if isinstance(headers, dict):
13529 header_items = headers.items()
13530 elif isinstance(headers, (list, tuple)):
13531 header_items = headers
13532 else:
13533 return []
13534
13535 normalized = []
13536 for item in header_items:
13537 if not isinstance(item, (list, tuple)) or len(item) != 2:
13538 continue
13539 name, value = item
13540 header_name = _header_text(name).lower()
13541 if header_name:
13542 normalized.append((header_name, _header_text(value)))
13543 return normalized
13544
13545
13546def _header_text(value: Any) -> str:
13547 if isinstance(value, bytes):
13548 text = value.decode("latin-1")
13549 else:
13550 text = str(value)
13551 return text.replace("\r", "").replace("\n", "")
13552
13553
13554def _download_filename(filename: str) -> str:
13555 name = filename.rsplit("/", 1)[-1]
13556 return name.replace("\\", "_").replace('"', "_") or "download"
13557
13558
13559def _normalize_body(body: Any) -> bytes:
13560 if body is None:
13561 return b""
13562
13563 if isinstance(body, bytes):
13564 return body
13565
13566 if isinstance(body, str):
13567 return body.encode("utf-8")
13568
13569 if isinstance(body, (list, tuple)):
13570 parts = []
13571 for part in body:
13572 parts.append(_normalize_body(part))
13573 return b"".join(parts)
13574
13575 return str(body).encode("utf-8")
13576
13577
13578async def _send_execution_error(
13579 send,
13580 result: object_execution.ObjectExecutionResult,
13581) -> None:
13582 error = result.error
13583 error_message = "Object execution failed"
13584 status = 500
13585
13586 if error is not None:
13587 error_message = error.message
13588 if error.type == "ObjectNotFoundError":
13589 status = 404
13590 elif error.type == MethodNotSupportedError.__name__:
13591 status = 405
13592 elif error.type == object_execution.TIMEOUT_ERROR_TYPE:
13593 status = 504
13594
13595 prefix = "Execution failed: "
13596 if status == 404:
13597 prefix = ""
13598
13599 await _send_json(
13600 send,
13601 {
13602 "status": "error",
13603 "error": f"{prefix}{error_message}",
13604 "correlation_id": result.correlation_id,
13605 },
13606 status=status,
13607 )
13608
13609
13610_ANALYTICS_POSTURE_LOGGED = False
13611
13612
13613def _note_analytics_posture_once() -> None:
13614 """State the visitor cookie's posture on the boot line, in words.
13615
13616 The daemon prints the same sentence; the server prints it too because
13617 the two processes are started separately and an operator reading only
13618 one of them should still be told. `DBBASIC_ANALYTICS_VISITOR_COOKIE=on`
13619 is the single act that makes this server store an identifier on
13620 somebody's device, and object_analytics.OBLIGATION says what that
13621 commits them to rather than merely echoing the setting back.
13622 """
13623 global _ANALYTICS_POSTURE_LOGGED
13624 if _ANALYTICS_POSTURE_LOGGED:
13625 return
13626 _ANALYTICS_POSTURE_LOGGED = True
13627 print(f"[dbbasic] Analytics: {object_analytics.visitor_cookie_posture()}",
13628 file=sys.stderr)
13629
13630
13631async def _handle_lifespan(receive, send) -> None:
13632 while True:
13633 message = await receive()
13634 if message["type"] == "lifespan.startup":
13635 _note_analytics_posture_once()
13636 await send({"type": "lifespan.startup.complete"})
13637 elif message["type"] == "lifespan.shutdown":
13638 await _shutdown_worker_pool()
13639 await send({"type": "lifespan.shutdown.complete"})
13640 return
13641
13642
13643if __name__ == "__main__":
13644 import uvicorn
13645
13646 uvicorn.run("object_server:app", host="127.0.0.1", port=8001, reload=False)