@centralping/ergo 0.1.0-beta.1

package/lib/authorization.js

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Authorization header parsing and strategy dispatch logic.
+ *
+ * Parses the HTTP `Authorization` header and dispatches to the matching strategy handler.
+ * Supports three built-in schemes with pluggable `authorizer` callbacks:
+ * - **Basic** — decodes base64 `username:password` credentials, passes `(attributes, username, password)`
+ * - **Bearer** — passes the raw token string unchanged `(attributes, token)`; no decoding (JWTs and opaque tokens are not base64 encoded at the HTTP layer)
+ * - **$default** — passes raw credentials for any custom scheme `(attributes, credentials)`
+ *
+ * Each strategy returns `{authorized: boolean, info: object}`. Authorization failure returns
+ * 401 for known schemes (with a `WWW-Authenticate` challenge) or 403 for unrecognized schemes.
+ *
+ * @module lib/authorization
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import authorize from 'ergo/lib/authorization';
+ *
+ * const authorizer = authorize([{
+ *   type: 'Bearer',
+ *   attributes: {realm: 'API'},
+ *   authorizer: async (attrs, token) => {
+ *     const user = await verifyJwt(token);
+ *     return user ? {authorized: true, info: {user}} : {authorized: false, info: {}};
+ *   }
+ * }]);
+ *
+ * const result = await authorizer('Bearer eyJ...');
+ * // result => {authorized: true, info: {user: {...}}}
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6750 RFC 6750 - Bearer Token Usage}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7617 RFC 7617 - The 'Basic' HTTP Authentication Scheme}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7235 RFC 7235 - HTTP Authentication}
+ */
+import sanitizeQuotedString from './sanitize-quoted-string.js';
+
+/**
+ * Creates an authorization dispatcher for the given strategy list.
+ *
+ * @param {Array<{type: string, attributes?: object, authorizer: function}>} strategies - Authentication strategy definitions
+ * @returns {function} - Async `(authorization) => {authorized, info}`
+ */
+export default (strategies = []) => {
+  const dispatcher = createDispatcher(strategies);
+
+  return async (authorization = '') => {
+    const [type, rawCredentials] = authorization.split(/ (.*)$/);
+    const strategy = dispatcher[type.toLowerCase()];
+
+    if (strategy === undefined || rawCredentials === undefined) {
+      const obj = {
+        authorized: false,
+        info: {
+          statusCode: 403
+        }
+      };
+
+      if (Object.keys(dispatcher).length > 0) {
+        obj.info = {
+          statusCode: 401,
+          authenticate: Object.values(dispatcher).map(s => s.authenticate)
+        };
+      }
+
+      return obj;
+    }
+
+    return await strategy.authorizer(rawCredentials);
+  };
+};
+
+const dispatchHelper = new Proxy(
+  {
+    basic({authorizer, attributes, authenticate}) {
+      return {
+        authenticate,
+        authorizer: async rawCredentials => {
+          const decoded = Buffer.from(rawCredentials, 'base64').toString();
+          const [username, password] = decoded.split(/:(.*)$/);
+          const {authorized = false, info = {}} = await authorizer(attributes, username, password);
+
+          if (authorized === false) {
+            return {
+              authorized,
+              info: {
+                statusCode: 403
+              }
+            };
+          }
+
+          return {authorized, info};
+        }
+      };
+    },
+    bearer({authorizer, attributes, authenticate}) {
+      return {
+        authenticate,
+        authorizer: async rawCredentials => {
+          const {authorized = false, info = {}} = await authorizer(attributes, rawCredentials);
+
+          if (authorized === false) {
+            return {
+              authorized,
+              info: {
+                statusCode:
+                  info.type === 'invalid_request'
+                    ? 400
+                    : info.type === 'insufficient_scope'
+                      ? 403
+                      : 401, // default and 'invalid_token'
+                authenticate: [authenticate, ...formatError(info)].join(', ')
+              }
+            };
+          }
+
+          return {authorized, info};
+        }
+      };
+    },
+    $default({authorizer, attributes, authenticate}) {
+      return {
+        authenticate,
+        authorizer: async rawCredentials => {
+          const {authorized = false, info = {}} = await authorizer(attributes, rawCredentials);
+
+          if (authorized === false) {
+            return {
+              authorized,
+              info: {
+                statusCode: 403
+              }
+            };
+          }
+
+          return {authorized, info};
+        }
+      };
+    }
+  },
+  {
+    get(o, p) {
+      return Object.hasOwn(o, p) ? o[p] : o.$default;
+    }
+  }
+);
+
+/**
+ * Builds a dispatcher map from the strategy array, keyed by lowercase scheme name.
+ *
+ * @param {Array<{type: string, attributes?: object, authorizer: function}>} strategies - Authentication strategy definitions
+ * @returns {object} - Dispatcher map keyed by lowercase scheme name
+ */
+function createDispatcher(strategies) {
+  return strategies.reduce((o, {type, attributes = {realm: 'Users'}, authorizer}) => {
+    o[type.toLowerCase()] = dispatchHelper[type.toLowerCase()]({
+      attributes,
+      authorizer,
+      authenticate: `${type} ${Object.entries(attributes)
+        .map(([k, v]) => `${k}="${sanitizeQuotedString(v)}"`)
+        .join(', ')}`
+    });
+
+    return o;
+  }, {});
+}
+
+const errorPropMap = [
+  ['type', 'error'],
+  ['desc', 'error_description'],
+  ['uri', 'error_uri']
+];
+
+/**
+ * Formats a Bearer token error object into WWW-Authenticate parameter strings (RFC 6750).
+ *
+ * @param {object} error - Error info from the authorizer
+ * @param {string} [error.type] - OAuth error type (e.g. 'invalid_token')
+ * @param {string} [error.desc] - Human-readable error description
+ * @param {string} [error.uri] - URI to more error information
+ * @returns {string[]} - Array of key="value" attribute strings for the WWW-Authenticate header
+ */
+function formatError(error) {
+  return errorPropMap
+    .filter(([p]) => error[p] !== undefined)
+    .map(([p, k]) => `${k}="${sanitizeQuotedString(error[p])}"`);
+}

