feat(postgres): add SCRAM hashing and password type detection - #260

…y trust

Tighten the hash parser used by Verify so it agrees with the structural
check performed by the password classifier (package password):

  - reject iteration counts <= 0 via the new ErrInvalidIterations
    sentinel (was: any int accepted, including 0 and negatives)
  - reject StoredKey / ServerKey values that do not decode to exactly
    32 bytes via the new ErrInvalidStoredKey / ErrInvalidServerKey
    sentinels (was: any base64-decodable length accepted, with the
    mismatch caught later via the length-mismatch short-circuit in
    subtle.ConstantTimeCompare)

Also clarify the wording of the two existing structural error
sentinels — "first block" / "second block" required the reader to
remember the canonical SCRAM-SHA-256$<iter>:<salt>$<StoredKey>:<ServerKey>
layout to know which is which.

Document on Verify that the iteration count parsed from the hash drives
the PBKDF2 work. Callers that may receive attacker-controlled hashes
should validate or cap that count before invoking Verify; the library
does not impose a hard maximum.

Test additions cover the four new error paths and tighten the existing
"non-base64 server key" entry so it no longer trips the new
StoredKey-length check before reaching the ServerKey decode.

Signed-off-by: Armando Ruocco <[email protected]>

Documentation-only follow-up: expand the package doc, normalize the
Err* sentinels to "is returned" and have each name the structural
rule it covers, document Verify's return contract, move the canonical
hash format into parsePostgreSQLHash's godoc, cite the upstream
defaults sources, switch GenerateOptions to Go's "// FieldName" form,
and fix the "have not have been" typo on Defaults.

Assisted-by: Claude Opus 4.7

Signed-off-by: Gabriele Bartolini <[email protected]>

Export the SCRAM-SHA-256 key length from pkg/postgres/password and
consume it from pkg/postgres/scram, removing the duplicated unexported
constant.

Assisted-by: Claude Opus 4.7

Signed-off-by: Gabriele Bartolini <[email protected]>

Defaults treated zero as "use DefaultPostgresIterations" but passed any
other value, including negatives, straight through to xdg-go/scram,
where it produced an opaque downstream error. Reject negatives early
with ErrInvalidIterations, matching what parsePostgreSQLHash already
does on the read side.

Signed-off-by: Marco Nenciarini <[email protected]>

Generate previously called the exported Defaults method, which wrote the
random salt and default iteration count back onto the receiver. A
caller that left Salt unset and invoked Generate twice on the same
options got identical hashes, because the first call had silently
filled in the salt.

Unexport Defaults as applyDefaults and have Generate operate on a local
copy of the receiver, so repeated calls draw independent salts and the
caller's struct is never modified. Drop the direct Defaults tests and
fold their assertions into observable Generate behavior, plus a
regression guard that asserts the receiver is unchanged across calls.

Signed-off-by: Marco Nenciarini <[email protected]>