Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

15.4 KB
Raw Blame
// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
/**
 * Layered workspace configuration.
 *
 * A workspace may carry two files under `<root>/.openviking/`: `config.json`,
 * which the team commits, and `config.local.json`, which stays private. A third
 * layer lives per machine in the user registry. All three share this schema and
 * this merge, so there is one set of rules to learn and one to test.
 *
 * These files are trusted without a prompt — a hook is non-interactive, and any
 * approval gate degrades into "run one command per workspace first". What is
 * refused instead is structural, and costs nobody anything:
 *
 *   - connection and credential keys are stripped, loudly. "Which server does
 *     my data go to" must stay answerable without reading a repository.
 *   - `${VAR}` is never expanded here. Variable expansion is a property of the
 *     layer, not of the parser: a committed file that could expand `${HOME}`
 *     could exfiltrate the environment.
 *
 * Everything else a workspace file sets takes effect. What it turns off is
 * announced rather than blocked.
 */

import { readFileSync, realpathSync, statSync } from "node:fs";
import { isAbsolute, join, relative } from "node:path";

import { WORKSPACE_ENUMS, WORKSPACE_KNOB_MAP, WORKSPACE_RANGES } from "./config-schema.mjs";
import { CONFIG_DIR_NAME, LOCAL_FILE, TEAM_FILE } from "./workspace-identity.mjs";

/**
 * `JSON.parse` keeps `__proto__` as an own property, and assigning it walks
 * into `Object.prototype`. Since `process.env` reads through the prototype
 * chain and the environment outranks ovcli.conf, one such key in a committed
 * file would set `OPENVIKING_URL` and `OPENVIKING_API_KEY` for the whole
 * process — the exact thing every other rule here exists to prevent.
 */
const UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];

// Deep enough for any real config; a file can nest far past the stack limit
// inside the 64 KiB cap, and an overflow here would take out sibling layers.
const MAX_DEPTH = 32;

export { CONFIG_DIR_NAME, TEAM_FILE, LOCAL_FILE };
export const CONFIG_VERSION = 1;
export const MAX_CONFIG_BYTES = 64 * 1024;

/**
 * Keys no workspace file may set, at any depth. Connection and credentials
 * belong to ovcli.conf and the environment, full stop — this is the invariant
 * git spells `protected configuration`.
 */
export const FORBIDDEN_KEYS = [
  "url",
  "base_url",
  "mcp_url",
  "api_key",
  "bearer_token",
  "root_api_key",
  "gateway_token",
  "oidc_token",
  "ldap_username",
  "ldap_password",
  "account",
  "account_id",
  "user",
  "user_id",
  "auth_mode",
  "extra_headers",
  "credential_source",
  "cli_config_file",
  "config_file",
  // The camelCase spellings the harness loaders use. The projection into
  // harness knobs is an allowlist, so these could never take effect anyway —
  // but someone who writes `apiKey` here deserves to be told it was ignored,
  // not to have it vanish.
  "baseUrl",
  "mcpUrl",
  "apiKey",
  "bearerToken",
  "rootApiKey",
  "gatewayToken",
  "accountId",
  "userId",
  "authMode",
  "extraHeaders",
  "credentialSource",
  "credentialPath",
  "configPath",
];

/**
 * Sections whose keys are the user's own vocabulary, not ours. The ban below is
 * recursive so no section can smuggle a credential to a consumer that spreads
 * it into a request — but a free-form map's `user` key is a label, and
 * mangling it would be a bug, not a defence.
 */
export const FREE_FORM_SECTIONS = ["labels"];

/**
 * The workspace schema is a projection of `config-schema.mjs`: the dotted key,
 * its enum members and its range all come from the one knob declaration, so a
 * knob cannot be spelled one way here and another way in the loaders.
 */
const ENUMS = WORKSPACE_ENUMS;
const RANGES = WORKSPACE_RANGES;
const KNOB_MAP = WORKSPACE_KNOB_MAP;

