Support explicit local, OIDC, and built-in authentication modes

[DenWin]

Tracked by #9. Related to #19, #28, #30, #33, and #40.

Problem

The current authentication behavior treats email/password login as the primary path even for a single-user instance published only on 127.0.0.1. That adds unnecessary friction locally, while the existing ALLOW_UNAUTHENTICATED behavior does not clearly express or enforce the deployment trust boundary.

Authenticated users also receive a seven-day JWT cookie whose signing secret defaults to randomUUID() at application startup. When JWT_SECRET is unset, every restart changes the secret and invalidates existing sessions.

Browser authentication and machine/AI-agent authorization are different security concerns. Claude, Codex, MCP clients, scripts, and other automation must not reuse a browser password or session cookie.

Goal

Introduce explicit authentication modes appropriate for local-only, LAN, and future internet-facing deployments while preserving a secure compatibility path and durable, revocable sessions.

Proposed modes

AUTH_MODE=local

For an explicitly configured, single-user instance published only on loopback:

• Skip setup and login screens.
• Use one stable local identity so history and ownership survive container restarts.
• Disable account registration and password-authentication endpoints.
• Keep browser cookies bounded, HttpOnly, and SameSite=Strict.
• Document and prominently warn that the Docker port must be bound to loopback, for example 127.0.0.1:3000:3000.
• Do not infer safety solely from the source address observed inside the container; Docker networking and reverse proxies obscure the external publication boundary.
• Fail closed, or require a separate explicit unsafe override, when configuration indicates a non-loopback deployment.

AUTH_MODE=oidc

For LAN and future public deployments:

• Delegate interactive authentication to a standards-based OIDC provider.
• Prefer Authorization Code with PKCE.
• Validate issuer, audience, signature, expiry, nonce, and redirect URI.
• Define trusted-proxy behavior explicitly; never accept identity headers from arbitrary clients.
• Map the external subject to a stable internal user identity.
• Preserve logout, session expiry, revocation behavior, and account ownership rules.
• Require HTTPS except for standards-permitted loopback development callbacks.

OIDC may initially be implemented through a trusted authentication proxy, provided the proxy trust boundary and direct-backend exposure are documented and tested.

AUTH_MODE=builtin

Compatibility mode for the existing email/password workflow:

• Preserve explicit administrator-controlled JWT_SECRET support.
• When JWT_SECRET is unset, generate a strong signing secret once and persist it in the application data volume.
• Reuse the persisted secret after restarts.
• Never expose the secret in logs, responses, image layers, or source-controlled files.
• Use restrictive filesystem permissions where supported.
• Preserve bounded expiry, explicit logout, and deliberate secret rotation.
• Consider configurable session duration or “remember this device”; do not create unlimited sessions.

Configuration safety

• Authentication mode must be explicit; avoid silently changing modes from incidental network observations.
• Define a safe migration from the existing ALLOW_UNAUTHENTICATED setting and eventually deprecate it.
• Reject incompatible combinations such as local mode with account registration.
• Document behavior behind reverse proxies and when HTTP_ALLOWED is enabled.
• Multiple replicas must use a shared session store or common signing/verification keys.
• Persisted local identity and signing material survive only when the configured data volume survives.
• Backups containing authentication material must be treated as secrets.

Agent and automation boundary

This issue does not make browser sessions an agent API.

• Do not give agents the built-in user password.
• Do not export or reuse browser JWT cookies.
• Design agent access separately as a narrow API or MCP interface.
• Prefer local MCP over stdio for same-host Claude/Codex access.
• Require scoped, short-lived OAuth tokens for remote MCP/API access.
• Use client credentials only for explicitly trusted unattended automation.
• Define granular permissions such as conversion discovery, create, status, cancel, result download, and history access.

A separate issue should specify the agent/MCP interface, scopes, filesystem boundaries, user consent, rate/resource limits, audit events, and remote OAuth behavior.

TDD and characterization requirements

Before refactoring:

• Characterize the current setup, login, logout, cookie, ALLOW_UNAUTHENTICATED, restart, and ownership behavior under Characterize authentication, authorization, and account lifecycle #19.
• Add tests proving the current behavior at the HTTP boundary.

For each new mode:

1. Add failing tests for the intended mode and unsafe configuration combinations.
2. Implement the smallest mode-specific behavior.
3. Add integration tests across process/container restarts.
4. Add browser tests for redirects, login bypass, logout, expiry, and error states.
5. Add deployment tests showing local mode is reachable through the documented loopback mapping and is not published by the supported Compose configuration on external interfaces.

Acceptance criteria

• An ADR records the authentication modes, trust boundaries, rejected alternatives, and migration strategy.
• AUTH_MODE=local provides login-free access with a stable local identity across restarts.
• The supported local Compose example publishes only to 127.0.0.1.
• Local mode disables password and registration endpoints and rejects unsafe configuration combinations.
• AUTH_MODE=builtin preserves sessions across container recreation with the same data volume.
• Built-in sessions remain bounded; logout, expiry, and key rotation invalidate them predictably.
• AUTH_MODE=oidc validates identity and tokens correctly, or the first increment documents and verifies a trusted-proxy OIDC boundary.
• Direct access cannot spoof trusted-proxy identity headers.
• Migration from ALLOW_UNAUTHENTICATED is documented and tested.
• Browser authentication artifacts are not accepted as the planned agent-authentication contract.
• Unit, integration, restart, browser, negative-security, and supported-deployment tests pass.
• README and operations documentation explain localhost, LAN, reverse-proxy, future public-hosting, backup, rotation, and recovery implications.

Out of scope

• Implementing the converter API or MCP tool surface.
• Teaching agents to automate the HTML UI.
• Treating a LAN as inherently trusted.
• Supporting anonymous public internet access.

[DenWin]

Testing requirement

Implementation of this issue must follow the red-green-refactor workflow and provide the applicable unit, integration, browser, and real-world evidence defined in #16. Completion requires behavior-level tests and assessment results, not only working production code.