feat(02): GREEN — argon2id Hash + Verify + self-test

- Add Params struct with Memory/Iterations/Parallelism/SaltLength/KeyLength
- DefaultParams: OWASP 2024 baseline (m=64KiB, t=1, p=4, salt=16B, key=32B) — D-08
- TestParams: reduced cost (m=8KiB) so go test stays under 5s — D-26/Pitfall 4
- Hash(): crypto/rand salt per call, argon2.IDKey, PHC format $argon2id$v=19$...
- Verify(): PHC split/parse, ErrInvalidHash on malformed, ErrIncompatibleVersion on v!=19
- subtle.ConstantTimeCompare for timing-attack resistance (T-2-13)
- init() self-test: hash/verify round-trip panics on regression (D-08/T-2-15)
- Add golang.org/x/crypto v0.51.0 as direct dependency

backend/go.mod

@@ -8,6 +8,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.9.2
 	github.com/pressly/goose/v3 v3.27.1
+	golang.org/x/crypto v0.51.0
 )
 
 require (
@@ -18,5 +19,6 @@ require (
 	github.com/sethvargo/go-retry v0.3.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
 )

backend/go.sum

@@ -40,12 +40,14 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
 go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

backend/internal/auth/password.go

@@ -0,0 +1,117 @@
+package auth
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"fmt"
+	"strings"
+
+	"golang.org/x/crypto/argon2"
+)
+
+// Params holds the argon2id cost parameters.
+// The PHC string format self-describes these values, so each stored hash
+// carries its own params — cost upgrades are non-breaking.
+type Params struct {
+	Memory      uint32 // KiB
+	Iterations  uint32
+	Parallelism uint8
+	SaltLength  uint32
+	KeyLength   uint32
+}
+
+// DefaultParams matches the OWASP 2024 Password Storage Cheat Sheet baseline
+// for argon2id (D-08). Do not reduce these in production.
+var DefaultParams = Params{
+	Memory:      64 * 1024, // 64 MiB
+	Iterations:  1,
+	Parallelism: 4,
+	SaltLength:  16,
+	KeyLength:   32,
+}
+
+// TestParams uses reduced cost so that `go test` wall-time stays under 5 seconds
+// (D-26, Pitfall 4). The same code path is exercised; only the cost differs.
+var TestParams = Params{
+	Memory:      8 * 1024, // 8 MiB
+	Iterations:  1,
+	Parallelism: 2,
+	SaltLength:  16,
+	KeyLength:   32,
+}
+
+// init runs a self-test hash/verify round-trip to catch param-drift or build
+// regressions at package import time (D-08).
+func init() {
+	phc, err := Hash("self-test-password-12chars", TestParams)
+	if err != nil {
+		panic("argon2 self-test Hash failed: " + err.Error())
+	}
+	ok, err := Verify(phc, "self-test-password-12chars")
+	if err != nil || !ok {
+		panic("argon2 self-test Verify failed: hash/verify round-trip mismatch")
+	}
+}
+
+// Hash derives an argon2id key from password and encodes it as a PHC-formatted
+// string. A fresh random salt is generated on every call (never reused).
+//
+// Length contract (D-25): callers MUST reject len(password) > 128 before calling
+// Hash to prevent a long-password DoS. This function does not enforce the ceiling
+// itself so that it remains a pure primitive usable in tests.
+func Hash(password string, p Params) (string, error) {
+	salt := make([]byte, p.SaltLength)
+	if _, err := rand.Read(salt); err != nil {
+		return "", fmt.Errorf("auth: failed to generate salt: %w", err)
+	}
+	h := argon2.IDKey([]byte(password), salt, p.Iterations, p.Memory, p.Parallelism, p.KeyLength)
+	return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
+		argon2.Version,
+		p.Memory,
+		p.Iterations,
+		p.Parallelism,
+		base64.RawStdEncoding.EncodeToString(salt),
+		base64.RawStdEncoding.EncodeToString(h),
+	), nil
+}
+
+// Verify checks whether password matches the argon2id PHC string encoded.
+// Returns (true, nil) on match, (false, nil) on mismatch, and (false, sentinel)
+// when encoded is structurally invalid or uses an incompatible argon2 version.
+// The comparison is constant-time to prevent timing attacks (T-2-13).
+func Verify(encoded, password string) (bool, error) {
+	parts := strings.Split(encoded, "$")
+	// A valid PHC string split on "$" yields 6 elements:
+	//   [0]=""  [1]="argon2id"  [2]="v=19"  [3]="m=...,t=...,p=..."  [4]=<salt>  [5]=<hash>
+	if len(parts) != 6 || parts[1] != "argon2id" {
+		return false, ErrInvalidHash
+	}
+
+	var version int
+	if _, err := fmt.Sscanf(parts[2], "v=%d", &version); err != nil {
+		return false, ErrInvalidHash
+	}
+	if version != argon2.Version {
+		return false, ErrIncompatibleVersion
+	}
+
+	var mem, iter uint32
+	var par uint8
+	if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &mem, &iter, &par); err != nil {
+		return false, ErrInvalidHash
+	}
+
+	salt, err := base64.RawStdEncoding.Strict().DecodeString(parts[4])
+	if err != nil {
+		return false, ErrInvalidHash
+	}
+	want, err := base64.RawStdEncoding.Strict().DecodeString(parts[5])
+	if err != nil {
+		return false, ErrInvalidHash
+	}
+
+	got := argon2.IDKey([]byte(password), salt, iter, mem, par, uint32(len(want)))
+	// NOTE: constant-time compare is required here to prevent timing attacks (T-2-13).
+	return subtle.ConstantTimeCompare(want, got) == 1, nil
+}