export const WORKSPACE_SCHEMA_KEYS = Object.keys(KNOB_MAP);

/** -1, 0 or 1 over dotted numeric versions; a non-numeric tail is ignored. */
function compareVersions(left, right) {
  const parse = (value) => String(value || "").split(".").map((part) => Number.parseInt(part, 10) || 0);
  const a = parse(left);
  const b = parse(right);
  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
    const diff = (a[i] || 0) - (b[i] || 0);
    if (diff) return diff < 0 ? -1 : 1;
  }
  return 0;
}

/**
 * `min_client_version` warns and never blocks. A committed file that could stop
 * an older plugin from running would be a denial of service anyone with commit
 * access could mount, so it says "this was written for a newer client" and the
 * settings still apply.
 */
export function checkMinClientVersion(declared, clientVersion, warnings = []) {
  const required = String(declared || "").trim();
  const current = String(clientVersion || "").trim();
  if (!required || !current) return true;
  if (compareVersions(current, required) >= 0) return true;
  warnings.push(
    `this workspace asks for OpenViking plugin ${required} and this one is ${current}; `
    + "settings it introduced will be ignored rather than blocking the session",
  );
  return false;
}

function isPlainObject(value) {
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}

/**
 * Strip banned keys wherever they appear, collecting one warning per hit. They
 * are removed rather than rejected: a file is not made unusable by carrying a
 * key this layer refuses to honour.
 */
function stripForbidden(value, banned, warnings, path = "", depth = 0) {
  if (depth > MAX_DEPTH) throw new RangeError(`nested more than ${MAX_DEPTH} levels at '${path}'`);
  if (Array.isArray(value)) {
    return value.map((item, index) => stripForbidden(item, banned, warnings, `${path}[${index}]`, depth + 1));
  }
  if (!isPlainObject(value)) return value;

  const out = {};
  for (const [key, child] of Object.entries(value)) {
    const here = path ? `${path}.${key}` : key;
    if (UNSAFE_KEYS.includes(key)) {
      warnings.push(`ignored '${here}': a config file may not reach the object prototype`);
      continue;
    }
    if (banned.includes(key)) {
      warnings.push(`ignored '${here}': connection and credential settings belong in ovcli.conf or the environment`);
      continue;
    }
    // Matched on the key itself, not on depth: a registry entry keeps the same
    // section under `settings.`, and it must not end up stricter than the
    // committed file it outranks.
    out[key] = FREE_FORM_SECTIONS.includes(key)
      ? stripUnsafeOnly(child, warnings, here, depth + 1)
      : stripForbidden(child, banned, warnings, here, depth + 1);
  }
  return out;
}

/** A free-form section keeps its own vocabulary, minus the prototype keys. */
function stripUnsafeOnly(value, warnings, path, depth) {
  return stripForbidden(value, [], warnings, path, depth);
}

/**
 * Read one layer file. Every failure is a warning and an empty layer — a hook
 * must not die because a config file is odd.
 */