package/lib/body/multiparse.js

@@ -0,0 +1,173 @@
+/**
+ * @fileoverview RFC 7578 multipart/form-data parser.
+ *
+ * Parses a fully buffered `multipart/form-data` body into an array of part descriptors.
+ * Each part contains parsed headers, the binary body buffer, and convenience shortcuts
+ * for the `Content-Disposition` `name` and `filename` parameters.
+ *
+ * Uses Buffer-level KMP split (`utils/iterables/buffer-split`) for efficient binary
+ * boundary detection without converting the entire body to a string.
+ *
+ * Only the MIME headers explicitly allowed by RFC 7578 §4.8 are parsed:
+ * `Content-Disposition`, `Content-Type`, `Content-Transfer-Encoding`.
+ *
+ * @module lib/body/multiparse
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./multipart/headers.js
+ * @requires ../../utils/iterables/buffer-split.js
+ * @requires ../../utils/iterables/chain.js
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7578}
+ *
+ * @example
+ * import multiparse from 'ergo/lib/body/multiparse';
+ *
+ * const parts = multiparse(rawBodyBuffer, 'boundary-string');
+ * // parts => [{headers: {...}, name: 'file', filename: 'upload.txt', body: Buffer}]
+ */
+// https://www.rfc-editor.org/rfc/rfc7578
+import parseHeaders from './multipart/headers.js';
+import bufferSplit from '../../utils/iterables/buffer-split.js';
+import chain from '../../utils/iterables/chain.js';
+
+const CRLF = Buffer.from('\r\n');
+const CRLFCRLF = Buffer.from('\r\n\r\n');
+
+/**
+ * Parses a multipart/form-data body buffer according to RFC 7578.
+ *
+ * Each part is returned as an object with:
+ *  - headers: parsed headers (content-disposition, content-type, etc.)
+ *  - body: Buffer of the part body
+ *  - name: shortcut to content-disposition name parameter
+ *  - filename: shortcut to content-disposition filename parameter (if present)
+ *
+ * @param {import('node:buffer').Buffer|string} rawbody - the raw body buffer (from writer.js)
+ * @param {string} boundary - the multipart boundary string
+ * @param {object} [options] - Parser options
+ * @param {number} [options.maxParts=100] - Maximum number of parts to parse
+ * @returns {object[]} - array of parsed parts
+ */
+const DEFAULT_MAX_PARTS = 100;
+
+export default (rawbody, boundary, {maxParts = DEFAULT_MAX_PARTS} = {}) => {
+  // Boundaries are prefixed with '--' per RFC 7578
+  const delimiter = Buffer.from(`--${boundary}`);
+
+  // Wrap in an array so bufferSplit iterable works over a single-chunk source
+  const source = [Buffer.isBuffer(rawbody) ? rawbody : Buffer.from(rawbody)];
+
+  // Split body on the boundary delimiter; yields [index, buffer] pairs
+  const parts = chain(source, bufferSplit(delimiter));
+
+  const results = [];
+
+  for (const [index, partBuf] of parts) {
+    // index 0 is preamble (before first boundary), skip it
+    // The last part will be just '--\r\n' (closing boundary) or empty, skip it too
+    if (index === 0) {
+      continue;
+    }
+
+    // Each part buffer starts with \r\n after the boundary delimiter
+    // and may end with \r\n before the next boundary delimiter
+    // Strip leading CRLF
+    let content = partBuf;
+    if (content.slice(0, CRLF.length).equals(CRLF)) {
+      content = content.slice(CRLF.length);
+    }
+
+    // Strip trailing CRLF
+    if (content.slice(-CRLF.length).equals(CRLF)) {
+      content = content.slice(0, -CRLF.length);
+    }
+
+    // The closing boundary part ends with '--'; skip it
+    if (content.length >= 2 && content[0] === 0x2d && content[1] === 0x2d) {
+      continue;
+    }
+
+    if (results.length >= maxParts) break;
+
+    // Split headers from body on the first CRLFCRLF sequence
+    const separatorIdx = indexOfSequence(content, CRLFCRLF);
+
+    if (separatorIdx === -1) {
+      // Malformed part: no header/body separator
+      continue;
+    }
+
+    const headerSection = content.slice(0, separatorIdx);
+    const body = content.slice(separatorIdx + CRLFCRLF.length);
+
+    // Split header section into individual header lines
+    const headerLines = splitBuffer(headerSection, CRLF).map(b => b.toString());
+
+    const headers = parseHeaders(headerLines);
+
+    const disposition = headers['content-disposition'] ?? {};
+    const params = disposition.parameters ?? {};
+
+    results.push({
+      headers,
+      name: params.name,
+      filename: params.filename,
+      body
+    });
+  }
+
+  return results;
+};
+
+/**
+ * Find the first occurrence of a sequence (needle) in a buffer (haystack).
+ * Returns the index of the first byte of the sequence, or -1 if not found.
+ *
+ * @param {import('node:buffer').Buffer} haystack - Buffer to search within
+ * @param {import('node:buffer').Buffer} needle - Byte sequence to find
+ * @returns {number} - Index of the first match, or -1
+ */
+function indexOfSequence(haystack, needle) {
+  const nLen = needle.length;
+  outer: for (let i = 0; i <= haystack.length - nLen; i++) {
+    for (let j = 0; j < nLen; j++) {
+      if (haystack[i + j] !== needle[j]) {
+        continue outer;
+      }
+    }
+    return i;
+  }
+  return -1;
+}
+
+/**
+ * Split a buffer by a separator buffer, returning an array of Buffer slices.
+ *
+ * @param {import('node:buffer').Buffer} buf - Buffer to split
+ * @param {import('node:buffer').Buffer} sep - Separator byte sequence
+ * @returns {import('node:buffer').Buffer[]} - Array of Buffer slices between separators
+ */
+function splitBuffer(buf, sep) {
+  const results = [];
+  let start = 0;
+  const sLen = sep.length;
+
+  for (let i = 0; i <= buf.length - sLen; i++) {
+    let match = true;
+    for (let j = 0; j < sLen; j++) {
+      if (buf[i + j] !== sep[j]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) {
+      results.push(buf.slice(start, i));
+      start = i + sLen;
+      i += sLen - 1;
+    }
+  }
+
+  results.push(buf.slice(start));
+  return results;
+}

package/lib/body/multipart/headers.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Multipart MIME header parser for RFC 7578 parts.
+ *
+ * Parses an array of header line strings from a multipart/form-data part into a structured
+ * object. Extracts parameter key-value pairs from headers with directives (e.g.
+ * `Content-Disposition: form-data; name="file"; filename="upload.txt"`).
+ *
+ * Only the headers explicitly allowed by RFC 7578 §4.8 are retained:
+ * - `content-disposition`
+ * - `content-type`
+ * - `content-transfer-encoding` (deprecated but present in legacy clients)
+ *
+ * @module lib/body/multipart/headers
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../../../utils/iterables/exec-all.js
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7578 RFC 7578 - Returning Values from Forms: multipart/form-data}
+ *
+ * @example
+ * import parseHeaders from 'ergo/lib/body/multipart/headers';
+ *
+ * parseHeaders(['Content-Disposition: form-data; name="field1"']);
+ * // => {'content-disposition': {type: 'form-data', parameters: {name: 'field1'}}}
+ */
+import execAll from '../../../utils/iterables/exec-all.js';
+
+const headerRegExp = /^([^:]+):\s*([^;]+);?\s*(.*?)$/;
+const directivesRegExp = /\s*([^=]+)=\s*(?:"([^"]+)"|([^;\s]+));?/;
+
+/**
+ * Allowed headers are restricted to:
+ *  Content-Disposition https://www.rfc-editor.org/rfc/rfc7578#section-4.2,
+ *  Content-Type https://www.rfc-editor.org/rfc/rfc7578#section-4.4
+ *  and Content-Transfer-Encoding (deprecated) https://www.rfc-editor.org/rfc/rfc7578#section-4.7.
+ *
+ * https://www.rfc-editor.org/rfc/rfc7578#section-4.8
+ */
+const allowed = ['content-disposition', 'content-type', 'content-transfer-encoding'];
+
+const reAll = execAll(directivesRegExp);
+
+/**
+ * @param {Array<import('node:buffer').Buffer|string>} [buffers=[]] - Array of header line buffers from a multipart part
+ * @param {object} [headers] - Initial headers object; defaults to `{content-type: {type: 'text/plain'}}` when omitted
+ * @returns {object} - Parsed headers keyed by lowercase header name with `{type, parameters}` values
+ */
+export default (buffers = [], headers) => {
+  const base =
+    headers !== undefined
+      ? Object.assign(Object.create(null), headers)
+      : Object.assign(Object.create(null), {'content-type': {type: 'text/plain'}});
+  return buffers
+    .map(buffer => headerRegExp.exec(buffer.toString().trim()))
+    .filter(m => m !== null)
+    .reduce((obj, [, prop, type, parameters]) => {
+      const lcProp = prop.toLowerCase();
+
+      if (allowed.includes(lcProp)) {
+        const params = Object.create(null);
+        for (const [k, quoted, unquoted] of reAll(parameters)) {
+          params[k] = quoted ?? unquoted;
+        }
+        obj[lcProp] = {type, parameters: params};
+      }
+
+      return obj;
+    }, base);
+};

