newdrive/docs/adr/0010-authentication-primitives.md

ADR-0010: Authentication primitives and browser session policy

Status: Accepted

Context

The architecture baseline requires Argon2id password hashing, revocable server-side sessions, secure cookie authentication, and CSRF protection. Phase 1 needs concrete parameters and token handling rules before owner setup and login can be implemented consistently.

Decision

• Passwords are encoded in the standard Argon2id PHC string format with the algorithm version and cost parameters embedded in every hash.
• New hashes use Argon2id version 19 with 64 MiB of memory, three iterations, four lanes, a 16-byte random salt, and a 32-byte derived key. Verification rejects malformed or unreasonable encoded parameters before allocating memory. Parameters may be raised later without invalidating stored hashes.
• golang.org/x/crypto/argon2 is the only new cryptographic runtime dependency. Drive owns the small PHC encoder/parser around it rather than adding another wrapper library.
• Session and CSRF secrets are independent 256-bit values from crypto/rand. PostgreSQL stores only SHA-256 digests. Plain session secrets exist only in the secure cookie and the request that creates it.
• Browser sessions use Secure, HttpOnly, SameSite=Strict, host-only cookies. The CSRF companion cookie is deliberately readable by browser code and its value must match the X-CSRF-Token header and the digest stored with the authenticated session.
• Session cookies use the __Host- prefix and Path=/, so insecure direct-HTTP browser authentication is not supported. Development authentication uses HTTPS through the configured reverse proxy or direct API tests.
• Session lifetime is 30 days. Revocation is authoritative in PostgreSQL; no browser JWT is introduced.
• First-run setup creates the owner, root node, attributed initial change event, audit event, recovery codes, and first session in one PostgreSQL transaction. The existing single-owner unique constraint decides concurrent setup attempts, making setup a single-winner operation.

Consequences

• The implementation follows the baseline without inventing a second credential mechanism.
• Authentication consumes bounded memory per verification. Persistent rate limiting and trusted-proxy client-address handling remain required Phase 1 follow-up work before production exposure.
• Browsers must reach Drive over HTTPS for setup and login. This matches the intended Nginx Proxy Manager deployment.