@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/providers/capabilities.js

@@ -0,0 +1,46 @@
+export const PROVIDER_KINDS = Object.freeze([
+  "ADVISORY_CONTEXT",
+  "VERIFICATION_EXECUTION",
+  "BROWSER_VERIFICATION",
+  "SECURITY_REVIEW",
+  "PRESENTATION",
+]);
+
+export const PROVIDER_CAPABILITIES = Object.freeze({
+  ADVISORY_CONTEXT: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    executableAuthority: false,
+    evidenceAuthority: false,
+  }),
+  VERIFICATION_EXECUTION: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    canProduceExecutionObservation: true,
+    evidenceAuthority: false,
+  }),
+  BROWSER_VERIFICATION: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    evidenceRequiresForgeLoopValidation: true,
+    evidenceAuthority: false,
+  }),
+  SECURITY_REVIEW: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    evidenceRequiresForgeLoopValidation: true,
+    evidenceAuthority: false,
+  }),
+  PRESENTATION: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    executableAuthority: false,
+    evidenceAuthority: false,
+    mayMutateProtocolState: false,
+  }),
+});
+
+export function capabilityFor(kind) {
+  if (!PROVIDER_KINDS.includes(kind)) return null;
+  return PROVIDER_CAPABILITIES[kind] ?? null;
+}

package/src/providers/errors.js

@@ -0,0 +1,15 @@
+export const E_PROVIDER_INVALID = "E_PROVIDER_INVALID";
+export const E_PROVIDER_UNAVAILABLE = "E_PROVIDER_UNAVAILABLE";
+export const E_PROVIDER_TIMEOUT = "E_PROVIDER_TIMEOUT";
+export const E_PROVIDER_OUTPUT_INVALID = "E_PROVIDER_OUTPUT_INVALID";
+export const E_PROVIDER_OUTPUT_LIMIT = "E_PROVIDER_OUTPUT_LIMIT";
+export const E_PROVIDER_CAPABILITY_UNSUPPORTED = "E_PROVIDER_CAPABILITY_UNSUPPORTED";
+export const E_PROVIDER_AUTHORITY_ESCALATION = "E_PROVIDER_AUTHORITY_ESCALATION";
+export const E_PROVIDER_EXECUTION_FAILED = "E_PROVIDER_EXECUTION_FAILED";
+
+export function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "ProviderError";
+  error.code = code;
+  return error;
+}

package/src/providers/index.js

@@ -0,0 +1,29 @@
+import { PROVIDER_KINDS, PROVIDER_CAPABILITIES, capabilityFor } from "./capabilities.js";
+import {
+  E_PROVIDER_INVALID,
+  E_PROVIDER_UNAVAILABLE,
+  E_PROVIDER_TIMEOUT,
+  E_PROVIDER_OUTPUT_INVALID,
+  E_PROVIDER_OUTPUT_LIMIT,
+  E_PROVIDER_CAPABILITY_UNSUPPORTED,
+  E_PROVIDER_AUTHORITY_ESCALATION,
+  E_PROVIDER_EXECUTION_FAILED,
+  providerError,
+} from "./errors.js";
+import { createProviderRegistry } from "./registry.js";
+
+export {
+  PROVIDER_KINDS,
+  PROVIDER_CAPABILITIES,
+  capabilityFor,
+  E_PROVIDER_INVALID,
+  E_PROVIDER_UNAVAILABLE,
+  E_PROVIDER_TIMEOUT,
+  E_PROVIDER_OUTPUT_INVALID,
+  E_PROVIDER_OUTPUT_LIMIT,
+  E_PROVIDER_CAPABILITY_UNSUPPORTED,
+  E_PROVIDER_AUTHORITY_ESCALATION,
+  E_PROVIDER_EXECUTION_FAILED,
+  providerError,
+  createProviderRegistry,
+};

package/src/providers/json-snapshot.js

