@centralping/ergo 0.1.0-beta.1

package/lib/validate.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview JSON Schema validation factory using AJV 8.
+ *
+ * Compiles a JSON Schema once at creation time and returns a validator function.
+ * The validator throws `422 Unprocessable Entity` with structured error details
+ * when validation fails, returning the input data unchanged on success.
+ *
+ * Used by `http/validate.js` as the pure-logic backing implementation.
+ *
+ * @module lib/validate
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ajv
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import createValidator from 'ergo/lib/validate';
+ *
+ * const validate = createValidator({
+ *   type: 'object',
+ *   properties: {name: {type: 'string'}},
+ *   required: ['name']
+ * });
+ *
+ * validate({name: 'Alice'});       // returns {name: 'Alice'}
+ * validate({});                    // throws 422 with details
+ */
+import Ajv from 'ajv';
+import httpErrors from '../utils/http-errors.js';
+
+/**
+ * Compiles a JSON Schema and returns a validating function.
+ *
+ * @param {object} schema - JSON Schema 2020-12 or draft-07 object
+ * @param {object} [options] - Validator options
+ * @param {boolean} [options.allErrors=true] - Report all errors instead of stopping at the first
+ * @param {boolean} [options.coerceTypes=false] - Coerce input values to match schema types
+ * @param {object} [options.ajv] - Additional AJV constructor options
+ * @returns {function} - `validateData(data)` — returns `data` on success, throws 422 on failure
+ * @throws {Error} 422 with `details` array if schema validation fails
+ */
+export default function createValidator(schema, options = {}) {
+  const ajv = new Ajv({
+    allErrors: options.allErrors !== false,
+    coerceTypes: options.coerceTypes ?? false,
+    ...options.ajv
+  });
+
+  const validate = ajv.compile(schema);
+
+  return function validateData(data) {
+    const valid = validate(data);
+
+    if (!valid) {
+      throw httpErrors(422, {
+        message: 'Validation failed',
+        details: validate.errors.map(formatError)
+      });
+    }
+
+    return data;
+  };
+}
+
+/**
+ * Formats an AJV error object into a concise detail record.
+ *
+ * @param {object} err - AJV validation error (from `ajv.errors`)
+ * @param {string} err.instancePath - JSON Pointer to the failing field
+ * @param {string} err.message - Human-readable error message
+ * @param {object} err.params - Additional error parameters
+ * @returns {{path: string, message: string, params: object}} - Formatted error detail
+ */
+function formatError(err) {
+  return {
+    path: err.instancePath || '/',
+    message: err.message,
+    params: err.params
+  };
+}

package/lib/vary.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Shared Vary header utility.
+ *
+ * Appends tokens to the `Vary` response header without duplicating existing tokens.
+ * Uses Set-based deduplication with case-insensitive comparison.
+ *
+ * @module lib/vary
+ * @version 0.1.0
+ * @since 0.1.0
+ */
+
+/**
+ * Append a Vary token (or comma-separated tokens) to the response, avoiding duplicates.
+ *
+ * @param {import('node:http').ServerResponse} res - HTTP response object
+ * @param {string} value - Token(s) to append (e.g. "Accept-Encoding" or "Accept, Accept-Encoding")
+ */
+export default function appendVary(res, value) {
+  const existing = res.getHeader('Vary');
+
+  if (!existing) {
+    res.setHeader('Vary', value);
+    return;
+  }
+
+  const tokens = new Set(
+    String(existing)
+      .toLowerCase()
+      .split(/,\s*/)
+      .map(s => s.trim())
+  );
+  const toAdd = value
+    .split(',')
+    .map(s => s.trim())
+    .filter(t => !tokens.has(t.toLowerCase()));
+
+  if (toAdd.length) {
+    res.setHeader('Vary', `${existing}, ${toAdd.join(', ')}`);
+  }
+}

package/package.json

