@daloyjs/core 0.34.3 → 0.35.1

package/dist/safe-redirect.js

@@ -0,0 +1,168 @@
+/**
+ * First-party `safeRedirect()` helper that refuses open-redirect inputs.
+ *
+ * Open redirects (Aikido "Top 10 app security problems" #10, OWASP
+ * "Unvalidated Redirects and Forwards") happen when an app blindly trusts
+ * a `?next=...` / `?returnTo=...` query parameter and emits a `Location`
+ * header pointing wherever the attacker wants. The fix the industry has
+ * settled on is the same one Daloy enforces here: validate every
+ * candidate URL against an explicit allowlist of internal paths and
+ * external origins **before** building the redirect response.
+ *
+ * Defaults are deliberately strict:
+ *
+ * - Same-origin paths must start with `/` and must not start with `//`
+ *   or `/\` (which browsers interpret as protocol-relative URLs that
+ *   escape your origin).
+ * - Backslashes, control characters, and `CR`/`LF` are rejected to
+ *   stop response-splitting and homograph tricks.
+ * - Absolute URLs are only allowed when their `origin` exactly matches
+ *   one of the entries in `allowedOrigins`.
+ * - `javascript:`, `data:`, `vbscript:`, and `file:` schemes are always
+ *   refused, even if the caller wrote a bug into the allowlist.
+ * - The default status is `303 See Other`, which is the
+ *   POST-redirect-GET-safe choice. Override with `status` when you
+ *   genuinely need `301`/`302`/`307`/`308`.
+ *
+ * @example
+ * ```ts
+ * import { safeRedirect } from "@daloyjs/core";
+ *
+ * app.get("/login/callback", (ctx) => {
+ *   const next = new URL(ctx.request.url).searchParams.get("next") ?? "/";
+ *   return safeRedirect(next, {
+ *     allowedPaths: ["/", "/dashboard", "/account"],
+ *     allowedOrigins: ["https://app.example.com"],
+ *     fallback: "/",
+ *   });
+ * });
+ * ```
+ *
+ * @since 0.35.1
+ */
+/** Thrown when {@link safeRedirect} refuses a candidate URL and no `fallback` is configured. */
+export class OpenRedirectBlockedError extends Error {
+    reason;
+    target;
+    constructor(reason, target) {
+        super(`safeRedirect: refused redirect (${reason})`);
+        this.name = "OpenRedirectBlockedError";
+        this.reason = reason;
+        this.target = target;
+    }
+}
+const FORBIDDEN_SCHEMES = new Set([
+    "javascript:",
+    "data:",
+    "vbscript:",
+    "file:",
+]);
+const ALLOWED_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+// Reject NUL, CR, LF, and other C0/C1 control characters; they enable
+// response-splitting via the `Location` header.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f-\u009f]/;
+function buildResponse(location, status, headers) {
+    const merged = new Headers(headers);
+    merged.set("Location", location);
+    // Belt and suspenders: cache directives so browsers and shared caches
+    // never reuse a redirect that was scoped to a single request.
+    if (!merged.has("Cache-Control"))
+        merged.set("Cache-Control", "no-store");
+    return new Response(null, { status, headers: merged });
+}
+function classify(target, allowedPaths, allowedOrigins) {
+    if (typeof target !== "string" || target.length === 0) {
+        return { ok: false, reason: "empty-target" };
+    }
+    if (CONTROL_CHAR_RE.test(target)) {
+        return { ok: false, reason: "invalid-control-characters" };
+    }
+    // Protocol-relative (`//evil.com`) is the classic open-redirect bypass.
+    if (target.startsWith("//"))
+        return { ok: false, reason: "protocol-relative" };
+    // `/\evil.com` is interpreted by some browsers as protocol-relative too.
+    if (target.startsWith("/\\"))
+        return { ok: false, reason: "backslash-path" };
+    if (target.startsWith("/")) {
+        // Same-origin path. Backslashes anywhere in the path can confuse
+        // user agents and proxies — refuse them outright.
+        if (target.includes("\\"))
+            return { ok: false, reason: "backslash-path" };
+        if (allowedPaths.length === 0) {
+            return { ok: false, reason: "path-not-allowed" };
+        }
+        if (allowedPaths.includes("/*"))
+            return { ok: true, location: target };
+        // Match on pathname only; preserve any user-provided query/fragment.
+        const qIdx = target.search(/[?#]/);
+        const pathname = qIdx === -1 ? target : target.slice(0, qIdx);
+        if (!allowedPaths.includes(pathname)) {
+            return { ok: false, reason: "path-not-allowed" };
+        }
+        return { ok: true, location: target };
+    }
+    // Absolute URL path. Parse and compare origin.
+    let parsed;
+    try {
+        parsed = new URL(target);
+    }
+    catch {
+        return { ok: false, reason: "parse-failed" };
+    }
+    if (FORBIDDEN_SCHEMES.has(parsed.protocol.toLowerCase())) {
+        return { ok: false, reason: "scheme-not-allowed" };
+    }
+    if (!allowedOrigins.includes(parsed.origin)) {
+        return { ok: false, reason: "origin-not-allowed" };
+    }
+    return { ok: true, location: parsed.toString() };
+}
+/**
+ * Build a redirect `Response` after validating the target against an
+ * explicit allowlist. Throws {@link OpenRedirectBlockedError} when the
+ * candidate fails validation and no `fallback` is configured.
+ *
+ * @param target - User-supplied URL candidate (path or absolute URL).
+ * @param options - Allowlist + response configuration.
+ *
+ * @since 0.35.1
+ */
+export function safeRedirect(target, options = {}) {
+    const allowedPaths = options.allowedPaths ?? [];
+    const allowedOrigins = options.allowedOrigins ?? [];
+    const status = options.status ?? 303;
+    if (!ALLOWED_REDIRECT_STATUSES.has(status)) {
+        throw new TypeError(`safeRedirect: status ${String(status)} is not a redirect status (allowed: 301, 302, 303, 307, 308)`);
+    }
+    for (const p of allowedPaths) {
+        if (typeof p !== "string" || (p !== "/*" && !p.startsWith("/"))) {
+            throw new TypeError(`safeRedirect: allowedPaths entries must start with "/" (got ${JSON.stringify(p)})`);
+        }
+    }
+    for (const o of allowedOrigins) {
+        if (typeof o !== "string" || o.length === 0) {
+            throw new TypeError("safeRedirect: allowedOrigins entries must be non-empty strings");
+        }
+        let parsed;
+        try {
+            parsed = new URL(o);
+        }
+        catch {
+            throw new TypeError(`safeRedirect: allowedOrigins entry is not a valid URL: ${o}`);
+        }
+        if (parsed.origin !== o) {
+            throw new TypeError(`safeRedirect: allowedOrigins entry must be a bare origin (scheme + host [+ port]); got ${o}`);
+        }
+    }
+    const result = classify(target, allowedPaths, allowedOrigins);
+    if (result.ok)
+        return buildResponse(result.location, status, options.headers);
+    if (options.fallback !== undefined) {
+        if (!options.fallback.startsWith("/") || options.fallback.startsWith("//")) {
+            throw new TypeError(`safeRedirect: fallback must be a same-origin path starting with "/"; got ${options.fallback}`);
+        }
+        return buildResponse(options.fallback, status, options.headers);
+    }
+    throw new OpenRedirectBlockedError(result.reason, target);
+}

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:83195aa9-d821-5a41-9fbb-6c69378e250d",
+  "serialNumber": "urn:uuid:3d46c2b6-0b38-564b-9dd2-79098e99155b",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T13:34:50.159Z",
+    "timestamp": "2026-05-26T23:20:20.188Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.34.3"
+        "version": "0.35.1"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@0.34.3",
+      "bom-ref": "pkg:npm/@daloyjs/core@0.35.1",
       "name": "@daloyjs/core",
-      "version": "0.34.3",
+      "version": "0.35.1",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@0.34.3",
+      "purl": "pkg:npm/@daloyjs/core@0.35.1",
       "licenses": [
         {
           "license": {
@@ -39,12 +39,16 @@
         {
           "type": "website",
           "url": "https://daloyjs.dev"
+        },
+        {
+          "type": "distribution",
+          "url": "https://www.npmjs.com/package/@daloyjs/core"
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.34.3",
+        "tagId": "swidtag--daloyjs-core-0.35.1",
         "name": "@daloyjs/core",
-        "version": "0.34.3",
+        "version": "0.35.1",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@0.34.3",
+      "ref": "pkg:npm/@daloyjs/core@0.35.1",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-0.34.3",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.34.3-83195aa9-d821-5a41-9fbb-6c69378e250d",
+  "name": "@daloyjs/core-0.35.1",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.35.1-3d46c2b6-0b38-564b-9dd2-79098e99155b",
   "creationInfo": {
-    "created": "2026-05-23T13:34:50.159Z",
+    "created": "2026-05-26T23:20:20.188Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "0.34.3",
+      "versionInfo": "0.35.1",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@0.34.3"
+          "referenceLocator": "pkg:npm/@daloyjs/core@0.35.1"
         }
       ]
     }

package/dist/schema.d.ts

@@ -73,4 +73,3 @@ export declare function validate<S extends StandardSchemaV1>(schema: S, value: u
  * @since 0.1.0
  */
 export declare function isStandardSchema(x: unknown): x is StandardSchemaV1;
-//# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -41,4 +41,3 @@ export function isStandardSchema(x) {
         "~standard" in x &&
         typeof x["~standard"]?.validate === "function");
 }
-//# sourceMappingURL=schema.js.map

package/dist/security-schemes.d.ts

@@ -210,4 +210,3 @@ export declare function oauth2Scheme(options: OAuth2SchemeOptions): OAuth2Scheme
  * @since 0.1.0
  */
 export declare function openIdConnectScheme(options: OpenIdConnectSchemeOptions): OpenIdConnectScheme;
-//# sourceMappingURL=security-schemes.d.ts.map

package/dist/security-schemes.js

@@ -177,4 +177,3 @@ export function openIdConnectScheme(options) {
         scheme.description = options.description;
     return markRequirePayloadAuth(scheme, options);
 }
-//# sourceMappingURL=security-schemes.js.map

package/dist/security.d.ts

@@ -104,8 +104,8 @@ export declare function randomId(): string;
 /**
  * Header names that MUST appear at most once on a request per RFC 7230.
  * Duplicate values for these headers are a classic HTTP-request-smuggling
- * vector — front-end and back-end proxies can disagree on which value
- * "wins", letting an attacker desync the connection.
+ * vector — front-end and back-end proxies can disagree on framing or
+ * routing, letting an attacker desync the connection.
  *
  * Exported for adapter authors that need the same set.
  *
@@ -202,6 +202,14 @@ export declare function assertStrongSecret(secret: unknown, scope: string): void
  * @since 0.15.0
  */
 export type WebhookHmacAlgorithm = "sha256" | "sha384" | "sha512";
+/**
+ * Default tolerance window (in seconds) for webhook timestamp verification.
+ * Matches Stripe / Standard Webhooks defaults — five minutes either side of
+ * the receiver's clock. Override per call via `toleranceSeconds`.
+ *
+ * @since 0.21.0
+ */
+export declare const WEBHOOK_DEFAULT_TOLERANCE_SECONDS = 300;
 /**
  * Verify an HMAC signature for a webhook payload in constant time.
  *
@@ -243,6 +251,35 @@ export declare function verifyWebhookSignature(opts: {
     signature: string | Uint8Array;
     secret: string | Uint8Array;
     algorithm?: WebhookHmacAlgorithm;
+    /**
+     * Optional event timestamp (Unix seconds; string or number). When
+     * supplied, the HMAC is computed over `"<timestamp>.<payload>"` instead
+     * of just `payload`, which binds the signature to a specific point in
+     * time and lets the verifier reject replays whose timestamp drifts
+     * outside `toleranceSeconds`. Matches the Stripe / Standard Webhooks
+     * convention. Pass the value extracted from the producer's signature
+     * header (e.g. the `t=` field of `Stripe-Signature`).
+     *
+     * @since 0.21.0
+     */
+    timestamp?: string | number;
+    /**
+     * Maximum drift (in seconds) between `timestamp` and `now()` before the
+     * signature is rejected as a likely replay. Only consulted when
+     * `timestamp` is supplied. Defaults to
+     * {@link WEBHOOK_DEFAULT_TOLERANCE_SECONDS} (5 minutes).
+     *
+     * @since 0.21.0
+     */
+    toleranceSeconds?: number;
+    /**
+     * Clock used for replay-window checks. Returns milliseconds since the
+     * Unix epoch. Defaults to {@link Date.now}; override in tests to make
+     * the clock deterministic.
+     *
+     * @since 0.21.0
+     */
+    now?: () => number;
 }): Promise<boolean>;
 /**
  * Compute an HMAC signature over `payload` and return it hex-encoded. The
@@ -255,5 +292,99 @@ export declare function signWebhookPayload(opts: {
     payload: Uint8Array | string;
     secret: string | Uint8Array;
     algorithm?: WebhookHmacAlgorithm;
+    /**
+     * Optional event timestamp (Unix seconds; string or number). When
+     * supplied, the HMAC is computed over `"<timestamp>.<payload>"` so the
+     * receiver can use {@link verifyWebhookSignature} with the same
+     * `timestamp` and a `toleranceSeconds` window to defeat replay attacks.
+     *
+     * @since 0.21.0
+     */
+    timestamp?: string | number;
 }): Promise<string>;
