feat(files): share-link tokens are kept only hashed and encrypted, and every link change is audited

A /watch link's token is the credential, and it sat in the database as written. Migration 0107
replaces the column with the token's SHA-256 (the lookup) and a Fernet-encrypted copy (so the owner
can copy the same link again); every existing address keeps working, and the downgrade decrypts
them back. Without a copy this key can read, a link still opens but its address cannot be shown:
"Copy link" then takes the newest link that has one or makes a new one, and the Share dialog says
so in that row instead of a broken URL. Making, changing and revoking a link are audited, never
with its token or password.

backend/app/audit.py

@@ -73,6 +73,11 @@ class AuditAction:
     # What a token then did is the file rows above, their summary naming it.
     API_TOKEN_CREATE = "api_token_create"
     API_TOKEN_REVOKE = "api_token_revoke"
+    # A public `/watch` link to a file (`routes.downloads`): made, its settings changed, revoked.
+    # Never its token or password — only whether it has one.
+    DOWNLOAD_LINK_CREATE = "download_link_create"
+    DOWNLOAD_LINK_UPDATE = "download_link_update"
+    DOWNLOAD_LINK_REVOKE = "download_link_revoke"
 
 
 def record(

backend/app/downloads/links.py

@@ -1,10 +1,14 @@
 """Public "share by link" helpers for the download center.
 
-A DownloadLink is a capability URL: the unguessable `token` grants anyone read access to one
-download's file on the login-free `/watch/{token}` page. Password-protected links additionally
-require a short-lived signed **grant** on the file request — because a `<video src>` can't send a
-header, the password is exchanged once at `/unlock` for an HMAC grant appended to the file URL,
-so the raw password never rides in the media URL (or server logs).
+A DownloadLink is a capability URL: the unguessable token grants anyone read access to one
+download's file on the login-free `/watch/{token}` page. So the token is never stored as written:
+the link is found by its SHA-256, and the owner's copy is Fernet-encrypted — a database copy alone
+opens nothing. Without that copy (no TOKEN_ENCRYPTION_KEY, or a key since changed) the link still
+opens; only its address cannot be shown again, and the owner makes a new link to share.
+
+Password-protected links additionally require a short-lived signed **grant** on the file request —
+because a `<video src>` can't send a header, the password is exchanged once at `/unlock` for an HMAC
+grant appended to the file URL, so the raw password never rides in the media URL (or server logs).
 """
 
 import hashlib
@@ -12,6 +16,10 @@ import hmac
 import secrets
 from datetime import datetime, timezone
 
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app import security
 from app.config import settings
 from app.models import DownloadLink
 
@@ -22,6 +30,24 @@ def new_token() -> str:
     return secrets.token_urlsafe(24)  # ~32 chars, 192 bits
 
 
+def seal(link: DownloadLink, token: str) -> None:
+    """Store `token` on `link` the only ways it is kept: its hash, and its encrypted copy."""
+    link.token_hash = security.hash_token(token)
+    link.token_enc = security.encrypt(token) if security.can_encrypt() else None
+
+
+def find(db: Session, token: str) -> DownloadLink | None:
+    """The link a `/watch` token names, by its hash."""
+    return db.execute(
+        select(DownloadLink).where(DownloadLink.token_hash == security.hash_token(token))
+    ).scalar_one_or_none()
+
+
+def recover(link: DownloadLink) -> str | None:
+    """The link's token from its encrypted copy, or None when there is none this key can read."""
+    return security.decrypt_optional(link.token_enc)
+
+
 def is_expired(link: DownloadLink) -> bool:
     return link.expires_at is not None and link.expires_at <= datetime.now(timezone.utc)
 
@@ -61,12 +87,14 @@ def check_grant(token: str, grant: str | None, password_version: int) -> bool:
 # --- serialization -------------------------------------------------------------------------
 
 
-def owner_view(link: DownloadLink, base_url: str = "") -> dict:
-    """What the file owner sees when managing their links."""
+def owner_view(link: DownloadLink, base_url: str = "", token: str | None = None) -> dict:
+    """What the file owner sees when managing their links. `token` is the one just made (it is in
+    hand even where no copy is kept); else it is read back, and `url` is None when it cannot be."""
+    token = token or recover(link)
     return {
         "id": link.id,
-        "token": link.token,
-        "url": f"{base_url}/watch/{link.token}",
+        "token": token,
+        "url": f"{base_url}/watch/{token}" if token else None,
         "allow_download": link.allow_download,
         "has_password": link.password_hash is not None,
         "expires_at": link.expires_at.isoformat() if link.expires_at else None,

backend/app/downloads/og.py

@@ -11,13 +11,12 @@ import html
 import re
 from pathlib import Path
 
-from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.config import settings
 from app.downloads import links as linksmod
 from app.downloads import storage
-from app.models import DownloadJob, DownloadLink, MediaAsset
+from app.models import DownloadJob, MediaAsset
 
 _OG_BLOCK = re.compile(r"<!--OG:START-->.*?<!--OG:END-->", re.DOTALL)
 
@@ -74,7 +73,7 @@ def _jpeg_size(path: Path) -> tuple[int, int] | None:
 
 def _watch_tags(token: str, db: Session) -> str | None:
     """Build the OG/Twitter meta block for a watch token, or None to keep the generic card."""
-    link = db.execute(select(DownloadLink).where(DownloadLink.token == token)).scalar_one_or_none()
+    link = linksmod.find(db, token)
     if link is None or linksmod.is_expired(link):
         return None
     url = f"{settings.app_base}/watch/{token}"

backend/app/models.py

@@ -1131,8 +1131,10 @@ class DownloadQuota(Base, UpdatedAtMixin):
 class DownloadLink(Base, TimestampMixin):
     """A public capability link to one download — the "share by link" surface.
 
-    Anyone holding the unguessable `token` can watch the file on the login-free `/watch/{token}`
-    player page (Google-Drive style). Optional per-link controls: `expires_at`, `allow_download`
+    Anyone holding the unguessable token can watch the file on the login-free `/watch/{token}`
+    player page (Google-Drive style). The token itself is never stored as written: a link is found
+    by its SHA-256 (`token_hash`), and `token_enc` is the Fernet-encrypted copy its owner copies the
+    link from again — absent without a key (`downloads/links.py`). Optional per-link controls: `expires_at`, `allow_download`
     (stream-only vs downloadable), and a `password_hash` (argon2, like a user password). Revoke =
     delete the row. Distinct from `DownloadShare`, which grants a *registered* user access via the
     in-app "Shared with me" list."""
@@ -1143,7 +1145,8 @@ class DownloadLink(Base, TimestampMixin):
     job_id: Mapped[int] = mapped_column(
         ForeignKey("download_jobs.id", ondelete="CASCADE"), index=True
     )
-    token: Mapped[str] = mapped_column(String(64), unique=True)
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True)
+    token_enc: Mapped[str | None] = mapped_column(Text)  # Fernet ciphertext — never returned/logged
     created_by: Mapped[int | None] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
     allow_download: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
     password_hash: Mapped[str | None] = mapped_column(Text)

backend/app/routes/downloads.py

@@ -62,6 +62,7 @@ from app.routes.files import (
 )
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
+from app.utils import iso
 from app.refusal import refused
 
 router = APIRouter(prefix="/api/downloads", tags=["downloads"])
@@ -769,18 +770,37 @@ def create_link(
     if job.status != JobStatus.DONE or job.asset_id is None:
         raise refused(409, "share_unfinished")
     pw = body.password.strip()
+    token = linksmod.new_token()
     link = DownloadLink(
         job_id=job_id,
-        token=linksmod.new_token(),
         created_by=user.id,
         allow_download=body.allow_download,
         password_hash=hash_password(pw) if pw else None,
         expires_at=_link_expiry(body.expires_days),
     )
+    linksmod.seal(link, token)
     db.add(link)
+    db.flush()
+    audit.record(
+        db,
+        user.id,
+        audit.AuditAction.DOWNLOAD_LINK_CREATE,
+        target_type="download_link",
+        target_id=link.id,
+        after={"job_id": job_id, **_link_audit(link)},
+    )
     db.commit()
     db.refresh(link)
-    return linksmod.owner_view(link)
+    return linksmod.owner_view(link, token=token)
+
+
+def _link_audit(link: DownloadLink) -> dict:
+    """A link's settings as the audit records them: whether it has a password, never which."""
+    return {
+        "allow_download": link.allow_download,
+        "has_password": link.password_hash is not None,
+        "expires_at": iso(link.expires_at),
+    }
 
 
 class UpdateLinkIn(BaseModel):
@@ -797,6 +817,7 @@ def update_link(
     db: Session = Depends(get_db),
 ) -> dict:
     link = _own_link(db, user, link_id)
+    before = _link_audit(link)
     sent = body.model_fields_set
     if "allow_download" in sent:
         link.allow_download = bool(body.allow_download)
@@ -808,6 +829,17 @@ def update_link(
         # Bump the version so any grant issued under the previous password stops working now, rather
         # than living out its 6h TTL (setting/clearing/changing the password all count as a rotation).
         link.password_version += 1
+    after = _link_audit(link)
+    if after != before or "password" in sent:
+        audit.record(
+            db,
+            user.id,
+            audit.AuditAction.DOWNLOAD_LINK_UPDATE,
+            target_type="download_link",
+            target_id=link_id,
+            before=before,
+            after=after,
+        )
     db.commit()
     return linksmod.owner_view(link)
 
@@ -818,8 +850,16 @@ def revoke_link(
 ) -> dict:
     link = _own_link(db, user, link_id)
     db.delete(link)
+    audit.record(
+        db,
+        user.id,
+        audit.AuditAction.DOWNLOAD_LINK_REVOKE,
+        target_type="download_link",
+        target_id=link_id,
+        after={"job_id": link.job_id},
+    )
     db.commit()
-    return {"deleted": link_id}
+    return {"ok": True, "deleted": link_id}
 
 
 # --- admin ---------------------------------------------------------------------------------

backend/app/routes/public.py

@@ -9,7 +9,6 @@ a short-lived signed grant that the media URL carries (a `<video src>` can't sen
 from fastapi import APIRouter, Depends, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel
-from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.config import settings
@@ -38,7 +37,7 @@ _unlock_failures = RateLimiter(max_events=50, window_seconds=300)
 
 
 def _link_or_404(db: Session, token: str) -> DownloadLink:
-    link = db.execute(select(DownloadLink).where(DownloadLink.token == token)).scalar_one_or_none()
+    link = linksmod.find(db, token)
     if link is None or linksmod.is_expired(link):
         raise refused(404, "link_gone")
     return link

backend/app/security.py

@@ -46,6 +46,12 @@ _fernet: Fernet | None = (
 )
 
 
+def can_encrypt() -> bool:
+    """Whether a value can be stored encrypted here: TOKEN_ENCRYPTION_KEY is set. Production
+    refuses to start without it (`config`); a local box may run without one."""
+    return _fernet is not None
+
+
 def _require_fernet() -> Fernet:
     if _fernet is None:
         raise RuntimeError("TOKEN_ENCRYPTION_KEY is not configured")