@centralping/ergo 0.1.0-beta.1

package/lib/cookie/index.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Cookie module barrel export.
+ *
+ * Provides `parse` for parsing the `Cookie` header string into a key-value map,
+ * and `jar` for creating a cookie jar instance that manages cookie state for a request.
+ *
+ * @module lib/cookie
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./parse.js
+ * @requires ./jar.js
+ */
+export {default as parse} from './parse.js';
+export {default as jar} from './jar.js';

package/lib/cookie/jar.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Cookie jar factory for managing per-request cookie state.
+ *
+ * Creates a cookie jar with dual-storage semantics for per-request cookie management.
+ *
+ * **Incoming cookies** (from the `Cookie` header) are parsed as raw `name: value` strings
+ * and stored as own properties via `Object.assign()`. Per RFC 6265 §5.4, the browser sends
+ * only `name=value` pairs — no directives. Access them directly: `jar.session`.
+ *
+ * **Outgoing cookies** (created via `set()`) are full cookie objects with directives,
+ * stored in an internal `Map`. Only these are serialized by `toHeader()` into `Set-Cookie`
+ * headers. A server should not echo all received cookies back — only cookies it explicitly
+ * creates or modifies should produce `Set-Cookie` headers.
+ *
+ * Methods:
+ * - `get(name)` — returns an outgoing cookie object from the Map, or an iterator over all
+ * - `set(name, value, opts)` — creates and stores an outgoing cookie (delegates to `lib/cookie/cookie`)
+ * - `clear(name?)` — deletes one outgoing cookie by name, or clears all
+ * - `toHeader()` — serializes outgoing cookies to `Set-Cookie` header strings
+ *
+ * @module lib/cookie/jar
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./cookie.js
+ * @requires ../../utils/iterables/index.js
+ *
+ * @example
+ * import jar from 'ergo/lib/cookie/jar';
+ * import parse from 'ergo/lib/cookie/parse';
+ *
+ * const cookies = jar(parse('session=abc123; lang=en'));
+ * cookies.session;     // => 'abc123' (incoming, own property)
+ * cookies.lang;        // => 'en'     (incoming, own property)
+ * cookies.get('session'); // => undefined (not in the outgoing Map)
+ * cookies.set('theme', 'dark', {maxAge: 86400});
+ * cookies.get('theme');   // => cookie object (outgoing, in the Map)
+ * cookies.toHeader();     // => ['theme=dark; Max-Age=86400'] (outgoing only)
+ */
+export default jar;
+
+import cookie from './cookie.js';
+import {chain, map} from '../../utils/iterables/index.js';
+
+const clay = Object.create(
+  {},
+  {
+    set: {
+      value(n, ...args) {
+        return this.jar.set(n, cookie(n, ...args));
+      }
+    },
+    get: {
+      value(n) {
+        if (n) {
+          return this.jar.get(n);
+        }
+
+        return this.jar.values();
+      }
+    },
+    clear: {
+      value(n) {
+        if (n) {
+          return this.jar.delete(n);
+        } else {
+          return this.jar.clear();
+        }
+      }
+    },
+    toHeader: {
+      value() {
+        return [
+          ...chain(
+            this.get(),
+            map(c => c.toHeader())
+          )
+        ];
+      }
+    },
+    size: {
+      get() {
+        return this.jar.size;
+      }
+    },
+    isJar: {
+      value: true
+    }
+  }
+);
+
+/**
+ * Creates a cookie jar pre-populated from a parsed cookie object.
+ *
+ * @param {object} [cookies={}] - Initial cookie values (from `parse()`)
+ * @returns {object} - Cookie jar with `get`, `set`, `clear`, `toHeader`, `size` members
+ */
+function jar(cookies = {}) {
+  return Object.assign(
+    Object.create(clay, {
+      jar: {
+        value: new Map()
+      }
+    }),
+    cookies
+  );
+}

