feat: add password policies and tighten argon2id defaults

- introduce Policy presets, WithPolicy option, and shared argon2 policy params
- gate argon2id hashing behind parameter validation and document the new API
- expand policy-focused tests plus README/CHANGELOG updates describing the Argon2id-only stance
- refresh README + CHANGELOG for v0.2.0 release

Author: allisson

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## v0.2.0 - 2026-01-17
+- Added policy presets (`PolicyInteractive`, `PolicyModerate`, `PolicySensitive`) plus the `WithPolicy` option for configuring Argon2id without manual parameters.
+- Introduced `argon2.ParamsForPolicy` and a shared policy descriptor so the CLI and library reuse the same vetted defaults.
+- Hardened `argon2.Argon2idHasher` with parameter validation guards and augmented doc comments across the new public surface.
+- Expanded the test suite to cover policy selection and the Argon2 preset helpers, keeping `go test ./...` green.
+- Rewrote README to state the Argon2id-only stance and document the policy workflow.
+
 ## v0.1.0 - 2026-01-17
 - Initial public release of `go-pwdhash` with Argon2id defaults (64MiB memory, 3 iterations, 4 lanes, 16-byte salts, 32-byte keys).
 - Introduced PHC-compliant encoder/decoder plus constant-time comparison helpers.

README.md

@@ -1,23 +1,35 @@
 # go-pwdhash
 
-`go-pwdhash` is a Go-first implementation of the Password Hashing Competition (PHC) string format with a batteries-included Argon2id hasher, deterministic upgrade signals, and zero surprises for callers who need predictable password hygiene.
+`go-pwdhash` is a Go-first password hashing helper that embraces the PHC (Password Hashing Competition) format, wraps Argon2id with safe defaults, and surfaces a minimal API for hashing, verification, and upgrades.
+
+## Argon2id Only
+
+pwdhash intentionally supports **Argon2id only**. Algorithms that have already been superseded by Argon2id will not be added, reducing the chance of accidentally selecting outdated primitives. If a superior successor to Argon2id emerges, pwdhash will adopt it behind the same API surface.
+
+## Password Policies
+
+pwdhash ships with opinionated Argon2id policies so applications can select a strength profile without touching raw parameters:
+
+- **Interactive** – user login flows where latency matters most.
+- **Moderate** – API keys, service-to-service calls, and privileged automation.
+- **Sensitive** – infrastructure secrets, root accounts, and long-lived credentials.
+
+Policies prevent insecure configurations by clamping the underlying Argon2id memory, iteration, and parallelism values to vetted presets.
 
 ## Highlights
 
-- **Modern Argon2id defaults** – ships with 64MiB memory, 3 iterations, 4 lanes, 16-byte salts, 32-byte keys, and Argon2 v=19 metadata.
-- **PHC compliant outputs** – hashes look like `$argon2id$v=19$...` and round-trip cleanly through the built-in parser.
-- **Interoperable by design** – encoded hashes verify inside Python's `pwdlib` and equivalent implementations in Rust or C without adapters.
-- **Extensible registry** – inject alternative hashers (or tuned Argon2id instances) via options while keeping a single entry point.
-- **Deterministic lifecycle** – `Hash`, `Verify`, and `NeedsRehash` expose the minimum API you need to manage password upgrades.
-- **Constant-time comparisons** – verification uses `crypto/subtle` helpers to avoid timing leaks.
+- **PHC-compliant output** – hashes look like `$argon2id$v=19$...` and parse cleanly across ecosystems.
+- **Deterministic upgrade path** – `NeedsRehash` compares stored parameters to the active policy so callers know exactly when to re-encode.
+- **Extensible registry** – advanced users may inject tuned Argon2id instances or alternate hashers via the option system.
+- **Constant-time verification** – comparisons use helpers under `internal/subtle` to avoid timing leaks.
 
 ## Installation
 
 ```bash
 go get github.com/allisson/go-pwdhash
 ```
 
-The module targets Go 1.24, depends on `golang.org/x/crypto`, and uses `stretchr/testify` only for tests.
+The module targets Go 1.24, depends on `golang.org/x/crypto`, and uses `stretchr/testify` solely for tests.
 
 ## Quick Start
 
