@hardenlabs/hmac 0.1.0

package/dist/http-client.d.ts

@@ -0,0 +1,61 @@
+/** Options for HTTP request methods. */
+export interface RequestOptions {
+    headers?: Record<string, string>;
+}
+/** Normalized HTTP response, adapter-independent. */
+export interface HmacResponse {
+    status: number;
+    headers: Record<string, string>;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** HTTP client with automatic HMAC signing. */
+export interface HmacClient {
+    get(path: string, options?: RequestOptions): Promise<HmacResponse>;
+    post(path: string, body?: string, options?: RequestOptions): Promise<HmacResponse>;
+    put(path: string, body?: string, options?: RequestOptions): Promise<HmacResponse>;
+    patch(path: string, body?: string, options?: RequestOptions): Promise<HmacResponse>;
+    delete(path: string, options?: RequestOptions): Promise<HmacResponse>;
+    /** Generic request method for non-standard HTTP methods. */
+    request(method: string, path: string, body?: string, options?: RequestOptions): Promise<HmacResponse>;
+}
+/** Adapter interface that abstracts the underlying HTTP transport (fetch vs axios). */
+export interface HttpAdapter {
+    request(url: string, method: string, body: string | undefined, headers: Record<string, string>): Promise<HmacResponse>;
+}
+/** Adapter that uses the Fetch API as the underlying HTTP transport. */
+export declare class FetchAdapter implements HttpAdapter {
+    private fetchFn;
+    constructor(fetchFn?: typeof globalThis.fetch);
+    request(url: string, method: string, body: string | undefined, headers: Record<string, string>): Promise<HmacResponse>;
+}
+/**
+ * Minimal axios instance type to avoid requiring the axios package at compile time.
+ * Users pass their own axios instance; we only depend on the shape.
+ */
+export interface AxiosInstance {
+    request(config: {
+        url: string;
+        method: string;
+        data?: string;
+        headers?: Record<string, string>;
+    }): Promise<{
+        status: number;
+        headers: Record<string, string>;
+        data: unknown;
+    }>;
+}
+/** Adapter that uses an axios instance as the underlying HTTP transport. */
+export declare class AxiosAdapter implements HttpAdapter {
+    private axios;
+    constructor(axiosInstance: AxiosInstance);
+    request(url: string, method: string, body: string | undefined, headers: Record<string, string>): Promise<HmacResponse>;
+}
+/** Options for creating an HmacClientFactory. */
+export interface HmacClientFactoryOptions {
+    /** Custom fetch function. Ignored if axios is provided. */
+    fetchFn?: typeof globalThis.fetch;
+    /** Axios instance to use instead of fetch. */
+    axios?: AxiosInstance;
+}
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

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

package/dist/http-client.js

@@ -0,0 +1,51 @@
+/** Adapter that uses the Fetch API as the underlying HTTP transport. */
+export class FetchAdapter {
+    fetchFn;
+    constructor(fetchFn) {
+        this.fetchFn = fetchFn ?? globalThis.fetch;
+    }
+    async request(url, method, body, headers) {
+        const resp = await this.fetchFn(url, { method, body, headers });
+        const responseHeaders = {};
+        resp.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        // Cache the body text so both json() and text() work without double-consuming
+        let cachedText;
+        return {
+            status: resp.status,
+            headers: responseHeaders,
+            async json() {
+                cachedText ??= await resp.text();
+                return JSON.parse(cachedText);
+            },
+            async text() {
+                cachedText ??= await resp.text();
+                return cachedText;
+            },
+        };
+    }
+}
+/** Adapter that uses an axios instance as the underlying HTTP transport. */
+export class AxiosAdapter {
+    axios;
+    constructor(axiosInstance) {
+        this.axios = axiosInstance;
+    }
+    async request(url, method, body, headers) {
+        const resp = await this.axios.request({ url, method, data: body, headers });
+        const data = resp.data;
+        const text = typeof data === "string" ? data : JSON.stringify(data);
+        return {
+            status: resp.status,
+            headers: resp.headers,
+            async json() {
+                return typeof data === "string" ? JSON.parse(data) : data;
+            },
+            async text() {
+                return text;
+            },
+        };
+    }
+}
+//# sourceMappingURL=http-client.js.map

package/dist/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAkCA,wEAAwE;AACxE,MAAM,OAAO,YAAY;IACf,OAAO,CAA0B;IAEzC,YAAY,OAAiC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,OAAO,CACX,GAAW,EACX,MAAc,EACd,IAAwB,EACxB,OAA+B;QAE/B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChE,MAAM,eAAe,GAA2B,EAAE,CAAC;QACnD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YAClC,eAAe,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC/B,CAAC,CAAC,CAAC;QAEH,8EAA8E;QAC9E,IAAI,UAA8B,CAAC;QACnC,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,eAAe;YACxB,KAAK,CAAC,IAAI;gBACR,UAAU,KAAK,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;gBACjC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAChC,CAAC;YACD,KAAK,CAAC,IAAI;gBACR,UAAU,KAAK,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;gBACjC,OAAO,UAAU,CAAC;YACpB,CAAC;SACF,CAAC;IACJ,CAAC;CACF;AAmBD,4EAA4E;AAC5E,MAAM,OAAO,YAAY;IACf,KAAK,CAAgB;IAE7B,YAAY,aAA4B;QACtC,IAAI,CAAC,KAAK,GAAG,aAAa,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO,CACX,GAAW,EACX,MAAc,EACd,IAAwB,EACxB,OAA+B;QAE/B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACpE,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAiC;YAC/C,KAAK,CAAC,IAAI;gBACR,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC5D,CAAC;YACD,KAAK,CAAC,IAAI;gBACR,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { buildCanonicalString, buildSignedHeaders, type CanonicalStringParams, type SignedHeadersResult, } from "./canonical.js";
+export { type HmacClientIdentity, type HmacConfig, type HmacTargetConfig, type SignedHeadersConfig, SIGNATURE_HEADER, TIMESTAMP_HEADER, SIGNED_HEADERS_HEADER, CLIENT_ID_HEADER, DEFAULT_TIMESTAMP_TOLERANCE_SECONDS, defaultSignedHeadersConfig, noneSignedHeadersConfig, createHmacConfig, getEffectiveSecret, getEffectiveSignedHeaders, getEffectiveTimestampTolerance, configForTarget, } from "./config.js";
+export { HmacValidationError, type HmacErrorType } from "./errors.js";
+export { sign, verify } from "./signing.js";
+export { validateRequest, type ValidateRequestParams } from "./validation.js";
+export { signRequestHeaders, createSignedFetch } from "./middleware/fetch.js";
+export { hardenHmacMiddleware, type SecretResolver } from "./middleware/express.js";
+export { fromEnv } from "./env-loader.js";
+export { createHmacClientFactory, type HmacClientFactory, } from "./client-factory.js";
+export { FetchAdapter, AxiosAdapter, type HmacClient, type HmacResponse, type RequestOptions, type HttpAdapter, type AxiosInstance, type HmacClientFactoryOptions, } from "./http-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,mCAAmC,EACnC,0BAA0B,EAC1B,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,8BAA8B,EAC9B,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEpF,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,wBAAwB,GAC9B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { buildCanonicalString, buildSignedHeaders, } from "./canonical.js";
+export { SIGNATURE_HEADER, TIMESTAMP_HEADER, SIGNED_HEADERS_HEADER, CLIENT_ID_HEADER, DEFAULT_TIMESTAMP_TOLERANCE_SECONDS, defaultSignedHeadersConfig, noneSignedHeadersConfig, createHmacConfig, getEffectiveSecret, getEffectiveSignedHeaders, getEffectiveTimestampTolerance, configForTarget, } from "./config.js";
+export { HmacValidationError } from "./errors.js";
+export { sign, verify } from "./signing.js";
+export { validateRequest } from "./validation.js";
+export { signRequestHeaders, createSignedFetch } from "./middleware/fetch.js";
+export { hardenHmacMiddleware } from "./middleware/express.js";
+export { fromEnv } from "./env-loader.js";
+export { createHmacClientFactory, } from "./client-factory.js";
+export { FetchAdapter, AxiosAdapter, } from "./http-client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAKL,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,mCAAmC,EACnC,0BAA0B,EAC1B,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,8BAA8B,EAC9B,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAsB,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,eAAe,EAA8B,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAuB,MAAM,yBAAyB,CAAC;AAEpF,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,OAAO,EACL,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,YAAY,GAOb,MAAM,kBAAkB,CAAC"}