@@ -0,0 +1,105 @@
+import { types } from "node:util";
+import { deepFreeze } from "../core/portable-context.js";
+import {
+  E_PROVIDER_AUTHORITY_ESCALATION,
+  E_PROVIDER_INVALID,
+  E_PROVIDER_OUTPUT_INVALID,
+  E_PROVIDER_OUTPUT_LIMIT,
+  providerError,
+} from "./errors.js";
+
+const AUTHORITY_KEYS = new Set([
+  "lifecycleAuthority", "completionAuthority", "evidenceAuthority",
+  "executableAuthority", "installAuthority",
+]);
+
+export function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function serializeSnapshot(value, maxBytes, invalidCode) {
+  const ancestors = new WeakSet();
+  let bytes = 0;
+  let nodes = 0;
+  const invalid = () => { throw providerError(invalidCode, "Provider payload must contain only plain JSON data without accessors"); };
+  const limit = () => { throw providerError(E_PROVIDER_OUTPUT_LIMIT, "Provider payload exceeds its byte or structural limit"); };
+  function charge(text) {
+    bytes += Buffer.byteLength(text, "utf8");
+    if (bytes > maxBytes) limit();
+    return text;
+  }
+  function string(value) {
+    if (value.length > maxBytes - bytes) limit();
+    return charge(JSON.stringify(value));
+  }
+  function visit(value, depth) {
+    nodes += 1;
+    if (depth > 64 || nodes > 100_000) limit();
+    if (value === null) return charge("null");
+    if (typeof value === "string") return string(value);
+    if (typeof value === "boolean") return charge(String(value));
+    if (typeof value === "number" && Number.isFinite(value)) return charge(JSON.stringify(value));
+    if (typeof value !== "object" || types.isProxy(value)) invalid();
+    return visitContainer(value, depth);
+  }
+  function assertContainer(value, array) {
+    const valid = array ? Object.getPrototypeOf(value) === Array.prototype : isPlainObject(value);
+    if (!valid) invalid();
+  }
+  function visitContainer(value, depth) {
+    const array = Array.isArray(value);
+    assertContainer(value, array);
+    if (ancestors.has(value)) invalid();
+    ancestors.add(value);
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 100_000 || keys.length > maxBytes) limit();
+    const parts = [];
+    charge(array ? "[]" : "{}");
+    const length = array ? Object.getOwnPropertyDescriptor(value, "length").value : 0;
+    if (array && keys.length !== length + 1) invalid();
+    let index = 0;
+    for (const key of keys) {
+      if (array && key === "length") continue;
+      if (typeof key !== "string") invalid();
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) invalid();
+      if (array && key !== String(index)) invalid();
+      if (index > 0) charge(",");
+      const prefix = array ? "" : string(key) + charge(":");
+      parts.push(prefix + visit(descriptor.value, depth + 1));
+      index += 1;
+    }
+    if (array && index !== length) invalid();
+    ancestors.delete(value);
+    return array ? `[${parts.join(",")}]` : `{${parts.join(",")}}`;
+  }
+  return visit(value, 0);
+}
+
+function assertAuthorityFree(value) {
+  if (value === null || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (AUTHORITY_KEYS.has(key) && child === true) {
+      throw providerError(E_PROVIDER_AUTHORITY_ESCALATION, "Provider result declares forbidden authority");
+    }
+    assertAuthorityFree(child);
+  }
+}
+
+export function normalizeProviderInput(value, maxBytes) {
+  return deepFreeze(JSON.parse(serializeSnapshot(value, maxBytes, E_PROVIDER_INVALID)));
+}
+
+export function normalizeProviderResult(value, maxBytes) {
+  if (!isPlainObject(value)) {
+    throw providerError(E_PROVIDER_OUTPUT_INVALID, "Provider result must be a plain JSON object");
+  }
+  const normalized = JSON.parse(serializeSnapshot(value, maxBytes, E_PROVIDER_OUTPUT_INVALID));
+  assertAuthorityFree(normalized);
+  if (normalized.status === "COMPLETE") {
+    throw providerError(E_PROVIDER_AUTHORITY_ESCALATION, "Provider result cannot assign lifecycle completion");
+  }
+  return deepFreeze(normalized);
+}

package/src/providers/registry.js

