terp-cap-files 0.1.0__tar.gz

terp_cap_files-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_files-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: terp-cap-files
+Version: 0.1.0
+Summary: Terp files capability — owner-scoped file objects with metadata in the platform database and bytes behind a pluggable storage backend.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: python-multipart>=0.0.30
+Requires-Dist: terp-core==0.1.0

terp_cap_files-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,3 @@
+{
+  "arch-allow-routes-declare-response-model": 1
+}

terp_cap_files-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-files"
+version = "0.1.0"
+description = "Terp files capability — owner-scoped file objects with metadata in the platform database and bytes behind a pluggable storage backend."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    # FastAPI parses the multipart upload body through this (UploadFile); the byte
+    # stream never touches app code — it flows metadata->DB, bytes->StorageBackend.
+    "python-multipart>=0.0.30",
+]
+
+# Self-registering: the kernel discovers this ModuleSpec via the entry point, mounting the
+# admin files router at `/api/v1/files` without any composition-root edit.
+[project.entry-points."terp.capabilities"]
+files = "terp.capabilities.files:module"
+
+# Owns the `file_object` metadata table, so it ships an independent, linear Alembic
+# history (its own `alembic_version_files` table). `terp migrate` discovers this via
+# the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+files = "terp.capabilities.files"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.files`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/files"]

terp_cap_files-0.1.0/src/terp/capabilities/files/__init__.py

