@shaferllc/keel 0.66.0 → 0.74.0

package/docs/hashing.md

@@ -0,0 +1,259 @@
+# Hashing & Encryption
+
+Password hashing and value encryption, both built on the Web Crypto API — so
+they run identically on Node and the edge, with no native bindings (no `bcrypt`
+to compile). Every operation is `async` (Web Crypto is promise-based), and the
+core never reaches for a Node-only module, so the same code ships to a Worker or
+a server unchanged.
+
+## Hashing passwords
+
+`hash.make()` produces a self-describing PBKDF2-SHA256 hash (algorithm,
+iterations, salt, and digest are all encoded in the string):
+
+```ts
+import { hash } from "@shaferllc/keel/core";
+
+const hashed = await hash.make(password);      // store this
+await hash.verify(hashed, password);            // → true / false
+```
+
+The stored string is `pbkdf2_sha256$<iterations>$<base64 salt>$<base64 digest>` —
+four `$`-joined fields. Because the salt and work factor travel with the digest,
+`verify()` needs nothing but the stored string and the candidate password; there
+is no separate salt column to manage.
+
+Each call to `make()` draws a fresh 16-byte random salt, so hashing the same
+password twice yields two different strings — both verify:
+
+```ts
+const a = await hash.make("hunter2");
+const b = await hash.make("hunter2");
+a === b;                          // false — different salts
+await hash.verify(a, "hunter2");  // true
+await hash.verify(b, "hunter2");  // true
+```
+
+Note the argument order: `verify(hashed, password)` — the **stored hash comes
+first**, the plaintext second.
+
+### Rotating the work factor
+
+Rotate work factors over time — bump the iteration count and rehash on next
+login, while the user's plaintext is in hand:
+
+```ts
+if (await hash.verify(user.password, plain)) {
+  if (hash.needsRehash(user.password)) {
+    user.password = await hash.make(plain);
+    await user.save();
+  }
+}
+```
+
+The default is 100,000 iterations. To raise the bar, pass a higher count to
+`make()` and check against the same number with `needsRehash()`:
+
+```ts
+const hashed = await hash.make(password, 200_000);
+hash.needsRehash(hashed, 200_000);   // false — already at target
+hash.needsRehash(hashed, 300_000);   // true  — below the new default
+```
+
+Verification is timing-safe (a constant-time compare of the derived digests),
+and `verify()` returns `false` — never throws — for the common malformed cases:
+wrong algorithm prefix or a missing field. A hash whose iteration field or salt
+is unparsable is a corrupt store, not a wrong password (see the note on
+`verify` in the reference).
+
+### Faster tests
+
+PBKDF2 is deliberately slow, which makes a test suite that creates lots of users
+crawl. `hash.fake()` swaps in a trivial, **insecure** scheme (`make` returns
+`fake$<password>`, `verify` just compares) so hashing is near-instant; `restore()`
+brings back real PBKDF2. Call them in your test setup/teardown:
+
+```ts
+beforeEach(() => hash.fake());
+afterEach(() => hash.restore());
+```
+
+Never call `fake()` outside tests.
+
+## Encrypting values
+
+`encryption` encrypts any JSON-serializable value with AES-GCM (a 256-bit key
+derived by SHA-256 from `config('app.key')`, a fresh 12-byte IV per call). Use it
+for tokens, opaque cookies, or anything you hand to a client and get back:
+
+```ts
+import { encryption } from "@shaferllc/keel/core";
+
+const token = await encryption.encrypt({ userId: 1, scope: "reset" });
+const data = await encryption.decrypt<{ userId: number }>(token);
+// data → { userId: 1, scope: "reset" }  or  null if tampered / invalid
+```
+
+AES-GCM is authenticated: the tag is verified on decrypt, so any tampering with
+the ciphertext (or a payload produced under a different key) fails the
+authentication check. `decrypt()` turns that failure into `null` rather than
+throwing — so a bad token is just an unauthenticated request, not a crash:
+
+```ts
+const value = await encryption.decrypt(untrustedInput);
+if (value === null) return unauthorized();   // tampered, truncated, or wrong key
+```
+
+`encrypt()` round-trips anything `JSON.stringify` accepts — objects, arrays,
+strings, numbers, booleans. It is not deterministic: the random IV means the same
+input encrypts to a different string every time, so you can't use the ciphertext
+as a lookup key.
+
+### Expiring and purpose-bound tokens
+
+`encrypt()` takes options that make the ciphertext self-expire and bind it to a
+context — ideal for one-shot links like password resets or email confirmations:
+
+```ts
+const token = await encryption.encrypt(
+  { userId: 1 },
+  { expiresIn: "1h", purpose: "password-reset" },
+);
+
+// later — decrypt with the SAME purpose, or you get null
+const data = await encryption.decrypt(token, { purpose: "password-reset" });
+```
+
+`expiresIn` is seconds or a duration string (`"30m"`, `"1h"`, `"7d"`); an expired
+token decrypts to `null`. `purpose` binds the token to a use — decrypting with a
+different purpose (or none) returns `null`, so a reset token can't be replayed as,
+say, a login token. Both travel inside the ciphertext, so they can't be tampered
+with. Tokens made without these options keep decrypting as before.
+
+## The app key
+
+Both encryption and [signed URLs](./url-builder.md) use `config('app.key')`. Set
+a long, random `APP_KEY` and keep it secret:
+
+```
+APP_KEY=a-long-random-secret-value
+```
+
+If `app.key` is unset, `encrypt()` **throws** (`Encryption requires
+config('app.key'). Set APP_KEY.`) — encryption can't proceed without a key. On
+the read side `decrypt()` still returns `null` (the missing-key error is caught
+alongside every other decrypt failure), so a misconfigured key surfaces as failed
+decryption, not an exception.
+
+Changing the key invalidates every previously encrypted value and signed URL —
+old ciphertext no longer authenticates under the new key, so every prior token
+decrypts to `null`.
+
+---
+
+## API reference
+
+Two objects are exported: `hash` (password hashing) and `encryption` (reversible
+value encryption). Both are plain objects — import and call their methods
+directly; there's nothing to construct.
+
+### `hash`
+
+PBKDF2-SHA256 password hashing. All three methods work on the self-describing
+string format `pbkdf2_sha256$<iterations>$<salt>$<digest>`.
+
+#### `hash.make(password, iterations?)`
+
+`make(password: string, iterations?: number): Promise<string>`
+
+Hashes a password with PBKDF2-SHA256 and a fresh random 16-byte salt, returning
+the self-describing hash string.
+
+```ts
+const hashed = await hash.make(password);        // 100,000 iterations
+const stronger = await hash.make(password, 200_000);
+```
+
+**Notes:** `iterations` defaults to `100_000`. The salt is drawn from
+`crypto.getRandomValues`, so the output differs on every call; the digest is
+256-bit. Async because Web Crypto's `deriveBits` is. Store the whole returned
+string — it carries everything `verify` needs.
+
+#### `hash.verify(hashed, password)`
+
+`verify(hashed: string, password: string): Promise<boolean>`
+
+Re-derives the digest from `password` using the salt and iteration count embedded
+in `hashed`, and compares it constant-time. **Stored hash first, plaintext
+second.**
+
+```ts
+if (await hash.verify(user.password, submitted)) {
+  // authenticated
+}
+```
+
+**Notes:** the compare is timing-safe. Returns `false` (never throws) when the
+algorithm prefix isn't `pbkdf2_sha256` or any of the four fields is missing.
+Caveat: a hash with the right prefix but a *non-numeric* iteration field or an
+*invalid-base64* salt slips past those guards and makes the underlying Web Crypto
+call throw — so "never throws" holds for genuine wrong-password and simple
+malformed cases, but not for a corrupted store. Treat your hash column as
+trusted.
+
+#### `hash.needsRehash(hashed, iterations?)`
+
+`needsRehash(hashed: string, iterations?: number): boolean`
+
+Returns `true` when `hashed` was made with fewer iterations than the given target
+— your cue to re-hash the plaintext at the current work factor.
+
+```ts
+if (hash.needsRehash(user.password)) {
+  user.password = await hash.make(plain);
+}
+```
+
+**Notes:** synchronous (it just reads the iteration field). `iterations`
+defaults to `100_000`. Returns `true` if the iteration field is absent or
+unparsable (a `0`/`NaN` count reads as "below target"). Only meaningful right
+after a successful `verify`, when you still hold the plaintext to re-hash.
+
+### `encryption`
+
+Authenticated (AES-GCM) encryption of JSON-serializable values, keyed by
+`config('app.key')`.
+
+#### `encryption.encrypt(value)`
+
+`encrypt(value: unknown): Promise<string>`
+
+JSON-serializes `value`, encrypts it with AES-GCM under a key derived from
+`config('app.key')`, and returns a base64 string (IV prepended to the
+ciphertext).
+
+```ts
+const token = await encryption.encrypt({ userId: 1, scope: "reset" });
+```
+
+**Notes:** each call uses a fresh random 12-byte IV, so the output is
+non-deterministic — never use the ciphertext as a cache/lookup key. Throws
+`Encryption requires config('app.key'). Set APP_KEY.` if the app key is unset.
+`value` must survive `JSON.stringify` (no `undefined`, functions, or `BigInt`).
+
+#### `encryption.decrypt(payload)`
+
+`decrypt<T = unknown>(payload: string): Promise<T | null>`
+
+Reverses `encrypt`: verifies the AES-GCM tag, decrypts, and `JSON.parse`s the
+result. The type parameter types the resolved value.
+
+```ts
+const data = await encryption.decrypt<{ userId: number }>(token);
+if (data === null) return unauthorized();
+```
+
+**Notes:** returns `null` — never throws — for any failure: tampered or truncated
+ciphertext, a payload encrypted under a different key, malformed base64, or an
+unset app key (all caught internally). `T` is a compile-time convenience; it does
+not validate the decrypted shape at runtime.