package/lib/body/writer.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Writable stream accumulator for collecting request body chunks.
+ *
+ * Creates a `Writable` stream that buffers all incoming `Buffer` chunks and consolidates
+ * them into a single `Buffer` when the stream finishes. Exposed via the `.data` getter.
+ *
+ * Used by `http/body.js` in the 3-stream decompression pipeline:
+ * `pipeline(req, meter, decompressor, writer())`
+ *
+ * @module lib/body/writer
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:stream
+ *
+ * @example
+ * import {pipeline} from 'node:stream';
+ * import writer from 'ergo/lib/body/writer';
+ *
+ * const w = writer();
+ * pipeline(readable, w, err => {
+ *   if (!err) console.log(w.data); // => Buffer with all accumulated bytes
+ * });
+ */
+import {Writable} from 'node:stream';
+
+const chunksSym = Symbol('chunks');
+const bytesSym = Symbol('bytes');
+
+/**
+ * Creates a Writable stream that accumulates chunks into a single Buffer.
+ *
+ * @returns {import('node:stream').Writable} - Writable stream with a `.data` getter for the concatenated Buffer (available after stream ends)
+ */
+export default () => {
+  const w = Object.defineProperties(new Writable({write, final}), {
+    [chunksSym]: {
+      value: [],
+      writable: true
+    },
+    [bytesSym]: {
+      value: 0,
+      writable: true
+    },
+    data: {
+      get() {
+        return this[chunksSym];
+      }
+    }
+  });
+
+  return w;
+};
+
+/**
+ * @param {import('node:buffer').Buffer} chunk - Incoming data chunk
+ * @param {string} encoding - Chunk encoding (ignored for Buffers)
+ * @param {function} cb - Callback to signal write completion
+ */
+function write(chunk, encoding, cb) {
+  const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+  this[chunksSym].push(buf);
+  this[bytesSym] += buf.length;
+  cb(null);
+}
+
+/**
+ * @param {function} cb - Callback to signal finalization is complete
+ */
+function final(cb) {
+  // Consolidate all chunks into a single Buffer
+  this[chunksSym] = Buffer.concat(this[chunksSym], this[bytesSym]);
+  cb(null);
+}