package/lib/cookie/parse.js

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview RFC 6265 and RFC 2109 cookie string parser using generators.
+ *
+ * Parses raw `Cookie` header strings into key-value maps using compiled regular expressions
+ * derived from the RFC token/value grammars. Supports both RFC 6265 (strict) and RFC 2109
+ * (loose/legacy) parsing modes.
+ *
+ * Multi-value cookies (same name appearing multiple times) are optionally aggregated into
+ * arrays via the `collection` option. A `max` option enforces a limit on total cookie count
+ * to protect against header-stuffing attacks.
+ *
+ * @module lib/cookie/parse
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../../utils/iterables/index.js
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6265 RFC 6265 - HTTP State Management Mechanism}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc2109 RFC 2109 - HTTP State Management Mechanism (obsoleted)}
+ *
+ * @example
+ * import parse from 'ergo/lib/cookie/parse';
+ *
+ * parse('session=abc123; user=alice');
+ * // => {session: 'abc123', user: 'alice'}
+ *
+ * parse('tag=a; tag=b', {collection: true});
+ * // => {tag: ['a', 'b']}
+ */
+import {chain, reduce, map, forEach} from '../../utils/iterables/index.js';
+
+export default parse;
+
+/*
+https://www.rfc-editor.org/rfc/rfc2109
+https://www.rfc-editor.org/rfc/rfc6265
+*/
+const tokenRFC2109 = /[\x21-\x3a\x3c\x3e-\x7e]+/;
+const valueRFC2109 = /[\x20-\x3a\x3c-\x7e]*/;
+
+const tokenRFC6265 = /[\x21\x23-\x27\x2a\x2b\x2d\x2e\x30-\x39\x41-\x5a\x5c\x5e-\x7a\x7c\x7e]+/;
+const valueRFC6265 = /[\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e]*/;
+const dblQuote = /\x22/;
+const pairSeparator = /\x3d/;
+const listSeparator = /(?:\x3b\x20+|$)/;
+const matchRFC6265 = new RegExp(
+  `(${tokenRFC6265.source})${pairSeparator.source}(?:(${dblQuote.source}?)(${valueRFC6265.source})\\2)?${listSeparator.source}`,
+  'g'
+);
+const matchRFC2109 = new RegExp(
+  `(${tokenRFC2109.source})\x20*(?:${pairSeparator.source}\x20*(${dblQuote.source}?)(${valueRFC2109.source})\\2\x20*)?${listSeparator.source}`,
+  'g'
+);
+
+/**
+ * Parses a `Cookie` header string into a key-value map.
+ *
+ * @param {string} [cookie=''] - Raw value of the `Cookie` HTTP header
+ * @param {object} [options] - Parser configuration
+ * @param {function} [options.decoder=v=>v] - Transform applied to each `[name, value]` pair
+ * @param {boolean} [options.loose=false] - Use RFC 2109 (lenient) instead of RFC 6265 (strict) parsing
+ * @param {boolean} [options.collection=true] - Aggregate duplicate names into arrays
+ * @param {number} [options.max=50] - Maximum number of cookies; throws on excess
+ * @returns {object} - Plain object of cookie name → value (or string[])
+ * @throws {Error} If `max` is exceeded
+ */
+function parse(cookie = '', {decoder = v => v, loose = false, collection = true, max = 50} = {}) {
+  const process = chain(
+    matchGenerator(loose ? matchRFC2109 : matchRFC6265, cookie),
+    forEach((v, i) => {
+      if (i >= max) {
+        throw new Error(`Too many cookies (max ${max})`);
+      }
+    }),
+    map(decoder),
+    reduce((cookies, [name, value]) => {
+      cookies[name] =
+        collection && Object.hasOwn(cookies, name) ? [cookies[name], value].flat() : value;
+
+      return cookies;
+    }, Object.create(null))
+  );
+
+  return process;
+}
+
+/**
+ * Generator that yields `[name, value]` pairs for all cookie matches in a string.
+ *
+ * @param {RegExp} re - Compiled RFC cookie regex (must have `g` flag)
+ * @param {string} str - The raw cookie header string to scan
+ * @yields {[string, string|undefined]} Name-value pair for each matched cookie
+ */
+function* matchGenerator(re, str) {
+  let match;
+
+  while ((match = re.exec(str)) !== null) {
+    const [, name, , value] = match;
+
+    yield [name, value];
+  }
+}

