@omega.js/backend 0.1.0

package/dist/manager/helpers/safe-compare.js

@@ -0,0 +1,31 @@
+/**
+ * Constant-time string comparison for secrets (admin keys, webhook keys).
+ *
+ * A plain `===` on a secret leaks how many leading characters match through
+ * response timing. crypto.timingSafeEqual requires equal-length buffers, so
+ * both inputs are reduced to a fixed-length SHA-256 digest first — the
+ * comparison is then always constant-time regardless of input lengths.
+ * The digest is unkeyed on purpose: it only normalizes length here, it is
+ * not standing in for a MAC.
+ */
+const crypto = require('crypto');
+
+/**
+ * Compare two secrets in constant time.
+ *
+ * @param {string} a - Candidate value (e.g. from the request)
+ * @param {string} b - Expected value (e.g. from the environment)
+ * @returns {boolean} True when both are non-empty strings and equal
+ */
+function safeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || !a || !b) {
+    return false;
+  }
+
+  const hashA = crypto.createHash('sha256').update(a).digest();
+  const hashB = crypto.createHash('sha256').update(b).digest();
+
+  return crypto.timingSafeEqual(hashA, hashB);
+}
+
+module.exports = safeCompare;

package/dist/manager/helpers/schema-engine.js

@@ -0,0 +1,314 @@
+/**
+ * schema-engine.js — in-house declarative schema resolution (replaces powertools.defaults()
+ * for settings; node-powertools stays a dependency for its other utilities).
+ *
+ * The shared field pipeline BOTH engines run on:
+ *   - Declarative node schemas: Settings.resolve() → resolveSchema() walks the schema
+ *     and resolves each leaf through resolveFieldValue().
+ *   - Zod schemas: the fields.* builders (schema-zod.js) wrap the same
+ *     resolveFieldValue() in z.preprocess pipes.
+ *
+ * Semantics are powertools.defaults() parity, proven differentially in
+ * test/helpers/schema-zod.js, with deliberate bug fixes:
+ *   - No default-object pollution: powertools mutated non-empty object/array defaults
+ *     in place (injecting types/min/max/value/default keys) and returned them by
+ *     reference; this engine clones defaults per request and returns them clean.
+ *   - Sound leaf detection: a node is a field when it carries any field option —
+ *     powertools' walk only terminated on no-default nodes because its own pollution
+ *     added `default`/`value` to them first. A `types` key that is neither a type
+ *     list nor a nested node throws, naming the path: a malformed leaf is an author
+ *     error, and reading it as a group resolved the field away silently.
+ *   - min/max enforce ONLY when declared (Ian, cp84): powertools' `min || 0` /
+ *     `max || Infinity` clamped negatives to 0 on every undeclared-min number field
+ *     and made declared 0-bounds vanish. Now: no min → negatives pass through;
+ *     min: 0 / max: 0 are real bounds.
+ *   - min bounds strings and arrays by LENGTH, at the route boundary: a short
+ *     value is REFUSED with a 400, never padded — see enforceMins()
+ *     ([#789](https://github.com/Omega-JS-Stack/omega/issues/789)).
+ *
+ * Preserved quirks (wire-visible, kept for parity):
+ *   - Coerce-never-reject: single-typed fields force(), multi-typed replace with default.
+ *   - Empty-object schema nodes ({}) contribute nothing to output; unknown keys strip.
+ */
+
+const powertools = require('node-powertools');
+const _ = require('lodash');
+
+// Node options accepted by the zod fields builders — one-to-one with declarative
+// schema nodes. `sanitize` is carried for the middleware sanitize pass; `enum` and
+// the string/array `min` floor are enforced post-resolution at the route boundary —
+// see enforceEnums() and enforceMins().
+const FIELD_OPTIONS = ['types', 'default', 'value', 'min', 'max', 'required', 'clean', 'sanitize', 'enum'];
+
+// Keys that mark a declarative node as a FIELD (leaf) rather than a nested group.
+// Superset of FIELD_OPTIONS: legacy declarative schemas may also carry `available`.
+const LEAF_KEYS = [...FIELD_OPTIONS, 'available'];
+
+/**
+ * Whether `types` holds a DECLARATION (a non-empty list of type names) rather
+ * than a field named `types`.
+ * @param {*} value - The node's `types` value
+ * @returns {boolean}
+ */
+function isTypeList(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((type) => typeof type === 'string');
+}
+
+/**
+ * Whether a declarative schema node is a field (leaf) rather than a nested group.
+ *
+ * `types` decides on SHAPE, not on presence: a schema declaring a field
+ * literally named `types` (`{types: {types: ['array']}, name: {...}}`) used to
+ * read as one leaf, so the whole schema resolved to {} and every request 400'd
+ * ([#256](https://github.com/Omega-JS-Stack/omega/issues/256)). A declaration
+ * is always a list of type names; a nested NODE under that key is a field
+ * named `types`; anything else is neither, and a schema is author-written code
+ * — so it THROWS rather than reading as a group whose field then silently
+ * resolves away (`{types: 'string'}` used to strip its own leaf; the powertools
+ * engine it replaced threw).
+ * @param {*} node - Schema node
+ * @param {string} [path] - Dot path of the node, for the error message
+ * @returns {boolean}
+ * @throws {Error} When `types` is neither a type list nor a nested node
+ */
+function isFieldNode(node, path) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    return false;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(node, 'types')) {
+    if (isTypeList(node.types)) {
+      return true;
+    }
+
+    // A field literally named `types`, or a group of them.
+    if (node.types && typeof node.types === 'object' && !Array.isArray(node.types)) {
+      return false;
+    }
+
+    const received = node.types === undefined ? 'undefined' : JSON.stringify(node.types);
+
+    throw new Error(`Invalid schema at "${path || '(root)'}": \`types\` must be a non-empty array of type names (or a nested field node named "types"), received ${received}`);
+  }
+
+  return LEAF_KEYS.some((key) => Object.prototype.hasOwnProperty.call(node, key));
+}
+
+/**
+ * Depth-first walk of a declarative schema, calling fn(dotPath, node) for each field
+ * node. Plain objects without field options are groups (recursed); empty objects and
+ * non-object values contribute nothing (powertools enumerated no paths for them).
+ * @param {object} schema - Declarative schema (map of key → field node or group)
+ * @param {function} fn - (path, node) called per field node, in schema key order
+ * @param {string} [path] - Internal recursion prefix
+ */
+function iterateSchema(schema, fn, path) {
+  path = path || '';
+
+  // The ROOT is never a leaf: a marker key there names a FIELD, and there is no
+  // key to resolve the root onto anyway — reading it as a leaf swallowed every
+  // sibling ([#256](https://github.com/Omega-JS-Stack/omega/issues/256)).
+  if (path && isFieldNode(schema, path)) {
+    fn(path, schema);
+    return;
+  }
+
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return;
+  }
+
+  Object.keys(schema).forEach((key) => {
+    iterateSchema(schema[key], fn, path ? `${path}.${key}` : key);
+  });
+}
+
+/**
+ * Resolve settings against a declarative schema — drop-in replacement for
+ * powertools.defaults(settings, schema). Returns a NEW object containing ONLY
+ * schema-declared paths (unknown keys stripped at every level), each leaf resolved
+ * through the shared pipeline. Mutates neither settings nor schema.
+ * @param {object} settings - Raw input data
+ * @param {object} schema - Declarative schema
+ * @returns {object} Resolved settings
+ */
+function resolveSchema(settings, schema) {
+  const output = {};
+
+  iterateSchema(schema, (path, node) => {
+    _.set(output, path, resolveFieldValue(_.get(settings, path), node));
+  });
+
+  return output;
+}
+
+/**
+ * Replicate powertools' enforceValidTypes() (node-powertools src/lib/object.js):
+ * single-typed fields coerce via force(), multi-typed fields replace with the
+ * default on mismatch, 'any' accepts everything. null and arrays pass as 'object'
+ * (typeof semantics), matching the original.
+ */
+function enforceValidTypes(value, types, def) {
+  const isValidType = types.some((type) => {
+    if (type === 'any') return true;
+    return typeof value === type || (type === 'array' && Array.isArray(value));
+  });
+
+  const resolved = types.length === 1 && types[0] !== 'any'
+    ? (isValidType ? value : powertools.force(value, types[0]))
+    : (isValidType ? value : def);
+
+  // NaN and ±Infinity are `number` to typeof, so the check above accepts them
+  // and enforceMinMax's comparisons against NaN are all false — the clamp never
+  // fires and the value flows to sinks like usage.consume(), where it poisons
+  // every later limit comparison
+  // ([#244](https://github.com/Omega-JS-Stack/omega/issues/244)). A non-finite
+  // number is never a usable value: it takes the default, like any other
+  // rejected input. Checked AFTER coercion, which can produce one of its own
+  // (force('Infinity', 'number')).
+  if (typeof resolved === 'number' && !Number.isFinite(resolved)) {
+    return def;
+  }
+
+  return resolved;
+}
+
+/**
+ * Bounds: numbers clamp to [min, max]; strings and arrays truncate to max. A
+ * string or array shorter than `min` is NOT padded here — length floors are
+ * refusals, enforced at the route boundary by enforceMins(). Enforced ONLY when
+ * the schema declares them — undeclared min means negatives pass through, and a
+ * declared 0 is a real bound (unlike powertools' `min || 0` / `max || Infinity`).
+ */
+function enforceMinMax(value, min, max) {
+  const isNumber = typeof value === 'number';
+  const isString = typeof value === 'string';
+
+  if (min !== undefined && isNumber && value < min) {
+    return min;
+  }
+
+  if (max !== undefined) {
+    if (isNumber && value > max) {
+      return max;
+    } else if (isString && value.length > max) {
+      return value.slice(0, max);
+    } else if (Array.isArray(value) && value.length > max) {
+      return value.slice(0, max);
+    }
+  }
+
+  return value;
+}
+
+/**
+ * Enforce enum constraints post-resolution: values the caller actually SENT are
+ * checked against the allowed list (after coercion — the resolved value is what
+ * handlers see); out-of-list values reject with 400. Absent fields pass — enum
+ * does not imply required, and schema-author defaults are presumed valid.
+ * Runs at the route boundary (Settings.resolve / resolveZodSchema), not inside
+ * resolveSchema(), so bare resolution stays a pure defaults/coercion pass.
+ * @param {object} ctx - RouteContext (report)
+ * @param {object} raw - The ORIGINAL request settings (absence check)
+ * @param {object} resolved - The resolved settings (value check)
+ * @param {Array<{path: string, allowed: Array}>} enumPaths - Fields carrying enum lists
+ */
+function enforceEnums(ctx, raw, resolved, enumPaths) {
+  for (const { path, allowed } of enumPaths) {
+    if (typeof _.get(raw, path) === 'undefined') {
+      continue;
+    }
+
+    const value = _.get(resolved, path);
+
+    if (!allowed.includes(value)) {
+      throw ctx.report(`Invalid settings {${path}}: must be one of [${allowed.join(', ')}]`, {code: 400});
+    }
+  }
+}
+
+/**
+ * Enforce `min` on lengths post-resolution: a resolved string or array shorter
+ * than its declared `min` rejects with 400, in the same shape enforceEnums()
+ * produces. Numbers never reach here below their bound (enforceMinMax clamps
+ * them); values with no length (booleans, objects, null) have no floor.
+ *
+ * Runs at the route boundary (Settings.resolve / resolveZodSchema), NOT inside
+ * resolveFieldValue(): the refusal needs the ctx and the dot-path a single
+ * leaf's resolution never sees, resolveSchema() also serves callers that must
+ * only resolve and never reject (routes/user/settings/validate), and at the
+ * boundary it reads the FINAL value — post forced `value` and `clean` — which
+ * is what the handler sees. A short value is refused rather than padded: the
+ * documented path-id idiom (path-derived default + `min: 1`, NOT `required`)
+ * guarded nothing while min bounded numbers only
+ * ([#789](https://github.com/Omega-JS-Stack/omega/issues/789)).
+ * @param {object} ctx - RouteContext (report)
+ * @param {object} resolved - The resolved settings (length check)
+ * @param {Array<{path: string, min: number}>} minPaths - Fields carrying a min
+ */
+function enforceMins(ctx, resolved, minPaths) {
+  for (const { path, min } of minPaths) {
+    const value = _.get(resolved, path);
+    const isString = typeof value === 'string';
+
+    if (!isString && !Array.isArray(value)) {
+      continue;
+    }
+
+    if (value.length < min) {
+      const bound = isString
+        ? `must be at least ${min} character${min === 1 ? '' : 's'}`
+        : `must have at least ${min} item${min === 1 ? '' : 's'}`;
+
+      throw ctx.report(`Invalid settings {${path}}: ${bound}`, {code: 400});
+    }
+  }
+}
+
+/**
+ * Resolve one field's raw input through the powertools node pipeline:
+ * default-or-user → enforceValidTypes → enforceMinMax → forced value → clean.
+ */
+function resolveFieldValue(raw, opts) {
+  const types = opts.types || ['any'];
+
+  // powertools skips executing function defaults/values for 'any'/'function' types
+  // (the function itself becomes the value)
+  const shouldExecute = !types.includes('any') && !types.includes('function');
+
+  let value = opts.value;
+  if (typeof value === 'function' && shouldExecute) {
+    value = value();
+  }
+
+  let def = opts.default;
+  if (typeof def === 'function' && shouldExecute) {
+    def = def();
+  }
+
+  // Clone object/array defaults so a request can't mutate schema state and the
+  // pollution divergence documented in the header stays fixed
+  if (def && typeof def === 'object') {
+    def = _.cloneDeep(def);
+  }
+
+  let working = typeof raw === 'undefined' ? def : raw;
+  working = enforceValidTypes(working, types, def);
+  working = enforceMinMax(working, opts.min, opts.max);
+
+  if (typeof value !== 'undefined') {
+    working = value;
+  }
+
+  // Clean — applied to the fully-resolved value
+  if (opts.clean) {
+    if (opts.clean instanceof RegExp) {
+      working = working.replace(opts.clean, '');
+    } else if (typeof opts.clean === 'function') {
+      working = opts.clean(working);
+    }
+  }
+
+  return working;
+}
+
+module.exports = { FIELD_OPTIONS, isFieldNode, iterateSchema, resolveSchema, resolveFieldValue, enforceEnums, enforceMins };