package/lib/cookie/cookie.js

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Cookie construction factory (RFC 6265 compliant).
+ *
+ * Creates typed cookie objects with a `toHeader()` method that serializes the cookie
+ * to a `Set-Cookie` header string per RFC 6265.
+ *
+ * Default directives enforce secure cookie practices: `Secure: true`, `HttpOnly: true`,
+ * `Path: /`. Cookies without a `value` (or where `value` is undefined) are set to expire
+ * immediately by defaulting `maxAge` to 0.
+ *
+ * @module lib/cookie/cookie
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import bake from 'ergo/lib/cookie/cookie';
+ *
+ * const c = bake('session', 'abc123', {maxAge: 3600, sameSite: 'Lax'});
+ * c.toHeader(); // 'session=abc123; Path=/; Max-Age=3600; SameSite=Lax; Secure; HttpOnly'
+ *
+ * // Expire a cookie by omitting value
+ * bake('session').toHeader(); // 'session=; Path=/; Max-Age=0; Expires=...; Secure; HttpOnly'
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6265 RFC 6265 - HTTP State Management Mechanism}
+ */
+export default bake;
+
+const dough = Object.create(
+  {},
+  {
+    toHeader: {
+      value() {
+        return toHeader(this);
+      }
+    },
+    isCookie: {
+      value: true
+    }
+  }
+);
+
+/**
+ * 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().
+ */
+function bake(
+  name,
+  value,
+  {domain, path = '/', maxAge, expires, sameSite, secure = true, httpOnly = true} = {}
+) {
+  // RFC 6265bis §5.4.7: SameSite=None requires the Secure attribute
+  const effectiveSecure =
+    sameSite !== undefined && String(sameSite).toLowerCase() === 'none' ? true : secure;
+
+  return Object.assign(Object.create(dough), {
+    name,
+    value,
+    domain,
+    path,
+    maxAge,
+    expires,
+    sameSite,
+    secure: effectiveSecure,
+    httpOnly
+  });
+}
+
+/**
+ * Creates a new cookie header.
+ * @param {object} cookie - The cookie object.
+ * @param {string} [cookie.name] - The name of the cookie.
+ * @param {string} [cookie.value] - The value of the cookie. If undefined
+ *  and expires/maxAge are undefined, the cookie will be set to expire.
+ * @param {string} [cookie.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} [cookie.path] - The absolute path of the cookie. Defaults
+ *  to the current path of the current document location.
+ * @param {boolean} [cookie.secure] - Indicates whether the cookie is
+ *  transmitted over secure protocols such as HTTPS.
+ * @param {string} [cookie.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 {boolean} [cookie.httpOnly] - Indicates whether the cookie is inaccessible
+ *  to client-side JavaScript (e.g. `document.cookie`). See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies|HttpOnly} for more information.
+ * @param {number} [cookie.maxAge] - The maximum age of a cookie in seconds.
+ * @param {(Date|string|number)} [cookie.expires] - The GMT timestamp of the cookie
+ *  expiration.
+ * @returns {string} - A serialized Set-Cookie header string.
+ */
+// RFC 6265 §4.1.1: cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+// Reject anything outside cookie-octet: SP, ", comma, semicolon, backslash, CTLs, DEL
+// eslint-disable-next-line no-control-regex -- intentional: reject CTLs per RFC 6265 cookie-octet
+const COOKIE_VALUE_UNSAFE_RE = /[\x00-\x20",;\\\x7f]/;
+// RFC 7230 §3.2.6: token = 1*tchar (no CTLs, SP, or delimiters)
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~\w]+$/;
+
+/**
+ * Rejects cookie values containing characters outside RFC 6265 cookie-octet.
+ * @param {*} val - Field value to check
+ * @param {string} field - Field name for the error message
+ * @throws {TypeError} If the value contains forbidden characters
+ */
+function assertSafeValue(val, field) {
+  if (typeof val === 'string' && COOKIE_VALUE_UNSAFE_RE.test(val)) {
+    throw new TypeError(`Cookie ${field} contains forbidden characters`);
+  }
+}
+
+/**
+ * Rejects cookie names that are not valid HTTP tokens per RFC 7230.
+ * @param {*} val - Name to check
+ * @throws {TypeError} If the name is not a valid token
+ */
+function assertSafeName(val) {
+  if (typeof val === 'string' && !TOKEN_RE.test(val)) {
+    throw new TypeError('Cookie name contains forbidden characters');
+  }
+}
+
+function toHeader({
+  name,
+  value,
+  domain,
+  path,
+  secure,
+  sameSite,
+  httpOnly,
+  maxAge = value === undefined ? 0 : undefined,
+  expires = value === undefined ? Date.now() + maxAge : undefined
+} = {}) {
+  assertSafeName(name);
+  assertSafeValue(value, 'value');
+  assertSafeValue(domain, 'domain');
+  assertSafeValue(path, 'path');
+
+  let header = `${name === undefined ? '' : name}=${value === undefined ? '' : value}`;
+
+  /*
+   * RFC 6265 uses OWS (optional whitespace) after semicolons; a space is
+   * conventional and maximizes compatibility with existing parsers.
+   * https://www.rfc-editor.org/rfc/rfc6265
+   */
+  if (domain !== undefined) {
+    header += `; Domain=${domain}`;
+  }
+
+  if (path !== undefined) {
+    header += `; Path=${path}`;
+  }
+
+  if (maxAge !== undefined) {
+    header += `; Max-Age=${maxAge}`;
+  }
+
+  if (expires !== undefined) {
+    header += `; Expires=${new Date(expires).toUTCString()}`;
+  }
+
+  assertSafeValue(sameSite, 'sameSite');
+
+  if (sameSite !== undefined) {
+    header += `; SameSite=${sameSite}`;
+  }
+
+  if (secure) {
+    header += '; Secure';
+  }
+
+  if (httpOnly) {
+    header += '; HttpOnly';
+  }
+
+  return header;
+}