package/lib/cors.js

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview CORS validation logic implementing the W3C CORS specification.
+ *
+ * Provides a factory that compiles CORS policy options into efficient validators,
+ * then processes each request returning `{allowed, info}`. Used by `http/cors.js`
+ * as the pure-logic backing implementation.
+ *
+ * Supports:
+ * - Wildcard origins (`*`) with optional credentials support
+ * - String, RegExp, function, and array-based origin validation
+ * - Pre-flight (`OPTIONS`) and simple CORS requests
+ * - Header filtering (wildcard, RegExp, function, string list)
+ * - `Access-Control-Max-Age`, `Access-Control-Expose-Headers`, `Vary`
+ *
+ * @see {@link https://www.w3.org/TR/2014/REC-cors-20140116/}
+ *
+ * @module lib/cors
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../utils/type.js
+ * @requires ../utils/flat-array.js
+ *
+ * @example
+ * import cors from 'ergo/lib/cors';
+ *
+ * const corsValidator = cors({
+ *   origins: ['https://app.example.com'],
+ *   allowMethods: ['GET', 'POST'],
+ *   allowCredentials: true
+ * });
+ *
+ * const result = corsValidator({
+ *   origin: 'https://app.example.com',
+ *   method: 'GET'
+ * });
+ * // result.allowed => true
+ * // result.info.headers => [{h: 'Access-Control-Allow-Origin', v: '...'}, ...]
+ *
+ * @see {@link https://fetch.spec.whatwg.org/#http-cors-protocol Fetch Standard - CORS Protocol}
+ */
+import type from '../utils/type.js';
+import flatArray from '../utils/flat-array.js';
+
+/*
+https://www.w3.org/TR/2014/REC-cors-20140116/
+*/
+
+const defaultMethods = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT', 'TRACE'];
+
+/**
+ * Creates a CORS policy validator from the given options.
+ *
+ * @param {object} [options] - CORS policy configuration
+ * @param {string|RegExp|function|Array} [options.origins='*'] - Allowed origins
+ * @param {string[]} [options.allowMethods] - Allowed HTTP methods
+ * @param {boolean} [options.allowCredentials=false] - Whether credentials are allowed
+ * @param {string|RegExp|function|Array} [options.allowHeaders='*'] - Allowed request headers
+ * @param {string|string[]} [options.exposeHeaders] - Headers to expose to the client
+ * @param {number} [options.maxAge] - Pre-flight cache duration in seconds
+ * @returns {function} - `({origin, method, requestMethod, requestHeaders}) => {allowed, info}`
+ */
+export default ({
+  origins = '*', // '*', 'foo.com', /foo/, ['foo', /bar/]
+  allowMethods = defaultMethods,
+  allowCredentials = false,
+  allowHeaders = '*',
+  exposeHeaders,
+  maxAge
+} = {}) => {
+  const methods = flatArray(allowMethods);
+  const headerValidator = configHeaderValidator(allowHeaders);
+  const originValidator = configOriginValidator(origins, allowCredentials);
+  const baseHeaders = flatArray(
+    allowCredentials ? {h: 'Access-Control-Allow-Credentials', v: true} : [],
+    exposeHeaders !== undefined
+      ? {h: 'Access-Control-Expose-Headers', v: flatArray(exposeHeaders)}
+      : [],
+    type(origins) !== 'String' || origins === '*' ? {h: 'Vary', v: 'Origin'} : []
+  );
+  const preflightHeaders = flatArray(
+    {h: 'Access-Control-Allow-Methods', v: methods},
+    {h: 'Vary', v: 'Access-Control-Request-Methods'},
+    maxAge !== undefined ? {h: 'Access-Control-Max-Age', v: maxAge} : [],
+    type(allowHeaders) !== 'String' || allowHeaders === '*'
+      ? {h: 'Vary', v: 'Access-Control-Request-Headers'}
+      : []
+  );
+
+  return ({origin, method, requestMethod, requestHeaders} = {}) => {
+    const allowedOrigin = originValidator(origin);
+    const isPreflight = method === 'OPTIONS' && requestMethod !== undefined;
+
+    if (allowedOrigin === false) {
+      return {
+        allowed: false,
+        info: {
+          type: 'invalid_origin',
+          origin
+        }
+      };
+    }
+
+    if (!methods.includes(isPreflight ? requestMethod : method)) {
+      return {
+        allowed: false,
+        info: {
+          type: 'invalid_method',
+          origin,
+          method: isPreflight ? requestMethod : method
+        }
+      };
+    }
+
+    return {
+      allowed: true,
+      info: {
+        origin,
+        headers: flatArray(
+          {h: 'Access-Control-Allow-Origin', v: allowedOrigin},
+          baseHeaders,
+          isPreflight
+            ? flatArray(preflightHeaders, getAllowHeaders(method, headerValidator, requestHeaders))
+            : []
+        )
+      }
+    };
+  };
+};
+
+/**
+ * Builds an origin validator function from a policy value.
+ *
+ * @param {string|RegExp|function|Array<string|RegExp>} valid - Origin policy
+ * @param {boolean} [allowCreds] - If true, wildcard reflects the request origin
+ * @returns {function} - `(origin: string) => string|false` — returns the allowed origin or false
+ */
+function configOriginValidator(valid, allowCreds) {
+  if (valid === '*') {
+    return allowCreds ? origin => origin : () => valid;
+  } else if (type(valid) === 'Function') {
+    return origin => valid(origin) && origin;
+  } else {
+    const validators = flatArray(valid).map(v =>
+      type(v) === 'RegExp' ? origin => v.test(origin) : origin => v === origin
+    );
+
+    return origin => validators.some(v => v(origin)) && origin;
+  }
+}
+
+/**
+ * Builds a request header validator function from an allowed-headers policy.
+ *
+ * @param {string|RegExp|function|Array<string|RegExp>} allowed - Header policy
+ * @returns {function} - `(headers: string[]) => string[]` — returns filtered allowed headers
+ */
+function configHeaderValidator(allowed) {
+  if (allowed === '*') {
+    // Current living standard has proposed allowing wildcards for non credential requests.
+    // For now, echo back the request headers.
+    return headers => headers;
+  } else if (type(allowed) === 'Function') {
+    return headers => allowed(headers);
+  } else {
+    const validators = flatArray(allowed).map(v =>
+      type(v) === 'RegExp' ? header => v.test(header) : header => v === header
+    );
+
+    return (headers = []) => headers.filter(h => validators.some(v => v(h)));
+  }
+}
+
+/**
+ * Returns the `Access-Control-Allow-Headers` header entry for pre-flight requests.
+ *
+ * @param {string} method - HTTP method (must be 'OPTIONS' for pre-flight)
+ * @param {function} validator - Header validator returned by `configHeaderValidator`
+ * @param {string[]|undefined} headers - Requested headers from `Access-Control-Request-Headers`
+ * @returns {{h: string, v: string[]}|Array} - Header entry or empty array if N/A
+ */
+function getAllowHeaders(method, validator, headers) {
+  if (method === 'OPTIONS' && headers !== undefined) {
+    const allowedHeaders = validator(headers);
+
+    if (allowedHeaders !== undefined && allowedHeaders.length) {
+      return {h: 'Access-Control-Allow-Headers', v: allowedHeaders};
+    }
+  }
+
+  return [];
+}

package/lib/csrf.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview CSRF token issuance and verification using HMAC-SHA256.
+ *
+ * Issues UUID-backed CSRF tokens signed with a shared secret. Verification uses
+ * `crypto.timingSafeEqual()` to prevent timing side-channel attacks.
+ *
+ * Token format: `HMAC-SHA256(secret, uuid)` encoded as `base64` (default) or any
+ * Node.js digest encoding. The UUID is stored separately (in a cookie) so the token
+ * can be reissued without changing the UUID.
+ *
+ * @module lib/csrf
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:crypto
+ * @requires ../utils/type.js
+ *
+ * @example
+ * import {issue, verify} from 'ergo/lib/csrf';
+ *
+ * const {token, uuid} = issue('my-secret');
+ * // token => 'base64-encoded-hmac'
+ * // uuid  => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+ *
+ * verify(token, {secret: 'my-secret', uuid}); // => true
+ * verify('tampered', {secret: 'my-secret', uuid}); // => false
+ *
+ * @see {@link https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html OWASP CSRF Prevention Cheat Sheet}
+ */
+import {createHmac, timingSafeEqual, randomUUID} from 'node:crypto';
+
+import type from '../utils/type.js';
+
+export {issue};
+export {verify};
+
+/**
+ * Issues a new CSRF token/UUID pair signed with HMAC-SHA256.
+ *
+ * @param {string} secret - Shared HMAC secret; throws `TypeError` if missing
+ * @param {string} [uuid=randomUUID()] - Pre-existing UUID to bind the token to
+ * @param {string} [encoding='base64'] - Node.js digest encoding for the token
+ * @returns {{token: string, uuid: string}} - The signed token and its associated UUID
+ * @throws {TypeError} If `secret` is not provided
+ */
+function issue(
+  secret = new TypeError('Missing required parameter: "secret"'),
+  uuid = randomUUID(),
+  encoding = 'base64'
+) {
+  if (type(secret) === 'TypeError') {
+    throw secret;
+  }
+
+  return {
+    token: createHmac('SHA256', secret).update(uuid).digest(encoding),
+    uuid
+  };
+}
+
+/**
+ * Verifies a CSRF token against the expected value for the given secret and UUID.
+ *
+ * Uses `crypto.timingSafeEqual()` to prevent timing attacks. Returns `false` (not throws)
+ * for any mismatch, length difference, or type error.
+ *
+ * @param {string} token - The token from the request header
+ * @param {object} key - Key components used to re-derive the expected token
+ * @param {string} key.secret - Shared HMAC secret; throws `TypeError` if missing
+ * @param {string} key.uuid - UUID from the CSRF cookie; throws `TypeError` if missing
+ * @param {string} [key.encoding='base64'] - Encoding used when the token was issued
+ * @returns {boolean} - `true` if the token is valid, `false` otherwise
+ * @throws {TypeError} If `secret` or `uuid` are not provided
+ */
+function verify(
+  token,
+  {
+    secret = new TypeError('Missing required parameter: "secret"'),
+    uuid = new TypeError('Missing required parameter: "uuid"'),
+    encoding = 'base64'
+  } = {}
+) {
+  if (type(secret) === 'TypeError') {
+    throw secret;
+  }
+  if (type(uuid) === 'TypeError') {
+    throw uuid;
+  }
+
+  const expected = issue(secret, uuid, encoding).token;
+
+  if (typeof token !== 'string' || token.length !== expected.length) {
+    return false;
+  }
+
+  return timingSafeEqual(Buffer.from(token), Buffer.from(expected));
+}

package/lib/from-connect.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Adapter for Connect/Express-style middleware.
+ *
+ * Wraps a Connect-style `(req, res, next)` middleware into ergo's
+ * `(req, res) => Promise<undefined>` signature so it can be used inside
+ * ergo's `compose()` pipeline.
+ *
+ * The adapter handles two completion signals:
+ * - `next()` called — the standard path; promise resolves and the pipeline continues.
+ * - `res` `finish` event — fallback for middleware that ends the response directly
+ *   (e.g., CORS preflight, rate limiter sending 429) without calling `next()`.
+ *
+ * A `settled` guard prevents double-resolution from buggy middleware that calls
+ * `next()` multiple times or calls `next()` after ending the response.
+ *
+ * Returns `undefined` so neither the domain nor response accumulator is affected.
+ * Connect middleware communicates via side effects on `res` headers.
+ *
+ * Limitations:
+ * - Express error-handling middleware `(err, req, res, next)` is not supported.
+ *   Ergo handles errors via `handler()` / `attempt()` try/catch.
+ * - Connect middleware may mutate `req` (e.g., `req.user`). This violates ergo's
+ *   no-mutation convention but is accepted at the interop boundary.
+ *
+ * @module lib/from-connect
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {compose, handler} from 'ergo';
+ * import fromConnect from 'ergo/lib/from-connect';
+ * import helmet from 'helmet';
+ *
+ * const pipeline = compose(
+ *   fromConnect(helmet()),
+ *   () => ({response: {body: {ok: true}}})
+ * );
+ *
+ * export default handler(pipeline);
+ */
+
+/**
+ * Wrap a Connect/Express-style middleware for use in an ergo pipeline.
+ *
+ * @param {function} middleware - Connect middleware `(req, res, next) => void`
+ * @returns {function} - Ergo-compatible middleware `(req, res) => Promise<undefined>`
+ */
+export default function fromConnect(middleware) {
+  return (req, res) =>
+    new Promise((resolve, reject) => {
+      let settled = false;
+
+      const onFinish = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+
+      res.once('finish', onFinish);
+
+      middleware(req, res, err => {
+        if (settled) return;
+        settled = true;
+        res.removeListener('finish', onFinish);
+        if (err) return reject(err);
+        resolve();
+      });
+    });
+}

package/lib/json-api-query/index.js

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Vendored JSON:API query module with AJV 8 and JSON Schema 2020-12.
+ *
+ * Provides the JSON:API query parameter validator and the default schema as a deep-cloneable
+ * getter. The schema clone pattern prevents mutation from affecting the original definition.
+ *
+ * Original: `@centralping/json-api-query`. Vendored and upgraded to AJV 8 / JSON Schema 2020-12.
+ *
+ * @module lib/json-api-query
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./schema.json
+ * @requires ./validate.js
+ */
+import schemaSource from './schema.json' with {type: 'json'};
+
+export {default as validate} from './validate.js';
+
+/**
+ * A deep copy of the default JSON API query schema, computed once at module load.
+ * Callers should clone again if mutation is needed.
+ *
+ * @member {object} schema JSON Schema 2020-12
+ */
+export const schema = structuredClone(schemaSource);