@xtandard/webhooks 0.1.0

package/dist/basic-DKk0Xfuu.mjs

@@ -0,0 +1,176 @@
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
+import { randomBytes, scrypt, timingSafeEqual } from "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__ */ __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) => {
+	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 = 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 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) {
+		timingSafeEqual(bufA, bufA);
+		return false;
+	}
+	return 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
+export { verifyPassword as i, basic_exports as n, hashPassword as r, basicAuth as t };
+
+//# sourceMappingURL=basic-DKk0Xfuu.mjs.map

package/dist/basic-DKk0Xfuu.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-DKk0Xfuu.mjs","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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"}

package/dist/chunk-D7D4PA-g.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };