@centralping/ergo 0.1.0-beta.1

package/types/lib/authorization.d.ts

@@ -0,0 +1,6 @@
+declare function _default(strategies?: Array<{
+    type: string;
+    attributes?: object;
+    authorizer: Function;
+}>): Function;
+export default _default;

package/types/lib/body/multiparse.d.ts

@@ -0,0 +1,9 @@
+declare function _default(rawbody: any, boundary: any, { maxParts }?: {
+    maxParts?: number | undefined;
+}): {
+    headers: object;
+    name: any;
+    filename: any;
+    body: any;
+}[];
+export default _default;

package/types/lib/body/multipart/headers.d.ts

@@ -0,0 +1,2 @@
+declare function _default(buffers?: Array<any | string>, headers?: object): object;
+export default _default;

package/types/lib/body/writer.d.ts

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

package/types/lib/cookie/cookie.d.ts

@@ -0,0 +1,32 @@
+export default bake;
+/**
+ * A cookie factory function.
+ * @param {string} name - The name of the cookie.
+ * @param {string} [value] - The value of the cookie. If undefined
+ *  as well as expires and maxAge are undefined, then the cookie will be set to expire.
+ * @param {object} [directives] - See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies|Cookies} for more information about directives.
+ * @param {string} [directives.domain] - The domain of the cookie. Defaults to
+ *  the host portion of the current document location. If a domain is specified,
+ *  subdomains are always included.
+ * @param {string} [directives.path='/'] - The absolute path of the cookie. Defaults
+ *  to the current path of the current document location.
+ * @param {boolean} [directives.secure=true] - Indicates whether the cookie is
+ *  transmitted over secure protocols such as HTTPS.
+ * @param {boolean} [directives.httpOnly=true] - Indicates whether the cookie is
+ *  accessible via client JavaScript (e.g. document.cookie, Request, XMLHttpRequest, etc.).
+ * @param {'lax'|'strict'|'none'} [directives.sameSite] - Indicates if a cookie shouldn't be sent
+ *  with cross-site requests. See {@link https://www.owasp.org/index.php/SameSite|SameSite} for more information.
+ * @param {number} [directives.maxAge] - The maximum age of a cookie in seconds.
+ * @param {(Date|string|number)} [directives.expires] - The GMT timestamp of the cookie
+ *  expiration.
+ * @returns {object} - A cookie object with name, value, directives, and toHeader().
+ */
+declare function bake(name: string, value?: string, { domain, path, maxAge, expires, sameSite, secure, httpOnly }?: {
+    domain?: string | undefined;
+    path?: string | undefined;
+    secure?: boolean | undefined;
+    httpOnly?: boolean | undefined;
+    sameSite?: "lax" | "none" | "strict" | undefined;
+    maxAge?: number | undefined;
+    expires?: string | number | Date | undefined;
+}): object;

package/types/lib/cookie/index.d.ts

@@ -0,0 +1,2 @@
+export { default as parse } from "./parse.js";
+export { default as jar } from "./jar.js";

package/types/lib/cookie/jar.d.ts

@@ -0,0 +1,8 @@
+export default jar;
+/**
+ * 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
+ */
+declare function jar(cookies?: object): object;

package/types/lib/cookie/parse.d.ts

@@ -0,0 +1,19 @@
+export default parse;
+/**
+ * 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
+ */
+declare function parse(cookie?: string, { decoder, loose, collection, max }?: {
+    decoder?: Function | undefined;
+    loose?: boolean | undefined;
+    collection?: boolean | undefined;
+    max?: number | undefined;
+}): object;

package/types/lib/cors.d.ts

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

package/types/lib/csrf.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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
+ */
+export function issue(secret?: string, uuid?: string, encoding?: string): {
+    token: string;
+    uuid: string;
+};
+/**
+ * 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
+ */
+export function verify(token: string, { secret, uuid, encoding }?: {
+    secret: string;
+    uuid: string;
+    encoding?: string | undefined;
+}): boolean;

package/types/lib/from-connect.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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: Function): Function;

package/types/lib/json-api-query/index.d.ts

