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.
2026-10-14 18:40:23 +02:00
parent c335d54929
commit b2d34e6e6c
18 changed files with 1080 additions and 48 deletions
@@ -0,0 +1,94 @@
+"""Machine access to the Files library: API tokens bound to folders, and the Hub folder
+
+Revision ID: 0106_api_tokens
+Revises: 0105_job_source_key
+Create Date: 2026-10-14
+
+`api_tokens` is a user's token for a machine (a script, the hub): only its SHA-256 is kept, plus the
+first characters to recognise it by. `api_token_grants` says what it may do in which folder — list,
+read, write, delete — so a token reaches nothing it was not given, folder by folder.
+
+A third folder kind, `hub`: the one folder a user exchanges files with their hub machine through.
+Like a source folder its name is the client's to render; like an own folder a file may be moved in.
+One per user.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0106_api_tokens"
+down_revision: str | None = "0105_job_source_key"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+_KIND_OLD = (
+    "(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)"
+)
+_KIND_NEW = _KIND_OLD + " OR (kind = 'hub' AND name IS NULL AND source_key IS NULL)"
+
+
+def upgrade() -> None:
+    op.drop_constraint("ck_file_folder_kind", "file_folders", type_="check")
+    op.create_check_constraint("ck_file_folder_kind", "file_folders", _KIND_NEW)
+    op.create_index(
+        "uq_file_folder_hub",
+        "file_folders",
+        ["user_id"],
+        unique=True,
+        postgresql_where=sa.text("kind = 'hub'"),
+    )
+    op.create_table(
+        "api_tokens",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+            index=True,
+        ),
+        sa.Column("name", sa.String(80), nullable=False),
+        sa.Column("prefix", sa.String(16), nullable=False),
+        sa.Column("token_hash", sa.String(64), nullable=False, unique=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True)),
+        sa.Column("last_used_at", sa.DateTime(timezone=True)),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+        ),
+    )
+    op.create_table(
+        "api_token_grants",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "token_id",
+            sa.Integer(),
+            sa.ForeignKey("api_tokens.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "folder_id",
+            sa.Integer(),
+            sa.ForeignKey("file_folders.id", ondelete="CASCADE"),
+            nullable=False,
+            index=True,
+        ),
+        sa.Column("can_list", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("can_read", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("can_write", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("can_delete", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.UniqueConstraint("token_id", "folder_id", name="uq_api_token_grant"),
+        sa.CheckConstraint(
+            "can_list OR can_read OR can_write OR can_delete", name="ck_api_token_grant_some"
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("api_token_grants")
+    op.drop_table("api_tokens")
+    op.drop_index("uq_file_folder_hub", table_name="file_folders")
+    # A Hub folder may hold files (their foreign key RESTRICTs a delete): it becomes an own folder.
+    op.execute("UPDATE file_folders SET kind = 'own', name = 'Hub ' || id WHERE kind = 'hub'")
+    op.drop_constraint("ck_file_folder_kind", "file_folders", type_="check")
+    op.create_check_constraint("ck_file_folder_kind", "file_folders", _KIND_OLD)