@@ -0,0 +1,101 @@
+"""terp.capabilities.files — owner-scoped file objects on a pluggable storage backend.
+
+The last of the planned foundation capabilities (design §3.1, §6): an app stores and
+retrieves **file objects** through a maintained, secure-by-default surface, with all
+*metadata* owned in the platform database and the *bytes* behind a tiny storage port.
+
+* :class:`File` (``BaseTable`` + ``OwnedMixin``) is the metadata row — name, type, size,
+  digest, the server-generated ``storage_key`` addressing the bytes, and the
+  ``storage_profile`` naming the backend that holds them. Both are server-side-only
+  material: no Read DTO ever serializes them.
+* :class:`StorageBackend` is the pluggable byte-store seam (``put`` / ``open`` /
+  ``delete``, streamed through readable binary objects — ADR 0066) behind a
+  **named-profile registry** (ADR 0057): the ``"default"`` profile
+  is the shipped :class:`LocalFilesystemStorage` reference adapter, and a deployment
+  installs any provider — another root, S3, Azure Blob, a NAS mount — under one or many
+  profiles (one per container / module use) with one :func:`register_storage_backend`
+  line each; resolution (:func:`resolve_storage_backend`) is fail-closed
+  (:class:`UnknownStorageProfileError`). A service or call selects a store by profile
+  name; a client never does.
+* :func:`FileRef` declares a model column that references a stored file, and
+  :meth:`FileService.load_for` is the serve-through delegation read: a module serves a
+  file through its **own**, already-authorized row, fail-closed on any undeclared
+  reference (:class:`UndeclaredFileReferenceError`; build-time twin: the
+  ``no_raw_file_references`` rule).
+* The discovered, admin-only router at ``/api/v1/files`` uploads, downloads, lists
+  (``Page[T]``), renames, and deletes; ``OwnedMixin`` makes edit / delete owner-gated
+  centrally in ``BaseService`` with zero module code.
+
+It depends only on ``terp-core`` (plus the multipart parser FastAPI needs for uploads) —
+never a sibling capability or a storage engine SDK.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.files.models import File
+from terp.capabilities.files.references import (
+    FileRef,
+    UndeclaredFileReferenceError,
+    is_file_reference,
+)
+from terp.capabilities.files.router import (
+    MAX_UPLOAD_BYTES,
+    active_upload_limit,
+    configure_upload_limit,
+    module,
+    reset_upload_limit,
+    router,
+)
+from terp.capabilities.files.schemas import FileCreate, FileRead, FileUpdate
+from terp.capabilities.files.service import (
+    ContentTypeMismatchError,
+    FileService,
+    UnsupportedContentTypeError,
+    active_allowed_content_types,
+    configure_allowed_content_types,
+    reset_allowed_content_types,
+)
+from terp.capabilities.files.storage import (
+    DEFAULT_STORAGE_PROFILE,
+    FileStorageError,
+    LocalFilesystemStorage,
+    StorageBackend,
+    UnknownStorageProfileError,
+    active_storage_backend,
+    register_storage_backend,
+    reset_storage_backend,
+    resolve_storage_backend,
+    set_storage_backend,
+)
+
+__all__ = [
+    "DEFAULT_STORAGE_PROFILE",
+    "MAX_UPLOAD_BYTES",
+    "ContentTypeMismatchError",
+    "File",
+    "FileCreate",
+    "FileRead",
+    "FileRef",
+    "FileService",
+    "FileStorageError",
+    "FileUpdate",
+    "LocalFilesystemStorage",
+    "StorageBackend",
+    "UndeclaredFileReferenceError",
+    "UnknownStorageProfileError",
+    "UnsupportedContentTypeError",
+    "active_allowed_content_types",
+    "active_storage_backend",
+    "active_upload_limit",
+    "configure_allowed_content_types",
+    "configure_upload_limit",
+    "is_file_reference",
+    "module",
+    "register_storage_backend",
+    "reset_allowed_content_types",
+    "reset_storage_backend",
+    "reset_upload_limit",
+    "resolve_storage_backend",
+    "router",
+    "set_storage_backend",
+]

terp_cap_files-0.1.0/src/terp/capabilities/files/migrations/versions/ceffeb4b0fc2_create_file_table.py

@@ -0,0 +1,54 @@
+"""create file table
+
+Revision ID: ceffeb4b0fc2
+Revises: 
+Create Date: 2026-07-02 11:20:59.258321
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'ceffeb4b0fc2'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('file_object',
+    sa.Column('owner_id', sa.Uuid(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('version', sa.Integer(), nullable=False),
+    sa.Column('filename', sqlmodel.sql.sqltypes.AutoString(length=255), nullable=False),
+    sa.Column('content_type', sqlmodel.sql.sqltypes.AutoString(length=255), nullable=False),
+    sa.Column('size', sa.Integer(), nullable=False),
+    sa.Column('sha256', sqlmodel.sql.sqltypes.AutoString(length=64), nullable=False),
+    sa.Column('storage_key', sqlmodel.sql.sqltypes.AutoString(length=512), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_file_object')),
+    sa.UniqueConstraint('storage_key', name=op.f('uq_file_object_storage_key'))
+    )
+    with op.batch_alter_table('file_object', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_file_object_filename'), ['filename'], unique=False)
+        batch_op.create_index(batch_op.f('ix_file_object_owner_id'), ['owner_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('file_object', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_file_object_owner_id'))
+        batch_op.drop_index(batch_op.f('ix_file_object_filename'))
+
+    op.drop_table('file_object')
+    # ### end Alembic commands ###

terp_cap_files-0.1.0/src/terp/capabilities/files/migrations/versions/e3a9c47d51b8_add_file_storage_profile.py

@@ -0,0 +1,40 @@
+"""add file storage profile
+
+Revision ID: e3a9c47d51b8
+Revises: ceffeb4b0fc2
+Create Date: 2026-07-02 12:05:00.000000
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'e3a9c47d51b8'
+down_revision: str | None = 'ceffeb4b0fc2'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # Every pre-existing row was stored through the original single (default) backend,
+    # so the backfill value is exactly the store that holds its bytes.
+    with op.batch_alter_table('file_object', schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column(
+                'storage_profile',
+                sqlmodel.sql.sqltypes.AutoString(length=64),
+                nullable=False,
+                server_default='default',
+            )
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('file_object', schema=None) as batch_op:
+        batch_op.drop_column('storage_profile')

terp_cap_files-0.1.0/src/terp/capabilities/files/models.py

@@ -0,0 +1,66 @@
+"""The ``file_object`` metadata table: an owner-scoped file record.
+
+``File`` is a normal owner-scoped resource (``BaseTable`` + ``OwnedMixin``): its creator
+owns it and only the owner may edit / delete it — the per-row write gate (ADR 0029),
+enforced centrally by ``BaseService`` with zero module code (never a hand-rolled
+``owner_id`` check — ``terp guide ownership``). Only the *metadata* lives here; the bytes
+live behind the pluggable :class:`~terp.capabilities.files.StorageBackend`, addressed by
+the server-generated ``storage_key``.
+
+Mutability is decided per field:
+
+* ``filename`` — **mutable** (a rename is a metadata edit; the bytes are untouched), via
+  the OCC-bearing ``update`` path.
+* ``content_type`` / ``size`` / ``sha256`` / ``storage_key`` / ``storage_profile`` —
+  **append-only**: set once from the uploaded bytes at create time and never patched
+  (``FileUpdate`` carries no field for them; replacing content is a new upload).
+  ``storage_key`` and ``storage_profile`` in particular are server-side-only material
+  (the raw storage address and the named backend holding it): both are generated /
+  selected by the service, never accepted from a client, and never serialized out of the
+  API boundary (no ``*Read`` DTO carries them — enforced by a runtime test alongside the
+  ``schemas_exclude_sensitive_fields`` posture). ``storage_profile`` being append-only is
+  what keeps a row pointing at the store that actually holds its bytes: re-homing a blob
+  is an explicit migration, never a patch.
+
+Every caller-influenceable ``str`` column caps its length so a hostile or oversized value
+can never break the INSERT.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from sqlmodel import Field
+
+from terp.core import BaseTable, OwnedMixin
+
+from terp.capabilities.files.storage import STORAGE_PROFILE_MAX
+
+# Hard caps so a hostile / oversized value can never break the INSERT.
+FILENAME_MAX: Final[int] = 255
+CONTENT_TYPE_MAX: Final[int] = 255
+_SHA256_MAX: Final[int] = 64
+_STORAGE_KEY_MAX: Final[int] = 512
+
+
+class File(BaseTable, OwnedMixin, table=True):
+    """One stored file's metadata: name, type, size, digest, and its storage address.
+
+    ``id`` / ``created_at`` / ``updated_at`` / ``version`` are inherited from ``BaseTable``;
+    ``owner_id`` from ``OwnedMixin`` (stamped from the request actor on create, then enforced
+    as the per-row write gate). ``storage_key`` addresses the bytes inside the storage
+    backend registered under ``storage_profile`` (ADR 0057); neither is **ever**
+    serialized in a Read DTO.
+    """
+
+    __tablename__ = "file_object"
+
+    filename: str = Field(max_length=FILENAME_MAX, index=True)
+    content_type: str = Field(max_length=CONTENT_TYPE_MAX)
+    size: int = Field(ge=0)
+    sha256: str = Field(max_length=_SHA256_MAX)
+    storage_key: str = Field(max_length=_STORAGE_KEY_MAX, unique=True)
+    storage_profile: str = Field(max_length=STORAGE_PROFILE_MAX)
+
+
+__all__ = ["CONTENT_TYPE_MAX", "FILENAME_MAX", "File"]

terp_cap_files-0.1.0/src/terp/capabilities/files/references.py

@@ -0,0 +1,82 @@
+"""Declared file references: ``FileRef`` + the fail-closed delegation check (ADR 0057).
+
+A module that stores a pointer to a :class:`~terp.capabilities.files.File` (an invoice's
+attachment, a report's export) must **declare** the reference — a bare
+``file_id: uuid.UUID`` column carries no authorization semantics, and implicit "can see
+the record ⇒ can see the file" propagation is exactly how object-level (BOLA) leaks
+happen. The posture is **default-deny + explicit delegation**:
+
+* :func:`FileRef` declares the column: it returns a normal indexed ``uuid`` field whose
+  ``FieldInfo`` carries a machine-readable marker, making the reference greppable and
+  verifiable at both build time (the ``no_raw_file_references`` rule flags a bare
+  ``*file_id`` table column) and runtime (:func:`is_file_reference`).
+* Delegated access is **serve-through**: the referencing module loads its *own* row
+  through its *own* service (so that row's policy + row scope + per-row write gate
+  already decided visibility), then serves the bytes with
+  :meth:`~terp.capabilities.files.FileService.load_for` — which fail-closes on any
+  column not declared with :func:`FileRef` (:class:`UndeclaredFileReferenceError`).
+  Access to the file thus provably follows the referencing record's access, the raw
+  ``/api/v1/files`` surface stays ADMIN-only, and delegation widens to exactly one
+  already-authorized row — never by an implicit, registry-wide grant.
+
+The kernel's predicate seams (scope / object-authz) compose with **AND** semantics — they
+can only ever *narrow* access. That is deliberate, and it is why delegation is a
+serve-through helper rather than a registered predicate: a predicate cannot (and must
+never) silently *widen* who may reach a file.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlmodel import Field, SQLModel
+
+from terp.core import AppError
+
+# The machine-readable marker a FileRef-declared column carries in its FieldInfo.
+_FILE_REF_MARKER = "terp_file_ref"
+
+
+class UndeclaredFileReferenceError(AppError):
+    """500 — a serve-through read named a column not declared with ``FileRef``.
+
+    Fail-closed: delegated file access flows only through a **declared** reference, so a
+    typo'd column name or an undeclared bare ``uuid`` column refuses instead of serving
+    bytes. This is a module wiring error (declare the column with :func:`FileRef`),
+    never a caller mistake.
+    """
+
+    status_code = 500
+    code = "file_reference_undeclared"
+    default_message = "The record's file reference is not declared with FileRef."
+
+
+def FileRef(*, index: bool = True) -> Any:  # noqa: N802 - a Field-style factory, named like the trait it declares
+    """Declare a model column as a reference to a stored ``File``.
+
+    Use it instead of a bare ``uuid`` field::
+
+        class Invoice(BaseTable, table=True):
+            attachment_file_id: uuid.UUID | None = FileRef()
+
+    The column is a normal nullable, indexed ``uuid`` — no database FK is imposed (the
+    ``File`` row may live in another package's migration history) — but its ``FieldInfo``
+    carries the declaration marker :func:`is_file_reference` and
+    :meth:`~terp.capabilities.files.FileService.load_for` verify, and the
+    ``no_raw_file_references`` rule enforces at build time.
+    """
+    field = Field(default=None, index=index)
+    field.json_schema_extra = {_FILE_REF_MARKER: True}
+    return field
+
+
+def is_file_reference(model: type[SQLModel], column: str) -> bool:
+    """Whether *model*.*column* is declared as a file reference (via :func:`FileRef`)."""
+    field = model.model_fields.get(column)
+    if field is None:
+        return False
+    extra = field.json_schema_extra
+    return isinstance(extra, dict) and bool(extra.get(_FILE_REF_MARKER))
+
+
+__all__ = ["FileRef", "UndeclaredFileReferenceError", "is_file_reference"]

terp_cap_files-0.1.0/src/terp/capabilities/files/router.py

@@ -0,0 +1,221 @@
+"""Owner-scoped admin router for files: upload, download, list, rename, delete.
+
+Self-registering (``module``): the kernel's entry-point discovery mounts it at
+``/api/v1/files`` with no composition-root edit. File storage is a privileged,
+disk/backend-consuming capability, so the policy requires ``ADMIN``; ``File`` also
+composes ``OwnedMixin``, so the **per-row** write gate (an admin may rename / delete only
+their *own* file) is enforced centrally by ``BaseService`` — the routes carry no ownership
+logic. The raw ``storage_key`` never leaves the boundary (``FileRead`` omits it); the
+download route **streams** the bytes back through a ``StreamingResponse`` (read from the
+backend in chunks, so a large file never lands in memory whole) with a sanitized
+``Content-Disposition`` (RFC 5987 encoding, so a hostile stored filename can never inject
+response headers). The upload is **streamed** straight from the parsed part's spooled file
+into the storage backend, hashing and size-capping the bytes in flight (ADR 0066): the
+service refuses the instant the running total crosses ``MAX_UPLOAD_BYTES`` and compensates
+the partial blob, so the write path never buffers the whole upload — and the kernel's
+``RequestSizeLimitMiddleware`` still bounds the raw request body up front.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+import uuid
+from collections.abc import Iterator
+from typing import BinaryIO, Final
+
+from fastapi import APIRouter, Request
+from fastapi.responses import StreamingResponse
+from starlette.datastructures import UploadFile
+
+from terp.core import (
+    ADMIN,
+    ModuleSpec,
+    Page,
+    PaginationDep,
+    Policy,
+    SessionDep,
+    ValidationFailedError,
+)
+
+from terp.capabilities.files.models import CONTENT_TYPE_MAX, FILENAME_MAX
+from terp.capabilities.files.schemas import FileRead, FileUpdate
+from terp.capabilities.files.service import FileService
+
+# The default cap on one upload's stored byte size (a DoS guard enforced mid-stream by the
+# service, which compensates the partial blob on overrun — the request path never buffers the
+# whole upload). Deliberately conservative; a deployment retunes it with one composition-root
+# line (configure_upload_limit) paired with create_app(request_size_overrides={"files": ...})
+# when the new ceiling exceeds the module's declared request allowance (ADR 0067).
+MAX_UPLOAD_BYTES: Final[int] = 25 * 1024 * 1024
+
+# Headroom the module's declared request-body allowance adds over the stored-bytes cap:
+# a multipart body carries boundary lines + part headers around the file bytes, so the
+# request cap must sit slightly above the stored cap or a maximum-size file would be
+# refused at the socket before the streamed cap ever measured it.
+_MULTIPART_HEADROOM_BYTES: Final[int] = 64 * 1024
+
+# The active stored-bytes cap (module-level, composition-root-configured — the same seam
+# shape as the storage registry). Never client data.
+_upload_limit: int = MAX_UPLOAD_BYTES
+
+
+def configure_upload_limit(max_bytes: int) -> None:
+    """Set the stored-bytes cap for uploads (a composition-root line, ADR 0067).
+
+    Validated eagerly (positive) so a mis-wired root fails at boot, not at the first
+    upload. A ceiling above the module's declared request allowance
+    (``MAX_UPLOAD_BYTES + 64 KiB``) must be paired with
+    ``create_app(request_size_overrides={"files": <ceiling + headroom>})`` — otherwise
+    the kernel's request-size middleware still refuses the larger body first
+    (fail-closed, never silently wider).
+    """
+    global _upload_limit
+    if max_bytes <= 0:
+        raise ValueError("the upload limit must be a positive byte count")
+    _upload_limit = max_bytes
+
+
+def active_upload_limit() -> int:
+    """The stored-bytes cap uploads are currently held to."""
+    return _upload_limit
+
+
+def reset_upload_limit() -> None:
+    """Restore the default cap (the test-isolation reset, like the storage registry's)."""
+    global _upload_limit
+    _upload_limit = MAX_UPLOAD_BYTES
+
+
+# The chunk size the download route pulls from the backend stream (bounded memory per read).
+_DOWNLOAD_CHUNK_BYTES: Final[int] = 64 * 1024
+
+_DEFAULT_FILENAME: Final[str] = "upload"
+_DEFAULT_CONTENT_TYPE: Final[str] = "application/octet-stream"
+
+
+def _iter_blob(stream: BinaryIO) -> Iterator[bytes]:
+    """Yield a backend blob stream in fixed-size chunks, closing it when exhausted.
+
+    Feeds ``StreamingResponse`` so a download never materializes the whole file in memory;
+    the ``finally`` guarantees the backend handle is released even if the client disconnects
+    mid-stream.
+    """
+    try:
+        while chunk := stream.read(_DOWNLOAD_CHUNK_BYTES):
+            yield chunk
+    finally:
+        stream.close()
+
+
+router = APIRouter(tags=["files"])
+_service = FileService()
+
+
+def _content_disposition(filename: str) -> str:
+    """A header-safe attachment disposition for *filename* (RFC 5987 / RFC 6266).
+
+    The stored filename is caller-supplied, so it is never emitted raw: the primary
+    ``filename*`` value is fully percent-encoded (no CR/LF/quote can survive), and the
+    ASCII ``filename`` fallback keeps only a conservative character set.
+    """
+    fallback = "".join(
+        ch if ch.isascii() and (ch.isalnum() or ch in "._-") else "_" for ch in filename
+    )
+    encoded = urllib.parse.quote(filename, safe="")
+    return f'attachment; filename="{fallback or _DEFAULT_FILENAME}"; filename*=UTF-8\'\'{encoded}'
+
+
+@router.post("/", response_model=FileRead, status_code=201)
+async def upload_file(request: Request, session: SessionDep) -> FileRead:
+    form = await request.form(max_files=1, max_fields=0, max_part_size=1024)
+    uploaded = form.get("file")
+    if not isinstance(uploaded, UploadFile):
+        raise ValidationFailedError("Upload a file part named 'file'.")
+    file = uploaded
+    filename = file.filename or _DEFAULT_FILENAME
+    if len(filename) > FILENAME_MAX:
+        raise ValidationFailedError(
+            f"The filename exceeds the {FILENAME_MAX}-character limit."
+        )
+    content_type = file.content_type or _DEFAULT_CONTENT_TYPE
+    if len(content_type) > CONTENT_TYPE_MAX:
+        raise ValidationFailedError(
+            f"The content type exceeds the {CONTENT_TYPE_MAX}-character limit."
+        )
+    # Stream the parsed part's spooled file straight into the backend: the service hashes
+    # and size-caps the bytes in flight (refusing + compensating past the active limit), so
+    # the write path never holds the whole upload in memory. A sync handler runs in the
+    # threadpool, so the blocking copy never stalls the event loop.
+    file.file.seek(0)
+    return FileRead.model_validate(
+        _service.store(
+            session,
+            filename=filename,
+            content_type=content_type,
+            source=file.file,
+            max_bytes=active_upload_limit(),
+        )
+    )
+
+
+@router.get("/", response_model=Page[FileRead])
+def list_files(session: SessionDep, pagination: PaginationDep) -> Page[FileRead]:
+    rows, total = _service.list(session, skip=pagination.skip, limit=pagination.limit)
+    return Page[FileRead].of(
+        [FileRead.model_validate(row) for row in rows], total, pagination
+    )
+
+
+@router.get("/{file_id}", response_model=FileRead)
+def get_file(file_id: uuid.UUID, session: SessionDep) -> FileRead:
+    return FileRead.model_validate(_service.get(session, file_id))
+
+
+@router.get("/{file_id}/content")  # arch-allow-routes-declare-response-model: binary download — the bytes stream out through a StreamingResponse (stored media type + sanitized attachment disposition), never a serialized ORM object
+def download_file(file_id: uuid.UUID, session: SessionDep) -> StreamingResponse:
+    row, stream = _service.open_stream(session, file_id)
+    return StreamingResponse(
+        _iter_blob(stream),
+        media_type=row.content_type,
+        headers={
+            "Content-Disposition": _content_disposition(row.filename),
+            # The stored size is append-only and derived from the streamed bytes at create
+            # time, so it is authoritative: declaring it keeps download progress / resume
+            # working, and a blob truncated out-of-band surfaces as a protocol error
+            # instead of a silently short body.
+            "Content-Length": str(row.size),
+        },
+    )
+
+
+@router.patch("/{file_id}", response_model=FileRead)
+def update_file(
+    file_id: uuid.UUID, payload: FileUpdate, session: SessionDep
+) -> FileRead:
+    return FileRead.model_validate(_service.update(session, file_id, payload))
+
+
+@router.delete("/{file_id}", status_code=204)
+def delete_file(file_id: uuid.UUID, session: SessionDep) -> None:
+    _service.remove(session, file_id)
+
+
+module = ModuleSpec(
+    name="files",
+    router=router,
+    policy=Policy(read=ADMIN, write=ADMIN),
+    # The declared request-body allowance for /api/v1/files (ADR 0067): the default
+    # stored-bytes cap plus multipart framing headroom, so a maximum-size upload fits
+    # through the kernel's request-size middleware without widening the global cap.
+    max_request_bytes=MAX_UPLOAD_BYTES + _MULTIPART_HEADROOM_BYTES,
+)
+
+
+__all__ = [
+    "MAX_UPLOAD_BYTES",
+    "active_upload_limit",
+    "configure_upload_limit",
+    "module",
+    "reset_upload_limit",
+    "router",
+]