truf-server/openspec/changes/add-minimal-remote-scan-workers/specs/restricted-public-access/spec.md

ADDED Requirements

Requirement: Only authenticated edge routes are public

The deployment SHALL expose HTTPS through Caddy only for /api/v1/worker/* and a configured random administrative prefix. The standalone dashboard, PostgreSQL, supervisor control, Caddy control API, and raw backend ports SHALL remain private. Unknown application paths SHALL return 404; an administrative URL MUST NOT replace authentication.

Scenario: Internet visitor requests backend or dashboard access

• WHEN an unauthenticated visitor requests /dashboard, a normal /admin path, an unknown route, or a backend/control/database port
• THEN no dashboard data or backend/control access is available

Scenario: Dashboard information appears inside admin

• WHEN operational dashboard information is rendered in the administrative area
• THEN every page, asset, and data request is protected by the same admin authentication boundary without publishing the standalone backend

Requirement: Worker access has narrow device-scoped authority

Every Worker API operation SHALL require a valid revocable opaque device token over certificate-validated HTTPS, scoped to its user/device assignments and quotas. The server SHALL store token hashes, not reusable plaintext tokens. Worker tokens MUST NOT authorize admin actions, another device's result mutation, database access, or generic commands.

Scenario: Invalid or revoked token submits work

• WHEN an invalid/revoked device token claims a task or uploads a result
• THEN the request is refused before task/result mutation and does not count toward the admin login jail

Scenario: Authorized device tries to finish somebody else's task

• WHEN a device submits another device's reservation identity
• THEN the request is refused without changing that reservation or disclosing task credentials

Requirement: Admin routes require credentials and safe mutations

The administrative prefix SHALL contain at least 128 bits of randomness and all administrative routes SHALL require login/password authentication using a supported password hash. Typed mutations SHALL enforce appropriate Origin/CSRF protection. The interface MUST NOT expose a shell or generic supervisor-command passthrough.

Scenario: Visitor knows the full administrative URL

• WHEN a visitor accesses the correct administrative prefix without valid credentials
• THEN no administrative page, data, asset, or mutation becomes available

Scenario: Cross-site request attempts a queue or token mutation

• WHEN a browser submits an administrative mutation without valid same-origin/CSRF authorization
• THEN the mutation is rejected even if browser-level password authentication is present

Requirement: Two failed admin logins trigger an admin-only day ban

Two actual invalid administrative credential submissions from one IP within ten minutes SHALL ban that IP from administrative routes for 24 hours. The ban SHALL persist across service restart, expire automatically, and support SSH/operator removal. Initial unauthenticated authentication challenges, Worker API failures, and unrelated requests MUST NOT count. Enforcement SHALL leave Worker API traffic from the same IP unaffected.

Scenario: Repeated invalid admin credentials

• WHEN an IP submits a second invalid admin login within the ten-minute window
• THEN subsequent admin requests from that IP are denied for 24 hours, including otherwise valid credentials, until expiry or operator unban

Scenario: Admin and worker share one NAT address

• WHEN admin login failures trigger a ban for an IP also used by an authorized worker
• THEN the worker can still claim/upload over HTTPS and administrative requests remain blocked

Scenario: Normal first visit receives an authentication challenge

• WHEN a browser initially requests the protected area without sending credentials
• THEN the normal challenge does not consume either of the two failed-login attempts

Scenario: Ban expires or operator recovers access

• WHEN 24 hours elapse or an operator removes the ban through the documented SSH procedure
• THEN credential-authenticated administrative access is restored without restarting or weakening Worker API authorization

Requirement: IP identification and ban enforcement match the deployed edge

The initial direct-DNS deployment SHALL derive client IP from the direct connection, ignoring untrusted forwarded headers. Any future proxy SHALL require an explicit trusted-proxy configuration and verification before enabling IP bans. The fail2ban action SHALL enforce the admin route boundary at Caddy rather than indiscriminately blocking shared port 443.

Scenario: Attacker supplies another address in a forwarded header

• WHEN a direct client sends arbitrary X-Forwarded-For or equivalent headers with failed admin credentials
• THEN another user's address is not selected for banning and the caller cannot evade its own ban

Scenario: Deployed ban is verified through Docker ingress

• WHEN the admin jail applies its ban against the actual Caddy/Docker topology
• THEN external administrative requests are denied and worker requests remain available, not merely a host firewall rule being present

Requirement: Diagnostics and transport protect sensitive data

All worker/admin transport SHALL use HTTPS without disabling certificate verification. Tokens, passwords, secret admin prefixes in routine access logs, task credentials, and raw findings SHALL be redacted or omitted from diagnostics. Admin responses SHALL disable caching and referrer disclosure and use a compatible restrictive CSP; production HTTPS SHALL use HSTS. Client disk/workspace encryption SHALL NOT be required.

Scenario: Auth or upload error is logged

• WHEN authentication, payload validation, or upload handling fails
• THEN logs contain only safe correlation/status/error metadata and enough redacted authentication outcome for the admin jail, not request credentials or raw result content

Scenario: Trusted client stores pending work locally

• WHEN a worker downloads or persists a bundle before acknowledgement
• THEN ordinary local storage is supported without an application encryption layer while HTTPS and post-acknowledgement cleanup remain enforced