@devorash/core 0.1.0

package/dist/security/index.js

@@ -0,0 +1,345 @@
+/**
+ * Security utilities for Devora SDKs
+ * @module @devorash/core/security
+ */
+import { SDK_DEFAULTS, READ_METHODS } from "../constants/index.js";
+// ============================================================================
+// Timestamps
+// ============================================================================
+/**
+ * A timestamp tolerance is a whole, non-negative number of seconds. Zero means
+ * only the current second is accepted; there is no "falsy means default".
+ */
+export function isValidTimestampTolerance(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** Throws for configuration values that {@link isValidTimestampTolerance} rejects. */
+export function assertTimestampTolerance(value, name = "timestampTolerance") {
+    if (value !== undefined && !isValidTimestampTolerance(value))
+        throw new Error(`Devora SDK: ${name} must be a non-negative integer number of seconds`);
+}
+/**
+ * Validate timestamp is within acceptable window
+ */
+export function validateTimestamp(requestTimestamp, toleranceSeconds = SDK_DEFAULTS.TIMESTAMP_TOLERANCE) {
+    // NaN/Infinity/negative tolerances would make every drift comparison pass.
+    if (!isValidTimestampTolerance(toleranceSeconds)) {
+        return { valid: false, error: "Invalid timestamp tolerance" };
+    }
+    if (!Number.isFinite(requestTimestamp) || requestTimestamp <= 0) {
+        return {
+            valid: false,
+            error: "Invalid timestamp",
+        };
+    }
+    const currentTime = Math.floor(Date.now() / 1000);
+    const drift = Math.abs(currentTime - requestTimestamp);
+    if (drift > toleranceSeconds) {
+        return {
+            valid: false,
+            error: `Request timestamp outside tolerance window (drift: ${drift}s, max: ${toleranceSeconds}s)`,
+        };
+    }
+    return { valid: true };
+}
+// ============================================================================
+// Scope Enforcement Utilities
+// ============================================================================
+/**
+ * Check if HTTP method is a write operation
+ */
+export function isWriteMethod(method) {
+    // Unknown verbs are not safe just because they are absent from our CRUD list.
+    return !READ_METHODS.includes(method.toUpperCase());
+}
+/**
+ * Path of an origin-form request target (`/path?query`), still percent-encoded.
+ *
+ * Absolute-form targets (`http://host/path`) are deliberately NOT unwrapped:
+ * routers disagree with any regex about where such a host ends (a `?` inside
+ * it moves the routed path to `/`), so the result does not start with `/` and
+ * {@link isAmbiguousRequestPath} rejects it.
+ */
+export function getRawRequestPath(value) {
+    return (value ?? "").split(/[?#]/)[0] || "/";
+}
+/** Headers through which common middleware lets a client change the effective method. */
+export const METHOD_OVERRIDE_HEADERS = [
+    "x-http-method-override",
+    "x-http-method",
+    "x-method-override",
+];
+/** The query parameter method-override middleware reads (`?_method=DELETE`). */
+export const METHOD_OVERRIDE_QUERY_PARAM = "_method";
+/**
+ * Every method a request might execute as. The guard judges all of them, so a
+ * method-override middleware ordered after the guard cannot turn an allowed
+ * POST into a blocked DELETE. `target` (the raw request target) adds any
+ * `_method` query parameters. A `_method` field in a request body is invisible
+ * to a guard that runs before body parsing; see the guard docs.
+ */
+export function getPolicyMethods(method, headers, target) {
+    const methods = new Set([method.toUpperCase()]);
+    for (const name of METHOD_OVERRIDE_HEADERS) {
+        const value = headers?.[name];
+        for (const item of Array.isArray(value) ? value : value ? [value] : [])
+            for (const part of item.split(","))
+                if (part.trim())
+                    methods.add(part.trim().toUpperCase());
+    }
+    const queryStart = target?.indexOf("?") ?? -1;
+    if (target && queryStart !== -1) {
+        const query = target.slice(queryStart + 1).split("#")[0];
+        try {
+            for (const value of new URLSearchParams(query).getAll(METHOD_OVERRIDE_QUERY_PARAM))
+                if (value.trim())
+                    methods.add(value.trim().toUpperCase());
+        }
+        catch {
+            // An unparseable query overrides nothing; the route guard judges it.
+        }
+    }
+    return [...methods];
+}
+/**
+ * Methods a deny rule must cover. Frameworks answer HEAD with the GET handler,
+ * so a GET deny rule also denies HEAD.
+ */
+export function getDenyMethods(methods) {
+    return methods.includes("HEAD") && !methods.includes("GET") ? [...methods, "GET"] : methods;
+}
+/** Join a router mount prefix and a mount-relative origin-form target. */
+export function joinMountedTarget(mountPath, target) {
+    if (!mountPath || mountPath === "/")
+        return target;
+    // A mounted router sees `/` for both `/mount` and `/mount/`; both dispatch
+    // to the router's root handler, so report the mount path itself.
+    if (target === "/" || target.startsWith("/?") || target.startsWith("/#"))
+        return mountPath + target.slice(1);
+    return mountPath + target;
+}
+// A plain space (`%20` once decoded) is ordinary route-parameter content and
+// does not move a segment boundary; control characters and backslashes do.
+function hasPathControl(value) {
+    return Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127 || char.charCodeAt(0) === 92);
+}
+/** Reject paths whose segment boundaries differ between common routers. */
+export function isAmbiguousRequestPath(value) {
+    const raw = getRawRequestPath(value);
+    if (raw.length > 8192 || !raw.startsWith("/") || hasPathControl(raw))
+        return true;
+    try {
+        const decoded = decodeURIComponent(raw);
+        return (
+        // A still-encoded sequence after one decode means double encoding; a
+        // bare `%` (from a literal `%25`) is ordinary parameter content.
+        /%[0-9a-f]{2}/i.test(decoded) ||
+            // Routers may treat semicolons as query/matrix delimiters. A deny
+            // rule must not compare a different path from the selected handler.
+            decoded.includes(";") ||
+            hasPathControl(decoded) ||
+            /%(?:2f|5c)/i.test(raw) ||
+            decoded.includes("//") ||
+            decoded.split("/").some((part) => part === "." || part === ".."));
+    }
+    catch {
+        return true;
+    }
+}
+/** Decode one segment at a time, preserving case and separators. */
+export function normalizeRequestPath(value) {
+    const path = getRawRequestPath(value);
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** Linear-space wildcard matching within one path segment. */
+function segmentMatches(pattern, value) {
+    let previous = new Uint8Array(value.length + 1);
+    previous[0] = 1;
+    for (const token of pattern) {
+        const current = new Uint8Array(value.length + 1);
+        if (token === "*")
+            current[0] = previous[0];
+        for (let j = 1; j <= value.length; j++) {
+            current[j] =
+                token === "*"
+                    ? previous[j] || current[j - 1]
+                        ? 1
+                        : 0
+                    : previous[j - 1] && token === value[j - 1]
+                        ? 1
+                        : 0;
+        }
+        previous = current;
+    }
+    return previous[value.length] === 1;
+}
+/**
+ * Bounded iterative glob matching: * stays within a segment; ** spans zero or
+ * more whole segments. Allow rules preserve case/trailing slashes. Deny rules
+ * opt into conservative case-insensitive matching for non-strict routers.
+ */
+export function matchEndpointPattern(pattern, path, options = {}) {
+    if (pattern.length > 500 || path.length > 8192)
+        return false;
+    let patternPath = pattern.startsWith("/") ? pattern : `/${pattern}`;
+    let requestPath = path.startsWith("/") ? path : `/${path}`;
+    if (options.caseSensitive === false) {
+        patternPath = patternPath.toLowerCase();
+        requestPath = requestPath.toLowerCase();
+    }
+    if (options.ignoreTrailingSlash) {
+        patternPath = patternPath.replace(/\/+$/, "") || "/";
+        requestPath = requestPath.replace(/\/+$/, "") || "/";
+    }
+    const patterns = patternPath.slice(1).split("/");
+    const parts = requestPath.slice(1).split("/");
+    let previous = new Uint8Array(parts.length + 1);
+    previous[0] = 1;
+    for (const token of patterns) {
+        const current = new Uint8Array(parts.length + 1);
+        if (token === "**")
+            current[0] = previous[0];
+        for (let j = 1; j <= parts.length; j++) {
+            current[j] =
+                token === "**"
+                    ? previous[j] || current[j - 1]
+                        ? 1
+                        : 0
+                    : previous[j - 1] && segmentMatches(token, parts[j - 1])
+                        ? 1
+                        : 0;
+        }
+        previous = current;
+    }
+    return previous[parts.length] === 1;
+}
+/**
+ * Create a blocked response for scope violations
+ */
+export function createBlockedResponse(method, url) {
+    return new Response(JSON.stringify({
+        error: "Write operations disabled in read-only mode",
+        method,
+        url,
+        code: "SCOPE_VIOLATION",
+    }), {
+        status: 403,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+// ============================================================================
+// Token Utilities
+// ============================================================================
+/**
+ * Generate a cryptographically secure random string for tokens/IDs.
+ *
+ * @throws {Error} If no secure random source is available.
+ *         This is intentional - we must never fall back to Math.random()
+ *         for security-sensitive operations like token generation.
+ */
+export function generateRandomString(length = 32) {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    // Check for Web Crypto API (browser and modern Node.js)
+    if (typeof crypto === "undefined" || !crypto.getRandomValues) {
+        // NO FALLBACK - throw error instead of using insecure Math.random()
+        throw new Error("Devora SDK: Secure random number generator not available. " +
+            "This environment does not support Web Crypto API. " +
+            "For Node.js < 19, ensure you're using the crypto module.");
+    }
+    // Use rejection sampling to avoid modulo bias
+    const maxValidValue = 256 - (256 % chars.length); // 248 for 62 chars
+    for (let i = 0; i < length; i++) {
+        let randomValue;
+        do {
+            const randomBytes = new Uint8Array(1);
+            crypto.getRandomValues(randomBytes);
+            // Non-null assertion is safe: we just created a 1-byte array
+            randomValue = randomBytes[0];
+        } while (randomValue >= maxValidValue);
+        result += chars[randomValue % chars.length];
+    }
+    return result;
+}
+/**
+ * Convert ArrayBuffer to hex string
+ */
+export function arrayBufferToHex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Convert hex string to ArrayBuffer
+ */
+export function hexToArrayBuffer(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error(`Invalid hex string: length must be even (got ${hex.length})`);
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes.buffer;
+}
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Base error class for Devora SDK errors
+ */
+export class DevoraSDKError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode = 400) {
+        super(message);
+        this.name = "DevoraSDKError";
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Security-related errors
+ */
+export class DevoraSecurityError extends DevoraSDKError {
+    securityCode;
+    constructor(message, securityCode, statusCode = 401) {
+        super(message, `SECURITY_${securityCode}`, statusCode);
+        this.name = "DevoraSecurityError";
+        this.securityCode = securityCode;
+    }
+}
+/**
+ * Validation errors
+ */
+export class DevoraValidationError extends DevoraSDKError {
+    constructor(message, code = "VALIDATION_ERROR") {
+        super(message, code, 400);
+        this.name = "DevoraValidationError";
+    }
+}
+/**
+ * Configuration errors
+ */
+export class DevoraConfigError extends DevoraSDKError {
+    constructor(message) {
+        super(message, "CONFIG_ERROR", 500);
+        this.name = "DevoraConfigError";
+    }
+}
+/**
+ * Network/connectivity errors
+ */
+export class DevoraNetworkError extends DevoraSDKError {
+    constructor(message) {
+        super(message, "NETWORK_ERROR", 503);
+        this.name = "DevoraNetworkError";
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGlE,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACvD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAC9E,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,wBAAwB,CAAC,KAAc,EAAE,IAAI,GAAG,oBAAoB;IACnF,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,mDAAmD,CAAC,CAAA;AACzF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAChC,gBAAwB,EACxB,mBAA2B,YAAY,CAAC,mBAAmB;IAE3D,2EAA2E;IAC3E,IAAI,CAAC,yBAAyB,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAA;IAC9D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;QACjE,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,mBAAmB;SAC1B,CAAA;IACF,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,gBAAgB,CAAC,CAAA;IAEtD,IAAI,KAAK,GAAG,gBAAgB,EAAE,CAAC;QAC9B,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,sDAAsD,KAAK,WAAW,gBAAgB,IAAI;SACjG,CAAA;IACF,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACvB,CAAC;AAED,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC3C,8EAA8E;IAC9E,OAAO,CAAE,YAAkC,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC9C,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAA;AAC7C,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,wBAAwB;IACxB,eAAe;IACf,mBAAmB;CACV,CAAA;AAEV,gFAAgF;AAChF,MAAM,CAAC,MAAM,2BAA2B,GAAG,SAAS,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC/B,MAAc,EACd,OAAuD,EACvD,MAAe;IAEf,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;IAC/C,KAAK,MAAM,IAAI,IAAI,uBAAuB,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,CAAA;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;YACrE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;gBAAE,IAAI,IAAI,CAAC,IAAI,EAAE;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAA;IAC7F,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;IAC7C,IAAI,MAAM,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAA;QACzD,IAAI,CAAC;YACJ,KAAK,MAAM,KAAK,IAAI,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,2BAA2B,CAAC;gBACjF,IAAI,KAAK,CAAC,IAAI,EAAE;oBAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAA;QAC3D,CAAC;QAAC,MAAM,CAAC;YACR,qEAAqE;QACtE,CAAC;IACF,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAA;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAiB;IAC/C,OAAO,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;AAC5F,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,SAA6B,EAAE,MAAc;IAC9E,IAAI,CAAC,SAAS,IAAI,SAAS,KAAK,GAAG;QAAE,OAAO,MAAM,CAAA;IAClD,2EAA2E;IAC3E,iEAAiE;IACjE,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;QACvE,OAAO,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACnC,OAAO,SAAS,GAAG,MAAM,CAAA;AAC1B,CAAC;AAED,6EAA6E;AAC7E,2EAA2E;AAC3E,SAAS,cAAc,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAC5B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAC5F,CAAA;AACF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,sBAAsB,CAAC,KAAa;IACnD,MAAM,GAAG,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACpC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjF,IAAI,CAAC;QACJ,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAA;QACvC,OAAO;QACN,qEAAqE;QACrE,iEAAiE;QACjE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;YAC7B,kEAAkE;YAClE,oEAAoE;YACpE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YACrB,cAAc,CAAC,OAAO,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;YACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,CAChE,CAAA;IACF,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,oBAAoB,CAAC,KAAa;IACjD,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACrC,IAAI,CAAC;QACJ,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED,8DAA8D;AAC9D,SAAS,cAAc,CAAC,OAAe,EAAE,KAAa;IACrD,IAAI,QAAQ,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC/C,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACf,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAChD,IAAI,KAAK,KAAK,GAAG;YAAE,OAAO,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAA;QAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,OAAO,CAAC,CAAC,CAAC;gBACT,KAAK,KAAK,GAAG;oBACZ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;wBAC9B,CAAC,CAAC,CAAC;wBACH,CAAC,CAAC,CAAC;oBACJ,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;wBAC1C,CAAC,CAAC,CAAC;wBACH,CAAC,CAAC,CAAC,CAAA;QACP,CAAC;QACD,QAAQ,GAAG,OAAO,CAAA;IACnB,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAe,EACf,IAAY,EACZ,UAAsE,EAAE;IAExE,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI;QAAE,OAAO,KAAK,CAAA;IAC5D,IAAI,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAA;IACnE,IAAI,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAA;IAC1D,IAAI,OAAO,CAAC,aAAa,KAAK,KAAK,EAAE,CAAC;QACrC,WAAW,GAAG,WAAW,CAAC,WAAW,EAAE,CAAA;QACvC,WAAW,GAAG,WAAW,CAAC,WAAW,EAAE,CAAA;IACxC,CAAC;IACD,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;QACjC,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAA;QACpD,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAA;IACrD,CAAC;IACD,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAChD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC7C,IAAI,QAAQ,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC/C,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACf,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAChD,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAA;QAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,OAAO,CAAC,CAAC,CAAC;gBACT,KAAK,KAAK,IAAI;oBACb,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;wBAC9B,CAAC,CAAC,CAAC;wBACH,CAAC,CAAC,CAAC;oBACJ,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;wBACxD,CAAC,CAAC,CAAC;wBACH,CAAC,CAAC,CAAC,CAAA;QACP,CAAC;QACD,QAAQ,GAAG,OAAO,CAAA;IACnB,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,GAAW;IAChE,OAAO,IAAI,QAAQ,CAClB,IAAI,CAAC,SAAS,CAAC;QACd,KAAK,EAAE,6CAA6C;QACpD,MAAM;QACN,GAAG;QACH,IAAI,EAAE,iBAAiB;KACvB,CAAC,EACF;QACC,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;KAC/C,CACD,CAAA;AACF,CAAC;AAED,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE;IACvD,MAAM,KAAK,GAAG,gEAAgE,CAAA;IAC9E,IAAI,MAAM,GAAG,EAAE,CAAA;IAEf,wDAAwD;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QAC9D,oEAAoE;QACpE,MAAM,IAAI,KAAK,CACd,4DAA4D;YAC3D,oDAAoD;YACpD,0DAA0D,CAC3D,CAAA;IACF,CAAC;IAED,8CAA8C;IAC9C,MAAM,aAAa,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA,CAAC,mBAAmB;IACpE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,IAAI,WAAmB,CAAA;QACvB,GAAG,CAAC;YACH,MAAM,WAAW,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;YACrC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,CAAA;YACnC,6DAA6D;YAC7D,WAAW,GAAG,WAAW,CAAC,CAAC,CAAE,CAAA;QAC9B,CAAC,QAAQ,WAAW,IAAI,aAAa,EAAC;QACtC,MAAM,IAAI,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IACnD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAA;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAA;AACX,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC3C,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,gDAAgD,GAAG,CAAC,MAAM,GAAG,CAAC,CAAA;IAC/E,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAA;AACpB,CAAC;AAED,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC/B,IAAI,CAAQ;IACZ,UAAU,CAAQ;IAE3B,YAAY,OAAe,EAAE,IAAY,EAAE,aAAqB,GAAG;QAClE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC7B,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IAC7C,YAAY,CAAoB;IAEzC,YAAY,OAAe,EAAE,YAAgC,EAAE,aAAqB,GAAG;QACtF,KAAK,CAAC,OAAO,EAAE,YAAY,YAAY,EAAE,EAAE,UAAU,CAAC,CAAA;QACtD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IACjC,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACxD,YAAY,OAAe,EAAE,OAAe,kBAAkB;QAC7D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACpC,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACpD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,CAAA;QACnC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IAChC,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACrD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,CAAC,CAAA;QACpC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IACjC,CAAC;CACD"}

package/dist/security/request-body.d.ts

@@ -0,0 +1,16 @@
+/** Failures raised before an oversized or stalled body is fully materialized. */
+export declare class BodyReadError extends Error {
+    readonly code: "BODY_TOO_LARGE" | "BODY_TIMEOUT" | "INVALID_BODY";
+    readonly status: 400 | 408 | 413;
+    constructor(code: "BODY_TOO_LARGE" | "BODY_TIMEOUT" | "INVALID_BODY", status: 400 | 408 | 413, message: string);
+}
+/**
+ * Read the exact body bytes with a size bound and a total deadline, cancelling
+ * on failure. A single transport chunk may exceed the limit; it is rejected
+ * before being retained. Framework/ingress limits must also bound the
+ * transport's own buffering.
+ */
+export declare function readBoundedBytes(request: Pick<Request, "headers" | "body">, maxBytes: number, timeoutMs?: number): Promise<Uint8Array>;
+/** {@link readBoundedBytes}, decoded as UTF-8 (invalid sequences become U+FFFD). */
+export declare function readBoundedBody(request: Pick<Request, "headers" | "body">, maxBytes: number, timeoutMs?: number): Promise<string>;
+//# sourceMappingURL=request-body.d.ts.map

package/dist/security/request-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-body.d.ts","sourceRoot":"","sources":["../../src/security/request-body.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,qBAAa,aAAc,SAAQ,KAAK;aAEtB,IAAI,EAAE,gBAAgB,GAAG,cAAc,GAAG,cAAc;aACxD,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG;gBADvB,IAAI,EAAE,gBAAgB,GAAG,cAAc,GAAG,cAAc,EACxD,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,EACvC,OAAO,EAAE,MAAM;CAKhB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC,EAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,SAAQ,GACf,OAAO,CAAC,UAAU,CAAC,CA8DrB;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CACpC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC,EAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,SAAQ,GACf,OAAO,CAAC,MAAM,CAAC,CAEjB"}

package/dist/security/request-body.js

@@ -0,0 +1,84 @@
+/** Failures raised before an oversized or stalled body is fully materialized. */
+export class BodyReadError extends Error {
+    code;
+    status;
+    constructor(code, status, message) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "BodyReadError";
+    }
+}
+/**
+ * Read the exact body bytes with a size bound and a total deadline, cancelling
+ * on failure. A single transport chunk may exceed the limit; it is rejected
+ * before being retained. Framework/ingress limits must also bound the
+ * transport's own buffering.
+ */
+export async function readBoundedBytes(request, maxBytes, timeoutMs = 5_000) {
+    if (!Number.isSafeInteger(maxBytes) ||
+        maxBytes < 0 ||
+        !Number.isFinite(timeoutMs) ||
+        timeoutMs <= 0)
+        throw new Error("Invalid body budget");
+    const declared = request.headers.get("content-length");
+    const cancel = () => {
+        void request.body?.cancel().catch(() => { });
+    };
+    if (declared !== null && !/^\d+$/.test(declared)) {
+        cancel();
+        throw new BodyReadError("INVALID_BODY", 400, "Invalid Content-Length");
+    }
+    if (declared !== null && Number(declared) > maxBytes) {
+        cancel();
+        throw new BodyReadError("BODY_TOO_LARGE", 413, "Request body too large");
+    }
+    if (!request.body)
+        return new Uint8Array();
+    const reader = request.body.getReader();
+    let timer;
+    let finished = false;
+    try {
+        return await Promise.race([
+            (async () => {
+                const chunks = [];
+                let total = 0;
+                while (!finished) {
+                    const { value, done } = await reader.read();
+                    if (finished)
+                        break;
+                    if (done) {
+                        const bytes = new Uint8Array(total);
+                        let offset = 0;
+                        for (const chunk of chunks) {
+                            bytes.set(chunk, offset);
+                            offset += chunk.byteLength;
+                        }
+                        return bytes;
+                    }
+                    total += value.byteLength;
+                    if (total > maxBytes)
+                        throw new BodyReadError("BODY_TOO_LARGE", 413, "Request body too large");
+                    chunks.push(value);
+                }
+                throw new BodyReadError("BODY_TIMEOUT", 408, "Request body timed out");
+            })(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new BodyReadError("BODY_TIMEOUT", 408, "Request body timed out")), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        finished = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        // Do not wait for an uncooperative upstream cancellation.
+        void reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** {@link readBoundedBytes}, decoded as UTF-8 (invalid sequences become U+FFFD). */
+export async function readBoundedBody(request, maxBytes, timeoutMs = 5_000) {
+    return new TextDecoder().decode(await readBoundedBytes(request, maxBytes, timeoutMs));
+}
+//# sourceMappingURL=request-body.js.map

package/dist/security/request-body.js.map

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

package/dist/security/signing.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Devora request signing, version 3.
+ *
+ * The signature covers the exact bytes on the wire: raw path, raw query and a
+ * SHA-256 of the raw body, plus the direction the request travels in. Every
+ * header has one accepted spelling. The canonical string joins fields with
+ * `\n`; each field's grammar excludes `\n`, so the encoding is injective.
+ *
+ * This module is pure (no hashing): runtimes supply SHA-256 and HMAC.
+ * Conformance vectors: packages/sdks/test/signing-v3-vectors.json.
+ *
+ * @module @devorash/core/security/signing
+ */
+export declare const SIGNING: {
+    readonly VERSION: "3";
+    readonly ALGORITHM: "DEVORA-HMAC-SHA256";
+    /** Devora backend -> customer backend (the SDK verifies). */
+    readonly DEVORA_TO_CUSTOMER: "devora-to-customer";
+    /** Customer backend SDK -> Devora backend (Devora verifies). */
+    readonly CUSTOMER_TO_DEVORA: "customer-to-devora";
+    /** SHA-256 of an empty body. */
+    readonly EMPTY_BODY_SHA256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+};
+export type SigningDirection = typeof SIGNING.DEVORA_TO_CUSTOMER | typeof SIGNING.CUSTOMER_TO_DEVORA;
+/** Exact header grammars. (?![\s\S]) requires the actual end of input;
+ * JavaScript's $ also accepts a position before a final newline. */
+export declare const SIGNED_HEADER_PATTERNS: {
+    readonly signatureVersion: RegExp;
+    readonly keyId: RegExp;
+    readonly orgId: RegExp;
+    readonly sentAt: RegExp;
+    readonly requestId: RegExp;
+    readonly signature: RegExp;
+    readonly method: RegExp;
+    readonly bodySha256: RegExp;
+    /** The full secret string; its ASCII bytes are the HMAC key. */
+    readonly secretKey: RegExp;
+};
+export type SignatureErrorCode = "INVALID_SIGNATURE_HEADERS" | "UNSUPPORTED_SIGNATURE_VERSION" | "ORG_MISMATCH" | "TIMESTAMP_EXPIRED" | "INVALID_REQUEST_TARGET" | "UNSUPPORTED_CONTENT_ENCODING" | "INVALID_SIGNATURE" | "REPLAYED_REQUEST" | "REPLAY_STORE_UNAVAILABLE";
+/** Header values as frameworks expose them. */
+export type HeaderMap = Record<string, string | string[] | undefined>;
+export interface SignatureHeaders {
+    keyId: string;
+    orgId: string;
+    sentAt: string;
+    requestId: string;
+    signature: string;
+}
+export type SignatureHeaderResult = {
+    valid: true;
+    headers: SignatureHeaders;
+} | {
+    valid: false;
+    errorCode: SignatureErrorCode;
+    error: string;
+};
+export interface CanonicalFields {
+    direction: SigningDirection;
+    keyId: string;
+    orgId: string;
+    sentAt: string;
+    requestId: string;
+    method: string;
+    /** Raw, percent-encoded path (mount-relative for devora-to-customer). */
+    path: string;
+    /** Raw query after the first `?`, exactly as sent; "" when absent. */
+    query: string;
+    /** Lowercase hex SHA-256 of the exact body bytes. */
+    bodySha256: string;
+}
+/** UTF-8 percent-encode every byte outside `A-Z a-z 0-9 - _ . ~`, with uppercase hex. */
+export declare function strictEncode(value: string): string;
+/**
+ * Encode one path parameter. `""`, `.` and `..` are refused: URL parsers
+ * remove dot segments (even `%2E%2E`), so they cannot be sent as signed.
+ */
+export declare function encodePathParam(value: string): string;
+/** Strict-encoded `key=value` pairs, in the given order (the order is signed). */
+export declare function buildStrictQuery(pairs: ReadonlyArray<readonly [string, string]>): string;
+/**
+ * A raw request path as signed: absolute, printable ASCII, uppercase escapes,
+ * and no empty or dot segments.
+ */
+export declare function isValidSignedPath(path: string): boolean;
+/** A raw query as signed: printable ASCII, no fragment, uppercase escapes. */
+export declare function isValidSignedQuery(query: string): boolean;
+/** Build the canonical string. Throws if any field is outside its grammar. */
+export declare function buildCanonicalString(fields: CanonicalFields): string;
+/**
+ * The single value of a header, or `null` when it is present more than once
+ * (an array, or a comma-joined value that the grammar then rejects).
+ */
+export declare function getSingleHeader(headers: HeaderMap, name: string): string | undefined | null;
+/** Parse and validate the signature headers. Never first-wins, never trims. */
+export declare function parseSignatureHeaders(headers: HeaderMap): SignatureHeaderResult;
+/** Accept only an absent or `identity` Content-Encoding (the body digest is over wire bytes). */
+export declare function hasIdentityContentEncoding(headers: HeaderMap): boolean;
+/** Replay-store namespace: version, direction and key. */
+export declare function replayNamespace(direction: SigningDirection, keyId: string): string;
+/**
+ * Nonce lifetime covering the whole acceptance window: the floor second of the
+ * timestamp check plus one second of clock jitter.
+ */
+export declare function replayExpiresAtMs(sentAt: number, nowSeconds: number, toleranceSeconds: number): number;
+/**
+ * Parse a verified raw query into a null-prototype map. Repeated keys become
+ * arrays in wire order; `__proto__` and `constructor` are ordinary keys.
+ */
+export declare function parseVerifiedQuery(query: string): Record<string, string | string[]>;
+export type VerifiedBodyResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Decode a verified body: empty means `undefined`; otherwise it must be JSON
+ * (declared `application/json`) and strictly valid UTF-8.
+ */
+export declare function parseVerifiedJsonBody(bytes: Uint8Array, contentType: string | undefined | null): VerifiedBodyResult;
+/**
+ * Last `count` segments of a raw path, i.e. the path relative to a mount whose
+ * route template has `count` segments. `null` when the path is shorter.
+ */
+export declare function routeRelativePath(rawPath: string, routeTemplate: string): string | null;
+//# sourceMappingURL=signing.d.ts.map

package/dist/security/signing.d.ts.map

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