export function readWorkspaceFile(path, { root = "", layer = "" } = {}) {
  const warnings = [];
  const empty = { path, layer, exists: false, data: null, warnings };

  let stat;
  try {
    stat = statSync(path);
  } catch {
    return empty;
  }
  empty.exists = true;
  if (!stat.isFile()) {
    warnings.push(`${path} is not a regular file`);
    return empty;
  }
  if (stat.size > MAX_CONFIG_BYTES) {
    warnings.push(`${path} is larger than ${MAX_CONFIG_BYTES} bytes`);
    return empty;
  }
  // A symlink out of the workspace would let a repository read a file the user
  // never meant to expose to it.
  if (root) {
    try {
      const rel = relative(realpathSync(root), realpathSync(path));
      if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
        warnings.push(`${path} resolves outside the workspace`);
        return empty;
      }
    } catch {
      warnings.push(`${path} could not be resolved`);
      return empty;
    }
  }

  let parsed;
  try {
    // Deliberately bare: no `${VAR}` expansion reaches a workspace file.
    parsed = JSON.parse(readFileSync(path, "utf-8"));
  } catch (err) {
    warnings.push(`${path} is not valid JSON (${err?.message || err})`);
    return empty;
  }
  if (!isPlainObject(parsed)) {
    warnings.push(`${path} must contain a JSON object`);
    return empty;
  }
  if (parsed.version !== CONFIG_VERSION) {
    warnings.push(`${path} declares version ${JSON.stringify(parsed.version)}; this client understands ${CONFIG_VERSION}`);
    return empty;
  }

  const { version, $schema, min_client_version: minClientVersion, ...rest } = parsed;
  let data;
  try {
    data = stripForbidden(rest, FORBIDDEN_KEYS, warnings);
  } catch (err) {
    warnings.push(`${path} is nested too deeply (${err?.message || err})`);
    return empty;
  }
  if (minClientVersion) data.min_client_version = String(minClientVersion);

  return { path, layer, exists: true, data, warnings };
}

function shadow(provenance, here, value, source) {
  const previous = provenance[here];
  const shadowed = previous ? [{ value: previous.value, source: previous.source }, ...previous.shadowed] : [];
  provenance[here] = { value, source, shadowed };
  return provenance[here];
}

function mergeInto(target, source, layer, provenance, path = "", depth = 0) {
  if (depth > MAX_DEPTH) throw new RangeError(`nested more than ${MAX_DEPTH} levels at '${path}'`);
  for (const [key, value] of Object.entries(source)) {
    if (UNSAFE_KEYS.includes(key)) continue;
    const here = path ? `${path}.${key}` : key;

    if (isPlainObject(value)) {
      // A section replacing a scalar is still a change of the effective value,
      // so the scalar has to be recorded as shadowed rather than left standing
      // in provenance as if it were still in force.
      if (!isPlainObject(target[key])) {
        if (target[key] !== undefined) shadow(provenance, here, "(section)", layer);
        target[key] = {};
      }
      mergeInto(target[key], value, layer, provenance, here, depth + 1);
      continue;
    }

    if (Array.isArray(value)) {
      // `"!reset"` drops everything the lower layers contributed, the way
      // EditorConfig's `unset` and git's empty `safe.directory` do.
      const reset = value[0] === "!reset";
      const incoming = reset ? value.slice(1) : value;
      const inheritable = !reset && Array.isArray(target[key]);
      const merged = inheritable ? [...target[key]] : [];
      for (const item of incoming) if (!merged.includes(item)) merged.push(item);

      // Only a genuine union credits both layers. A list landing on a scalar,
      // or on nothing, belongs to this layer alone.
      const previous = provenance[here];
      if (inheritable && previous) {
        provenance[here] = {
          value: merged,
          source: [previous.source, layer].filter(Boolean).join(" + "),
          shadowed: previous.shadowed,
        };
      } else {
        shadow(provenance, here, merged, reset ? `${layer} (reset)` : layer);
      }
      target[key] = merged;
      continue;
    }

    shadow(provenance, here, value, layer);
    target[key] = value;
  }
}

/**
 * Merge layers given lowest-precedence first, returning the effective value
 * plus, for every key, where it came from and what it covered up — the same
 * question `git config --show-origin --show-scope` answers.
 */
export function mergeConfigLayers(layers, warnings = []) {
  const value = {};
  const provenance = {};
  for (const { layer, data } of layers) {
    if (!isPlainObject(data)) continue;
    try {
      mergeInto(value, data, layer, provenance);
    } catch (err) {
      // One pathological layer must not take the others down with it.
      warnings.push(`skipped ${layer}: ${err?.message || err}`);
    }
  }
  return { value, provenance };
}

function get(object, path) {
  return path.split(".").reduce((node, key) => (isPlainObject(node) ? node[key] : undefined), object);
}