-//# sourceMappingURL=security.d.ts.map
+/**
+ * Return a single-segment, storage-safe basename derived from a
+ * (potentially attacker-controlled) filename — for example, the `name`
+ * field on a multipart `UploadedFile` before passing it to `fs.writeFile`
+ * or any other filesystem sink.
+ *
+ * The transformation:
+ *
+ *   1. Takes the basename only — anything before the last `/` or `\` is
+ *      discarded (`../../etc/passwd` → `passwd`, `C:\\foo\\bar.txt` →
+ *      `bar.txt`).
+ *   2. Strips NUL bytes and other control characters (NUL truncation is
+ *      the classic `evil.png\0.exe` bypass).
+ *   3. Strips Windows-reserved characters (`<>:"|?*`) and replaces them
+ *      with `_`.
+ *   4. Strips leading dots so the result cannot be `.`, `..`, or a hidden
+ *      dotfile (`.htaccess` → `htaccess`).
+ *   5. Trims trailing dots and spaces (Windows silently strips these on
+ *      `CreateFile`, so `file.txt ` and `file.txt` collide).
+ *   6. Refuses Windows-reserved names (`CON`, `PRN`, `AUX`, `NUL`,
+ *      `COM1`–`COM9`, `LPT1`–`LPT9`) — case-insensitive, with or without
+ *      extension.
+ *   7. Throws {@link BadRequestError} if the result is empty.
+ *
+ * Returns a basename only — never includes a directory. Callers are
+ * expected to combine it with a trusted base directory via
+ * `path.join(baseDir, sanitized)`. Combined with a final
+ * `path.resolve(baseDir, sanitized).startsWith(path.resolve(baseDir))`
+ * check this fully closes the Zip-Slip and arbitrary-write class of bug.
+ *
+ * @param name - The candidate filename (typically from
+ *   `UploadedFile.name`, a `Content-Disposition` header, or any other
+ *   untrusted source).
+ * @returns A sanitized basename safe to combine with a trusted directory.
+ * @throws {BadRequestError} When the input reduces to an empty string or
+ *   matches a Windows-reserved device name.
+ * @since 0.35.1
+ */
+export declare function sanitizeFilename(name: string): string;
+/**
+ * Validate that a candidate relative path is safe to combine with a
+ * trusted base directory — i.e. it cannot escape via `..` segments,
+ * absolute roots, drive letters, NUL truncation, or mixed
+ * POSIX/Windows separators.
+ *
+ * Throws {@link BadRequestError} on any of:
+ *
+ *   - Empty input
+ *   - NUL bytes (`evil\0../../etc/passwd` truncation)
+ *   - Backslash characters (treated as Windows separators; rejecting
+ *     them prevents POSIX callers being bypassed by `..\\..\\etc`)
+ *   - POSIX absolute paths (`/etc/passwd`)
+ *   - Windows drive letters or UNC roots (`C:\\foo`, `\\\\server\\share`)
+ *   - Any segment equal to `..` after `/`-splitting
+ *
+ * Returns the normalized POSIX-style relative path on success. Designed
+ * for the Aikido / OWASP "Directory Traversal & File Exposure" class
+ * (`CVE-2023-26111` `node-static`, Zip Slip, `req.query.file` →
+ * `sendFile`).
+ *
+ * @param input - The candidate relative path.
+ * @returns The input unchanged when safe.
+ * @throws {BadRequestError} When the path could escape its base directory.
+ * @since 0.35.1
+ */
+export declare function assertSafeRelativePath(input: string): string;
+/**
+ * Recursively scan a parsed JSON value (object / array / scalar) for any
+ * property key that starts with `$` — the MongoDB / NoSQL operator
+ * namespace (`$ne`, `$gt`, `$regex`, `$where`, …).
+ *
+ * Returns `true` on the first hit. Use before passing untrusted data
+ * into a query object that may be interpreted as an operator expression.
+ *
+ * @since 0.35.1
+ */
+export declare function hasMongoOperatorKeys(value: unknown): boolean;
+/**
+ * Throw {@link BadRequestError} when {@link hasMongoOperatorKeys}
+ * returns `true`. Safe to call on the parsed request body before
+ * threading it into a NoSQL driver — closes the
+ * `{"password": {"$ne": null}}` authentication-bypass class of bug.
+ *
+ * @since 0.35.1
+ */
+export declare function assertNoMongoOperators(value: unknown): void;