docs: publish password hashing APIs

scripts/api_coverage_manifest.py

@@ -37,7 +37,9 @@ PUBLIC_APIS = [
     ("to_json", False, "public"), ("remove", False, "public"), ("clear", False, "public"),
     ("gen_sha1", True, "public"), ("sha256", True, "public"), ("sha256_hex", True, "public"),
     ("hmac_sha256", True, "public"), ("hmac_sha256_hex", True, "public"), ("random_bytes", True, "public"),
-    ("crypto_equal", True, "public"), ("gen_noise32", True, "public"), ("gen_noise64", True, "public"),
+    ("crypto_equal", True, "public"), ("password_hash", True, "public"),
+    ("password_verify", True, "public"), ("password_needs_rehash", True, "public"),
+    ("gen_noise32", True, "public"), ("gen_noise64", True, "public"),
     ("gen_noise01", True, "public"), ("gen_int", True, "public"), ("gen_float", True, "public"),
     ("draw_int", True, "public"), ("draw_float", True, "public"),
     ("encode_query", True, "public"), ("csrf_token", True, "public"),

scripts/test_password_hashing.sh

@@ -25,11 +25,14 @@ cache_dir="$bin_directory$(realpath "$source_dir")"
 printf '%s\n' \
 	'CLI(Request& context) {' \
 	'  String encoded = password_hash("correct horse battery staple");' \
-	'  print(encoded, "\n", password_verify("correct horse battery staple", encoded) ? "valid" : "invalid", "\n", password_verify("wrong password", encoded) ? "wrong-valid" : "wrong-rejected", "\n", password_needs_rehash(encoded) ? "rehash" : "current", "\n", password_verify("password", "$uce$scrypt$999999999$8$1$00$00") ? "malformed-valid" : "malformed-rejected");' \
+	'  String second = password_hash("correct horse battery staple");' \
+	'  String weaker = "$uce$scrypt$16384$8$1$00112233445566778899aabbccddeeff$29fdfb3d991961e926a19c1136a07e252afa5fdb8d3a0fb74cdcfa5016956f34";' \
+	'  String excessive = "$uce$scrypt$131072$8$1$00112233445566778899aabbccddeeff$0000000000000000000000000000000000000000000000000000000000000000";' \
+	'  print(encoded, "\n", encoded != second ? "randomized" : "reused", "\n", password_verify("correct horse battery staple", encoded) ? "valid" : "invalid", "\n", password_verify("wrong password", encoded) ? "wrong-valid" : "wrong-rejected", "\n", password_needs_rehash(encoded) ? "rehash" : "current", "\n", password_verify("legacy password", weaker) && password_needs_rehash(weaker) ? "legacy-valid-rehash" : "legacy-failed", "\n", !password_verify("password", excessive) && password_needs_rehash(excessive) ? "excessive-rejected" : "excessive-accepted", "\n", !password_verify("password", "$uce$scrypt$65536$8$1$zz$00") && password_needs_rehash("malformed") ? "malformed-rejected" : "malformed-valid");' \
 	'}' >"$source_dir/test.uce"
 
 output=$(scripts/uce-cli "/$test_name/test.uce")
-if [[ "$output" != *'$uce$scrypt$65536$8$1$'* || "$output" != *$'\nvalid\nwrong-rejected\ncurrent\nmalformed-rejected'* ]]; then
+if [[ "$output" != *'$uce$scrypt$65536$8$1$'* || "$output" != *$'\nrandomized\nvalid\nwrong-rejected\ncurrent\nlegacy-valid-rehash\nexcessive-rejected\nmalformed-rejected'* ]]; then
 	echo "native password hashing failed: $output" >&2
 	exit 1
 fi

site/doc/areas/noise.txt

@@ -14,3 +14,6 @@ hmac_sha256
 hmac_sha256_hex
 random_bytes
 crypto_equal
+password_hash
+password_verify
+password_needs_rehash

site/doc/pages/password_hash.txt

@@ -0,0 +1,18 @@
+:sig
+String password_hash(String password)
+
+:params
+password : password bytes to hash
+return value : self-contained scrypt encoding, or an empty string on failure
+
+:content
+Creates a password credential with a cryptographically random salt and UCE's current bounded scrypt parameters. Store the returned encoding exactly as produced. An empty result means hashing failed; abort the credential write and report an operational error instead of storing it.
+
+:example
+String encoded = password_hash("correct horse battery staple");
+print(encoded != "" && password_verify("correct horse battery staple", encoded) ? "valid" : "failed", "\n");
+
+:see
+>sys
+password_verify
+password_needs_rehash

site/doc/pages/password_needs_rehash.txt

@@ -0,0 +1,18 @@
+:sig
+bool password_needs_rehash(String encoded)
+
+:params
+encoded : stored password credential
+return value : true when the encoding is malformed or does not use UCE's current parameters
+
+:content
+Checks whether a stored UCE password encoding should be replaced. Call it only after successful verification, then hash the known-correct password again and atomically replace the old credential. Non-UCE legacy formats are reported as needing rehash but must be verified by the application before upgrade.
+
+:example
+String old = "$uce$scrypt$16384$8$1$00112233445566778899aabbccddeeff$29fdfb3d991961e926a19c1136a07e252afa5fdb8d3a0fb74cdcfa5016956f34";
+print(password_verify("legacy password", old) && password_needs_rehash(old) ? "upgrade" : "keep", "\n");
+
+:see
+>sys
+password_hash
+password_verify

site/doc/pages/password_verify.txt

@@ -0,0 +1,20 @@
+:sig
+bool password_verify(String password, String encoded)
+
+:params
+password : candidate password bytes
+encoded : self-contained `$uce$scrypt$...` credential
+return value : true only when the password matches a structurally valid, bounded encoding
+
+:content
+Derives the candidate with the parameters embedded in `encoded` and compares the result in constant time. Malformed encodings and parameters above UCE's accepted memory/work policy are rejected before derivation. Apply application-level password length limits and rate limiting around public authentication endpoints.
+
+:example
+String encoded = password_hash("correct horse battery staple");
+print(password_verify("correct horse battery staple", encoded) ? "valid" : "invalid", " / ");
+print(password_verify("wrong password", encoded) ? "valid" : "invalid", "\n");
+
+:see
+>sys
+password_hash
+password_needs_rehash