# primitives/crypto-pwhash

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`cryptoPwhashStr` and `cryptoPwhashStrVerify` expose libsodium's Argon2id password hashing via `crypto_pwhash_str` and `crypto_pwhash_str_verify`. Argon2id is the winner of the Password Hashing Competition (2015) and the recommended algorithm for password storage by OWASP and NIST SP 800-63B.

The encoded hash string includes the algorithm identifier, salt, and cost parameters — it is self-contained and safe to store directly in a database. This eliminates a class of bugs where the salt or parameters are stored separately and can become desynchronised.

## Features

- Argon2id password hashing via `crypto_pwhash_str` — salt generated internally.
- Self-contained encoded output (≈97 chars) — includes algorithm, salt, opsLimit, memLimit.
- Constant-time verification via `crypto_pwhash_str_verify`.
- Configurable `opsLimit` and `memLimit` — defaults to `OPSLIMIT_INTERACTIVE` / `MEMLIMIT_INTERACTIVE`.
- Async — calls `sodiumReady()` internally.
- `cryptoPwhashStrVerify` returns `false` on any failure, never throws.

## Usage: Basic Example

```ts
import { cryptoPwhashStr, cryptoPwhashStrVerify } from "@suaveplan/crypto-sodium/primitives/pwhash";

const password = new TextEncoder().encode("user-password-here");
const hash = await cryptoPwhashStr(password);

// Store `hash` in your database. Later, at login:
const valid = await cryptoPwhashStrVerify(hash, password);
console.log(valid); // true
```

## Usage: Advanced Example

Higher-security settings for sensitive credential storage:

```ts
import { cryptoPwhashStr, cryptoPwhashStrVerify } from "@suaveplan/crypto-sodium/primitives/pwhash";

const password = new TextEncoder().encode("admin-master-password");

// Sensitive account — use MODERATE or SENSITIVE preset values
// crypto_pwhash_OPSLIMIT_MODERATE = 3, MEMLIMIT_MODERATE = 268435456 (256 MiB)
const hash = await cryptoPwhashStr(password, {
  opsLimit: 3,
  memLimit: 268_435_456,
});

// Verification automatically reads cost parameters from the hash string
const ok = await cryptoPwhashStrVerify(hash, password);

// Password rehashing: if ok but hash uses lower-cost params, rehash
// (the encoded string embeds the params so you can detect this)
```

## API Reference

### `cryptoPwhashStr(password, opts?): Promise<string>`

Hashes `password` with Argon2id.

**Parameters:**

- `password: Uint8Array` — Raw password bytes.
- `opts.opsLimit?: number` — CPU/iteration cost. Default: `crypto_pwhash_OPSLIMIT_INTERACTIVE`.
- `opts.memLimit?: number` — Memory cost in bytes. Default: `crypto_pwhash_MEMLIMIT_INTERACTIVE`.

**Returns:** `Promise<string>` — Argon2id-encoded hash string, safe for database storage.

### `cryptoPwhashStrVerify(hash, password): Promise<boolean>`

Verifies `password` against an encoded hash string.

**Parameters:**

- `hash: string` — Encoded hash from `cryptoPwhashStr`.
- `password: Uint8Array` — Candidate password bytes.

**Returns:** `Promise<boolean>` — `true` if the password matches. Returns `false` (not throws) on any failure including malformed hash strings.

### `interface PwhashOptions`

- `opsLimit?: number`
- `memLimit?: number`

## Implementation Notes

`crypto_pwhash_str` generates a random salt internally and encodes the full Argon2id parameter set into the output string. This is the `$argon2id$v=19$...` format, compatible with most password-hashing libraries. The salt is never exposed to the caller.

`crypto_pwhash_str_verify` uses constant-time comparison for the hash check. The `try/catch` maps libsodium exceptions (e.g., malformed hash strings, wrong length) to `false` for uniform API behaviour.

The interactive preset (`OPSLIMIT_INTERACTIVE`, `MEMLIMIT_INTERACTIVE`) is calibrated for ≈50 ms on typical hardware. Increase `opsLimit` and `memLimit` for stored API keys, encryption master passwords, or recovery codes.