@@ -0,0 +1,158 @@
+{
+  "name": "@centralping/ergo",
+  "version": "0.1.0-beta.1",
+  "description": "A Fast Fail REST API toolkit for Node.js -- composable middleware with structured Negotiation, Authorization, Validation, and Execution stages.",
+  "main": "http/index.js",
+  "type": "module",
+  "types": "types/http/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/http/index.d.ts",
+      "default": "./http/index.js"
+    },
+    "./http": {
+      "types": "./types/http/index.d.ts",
+      "default": "./http/index.js"
+    },
+    "./http/*": {
+      "types": "./types/http/*.d.ts",
+      "default": "./http/*.js"
+    },
+    "./lib/cookie": {
+      "types": "./types/lib/cookie/index.d.ts",
+      "default": "./lib/cookie/index.js"
+    },
+    "./lib/json-api-query": {
+      "types": "./types/lib/json-api-query/index.d.ts",
+      "default": "./lib/json-api-query/index.js"
+    },
+    "./lib/*": {
+      "types": "./types/lib/*.d.ts",
+      "default": "./lib/*.js"
+    },
+    "./utils/buffers": {
+      "types": "./types/utils/buffers/index.d.ts",
+      "default": "./utils/buffers/index.js"
+    },
+    "./utils/iterables": {
+      "types": "./types/utils/iterables/index.d.ts",
+      "default": "./utils/iterables/index.js"
+    },
+    "./utils/observables": {
+      "types": "./types/utils/observables/index.d.ts",
+      "default": "./utils/observables/index.js"
+    },
+    "./utils/streams": {
+      "types": "./types/utils/streams/index.d.ts",
+      "default": "./utils/streams/index.js"
+    },
+    "./utils/*": {
+      "types": "./types/utils/*.d.ts",
+      "default": "./utils/*.js"
+    }
+  },
+  "files": [
+    "http/",
+    "lib/",
+    "utils/",
+    "types/",
+    "!**/*.spec.*.js",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "format": "prettier --write \"**/*.js\"",
+    "format:check": "prettier --check \"**/*.js\"",
+    "pretest": "npm run lint && npm run format:check",
+    "test": "c8 node --test \"**/*.spec.unit.js\" \"**/*.spec.func.js\"",
+    "test:watch": "node --test --watch \"**/*.spec.unit.js\" \"**/*.spec.func.js\"",
+    "preversion": "npm test",
+    "types": "tsc",
+    "prepublishOnly": "npm test && npm run types",
+    "prepare": "simple-git-hooks"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged"
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CentralPing/ergo.git"
+  },
+  "keywords": [
+    "fast-fail",
+    "rest-api",
+    "json-api",
+    "http",
+    "middleware",
+    "streaming",
+    "security",
+    "security-headers",
+    "owasp",
+    "api-security"
+  ],
+  "author": "Jason Cust <jason@centralping.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/CentralPing/ergo/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/CentralPing/ergo",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/jasoncust"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "content-type": "^2.0.0",
+    "etag": "^1.8.1",
+    "negotiator": "^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "c8": "^11.0.0",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "lint-staged": "^17.0.3",
+    "prettier": "^3.8.1",
+    "simple-git-hooks": "^2.12.1",
+    "typescript": "^6.0.3",
+    "undici": "^8.0.1"
+  },
+  "c8": {
+    "include": [
+      "http/**/*.js",
+      "lib/**/*.js",
+      "utils/**/*.js"
+    ],
+    "exclude": [
+      "**/*.spec.*.js",
+      "**/node_modules/**",
+      "**/coverage/**",
+      "benchmarks/**",
+      "eslint.config.js"
+    ],
+    "branches": 80,
+    "functions": 100,
+    "lines": 80,
+    "statements": 80,
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "all": true
+  }
+}

package/types/http/accepts.d.ts

