feat(files): API tokens — a machine reaches the library folder by folder

A user can make a token for a machine of theirs (`/api/tokens`, signed-in only): `sfl_` + 32
random bytes + a checksum, only its SHA-256 kept, shown once. Sent as a Bearer header it is
honoured on six `/api/files` routes only — folders, list, file, hash, upload, delete — and there
only in the folders its grants name, with the rights they give (list / read / write / delete).
One check, `FilesCaller.may`, in every route; a folder or file out of reach answers like a
missing one; the files shared with the user are never in reach. A token beats a cookie on the
same request.

The Hub preset makes the user's one Hub folder (a new folder kind) and grants it every right.
Refused tokens are slowed down per client, a runaway machine per token; last use is stamped at
most once a minute; making and revoking a token is audited, and a token's uploads and deletes
name it in their audit rows.

backend/app/models.py

@@ -919,7 +919,8 @@ class FileFolder(Base, TimestampMixin):
     """A folder of the Files library (`app.downloads.folders`): a row, never a directory.
 
     A SOURCE folder (`source_key` set: youtube / plex / upload / site:<host>) is made the first time a
-    user gets a file from that origin; an OWN folder (`name` set) is one the user made. Every file —
+    user gets a file from that origin; an OWN folder (`name` set) is one the user made; the HUB folder
+    (neither set, one per user) is where they swap files with a machine of theirs. Every file —
     a `DownloadJob` — sits in exactly one (`DownloadJob.folder_id`). `retention_days` is how long a
     file stays once done (NULL = until deleted); a file's own `expires_at` is stamped from it."""
 
@@ -933,9 +934,12 @@ class FileFolder(Base, TimestampMixin):
             unique=True,
             postgresql_where=text("name IS NOT NULL"),
         ),
+        # One Hub folder per user.
+        Index("uq_file_folder_hub", "user_id", unique=True, postgresql_where=text("kind = 'hub'")),
         CheckConstraint(
             "(kind = 'source' AND source_key IS NOT NULL AND name IS NULL)"
-            " OR (kind = 'own' AND name IS NOT NULL AND source_key IS NULL)",
+            " OR (kind = 'own' AND name IS NOT NULL AND source_key IS NULL)"
+            " OR (kind = 'hub' AND name IS NULL AND source_key IS NULL)",
             name="ck_file_folder_kind",
         ),
     )
@@ -949,6 +953,45 @@ class FileFolder(Base, TimestampMixin):
     retention_days: Mapped[int | None] = mapped_column(Integer)
 
 
+class ApiToken(Base, TimestampMixin):
+    """A user's token for a machine to reach their Files library with (`app.apitokens`): sent as
+    `Authorization: Bearer sfl_…`, honoured on `/api/files` only, and only in the folders its
+    grants name. Only the SHA-256 of the token is kept — it is shown once, when it is made — plus
+    its first characters (`prefix`), so the user can tell their tokens apart."""
+
+    __tablename__ = "api_tokens"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    name: Mapped[str] = mapped_column(String(80))
+    prefix: Mapped[str] = mapped_column(String(16))
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))  # NULL = never
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class ApiTokenGrant(Base):
+    """What one token may do in one folder. A folder with no grant is out of the token's reach."""
+
+    __tablename__ = "api_token_grants"
+    __table_args__ = (
+        UniqueConstraint("token_id", "folder_id", name="uq_api_token_grant"),
+        CheckConstraint(
+            "can_list OR can_read OR can_write OR can_delete", name="ck_api_token_grant_some"
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    token_id: Mapped[int] = mapped_column(ForeignKey("api_tokens.id", ondelete="CASCADE"))
+    folder_id: Mapped[int] = mapped_column(
+        ForeignKey("file_folders.id", ondelete="CASCADE"), index=True
+    )
+    can_list: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
+    can_read: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
+    can_write: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
+    can_delete: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
+
+
 def _ready_on_insert(context) -> datetime | None:
     """A job inserted already done (an upload kept as it came) was ready the moment it was made; one
     that becomes done later is stamped then (`folders.stamp_done`, `service.finalize_if_running`)."""