@daloyjs/core 0.17.0 → 0.28.0

package/dist/combine.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Composition primitives for {@link Hooks} bundles. These let you assemble
+ * curated middleware stacks (`every`), express "any of these proofs is
+ * enough" auth (`some`), and exempt specific paths from a check (`except`).
+ *
+ * @since 0.19.0
+ */
+import type { Hooks, BaseContext } from "./types.js";
+/**
+ * Run every supplied {@link Hooks} bundle in order, pipeline-style.
+ * Equivalent to passing the bundles to `app.use(...)` one after another,
+ * but lets you package a curated stack as a single value (e.g. "the auth
+ * stack for the admin section"). All lifecycle phases compose:
+ *
+ * - `onRequest` / `onResponse` run in registration order.
+ * - `beforeHandle` / `onError` short-circuit on the first `Response`.
+ * - `afterHandle` / `onSend` thread the value through every bundle.
+ *
+ * Symbol-keyed security markers (CORS / CSRF / session / secure-headers)
+ * are forwarded onto the merged bundle so boot-time guards still see them.
+ *
+ * @example
+ * ```ts
+ * const adminStack = every(
+ *   requestId(),
+ *   bearerAuth({ validate: (token) => token === env.ADMIN_TOKEN }),
+ *   rateLimit({ windowMs: 60_000, max: 30, groupId: "admin" }),
+ * );
+ * app.use(adminStack);
+ * ```
+ *
+ * @since 0.19.0
+ */
+export declare function every(...layers: Hooks[]): Hooks;
+/**
+ * Run the supplied bundles until one of them passes its `beforeHandle`
+ * check without throwing. Useful for "this route accepts a bearer token
+ * OR a signed cookie OR an API key" patterns where any single proof of
+ * identity is enough.
+ *
+ * Semantics:
+ *
+ * - The bundles' `beforeHandle` hooks are awaited in order. The first one
+ *   that resolves without throwing wins; its `ctx` mutations (headers,
+ *   `ctx.state`, etc.) are preserved.
+ * - When a bundle returns a `Response`, that response is treated as a
+ *   denial and the next bundle gets a chance to pass. If every bundle
+ *   denies, the first denial wins.
+ * - When the first denial is a thrown error, that error is rethrown so the
+ *   client gets a deterministic status code. Place the auth method whose
+ *   `WWW-Authenticate` challenge you want clients to see first.
+ * - `afterHandle`, `onSend`, `onResponse`, and `onError` from every bundle
+ *   still compose normally — `some()` only changes the `beforeHandle`
+ *   evaluation strategy.
+ *
+ * @example
+ * ```ts
+ * app.use(some(
+ *   bearerAuth({ validate: (token) => token === env.PUBLIC_API_TOKEN }),
+ *   session(),
+ * ));
+ * ```
+ *
+ * @since 0.19.0
+ */
+export declare function some(...layers: Hooks[]): Hooks;
+/**
+ * Pattern accepted by {@link except}. Strings starting with `/` are matched
+ * against the request `pathname`. `*` matches one path segment (no `/`);
+ * `**` matches any suffix (zero or more segments). Functions receive the
+ * request context and return `true` to skip the gated bundle.
+ *
+ * @since 0.19.0
+ */
+export type ExceptPredicate = string | string[] | ((ctx: BaseContext<any, any>) => boolean | Promise<boolean>);
+/**
+ * Run a hook bundle on every request EXCEPT those matching `when`. The
+ * canonical use is "apply auth everywhere except the public endpoints":
+ *
+ * @example
+ * ```ts
+ * app.use(except(
+ *   ["/health", "/openapi.json", "/docs/**"],
+ *   bearerAuth({ validate: (token) => token === env.API_TOKEN }),
+ * ));
+ * ```
+ *
+ * Only the `beforeHandle` phase is gated — the surrounding
+ * `onRequest`/`afterHandle`/`onSend`/`onResponse` phases still run so
+ * shared concerns like request-id propagation are not accidentally
+ * exempted. Wrap each bundle with {@link except} individually when you
+ * need to gate other phases.
+ *
+ * @since 0.19.0
+ */
+export declare function except(when: ExceptPredicate, hooks: Hooks): Hooks;
+//# sourceMappingURL=combine.d.ts.map

package/dist/combine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combine.d.ts","sourceRoot":"","sources":["../src/combine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAE/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,IAAI,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CA8B9C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,MAAM,EAAE,GACR,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAWjE"}

package/dist/combine.js