package/dist/middleware/express.d.ts

@@ -0,0 +1,24 @@
+import type { Request, Response, NextFunction } from "express";
+import type { HmacConfig } from "../config.js";
+/**
+ * Optional callback to resolve the shared secret per-request.
+ * Return the Base64-encoded secret, or null/undefined to fall back to config.sharedSecretBase64.
+ */
+export type SecretResolver = (req: Request) => string | null | undefined | Promise<string | null | undefined>;
+/**
+ * Create an Express middleware that validates incoming HMAC-signed requests.
+ *
+ * IMPORTANT: This middleware requires the raw request body as a string or Buffer.
+ * Use `express.text({ type: "*\/*" })` or `express.raw()` upstream — NOT `express.json()`.
+ *
+ * If `express.json()` runs first, `req.body` will be a parsed object and
+ * `JSON.stringify(req.body)` may produce different output than the original raw body,
+ * causing signature verification to fail. In that case this middleware returns 400
+ * with a descriptive error rather than silently producing incorrect results.
+ *
+ * @param config - HMAC configuration with shared secret and tolerance.
+ * @param secretResolver - Optional callback to resolve the secret per-request (e.g., for multi-tenant).
+ * @returns Express middleware function.
+ */
+export declare function hardenHmacMiddleware(config: HmacConfig, secretResolver?: SecretResolver): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=express.d.ts.map