@@ -0,0 +1,123 @@
+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: {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    type: string;
+    properties: {
+        fields: {
+            description: string;
+            type: string;
+            additionalProperties: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                uniqueItems: boolean;
+                minItems: number;
+            };
+            minProperties: number;
+        };
+        filter: {
+            description: string;
+            type: string;
+            minProperties: number;
+        };
+        include: {
+            description: string;
+            type: string;
+            items: {
+                type: string;
+            };
+            uniqueItems: boolean;
+            minItems: number;
+        };
+        page: {
+            description: string;
+            type: string;
+            properties: {
+                cursor: {
+                    type: string;
+                    minLength: number;
+                };
+                size: {
+                    type: string;
+                    minimum: number;
+                };
+                number: {
+                    type: string;
+                    minimum: number;
+                };
+                limit: {
+                    type: string;
+                    minimum: number;
+                };
+                offset: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+            dependentRequired: {
+                offset: string[];
+                number: string[];
+            };
+            additionalProperties: boolean;
+            minProperties: number;
+            if: {
+                required: string[];
+            };
+            then: {
+                maxProperties: number;
+            };
+            else: {
+                maxProperties: number;
+                if: {
+                    required: string[];
+                };
+                then: {
+                    not: {
+                        required: string[];
+                    };
+                };
+            };
+        };
+        sort: {
+            description: string;
+            type: string;
+            items: {
+                type: string;
+            };
+            uniqueItems: boolean;
+            minItems: number;
+        };
+    };
+    patternProperties: {
+        "[^a-z]": {
+            description: string;
+            type: string[];
+        };
+    };
+    additionalProperties: boolean;
+    if: {
+        required: string[];
+        properties: {
+            page: {
+                required: string[];
+            };
+        };
+    };
+    then: {
+        not: {
+            anyOf: {
+                required: string[];
+            }[];
+        };
+    };
+};

package/types/lib/json-api-query/validate.d.ts

@@ -0,0 +1,5 @@
+declare function _default({ coerceTypes, ownProperties, ...ajvOptions }?: {
+    coerceTypes?: string | boolean | undefined;
+    ownProperties?: boolean | undefined;
+}, schema?: object): Function;
+export default _default;

package/types/lib/link.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Formats an array of link objects into an RFC 8288 `Link` header value.
+ *
+ * @param {Array<{href: string, rel: string}>} links - Link descriptors. Each object
+ *   must have `href` and `rel`; additional properties become link parameters.
+ * @returns {string} - Formatted header value (e.g. `<url>; rel="next", <url>; rel="prev"`)
+ * @throws {TypeError} If `href` contains `>` or a parameter key is not a valid token
+ */
+export function formatLinkHeader(links: Array<{
+    href: string;
+    rel: string;
+}>): string;
+/**
+ * Generates pagination link objects for first, prev, next, and last pages.
+ *
+ * Only includes `prev` when `page > 1` and `next` when `page < lastPage`.
+ * `first` and `last` are always included.
+ *
+ * @param {object} options - Pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {number} options.page - Current page number (1-based)
+ * @param {number} options.perPage - Items per page
+ * @param {number} options.total - Total item count
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before pagination params.
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function paginationLinks({ baseUrl, page, perPage, total, searchParams }: {
+    baseUrl: string;
+    page: number;
+    perPage: number;
+    total: number;
+    searchParams?: string | undefined;
+}): Array<{
+    href: string;
+    rel: string;
+}>;

package/types/lib/prefer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Pure Prefer header parser (RFC 7240).
+ *
+ * Parses the HTTP `Prefer` request header into a plain object of preference
+ * name-value pairs. Supports:
+ * - Simple tokens (`respond-async` -> `{'respond-async': true}`)
+ * - Token=value pairs (`return=minimal` -> `{return: 'minimal'}`)
+ * - Quoted values (`foo="bar baz"` -> `{foo: 'bar baz'}`)
+ * - Multiple comma-separated preferences
+ * - Per-preference parameters after semicolons (stripped; only the main token is kept)
+ *
+ * Used by:
+ * - `http/prefer.js` (ergo pipeline middleware)
+ *
+ * @module lib/prefer
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import parsePrefer from 'ergo/lib/prefer';
+ *
+ * parsePrefer('return=minimal');
+ * // {return: 'minimal'}
+ *
+ * parsePrefer('respond-async, wait=100');
+ * // {'respond-async': true, wait: '100'}
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7240 RFC 7240 - Prefer Header for HTTP}
+ */
+/**
+ * Parse a Prefer header value into a preferences object.
+ *
+ * @param {string} [header] - Raw Prefer header value
+ * @returns {object} - Map of preference name to value (string) or `true` for bare tokens
+ */
+export default function parsePrefer(header?: string): object;

