openyida 2026.7.18 → 2026.7.21

package/lib/schema/manifest-limits.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const { schemaError } = require('./errors');
+
+const MANIFEST_INPUT_LIMITS = Object.freeze({
+  maxBytes: 1024 * 1024,
+  maxDepth: 80,
+  maxNodes: 20000,
+  maxCollectionItems: 1000,
+  maxStringLength: 8192,
+});
+
+const MANIFEST_LIMIT_KEYS = Object.freeze(Object.keys(MANIFEST_INPUT_LIMITS));
+
+function createManifestLimitState(options = {}) {
+  return {
+    limits: resolveManifestInputLimits(options),
+    nodes: 0,
+    seen: typeof WeakSet === 'function' ? new WeakSet() : null,
+  };
+}
+
+function resolveManifestInputLimits(options = {}) {
+  const overrides = options.limits;
+  if (overrides === undefined) {
+    return Object.assign({}, MANIFEST_INPUT_LIMITS);
+  }
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throwInvalidLimit();
+  }
+
+  const result = {};
+  const knownKeys = new Set(MANIFEST_LIMIT_KEYS);
+  for (const key of Object.keys(overrides)) {
+    if (!knownKeys.has(key)) {
+      throwInvalidLimit();
+    }
+  }
+  for (const key of MANIFEST_LIMIT_KEYS) {
+    const defaultValue = MANIFEST_INPUT_LIMITS[key];
+    if (!Object.prototype.hasOwnProperty.call(overrides, key)) {
+      result[key] = defaultValue;
+      continue;
+    }
+    const override = overrides[key];
+    if (!Number.isSafeInteger(override) || override <= 0) {
+      throwInvalidLimit();
+    }
+    result[key] = Math.min(defaultValue, override);
+  }
+  return result;
+}
+
+function throwInvalidLimit() {
+  throw schemaError('SCHEMA_MANIFEST_LIMIT_INVALID', 'Manifest input limit override is invalid.');
+}
+
+function assertManifestFileSize(byteLength, options = {}) {
+  const limits = resolveManifestInputLimits(options);
+  if (!Number.isFinite(byteLength) || byteLength < 0) {
+    throw schemaError('SCHEMA_MANIFEST_LOAD_FAILED', 'Unable to read manifest file.');
+  }
+  if (byteLength > limits.maxBytes) {
+    throw schemaError('SCHEMA_MANIFEST_TOO_LARGE', 'Manifest file exceeds the maximum supported size.', {
+      path: '/',
+      details: {
+        limit: limits.maxBytes,
+      },
+    });
+  }
+}
+
+function assertManifestNode(state, pathSegments, depth) {
+  if (depth > state.limits.maxDepth) {
+    throw schemaError('SCHEMA_MANIFEST_DEPTH_LIMIT_EXCEEDED', 'Manifest JSON exceeds the maximum supported depth.', {
+      path: formatJsonPointer(pathSegments),
+      details: {
+        limit: state.limits.maxDepth,
+      },
+    });
+  }
+  state.nodes += 1;
+  if (state.nodes > state.limits.maxNodes) {
+    throw schemaError('SCHEMA_MANIFEST_NODE_LIMIT_EXCEEDED', 'Manifest JSON exceeds the maximum supported node count.', {
+      path: formatJsonPointer(pathSegments),
+      details: {
+        limit: state.limits.maxNodes,
+      },
+    });
+  }
+}
+
+function assertManifestCollectionSize(state, size, pathSegments) {
+  if (size > state.limits.maxCollectionItems) {
+    throw schemaError('SCHEMA_MANIFEST_COLLECTION_LIMIT_EXCEEDED', 'Manifest JSON collection exceeds the maximum supported item count.', {
+      path: formatJsonPointer(pathSegments),
+      details: {
+        limit: state.limits.maxCollectionItems,
+      },
+    });
+  }
+}
+
+function assertManifestStringLength(state, value, pathSegments) {
+  if (String(value).length > state.limits.maxStringLength) {
+    throw schemaError('SCHEMA_MANIFEST_STRING_LIMIT_EXCEEDED', 'Manifest JSON string exceeds the maximum supported length.', {
+      path: formatJsonPointer(pathSegments),
+      details: {
+        limit: state.limits.maxStringLength,
+      },
+    });
+  }
+}
+
+function assertManifestObjectLimits(value, options = {}) {
+  const state = createManifestLimitState(options);
+  visit(value, state, [], 0);
+}
+
+function visit(value, state, pathSegments, depth) {
+  assertManifestNode(state, pathSegments, depth);
+  if (typeof value === 'string') {
+    assertManifestStringLength(state, value, pathSegments);
+    return;
+  }
+  if (!value || typeof value !== 'object') {
+    return;
+  }
+  if (state.seen) {
+    if (state.seen.has(value)) {
+      throw schemaError('SCHEMA_MANIFEST_STRUCTURE_UNSUPPORTED', 'Manifest JSON object graph must be acyclic.', {
+        path: formatJsonPointer(pathSegments),
+      });
+    }
+    state.seen.add(value);
+  }
+  if (Array.isArray(value)) {
+    assertManifestCollectionSize(state, value.length, pathSegments);
+    value.forEach((item, index) => visit(item, state, pathSegments.concat(String(index)), depth + 1));
+    return;
+  }
+  if (!isPlainJsonObject(value)) {
+    throw schemaError('SCHEMA_MANIFEST_STRUCTURE_UNSUPPORTED', 'Manifest JSON object graph must contain only plain objects and arrays.', {
+      path: formatJsonPointer(pathSegments),
+    });
+  }
+  const keys = Object.keys(value);
+  assertManifestCollectionSize(state, keys.length, pathSegments);
+  keys.forEach((key) => {
+    assertManifestStringLength(state, key, pathSegments.concat(key));
+    visit(value[key], state, pathSegments.concat(key), depth + 1);
+  });
+}
+
+function isPlainJsonObject(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function formatJsonPointer(segments) {
+  if (!segments || segments.length === 0) {
+    return '/';
+  }
+  return '/' + segments.map(segment => String(segment).replace(/~/g, '~0').replace(/\//g, '~1')).join('/');
+}
+
+module.exports = {
+  MANIFEST_INPUT_LIMITS,
+  assertManifestCollectionSize,
+  assertManifestFileSize,
+  assertManifestNode,
+  assertManifestObjectLimits,
+  assertManifestStringLength,
+  createManifestLimitState,
+  formatJsonPointer,
+  resolveManifestInputLimits,
+};

package/lib/schema/manifest-loader.js

@@ -0,0 +1,309 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { schemaError } = require('./errors');
+const {
+  assertManifestCollectionSize,
+  assertManifestFileSize,
+  assertManifestNode,
+  assertManifestStringLength,
+  createManifestLimitState,
+  formatJsonPointer,
+  resolveManifestInputLimits,
+} = require('./manifest-limits');
+
+function loadManifest(manifestPath, options = {}) {
+  if (!manifestPath || typeof manifestPath !== 'string') {
+    throw schemaError('SCHEMA_INVALID_ARGUMENTS', 'Manifest path is required.');
+  }
+
+  const resolved = resolveManifestPath(manifestPath, options);
+  const raw = readManifestFileBounded(resolved.realPath, options);
+
+  detectDuplicateJsonKeys(raw, options);
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw schemaError('SCHEMA_MANIFEST_PARSE_FAILED', 'Manifest file must be valid JSON.', {
+      details: {
+        reason: error && error.message ? String(error.message).split('\n')[0] : 'Invalid JSON',
+      },
+    });
+  }
+}
+
+function readManifestFileBounded(filePath, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const limits = resolveManifestInputLimits(options);
+  const readLimit = limits.maxBytes + 1;
+  const flags = resolveOpenFlags(fsImpl);
+  let fd;
+  try {
+    fd = fsImpl.openSync(filePath, flags);
+    const stat = fsImpl.fstatSync(fd);
+    if (!stat || typeof stat.isFile !== 'function' || !stat.isFile()) {
+      throw schemaError('SCHEMA_MANIFEST_LOAD_FAILED', 'Unable to read manifest file.');
+    }
+    assertManifestFileSize(stat.size, { limits });
+
+    const buffer = Buffer.alloc(readLimit);
+    let totalRead = 0;
+    while (totalRead < readLimit) {
+      const bytesRead = fsImpl.readSync(fd, buffer, totalRead, readLimit - totalRead, null);
+      if (bytesRead === 0) {
+        break;
+      }
+      totalRead += bytesRead;
+      if (totalRead > limits.maxBytes) {
+        throw schemaError('SCHEMA_MANIFEST_TOO_LARGE', 'Manifest file exceeds the maximum supported size.', {
+          path: '/',
+          details: { limit: limits.maxBytes },
+        });
+      }
+    }
+    return buffer.toString('utf8', 0, totalRead);
+  } catch (error) {
+    if (error && error.code && String(error.code).startsWith('SCHEMA_')) {
+      throw error;
+    }
+    throw schemaError('SCHEMA_MANIFEST_LOAD_FAILED', 'Unable to read manifest file.');
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fsImpl.closeSync(fd);
+      } catch {
+        // Best effort close: keep the original read/validation error stable.
+      }
+    }
+  }
+}
+
+function resolveOpenFlags(fsImpl) {
+  const constants = fsImpl.constants || fs.constants || {};
+  const readOnly = constants.O_RDONLY !== undefined ? constants.O_RDONLY : 'r';
+  if (typeof readOnly === 'number' && typeof constants.O_NOFOLLOW === 'number') {
+    return readOnly | constants.O_NOFOLLOW;
+  }
+  return readOnly;
+}
+
+function resolveManifestPath(manifestPath, options = {}) {
+  const workspaceRoot = path.resolve(options.workspaceRoot || options.projectRoot || process.cwd());
+  let rootRealPath;
+  try {
+    rootRealPath = fs.realpathSync(workspaceRoot);
+  } catch {
+    throw schemaError('SCHEMA_MANIFEST_PATH_UNSAFE', 'Manifest path must stay inside the workspace trust root.', {
+      path: '/',
+    });
+  }
+
+  const absolutePath = path.isAbsolute(manifestPath)
+    ? path.resolve(manifestPath)
+    : path.resolve(rootRealPath, manifestPath);
+  const lexicallyInside = isPathInside(rootRealPath, absolutePath) ||
+    (path.isAbsolute(manifestPath) && isPathInside(workspaceRoot, absolutePath));
+
+  let realPath;
+  try {
+    realPath = fs.realpathSync(absolutePath);
+  } catch {
+    if (!lexicallyInside) {
+      throw schemaError('SCHEMA_MANIFEST_PATH_UNSAFE', 'Manifest path must stay inside the workspace trust root.', {
+        path: '/',
+      });
+    }
+    throw schemaError('SCHEMA_MANIFEST_LOAD_FAILED', 'Unable to read manifest file.');
+  }
+  if (!isPathInside(rootRealPath, realPath)) {
+    throw schemaError('SCHEMA_MANIFEST_PATH_UNSAFE', 'Manifest path must stay inside the workspace trust root.', {
+      path: '/',
+    });
+  }
+
+  return {
+    realPath,
+    rootRealPath,
+  };
+}
+
+function isPathInside(rootPath, targetPath) {
+  const relative = path.relative(rootPath, targetPath);
+  return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function detectDuplicateJsonKeys(source, options = {}) {
+  let index = 0;
+  const limitState = createManifestLimitState(options);
+
+  function skipWhitespace() {
+    while (index < source.length && /\s/.test(source[index])) {
+      index += 1;
+    }
+  }
+
+  function parseString(pathSegments) {
+    let result = '';
+    index += 1;
+    while (index < source.length) {
+      const char = source[index];
+      if (char === '"') {
+        index += 1;
+        return result;
+      }
+      if (char === '\\') {
+        index += 1;
+        if (index >= source.length) {
+          return result;
+        }
+        const escaped = source[index];
+        if (escaped === 'u') {
+          const hex = source.slice(index + 1, index + 5);
+          if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+            result += String.fromCharCode(parseInt(hex, 16));
+            index += 5;
+          } else {
+            index += 1;
+          }
+          continue;
+        }
+        const escapeMap = {
+          '"': '"',
+          '\\': '\\',
+          '/': '/',
+          b: '\b',
+          f: '\f',
+          n: '\n',
+          r: '\r',
+          t: '\t',
+        };
+        result += Object.prototype.hasOwnProperty.call(escapeMap, escaped) ? escapeMap[escaped] : escaped;
+        assertManifestStringLength(limitState, result, pathSegments);
+        index += 1;
+        continue;
+      }
+      result += char;
+      assertManifestStringLength(limitState, result, pathSegments);
+      index += 1;
+    }
+    return result;
+  }
+
+  function parseNumber() {
+    const start = index;
+    while (index < source.length && /[-+0-9.eE]/.test(source[index])) {
+      index += 1;
+    }
+    if (index === start) {
+      index += 1;
+    }
+  }
+
+  function parseLiteral(value) {
+    if (source.slice(index, index + value.length) === value) {
+      index += value.length;
+    } else {
+      index += 1;
+    }
+  }
+
+  function parseArray(pathSegments, depth) {
+    index += 1;
+    let itemIndex = 0;
+    skipWhitespace();
+    if (source[index] === ']') {
+      index += 1;
+      return;
+    }
+    while (index < source.length) {
+      if (itemIndex + 1 > limitState.limits.maxCollectionItems) {
+        assertManifestCollectionSize(limitState, itemIndex + 1, pathSegments);
+      }
+      parseValue(pathSegments.concat(String(itemIndex)), depth + 1);
+      itemIndex += 1;
+      skipWhitespace();
+      if (source[index] === ',') {
+        index += 1;
+        continue;
+      }
+      if (source[index] === ']') {
+        index += 1;
+      }
+      return;
+    }
+  }
+
+  function parseObject(pathSegments, depth) {
+    index += 1;
+    const keys = new Set();
+    skipWhitespace();
+    if (source[index] === '}') {
+      index += 1;
+      return;
+    }
+    while (index < source.length) {
+      skipWhitespace();
+      if (source[index] !== '"') {
+        return;
+      }
+      const key = parseString(pathSegments);
+      assertManifestStringLength(limitState, key, pathSegments.concat(key));
+      if (keys.has(key)) {
+        throw schemaError('SCHEMA_DUPLICATE_KEY', 'Manifest contains duplicate JSON object keys.', {
+          path: formatJsonPointer(pathSegments.concat(key)),
+          details: { key },
+        });
+      }
+      keys.add(key);
+      assertManifestCollectionSize(limitState, keys.size, pathSegments);
+      skipWhitespace();
+      if (source[index] !== ':') {
+        return;
+      }
+      index += 1;
+      parseValue(pathSegments.concat(key), depth + 1);
+      skipWhitespace();
+      if (source[index] === ',') {
+        index += 1;
+        continue;
+      }
+      if (source[index] === '}') {
+        index += 1;
+      }
+      return;
+    }
+  }
+
+  function parseValue(pathSegments, depth) {
+    skipWhitespace();
+    assertManifestNode(limitState, pathSegments, depth);
+    const char = source[index];
+    if (char === '{') {
+      parseObject(pathSegments, depth);
+    } else if (char === '[') {
+      parseArray(pathSegments, depth);
+    } else if (char === '"') {
+      parseString(pathSegments);
+    } else if (char === 't') {
+      parseLiteral('true');
+    } else if (char === 'f') {
+      parseLiteral('false');
+    } else if (char === 'n') {
+      parseLiteral('null');
+    } else {
+      parseNumber();
+    }
+  }
+
+  parseValue([], 0);
+}
+
+module.exports = {
+  detectDuplicateJsonKeys,
+  isPathInside,
+  loadManifest,
+  readManifestFileBounded,
+  resolveManifestPath,
+};

