auth.password-hash

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { pbkdf2Sha256 } from "./crypto_pbkdf2_sha256.ts";  ← from crypto.pbkdf2-sha256 ^1.0.0 · built alongside by fune
import { base64Encode } from "./encoding_base64_base64_encode.ts";
import { utf8Encode } from "./encoding_utf8_utf8_encode.ts";

/**
 * A password as pbkdf2_sha256$<iterations>$<salt>$<hash>, the salt and the
 * 32-byte PBKDF2-HMAC-SHA256 key in standard base64. The salt is passed in
 * because a capability may not read randomness: generate 16 or more fresh
 * random bytes for every call.
 */
export function hashPassword(password: string, salt: readonly number[], iterations: number): string {
  if (typeof password !== "string") throw new TypeError("password must be a string");
  if (!Array.isArray(salt) && !(salt instanceof Uint8Array)) {
    throw new TypeError("salt must be a list of integers from 0 to 255");
  }
  if (salt.length < 16) {
    throw new RangeError(`salt must be at least 16 bytes, received ${salt.length}`);
  }
  if (typeof iterations !== "number" || !Number.isInteger(iterations) || iterations < 1000) {
    throw new RangeError("iterations must be a whole number of at least 1000");
  }
  const hash = pbkdf2Sha256(utf8Encode(password), salt, iterations, 32);
  return `pbkdf2_sha256$${iterations}$${base64Encode(salt)}$${base64Encode(hash)}`;
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { pbkdf2Sha256 } from "./crypto_pbkdf2_sha256.ts";  ← from crypto.pbkdf2-sha256 ^1.0.0 · built alongside by fune
import { constantTimeEqual } from "./crypto_constant_time_equal.ts";  ← from crypto.constant-time-equal ^1.0.0 · built alongside by fune
import { base64Decode } from "./encoding_base64_base64_decode.ts";
import { utf8Encode } from "./encoding_utf8_utf8_encode.ts";

const MALFORMED = "stored password hash is malformed";

function decodeField(text: string): readonly number[] {
  let bytes: readonly number[];
  try {
    bytes = base64Decode(text);
  } catch {
    throw new RangeError(MALFORMED);
  }
  if (bytes.length === 0) throw new RangeError(MALFORMED);
  return bytes;
}

/**
 * The parts of a stored pbkdf2_sha256 string, or an error: a string this
 * code did not write is a data problem to surface, not a wrong password.
 */
export function parseStoredHash(stored: string): { iterations: number; salt: readonly number[]; hash: readonly number[] } {
  if (typeof stored !== "string") throw new TypeError("stored password hash must be a string");
  const parts = stored.split("$");
  if (parts[0] !== "pbkdf2_sha256") throw new RangeError("stored password hash is not a pbkdf2_sha256 hash");
  if (parts.length !== 4) throw new RangeError(MALFORMED);
  const count = parts[1];
  if (count.length === 0 || count.length > 10 || count[0] === "0") throw new RangeError(MALFORMED);
  for (let i = 0; i < count.length; i++) {
    if (count[i] < "0" || count[i] > "9") throw new RangeError(MALFORMED);
  }
  return { iterations: Number(count), salt: decodeField(parts[2]), hash: decodeField(parts[3]) };
}

/**
 * Does the password match the stored hash? Re-derived with the stored salt
 * and iteration count, compared in constant time.
 */
export function verifyPassword(password: string, stored: string): boolean {
  if (typeof password !== "string") throw new TypeError("password must be a string");
  const { iterations, salt, hash } = parseStoredHash(stored);
  return constantTimeEqual(pbkdf2Sha256(utf8Encode(password), salt, iterations, hash.length), hash);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { parseStoredHash } from "./auth_password_hash_verify_password.ts";  ← verifyPassword, another function of this group · built into the same file, even by a slim install

/**
 * Was this hash made more weakly than hashes are made today? Call it after
 * a successful login, while the plain password is at hand, and re-hash and
 * save when it answers true.
 */
export function passwordNeedsRehash(stored: string, iterations: number): boolean {
  if (typeof iterations !== "number" || !Number.isInteger(iterations) || iterations < 1000) {
    throw new RangeError("iterations must be a whole number of at least 1000");
  }
  const parsed = parseStoredHash(stored);
  return parsed.iterations < iterations || parsed.salt.length < 16 || parsed.hash.length !== 32;
}