package/dist/middleware/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK/C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,OAAO,KACT,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,cAAc,CAAC,EAAE,cAAc,GAC9B,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAsI3D"}

package/dist/middleware/express.js

@@ -0,0 +1,145 @@
+import { CLIENT_ID_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER } from "../config.js";
+import { HmacValidationError } from "../errors.js";
+import { validateRequest } from "../validation.js";
+/**
+ * Create an Express middleware that validates incoming HMAC-signed requests.
+ *
+ * IMPORTANT: This middleware requires the raw request body as a string or Buffer.
+ * Use `express.text({ type: "*\/*" })` or `express.raw()` upstream — NOT `express.json()`.
+ *
+ * If `express.json()` runs first, `req.body` will be a parsed object and
+ * `JSON.stringify(req.body)` may produce different output than the original raw body,
+ * causing signature verification to fail. In that case this middleware returns 400
+ * with a descriptive error rather than silently producing incorrect results.
+ *
+ * @param config - HMAC configuration with shared secret and tolerance.
+ * @param secretResolver - Optional callback to resolve the secret per-request (e.g., for multi-tenant).
+ * @returns Express middleware function.
+ */
+export function hardenHmacMiddleware(config, secretResolver) {
+    return (req, res, next) => {
+        // Collect body as string.
+        // Reject parsed objects — they cannot be reliably re-serialized to the original wire format.
+        let body = "";
+        if (typeof req.body === "string") {
+            body = req.body;
+        }
+        else if (Buffer.isBuffer(req.body)) {
+            body = req.body.toString("utf8");
+        }
+        else if (req.body !== undefined && req.body !== null) {
+            // If it's a plain object with no keys, treat as empty body.
+            // Express can set req.body = {} when no body parser matches.
+            if (typeof req.body === "object" &&
+                Object.keys(req.body).length === 0) {
+                body = "";
+            }
+            else {
+                // req.body is a parsed object (e.g. from express.json()). This is not safe for HMAC
+                // because JSON.stringify may differ from the original wire bytes.
+                res.status(400).json({
+                    error: "body_not_raw",
+                    message: "HardenHMAC middleware requires the raw request body. " +
+                        "Use express.text() or express.raw() instead of express.json() " +
+                        "before this middleware.",
+                });
+                return;
+            }
+        }
+        const path = req.originalUrl ?? req.url;
+        // Extract headers as record
+        const requestHeaders = {};
+        for (const [name, value] of Object.entries(req.headers)) {
+            if (typeof value === "string") {
+                requestHeaders[name] = value;
+            }
+            else if (Array.isArray(value)) {
+                requestHeaders[name] = value.join(", ");
+            }
+        }
+        const rawSig = req.headers[SIGNATURE_HEADER.toLowerCase()];
+        const signatureHeader = Array.isArray(rawSig) ? rawSig[0] : rawSig;
+        const rawTs = req.headers[TIMESTAMP_HEADER.toLowerCase()];
+        const timestampHeader = Array.isArray(rawTs) ? rawTs[0] : rawTs;
+        // Validate with the resolved secret
+        const validateWithSecret = (secret) => {
+            const effectiveConfig = {
+                ...config,
+                sharedSecretBase64: secret,
+            };
+            try {
+                validateRequest(effectiveConfig, {
+                    method: req.method,
+                    path,
+                    body,
+                    signatureHeader,
+                    timestampHeader,
+                    requestHeaders,
+                });
+            }
+            catch (error) {
+                if (error instanceof HmacValidationError) {
+                    const statusCode = error.errorType === "missing_signature" ||
+                        error.errorType === "missing_timestamp" ||
+                        error.errorType === "invalid_timestamp"
+                        ? 400
+                        : 401;
+                    res.status(statusCode).json({
+                        error: error.errorType,
+                        message: error.message,
+                    });
+                    return;
+                }
+                throw error;
+            }
+            next();
+        };
+        // Resolution chain: resolver -> Clients dict -> config fallback
+        const resolveAndValidate = (resolverResult) => {
+            // 1. secretResolver callback result
+            if (resolverResult) {
+                validateWithSecret(resolverResult);
+                return;
+            }
+            // 2. X-Harden-Client-Id header -> look up in config.clients
+            const clientId = requestHeaders[CLIENT_ID_HEADER.toLowerCase()];
+            if (clientId) {
+                const clientIdentity = config.clients?.[clientId];
+                if (clientIdentity?.sharedSecret) {
+                    validateWithSecret(clientIdentity.sharedSecret);
+                    return;
+                }
+                // Client ID was provided but not found
+                res.status(401).json({
+                    error: "unknown_client",
+                    message: "Unknown or unconfigured client.",
+                });
+                return;
+            }
+            // 3. Fall back to config.sharedSecretBase64
+            if (config.sharedSecretBase64) {
+                validateWithSecret(config.sharedSecretBase64);
+                return;
+            }
+            // 4. No secret available
+            res.status(401).json({
+                error: "no_secret",
+                message: "No shared secret configured for this request.",
+            });
+        };
+        if (secretResolver) {
+            const result = secretResolver(req);
+            if (result instanceof Promise) {
+                result.then(resolveAndValidate).catch((err) => {
+                    next(err);
+                });
+                return;
+            }
+            resolveAndValidate(result);
+        }
+        else {
+            resolveAndValidate(null);
+        }
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/middleware/express.js.map

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

package/dist/middleware/fetch.d.ts

@@ -0,0 +1,16 @@
+import type { HmacConfig } from "../config.js";
+/**
+ * Sign headers for an outgoing request.
+ *
+ * Returns a Record of headers to add to the request.
+ */
+export declare function signRequestHeaders(config: HmacConfig, method: string, path: string, body?: string, requestHeaders?: Record<string, string>, timestamp?: number): Record<string, string>;
+/**
+ * Create a fetch wrapper that automatically signs outgoing requests.
+ *
+ * @param config - HMAC configuration with shared secret.
+ * @param fetchFn - The fetch function to wrap (defaults to globalThis.fetch).
+ * @returns A function that signs requests before passing them to the underlying fetch.
+ */
+export declare function createSignedFetch(config: HmacConfig, fetchFn?: typeof globalThis.fetch): (url: string | URL, init?: RequestInit) => Promise<Response>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/middleware/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/middleware/fetch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ/C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAW,EACjB,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAC3C,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6BxB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,GAChC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CA+E9D"}

package/dist/middleware/fetch.js

@@ -0,0 +1,105 @@
+import { buildCanonicalString, buildSignedHeaders } from "../canonical.js";
+import { SIGNATURE_HEADER, SIGNED_HEADERS_HEADER, TIMESTAMP_HEADER, } from "../config.js";
+import { sign } from "../signing.js";
+/**
+ * Sign headers for an outgoing request.
+ *
+ * Returns a Record of headers to add to the request.
+ */
+export function signRequestHeaders(config, method, path, body = "", requestHeaders = {}, timestamp) {
+    const ts = timestamp ?? Math.floor(Date.now() / 1000);
+    const { headerNames } = buildSignedHeaders(config.signedHeaders, requestHeaders);
+    const canonicalString = buildCanonicalString({
+        method,
+        path,
+        body,
+        timestamp: ts,
+        signedHeadersConfig: config.signedHeaders,
+        requestHeaders,
+    });
+    const signature = sign(config.sharedSecretBase64, canonicalString);
+    const result = {
+        [SIGNATURE_HEADER]: signature,
+        [TIMESTAMP_HEADER]: String(ts),
+    };
+    if (headerNames.length > 0) {
+        result[SIGNED_HEADERS_HEADER] = headerNames.join(";");
+    }
+    return result;
+}
+/**
+ * Create a fetch wrapper that automatically signs outgoing requests.
+ *
+ * @param config - HMAC configuration with shared secret.
+ * @param fetchFn - The fetch function to wrap (defaults to globalThis.fetch).
+ * @returns A function that signs requests before passing them to the underlying fetch.
+ */
+export function createSignedFetch(config, fetchFn) {
+    const baseFetch = fetchFn ?? globalThis.fetch;
+    return async (url, init) => {
+        let path;
+        if (typeof url === "string") {
+            // Handle both absolute URLs and relative paths
+            if (url.startsWith("/") || url.startsWith("?")) {
+                path = url;
+            }
+            else {
+                try {
+                    const parsedUrl = new URL(url);
+                    path = parsedUrl.pathname + parsedUrl.search;
+                }
+                catch {
+                    // Treat as relative path if URL parsing fails
+                    path = url;
+                }
+            }
+        }
+        else {
+            path = url.pathname + url.search;
+        }
+        const method = init?.method ?? "GET";
+        // Only string bodies are supported for HMAC signing.
+        // Non-string bodies (Blob, FormData, ReadableStream, etc.) cannot be
+        // reliably converted to the same bytes the server will receive.
+        let body = "";
+        if (init?.body !== undefined && init?.body !== null) {
+            if (typeof init.body === "string") {
+                body = init.body;
+            }
+            else {
+                throw new Error("HardenHMAC: Only string request bodies are supported for HMAC signing. " +
+                    "Convert your body to a string before passing it to fetch.");
+            }
+        }
+        // Collect existing headers, normalizing keys to lowercase
+        // to avoid case-sensitive duplicates (HTTP headers are case-insensitive)
+        const existingHeaders = {};
+        if (init?.headers) {
+            if (init.headers instanceof Headers) {
+                init.headers.forEach((value, key) => {
+                    existingHeaders[key.toLowerCase()] = value;
+                });
+            }
+            else if (Array.isArray(init.headers)) {
+                for (const [key, value] of init.headers) {
+                    existingHeaders[key.toLowerCase()] = String(value);
+                }
+            }
+            else {
+                for (const [key, value] of Object.entries(init.headers)) {
+                    existingHeaders[key.toLowerCase()] = String(value);
+                }
+            }
+        }
+        const sigHeaders = signRequestHeaders(config, method, path, body, existingHeaders);
+        const mergedHeaders = {
+            ...existingHeaders,
+            ...sigHeaders,
+        };
+        return baseFetch(url, {
+            ...init,
+            headers: mergedHeaders,
+        });
+    };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/middleware/fetch.js.map

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

package/dist/signing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compute the HMAC-SHA256 signature of a canonical string.
+ *
+ * @param sharedSecretBase64 - The shared secret as a Base64-encoded string.
+ * @param canonicalString - The canonical string to sign.
+ * @returns Lowercase hexadecimal signature string (64 characters).
+ */
+export declare function sign(sharedSecretBase64: string, canonicalString: string): string;
+/**
+ * Verify a signature against a canonical string using constant-time comparison.
+ *
+ * @param sharedSecretBase64 - The shared secret as a Base64-encoded string.
+ * @param canonicalString - The canonical string that was signed.
+ * @param signature - The signature to verify (64-char lowercase hex).
+ * @returns True if the signature is valid.
+ */
+export declare function verify(sharedSecretBase64: string, canonicalString: string, signature: string): boolean;
+//# sourceMappingURL=signing.d.ts.map

package/dist/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAgCA;;;;;;GAMG;AACH,wBAAgB,IAAI,CAClB,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,GACtB,MAAM,CAWR;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAWT"}

package/dist/signing.js

@@ -0,0 +1,62 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const BASE64_REGEX = /^[A-Za-z0-9+/]*={0,2}$/;
+/**
+ * Validate that a string is valid standard Base64.
+ * Throws a descriptive error if the input contains invalid characters.
+ */
+function validateBase64(input, label) {
+    const stripped = input.replace(/\s/g, "");
+    if (stripped.length === 0) {
+        throw new Error(`${label} is empty after stripping whitespace.`);
+    }
+    if (stripped.length % 4 !== 0) {
+        throw new Error(`${label} is not valid Base64. Length must be a multiple of 4 (got ${stripped.length}).`);
+    }
+    if (!BASE64_REGEX.test(stripped)) {
+        throw new Error(`${label} is not valid Base64. Contains characters outside the Base64 alphabet.`);
+    }
+    // Round-trip validation: decode then re-encode to catch padding mismatches
+    const decoded = Buffer.from(stripped, "base64");
+    if (decoded.toString("base64") !== stripped) {
+        throw new Error(`${label} is not valid Base64. Decoded/re-encoded value does not match input.`);
+    }
+}
+/**
+ * Compute the HMAC-SHA256 signature of a canonical string.
+ *
+ * @param sharedSecretBase64 - The shared secret as a Base64-encoded string.
+ * @param canonicalString - The canonical string to sign.
+ * @returns Lowercase hexadecimal signature string (64 characters).
+ */
+export function sign(sharedSecretBase64, canonicalString) {
+    const stripped = sharedSecretBase64.replace(/\s/g, "");
+    validateBase64(stripped, "sharedSecretBase64");
+    const keyBytes = Buffer.from(stripped, "base64");
+    try {
+        const hmac = createHmac("sha256", keyBytes);
+        hmac.update(canonicalString, "utf8");
+        return hmac.digest("hex");
+    }
+    finally {
+        keyBytes.fill(0);
+    }
+}
+/**
+ * Verify a signature against a canonical string using constant-time comparison.
+ *
+ * @param sharedSecretBase64 - The shared secret as a Base64-encoded string.
+ * @param canonicalString - The canonical string that was signed.
+ * @param signature - The signature to verify (64-char lowercase hex).
+ * @returns True if the signature is valid.
+ */
+export function verify(sharedSecretBase64, canonicalString, signature) {
+    // sign() handles stripping and validation
+    const expected = sign(sharedSecretBase64, canonicalString);
+    const expectedBuf = Buffer.from(expected, "utf8");
+    const signatureBuf = Buffer.from(signature, "utf8");
+    if (expectedBuf.length !== signatureBuf.length) {
+        return false;
+    }
+    return timingSafeEqual(expectedBuf, signatureBuf);
+}
+//# sourceMappingURL=signing.js.map

package/dist/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAE9C;;;GAGG;AACH,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,uCAAuC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,6DAA6D,QAAQ,CAAC,MAAM,IAAI,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,wEAAwE,CACjF,CAAC;IACJ,CAAC;IACD,2EAA2E;IAC3E,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,sEAAsE,CAC/E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAClB,kBAA0B,EAC1B,eAAuB;IAEvB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACvD,cAAc,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;YAAS,CAAC;QACT,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CACpB,kBAA0B,EAC1B,eAAuB,EACvB,SAAiB;IAEjB,0CAA0C;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAEpD,IAAI,WAAW,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;AACpD,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,21 @@
+import type { HmacConfig } from "./config.js";
+/** Parameters for request validation. */
+export interface ValidateRequestParams {
+    method: string;
+    path: string;
+    body: string;
+    signatureHeader: string | undefined | null;
+    timestampHeader: string | undefined | null;
+    requestHeaders?: Record<string, string>;
+    /** Override current timestamp for testing. */
+    currentTimestamp?: number;
+}
+/**
+ * Validate an HMAC-signed request.
+ *
+ * Checks timestamp freshness and signature correctness.
+ *
+ * @throws {HmacValidationError} If validation fails.
+ */
+export declare function validateRequest(config: HmacConfig, params: ValidateRequestParams): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC3C,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,qBAAqB,GAC5B,IAAI,CAyEN"}

package/dist/validation.js

@@ -0,0 +1,47 @@
+import { buildCanonicalString } from "./canonical.js";
+import { HmacValidationError } from "./errors.js";
+import { verify } from "./signing.js";
+/**
+ * Validate an HMAC-signed request.
+ *
+ * Checks timestamp freshness and signature correctness.
+ *
+ * @throws {HmacValidationError} If validation fails.
+ */
+export function validateRequest(config, params) {
+    const { method, path, body, signatureHeader, timestampHeader, requestHeaders, currentTimestamp, } = params;
+    if (!signatureHeader) {
+        throw new HmacValidationError("missing_signature", "X-Harden-Signature header is required.");
+    }
+    if (!timestampHeader) {
+        throw new HmacValidationError("missing_timestamp", "X-Harden-Timestamp header is required.");
+    }
+    const trimmedTimestamp = timestampHeader.trim();
+    if (!/^-?\d+$/.test(trimmedTimestamp)) {
+        throw new HmacValidationError("invalid_timestamp", "X-Harden-Timestamp header is not a valid integer.");
+    }
+    const requestTimestamp = parseInt(trimmedTimestamp, 10);
+    if (isNaN(requestTimestamp)) {
+        throw new HmacValidationError("invalid_timestamp", "X-Harden-Timestamp header is not a valid integer.");
+    }
+    const now = currentTimestamp ?? Math.floor(Date.now() / 1000);
+    const delta = now - requestTimestamp;
+    if (delta > config.timestampToleranceSeconds) {
+        throw new HmacValidationError("timestamp_expired", `Request timestamp is ${delta} seconds in the past (tolerance: ${config.timestampToleranceSeconds}s).`);
+    }
+    if (delta < -config.timestampToleranceSeconds) {
+        throw new HmacValidationError("timestamp_out_of_range", `Request timestamp is ${-delta} seconds in the future (tolerance: ${config.timestampToleranceSeconds}s).`);
+    }
+    const canonicalString = buildCanonicalString({
+        method,
+        path,
+        body: body ?? "",
+        timestamp: requestTimestamp,
+        signedHeadersConfig: config.signedHeaders,
+        requestHeaders,
+    });
+    if (!verify(config.sharedSecretBase64, canonicalString, signatureHeader)) {
+        throw new HmacValidationError("signature_invalid", "HMAC signature does not match the expected value.");
+    }
+}
+//# sourceMappingURL=validation.js.map