@@ -31,7 +43,9 @@ import (
 )
 
 func main() {
-    hasher, err := pwdhash.New()
+    hasher, err := pwdhash.New(
+        pwdhash.WithPolicy(pwdhash.PolicyInteractive),
+    )
     if err != nil {
         panic(err)
     }
@@ -57,7 +71,12 @@ func main() {
 
 ## Configuration
 
-`pwdhash.New` accepts functional options. By default it registers a single Argon2id hasher returned by `argon2.Default()`. To tune parameters, construct the hasher yourself and inject it:
+`pwdhash.New` accepts functional options:
+
+- `pwdhash.WithPolicy` selects one of the built-in presets.
+- `pwdhash.WithHasher` installs a custom `pwdhash.Hasher` (useful for bespoke Argon2id tuning or for experimenting with future algorithms).
+
+Example of injecting custom parameters:
 
 ```go
 import (
@@ -78,30 +97,23 @@ func tunedHasher() (*pwdhash.PasswordHasher, error) {
 }
 ```
 
-To introduce a new algorithm, implement the `pwdhash.Hasher` interface and register it through `WithHasher`. The password hasher keeps an internal registry keyed by `Hasher.ID()`, so mixed fleets of algorithms are possible during migrations.
-
-## PHC Encoding Basics
+## PHC Encoding
 
-Internally, the library serializes `encoding.EncodedHash` structures that follow the pattern:
+pwdhash serializes `encoding.EncodedHash` values using the canonical PHC layout:
 
 ```
 $argon2id$v=19$m=65536,t=3,p=4$<base64(salt)>$<base64(hash)>
 ```
 
-- Parameters are stored verbatim; `NeedsRehash` compares them to the current configuration to decide when to upgrade.
-- The parser validates the prefix, version, parameter key/value pairs, and base64 payloads, returning structured errors for callers.
-
-Because the format matches the PHC specification byte-for-byte, it remains compatible with Python, Rust, or C libraries that speak the same dialect.
+The parser validates algorithm identifiers, versions, parameter pairs, and Base64 payloads before handing them to the active hasher.
 
 ## Testing & Tooling
 
-Run the suite locally:
-
 ```bash
 go test ./...
 ```
 
-Automation-friendly targets live in the Makefile:
+Or use the convenience targets:
 
 ```bash
 make lint   # golangci-lint run -v --fix
@@ -112,9 +124,9 @@ make test   # go test -covermode=count -coverprofile=count.out -v ./...
 
 1. Fork and clone the repo.
 2. Run `go test ./...` (and `make lint`) before sending patches.
-3. Keep exports documented, stick to `gofmt` / `goimports`, and prefer table-driven tests.
-4. Discuss larger API changes via issues or draft PRs—Argon2 is the default focus, so new algorithms should include rationale and tests.
+3. Keep exports documented, prefer table-driven tests, and stick to `gofmt`/`goimports`.
+4. Argon2id is the focus; proposals for new algorithms should include rationale plus end-to-end tests.
 
 ## License
 
-MIT licensed. See `LICENSE` for full text.
+MIT licensed. See `LICENSE` for details.

argon2/argon2id.go

@@ -40,6 +40,10 @@ func (a *Argon2idHasher) ID() string {
 
 // Hash derives an Argon2id key and returns the PHC string.
 func (a *Argon2idHasher) Hash(password []byte) (string, error) {
+	if err := a.validate(); err != nil {
+		return "", err
+	}
+
 	salt := make([]byte, a.SaltLength)
 	if _, err := rand.Read(salt); err != nil {
 		return "", err
@@ -71,6 +75,10 @@ func (a *Argon2idHasher) Hash(password []byte) (string, error) {
 
 // Verify recomputes the Argon2id hash and compares it in constant time.
 func (a *Argon2idHasher) Verify(password []byte, encoded string) (bool, error) {
+	if err := a.validate(); err != nil {
+		return false, err
+	}
+
 	parsed, err := encoding.Parse(encoded)
 	if err != nil {
 		return false, err
@@ -137,3 +145,16 @@ func (a *Argon2idHasher) NeedsRehash(encoded string) (bool, error) {
 
 	return false, nil
 }
+
+func (a *Argon2idHasher) validate() error {
+	if a.Memory < 32*1024 {
+		return fmt.Errorf("argon2 memory too low")
+	}
+	if a.Iterations < 2 {
+		return fmt.Errorf("argon2 iterations too low")
+	}
+	if a.Parallelism < 1 {
+		return fmt.Errorf("argon2 parallelism too low")
+	}
+	return nil
+}

argon2/argon2id_test.go

@@ -18,6 +18,69 @@ func newTestHasher() *Argon2idHasher {
 	}
 }
 
+func TestParamsForPolicy(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		policy int
+		want   PolicyParams
+		ok     bool
+	}{
+		{
+			name:   "interactive",
+			policy: 0,
+			want: PolicyParams{
+				Memory:      64 * 1024,
+				Iterations:  3,
+				Parallelism: 4,
+			},
+			ok: true,
+		},
+		{
+			name:   "moderate",
+			policy: 1,
+			want: PolicyParams{
+				Memory:      128 * 1024,
+				Iterations:  4,
+				Parallelism: 4,
+			},
+			ok: true,
+		},
+		{
+			name:   "sensitive",
+			policy: 2,
+			want: PolicyParams{
+				Memory:      256 * 1024,
+				Iterations:  5,
+				Parallelism: 8,
+			},
+			ok: true,
+		},
+		{
+			name:   "unknown",
+			policy: 3,
+			want:   PolicyParams{},
+			ok:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			params, err := ParamsForPolicy(tt.policy)
+			if tt.ok {
+				require.NoError(t, err)
+				require.Equal(t, tt.want, params)
+				return
+			}
+
+			require.Error(t, err)
+		})
+	}
+}
+
 func TestArgon2idHasher_HashAndVerify(t *testing.T) {
 	hasher := newTestHasher()
 

argon2/policy.go

@@ -0,0 +1,38 @@
+package argon2
+
+import "errors"
+
+// PolicyParams captures the Argon2 tuning knobs for a policy preset.
+type PolicyParams struct {
+	Memory      uint32
+	Iterations  uint32
+	Parallelism uint8
+}
+
+// ParamsForPolicy returns the Argon2 parameters associated with the policy id.
+func ParamsForPolicy(p int) (PolicyParams, error) {
+	switch p {
+	case 0: // Interactive
+		return PolicyParams{
+			Memory:      64 * 1024, // 64 MB
+			Iterations:  3,
+			Parallelism: 4,
+		}, nil
+
+	case 1: // Moderate
+		return PolicyParams{
+			Memory:      128 * 1024, // 128 MB
+			Iterations:  4,
+			Parallelism: 4,
+		}, nil
+
+	case 2: // Sensitive
+		return PolicyParams{
+			Memory:      256 * 1024, // 256 MB
+			Iterations:  5,
+			Parallelism: 8,
+		}, nil
+	}
+
+	return PolicyParams{}, errors.New("unknown password policy")
+}

options.go

@@ -26,3 +26,21 @@ func WithHasher(h Hasher) Option {
 		c.current = h
 	}
 }
+
+// WithPolicy selects a preset Argon2id configuration for the PasswordHasher.
+func WithPolicy(p Policy) Option {
+	return func(c *config) {
+		params, err := argon2.ParamsForPolicy(int(p))
+		if err != nil {
+			panic(err) // invalid policy is a programming bug
+		}
+
+		c.current = &argon2.Argon2idHasher{
+			Memory:      params.Memory,
+			Iterations:  params.Iterations,
+			Parallelism: params.Parallelism,
+			SaltLength:  16,
+			KeyLength:   32,
+		}
+	}
+}

password_test.go

@@ -73,6 +73,59 @@ func TestPasswordHasher_NeedsRehashDelegates(t *testing.T) {
 	require.True(t, needs)
 }
 
+func TestPasswordHasher_WithPolicy(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		policy Policy
+		check  func(t *testing.T, hasher *argon2.Argon2idHasher)
+	}{
+		{
+			name:   "interactive",
+			policy: PolicyInteractive,
+			check: func(t *testing.T, hasher *argon2.Argon2idHasher) {
+				require.EqualValues(t, 64*1024, hasher.Memory)
+				require.EqualValues(t, 3, hasher.Iterations)
+				require.EqualValues(t, 4, hasher.Parallelism)
+			},
+		},
+		{
+			name:   "moderate",
+			policy: PolicyModerate,
+			check: func(t *testing.T, hasher *argon2.Argon2idHasher) {
+				require.EqualValues(t, 128*1024, hasher.Memory)
+				require.EqualValues(t, 4, hasher.Iterations)
+				require.EqualValues(t, 4, hasher.Parallelism)
+			},
+		},
+		{
+			name:   "sensitive",
+			policy: PolicySensitive,
+			check: func(t *testing.T, hasher *argon2.Argon2idHasher) {
+				require.EqualValues(t, 256*1024, hasher.Memory)
+				require.EqualValues(t, 5, hasher.Iterations)
+				require.EqualValues(t, 8, hasher.Parallelism)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ph, err := New(WithPolicy(tt.policy))
+			require.NoError(t, err)
+
+			h, ok := ph.registry["argon2id"].(*argon2.Argon2idHasher)
+			require.True(t, ok)
+
+			tt.check(t, h)
+		})
+	}
+}
+
 func TestNewSetsDefaultHasher(t *testing.T) {
 	ph, err := New()
 	require.NoError(t, err)

policy.go

@@ -0,0 +1,13 @@
+package pwdhash
+
+// Policy represents a password hashing strength preset.
+type Policy int
+
+const (
+	// PolicyInteractive balances CPU cost with low latency for login flows.
+	PolicyInteractive Policy = iota
+	// PolicyModerate increases cost for privileged accounts or admin portals.
+	PolicyModerate
+	// PolicySensitive maximizes cost for high-value secrets.
+	PolicySensitive
+)