@@ -0,0 +1,8 @@
+declare function _default({ throwIfFail, ...options }?: {
+    throwIfFail?: boolean | undefined;
+    types?: string[] | undefined;
+    languages?: string[] | undefined;
+    charsets?: string[] | undefined;
+    encodings?: string[] | undefined;
+}): Function;
+export default _default;

package/types/http/authorization.d.ts

@@ -0,0 +1,8 @@
+declare function _default({ strategies }?: {
+    strategies?: {
+        type: string;
+        attributes?: object;
+        authorizer: Function;
+    }[] | undefined;
+}): Function;
+export default _default;

package/types/http/body.d.ts

@@ -0,0 +1,20 @@
+declare function _default({ limit, decompressedLimit, types, charset }?: {
+    limit?: number | undefined;
+    decompressedLimit?: number | undefined;
+    types?: string[] | undefined;
+    charset?: string | undefined;
+}): (req: any) => Promise<{
+    type: string;
+    charset: string;
+    encoding: any;
+    length: number | undefined;
+    received: number;
+    boundary: string | undefined;
+    raw: string;
+} | {
+    response: {
+        statusCode: any;
+        detail: any;
+    };
+}>;
+export default _default;

package/types/http/cache-control.d.ts

@@ -0,0 +1,16 @@
+declare function _default({ directives, public: isPublic, private: isPrivate, noCache, noStore, noTransform, mustRevalidate, proxyRevalidate, immutable, maxAge, sMaxAge, staleWhileRevalidate, staleIfError }?: {
+    directives?: string | undefined;
+    public?: boolean | undefined;
+    private?: boolean | undefined;
+    noCache?: boolean | undefined;
+    noStore?: boolean | undefined;
+    noTransform?: boolean | undefined;
+    mustRevalidate?: boolean | undefined;
+    proxyRevalidate?: boolean | undefined;
+    immutable?: boolean | undefined;
+    maxAge?: number | undefined;
+    sMaxAge?: number | undefined;
+    staleWhileRevalidate?: number | undefined;
+    staleIfError?: number | undefined;
+}): Function;
+export default _default;

package/types/http/compress.d.ts

@@ -0,0 +1,5 @@
+declare function _default({ threshold, encodings }?: {
+    threshold?: number | undefined;
+    encodings?: string[] | undefined;
+}): Function;
+export default _default;

package/types/http/cookie.d.ts

@@ -0,0 +1,2 @@
+declare function _default(options?: object): Function;
+export default _default;

package/types/http/cors.d.ts

@@ -0,0 +1,9 @@
+declare function _default(options?: {
+    origins?: string | Function | RegExp | string[] | undefined;
+    allowMethods?: string[] | undefined;
+    allowHeaders?: string | Function | RegExp | string[] | undefined;
+    exposeHeaders?: string | string[] | undefined;
+    allowCredentials?: boolean | undefined;
+    maxAge?: number | undefined;
+}): Function;
+export default _default;

package/types/http/csrf.d.ts

@@ -0,0 +1,9 @@
+declare function _default({ cookieTokenName, headerTokenName, cookieUuidName, secret, encoding, cookieOptions }?: {
+    cookieTokenName?: string | undefined;
+    headerTokenName?: string | undefined;
+    cookieUuidName?: string | undefined;
+    secret: string;
+    encoding?: string | undefined;
+    cookieOptions?: object | undefined;
+}): object;
+export default _default;

package/types/http/handler.d.ts

@@ -0,0 +1,2 @@
+declare function _default(pipeline: Function, sendOptions?: object): Function;
+export default _default;

package/types/http/index.d.ts

@@ -0,0 +1 @@
+export * from "./main.js";

package/types/http/json-api-query.d.ts

@@ -0,0 +1,2 @@
+declare function _default(...options: any[]): Function;
+export default _default;

package/types/http/logger.d.ts

