go-authcrunch: Skill for Codex

Local Password Authentication

Ownership

pkg/identity/database.go owns Database.AuthenticateUser and identity lookup. pkg/identity/password_verifier.go owns passwordVerifier, newPasswordVerifier, activePasswordCost, and activeArgon2Password. Keep enumeration defenses at this shared database boundary so HTML, JSON, and other authentication callers receive the same protection.

The local adapter delegates through pkg/ids/local/store.go and pkg/ids/local/authenticator.go. HTML password challenges reach it from pkg/authn/handle_http_sandbox.go; JSON challenges use pkg/authn/handle_json_login.go.

pkg/identity/password.go owns password creation/import and Password.Match. password_argon2.go owns bounded Argon2id PHC decoding, generation and matching. Read password hashing contracts for formats, public configuration/parser APIs, CLI options, resource limits and migration. The default remains bcrypt; argon2: explicitly imports Argon2id v19. User.VerifyPassword in pkg/identity/user.go still serves credential-change checks. Substituting that per-user method for the database's store-wide verifier would remove work equalization. Client protocol and refresh-evidence lifecycle changes belong to their separate owning skills.

Password Management

Keep encoded imports at trusted provisioning boundaries. Public registration and Database.RequestWithIdentity password changes reject identity.IsPasswordHashImport inputs before mutation; see the password hashing contracts. Do not apply this restriction to login candidates or trusted configuration imports.

pkg/identity/user.go owns AddPassword, ResetPassword, ChangePassword, and UpdatePassword. Their shared replacement helper installs a validated active record and disables retained older records. Keep these mutation semantics separate from the authentication verifier's raw-plaintext comparison schedule.

• Validate replacement input through NewPassword before mutating credentials. Creation/import trims surrounding whitespace; duplicate comparison uses that same normalized input. Validation must still reject invalid imports and overlength bcrypt plaintext even if a comparison could match an existing hash. Argon2 supports longer plaintext subject to the database password policy. Valid imports are checked as hashes, not measured against plaintext length policy; import cannot prove the original plaintext satisfies that policy. Plaintext policy checks use the same trimmed value that creation hashes; surrounding whitespace cannot satisfy a minimum password length.
• For plaintext duplicates, compare against the first active record with Password.Match. For bcrypt and Argon2 imports, compare the algorithm and parsed encoded hash directly; never verify the serialized import string as though it were plaintext.
• A matching first record is reusable only while enabled and unexpired. AddPassword retains its hash, timestamps, and existing history when reusable. It must still disable other enabled password records. A duplicate is a complete no-op only when there are no such records left to revoke.
• Do not return early from UpdatePassword merely because VerifyPassword accepts the candidate: another active credential may need revocation.
• ResetPassword always installs a fresh active record, even when the plaintext or imported hash is unchanged. Validate before disabling the old credential; a failed reset must leave credentials usable and state unchanged.
• Plaintext replacements of a first Argon2 record retain Argon2 with current generation defaults. Explicit imports may switch either way. New users and existing bcrypt users keep their default algorithm; login does not rehash.
• ChangePassword still verifies the old password before replacing credentials. Database mutation wrappers must continue advancing CredentialVersion and persisting it even when the active hash is reused. Hash deduplication does not preserve refresh eligibility.