@xtandard/webhooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Montoya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,315 @@
+<div align="center">
+
+# @xtandard/webhooks
+
+**Self-hosted, embeddable, [Standard Webhooks](https://www.standardwebhooks.com)-compliant outbound-webhooks control plane.**
+
+Mount it inside your existing app, point it at the database you already run, and ship signed events with retries, dead-lettering, and a customer-facing portal — no per-message SaaS pricing, no separate service to operate.
+
+[![CI](https://github.com/xantiagoma/xtandard-webhooks/actions/workflows/ci.yml/badge.svg)](https://github.com/xantiagoma/xtandard-webhooks/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40xtandard%2Fwebhooks)](https://www.npmjs.com/package/@xtandard/webhooks)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+<img src="docs/assets/deliveries.png" alt="Deliveries view: attempt timeline with retries and dead-letters" width="800" />
+
+</div>
+
+> `publish()` never blocks on a customer's server. Your app publishes; the dispatcher inside your process (or a dedicated worker running the same library) delivers; your customers self-serve through an embeddable portal.
+
+## Contents
+
+- [Why another webhooks tool?](#why-another-webhooks-tool)
+- [How it works — the two planes](#how-it-works--the-two-planes)
+- [Quickstart](#quickstart)
+- [Send your first webhook](#send-your-first-webhook)
+- [Verify on the receiving side](#verify-on-the-receiving-side)
+- [The delivery model](#the-delivery-model)
+- [The consumer portal](#the-consumer-portal)
+- [Storage backends](#storage-backends)
+- [Subpath exports](#subpath-exports)
+- [Examples](#examples)
+- [CLI](#cli)
+- [Documentation](#documentation)
+- [Project status](#project-status)
+
+## Why another webhooks tool?
+
+Webhook delivery is a library concern, not a service you rent or a second deployment you babysit.
+
+- **Svix** is excellent — and a SaaS (or a heavyweight self-hosted server with its own Postgres/Redis to operate). This is `bun add` + the DB you already have.
+- **Hookdeck / Convoy** are services to operate. Same objection.
+- **Hand-rolled** senders reimplement signing, retries, and endpoint management — usually badly, always repeatedly. This packages the 20% everyone needs: applications, event types, endpoints, signed delivery, exponential retries, dead-letters, replay, observability, and a portal.
+
+And because the wire contract is **Standard Webhooks**, your receivers verify with the official `standardwebhooks` libraries in Python, Go, Ruby, Java, Rust, PHP, or the zero-dependency `@xtandard/webhooks/receiver` — nothing bespoke on their side.
+
+Sibling project: [`@xtandard/flags`](https://github.com/xantiagoma/xtandard-flags) — same architecture, same design system, for feature flags.
+
+## How it works — the two planes
+
+```mermaid
+flowchart LR
+  subgraph host["your app process"]
+    A[app code] -- "publish()" --> C[core]
+    UI[admin UI / portal] --> C
+    D[dispatcher] --> C
+  end
+  C <--> S[(your database)]
+  D -- "signed POSTs, retries" --> E1[customer endpoint]
+  D --> E2[customer endpoint]
+```
+
+- **Control plane** — CRUD on applications, event types, endpoints; browsing messages/deliveries; replay. Hook-guarded, audited, auth'd.
+- **Delivery plane** — `publish()` is one message write + fan-out (no HTTP, never throws because an endpoint is down). The in-process dispatcher owns all network I/O and retries; leases make it crash-safe and multi-instance-safe. At-least-once semantics; receivers dedupe on `webhook-id`.
+
+Kill the process mid-retry-schedule and restart it: pending deliveries resume. The admin UI can be completely unmounted and delivery still works.
+
+## Quickstart
+
+<details>
+<summary><b>Standalone (Docker)</b></summary>
+
+```sh
+docker run -p 3000:3000 -e STORAGE_DRIVER=memory ghcr.io/xantiagoma/xtandard-webhooks
+# open http://localhost:3000
+```
+
+</details>
+
+<details>
+<summary><b>CLI (npx / bunx)</b></summary>
+
+```sh
+bunx @xtandard/webhooks serve   # STORAGE_DRIVER=file by default → ./.webhooks
+```
+
+</details>
+
+<details>
+<summary><b>Elysia</b></summary>
+
+```ts
+import { Elysia } from "elysia";
+import { webhooksPanel } from "@xtandard/webhooks/elysia";
+import { createMemoryStorage } from "@xtandard/webhooks/storage/memory";
+
+const webhooks = webhooksPanel({ storage: createMemoryStorage() });
+new Elysia().mount("/webhooks", webhooks.fetch).listen(3000);
+```
+
+</details>
+
+<details>
+<summary><b>Hono</b></summary>
+
+```ts
+import { Hono } from "hono";
+import { webhooksPanel } from "@xtandard/webhooks/hono";
+import { createMemoryStorage } from "@xtandard/webhooks/storage/memory";
+
+const app = new Hono();
+app.route("/webhooks", webhooksPanel({ storage: createMemoryStorage() }));
+```
+
+</details>
+
+<details>
+<summary><b>Express</b></summary>
+
+```ts
+import express from "express";
+import { webhooksPanel } from "@xtandard/webhooks/express";
+import { createMemoryStorage } from "@xtandard/webhooks/storage/memory";
+
+const app = express();
+app.use("/webhooks", webhooksPanel({ storage: createMemoryStorage() })); // before body-parser
+app.listen(3000);
+```
+
+</details>
+
+<details>
+<summary><b>Bun</b></summary>
+
+```ts
+import { webhooksPanel } from "@xtandard/webhooks/bun";
+import { createMemoryStorage } from "@xtandard/webhooks/storage/memory";
+
+const webhooks = webhooksPanel({ storage: createMemoryStorage(), basePath: "/webhooks" });
+Bun.serve({ port: 3000, fetch: webhooks.fetch });
+```
+
+</details>
+
+Mounting the panel starts an in-process dispatcher by default (`dispatcher: false` for split-worker deployments).
+
+## Send your first webhook
+
+```ts
+const { core } = webhooks;
+
+await core.createApplication({ key: "acme" }); // your customer
+await core.upsertEventType({ name: "invoice.paid" }); // the catalog
+await core.createEndpoint("acme", {
+  url: "https://api.acme-customer.com/webhooks", // their receiver
+  eventTypes: ["invoice.paid"],
+});
+
+// The hot path — in the handler where the thing actually happens:
+await core.publish("acme", {
+  eventType: "invoice.paid",
+  payload: { invoiceId: "inv_123", amount: 4200 },
+  idempotencyKey: `invoice-paid-inv_123`, // safe to call twice
+});
+```
+
+## Verify on the receiving side
+
+TypeScript (this package, zero deps, any WinterCG runtime):
+
+```ts
+import { verifyWebhook } from "@xtandard/webhooks/receiver";
+
+export default async function handler(request: Request) {
+  const event = await verifyWebhook(request, process.env.WEBHOOK_SECRET!); // throws if invalid
+  // event.type === "invoice.paid", event.data === { invoiceId, amount }
+  return new Response("ok");
+}
+```
+
+Python / Go / anything — the **official** Standard Webhooks libraries verify deliveries from this package unmodified:
+
+```python
+from standardwebhooks.webhooks import Webhook
+payload = Webhook(secret).verify(body, headers)  # raises on failure
+```
+
+`examples/receivers/` runs FastAPI + Go receivers against a live dispatcher as the interop proof. Details: [docs/SIGNING.md](docs/SIGNING.md).
+
+## The delivery model
+
+```txt
+attempt:   #1      #2      #3      #4       #5      #6      #7
+delay:     0s ───► 5s ───► 5m ───► 30m ───► 2h ───► 5h ───► 10h ──► dead-letter
+                         (±10% jitter; fully configurable)
+```
+
+- Failures walk the schedule; exhaustion **dead-letters** (never silently drops) — visible in the UI with per-attempt HTTP detail, replayable one-at-a-time or in bulk (`recover` an endpoint since a timestamp).
+- Endpoints failing every attempt for 5 consecutive days auto-disable (configurable); disabled endpoints hold deliveries and resume on enable.
+- Every attempt hits the fire-and-forget `onDelivery` sink (metrics); terminal transitions fire `after` hooks (`delivery.succeeded` / `delivery.exhausted` — the offload point).
+- Secret rotation keeps the old secret verifying for a 24h grace window, with both signatures in the header.
+
+Details: [docs/DELIVERY.md](docs/DELIVERY.md).
+
+## The consumer portal
+
+The Svix "App Portal" experience, self-hosted: your customers manage their own endpoints and inspect their own deliveries inside your product, scoped by a signed token — no sessions, no proxy routes.
+
+```tsx
+// Your server: mint a token after your own auth
+const token = await createPortalToken(process.env.PORTAL_SECRET!, customer.appKey);
+
+// Your React frontend:
+import { WebhooksPortal } from "@xtandard/webhooks/react";
+import "@xtandard/webhooks/react/styles.css";
+
+<WebhooksPortal baseUrl="/webhooks" token={token} />;
+```
+
+Cross-application access is denied by construction — the host's authorization is never consulted for portal principals. Details: [docs/PORTAL.md](docs/PORTAL.md).
+
+## Storage backends
+
+Point it at what you already run — the whole system sits on a four-method KV contract ([ADR 0005](docs/ADR/0005-storage-kv-contract-due-index.md)):
+
+| Backend        | Subpath                                         | Notes                                                                       |
+| -------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
+| Memory         | `storage/memory`                                | dev/tests/demo; every capability                                            |
+| File           | `storage/file`                                  | zero-dep persistence                                                        |
+| Redis          | `storage/redis`                                 | native queue claiming (sorted set + Lua), pub/sub watch, JSON codec variant |
+| Postgres       | `storage/postgres`                              | jsonb KV, lazy DDL                                                          |
+| Drizzle        | `storage/drizzle` + `drizzle/{pg,mysql,sqlite}` | your ORM, your migrations                                                   |
+| MongoDB        | `storage/mongodb`                               |                                                                             |
+| SQLite (Bun)   | `storage/sqlite`                                | `bun:sqlite`                                                                |
+| libSQL / Turso | `storage/libsql`                                |                                                                             |
+| unstorage      | `storage/unstorage`                             | 20+ drivers via unjs                                                        |
+| Cloudflare KV  | `storage/cloudflare-kv`                         | dispatch via cron trigger                                                   |
+
+Split planes: control data in Postgres, delivery queue in Redis — `queueStorage`. Details: [docs/STORAGE.md](docs/STORAGE.md).
+
+## Subpath exports
+
+| Import                                   | What you get                                                                |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `@xtandard/webhooks`                     | core, dispatcher, panel handler, signing, portal tokens, hooks contract     |
+| `…/receiver`                             | `verifyWebhook` — zero-dep verification of **any** Standard Webhooks sender |
+| `…/signing`                              | low-level sign/verify primitives                                            |
+| `…/schema`                               | types only                                                                  |
+| `…/testing`                              | test core + verifying local receiver + drain helper                         |
+| `…/storage/*`, `…/drizzle/*`             | storage adapters (optional peers)                                           |
+| `…/auth/{none,basic,delegated}`          | authentication providers                                                    |
+| `…/authorization/{none,roles,delegated}` | authorization providers                                                     |
+| `…/hooks/log`                            | reference logging hook                                                      |
+| `…/{elysia,hono,express,bun}`            | framework adapters                                                          |
+| `…/react`, `…/react/styles.css`          | `<WebhooksDashboard>` + `<WebhooksPortal>` embeds                           |
+
+## Examples
+
+`bun run demo` boots a seeded playground on http://localhost:7789 — two applications, a grouped event catalog, healthy/flaky/dead endpoints producing real live attempt history, dead-letters to replay.
+
+| Example                                                                               | Shows                                                                  |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [`elysia`](examples/elysia) / [`hono`](examples/hono) / [`express`](examples/express) | panel + publish-on-user-action loop per framework                      |
+| [`full-loop`](examples/full-loop)                                                     | sender + verifying receiver in one command; watch retries live         |
+| [`portal-embed`](examples/portal-embed)                                               | `<WebhooksPortal>` inside a host React app                             |
+| [`auth`](examples/auth)                                                               | none/basic/delegated + roles + portal side-by-side                     |
+| [`receivers`](examples/receivers)                                                     | **polyglot proof**: official Python + Go libs verifying our deliveries |
+| [`storage-drivers`](examples/storage-drivers)                                         | one contract, every backend                                            |
+| [`postgres-redis`](examples/postgres-redis)                                           | split planes: control in Postgres, queue in Redis                      |
+| [`split-worker`](examples/split-worker)                                               | web publishes, worker dispatches                                       |
+| [`standalone-docker`](examples/standalone-docker)                                     | compose file for the image                                             |
+
+## Screenshots
+
+|                                       |                                         |
+| ------------------------------------- | --------------------------------------- |
+| ![Overview](docs/assets/overview.png) | ![Endpoints](docs/assets/endpoints.png) |
+
+## CLI
+
+```txt
+xtandard-webhooks serve            # panel + dispatcher from env
+xtandard-webhooks dispatch         # dispatcher only (split worker)
+xtandard-webhooks init             # create an app + example event type
+xtandard-webhooks list-apps
+xtandard-webhooks list-endpoints --app acme
+xtandard-webhooks publish --app acme --type invoice.paid --data '{"n":1}'
+xtandard-webhooks retry --app acme --delivery dlv_…
+xtandard-webhooks verify --secret whsec_… --payload-file body.json --headers-file headers.json
+xtandard-webhooks listen --port 4000 --secret whsec_…   # local inspecting receiver
+xtandard-webhooks sign --secret whsec_… --data '{"n":1}' --url http://localhost:4000
+```
+
+Env contract (storage drivers, auth, retention, `RETRY_SCHEDULE`, …): [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
+
+## Testing webhooks
+
+Self-hosted equivalents of webhook.site / Svix Play / the Standard Webhooks simulator — no hosting, no accounts:
+
+- **`xtandard-webhooks listen`** — a local inspecting receiver: point an endpoint at `http://localhost:4000` and every incoming webhook is pretty-printed; with `--secret` it verifies the signature (VERIFIED/FAILED) and answers 401 on failure so senders exercise their retry path.
+- **`xtandard-webhooks sign`** — the signature playground: builds a fully signed request from a secret + payload, printing the headers/body and a ready-to-run `curl` (with `--url`).
+- **Panel "Request" inspector** — on any delivery's detail, see the exact signed request it sends (method, URL, all headers including `webhook-signature`, body) with a Copy-as-curl button.
+- **`@xtandard/webhooks/testing`** — programmatic: `createTestReceiver` (a verifying local receiver) + `drainDeliveries` for deterministic tests.
+
+See [docs/TESTING.md](docs/TESTING.md).
+
+## Documentation
+
+[Getting started](docs/GETTING_STARTED.md) · [Architecture](docs/ARCHITECTURE.md) · [Delivery](docs/DELIVERY.md) · [Signing](docs/SIGNING.md) · [Storage](docs/STORAGE.md) · [Portal](docs/PORTAL.md) · [Auth](docs/AUTH.md) · [Authorization](docs/AUTHORIZATION.md) · [Hooks](docs/HOOKS.md) · [UI](docs/UI.md) · [Adapters](docs/ADAPTERS.md) · [Deployment](docs/DEPLOYMENT.md) · [Testing](docs/TESTING.md) · [Releases](docs/RELEASES.md) · [ADRs](docs/ADR)
+
+## Project status
+
+ZeroVer (`0.x`) and pre-first-publish: the surface is stabilizing, minor versions may break, and feedback shapes it — issues welcome. Anti-bloat is a core value: when a feature is composable from an existing primitive in ten lines, we document the recipe instead of shipping the subsystem.
+
+## License
+
+[MIT](./LICENSE)

package/bin/xtandard-webhooks.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../dist/cli.mjs";
+run(process.argv.slice(2)).then((code) => process.exit(code));

package/dist/basic-BIW3Rvuz.cjs

@@ -0,0 +1,199 @@
+const require_keys = require("./keys-FiKpaVHX.cjs");
+let node_crypto = require("node:crypto");
+//#region src/auth/basic.ts
+/**
+* HTTP Basic authentication {@link AuthProvider}.
+*
+* Parses the `Authorization: Basic <base64>` header, looks the username up in a
+* configured user list, and verifies the supplied password using one of three
+* credential modes (in order of preference):
+*
+* 1. A custom `passwordVerifier(username, password)` callback — for delegating
+*    to your own user store.
+* 2. A `passwordHash` produced by {@link hashPassword} — scrypt with a random
+*    salt, verified in constant time. **Recommended for production.**
+* 3. A plain `password` field — **development only**. Never ship real
+*    credentials as plaintext; they are compared in constant time but stored as
+*    cleartext in your config.
+*
+* On success the matched user becomes a {@link Principal}; on any failure
+* (missing/malformed header, unknown user, bad password) `authenticate` returns
+* `null`. {@link AuthProvider.challenge} emits a `401` with a
+* `WWW-Authenticate: Basic realm="…"` header so browsers prompt for credentials.
+*
+* Password hashing uses Node's `node:crypto` `scrypt`, which is available in
+* both Node and Bun — no Bun-only APIs and no extra dependencies.
+*
+* @module
+*/
+var basic_exports = /* @__PURE__ */ require_keys.__exportAll({
+	basicAuth: () => basicAuth,
+	hashPassword: () => hashPassword,
+	verifyPassword: () => verifyPassword
+});
+/** scrypt key length (bytes) used by {@link hashPassword}. */
+const KEY_LENGTH = 64;
+/** Salt length (bytes) used by {@link hashPassword}. */
+const SALT_LENGTH = 16;
+/** Prefix identifying a {@link hashPassword} digest. */
+const SCRYPT_PREFIX = "scrypt";
+const scryptAsync = (password, salt, keylen) => new Promise((resolve, reject) => {
+	(0, node_crypto.scrypt)(password, salt, keylen, (err, derivedKey) => {
+		if (err) reject(err);
+		else resolve(derivedKey);
+	});
+});
+/** Lowercase hex encoding of a buffer. */
+const toHex = (buf) => buf.toString("hex");
+/**
+* Hash a password with scrypt and a fresh random salt.
+*
+* The returned string is self-describing and safe to store in config or a
+* database: `scrypt$<saltHex>$<hashHex>`. Pass it back to
+* {@link verifyPassword} (or supply it as a user's `passwordHash`) to check a
+* candidate password.
+*
+* @example
+* ```ts
+* const stored = await hashPassword("correct horse battery staple");
+* // → "scrypt$<32 hex chars>$<128 hex chars>"
+* ```
+*/
+async function hashPassword(password) {
+	const salt = (0, node_crypto.randomBytes)(SALT_LENGTH);
+	const derived = await scryptAsync(password, salt, KEY_LENGTH);
+	return `${SCRYPT_PREFIX}$${toHex(salt)}$${toHex(derived)}`;
+}
+/**
+* Verify a candidate `password` against a digest produced by
+* {@link hashPassword}.
+*
+* Re-derives the scrypt hash using the stored salt and compares it to the stored
+* hash with `crypto.timingSafeEqual` (constant time). Returns `false` — rather
+* than throwing — for malformed or unrecognized digests.
+*/
+async function verifyPassword(password, stored) {
+	const parts = stored.split("$");
+	if (parts.length !== 3 || parts[0] !== SCRYPT_PREFIX) return false;
+	const saltHex = parts[1];
+	const hashHex = parts[2];
+	if (!saltHex || !hashHex) return false;
+	let salt;
+	let expected;
+	try {
+		salt = Buffer.from(saltHex, "hex");
+		expected = Buffer.from(hashHex, "hex");
+	} catch {
+		return false;
+	}
+	if (salt.length === 0 || expected.length === 0) return false;
+	const derived = await scryptAsync(password, salt, expected.length);
+	if (derived.length !== expected.length) return false;
+	return (0, node_crypto.timingSafeEqual)(derived, expected);
+}
+/** Constant-time string comparison that does not leak length via early exit. */
+function constantTimeEquals(a, b) {
+	const bufA = Buffer.from(a, "utf8");
+	const bufB = Buffer.from(b, "utf8");
+	if (bufA.length !== bufB.length) {
+		(0, node_crypto.timingSafeEqual)(bufA, bufA);
+		return false;
+	}
+	return (0, node_crypto.timingSafeEqual)(bufA, bufB);
+}
+/** Decode the `Authorization: Basic <base64>` header, or `null` if absent/malformed. */
+function parseBasicHeader(request) {
+	const header = request.headers.get("authorization");
+	if (!header) return null;
+	const [scheme, encoded] = header.split(" ", 2);
+	if (!scheme || scheme.toLowerCase() !== "basic" || !encoded) return null;
+	let decoded;
+	try {
+		decoded = Buffer.from(encoded, "base64").toString("utf8");
+	} catch {
+		return null;
+	}
+	const sep = decoded.indexOf(":");
+	if (sep < 0) return null;
+	return {
+		username: decoded.slice(0, sep),
+		password: decoded.slice(sep + 1)
+	};
+}
+/** Build the {@link Principal} for a successfully authenticated user. */
+function principalFor(user) {
+	return {
+		id: user.id ?? user.username,
+		name: user.username,
+		...user.email !== void 0 ? { email: user.email } : {},
+		...user.roles !== void 0 ? { roles: user.roles } : {}
+	};
+}
+/**
+* Create an HTTP Basic {@link AuthProvider}.
+*
+* @example
+* ```ts
+* import { basicAuth, hashPassword } from "@xtandard/webhooks/auth/basic";
+*
+* const auth = basicAuth({
+*   realm: "Webhooks Admin",
+*   users: [
+*     { username: "admin", passwordHash: await hashPassword("s3cret"), roles: ["admin"] },
+*   ],
+* });
+* ```
+*/
+function basicAuth(options) {
+	const realm = options.realm ?? "xtandard-webhooks";
+	const usersByName = /* @__PURE__ */ new Map();
+	for (const user of options.users) usersByName.set(user.username, user);
+	return {
+		async authenticate(request) {
+			const creds = parseBasicHeader(request);
+			if (!creds) return null;
+			const user = usersByName.get(creds.username);
+			if (!user) {
+				if (options.passwordVerifier) await options.passwordVerifier(creds.username, creds.password);
+				return null;
+			}
+			if (options.passwordVerifier) return await options.passwordVerifier(creds.username, creds.password) ? principalFor(user) : null;
+			if (user.passwordHash !== void 0) return await verifyPassword(creds.password, user.passwordHash) ? principalFor(user) : null;
+			if (user.password !== void 0) return constantTimeEquals(creds.password, user.password) ? principalFor(user) : null;
+			return null;
+		},
+		challenge(_request) {
+			return new Response("Unauthorized", {
+				status: 401,
+				headers: { "WWW-Authenticate": `Basic realm="${realm}"` }
+			});
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "basicAuth", {
+	enumerable: true,
+	get: function() {
+		return basicAuth;
+	}
+});
+Object.defineProperty(exports, "basic_exports", {
+	enumerable: true,
+	get: function() {
+		return basic_exports;
+	}
+});
+Object.defineProperty(exports, "hashPassword", {
+	enumerable: true,
+	get: function() {
+		return hashPassword;
+	}
+});
+Object.defineProperty(exports, "verifyPassword", {
+	enumerable: true,
+	get: function() {
+		return verifyPassword;
+	}
+});
+
+//# sourceMappingURL=basic-BIW3Rvuz.cjs.map

package/dist/basic-BIW3Rvuz.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-BIW3Rvuz.cjs","names":[],"sources":["../src/auth/basic.ts"],"sourcesContent":["/**\n * HTTP Basic authentication {@link AuthProvider}.\n *\n * Parses the `Authorization: Basic <base64>` header, looks the username up in a\n * configured user list, and verifies the supplied password using one of three\n * credential modes (in order of preference):\n *\n * 1. A custom `passwordVerifier(username, password)` callback — for delegating\n *    to your own user store.\n * 2. A `passwordHash` produced by {@link hashPassword} — scrypt with a random\n *    salt, verified in constant time. **Recommended for production.**\n * 3. A plain `password` field — **development only**. Never ship real\n *    credentials as plaintext; they are compared in constant time but stored as\n *    cleartext in your config.\n *\n * On success the matched user becomes a {@link Principal}; on any failure\n * (missing/malformed header, unknown user, bad password) `authenticate` returns\n * `null`. {@link AuthProvider.challenge} emits a `401` with a\n * `WWW-Authenticate: Basic realm=\"…\"` header so browsers prompt for credentials.\n *\n * Password hashing uses Node's `node:crypto` `scrypt`, which is available in\n * both Node and Bun — no Bun-only APIs and no extra dependencies.\n *\n * @module\n */\n\nimport { randomBytes, scrypt as scryptCb, timingSafeEqual } from \"node:crypto\";\nimport type { AuthProvider, Principal } from \"./contract.ts\";\n\n/** scrypt key length (bytes) used by {@link hashPassword}. */\nconst KEY_LENGTH = 64;\n/** Salt length (bytes) used by {@link hashPassword}. */\nconst SALT_LENGTH = 16;\n/** Prefix identifying a {@link hashPassword} digest. */\nconst SCRYPT_PREFIX = \"scrypt\";\n\nconst scryptAsync = (password: string, salt: Buffer, keylen: number): Promise<Buffer> =>\n  new Promise((resolve, reject) => {\n    scryptCb(password, salt, keylen, (err, derivedKey) => {\n      if (err) reject(err);\n      else resolve(derivedKey);\n    });\n  });\n\n/** Lowercase hex encoding of a buffer. */\nconst toHex = (buf: Buffer): string => buf.toString(\"hex\");\n\n/**\n * Hash a password with scrypt and a fresh random salt.\n *\n * The returned string is self-describing and safe to store in config or a\n * database: `scrypt$<saltHex>$<hashHex>`. Pass it back to\n * {@link verifyPassword} (or supply it as a user's `passwordHash`) to check a\n * candidate password.\n *\n * @example\n * ```ts\n * const stored = await hashPassword(\"correct horse battery staple\");\n * // → \"scrypt$<32 hex chars>$<128 hex chars>\"\n * ```\n */\nexport async function hashPassword(password: string): Promise<string> {\n  const salt = randomBytes(SALT_LENGTH);\n  const derived = await scryptAsync(password, salt, KEY_LENGTH);\n  return `${SCRYPT_PREFIX}$${toHex(salt)}$${toHex(derived)}`;\n}\n\n/**\n * Verify a candidate `password` against a digest produced by\n * {@link hashPassword}.\n *\n * Re-derives the scrypt hash using the stored salt and compares it to the stored\n * hash with `crypto.timingSafeEqual` (constant time). Returns `false` — rather\n * than throwing — for malformed or unrecognized digests.\n */\nexport async function verifyPassword(password: string, stored: string): Promise<boolean> {\n  const parts = stored.split(\"$\");\n  if (parts.length !== 3 || parts[0] !== SCRYPT_PREFIX) return false;\n  const saltHex = parts[1];\n  const hashHex = parts[2];\n  if (!saltHex || !hashHex) return false;\n\n  let salt: Buffer;\n  let expected: Buffer;\n  try {\n    salt = Buffer.from(saltHex, \"hex\");\n    expected = Buffer.from(hashHex, \"hex\");\n  } catch {\n    return false;\n  }\n  if (salt.length === 0 || expected.length === 0) return false;\n\n  const derived = await scryptAsync(password, salt, expected.length);\n  if (derived.length !== expected.length) return false;\n  return timingSafeEqual(derived, expected);\n}\n\n/** A configured user for {@link basicAuth}. */\nexport interface BasicAuthUser {\n  /** The login name, matched against the Basic credentials. */\n  username: string;\n  /**\n   * A digest produced by {@link hashPassword} (`scrypt$<salt>$<hash>`).\n   * Preferred for production.\n   */\n  passwordHash?: string;\n  /**\n   * A plaintext password. **Development only** — prefer `passwordHash`. Compared\n   * in constant time but stored as cleartext in your config.\n   */\n  password?: string;\n  /** Roles attached to the resulting {@link Principal}. */\n  roles?: string[];\n  /** Email attached to the resulting {@link Principal}. */\n  email?: string;\n  /** Principal id. Defaults to {@link BasicAuthUser.username} when omitted. */\n  id?: string;\n}\n\n/** Options for {@link basicAuth}. */\nexport interface BasicAuthOptions {\n  /** The known users. */\n  users: BasicAuthUser[];\n  /**\n   * Realm advertised in the `WWW-Authenticate` header on challenge.\n   * @default \"xtandard-webhooks\"\n   */\n  realm?: string;\n  /**\n   * Custom verifier. When supplied it takes precedence over `passwordHash` and\n   * `password` for matched users — delegate to your own credential store and\n   * return `true` to accept.\n   */\n  passwordVerifier?: (username: string, password: string) => Promise<boolean> | boolean;\n}\n\n/** Constant-time string comparison that does not leak length via early exit. */\nfunction constantTimeEquals(a: string, b: string): boolean {\n  const bufA = Buffer.from(a, \"utf8\");\n  const bufB = Buffer.from(b, \"utf8\");\n  // timingSafeEqual requires equal lengths; hash to a fixed width first so the\n  // comparison time does not depend on the inputs.\n  if (bufA.length !== bufB.length) {\n    // Still perform a comparison to keep timing uniform, then fail.\n    timingSafeEqual(bufA, bufA);\n    return false;\n  }\n  return timingSafeEqual(bufA, bufB);\n}\n\n/** Result of parsing an `Authorization: Basic` header. */\ninterface BasicCredentials {\n  username: string;\n  password: string;\n}\n\n/** Decode the `Authorization: Basic <base64>` header, or `null` if absent/malformed. */\nfunction parseBasicHeader(request: Request): BasicCredentials | null {\n  const header = request.headers.get(\"authorization\");\n  if (!header) return null;\n  const [scheme, encoded] = header.split(\" \", 2);\n  if (!scheme || scheme.toLowerCase() !== \"basic\" || !encoded) return null;\n\n  let decoded: string;\n  try {\n    decoded = Buffer.from(encoded, \"base64\").toString(\"utf8\");\n  } catch {\n    return null;\n  }\n  const sep = decoded.indexOf(\":\");\n  if (sep < 0) return null;\n  return { username: decoded.slice(0, sep), password: decoded.slice(sep + 1) };\n}\n\n/** Build the {@link Principal} for a successfully authenticated user. */\nfunction principalFor(user: BasicAuthUser): Principal {\n  return {\n    id: user.id ?? user.username,\n    name: user.username,\n    ...(user.email !== undefined ? { email: user.email } : {}),\n    ...(user.roles !== undefined ? { roles: user.roles } : {}),\n  };\n}\n\n/**\n * Create an HTTP Basic {@link AuthProvider}.\n *\n * @example\n * ```ts\n * import { basicAuth, hashPassword } from \"@xtandard/webhooks/auth/basic\";\n *\n * const auth = basicAuth({\n *   realm: \"Webhooks Admin\",\n *   users: [\n *     { username: \"admin\", passwordHash: await hashPassword(\"s3cret\"), roles: [\"admin\"] },\n *   ],\n * });\n * ```\n */\nexport function basicAuth(options: BasicAuthOptions): AuthProvider {\n  const realm = options.realm ?? \"xtandard-webhooks\";\n  const usersByName = new Map<string, BasicAuthUser>();\n  for (const user of options.users) usersByName.set(user.username, user);\n\n  return {\n    async authenticate(request: Request): Promise<Principal | null> {\n      const creds = parseBasicHeader(request);\n      if (!creds) return null;\n\n      const user = usersByName.get(creds.username);\n      if (!user) {\n        // Run a dummy verification to keep timing roughly uniform for unknown\n        // users versus known users.\n        if (options.passwordVerifier) {\n          await options.passwordVerifier(creds.username, creds.password);\n        }\n        return null;\n      }\n\n      // (a) custom verifier wins.\n      if (options.passwordVerifier) {\n        const ok = await options.passwordVerifier(creds.username, creds.password);\n        return ok ? principalFor(user) : null;\n      }\n\n      // (b) scrypt hash.\n      if (user.passwordHash !== undefined) {\n        const ok = await verifyPassword(creds.password, user.passwordHash);\n        return ok ? principalFor(user) : null;\n      }\n\n      // (c) dev-only plaintext.\n      if (user.password !== undefined) {\n        const ok = constantTimeEquals(creds.password, user.password);\n        return ok ? principalFor(user) : null;\n      }\n\n      return null;\n    },\n\n    challenge(_request: Request): Response {\n      return new Response(\"Unauthorized\", {\n        status: 401,\n        headers: { \"WWW-Authenticate\": `Basic realm=\"${realm}\"` },\n      });\n    },\n  };\n}\n"],"mappings":"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"}