@udibo/oauth2 0.4.1 → 0.5.1

package/esm/identity/mfa/service.d.ts

@@ -110,7 +110,9 @@ export interface MfaServiceOptions {
      * Throttles {@link verify} per user id (a 6-digit code is brute-forceable
      * without one). When the limit is hit the service emits
      * `mfa.verify.rate_limited` and — under `protectionMode: "enforce"` —
-     * throws an `IdentityError` with code `rate_limited`. A successful
+     * throws an `IdentityError` with code `rate_limited`; a limiter whose
+     * `check` throws is treated as limited under `"enforce"` and allowed under
+     * `"log-only"`. A successful
      * verification resets the user's window, so legitimate sign-ins never
      * accumulate toward a lockout.
      */
@@ -236,7 +238,8 @@ export declare class MfaService {
      * Builds the service around an app-owned {@link MfaStore}.
      *
      * @throws {TypeError} on unusable configuration — non-positive-integer
-     * `digits`/`periodSeconds`/`recoveryCodeCount` or negative `windows` — so a
+     * `digits`/`periodSeconds`/`recoveryCodeCount` or a negative or non-integer
+     * `windows` — so a
      * miswired deploy fails at construction instead of silently rejecting every
      * code an enrolled user submits.
      */
@@ -257,32 +260,47 @@ export declare class MfaService {
      * and stored, and the plaintext codes are returned for one-time display.
      * Returns `{ confirmed: false }` when the code is wrong, no enrollment is
      * pending, or the pending secret changed under a concurrent enrollment. If
-     * storing the recovery codes fails after activation, the just-activated
-     * credential is rolled back and the error rethrown — a failure leaves the
-     * user *not* enrolled (free to retry), never enrolled without the recovery
-     * codes they were promised.
+     * storing the recovery codes fails after activation, the service calls
+     * `clearTotp` to roll the credential back and rethrows the original error,
+     * leaving the user *not* enrolled and free to retry. If `clearTotp` also
+     * fails, its error is thrown instead and the credential stays active
+     * without recovery codes.
+     *
+     * Guesses against the pending secret count toward the same per-user window
+     * {@link verify} uses (`mfa:verify:<userId>`), and a confirmed enrollment
+     * resets it — an unthrottled confirm would otherwise be a brute-force path
+     * to a secret the user is about to rely on.
      *
      * @throws {IdentityError} `mfa_already_enrolled` when an active credential
      * exists (see {@link startEnrollment}).
+     * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
+     * `protectionMode` is `"enforce"`, and the per-user limit is hit or the
+     * limiter's `check` throws (it fails closed).
      */
     confirmEnrollment(userId: string, code: string, options?: Pick<MfaVerifyOptions, "timestamp">): Promise<MfaEnrollmentConfirmation>;
     /**
      * Verify a second-factor code: first as TOTP against the *active* secret
      * (pending secrets are ignored — they need {@link confirmEnrollment}), then
      * as a recovery code (restrict with {@link MfaVerifyOptions.method}). An
-     * accepted TOTP code atomically advances the stored last step, so the same
-     * code is rejected on replay even under concurrent submission; an accepted
-     * recovery code is atomically burned, so it is single-use. Without an
+     * accepted TOTP code advances the stored last step through
+     * {@link MfaStore.advanceLastStep}, so the same code is rejected on replay;
+     * an accepted recovery code is burned through
+     * {@link MfaStore.consumeRecoveryHash}, so it is single-use. Both hold under
+     * concurrent submission only if the store implements those methods
+     * atomically. Without an
      * active credential every code is rejected — recovery codes are a fallback
      * *for* the enrolled factor, so stale hashes can never authenticate a user
      * whose MFA was disabled. A successful verification resets the per-user
-     * rate-limit window. On failure the result carries a
+     * rate-limit window; a `reset` that throws is logged and does not fail the
+     * verification, since the code is already spent by then — the window just
+     * stays filled until it lapses. On failure the result carries a
      * {@link MfaVerifyFailureReason} — `"replayed"` for a valid-but-spent TOTP
      * code, `"invalid"` otherwise — so a caller can distinguish a reused code
      * from a wrong one without subscribing to `onEvent`.
      *
      * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
-     * the per-user limit is hit, and `protectionMode` is `"enforce"`.
+     * `protectionMode` is `"enforce"`, and the per-user limit is hit or the
+     * limiter's `check` throws (it fails closed).
      */
     verify(userId: string, code: string, options?: MfaVerifyOptions): Promise<MfaVerification>;
     /** Whether the user has an *active* (confirmed) TOTP credential. */

package/esm/identity/mfa/service.js

@@ -50,7 +50,8 @@ export class MfaService {
      * Builds the service around an app-owned {@link MfaStore}.
      *
      * @throws {TypeError} on unusable configuration — non-positive-integer
-     * `digits`/`periodSeconds`/`recoveryCodeCount` or negative `windows` — so a
+     * `digits`/`periodSeconds`/`recoveryCodeCount` or a negative or non-integer
+     * `windows` — so a
      * miswired deploy fails at construction instead of silently rejecting every
      * code an enrolled user submits.
      */
@@ -98,15 +99,25 @@ export class MfaService {
      * and stored, and the plaintext codes are returned for one-time display.
      * Returns `{ confirmed: false }` when the code is wrong, no enrollment is
      * pending, or the pending secret changed under a concurrent enrollment. If
-     * storing the recovery codes fails after activation, the just-activated
-     * credential is rolled back and the error rethrown — a failure leaves the
-     * user *not* enrolled (free to retry), never enrolled without the recovery
-     * codes they were promised.
+     * storing the recovery codes fails after activation, the service calls
+     * `clearTotp` to roll the credential back and rethrows the original error,
+     * leaving the user *not* enrolled and free to retry. If `clearTotp` also
+     * fails, its error is thrown instead and the credential stays active
+     * without recovery codes.
+     *
+     * Guesses against the pending secret count toward the same per-user window
+     * {@link verify} uses (`mfa:verify:<userId>`), and a confirmed enrollment
+     * resets it — an unthrottled confirm would otherwise be a brute-force path
+     * to a secret the user is about to rely on.
      *
      * @throws {IdentityError} `mfa_already_enrolled` when an active credential
      * exists (see {@link startEnrollment}).
+     * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
+     * `protectionMode` is `"enforce"`, and the per-user limit is hit or the
+     * limiter's `check` throws (it fails closed).
      */
     async confirmEnrollment(userId, code, options) {
+        await this.#throttle(userId);
         const record = await this.#store.getTotp(userId);
         this.#assertNotEnrolled(record);
         const pending = record?.pendingSecretBase32;
@@ -131,6 +142,7 @@ export class MfaService {
             await this.#store.clearTotp(userId);
             throw error;
         }
+        await this.#resetThrottle(userId);
         await this.#emit({ type: "mfa.enrollment.confirmed", userId });
         return { confirmed: true, recoveryCodes };
     }
@@ -138,19 +150,25 @@ export class MfaService {
      * Verify a second-factor code: first as TOTP against the *active* secret
      * (pending secrets are ignored — they need {@link confirmEnrollment}), then
      * as a recovery code (restrict with {@link MfaVerifyOptions.method}). An
-     * accepted TOTP code atomically advances the stored last step, so the same
-     * code is rejected on replay even under concurrent submission; an accepted
-     * recovery code is atomically burned, so it is single-use. Without an
+     * accepted TOTP code advances the stored last step through
+     * {@link MfaStore.advanceLastStep}, so the same code is rejected on replay;
+     * an accepted recovery code is burned through
+     * {@link MfaStore.consumeRecoveryHash}, so it is single-use. Both hold under
+     * concurrent submission only if the store implements those methods
+     * atomically. Without an
      * active credential every code is rejected — recovery codes are a fallback
      * *for* the enrolled factor, so stale hashes can never authenticate a user
      * whose MFA was disabled. A successful verification resets the per-user
-     * rate-limit window. On failure the result carries a
+     * rate-limit window; a `reset` that throws is logged and does not fail the
+     * verification, since the code is already spent by then — the window just
+     * stays filled until it lapses. On failure the result carries a
      * {@link MfaVerifyFailureReason} — `"replayed"` for a valid-but-spent TOTP
      * code, `"invalid"` otherwise — so a caller can distinguish a reused code
      * from a wrong one without subscribing to `onEvent`.
      *
      * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
-     * the per-user limit is hit, and `protectionMode` is `"enforce"`.
+     * `protectionMode` is `"enforce"`, and the per-user limit is hit or the
+     * limiter's `check` throws (it fails closed).
      */
     async verify(userId, code, options) {
         await this.#throttle(userId);
@@ -276,7 +294,13 @@ export class MfaService {
         });
     }
     async #resetThrottle(userId) {
-        await this.#rateLimiter?.reset(this.#rateKey(userId));
+        try {
+            await this.#rateLimiter?.reset(this.#rateKey(userId));
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] MFA rate-limit reset failed; the window stays " +
+                "filled until it lapses:", error instanceof Error ? error.message : error);
+        }
     }
     async #verifyFailed(userId, reason) {
         await this.#emit({ type: "mfa.verify.failed", userId, reason });

package/esm/identity/mfa/totp.d.ts

@@ -87,8 +87,10 @@ export interface OtpauthUriOptions {
  * `issuer` query parameter, so apps that read either convention group the
  * entry correctly.
  *
- * @throws {TypeError} if the secret is not base32 or `digits`/`periodSeconds`
- * are not positive integers, so a corrupted value cannot inject URI parameters.
+ * @throws {TypeError} if the secret contains characters outside the base32
+ * alphabet (after stripping whitespace and `=`) or `digits`/`periodSeconds`
+ * are not positive integers, so a corrupted value cannot inject URI
+ * parameters. The secret's length is not checked.
  */
 export declare function buildOtpauthUri(options: OtpauthUriOptions): string;
 /** Options for {@link generateTotpCode}. */

package/esm/identity/mfa/totp.js

@@ -80,8 +80,10 @@ export function generateTotpSecret() {
  * `issuer` query parameter, so apps that read either convention group the
  * entry correctly.
  *
- * @throws {TypeError} if the secret is not base32 or `digits`/`periodSeconds`
- * are not positive integers, so a corrupted value cannot inject URI parameters.
+ * @throws {TypeError} if the secret contains characters outside the base32
+ * alphabet (after stripping whitespace and `=`) or `digits`/`periodSeconds`
+ * are not positive integers, so a corrupted value cannot inject URI
+ * parameters. The secret's length is not checked.
  */
 export function buildOtpauthUri(options) {
     validateTotpParams(options);

package/esm/identity/migration.d.ts

@@ -77,9 +77,9 @@ export declare function findLegacyVerifier(verifiers: readonly LegacyPasswordVer
 /**
  * Verify `password` against a stored foreign hash `phc` using the first matching
  * verifier in `verifiers`. Resolves `false` when no verifier recognizes `phc` or
- * the matched verifier rejects the password. Useful for a bulk-import
- * dry-run/validation pass; {@link IdentityService.signIn} uses the same
- * selection internally for upgrade-on-login.
+ * the matched verifier rejects the password or throws. Useful for a
+ * bulk-import dry-run/validation pass; {@link IdentityService.signIn} uses the
+ * same selection for upgrade-on-login.
  */
 export declare function verifyLegacyPassword(verifiers: readonly LegacyPasswordVerifier[], password: string, phc: string): Promise<boolean>;
 /**
@@ -100,8 +100,8 @@ export interface PhcHash {
 }
 /**
  * Parse a PHC / modular-crypt string (`$id[$v=n][$k=v,...]$salt$hash`) into its
- * parts. Returns `null` for anything that isn't a `$`-led PHC string. Salt and
- * hash are decoded as base64 (padding optional). This is the parsing helper for
+ * parts. Returns `null` for anything that isn't a `$`-led PHC string, or whose
+ * salt or hash segment is not valid base64 (padding optional). This is the parsing helper for
  * writing a bring-your-own argon2/scrypt {@link LegacyPasswordVerifier}: parse
  * the stored string, feed `params`/`salt`/`hash` to your KDF dependency, and
  * constant-time compare.
@@ -128,8 +128,9 @@ export interface Pbkdf2VerifierOptions {
  * - **Django** — `pbkdf2_<digest>$<iterations>$<salt>$<base64 hash>`, where the
  *   salt is used as raw UTF-8 bytes and the hash is standard base64. This is
  *   Django's `PBKDF2PasswordHasher` output.
- * - **PHC** — `$pbkdf2-<digest>$i=<iterations>$<base64 salt>$<base64 hash>`,
- *   with base64 (padding optional) salt and hash.
+ * - **PHC** — `$pbkdf2-<digest>$i=<iterations>$<base64 salt>$<base64 hash>`
+ *   (`rounds=` is accepted in place of `i=`), with base64 (padding optional)
+ *   salt and hash.
  *
  * `<digest>` is one of `sha1`, `sha256`, `sha512`. The derived-key length is
  * taken from the stored hash. Comparison is constant-time. On a match,

package/esm/identity/migration.js

@@ -45,9 +45,9 @@ export function findLegacyVerifier(verifiers, phc) {
 /**
  * Verify `password` against a stored foreign hash `phc` using the first matching
  * verifier in `verifiers`. Resolves `false` when no verifier recognizes `phc` or
- * the matched verifier rejects the password. Useful for a bulk-import
- * dry-run/validation pass; {@link IdentityService.signIn} uses the same
- * selection internally for upgrade-on-login.
+ * the matched verifier rejects the password or throws. Useful for a
+ * bulk-import dry-run/validation pass; {@link IdentityService.signIn} uses the
+ * same selection for upgrade-on-login.
  */
 export async function verifyLegacyPassword(verifiers, password, phc) {
     const verifier = findLegacyVerifier(verifiers, phc);
@@ -66,8 +66,8 @@ function decodeB64(segment) {
 }
 /**
  * Parse a PHC / modular-crypt string (`$id[$v=n][$k=v,...]$salt$hash`) into its
- * parts. Returns `null` for anything that isn't a `$`-led PHC string. Salt and
- * hash are decoded as base64 (padding optional). This is the parsing helper for
+ * parts. Returns `null` for anything that isn't a `$`-led PHC string, or whose
+ * salt or hash segment is not valid base64 (padding optional). This is the parsing helper for
  * writing a bring-your-own argon2/scrypt {@link LegacyPasswordVerifier}: parse
  * the stored string, feed `params`/`salt`/`hash` to your KDF dependency, and
  * constant-time compare.
@@ -126,11 +126,7 @@ const PBKDF2_DIGEST = {
     sha512: "SHA-512",
 };
 const encoder = new TextEncoder();
-/**
- * Reject an imported hash whose derived-key segment is implausibly short: a
- * 0-byte checksum would make `deriveBits(0)` compare empty-to-empty and turn
- * any password into a match on a runtime where that returns an empty buffer.
- */
+// A 0-byte checksum would compare empty-to-empty and match any password.
 const MIN_HASH_BYTES = 16;
 const MAX_PBKDF2_ITERATIONS = 1_000_000;
 function parseDjango(phc) {
@@ -192,8 +188,9 @@ function parsePbkdf2(phc) {
  * - **Django** — `pbkdf2_<digest>$<iterations>$<salt>$<base64 hash>`, where the
  *   salt is used as raw UTF-8 bytes and the hash is standard base64. This is
  *   Django's `PBKDF2PasswordHasher` output.
- * - **PHC** — `$pbkdf2-<digest>$i=<iterations>$<base64 salt>$<base64 hash>`,
- *   with base64 (padding optional) salt and hash.
+ * - **PHC** — `$pbkdf2-<digest>$i=<iterations>$<base64 salt>$<base64 hash>`
+ *   (`rounds=` is accepted in place of `i=`), with base64 (padding optional)
+ *   salt and hash.
  *
  * `<digest>` is one of `sha1`, `sha256`, `sha512`. The derived-key length is
  * taken from the stored hash. Comparison is constant-time. On a match,

package/esm/identity/mod.d.ts

@@ -9,8 +9,8 @@
  * - {@link IdentityService} — orchestrates the primitives below into sign-up,
  *   sign-in, password-reset, and email-verification flows you call from your
  *   own routes (storage stays an app-owned {@link IdentityUserStore}).
- * - {@link PasswordIdentityService} — PBKDF2 password hashing + constant-time
- *   verify (no more hand-rolled crypto); implement {@link PasswordHasherLike}
+ * - {@link PasswordIdentityService} — PBKDF2 password hashing with a
+ *   constant-time digest comparison; implement {@link PasswordHasherLike}
  *   instead to plug in argon2 or scrypt.
  * - {@link TokenFlowService} — single-use, hashed-at-rest verify/reset/sign-in
  *   tokens over an app-owned {@link TokenFlowStore} (magic links reuse it via

package/esm/identity/mod.js

@@ -9,8 +9,8 @@
  * - {@link IdentityService} — orchestrates the primitives below into sign-up,
  *   sign-in, password-reset, and email-verification flows you call from your
  *   own routes (storage stays an app-owned {@link IdentityUserStore}).
- * - {@link PasswordIdentityService} — PBKDF2 password hashing + constant-time
- *   verify (no more hand-rolled crypto); implement {@link PasswordHasherLike}
+ * - {@link PasswordIdentityService} — PBKDF2 password hashing with a
+ *   constant-time digest comparison; implement {@link PasswordHasherLike}
  *   instead to plug in argon2 or scrypt.
  * - {@link TokenFlowService} — single-use, hashed-at-rest verify/reset/sign-in
  *   tokens over an app-owned {@link TokenFlowStore} (magic links reuse it via

package/esm/identity/otp.d.ts

@@ -4,17 +4,16 @@
  *
  * A short numeric code has a different threat model than a URL token: it is
  * **guessable online** (a 6-digit code is one in a million), so unlike
- * {@link TokenFlowService} tokens every code carries an attempt budget — wrong
- * tries are counted and the code is invalidated (`locked`) when the budget is
- * spent. Codes are stored **hashed** (SHA-256, domain-bound to the email +
- * purpose) and verified with a constant-time compare; the raw code exists only
- * in the delivery callback.
+ * {@link TokenFlowService} tokens every code carries an attempt budget — each
+ * verification attempt is counted and the code is invalidated (`locked`) when
+ * the budget is spent. Codes are stored **hashed** (SHA-256, domain-bound to
+ * the email + purpose) and the hashes are compared in constant time; the raw
+ * code exists only in the delivery callback.
  *
  * Storage is an app-owned {@link OtpStore} (a {@link MemoryOtpStore} ships for
  * dev/tests) and delivery is a caller-supplied callback — the package owns the
  * lifecycle, never your tables or your mailer. `purpose` is a free string, so
- * the same service covers sign-in codes today and step-up / verification codes
- * later.
+ * one service can issue sign-in, step-up, and verification codes.
  *
  * @module
  */
@@ -46,9 +45,15 @@ export interface OtpRecord {
     codeHash: string;
     /** Expiry, epoch ms. */
     expiresAt: number;
-    /** Wrong verification attempts so far. */
+    /**
+     * Verification attempts recorded so far — every checked attempt, counted
+     * before the code is compared, not only the wrong ones.
+     */
     attempts: number;
-    /** Attempt budget; reaching it invalidates the code. */
+    /**
+     * Attempt budget; a wrong code on the attempt that reaches it invalidates
+     * the code.
+     */
     maxAttempts: number;
     /** Created, epoch ms. */
     createdAt: number;
@@ -158,8 +163,8 @@ export interface VerifyOtpOptions {
 /**
  * The outcome of {@link EmailOtpService.verify}. `invalid` covers both a wrong
  * code and no active code — indistinguishable on purpose. `locked` is reported
- * once, on the attempt that spends the budget; afterwards the code is gone and
- * further tries report `invalid`.
+ * on the attempt that spends the budget (and on any concurrent attempt past
+ * it); afterwards the code is gone and further tries report `invalid`.
  */
 export type VerifyOtpResult = {
     status: "success";
@@ -172,8 +177,8 @@ export type VerifyOtpResult = {
 };
 /**
  * Issues and verifies short-lived numeric one-time codes over an app-owned
- * {@link OtpStore}. Purpose-generic: `"signin"` today, step-up or verification
- * codes tomorrow — one instance can serve them all.
+ * {@link OtpStore}. Purpose-generic: one instance can serve sign-in, step-up,
+ * and verification codes.
  *
  * @example
  * ```ts
@@ -224,9 +229,11 @@ export declare class EmailOtpService {
     invalidateCode(id: string): Promise<void>;
     /**
      * Check a submitted code against the active record for `(email, purpose)`.
-     * The hash compare is constant-time and runs even when no active record
-     * exists, so a missing account or code is not distinguishable by timing. The
-     * attempt is reserved atomically — via the store's `recordAttempt` return
+     * The submitted code is hashed and a constant-time compare runs even when no
+     * active record exists. Timing is not fully uniform, though: an expired
+     * record returns before any attempt is recorded, and a live record adds the
+     * `recordAttempt` store write the no-record path skips. The attempt is
+     * reserved atomically — via the store's `recordAttempt` return
      * value — **before** the compare, so concurrent verifies of one live code
      * can't each test a guess against a stale pre-increment count: at most
      * `maxAttempts` guesses ever reach the comparison. Spending the budget

package/esm/identity/otp.js

@@ -4,17 +4,16 @@
  *
  * A short numeric code has a different threat model than a URL token: it is
  * **guessable online** (a 6-digit code is one in a million), so unlike
- * {@link TokenFlowService} tokens every code carries an attempt budget — wrong
- * tries are counted and the code is invalidated (`locked`) when the budget is
- * spent. Codes are stored **hashed** (SHA-256, domain-bound to the email +
- * purpose) and verified with a constant-time compare; the raw code exists only
- * in the delivery callback.
+ * {@link TokenFlowService} tokens every code carries an attempt budget — each
+ * verification attempt is counted and the code is invalidated (`locked`) when
+ * the budget is spent. Codes are stored **hashed** (SHA-256, domain-bound to
+ * the email + purpose) and the hashes are compared in constant time; the raw
+ * code exists only in the delivery callback.
  *
  * Storage is an app-owned {@link OtpStore} (a {@link MemoryOtpStore} ships for
  * dev/tests) and delivery is a caller-supplied callback — the package owns the
  * lifecycle, never your tables or your mailer. `purpose` is a free string, so
- * the same service covers sign-in codes today and step-up / verification codes
- * later.
+ * one service can issue sign-in, step-up, and verification codes.
  *
  * @module
  */
@@ -59,8 +58,8 @@ const DEFAULT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_ATTEMPTS = 5;
 /**
  * Issues and verifies short-lived numeric one-time codes over an app-owned
- * {@link OtpStore}. Purpose-generic: `"signin"` today, step-up or verification
- * codes tomorrow — one instance can serve them all.
+ * {@link OtpStore}. Purpose-generic: one instance can serve sign-in, step-up,
+ * and verification codes.
  *
  * @example
  * ```ts
@@ -153,9 +152,11 @@ export class EmailOtpService {
     }
     /**
      * Check a submitted code against the active record for `(email, purpose)`.
-     * The hash compare is constant-time and runs even when no active record
-     * exists, so a missing account or code is not distinguishable by timing. The
-     * attempt is reserved atomically — via the store's `recordAttempt` return
+     * The submitted code is hashed and a constant-time compare runs even when no
+     * active record exists. Timing is not fully uniform, though: an expired
+     * record returns before any attempt is recorded, and a live record adds the
+     * `recordAttempt` store write the no-record path skips. The attempt is
+     * reserved atomically — via the store's `recordAttempt` return
      * value — **before** the compare, so concurrent verifies of one live code
      * can't each test a guess against a stale pre-increment count: at most
      * `maxAttempts` guesses ever reach the comparison. Spending the budget

package/esm/identity/password-policy.d.ts

@@ -28,9 +28,9 @@ export interface PasswordPolicyResult {
 /**
  * Check a password against a policy, collecting all issues.
  *
- * Fails closed on a non-string `password` — an untyped value off a JSON body
- * has no `length`, so the length checks would silently pass it through to a
- * hash function that then `String`-coerces it.
+ * A non-string `password` (an untyped value off a JSON body) fails with a
+ * single issue. A validator that throws rejects this call; use
+ * {@link assertPasswordPolicy} to have that surface as `weak_password`.
  */
 export declare function checkPasswordPolicy(password: string, policy?: PasswordPolicy): Promise<PasswordPolicyResult>;
 /**

package/esm/identity/password-policy.js

@@ -9,9 +9,9 @@ import { IdentityError } from "./errors.js";
 /**
  * Check a password against a policy, collecting all issues.
  *
- * Fails closed on a non-string `password` — an untyped value off a JSON body
- * has no `length`, so the length checks would silently pass it through to a
- * hash function that then `String`-coerces it.
+ * A non-string `password` (an untyped value off a JSON body) fails with a
+ * single issue. A validator that throws rejects this call; use
+ * {@link assertPasswordPolicy} to have that surface as `weak_password`.
  */
 export async function checkPasswordPolicy(password, policy = {}) {
     if (typeof password !== "string") {

package/esm/identity/password.d.ts

@@ -1,13 +1,11 @@
 /**
  * Password hashing primitive for the identity self-service layer.
  *
- * Promotes the package's internal PBKDF2 helpers (previously reachable only via
- * a relative import) to a public, documented service so apps stop hand-rolling
- * password crypto — the single riskiest thing to reinvent. The built-in
- * algorithm is PBKDF2-SHA-256 at {@link DEFAULT_PBKDF2_ITERATIONS} iterations
- * with a constant-time verify. Want argon2 or scrypt instead? Implement
- * {@link PasswordHasherLike} with your own dependency and pass it wherever a
- * hasher is accepted — nothing in the package requires the concrete class.
+ * The built-in algorithm is PBKDF2-SHA-256 at {@link DEFAULT_PBKDF2_ITERATIONS}
+ * iterations, with a constant-time comparison of the derived digest. Want
+ * argon2 or scrypt instead? Implement {@link PasswordHasherLike} with your own
+ * dependency and pass it wherever a hasher is accepted — nothing in the package
+ * requires the concrete class.
  *
  * **Storage is yours.** Persist the whole {@link PasswordCredential} — including
  * its `params` — on your user record and pass it back to
@@ -32,10 +30,9 @@ export declare function generateSalt(length?: number): string;
 export declare const DEFAULT_PBKDF2_ITERATIONS = 600000;
 /**
  * The iteration count a {@link PasswordCredential} with no `params` is assumed
- * to have been hashed at — the package's original default. Credentials minted
- * before `params` existed keep verifying against this, and
+ * to have been hashed at. Such credentials keep verifying against this, and
  * {@link PasswordIdentityService.needsRehash} reports them as due for an
- * upgrade.
+ * upgrade whenever the service mints at a higher count.
  */
 export declare const LEGACY_PBKDF2_ITERATIONS = 100000;
 /** The algorithm identifier {@link PasswordIdentityService} records and accepts. */
@@ -51,8 +48,8 @@ export interface PasswordHashParams {
     iterations: number;
 }
 /**
- * A stored password credential: the hash, the salt it used, and (for
- * credentials minted since `params` existed) the work factor behind it.
+ * A stored password credential: the hash, the salt it used, and the work
+ * factor behind it.
  *
  * Persist all three fields. A credential with no `params` is interpreted as
  * PBKDF2-SHA-256 at {@link LEGACY_PBKDF2_ITERATIONS}.
@@ -73,12 +70,16 @@ export interface PasswordCredential {
  *
  * Implement the optional `needsRehash` to get rehash-on-successful-sign-in: the
  * identity flows call it after a password verifies and, when it returns `true`,
- * re-hash the just-verified password and persist the result.
+ * re-hash the just-verified password and persist the result — provided the
+ * user store implements `replaceCredential`.
  */
 export interface PasswordHasherLike {
     /** Hashes a new password into a credential to store. */
     hash(password: string): Promise<PasswordCredential>;
-    /** Constant-time verify of a password against a stored credential. */
+    /**
+     * Whether `password` matches the stored credential. Compare in constant time;
+     * resolve `false` rather than throw for a credential you cannot verify.
+     */
     verify(password: string, credential: PasswordCredential): Promise<boolean>;
     /**
      * Whether a stored credential is weaker than what this hasher mints today.
@@ -101,7 +102,8 @@ export interface PasswordHasherLike {
  */
 export declare function hashPassword(password: string, salt: string, iterations?: number): Promise<string>;
 /**
- * Verifies a password against a stored hash in constant time.
+ * Verifies a password against a stored hash, comparing the digests in constant
+ * time.
  *
  * @param password The password to verify
  * @param salt The salt used for the hash
@@ -120,8 +122,8 @@ export interface PasswordIdentityServiceOptions {
     iterations?: number;
 }
 /**
- * Hashes and verifies passwords (PBKDF2-SHA-256, constant-time verify).
- * Construct once and reuse.
+ * Hashes and verifies passwords (PBKDF2-SHA-256, constant-time digest
+ * comparison). Construct once and reuse.
  *
  * Verification reads the work factor off the credential, so credentials minted
  * under an older default keep verifying; {@link needsRehash} tells you when one
@@ -157,9 +159,10 @@ export declare class PasswordIdentityService implements PasswordHasherLike {
     /** Hashes a new password, generating a fresh random salt. */
     hash(password: string): Promise<PasswordCredential>;
     /**
-     * Constant-time verify of a password against a stored credential, using the
-     * credential's own recorded work factor. Resolves `false` for a credential
-     * recorded under an algorithm this service does not implement.
+     * Verifies a password against a stored credential at the credential's own
+     * recorded work factor, comparing digests in constant time. Resolves `false`
+     * for a credential recorded under an algorithm this service does not
+     * implement.
      */
     verify(password: string, credential: PasswordCredential): Promise<boolean>;
     /**

package/esm/identity/password.js

@@ -1,13 +1,11 @@
 /**
  * Password hashing primitive for the identity self-service layer.
  *
- * Promotes the package's internal PBKDF2 helpers (previously reachable only via
- * a relative import) to a public, documented service so apps stop hand-rolling
- * password crypto — the single riskiest thing to reinvent. The built-in
- * algorithm is PBKDF2-SHA-256 at {@link DEFAULT_PBKDF2_ITERATIONS} iterations
- * with a constant-time verify. Want argon2 or scrypt instead? Implement
- * {@link PasswordHasherLike} with your own dependency and pass it wherever a
- * hasher is accepted — nothing in the package requires the concrete class.
+ * The built-in algorithm is PBKDF2-SHA-256 at {@link DEFAULT_PBKDF2_ITERATIONS}
+ * iterations, with a constant-time comparison of the derived digest. Want
+ * argon2 or scrypt instead? Implement {@link PasswordHasherLike} with your own
+ * dependency and pass it wherever a hasher is accepted — nothing in the package
+ * requires the concrete class.
  *
  * **Storage is yours.** Persist the whole {@link PasswordCredential} — including
  * its `params` — on your user record and pass it back to
@@ -39,10 +37,9 @@ const encoder = new TextEncoder();
 export const DEFAULT_PBKDF2_ITERATIONS = 600_000;
 /**
  * The iteration count a {@link PasswordCredential} with no `params` is assumed
- * to have been hashed at — the package's original default. Credentials minted
- * before `params` existed keep verifying against this, and
+ * to have been hashed at. Such credentials keep verifying against this, and
  * {@link PasswordIdentityService.needsRehash} reports them as due for an
- * upgrade.
+ * upgrade whenever the service mints at a higher count.
  */
 export const LEGACY_PBKDF2_ITERATIONS = 100_000;
 /** The algorithm identifier {@link PasswordIdentityService} records and accepts. */
@@ -70,7 +67,8 @@ export async function hashPassword(password, salt, iterations = DEFAULT_PBKDF2_I
     return encodeHex(new Uint8Array(derivedBits, 0, 32));
 }
 /**
- * Verifies a password against a stored hash in constant time.
+ * Verifies a password against a stored hash, comparing the digests in constant
+ * time.
  *
  * @param password The password to verify
  * @param salt The salt used for the hash
@@ -86,8 +84,8 @@ export async function verifyPassword(password, salt, hash, iterations = DEFAULT_
     return timingSafeEqual(encoder.encode(computedHash), encoder.encode(hash));
 }
 /**
- * Hashes and verifies passwords (PBKDF2-SHA-256, constant-time verify).
- * Construct once and reuse.
+ * Hashes and verifies passwords (PBKDF2-SHA-256, constant-time digest
+ * comparison). Construct once and reuse.
  *
  * Verification reads the work factor off the credential, so credentials minted
  * under an older default keep verifying; {@link needsRehash} tells you when one
@@ -134,9 +132,10 @@ export class PasswordIdentityService {
         };
     }
     /**
-     * Constant-time verify of a password against a stored credential, using the
-     * credential's own recorded work factor. Resolves `false` for a credential
-     * recorded under an algorithm this service does not implement.
+     * Verifies a password against a stored credential at the credential's own
+     * recorded work factor, comparing digests in constant time. Resolves `false`
+     * for a credential recorded under an algorithm this service does not
+     * implement.
      */
     verify(password, credential) {
         const params = credential.params;