Initial server source import

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

@@ -0,0 +1,75 @@
+## 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