Phase 2 W3b — HF reverse proxy (SEC-02 / INVARIANT 2)

api/openapi.yaml

@@ -67,7 +67,7 @@
 paths:
   # ========== Tasks ==========
   /tasks:
     get:
       tags: [tasks]
       summary: List tasks
       operationId: listTasks
@@ -90,7 +90,7 @@
         '401': {$ref: '#/components/responses/Unauthenticated'}
         '429': {$ref: '#/components/responses/RateLimited'}
 
     post:
       tags: [tasks]
       summary: Create download task
       operationId: createTask
@@ -191,7 +191,7 @@
     parameters:
       - $ref: '#/components/parameters/TaskId'
 
     get:
       tags: [tasks]
       summary: Get task by ID
       operationId: getTask
@@ -202,7 +202,7 @@
             application/json:
               schema: {$ref: '#/components/schemas/DownloadTask'}
 
     patch:
       tags: [tasks]
       summary: Update task (priority only)
       operationId: updateTask
@@ -224,7 +224,7 @@
   /tasks/{taskId}/cancel:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     post:
       tags: [tasks]
       summary: Cancel task (async)
       operationId: cancelTask
@@ -250,7 +250,7 @@
   /tasks/{taskId}/retry:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     post:
       tags: [tasks]
       summary: Retry failed subtasks
       operationId: retrySubtasks
@@ -296,7 +296,7 @@
   /tasks/{taskId}/upgrade:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     post:
       tags: [tasks]
       summary: Upgrade to new revision (incremental)
       operationId: upgradeTask
@@ -320,7 +320,7 @@
   /tasks/{taskId}/subtasks:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     get:
       tags: [subtasks]
       summary: List subtasks of a task
       operationId: listSubtasks
@@ -343,7 +343,7 @@
   /tasks/{taskId}/source-allocation:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     get:
       tags: [tasks]
       summary: View source allocation (multi-source visualization)
       operationId: getSourceAllocation
@@ -357,7 +357,7 @@
   /tasks/{taskId}/events:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     get:
       tags: [tasks]
       summary: Task event log
       operationId: getTaskEvents
@@ -730,6 +730,62 @@
                           got:
                             type: integer
 
+  /hf-proxy/subtask/{subtaskId}:
+    get:
+      tags: [executors]
+      summary: HF reverse proxy — stream a subtask's file from HF
+      description: >-
+        Controller-side reverse proxy. Authenticates the executor (mTLS + JWT),
+        verifies subtask ownership (assignment_token + epoch fence), reconstructs
+        the HF URL from the subtask row, injects the tenant HF token, and streams
+        the bytes back. The executor never holds the HF token (INVARIANT 2).
+      operationId: hfProxySubtask
+      parameters:
+        - name: subtaskId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: X-Assignment-Token
+          in: header
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: Range
+          in: header
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Full file stream.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '206':
+          description: Partial content (Range request).
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '401':
+          description: Missing or invalid mTLS / executor JWT.
+        '403':
+          description: NOT_YOUR_SUBTASK — authenticated executor does not own this subtask.
+        '404':
+          description: Subtask not found.
+        '409':
+          description: STALE_ASSIGNMENT or EPOCH_MISMATCH (fence-token mismatch).
+        '429':
+          description: Forwarded from HF — rate limited.
+        '503':
+          description: Forwarded from HF — upstream unavailable.
+
   /executors/{executorId}/subtasks/{subtaskId}/complete:
     parameters:
       - in: path

docs/operator/executor-runbook.md

@@ -86,3 +86,29 @@ anyone can forge the header. Default is `0` (direct uvicorn TLS only).
 
 Heartbeats carry an HMAC timestamp validated within ±5 min. Run
 `chrony` / `systemd-timesyncd` on all executor + controller hosts.
+
+## W3b — HF access via the controller reverse proxy
+
+As of Phase 2 W3b, executors no longer talk to huggingface.co directly. All
+HF file downloads flow through the controller's reverse proxy
+(`GET /api/v1/hf-proxy/subtask/{id}`), which injects the tenant HF token
+server-side (INVARIANT 2 — the token never leaves the controller).
+
+**Removed executor environment variables** (delete them from `.env.executor`
+and any deployment manifests — they are now ignored):
+
+- `DLW_EXECUTOR_HF_TOKEN`
+- `DLW_EXECUTOR_HF_ENDPOINT`
+
+**Controller environment variables:**
+
+- `DLW_HF_TOKEN` — the tenant HF token (already used by the controller for
+  repo-metadata enumeration; W3b also uses it for the download proxy).
+- `DLW_HF_ENDPOINT` — defaults to `https://huggingface.co`.
+- `DLW_HF_PROXY_TIMEOUT_SECONDS` — per-request timeout for the proxy's HF
+  fetch (default 300, range 10–3600).
+
+**Operational tradeoff:** download bandwidth now flows through the controller
+rather than executor→HF directly. For the internal beta this is acceptable;
+global rate-limit coordination and an executor-local credential pool are
+Phase 3 items.