package/types/lib/query.d.ts

@@ -0,0 +1,6 @@
+declare function _default(query: string, { split, maxPairs, maxLength }?: {
+    split?: boolean | undefined;
+    maxPairs?: number | undefined;
+    maxLength?: number | undefined;
+}): object;
+export default _default;

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

@@ -0,0 +1,76 @@
+/**
+ * Compute rate limit state from a store hit.
+ *
+ * @param {object} store - Store implementing `hit(key, windowMs) => {count, resetMs}`
+ * @param {string} key - Client identifier
+ * @param {number} max - Maximum requests allowed per window
+ * @param {number} windowMs - Window size in milliseconds
+ * @returns {{count: number, remaining: number, reset: number, limited: boolean, retryAfter: number|undefined}}
+ *   - `count`: total hits in the current window
+ *   - `remaining`: requests remaining before limit
+ *   - `reset`: Unix timestamp (seconds) when the window resets
+ *   - `limited`: true when count exceeds max
+ *   - `retryAfter`: seconds until retry is allowed (only when limited)
+ */
+export function checkRateLimit(store: object, key: string, max: number, windowMs: number): {
+    count: number;
+    remaining: number;
+    reset: number;
+    limited: boolean;
+    retryAfter: number | undefined;
+};
+/**
+ * Default key generator: uses the remote IP address.
+ * @param {object} req - HTTP request
+ * @returns {string} - Client identifier
+ */
+export function defaultKeyGenerator(req: object): string;
+/**
+ * @fileoverview Rate limiting shared primitives.
+ *
+ * Provides the core building blocks for both pipeline-level and transport-level
+ * rate limiting. The `MemoryStore` implements a sliding-window counter using
+ * per-key timestamp arrays. `checkRateLimit` computes the current state
+ * (remaining quota, reset time, whether the client is limited) from any store
+ * that implements the `hit(key, windowMs)` interface.
+ *
+ * Used by:
+ * - `http/rate-limit.js` (ergo pipeline middleware)
+ * - `ergo-router/lib/transport/rate-limit.js` (transport-level rate limiting)
+ *
+ * @module lib/rate-limit
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {MemoryStore, checkRateLimit, defaultKeyGenerator} from 'ergo/lib/rate-limit';
+ *
+ * const store = new MemoryStore();
+ * const key = defaultKeyGenerator(req);
+ * const result = checkRateLimit(store, key, 100, 60000);
+ * // result.limited === true when over quota
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6585#section-4 RFC 6585 Section 4 - 429 Too Many Requests}
+ */
+/**
+ * In-memory sliding-window rate limit store.
+ * Each key maps to an array of request timestamps. Expired entries are pruned
+ * on every `hit()` call.
+ */
+export class MemoryStore {
+    constructor({ maxKeys }?: {
+        maxKeys?: number | undefined;
+    });
+    _hits: Map<any, any>;
+    _maxKeys: number;
+    /**
+     * Record a hit and return the current count within the window.
+     * @param {string} key - Client identifier
+     * @param {number} windowMs - Window size in milliseconds
+     * @returns {{count: number, resetMs: number}} - Current count and ms until the oldest entry expires
+     */
+    hit(key: string, windowMs: number): {
+        count: number;
+        resetMs: number;
+    };
+}

package/types/lib/sanitize-quoted-string.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Shared quoted-string sanitizer per RFC 7230 section 3.2.6.
+ *
+ * Escapes backslashes and double-quotes and strips control characters (all CTL chars
+ * except HTAB, which is valid in `qdtext` per RFC 7230 §3.2.6) so the result is safe
+ * for inclusion between double-quote delimiters in HTTP headers such as
+ * `WWW-Authenticate`, `Link`, and `Set-Cookie`.
+ *
+ * @module lib/sanitize-quoted-string
+ * @version 0.1.0
+ * @since 0.1.0
+ */
+/**
+ * Escape a value for use inside a quoted-string per RFC 7230 section 3.2.6.
+ *
+ * @param {string} str - Raw value
+ * @returns {string} - Value safe for inclusion between double-quote delimiters
+ */
+export default function sanitizeQuotedString(str: string): string;

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