package/dist/manager/helpers/schema-zod.js

@@ -0,0 +1,203 @@
+/**
+ * schema-zod.js — zod route-schema support with powertools-parity semantics.
+ *
+ * A `schemas/<route>/<method>.js` module may export a zod schema instead of a
+ * declarative node object; Settings.resolve() detects it (isZodSchema) and runs
+ * resolveZodSchema() in place of the declarative walk. Wire shapes are preserved:
+ * schemas built with the `fields` builders run the SAME field pipeline as the
+ * declarative engine (shared in schema-engine.js — coerce-never-reject,
+ * clamp/truncate, required fires on undefined/'') — see
+ * _attic/plans/archive/zod-route-schemas-design.md for the full preservation checklist.
+ *
+ * Builders (mirror the declarative node options one-to-one):
+ *   const { z, fields: f } = require('../../helpers/schema-zod.js');
+ *   module.exports = (context) => f.object({
+ *     name: f.string({ default: undefined, required: true }),
+ *     amount: f.number({ default: 1, min: 1, max: 100 }),
+ *     tags: f.array({ default: [] }),
+ *     config: f.passthrough({ default: {} }),          // types: ['object'] — nested content passes through
+ *     version: f.multi(['string', 'number'], { default: '5' }),
+ *     nested: f.object({ level1: f.string({ default: 'x' }) }),
+ *   });
+ *
+ * Every field is a z.preprocess() pipe — zod 4 runs preprocess for ABSENT object
+ * keys (transforms are skipped), which is what lets defaults apply to missing input.
+ *
+ * A module may also export raw zod (no builders). That opts into zod-native
+ * semantics: invalid input REJECTS with 400 instead of coercing, and there is no
+ * `required` metadata (use zod's own optional/refine machinery).
+ *
+ * The field pipeline (and its deliberate powertools bug fixes: no default-object
+ * pollution, defaults cloned per request) lives in schema-engine.js — shared with
+ * the declarative engine and asserted in test/helpers/schema-zod.js.
+ */
+
+const { z } = require('zod');
+const _ = require('lodash');
+const { FIELD_OPTIONS, resolveFieldValue, enforceEnums, enforceMins } = require('./schema-engine.js');
+
+/**
+ * Detect a zod schema (any version with the zod 4 internal marker).
+ * Duck-typed instead of instanceof so consumer projects with their own zod copy work.
+ * @param {*} x
+ * @returns {boolean}
+ */
+function isZodSchema(x) {
+  return !!x && typeof x === 'object' && typeof x.safeParse === 'function' && !!x._zod;
+}
+
+/**
+ * Resolve settings against a zod schema — the zod counterpart of the declarative
+ * walk in Settings.resolve().
+ * Required semantics (fires on undefined/'', function support, checkRequired
+ * opt-out), enum enforcement (sent values checked post-coercion; absent fields
+ * pass) and the min length floor (short strings/arrays refuse) run from the
+ * ._omegaMeta registry that fields.object() builds; the error messages and codes
+ * match the declarative engine exactly.
+ * @param {object} ctx - RouteContext (report)
+ * @param {import('zod').ZodType} schema - Zod schema (usually from fields.object())
+ * @param {object} settings - Raw request data
+ * @param {object} options - Resolve options (checkRequired, user, ...)
+ * @returns {object} Resolved settings
+ */
+function resolveZodSchema(ctx, schema, settings, options) {
+  const meta = schema._omegaMeta;
+
+  // Required check — same rule as the declarative engine: fires when the raw value
+  // is undefined or '' (null, 0, false pass), honoring checkRequired and
+  // function-valued required(ctx, settings, options).
+  if (options.checkRequired && meta) {
+    for (const [path, node] of Object.entries(meta.paths)) {
+      const isRequired = typeof node.required === 'function'
+        ? node.required(ctx, settings, options)
+        : node.required === true;
+
+      const raw = _.get(settings, path);
+
+      if (isRequired && (typeof raw === 'undefined' || raw === '')) {
+        throw ctx.report(`Required key {${path}} is missing in settings`, {code: 400});
+      }
+    }
+  }
+
+  // Parse (parity builders never fail here — everything coerces; raw zod schemas can)
+  const result = schema.safeParse(settings);
+  if (!result.success) {
+    const first = result.error.issues[0];
+    const where = first && first.path.length ? ` {${first.path.join('.')}}` : '';
+
+    throw ctx.report(`Invalid settings${where}: ${first ? first.message : 'validation failed'}`, {code: 400});
+  }
+
+  // Enum + min enforcement — post-resolution, same layer as the declarative engine
+  if (meta) {
+    const enumPaths = Object.entries(meta.paths)
+      .filter(([, node]) => Array.isArray(node.enum))
+      .map(([path, node]) => ({ path: path, allowed: node.enum }));
+
+    enforceEnums(ctx, settings, result.data, enumPaths);
+
+    const minPaths = Object.entries(meta.paths)
+      .filter(([, node]) => typeof node.min !== 'undefined')
+      .map(([path, node]) => ({ path: path, min: node.min }));
+
+    enforceMins(ctx, result.data, minPaths);
+  }
+
+  return result.data;
+}
+
+/**
+ * Build the nested per-field map Settings.resolve exposes as self.schema for the
+ * middleware sanitize pass ({ sanitize } per leaf, mirroring the settings
+ * structure). Raw zod schemas have no registry → {} (every field sanitizes).
+ * @param {import('zod').ZodType} schema - Zod schema
+ * @returns {object} Nested map of leaf path → { sanitize }
+ */
+function buildSchemaMap(schema) {
+  const map = {};
+  const meta = schema._omegaMeta;
+
+  if (!meta) {
+    return map;
+  }
+
+  for (const [path, node] of Object.entries(meta.paths)) {
+    _.set(map, path, { sanitize: node.sanitize });
+  }
+
+  return map;
+}
+
+/**
+ * Generic field builder — accepts the exact declarative node options.
+ * @param {object} opts - { types, default, value, min, max, required, clean, sanitize }
+ * @returns {import('zod').ZodType} Preprocess pipe with ._omega metadata attached
+ */
+function field(opts) {
+  opts = opts || {};
+
+  // Catch migration typos (e.g. `defualt`) — declarative schemas silently ignored
+  // unknown node props; the builders are the one place strictness is free
+  const unknown = Object.keys(opts).filter((key) => !FIELD_OPTIONS.includes(key));
+  if (unknown.length) {
+    throw new Error(`schema-zod field(): unknown option(s) ${unknown.join(', ')} (allowed: ${FIELD_OPTIONS.join(', ')})`);
+  }
+
+  const type = z.preprocess((raw) => resolveFieldValue(raw, opts), z.any());
+
+  type._omega = {
+    required: opts.required || false,
+    sanitize: opts.sanitize !== false,
+    enum: opts.enum,
+    min: opts.min,
+  };
+
+  return type;
+}
+
+/**
+ * Structural group — wraps z.object() so absent/invalid parents still resolve leaf
+ * defaults (powertools resolves each leaf path independently). Builds the
+ * ._omegaMeta registry of dot-paths → {required, sanitize} that resolveZodSchema()
+ * uses for required checks, bubbling nested groups up with prefixed paths.
+ * Unknown keys are stripped (zod object default), matching powertools.
+ * @param {object} shape - Map of key → fields.* builder (or raw zod type)
+ * @returns {import('zod').ZodType}
+ */
+function object(shape) {
+  const paths = {};
+
+  for (const [key, type] of Object.entries(shape)) {
+    if (type._omega) {
+      paths[key] = type._omega;
+    } else if (type._omegaMeta) {
+      for (const [subPath, node] of Object.entries(type._omegaMeta.paths)) {
+        paths[`${key}.${subPath}`] = node;
+      }
+    }
+  }
+
+  const wrapped = z.preprocess((raw) => {
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  }, z.object(shape));
+
+  wrapped._omegaMeta = { paths };
+
+  return wrapped;
+}
+
+// Sugar builders — one per declarative `types` shape
+const fields = {
+  object: object,
+  field: field,
+  string: (opts) => field({ ...opts, types: ['string'] }),
+  number: (opts) => field({ ...opts, types: ['number'] }),
+  boolean: (opts) => field({ ...opts, types: ['boolean'] }),
+  array: (opts) => field({ ...opts, types: ['array'] }),
+  any: (opts) => field({ ...opts, types: ['any'] }),
+  passthrough: (opts) => field({ ...opts, types: ['object'] }),
+  multi: (types, opts) => field({ ...opts, types: types }),
+};
+
+module.exports = { z, fields, isZodSchema, resolveZodSchema, buildSchemaMap };