@daloyjs/core 0.36.0 → 0.37.0

package/dist/geo-block.js

@@ -0,0 +1,153 @@
+/**
+ * Country-level access control for {@link Hooks}. The {@link geoBlock}
+ * middleware enforces ISO 3166-1 alpha-2 country allow- and deny-lists by
+ * mapping the client IP to a country **using an operator-supplied lookup** —
+ * Daloy bundles no GeoIP database and adds no runtime dependency, keeping the
+ * `@daloyjs/core` zero-dependency floor intact.
+ *
+ * Two resolution strategies are supported, exactly one of which must be wired:
+ *
+ * - `lookupCountry(ip)` — you own the IP → country mapping (e.g. a MaxMind
+ *   GeoLite2 reader, an `ip2location` reader, or your own table). Daloy
+ *   resolves the client IP (reusing the same `X-Forwarded-For` / `X-Real-IP`
+ *   handling as {@link "./ip-restriction.js".ipRestriction}) and hands you the
+ *   string.
+ * - `resolveCountry(ctx)` — the country is already attached to the request by
+ *   an upstream edge (e.g. Cloudflare's `CF-IPCountry`, AWS CloudFront's
+ *   `CloudFront-Viewer-Country`, Vercel's `x-vercel-ip-country`); you read it
+ *   straight off the context.
+ *
+ * Like the other network guards this fails **closed for allow-lists** (an
+ * unknown country is rejected when an allow-list is configured) and **open for
+ * deny-only** configurations, so a missing lookup cannot silently widen access.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { ForbiddenError } from "./errors.js";
+/** @internal Validate + normalise a configured country code, or throw. */
+function normalizeConfiguredCode(input) {
+    const code = input.trim().toUpperCase();
+    if (!/^[A-Z0-9]{2}$/.test(code)) {
+        throw new Error(`geoBlock(): invalid country code ${JSON.stringify(input)}; expected a ` +
+            "2-character ISO 3166-1 alpha-2 code.");
+    }
+    return code;
+}
+/** @internal Default resolver: deliberately yields nothing (fail closed). */
+function noIpResolver(_ctx) {
+    return undefined;
+}
+/** @internal Read the leading `X-Forwarded-For` / `X-Real-IP` hop. */
+function forwardedIpResolver(ctx) {
+    const headers = ctx.request.headers;
+    const forwarded = headers.get("x-forwarded-for");
+    if (forwarded) {
+        const first = forwarded.split(",")[0]?.trim();
+        if (first)
+            return first;
+    }
+    return ctx.request.headers.get("x-real-ip") ?? undefined;
+}
+/**
+ * Block or allow requests by client country. Daloy ships no GeoIP database;
+ * supply either an IP → country `lookupCountry` (e.g. a MaxMind reader) or a
+ * `resolveCountry` that reads an edge-injected country header.
+ *
+ * @example MaxMind-style IP lookup behind a trusted proxy
+ * ```ts
+ * import maxmind from "maxmind"; // operator dependency, not a Daloy one
+ * const reader = await maxmind.open<{ country?: { iso_code?: string } }>("GeoLite2-Country.mmdb");
+ * app.use(geoBlock({
+ *   deny: ["KP", "IR"],
+ *   trustProxyHeaders: true,
+ *   lookupCountry: (ip) => reader.get(ip)?.country?.iso_code,
+ * }));
+ * ```
+ *
+ * @example Cloudflare edge header (no IP lookup needed)
+ * ```ts
+ * app.use(geoBlock({
+ *   allow: ["US", "CA", "GB"],
+ *   resolveCountry: (ctx) => ctx.request.headers.get("cf-ipcountry"),
+ * }));
+ * ```
+ *
+ * On reject the middleware throws a {@link ForbiddenError}, which Daloy renders
+ * as RFC 9457 `application/problem+json` with `Cache-Control: no-store`.
+ *
+ * @param opts - Geo-blocking configuration.
+ * @returns {@link Hooks} to register via `app.use(...)`.
+ * @throws Error when neither `allow` nor `deny` is provided, when both or
+ *   neither of `lookupCountry` / `resolveCountry` are provided, when a country
+ *   code is malformed, or when `mode` is invalid.
+ * @since 0.37.0
+ */
+export function geoBlock(opts) {
+    if (!opts.allow?.length && !opts.deny?.length) {
+        throw new Error('geoBlock(): at least one of "allow" or "deny" must be provided.');
+    }
+    const hasLookup = typeof opts.lookupCountry === "function";
+    const hasResolve = typeof opts.resolveCountry === "function";
+    if (hasLookup === hasResolve) {
+        throw new Error('geoBlock(): exactly one of "lookupCountry" or "resolveCountry" must ' +
+            "be provided.");
+    }
+    if (opts.mode !== undefined && opts.mode !== "block" && opts.mode !== "log") {
+        throw new Error(`geoBlock(): invalid mode ${JSON.stringify(opts.mode)}; expected ` +
+            '"block" or "log".');
+    }
+    const allow = new Set((opts.allow ?? []).map(normalizeConfiguredCode));
+    const deny = new Set((opts.deny ?? []).map(normalizeConfiguredCode));
+    // Allow-lists fail closed on an unknown country; deny-only fails open.
+    const allowUnknown = opts.allowUnknownCountry ?? allow.size === 0;
+    const mode = opts.mode ?? "block";
+    const message = opts.message ?? "Access from your region is not permitted";
+    const stateKey = opts.stateKey ?? "geo";
+    const onBlock = opts.onBlock;
+    const lookupCountry = opts.lookupCountry;
+    const resolveCountry = opts.resolveCountry;
+    const resolveIp = opts.resolveIp ??
+        (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    return {
+        async beforeHandle(ctx) {
+            let ip;
+            let rawCountry;
+            if (resolveCountry) {
+                rawCountry = await resolveCountry(ctx);
+            }
+            else {
+                ip = resolveIp(ctx) ?? undefined;
+                rawCountry = ip ? await lookupCountry(ip) : undefined;
+            }
+            const country = rawCountry && rawCountry.trim()
+                ? rawCountry.trim().toUpperCase()
+                : undefined;
+            let reason;
+            if (!country) {
+                if (!allowUnknown)
+                    reason = "unknown_country";
+            }
+            else if (deny.has(country)) {
+                reason = "denied_country";
+            }
+            else if (allow.size > 0 && !allow.has(country)) {
+                reason = "not_in_allowlist";
+            }
+            if (reason) {
+                const decision = {
+                    ...(ip ? { ip } : {}),
+                    ...(country ? { country } : {}),
+                    reason,
+                };
+                onBlock?.(decision);
+                if (mode === "block")
+                    throw new ForbiddenError(message);
+                return;
+            }
+            // Allowed: expose the resolved country to downstream handlers.
+            const state = country ? { country } : {};
+            ctx.state[stateKey] = state;
+        },
+    };
+}

package/dist/hashing.d.ts

@@ -40,7 +40,8 @@
  *
  * @param password - The plaintext password. UTF-8 encoded internally.
  * @returns A PHC-style hash string safe to store in a database column.
- * @throws {TypeError} When `password` is empty.
+ * @throws {TypeError} When `password` is empty or exceeds
+ * {@link MAX_PASSWORD_BYTES} UTF-8 bytes.
  * @since 0.15.0
  */
 export declare function passwordHash(password: string): Promise<string>;

package/dist/hashing.js

@@ -31,6 +31,11 @@ const SCRYPT_KEYLEN = 32;
 const SCRYPT_SALTLEN = 16;
 // Generous max — covers OWASP's recommended `N = 2^17` at `r = 8`, `p = 1`.
 const SCRYPT_MAXMEM = 192 * 1024 * 1024;
+// Upper bound on password size (UTF-8 bytes). scrypt runs PBKDF2-HMAC-SHA256
+// over the full password, so an unbounded input lets an attacker amplify CPU
+// per call. OWASP's Password Storage Cheat Sheet recommends capping length;
+// 4096 bytes is well above any legitimate passphrase while blocking abuse.
+const MAX_PASSWORD_BYTES = 4096;
 function scryptAsync(password, salt, keylen) {
     return new Promise((resolve, reject) => {
         scryptCb(password, salt, keylen, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM }, (err, key) => {
@@ -75,13 +80,17 @@ function fromBase64(s) {
  *
  * @param password - The plaintext password. UTF-8 encoded internally.
  * @returns A PHC-style hash string safe to store in a database column.
- * @throws {TypeError} When `password` is empty.
+ * @throws {TypeError} When `password` is empty or exceeds
+ * {@link MAX_PASSWORD_BYTES} UTF-8 bytes.
  * @since 0.15.0
  */
 export async function passwordHash(password) {
     if (typeof password !== "string" || password.length === 0) {
         throw new TypeError("password must be a non-empty string");
     }
+    if (Buffer.byteLength(password, "utf8") > MAX_PASSWORD_BYTES) {
+        throw new TypeError(`password must not exceed ${MAX_PASSWORD_BYTES} bytes`);
+    }
     const salt = randomBytes(SCRYPT_SALTLEN);
     const key = await scryptAsync(Buffer.from(password, "utf8"), salt, SCRYPT_KEYLEN);
     return `$scrypt$N=${SCRYPT_N},r=${SCRYPT_R},p=${SCRYPT_P}$${toBase64(salt)}$${toBase64(key)}`;
@@ -130,6 +139,8 @@ function parsePhc(s) {
 export async function passwordVerify(password, storedHash) {
     if (typeof password !== "string" || password.length === 0)
         return false;
+    if (Buffer.byteLength(password, "utf8") > MAX_PASSWORD_BYTES)
+        return false;
     const parsed = parsePhc(storedHash);
     if (!parsed)
         return false;

package/dist/http-signatures.d.ts

@@ -0,0 +1,303 @@
+/**
+ * HTTP Message Signatures (RFC 9421).
+ *
+ * First-party, dependency-free sign + verify for server-to-server request
+ * authentication. Where {@link "./security.js" | verifyWebhookSignature} binds
+ * an HMAC to a request *body* and {@link "./mtls.js" | clientCertAuth}
+ * authenticates the TLS *peer*, HTTP Message Signatures bind a signature to a
+ * caller-chosen set of **HTTP message components** (method, path, authority,
+ * selected headers, …) carried in the standard `Signature` /
+ * `Signature-Input` headers — the IETF-standard answer to "prove this internal
+ * call came from a trusted peer."
+ *
+ * The implementation is runtime-portable (WebCrypto only — no `node:` imports)
+ * and secure-by-default on the verify path:
+ *
+ * - The verifier requires an explicit {@link VerifyMessageOptions.algorithms}
+ *   allowlist; there is no implicit "accept any algorithm" mode, and a
+ *   resolved key may pin its own algorithm to defeat algorithm-confusion.
+ * - `created` is required by default and the signature is rejected once it is
+ *   older than {@link DEFAULT_MAX_SIGNATURE_AGE_SECONDS}, or if `created` is in
+ *   the future / `expires` has passed (outside a small clock-skew tolerance).
+ * - A configurable {@link VerifyMessageOptions.requiredComponents} set must be
+ *   covered, so a peer cannot sign an empty/irrelevant component set.
+ * - Raw HMAC keys must be at least 32 bytes (RFC 7518 §3.2 floor); SHA-1 and
+ *   `alg: "none"`-style escapes do not exist.
+ *
+ * Supported algorithms map 1:1 onto the RFC 9421 HTTP Signature Algorithms
+ * registry: `hmac-sha256`, `ed25519`, `ecdsa-p256-sha256`, `ecdsa-p384-sha384`,
+ * `rsa-pss-sha512`, and `rsa-v1_5-sha256`.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { Hooks } from "./types.js";
+/**
+ * HTTP Signature algorithm identifiers from the RFC 9421 registry that this
+ * module can sign and verify with.
+ *
+ * @since 0.37.0
+ */
+export type HttpSignatureAlgorithm = "hmac-sha256" | "ed25519" | "ecdsa-p256-sha256" | "ecdsa-p384-sha384" | "rsa-pss-sha512" | "rsa-v1_5-sha256";
+/** Key material accepted by the signer/verifier. */
+export type HttpSignatureKeyMaterial = CryptoKey | Uint8Array | JsonWebKey;
+/**
+ * A resolved verification key, optionally pinning the algorithm it may be used
+ * with. Returning the `alg` from {@link VerifyMessageOptions.resolveKey}
+ * defeats algorithm-confusion: the signature's declared `alg` must then match.
+ *
+ * @since 0.37.0
+ */
+export interface HttpSignatureKey {
+    /** Algorithm this key is bound to. When set, the message `alg` must match. */
+    alg?: HttpSignatureAlgorithm;
+    /** Raw secret (HMAC), `CryptoKey`, or JWK. */
+    key: HttpSignatureKeyMaterial;
+}
+/** Default signature label used when the caller does not supply one. */
+export declare const DEFAULT_SIGNATURE_LABEL = "sig1";
+/**
+ * Default maximum age (seconds) a signature's `created` timestamp may have
+ * before the verifier rejects it as stale. Mirrors the webhook-HMAC and
+ * Standard-Webhooks five-minute convention.
+ *
+ * @since 0.37.0
+ */
+export declare const DEFAULT_MAX_SIGNATURE_AGE_SECONDS = 300;
+/** Default clock-skew tolerance (seconds) for future `created` / `expires`. */
+export declare const DEFAULT_SIGNATURE_CLOCK_SKEW_SECONDS = 60;
+/**
+ * Options for {@link signMessage}. Describes the message to cover and the key
+ * to sign with.
+ *
+ * @since 0.37.0
+ */
+export interface SignMessageOptions {
+    /** HTTP method (e.g. `"POST"`). */
+    method: string;
+    /** Absolute request URL. */
+    url: string | URL;
+    /** Request headers referenced by header components. */
+    headers?: HeadersInit;
+    /** Response status code (only when signing a response, for `@status`). */
+    status?: number;
+    /**
+     * Covered component identifiers, in order. Derived components start with `@`
+     * (`@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`,
+     * `@path`, `@query`, `@query-param;name="…"`, `@status`); everything else is
+     * a lowercased HTTP header name. Defaults to `["@method", "@target-uri"]`.
+     */
+    components?: string[];
+    /** Algorithm to sign with. */
+    alg: HttpSignatureAlgorithm;
+    /** Signing key (HMAC secret, `CryptoKey`, or JWK). */
+    key: HttpSignatureKeyMaterial;
+    /** Key identifier surfaced as the `keyid` parameter (recommended). */
+    keyid?: string;
+    /** Signature label in the dictionary. Defaults to {@link DEFAULT_SIGNATURE_LABEL}. */
+    label?: string;
+    /** `created` timestamp (Unix seconds). Defaults to the current time. */
+    created?: number;
+    /** Optional `expires` timestamp (Unix seconds). */
+    expires?: number;
+    /** Optional `nonce` for replay defense. */
+    nonce?: string;
+    /** Optional `tag` (application-specific signature label). */
+    tag?: string;
+    /** Whether to emit the `alg` parameter. Defaults to `true`. */
+    includeAlg?: boolean;
+    /** Clock used to default `created`. Returns milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Computed `Signature` / `Signature-Input` header values plus the signature
+ * base that was signed (useful for debugging / interop testing).
+ *
+ * @since 0.37.0
+ */
+export interface MessageSignature {
+    /** Value for the `Signature-Input` header. */
+    signatureInput: string;
+    /** Value for the `Signature` header. */
+    signature: string;
+    /** The exact UTF-8 signature base that was signed. */
+    signatureBase: string;
+    /** The label used in the dictionary. */
+    label: string;
+}
+/**
+ * Compute HTTP Message Signature header values (RFC 9421) over the described
+ * message.
+ *
+ * @throws {TypeError} for unsupported algorithms, weak HMAC keys, or
+ *   unserializable parameter values.
+ * @throws {Error} when a covered component cannot be resolved (e.g. a covered
+ *   header is missing) or WebCrypto is unavailable.
+ * @since 0.37.0
+ */
+export declare function signMessage(opts: SignMessageOptions): Promise<MessageSignature>;
+/**
+ * Options for {@link signRequest}; the method, URL, and headers are taken from
+ * the {@link Request} itself.
+ *
+ * @since 0.37.0
+ */
+export type SignRequestOptions = Omit<SignMessageOptions, "method" | "url" | "headers" | "status">;
+/**
+ * Sign an outbound {@link Request} and return a new `Request` with the
+ * `Signature` and `Signature-Input` headers attached. The original request is
+ * not mutated.
+ *
+ * @since 0.37.0
+ */
+export declare function signRequest(request: Request, opts: SignRequestOptions): Promise<Request>;
+/** Information passed to {@link VerifyMessageOptions.resolveKey}. */
+export interface KeyResolutionInfo {
+    /** The `keyid` parameter, if the signer included one. */
+    keyid?: string;
+    /** The declared `alg` parameter, if present. */
+    alg?: HttpSignatureAlgorithm;
+    /** The signature label being verified. */
+    label: string;
+    /** The `tag` parameter, if present. */
+    tag?: string;
+}
+/** Successful verification result. */
+export interface VerifySuccess {
+    valid: true;
+    /** The verified signature label. */
+    label: string;
+    /** Algorithm used. */
+    alg: HttpSignatureAlgorithm;
+    /** The `keyid` parameter, if present. */
+    keyid?: string;
+    /** Covered component identifiers (serialized form). */
+    components: string[];
+    /** `created` timestamp (Unix seconds), if present. */
+    created?: number;
+    /** `expires` timestamp (Unix seconds), if present. */
+    expires?: number;
+    /** `nonce` parameter, if present. */
+    nonce?: string;
+    /** `tag` parameter, if present. */
+    tag?: string;
+}
+/** Failed verification result. Never throws on a bad signature. */
+export interface VerifyFailure {
+    valid: false;
+    /** Stable machine-readable reason code. */
+    reason: string;
+}
+/** Result of {@link verifyMessage} / {@link verifyRequest}. */
+export type VerifyResult = VerifySuccess | VerifyFailure;
+/**
+ * Options for {@link verifyMessage}. The verifier is secure-by-default: it
+ * requires an explicit {@link algorithms} allowlist and a {@link resolveKey}
+ * callback.
+ *
+ * @since 0.37.0
+ */
+export interface VerifyMessageOptions {
+    /** HTTP method of the received message. */
+    method: string;
+    /** Absolute URL of the received message. */
+    url: string | URL;
+    /** Headers of the received message (must include `Signature` / `Signature-Input`). */
+    headers: HeadersInit;
+    /** Response status code (only when verifying a response). */
+    status?: number;
+    /** Allowed algorithms. Required — there is no implicit "accept any" mode. */
+    algorithms: HttpSignatureAlgorithm[];
+    /**
+     * Resolve the verification key for a signature. Returning an
+     * {@link HttpSignatureKey} with `alg` pins the algorithm (defeats
+     * algorithm-confusion). Return `undefined` to reject an unknown key.
+     */
+    resolveKey: (info: KeyResolutionInfo) => HttpSignatureKey | HttpSignatureKeyMaterial | undefined | Promise<HttpSignatureKey | HttpSignatureKeyMaterial | undefined>;
+    /** Which signature label to verify. Defaults to the sole present label. */
+    label?: string;
+    /**
+     * Component identifiers that MUST be covered. Defaults to
+     * `["@method", "@path"]`. Pass `[]` to disable the check (not recommended).
+     */
+    requiredComponents?: string[];
+    /** Require the `created` parameter. Defaults to `true`. */
+    requireCreated?: boolean;
+    /** Maximum `created` age in seconds. Defaults to {@link DEFAULT_MAX_SIGNATURE_AGE_SECONDS}. */
+    maxAgeSeconds?: number;
+    /** Clock-skew tolerance in seconds. Defaults to {@link DEFAULT_SIGNATURE_CLOCK_SKEW_SECONDS}. */
+    toleranceSeconds?: number;
+    /** Require this exact `tag` parameter value. */
+    requiredTag?: string;
+    /**
+     * Replay check. When provided, a `nonce` is required and the signature is
+     * rejected if this returns `true`.
+     */
+    isReplay?: (nonce: string, info: KeyResolutionInfo) => boolean | Promise<boolean>;
+    /** Clock used for age checks. Returns milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Verify an HTTP Message Signature (RFC 9421) on a received message. Returns a
+ * structured result and never throws on a bad/forged signature — only on a
+ * programming error (e.g. WebCrypto unavailable).
+ *
+ * @since 0.37.0
+ */
+export declare function verifyMessage(opts: VerifyMessageOptions): Promise<VerifyResult>;
+/**
+ * Verify an HTTP Message Signature on an inbound {@link Request}. Thin wrapper
+ * over {@link verifyMessage} that pulls the method, URL, and headers from the
+ * request.
+ *
+ * @since 0.37.0
+ */
+export declare function verifyRequest(request: Request, opts: Omit<VerifyMessageOptions, "method" | "url" | "headers" | "status">): Promise<VerifyResult>;
+/**
+ * Options for {@link httpSignatureAuth}. Extends {@link VerifyMessageOptions}
+ * minus the per-message fields (which come from the request).
+ *
+ * @since 0.37.0
+ */
+export interface HttpSignatureAuthOptions extends Omit<VerifyMessageOptions, "method" | "url" | "headers" | "status"> {
+    /** Detail surfaced on the 401 problem+json response. */
+    message?: string;
+    /** `ctx.state` key the {@link VerifySuccess} is stamped on. Default `"httpSignature"`. */
+    stateKey?: string;
+    /**
+     * When `true`, requests **without** any `Signature` header pass through
+     * unauthenticated (a present-but-invalid signature is still rejected).
+     * Defaults to `false` — signatures are mandatory.
+     */
+    optional?: boolean;
+}
+/**
+ * Middleware that enforces a valid RFC 9421 HTTP Message Signature on inbound
+ * requests. On success the {@link VerifySuccess} is stamped on `ctx.state`; on
+ * a missing (unless `optional`) or invalid signature it throws
+ * {@link UnauthorizedError} (`401` + `Cache-Control: no-store`).
+ *
+ * @since 0.37.0
+ */
+export declare function httpSignatureAuth(opts: HttpSignatureAuthOptions): Hooks;
+/** Hash algorithms supported for {@link contentDigest}. */
+export type ContentDigestAlgorithm = "sha-256" | "sha-512";
+/**
+ * Compute an RFC 9530 `Content-Digest` header value over `body`, e.g.
+ * `sha-256=:<base64>:`. Pair it with a `content-digest` covered component to
+ * bind the request body into the signature, then re-check it against the
+ * received body with {@link verifyContentDigest}.
+ *
+ * @since 0.37.0
+ */
+export declare function contentDigest(body: Uint8Array | string, opts?: {
+    algorithm?: ContentDigestAlgorithm;
+}): Promise<string>;
+/**
+ * Verify that an RFC 9530 `Content-Digest` header value matches `body`.
+ * Returns `false` for any malformed header or mismatch (never throws on bad
+ * input). Only `sha-256` / `sha-512` members are considered.
+ *
+ * @since 0.37.0
+ */
+export declare function verifyContentDigest(header: string, body: Uint8Array | string): Promise<boolean>;