truf-server/openspec/changes/add-minimal-remote-scan-workers/proposal.md

Why

Truf needs to use trusted Windows and Linux machines for download/scan work without rewriting its already-debugged parser, queue, error policy, ingestion, or detailed keychecks. A separate source-only workspace and an empty, isolated local test environment let us develop this boundary without copying the large production database or touching the active runtime.

What Changes

• Add a thin authenticated HTTPS adapter around existing target reservation and canonical .trb result handoff, not a second task system.
• Keep PostgreSQL, discovery, scheduling, ingestion, projection, and detailed keycheck in one server Docker runtime; use a separate Caddy edge.
• Run existing download/scan logic on trusted clients. The server supplies the task, immutable plan, and required source/scanner settings; the client config contains server URL, device token, and desired execution slots.
• Claim one task per free client slot, subject to an atomic server-side per-user cap across devices and existing admission/backpressure rules.
• Use a configurable fixed assignment lifetime, default 24 hours, with periodic expiry recovery and no worker heartbeat. Preserve existing retry/error decisions, allow the same worker to reclaim work, fence stale assignments, and acknowledge result retries idempotently.
• Expose only the authenticated Worker API and a long-random-path authenticated admin area. Keep the standalone dashboard and backend/control/database ports private; ban admin IPs for 24 hours after two actual failed login attempts within ten minutes without banning Worker API traffic.
• Reuse existing records/logs for worker counts, durations, assignment outcomes, and last API contact.
• Validate with empty local storage and synthetic fixtures, including crash/retry/expiry scenarios, without production data or real provider requests.

Capabilities

New Capabilities

• distributed-scan-workers: Minimal remote scan execution, centralized settings, admission, fixed expiry, durable result handoff, observability, and isolated local verification.
• restricted-public-access: Private backend/dashboard topology, authenticated worker/admin access, admin-only login bans, and safe diagnostics.

Modified Capabilities

None. openspec/specs/ is empty in this snapshot. Existing unarchived deltas are design references, not canonical specifications to modify or archive as part of this work.

Impact

The change touches the execution boundary in app/console_runner.py and app/scanner.py, reservation/recovery in app/scanner_db.py, the existing bundle/ingester pipeline, runtime lifecycle wiring, packaging, Docker/Caddy deployment, and regression tests. New persistent state is limited to necessary worker identity/token/quota bindings and metadata attached to existing reservations; PostgreSQL remains the only server queue authority. Client detailed keychecks, another broker, a parallel result format, worker heartbeats, automatic updates, and production migration are out of scope.