@@ -0,0 +1,9 @@
+declare function _default({ log, error: logError, uuid, headerRequestIdName, headerRequestIpName, redactHeaders }?: {
+    log?: Function | undefined;
+    error?: Function | undefined;
+    uuid?: Function | undefined;
+    headerRequestIdName?: string | undefined;
+    headerRequestIpName?: string | undefined;
+    redactHeaders?: Set<string> | undefined;
+}): object;
+export default _default;

package/types/http/main.d.ts

@@ -0,0 +1,142 @@
+declare const _default: {
+    compose: {
+        (...ops: (Function | any[])[]): Function;
+        all(...ops: (Function | any[])[]): Function;
+    };
+    handler: (pipeline: Function, sendOptions?: object) => Function;
+    accepts: ({ throwIfFail, ...options }?: {
+        throwIfFail?: boolean | undefined;
+        types?: string[] | undefined;
+        languages?: string[] | undefined;
+        charsets?: string[] | undefined;
+        encodings?: string[] | undefined;
+    }) => Function;
+    authorization: ({ strategies }?: {
+        strategies?: {
+            type: string;
+            attributes?: object;
+            authorizer: Function;
+        }[] | undefined;
+    }) => Function;
+    body: ({ limit, decompressedLimit, types, charset }?: {
+        limit?: number | undefined;
+        decompressedLimit?: number | undefined;
+        types?: string[] | undefined;
+        charset?: string | undefined;
+    }) => (req: any) => Promise<{
+        type: string;
+        charset: string;
+        encoding: any;
+        length: number | undefined;
+        received: number;
+        boundary: string | undefined;
+        raw: string;
+    } | {
+        response: {
+            statusCode: any;
+            detail: any;
+        };
+    }>;
+    cacheControl: ({ directives, public: isPublic, private: isPrivate, noCache, noStore, noTransform, mustRevalidate, proxyRevalidate, immutable, maxAge, sMaxAge, staleWhileRevalidate, staleIfError }?: {
+        directives?: string | undefined;
+        public?: boolean | undefined;
+        private?: boolean | undefined;
+        noCache?: boolean | undefined;
+        noStore?: boolean | undefined;
+        noTransform?: boolean | undefined;
+        mustRevalidate?: boolean | undefined;
+        proxyRevalidate?: boolean | undefined;
+        immutable?: boolean | undefined;
+        maxAge?: number | undefined;
+        sMaxAge?: number | undefined;
+        staleWhileRevalidate?: number | undefined;
+        staleIfError?: number | undefined;
+    }) => Function;
+    compress: ({ threshold, encodings }?: {
+        threshold?: number | undefined;
+        encodings?: string[] | undefined;
+    }) => Function;
+    cookie: (options?: object) => Function;
+    cors: (options?: {
+        origins?: string | Function | RegExp | string[] | undefined;
+        allowMethods?: string[] | undefined;
+        allowHeaders?: string | Function | RegExp | string[] | undefined;
+        exposeHeaders?: string | string[] | undefined;
+        allowCredentials?: boolean | undefined;
+        maxAge?: number | undefined;
+    }) => Function;
+    csrf: ({ cookieTokenName, headerTokenName, cookieUuidName, secret, encoding, cookieOptions }?: {
+        cookieTokenName?: string | undefined;
+        headerTokenName?: string | undefined;
+        cookieUuidName?: string | undefined;
+        secret: string;
+        encoding?: string | undefined;
+        cookieOptions?: object | undefined;
+    }) => object;
+    fromConnect: typeof fromConnect;
+    httpErrors: typeof httpErrors;
+    jsonApiQuery: (...options: any[]) => Function;
+    logger: ({ log, error: logError, uuid, headerRequestIdName, headerRequestIpName, redactHeaders }?: {
+        log?: Function | undefined;
+        error?: Function | undefined;
+        uuid?: Function | undefined;
+        headerRequestIdName?: string | undefined;
+        headerRequestIpName?: string | undefined;
+        redactHeaders?: Set<string> | undefined;
+    }) => object;
+    prefer: () => Function;
+    precondition: typeof precondition;
+    rateLimit: typeof rateLimit;
+    securityHeaders: (options?: {
+        contentSecurityPolicy?: string | false | undefined;
+        strictTransportSecurity?: string | false | undefined;
+        xContentTypeOptions?: string | false | undefined;
+        xFrameOptions?: string | false | undefined;
+        referrerPolicy?: string | false | undefined;
+        xXssProtection?: string | false | undefined;
+        permissionsPolicy?: string | undefined;
+    }) => Function;
+    url: () => Function;
+    send: ({ prettify, vary, etag, prefer, envelope }?: {
+        prettify?: boolean | undefined;
+        vary?: string[] | undefined;
+        etag?: boolean | undefined;
+        prefer?: boolean | undefined;
+        envelope?: boolean | Function | undefined;
+    }) => Function;
+    timeout: ({ ms, statusCode }?: {
+        ms?: number | undefined;
+        statusCode?: number | undefined;
+    }) => Function;
+    validate: (schemas?: {
+        body?: object | undefined;
+        query?: object | undefined;
+        params?: object | undefined;
+    }, options?: object) => Function;
+};
+export default _default;
+import compose from '../utils/compose-with.js';
+import { createResponseAcc } from '../utils/compose-with.js';
+import { mergeResponse } from '../utils/compose-with.js';
+import handler from './handler.js';
+import accepts from './accepts.js';
+import authorization from './authorization.js';
+import body from './body.js';
+import cacheControl from './cache-control.js';
+import compress from './compress.js';
+import cookie from './cookie.js';
+import cors from './cors.js';
+import csrf from './csrf.js';
+import fromConnect from '../lib/from-connect.js';
+import httpErrors from '../utils/http-errors.js';
+import jsonApiQuery from './json-api-query.js';
+import logger from './logger.js';
+import prefer from './prefer.js';
+import precondition from './precondition.js';
+import rateLimit from './rate-limit.js';
+import securityHeaders from './security-headers.js';
+import url from './url.js';
+import send from './send.js';
+import timeout from './timeout.js';
+import validate from './validate.js';
+export { compose, createResponseAcc, mergeResponse, handler, accepts, authorization, body, cacheControl, compress, cookie, cors, csrf, fromConnect, httpErrors, jsonApiQuery, logger, prefer, precondition, rateLimit, securityHeaders, url, send, timeout, validate };