package/lib/schema/manifest-schema-v1.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openyida.ai/schemas/openyida-app-manifest-v1.json",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "app"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "const": "openyida_app_manifest"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "app": {
+      "$ref": "#/definitions/app"
+    },
+    "forms": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/form"
+      }
+    },
+    "processes": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/process"
+      }
+    },
+    "pages": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/page"
+      }
+    }
+  },
+  "definitions": {
+    "app": {
+      "type": "object",
+      "required": ["key", "name"],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "form": {
+      "type": "object",
+      "required": ["title", "fields"],
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mode": {
+          "enum": ["receipt", "process"]
+        },
+        "dependsOn": {
+          "$ref": "#/definitions/dependencyList"
+        },
+        "fields": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "$ref": "#/definitions/field"
+          }
+        }
+      }
+    },
+    "field": {
+      "type": "object",
+      "required": ["type", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              {
+                "type": "object",
+                "required": ["label", "value"],
+                "additionalProperties": false,
+                "properties": {
+                  "label": { "type": "string", "minLength": 1 },
+                  "value": { "type": "string", "minLength": 1 }
+                }
+              }
+            ]
+          }
+        },
+        "form": {
+          "type": "string",
+          "minLength": 1
+        },
+        "dependsOn": {
+          "$ref": "#/definitions/dependencyList"
+        },
+        "children": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "$ref": "#/definitions/field"
+          }
+        }
+      }
+    },
+    "process": {
+      "type": "object",
+      "required": ["form", "nodes"],
+      "additionalProperties": false,
+      "properties": {
+        "form": {
+          "type": "string",
+          "minLength": 1
+        },
+        "nodes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/processNode"
+          }
+        }
+      }
+    },
+    "page": {
+      "type": "object",
+      "required": ["title", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "dependsOn": {
+          "$ref": "#/definitions/dependencyList"
+        }
+      }
+    },
+    "processNode": {
+      "type": "object",
+      "required": ["key", "type", "name", "approver"],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "approver": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "dependencyList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  }
+}