24 lines
2.4 KiB
Markdown
24 lines
2.4 KiB
Markdown
# 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.
|