package/types/http/precondition.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Precondition Required middleware (RFC 6585 §3).
+ *
+ * Enforces that unsafe requests include a conditional header (`If-Match` or
+ * `If-Unmodified-Since`) before the pipeline proceeds. This prevents "lost update"
+ * problems where a client overwrites changes made by another client without first
+ * fetching the current resource state.
+ *
+ * Placed in Stage 1 (Negotiation) for Fast Fail — the check is a cheap header
+ * inspection that short-circuits before authorization, body parsing, or execution.
+ *
+ * @module http/precondition
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {compose, precondition} from 'ergo';
+ *
+ * // Enforce on all requests (method scoping handled by pipeline builder)
+ * const pipeline = compose(
+ *   [precondition(), 'precondition'],
+ *   (req, res, acc) => ({response: {statusCode: 200, body: {updated: true}}})
+ * );
+ *
+ * // Enforce only on specific methods (standalone usage)
+ * const pipeline = compose(
+ *   [precondition({methods: ['PUT', 'PATCH']}), 'precondition'],
+ *   (req, res, acc) => ({response: {statusCode: 200, body: {updated: true}}})
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6585#section-3 RFC 6585 Section 3 - 428 Precondition Required}
+ */
+/**
+ * Create a precondition enforcement middleware.
+ *
+ * @param {object} [options]
+ * @param {string[]|Set<string>} [options.methods] - HTTP methods to enforce on.
+ *   When omitted, enforces unconditionally (the pipeline builder handles method scoping).
+ *   When provided, only activates for the specified methods.
+ * @returns {function} - Middleware `(req) => void` that returns `{response: {statusCode: 428}}` if no conditional header is present
+ */
+export default function precondition({ methods }?: {
+    methods?: string[] | Set<string> | undefined;
+}): Function;

package/types/http/prefer.d.ts

@@ -0,0 +1,2 @@
+declare function _default(): Function;
+export default _default;

package/types/http/rate-limit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Create a rate limiting middleware.
+ *
+ * @param {object} [options]
+ * @param {number} [options.max=100] - Maximum requests per window
+ * @param {number} [options.windowMs=60000] - Window size in milliseconds (default: 1 minute)
+ * @param {object} [options.store] - Pluggable store (must implement `hit(key, windowMs)`)
+ * @param {function} [options.keyGenerator] - `(req) => string` client identifier (default: remote IP)
+ * @returns {function} - Middleware `(req) => {response}` that returns rate-limit header tuples on allowed
+ *   requests and `{response: {statusCode: 429, retryAfter}}` when the limit is exceeded
+ */
+export default function rateLimit({ max, windowMs, store, keyGenerator }?: {
+    max?: number | undefined;
+    windowMs?: number | undefined;
+    store?: object | undefined;
+    keyGenerator?: Function | undefined;
+}): Function;

package/types/http/security-headers.d.ts

@@ -0,0 +1,10 @@
+declare function _default(options?: {
+    contentSecurityPolicy?: string | false | undefined;
+    strictTransportSecurity?: string | false | undefined;
+    xContentTypeOptions?: string | false | undefined;
+    xFrameOptions?: string | false | undefined;
+    referrerPolicy?: string | false | undefined;
+    xXssProtection?: string | false | undefined;
+    permissionsPolicy?: string | undefined;
+}): Function;
+export default _default;

package/types/http/send.d.ts

@@ -0,0 +1,8 @@
+declare function _default({ prettify, vary, etag, prefer, envelope }?: {
+    prettify?: boolean | undefined;
+    vary?: string[] | undefined;
+    etag?: boolean | undefined;
+    prefer?: boolean | undefined;
+    envelope?: boolean | Function | undefined;
+}): Function;
+export default _default;

package/types/http/timeout.d.ts

@@ -0,0 +1,5 @@
+declare function _default({ ms, statusCode }?: {
+    ms?: number | undefined;
+    statusCode?: number | undefined;
+}): Function;
+export default _default;

package/types/http/url.d.ts

@@ -0,0 +1,2 @@
+declare function _default(): Function;
+export default _default;

package/types/http/validate.d.ts

@@ -0,0 +1,6 @@
+declare function _default(schemas?: {
+    body?: object | undefined;
+    query?: object | undefined;
+    params?: object | undefined;
+}, options?: object): Function;
+export default _default;

package/types/lib/accepts.d.ts

@@ -0,0 +1,7 @@
+declare function _default({ types, languages, charsets, encodings }?: {
+    types?: string | string[] | undefined;
+    languages?: string | string[] | undefined;
+    charsets?: string | string[] | undefined;
+    encodings?: string | string[] | undefined;
+}): Function;
+export default _default;

package/types/lib/attach-instance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Shared RFC 9457 instance injection helper.
+ *
+ * Auto-populates the `instance` property on an error from the response's
+ * `x-request-id` header, formatted as a `urn:uuid:` URI.
+ *
+ * @module lib/attach-instance
+ * @version 0.1.0
+ * @since 0.1.0
+ */
+/**
+ * Set `err.instance` from the response's `x-request-id` header if not already set.
+ *
+ * @param {Error & {instance?: string}} err - Error to annotate
+ * @param {import('node:http').ServerResponse} res - HTTP response
+ */
+export default function attachInstance(err: Error & {
+    instance?: string;
+}, res: any): void;