deploy: labeling server

labeling/static/app.js

@@ -4,6 +4,7 @@ const AXES = ["art_style", "color", "art_medium", "lighting"];
 const TOKEN_STORAGE_KEY = "aamcq_token";
 const THEME_STORAGE_KEY = "aamcq_theme";
 const ROUNDS_KEY = "aamcq_rounds_done";
+const PASSWORD_SESSION_KEY = "aamcq_access_password";
 const FIRST_SESSION_CAP = 20;
 const REPEAT_SESSION_CAP = 10;
 
@@ -53,13 +54,38 @@ function nextSessionCap() {
   return rounds === 0 ? FIRST_SESSION_CAP : REPEAT_SESSION_CAP;
 }
 
+async function attemptRegister(cap, password) {
+  const params = new URLSearchParams({ cap: String(cap) });
+  if (password) params.set("password", password);
+  return fetch(`/api/register?${params.toString()}`, { method: "POST" });
+}
+
 async function registerFresh(cap) {
-  const resp = await fetch(`/api/register?cap=${cap}`, { method: "POST" });
+  // Try with whatever password we have cached (could be empty).
+  let password = sessionStorage.getItem(PASSWORD_SESSION_KEY) || "";
+  let resp = await attemptRegister(cap, password);
+
+  // 403 means server wants a password — prompt (and re-prompt on mismatch).
+  while (resp.status === 403) {
+    sessionStorage.removeItem(PASSWORD_SESSION_KEY);
+    const entered = window.prompt(
+      password
+        ? "Wrong access password. Try again:"
+        : "Enter the access password to start labeling:"
+    );
+    if (entered == null) {
+      throw new Error("Access password required.");
+    }
+    password = entered;
+    resp = await attemptRegister(cap, password);
+  }
+
   if (!resp.ok) {
     throw new Error(
       "No ?token= in URL and anonymous registration is disabled on this server."
     );
   }
+  if (password) sessionStorage.setItem(PASSWORD_SESSION_KEY, password);
   const { token } = await resp.json();
   localStorage.setItem(TOKEN_STORAGE_KEY, token);
   return token;

labeling/static/index.html

@@ -41,6 +41,6 @@
       <span id="error"></span>
     </footer>
   </main>
-  <script src="/app.js?v=10"></script>
+  <script src="/app.js?v=11"></script>
 </body>
 </html>

spaces/space_entry.py

@@ -14,6 +14,7 @@ Env vars:
   AAMCQ_PER_ANNOTATOR_CAP    default: 20
   AAMCQ_LABELS_PER_ITEM      default: 3
   AAMCQ_BACKUP_INTERVAL      default: 60 (seconds)
+  AAMCQ_ACCESS_PASSWORD      optional; if set, /api/register requires it
 """
 
 from __future__ import annotations
@@ -41,6 +42,7 @@ MCQ_PATH = DATA_DIR / "mcq_unlabeled.jsonl"
 BACKUP_INTERVAL = int(os.environ.get("AAMCQ_BACKUP_INTERVAL", "60"))
 PER_ANNOTATOR_CAP = int(os.environ.get("AAMCQ_PER_ANNOTATOR_CAP", "20"))
 LABELS_PER_ITEM = int(os.environ.get("AAMCQ_LABELS_PER_ITEM", "3"))
+ACCESS_PASSWORD = os.environ.get("AAMCQ_ACCESS_PASSWORD") or None
 
 
 def _require_token() -> str:
@@ -141,7 +143,12 @@ def main() -> int:
         anonymous_register=True,
         max_labels_per_item=LABELS_PER_ITEM,
         max_labels_per_annotator=PER_ANNOTATOR_CAP,
+        access_password=ACCESS_PASSWORD,
     )
+    if ACCESS_PASSWORD:
+        print("access password gate: ON")
+    else:
+        print("access password gate: OFF (set AAMCQ_ACCESS_PASSWORD to enable)")
 
     @app.on_event("startup")
     async def _start_backup() -> None:

src/aamcq/annotation/api.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hmac
 import os
 import sqlite3
 from pathlib import Path
@@ -41,6 +42,7 @@ def create_app(
     anonymous_register: bool = False,
     max_labels_per_item: int = 3,
     max_labels_per_annotator: int | None = None,
+    access_password: str | None = None,
 ) -> FastAPI:
     """Labeling server.
 
@@ -58,6 +60,10 @@ def create_app(
     + token on demand, so a single public URL can serve any number of
     concurrent anonymous annotators (each browser session = one annotator).
     Intended for public-URL crowdsourcing.
+
+    `access_password`: if set, `/api/register` requires a matching
+    `?password=` query param (constant-time compared). Cheap anti-spam
+    gate for public Spaces — existing tokens keep working regardless.
     """
     db_path = Path(db_path or DEFAULT_DB)
     image_dir = Path(image_dir or DEFAULT_IMAGE_DIR)
@@ -72,6 +78,7 @@ def create_app(
     app.state.anonymous_register = anonymous_register
     app.state.max_labels_per_item = max_labels_per_item
     app.state.max_labels_per_annotator = max_labels_per_annotator
+    app.state.access_password = access_password
 
     def get_conn() -> sqlite3.Connection:
         return app.state.conn
@@ -111,6 +118,7 @@ def create_app(
     @app.post("/api/register")
     def api_register(
         cap: int | None = Query(default=None, ge=1, le=10000),
+        password: str | None = Query(default=None, max_length=256),
         conn: sqlite3.Connection = Depends(get_conn),
     ):
         """Mint a fresh anonymous annotator. Only enabled when anonymous_register.
@@ -118,9 +126,16 @@ def create_app(
         Optional `?cap=N` sets a per-annotator label cap that overrides the
         server default (used by the frontend to give the first session a
         larger quota than subsequent ones).
+
+        If `access_password` was set at startup, `?password=` must match
+        (constant-time compared) or we return 403.
         """
         if not app.state.anonymous_register:
             raise HTTPException(status_code=404, detail="anonymous register disabled")
+        expected = app.state.access_password
+        if expected:
+            if not password or not hmac.compare_digest(password, expected):
+                raise HTTPException(status_code=403, detail="wrong access password")
         existing = {row["annotator_id"] for row in conn.execute(
             "SELECT annotator_id FROM annotators"
         )}