@@ -0,0 +1,152 @@
+import { performance } from "node:perf_hooks";
+import { types } from "node:util";
+import { capabilityFor } from "./capabilities.js";
+import { isPlainObject, normalizeProviderInput, normalizeProviderResult } from "./json-snapshot.js";
+import {
+  E_PROVIDER_EXECUTION_FAILED,
+  E_PROVIDER_INVALID,
+  E_PROVIDER_TIMEOUT,
+  E_PROVIDER_UNAVAILABLE,
+  providerError,
+} from "./errors.js";
+
+const PROVIDER_ID_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const REGISTRY_MAX_PROVIDERS = 256;
+
+function assertEntry(entry, key) {
+  if (!isPlainObject(entry)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider must be a plain object");
+  }
+  for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(entry))) {
+    if (!("value" in descriptor)) throw providerError(E_PROVIDER_INVALID, "Provider accessors are not supported");
+  }
+  if (typeof entry.id !== "string" || !PROVIDER_ID_REGEX.test(entry.id) || entry.id !== key) {
+    throw providerError(E_PROVIDER_INVALID, "Provider identity does not match the registry key");
+  }
+  if (entry.version !== undefined && (typeof entry.version !== "string" || entry.version.trim() === "" || entry.version.length > 64)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider version must be a non-empty string of at most 64 characters");
+  }
+  if (!capabilityFor(entry.kind)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider declares an unsupported kind");
+  }
+  if (entry.capability !== undefined && entry.capability !== capabilityFor(entry.kind)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider capability metadata contradicts its kind");
+  }
+  if (typeof entry.operation !== "function") {
+    throw providerError(E_PROVIDER_INVALID, "Provider must implement operation(input, context)");
+  }
+}
+
+function boundedInteger(value, fallback, maximum) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isInteger(resolved) || resolved <= 0 || resolved > maximum) {
+    throw providerError(E_PROVIDER_INVALID, "Provider limits must be positive bounded integers");
+  }
+  return resolved;
+}
+
+function normalizeOptions(options) {
+  if (!isPlainObject(options)) throw providerError(E_PROVIDER_INVALID, "Provider options must be a plain object");
+  const descriptors = Object.getOwnPropertyDescriptors(options);
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!["timeoutMs", "maxInputBytes", "maxResultBytes"].includes(key) || !("value" in descriptor)) {
+      throw providerError(E_PROVIDER_INVALID, "Unsupported provider option");
+    }
+  }
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== "string") throw providerError(E_PROVIDER_INVALID, "Unsupported provider option");
+  }
+  return {
+    timeoutMs: boundedInteger(descriptors.timeoutMs?.value, 10_000, 300_000),
+    maxInputBytes: boundedInteger(descriptors.maxInputBytes?.value, 262_144, 4_194_304),
+    maxResultBytes: boundedInteger(descriptors.maxResultBytes?.value, 262_144, 4_194_304),
+  };
+}
+
+function callProvider(operation, normalize) {
+  let returned;
+  try {
+    returned = operation();
+  } catch {
+    throw providerError(E_PROVIDER_EXECUTION_FAILED, "Provider execution failed");
+  }
+  if (types.isPromise(returned) && !types.isProxy(returned)) {
+    return Promise.prototype.then.call(returned, normalize, () => {
+      throw providerError(E_PROVIDER_EXECUTION_FAILED, "Provider execution failed");
+    });
+  }
+  return normalize(returned);
+}
+
+async function withProviderDeadline(providerId, timeoutMs, operation) {
+  const controller = new AbortController();
+  const context = Object.freeze({ signal: controller.signal, timeoutMs, providerId });
+  const expires = performance.now() + timeoutMs;
+  const timeoutError = providerError(E_PROVIDER_TIMEOUT, "Provider invocation exceeded its deadline");
+  const checkpoint = () => {
+    if (controller.signal.aborted || performance.now() >= expires) {
+      controller.abort();
+      throw timeoutError;
+    }
+  };
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      controller.abort();
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      timeout,
+      Promise.resolve().then(() => operation(context, checkpoint)),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function createProviderRegistry({ providers = {} } = {}) {
+  if (!isPlainObject(providers)) throw providerError(E_PROVIDER_INVALID, "Provider registry requires an object map");
+  const map = new Map();
+  for (const key of Reflect.ownKeys(providers)) {
+    if (typeof key !== "string" || !PROVIDER_ID_REGEX.test(key)) {
+      throw providerError(E_PROVIDER_INVALID, "Invalid provider registry key");
+    }
+    if (map.size >= REGISTRY_MAX_PROVIDERS) throw providerError(E_PROVIDER_INVALID, "Too many providers");
+    const descriptor = Object.getOwnPropertyDescriptor(providers, key);
+    if (!("value" in descriptor) || !descriptor.enumerable) throw providerError(E_PROVIDER_INVALID, "Invalid provider registry entry");
+    const entry = descriptor.value;
+    if (typeof entry !== "function") assertEntry(entry, key);
+    map.set(key, entry);
+  }
+  return Object.freeze({
+    get(id) { return map.get(id) ?? null; },
+    has(id) { return map.has(id); },
+    list() { return [...map.keys()].sort(); },
+    async invoke(id, input = {}, options = {}) {
+      const { timeoutMs, maxInputBytes, maxResultBytes } = normalizeOptions(options);
+      if (!map.has(id)) throw providerError(E_PROVIDER_UNAVAILABLE, "Provider is not registered");
+      const payload = normalizeProviderInput(input, maxInputBytes);
+      const entry = map.get(id);
+      return withProviderDeadline(id, timeoutMs, async (context, checkpoint) => {
+        checkpoint();
+        const validate = provider => {
+          checkpoint();
+          assertEntry(provider, id);
+          return Object.freeze({ provider });
+        };
+        const { provider } = typeof entry === "function"
+          ? await callProvider(() => entry(context), validate)
+          : validate(entry);
+        checkpoint();
+        return callProvider(() => provider.operation(payload, context), result => {
+          checkpoint();
+          const normalized = normalizeProviderResult(result, maxResultBytes);
+          checkpoint();
+          return normalized;
+        });
+      });
+    },
+  });
+}