function set(object, path, value) {
  const keys = path.split(".");
  const last = keys.pop();
  let node = object;
  for (const key of keys) {
    if (!isPlainObject(node[key])) node[key] = {};
    node = node[key];
  }
  node[last] = value;
}

/**
 * Clamp numbers and reject unknown enum values, warning once per key.
 *
 * A repository can raise a cost knob, so the ceiling is enforced here rather
 * than trusted; an out-of-range value is clamped instead of rejected so a typo
 * degrades rather than disables.
 */
export function normalizeWorkspaceConfig(value, warnings = []) {
  for (const [path, { min, max, integer }] of Object.entries(RANGES)) {
    const raw = get(value, path);
    if (raw === undefined) continue;
    // `Number()` turns null, true and [] into finite numbers, which would
    // silently pin a knob to a bound instead of reporting a bad value.
    const number = typeof raw === "number" || typeof raw === "string" ? Number(raw) : NaN;
    if (!Number.isFinite(number)) {
      warnings.push(`ignored '${path}': ${JSON.stringify(raw)} is not a number`);
      set(value, path, undefined);
      continue;
    }
    const clamped = Math.min(max, Math.max(min, integer ? Math.floor(number) : number));
    if (clamped !== number) warnings.push(`clamped '${path}' from ${number} to ${clamped} (allowed ${min}..${max})`);
    set(value, path, clamped);
  }

  for (const [path, allowed] of Object.entries(ENUMS)) {
    if (!allowed) continue;
    const raw = get(value, path);
    if (raw === undefined) continue;
    if (!allowed.includes(raw)) {
      warnings.push(`ignored '${path}': ${JSON.stringify(raw)} is not one of ${allowed.join(", ")}`);
      set(value, path, undefined);
    }
  }
  return value;
}

/**
 * Flatten the merged workspace config into the flat knobs a harness loader
 * reads, so the new layers slot in exactly where the ovcli `plugin` section
 * already does and everything downstream — including the env vars that still
 * win — keeps working unchanged.
 */
export function projectWorkspaceSettings(value) {
  const settings = {};
  for (const [path, knob] of Object.entries(KNOB_MAP)) {
    const raw = get(value, path);
    if (raw !== undefined) settings[knob] = raw;
  }
  return settings;
}

export function workspaceConfigPaths(root) {
  if (!root) return [];
  const dir = join(root, CONFIG_DIR_NAME);
  return [
    { layer: `${TEAM_FILE} (workspace)`, path: join(dir, TEAM_FILE) },
    { layer: `${LOCAL_FILE} (workspace)`, path: join(dir, LOCAL_FILE) },
  ];
}

/**
 * The two workspace-file layers, lowest precedence first. Callers stack the
 * registry above these and the ovcli.conf plugin section below them.
 */
export function loadWorkspaceLayers(root, { clientVersion = "" } = {}) {
  const warnings = [];
  const layers = [];
  for (const { layer, path } of workspaceConfigPaths(root)) {
    const file = readWorkspaceFile(path, { root, layer });
    warnings.push(...file.warnings);
    if (!file.data) continue;
    const { min_client_version: declared, ...data } = file.data;
    checkMinClientVersion(declared, clientVersion, warnings);
    layers.push({ layer, data, path });
  }
  return { layers, warnings };
}

/**
 * Settings a workspace file turned off. Announced at session start and in
 * doctor, because trusting the file is a decision the user should be able to
 * see rather than one made silently on their behalf.
 */
export function announcedOverrides(provenance) {
  const announced = [];
  for (const [key, entry] of Object.entries(provenance)) {
    const fromWorkspace = String(entry.source || "").includes("(workspace)");
    if (!fromWorkspace) continue;
    if (entry.value === false || key === "peer.id" || key === "peer.source" || key.startsWith("bypass.")) {
      announced.push({ key, value: entry.value, source: entry.source });
    }
  }
  return announced;
}