@@ -0,0 +1,247 @@
+/**
+ * Composition primitives for {@link Hooks} bundles. These let you assemble
+ * curated middleware stacks (`every`), express "any of these proofs is
+ * enough" auth (`some`), and exempt specific paths from a check (`except`).
+ *
+ * @since 0.19.0
+ */
+/**
+ * Run every supplied {@link Hooks} bundle in order, pipeline-style.
+ * Equivalent to passing the bundles to `app.use(...)` one after another,
+ * but lets you package a curated stack as a single value (e.g. "the auth
+ * stack for the admin section"). All lifecycle phases compose:
+ *
+ * - `onRequest` / `onResponse` run in registration order.
+ * - `beforeHandle` / `onError` short-circuit on the first `Response`.
+ * - `afterHandle` / `onSend` thread the value through every bundle.
+ *
+ * Symbol-keyed security markers (CORS / CSRF / session / secure-headers)
+ * are forwarded onto the merged bundle so boot-time guards still see them.
+ *
+ * @example
+ * ```ts
+ * const adminStack = every(
+ *   requestId(),
+ *   bearerAuth({ validate: (token) => token === env.ADMIN_TOKEN }),
+ *   rateLimit({ windowMs: 60_000, max: 30, groupId: "admin" }),
+ * );
+ * app.use(adminStack);
+ * ```
+ *
+ * @since 0.19.0
+ */
+export function every(...layers) {
+    return mergeCombineHooks(layers);
+}
+/**
+ * Run the supplied bundles until one of them passes its `beforeHandle`
+ * check without throwing. Useful for "this route accepts a bearer token
+ * OR a signed cookie OR an API key" patterns where any single proof of
+ * identity is enough.
+ *
+ * Semantics:
+ *
+ * - The bundles' `beforeHandle` hooks are awaited in order. The first one
+ *   that resolves without throwing wins; its `ctx` mutations (headers,
+ *   `ctx.state`, etc.) are preserved.
+ * - When a bundle returns a `Response`, that response is treated as a
+ *   denial and the next bundle gets a chance to pass. If every bundle
+ *   denies, the first denial wins.
+ * - When the first denial is a thrown error, that error is rethrown so the
+ *   client gets a deterministic status code. Place the auth method whose
+ *   `WWW-Authenticate` challenge you want clients to see first.
+ * - `afterHandle`, `onSend`, `onResponse`, and `onError` from every bundle
+ *   still compose normally — `some()` only changes the `beforeHandle`
+ *   evaluation strategy.
+ *
+ * @example
+ * ```ts
+ * app.use(some(
+ *   bearerAuth({ validate: (token) => token === env.PUBLIC_API_TOKEN }),
+ *   session(),
+ * ));
+ * ```
+ *
+ * @since 0.19.0
+ */
+export function some(...layers) {
+    if (layers.length === 0)
+        return {};
+    const stripped = layers.map(({ beforeHandle: _b, ...rest }) => rest);
+    const base = mergeCombineHooks(stripped);
+    const candidates = layers
+        .map((h) => h.beforeHandle)
+        .filter((f) => typeof f === "function");
+    if (candidates.length === 0)
+        return base;
+    return {
+        ...base,
+        async beforeHandle(ctx) {
+            let firstFailure;
+            for (const fn of candidates) {
+                try {
+                    const r = await fn(ctx);
+                    if (r instanceof Response) {
+                        // Treat as a denial — try the next layer.
+                        if (!firstFailure)
+                            firstFailure = { kind: "response", res: r };
+                        continue;
+                    }
+                    // Undefined = pass; bundle accepts the request.
+                    return undefined;
+                }
+                catch (err) {
+                    if (!firstFailure)
+                        firstFailure = { kind: "throw", err };
+                }
+            }
+            if (firstFailure?.kind === "response")
+                return firstFailure.res;
+            throw firstFailure.err;
+        },
+    };
+}
+/**
+ * Run a hook bundle on every request EXCEPT those matching `when`. The
+ * canonical use is "apply auth everywhere except the public endpoints":
+ *
+ * @example
+ * ```ts
+ * app.use(except(
+ *   ["/health", "/openapi.json", "/docs/**"],
+ *   bearerAuth({ validate: (token) => token === env.API_TOKEN }),
+ * ));
+ * ```
+ *
+ * Only the `beforeHandle` phase is gated — the surrounding
+ * `onRequest`/`afterHandle`/`onSend`/`onResponse` phases still run so
+ * shared concerns like request-id propagation are not accidentally
+ * exempted. Wrap each bundle with {@link except} individually when you
+ * need to gate other phases.
+ *
+ * @since 0.19.0
+ */
+export function except(when, hooks) {
+    const matches = compileExceptMatcher(when);
+    const original = hooks.beforeHandle;
+    if (!original)
+        return hooks;
+    return {
+        ...hooks,
+        async beforeHandle(ctx) {
+            if (await matches(ctx))
+                return undefined;
+            return original(ctx);
+        },
+    };
+}
+function compileExceptMatcher(when) {
+    if (typeof when === "function") {
+        return async (ctx) => Boolean(await when(ctx));
+    }
+    const patterns = Array.isArray(when) ? when : [when];
+    const matchers = patterns.map(compilePathPattern);
+    return async (ctx) => {
+        const path = new URL(ctx.request.url).pathname;
+        return matchers.some((m) => m(path));
+    };
+}
+function compilePathPattern(pattern) {
+    if (!pattern.startsWith("/")) {
+        throw new Error(`except(): path patterns must start with "/" (got ${JSON.stringify(pattern)}).`);
+    }
+    if (!pattern.includes("*")) {
+        return (path) => path === pattern;
+    }
+    const escaped = pattern
+        .split(/(\*\*|\*)/)
+        .map((part) => {
+        if (part === "**")
+            return ".*";
+        if (part === "*")
+            return "[^/]*";
+        return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("");
+    const regex = new RegExp(`^${escaped}$`);
+    return (path) => regex.test(path);
+}
+function mergeCombineHooks(layers) {
+    const pick = (key) => layers
+        .map((h) => h[key])
+        .filter((f) => typeof f === "function");
+    const merged = {};
+    const onRequest = pick("onRequest");
+    if (onRequest.length > 0) {
+        merged.onRequest = async (req) => {
+            for (const fn of onRequest)
+                await fn(req);
+        };
+    }
+    const beforeHandle = pick("beforeHandle");
+    if (beforeHandle.length > 0) {
+        merged.beforeHandle = async (ctx) => {
+            for (const fn of beforeHandle) {
+                const r = await fn(ctx);
+                if (r instanceof Response)
+                    return r;
+            }
+            return undefined;
+        };
+    }
+    const afterHandle = pick("afterHandle");
+    if (afterHandle.length > 0) {
+        merged.afterHandle = async (ctx, value) => {
+            let current = value;
+            for (const fn of afterHandle) {
+                const out = await fn(ctx, current);
+                if (out !== undefined)
+                    current = out;
+            }
+            return current;
+        };
+    }
+    const onError = pick("onError");
+    if (onError.length > 0) {
+        merged.onError = async (err, ctx) => {
+            for (const fn of onError) {
+                const r = await fn(err, ctx);
+                if (r instanceof Response)
+                    return r;
+            }
+            return undefined;
+        };
+    }
+    const onSend = pick("onSend");
+    if (onSend.length > 0) {
+        merged.onSend = async (res, ctx) => {
+            let current = res;
+            for (const fn of onSend) {
+                const r = await fn(current, ctx);
+                if (r instanceof Response)
+                    current = r;
+            }
+            return current;
+        };
+    }
+    const onResponse = pick("onResponse");
+    if (onResponse.length > 0) {
+        merged.onResponse = async (res) => {
+            for (const fn of onResponse)
+                await fn(res);
+        };
+    }
+    // Forward symbol-keyed security markers (CORS / CSRF / session /
+    // secure-headers) so boot-time and per-request guards still see them
+    // on the composed bundle.
+    for (const hooks of layers) {
+        const record = hooks;
+        for (const key of Object.getOwnPropertySymbols(record)) {
+            if (!(key in merged)) {
+                merged[key] = record[key];
+            }
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=combine.js.map

package/dist/combine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"combine.js","sourceRoot":"","sources":["../src/combine.ts"],"names":[],"mappings":"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"}

package/dist/compression.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Wave 7 (first focused slice): first-party `compression()` middleware with
+ * BREACH-aware safe defaults.
+ *
+ * Built on the web-standard `CompressionStream` API so the same line works
+ * on Node, Bun, Deno, Cloudflare Workers, Vercel Edge, and Fastly Compute.
+ * The middleware deliberately refuses to expose a configurable compression
+ * level — `CompressionStream` uses the runtime's documented default (gzip
+ * level 6 on Node / V8); a `level: 9` opt-in is rejected at construction
+ * because the bytes-saved-per-CPU-cycle tradeoff turns into a small-vCPU
+ * DoS amplifier under sustained load with single-digit-percent bytes-saved
+ * gains on typical JSON payloads.
+ *
+ * BREACH guards (CRIME-style cross-domain compression-oracle defenses) are
+ * always-on and not opt-out: the middleware refuses to compress responses
+ * that carry `Set-Cookie`, responses on requests that carry an
+ * `Authorization` header, responses on requests that carry a
+ * recognized session / CSRF cookie, and responses whose content type is
+ * already entropy-coded (images, video, audio, archives, fonts, wasm, pdf).
+ *
+ * @since 0.25.0
+ */
+import type { Hooks } from "./types.js";
+/** Supported response encodings, in default preference order (best → worst ratio). */
+export type CompressionEncoding = "br" | "gzip" | "deflate";
+/** Options for {@link compression}. */
+export interface CompressionOptions {
+    /**
+     * Minimum response body size (in bytes) eligible for compression.
+     *
+     * Responses smaller than this threshold are never compressed: gzip /
+     * deflate / brotli all add a header + dictionary preamble (typically
+     * 10–18 bytes for gzip, 4–8 bytes for brotli) so anything smaller than
+     * the typical TCP MSS (~1448 bytes) does not actually save wire bytes
+     * after framing overhead.
+     *
+     * Default `1024`. Must be a finite non-negative integer; values
+     * below `0` or above `2 ** 31 - 1` are refused at construction.
+     */
+    minimumSize?: number;
+    /**
+     * Allowed encodings, in caller-preferred order. Defaults to
+     * `["br", "gzip", "deflate"]` — the middleware will pick the
+     * highest-quality encoding the client supports AND the runtime supports
+     * (probed lazily on first use). `deflate` is included for legacy
+     * intermediaries; if a runtime lacks `CompressionStream` for an
+     * encoding, that encoding is silently dropped from the allowlist.
+     */
+    encodings?: readonly CompressionEncoding[];
+    /**
+     * Additional MIME-type prefixes (lowercased, checked as a prefix of the
+     * response `Content-Type` token before any `;` parameter) that should
+     * NOT be compressed. Merged with the always-on built-in deny-list
+     * (image/*, video/*, audio/*, application/zip, application/x-7z-*,
+     * application/x-gzip, application/x-bzip*, application/x-xz,
+     * application/x-zstd, application/wasm, application/pdf, font/*).
+     */
+    excludeContentTypes?: readonly string[];
+    /**
+     * Additional request cookie names that, when present, mark the response
+     * as security-state-bound and skip compression. Merged with the
+     * always-on built-in set (any cookie matching `/session/i`,
+     * `/csrf/i`, `/xsrf/i`, any `__Host-` / `__Secure-` cookie).
+     *
+     * The match is performed on the unparsed cookie name (case-insensitive
+     * substring match), so passing `"my-app-auth"` covers
+     * `my-app-auth=...`, `my-app-auth.sig=...`, etc.
+     */
+    authCookieNames?: readonly string[];
+    /**
+    * Deliberately unsupported. Provided as a `never`-typed trap so the type
+    * system flags accidental opt-in. The actual `CompressionStream` never
+    * exposes a level knob — passing any value triggers a construction-time
+    * refusal.
+     *
+     * @internal
+     */
+    compressLevel?: never;
+}
+/**
+ * Internal marker stamped on the hook so a future audit gate can confirm
+ * the BREACH-aware middleware is installed (Wave 9 audit-item parity).
+ *
+ * @since 0.25.0
+ */
+export declare const COMPRESSION_HOOK_MARKER: unique symbol;
+/**
+ * @internal Reset cached runtime probe. Test-only.
+ * @since 0.25.0
+ */
+export declare function _resetCompressionRuntimeProbeForTests(): void;
+/**
+ * BREACH-aware response compression middleware.
+ *
+ * Picks `br` > `gzip` > `deflate` based on the client's `Accept-Encoding`
+ * header AND the runtime's `CompressionStream` support (probed once,
+ * cached). Skips compression when ANY of the following are true:
+ *
+ * - request method is not `GET` / `HEAD` (compressing responses on
+ *   state-changing requests offers no caching win and trips BREACH
+ *   oracles more easily);
+ * - request carried an `Authorization` header (auth-bound bodies);
+ * - request carried a recognized session / CSRF / `__Host-` /
+ *   `__Secure-` cookie (auth-bound bodies);
+ * - response status is not `2xx`;
+ * - response already declares a `Content-Encoding`;
+ * - response declares a `Set-Cookie` (response is mutating auth state);
+ * - response body byte length is below `minimumSize` (default `1024`);
+ * - response `Content-Type` is in the always-on already-compressed
+ *   deny-list (image/video/audio/archives/fonts/wasm/pdf, with
+ *   `image/svg+xml` carved back in as compressible XML).
+ *
+ * When skipping, the middleware still appends `Vary: Accept-Encoding`
+ * to the response so cache keys remain content-negotiation-correct.
+ *
+ * @example
+ * ```ts
+ * import { App, compression } from "@daloyjs/core";
+ *
+ * const app = new App();
+ * app.use(compression());
+ * ```
+ *
+ * @since 0.25.0
+ */
+export declare function compression(opts?: CompressionOptions): Hooks;
+//# sourceMappingURL=compression.d.ts.map

package/dist/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../src/compression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,sFAAsF;AACtF,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5D,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC3C;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,OAAO,MAE5C,CAAC;AA0HF;;;GAGG;AACH,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D;AAoHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,KAAK,CAgGhE"}