@@ -0,0 +1,24 @@
+/**
+ * Build an array of security header tuples from a configuration object.
+ *
+ * @param {object} [options] - Security header configuration
+ * @param {string|false} [options.contentSecurityPolicy="default-src 'none'"] - Content-Security-Policy
+ * @param {string|object|false} [options.strictTransportSecurity=false] - HSTS directive string or
+ *   `{maxAge, includeSubDomains, preload}` object. Defaults to `false`.
+ * @param {string|boolean|false} [options.xContentTypeOptions='nosniff'] - X-Content-Type-Options.
+ *   `true` is treated as `'nosniff'`.
+ * @param {string|false} [options.xFrameOptions='DENY'] - X-Frame-Options
+ * @param {string|false} [options.referrerPolicy='no-referrer'] - Referrer-Policy
+ * @param {string|false} [options.xXssProtection='0'] - X-XSS-Protection
+ * @param {string} [options.permissionsPolicy] - Permissions-Policy (omitted by default)
+ * @returns {Array<[string, string]>} - Header tuples suitable for `res.setHeader()` or accumulator storage
+ */
+export default function buildSecurityHeaderTuples({ contentSecurityPolicy, strictTransportSecurity, xContentTypeOptions, xFrameOptions, referrerPolicy, xXssProtection, permissionsPolicy }?: {
+    contentSecurityPolicy?: string | false | undefined;
+    strictTransportSecurity?: string | false | object | undefined;
+    xContentTypeOptions?: string | boolean | undefined;
+    xFrameOptions?: string | false | undefined;
+    referrerPolicy?: string | false | undefined;
+    xXssProtection?: string | false | undefined;
+    permissionsPolicy?: string | undefined;
+}): Array<[string, string]>;

package/types/lib/validate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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: object, options?: {
+    allErrors?: boolean | undefined;
+    coerceTypes?: boolean | undefined;
+    ajv?: object | undefined;
+}): Function;

package/types/lib/vary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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: any, value: string): void;

package/types/utils/attempt.d.ts

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

package/types/utils/buffers/index.d.ts

@@ -0,0 +1,2 @@
+export { default as match } from "./match.js";
+export { default as split } from "./split.js";

package/types/utils/buffers/match.d.ts

@@ -0,0 +1,10 @@
+declare function _default(buffer?: any, searchBuffer?: any, { limit, partial, lookup }?: {
+    limit?: number | undefined;
+    partial?: number | undefined;
+    lookup?: number[] | undefined;
+}): {
+    matches: number[];
+    partial: number;
+    lookup: number[];
+};
+export default _default;

package/types/utils/buffers/split.d.ts

@@ -0,0 +1,10 @@
+declare function _default(buffer?: any | string, separator?: any, { limit, ...options }?: {
+    limit?: number | undefined;
+    partial?: number | undefined;
+    lookup?: number[] | undefined;
+}): {
+    buffers: any[];
+    partial: number;
+    lookup: number[];
+};
+export default _default;

package/types/utils/compose-with.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Creates a null-prototype response accumulator.
+ *
+ * The returned object has a non-enumerable `isResponseAcc` flag used by the pipeline
+ * to distinguish it from the domain accumulator in the argument list.
+ *
+ * @returns {object} - Null-prototype object with `isResponseAcc: true`
+ */
+export function createResponseAcc(): object;
+/**
+ * Merges a response patch into the response accumulator.
+ *
+ * - `headers` arrays are **appended** (additive across middleware)
+ * - All other properties are **assigned** (last writer wins)
+ *
+ * @param {object} responseAcc - Mutable response accumulator
+ * @param {object} patch - Response contribution from middleware
+ */
+export function mergeResponse(responseAcc: object, patch: object): void;
+export default composeWith;
+/**
+ * Composes middleware with path-based result storage and two-accumulator support.
+ *
+ * The composed function pops the domain accumulator (last arg with `isAccumulator`)
+ * and response accumulator (last arg with `isResponseAcc`) from its arguments.
+ * If either is absent, a fresh one is created.
+ *
+ * @param {...(function|Array)} ops - Operation specs; each is a function or `[fn, setPath]`
+ * @returns {function} - Async composed pipeline
+ */
+declare function composeWith(...ops: (Function | any[])[]): Function;
+declare namespace composeWith {
+    /**
+     * Concurrent variant of composeWith.
+     *
+     * @param {...(function|Array)} ops - Operation specs
+     * @returns {function} - Async composed pipeline
+     */
+    function all(...ops: (Function | any[])[]): Function;
+}