package/docs/health.md

@@ -0,0 +1,225 @@
+# Health Checks
+
+Two endpoints, answering the two questions an orchestrator — Kubernetes, Fly,
+Railway, a load balancer — actually asks:
+
+| Endpoint | Question | Checks |
+|----------|----------|--------|
+| `/health/live` | Is the process up? | **nothing** — answers instantly |
+| `/health/ready` | Can it serve requests? | every registered check |
+
+The split matters. A liveness probe that touched the database would get a
+perfectly healthy app **restarted** during a database blip. So liveness checks
+nothing: if it answered, the process is alive. Readiness is where dependencies are
+checked — a 503 there pulls the instance out of the load-balancer pool without
+killing it, and it rejoins when the dependency recovers.
+
+## Using it
+
+Register your checks once, then install the middleware:
+
+```ts
+import { health, healthCheck, HttpKernel, DatabaseCheck, RedisCheck } from "@shaferllc/keel/core";
+
+export class HealthServiceProvider extends ServiceProvider {
+  boot(): void {
+    health().register([
+      new DatabaseCheck(),
+      new RedisCheck().cacheFor(30),
+    ]);
+
+    this.app.make(HttpKernel).use(healthCheck());
+  }
+}
+```
+
+`GET /health/ready` now returns:
+
+```json
+{
+  "isHealthy": true,
+  "status": "ok",
+  "finishedAt": "2026-07-11T18:04:22.014Z",
+  "checks": [
+    {
+      "name": "database",
+      "status": "ok",
+      "message": "Database is reachable",
+      "isCached": false,
+      "finishedAt": "2026-07-11T18:04:22.011Z",
+      "meta": { "durationMs": 3 }
+    }
+  ]
+}
+```
+
+with **200** while `isHealthy` is true and **503** the moment a check fails.
+
+## Built-in checks
+
+| Check | What it does |
+|-------|--------------|
+| `DatabaseCheck` | `SELECT 1` on the default connection, or `new DatabaseCheck("reporting")` for a named one |
+| `RedisCheck` | Reads a key — a failed read means a broken connection |
+| `CacheCheck` | Writes a key, reads it back, deletes it |
+
+Notably **absent**: disk-space, heap, and RSS checks. Those measure a Node
+process, and on Workers there isn't one — a memory threshold you can't observe is
+worse than no check at all. If you're on Node and want them, `check()` below takes
+ten lines.
+
+## Your own checks
+
+`check(name, fn)` builds one from a function. Return `Result.ok`, `Result.warning`,
+or `Result.failed`:
+
+```ts
+import { check, Result, health } from "@shaferllc/keel/core";
+
+health().register([
+  check("stripe", async () => {
+    const res = await fetch("https://api.stripe.com/healthcheck");
+    return res.ok
+      ? Result.ok("Stripe is reachable")
+      : Result.failed(`Stripe returned ${res.status}`);
+  }),
+
+  check("queue-depth", async () => {
+    const depth = await queue().size();
+    if (depth > 10_000) return Result.failed(`Queue is backed up (${depth})`);
+    if (depth > 1_000) return Result.warning(`Queue is deep (${depth})`);
+    return Result.ok("Queue is keeping up").withMeta({ depth });
+  }),
+]);
+```
+
+**A warning is still healthy.** It shows up in the report and moves the overall
+`status` to `"warning"`, but readiness stays **200** — degraded is not the same as
+unable to serve, and you don't want a slow-but-working queue to evict every
+instance you have. Only `Result.failed` returns a 503.
+
+`withMeta()` attaches arbitrary detail (latencies, counts, versions) to the check's
+entry in the report.
+
+For a check with dependencies or state, extend `BaseCheck` instead:
+
+```ts
+class QueueDepthCheck extends BaseCheck {
+  readonly name = "queue-depth";
+
+  constructor(private limit = 10_000) {
+    super();
+  }
+
+  async run(): Promise<Result> {
+    const depth = await queue().size();
+    return depth > this.limit
+      ? Result.failed(`Queue is backed up (${depth})`)
+      : Result.ok("Queue is keeping up").withMeta({ depth });
+  }
+}
+```
+
+**A check that throws becomes a failure**, not an exception — one broken check
+never takes down the whole report, and the other checks still run and report.
+
+## Caching a check
+
+A probe every few seconds shouldn't hammer the thing it's probing. `cacheFor(seconds)`
+reuses the last result inside that window, and the report marks it `isCached: true`:
+
+```ts
+health().register([
+  new DatabaseCheck(),          // run every time — it's cheap
+  new RedisCheck().cacheFor(30), // at most once every 30s
+]);
+```
+
+## Protecting the endpoint
+
+The readiness report names your infrastructure, so don't publish it. Pass a
+`secret` and readiness requires `Authorization: Bearer <secret>`:
+
+```ts
+this.app.make(HttpKernel).use(healthCheck({ secret: env.HEALTH_SECRET }));
+```
+
+Liveness stays open — the orchestrator's restart probe shouldn't need a key, and
+it reveals nothing.
+
+---
+
+## API reference
+
+### `health()`
+
+`health(): HealthChecks`
+
+The application's health-check registry — a singleton.
+
+### `healthCheck(options?)`
+
+`healthCheck(options?: HealthCheckOptions): MiddlewareHandler`
+
+Serves `/health/live` and `/health/ready`. Anything else falls through to your
+routes.
+
+**Options:** `basePath` (default `"/health"`), `secret` (bearer token required on
+readiness), `checks` (a `HealthChecks` to run instead of the global registry —
+handy in tests).
+
+### `HealthChecks`
+
+| Method | Signature |
+|--------|-----------|
+| `register` | `(checks: BaseCheck[]) => this` |
+| `run` | `() => Promise<HealthReport>` — runs every check concurrently |
+| `all` | `() => BaseCheck[]` |
+| `clear` | `() => this` |
+
+### `check(name, fn)`
+
+`check(name: string, run: () => Promise<Result> | Result): BaseCheck`
+
+Builds a check from a function.
+
+### `BaseCheck`
+
+Abstract. Implement `name` and `run(): Promise<Result>`. `cacheFor(seconds)` reuses
+the last result for a window.
+
+### `Result`
+
+`Result.ok(message)` / `Result.warning(message)` / `Result.failed(message, error?)`,
+plus `withMeta(data)` to attach detail. A warning keeps readiness at 200; a failure
+takes it to 503.
+
+### Interfaces & types
+
+#### `HealthReport`
+
+```ts
+{
+  isHealthy: boolean;   // false only if a check failed
+  status: HealthStatus; // the worst status any check reported
+  finishedAt: string;   // ISO 8601
+  checks: CheckReport[];
+}
+```
+
+#### `CheckReport`
+
+```ts
+{
+  name: string;
+  status: HealthStatus;
+  message: string;
+  isCached: boolean;    // reused from a cacheFor() window
+  finishedAt: string;
+  meta?: Record<string, unknown>;
+}
+```
+
+#### `HealthStatus`
+
+`type HealthStatus = "ok" | "warning" | "error"`.