@hamzaabili/opencode-integrity 0.0.0-stage → 0.1.0

package/src/cli.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { relative, resolve } from "node:path";
+import {
+  collectStaticAssets,
+  describeAudit,
+  filterAssets,
+  filterIgnored,
+  mergeRuntimeTools,
+} from "./audit.ts";
+import {
+  audit,
+  createLockfile,
+  formatDrift,
+  readLockfile,
+  severityCounts,
+  writeLockfile,
+} from "./lockfile.ts";
+import { parseOptions } from "./options.ts";
+import { generatePolicy } from "./policy.ts";
+import { toSarif } from "./sarif.ts";
+import { VERSION } from "./version.ts";
+
+type Command = "audit" | "lock" | "check" | "diff" | "policy" | "version";
+
+interface Args {
+  command: Command;
+  directory: string;
+  home: string;
+  lockfile?: string;
+  format: "text" | "json" | "sarif";
+  strict: boolean;
+  ignore: string[];
+  includeGlobal: boolean;
+}
+
+function parseArgs(argv: readonly string[]): Args {
+  const output: Args = {
+    command: "audit",
+    directory: process.cwd(),
+    home: homedir(),
+    format: "text",
+    strict: false,
+    ignore: [],
+    includeGlobal: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    const next = (): string => {
+      index += 1;
+      return argv[index] ?? "";
+    };
+    if (["audit", "lock", "check", "diff", "policy", "version"].includes(arg)) {
+      output.command = arg as Command;
+      continue;
+    }
+    switch (arg) {
+      case "--directory":
+      case "-C":
+        output.directory = resolve(next());
+        break;
+      case "--home":
+        output.home = resolve(next());
+        break;
+      case "--lockfile":
+        output.lockfile = next();
+        break;
+      case "--json":
+        output.format = "json";
+        break;
+      case "--format": {
+        const value = next();
+        output.format = value === "json" || value === "sarif" ? value : "text";
+        break;
+      }
+      case "--strict":
+        output.strict = true;
+        break;
+      case "--ignore":
+        output.ignore.push(next());
+        break;
+      case "--include-global":
+        output.includeGlobal = true;
+        break;
+      case "--version":
+      case "-v":
+        output.command = "version";
+        break;
+      default:
+        break;
+    }
+  }
+  return output;
+}
+
+function usage(): string {
+  return [
+    "opencode-integrity <audit|lock|check|diff|policy|version> [options]",
+    "",
+    "  audit     show loaded assets and drift (exit 0)",
+    "  lock      write opencode.lock.json from the current project",
+    "  check     compare against the lockfile (exit 1 on drift)",
+    "  diff      print the drift report (exit 0)",
+    "  policy    emit OpenCode policy allow statements from the lockfile",
+    "",
+    "  --directory, -C <path>  project directory (default: cwd)",
+    "  --home <path>           home directory (default: $HOME)",
+    "  --lockfile <path>       lockfile path (default: <project>/opencode.lock.json)",
+    "  --format text|json|sarif",
+    "  --strict                audit exits 1 on drift or an unlocked project",
+    "  --ignore <pattern>      ignore an asset id (repeatable)",
+    "  --include-global        include global MCP config (runtime also plugins/skills)",
+  ].join("\n");
+}
+
+async function main(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === "version") {
+    console.log(`opencode-integrity ${VERSION}`);
+    return 0;
+  }
+  if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(usage());
+    return 0;
+  }
+
+  const options = parseOptions(
+    {
+      lockfile: args.lockfile,
+      ignore: args.ignore,
+      includeGlobal: args.includeGlobal,
+      mode: "warn",
+    },
+    args.directory,
+    args.home
+  );
+
+  const current = await collectStaticAssets(args.directory, args.home, options);
+  const rawPrevious = await readLockfile(options.lockfile);
+  const previous =
+    rawPrevious === undefined
+      ? undefined
+      : { ...rawPrevious, assets: filterAssets(rawPrevious.assets, options.include) };
+
+  if (args.command === "lock") {
+    const merged = filterAssets(mergeRuntimeTools(current.assets, previous), options.include);
+    const lockfile = createLockfile(merged, undefined, VERSION);
+    await writeLockfile(options.lockfile, lockfile);
+    if (args.format === "json") console.log(JSON.stringify(lockfile, null, 2));
+    else {
+      console.log(`locked ${options.lockfile}`);
+      console.log(
+        `assets: ${Object.keys(merged.plugins).length} plugin(s), ${Object.keys(merged.mcp).length} MCP server(s), ${Object.keys(merged.skills).length} skill(s)`
+      );
+      const missing = Object.entries(merged.mcp)
+        .filter(([, asset]) => Object.keys(asset.tools ?? {}).length === 0)
+        .map(([name]) => name);
+      if (missing.length > 0) {
+        console.log(
+          `warning: no runtime MCP tool descriptors for ${missing.join(", ")}; run /integrity lock inside OpenCode to pin tool definitions.`
+        );
+      }
+    }
+    return 0;
+  }
+
+  if (args.command === "policy") {
+    const assets = previous?.assets ?? current.assets;
+    console.log(JSON.stringify(generatePolicy(assets), null, 2));
+    return 0;
+  }
+
+  const merged = filterAssets(mergeRuntimeTools(current.assets, previous), options.include);
+  const result = audit(previous?.assets, merged, current.warnings, false);
+  const drift = filterIgnored(result.drift, options.ignore);
+  const final = { ...result, drift, ok: drift.length === 0 };
+
+  if (args.format === "sarif") {
+    const uri = relative(args.directory, options.lockfile) || options.lockfile;
+    console.log(JSON.stringify(toSarif(drift, VERSION, uri, !final.locked), null, 2));
+  } else if (args.format === "json") {
+    console.log(JSON.stringify(final, null, 2));
+  } else if (args.command === "diff") {
+    console.log(drift.length === 0 ? "no drift" : formatDrift(drift));
+  } else {
+    console.log(describeAudit(final, args.command === "audit"));
+    if (final.locked && !final.ok) {
+      const counts = severityCounts(drift);
+      console.log(
+        `summary: ${counts.high ?? 0} high, ${counts.medium ?? 0} medium, ${counts.low ?? 0} low`
+      );
+    }
+  }
+
+  if (args.command === "check") return final.ok && final.locked ? 0 : 1;
+  if (args.command === "audit" && args.strict) return final.ok && final.locked ? 0 : 1;
+  return 0;
+}
+
+process.exitCode = await main();

package/src/config.ts

@@ -0,0 +1,123 @@
+import { join } from "node:path";
+import { isDirectory, pathExists, readJsoncFile } from "./util.ts";
+
+export interface PluginRef {
+  readonly target: string;
+  readonly version?: string;
+  readonly localPath?: string;
+}
+
+export interface ProjectConfig {
+  readonly files: readonly string[];
+  readonly plugins: readonly PluginRef[];
+  readonly mcp: Readonly<Record<string, unknown>>;
+  readonly warnings: readonly string[];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pluginRef(value: unknown): PluginRef | undefined {
+  if (typeof value === "string") {
+    return value.trim().length > 0 ? { target: value.trim() } : undefined;
+  }
+  if (Array.isArray(value) && typeof value[0] === "string") {
+    return { target: value[0] };
+  }
+  if (isObject(value) && typeof value.package === "string") {
+    return { target: value.package };
+  }
+  return undefined;
+}
+
+function configPaths(directory: string): string[] {
+  return [
+    join(directory, "opencode.json"),
+    join(directory, "opencode.jsonc"),
+    join(directory, ".opencode", "opencode.json"),
+    join(directory, ".opencode", "opencode.jsonc"),
+  ];
+}
+
+function mcpFromConfig(data: Record<string, unknown>): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+  if (!isObject(data.mcp)) return output;
+  if (isObject(data.mcp.servers)) Object.assign(output, data.mcp.servers);
+  for (const [name, value] of Object.entries(data.mcp)) {
+    if (name === "servers" || name === "timeout") continue;
+    if (isObject(value)) output[name] = value;
+  }
+  return output;
+}
+
+/** Global MCP servers, only used when `includeGlobal` is enabled. */
+export async function loadGlobalMcp(home: string): Promise<Record<string, unknown>> {
+  const output: Record<string, unknown> = {};
+  for (const path of [
+    join(home, ".config", "opencode", "opencode.json"),
+    join(home, ".config", "opencode", "opencode.jsonc"),
+  ]) {
+    if (!(await pathExists(path))) continue;
+    const data = await readJsoncFile(path);
+    if (isObject(data)) Object.assign(output, mcpFromConfig(data));
+  }
+  return output;
+}
+
+/** Read the project-scoped OpenCode configuration. Global config is intentionally excluded. */
+export async function loadProjectConfig(directory: string): Promise<ProjectConfig> {
+  const files: string[] = [];
+  const plugins: PluginRef[] = [];
+  const mcp: Record<string, unknown> = {};
+  const warnings: string[] = [];
+
+  for (const path of configPaths(directory)) {
+    if (!(await pathExists(path))) continue;
+    const data = await readJsoncFile(path);
+    if (!isObject(data)) {
+      warnings.push(`${path}: unreadable or invalid JSONC`);
+      continue;
+    }
+    files.push(path);
+    const values = [
+      ...(Array.isArray(data.plugins) ? data.plugins : []),
+      ...(Array.isArray(data.plugin) ? data.plugin : []),
+    ];
+    for (const value of values) {
+      const ref = pluginRef(value);
+      if (ref !== undefined) plugins.push(ref);
+    }
+    Object.assign(mcp, mcpFromConfig(data));
+  }
+
+  // V2 loads direct plugin files/directories under .opencode/plugins.
+  const pluginDirectory = join(directory, ".opencode", "plugins");
+  if (await isDirectory(pluginDirectory)) {
+    const { readdir } = await import("node:fs/promises");
+    for (const entry of await readdir(pluginDirectory, { withFileTypes: true })) {
+      if (entry.isDirectory())
+        plugins.push({
+          target: join(pluginDirectory, entry.name),
+          localPath: join(pluginDirectory, entry.name),
+        });
+      else if (entry.isFile() && /\.(ts|js|mjs|cjs)$/.test(entry.name)) {
+        plugins.push({
+          target: join(pluginDirectory, entry.name),
+          localPath: join(pluginDirectory, entry.name),
+        });
+      }
+    }
+  }
+
+  return { files, plugins: dedupe(plugins), mcp, warnings };
+}
+
+function dedupe(values: readonly PluginRef[]): PluginRef[] {
+  const seen = new Set<string>();
+  return values.filter((value) => {
+    if (seen.has(value.target)) return false;
+    seen.add(value.target);
+    return true;
+  });
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * opencode-integrity — dual OpenCode entry point.
+ *
+ * V2 calls `setup(ctx)` and inspects the live plugin/MCP/skill/tool surface.
+ * V1 calls `server(input, options)` and audits the project-scoped files only.
+ */
+
+import { server } from "./v1.ts";
+import { setup as setupV2 } from "./v2.ts";
+
+export const plugin = {
+  id: "opencode-integrity",
+  setup: setupV2,
+  server,
+};
+
+export default plugin;
+export { VERSION } from "./version.ts";
+export { server };

package/src/lockfile.ts

@@ -0,0 +1,298 @@
+import type { Assets, AuditResult, DriftEntry, Lockfile } from "./types.ts";
+import { SCHEMA_VERSION } from "./types.ts";
+import { readJsonFile, stableStringify, writeFileAtomic } from "./util.ts";
+
+function sortRecord<T>(value: Readonly<Record<string, T>>): Record<string, T> {
+  return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function sortAssets(assets: Assets): Assets {
+  return {
+    plugins: sortRecord(assets.plugins),
+    mcp: Object.fromEntries(
+      Object.entries(assets.mcp)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, asset]) => [
+          name,
+          { ...asset, tools: asset.tools === undefined ? undefined : sortRecord(asset.tools) },
+        ])
+    ),
+    skills: sortRecord(assets.skills),
+  };
+}
+
+export function createLockfile(assets: Assets, opencode?: string, version = "0.1.0"): Lockfile {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedBy: `opencode-integrity@${version}`,
+    opencode,
+    assets: sortAssets(assets),
+  };
+}
+
+export async function readLockfile(path: string): Promise<Lockfile | undefined> {
+  const raw = await readJsonFile<unknown>(path);
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const record = raw as Record<string, unknown>;
+  if (record.schemaVersion !== SCHEMA_VERSION || typeof record.assets !== "object")
+    return undefined;
+  const assets = record.assets as Record<string, unknown>;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedBy: typeof record.generatedBy === "string" ? record.generatedBy : "unknown",
+    opencode: typeof record.opencode === "string" ? record.opencode : undefined,
+    assets: {
+      plugins: isRecord(assets.plugins) ? (assets.plugins as Assets["plugins"]) : {},
+      mcp: isRecord(assets.mcp) ? (assets.mcp as Assets["mcp"]) : {},
+      skills: isRecord(assets.skills) ? (assets.skills as Assets["skills"]) : {},
+    },
+  };
+}
+
+export async function writeLockfile(path: string, lockfile: Lockfile): Promise<void> {
+  const canonical = JSON.parse(stableStringify(lockfile)) as Lockfile;
+  await writeFileAtomic(path, `${JSON.stringify(canonical, null, 2)}\n`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function diffAssets(locked: Assets, current: Assets, compareTools = true): DriftEntry[] {
+  const drift: DriftEntry[] = [];
+
+  for (const [id, asset] of Object.entries(current.plugins)) {
+    const before = locked.plugins[id];
+    if (before === undefined) {
+      drift.push({
+        asset: "plugin",
+        id,
+        change: "added",
+        severity: "high",
+        message: `new plugin ${id}`,
+      });
+      continue;
+    }
+    if (before.truncated === true || asset.truncated === true) {
+      drift.push({
+        asset: "plugin",
+        id,
+        change: "changed",
+        field: "hash incomplete",
+        severity: "high",
+        message: `plugin ${id}: package too large to hash completely; reduce it or inspect manually`,
+      });
+      continue;
+    }
+    if (before.contentHash !== asset.contentHash || before.packageHash !== asset.packageHash) {
+      const fields: string[] = [];
+      if (before.version !== asset.version)
+        fields.push(`version ${before.version ?? "?"} -> ${asset.version ?? "?"}`);
+      if (before.contentHash !== asset.contentHash) fields.push("package content changed");
+      drift.push({
+        asset: "plugin",
+        id,
+        change: "changed",
+        field: fields.join(", "),
+        severity: "high",
+        message: `plugin ${id}: ${fields.join(", ") || "content changed"}`,
+      });
+    }
+    const added = (asset.capabilities ?? []).filter(
+      (capability) => !(before.capabilities ?? []).includes(capability)
+    );
+    if (added.length > 0) {
+      drift.push({
+        asset: "plugin",
+        id,
+        change: "changed",
+        field: `capabilities +${added.join(",")}`,
+        severity: "high",
+        message: `plugin ${id}: new capabilities ${added.join(", ")}`,
+      });
+    }
+  }
+  for (const id of Object.keys(locked.plugins)) {
+    if (current.plugins[id] === undefined) {
+      drift.push({
+        asset: "plugin",
+        id,
+        change: "removed",
+        severity: "low",
+        message: `plugin ${id} removed`,
+      });
+    }
+  }
+
+  for (const [id, asset] of Object.entries(current.mcp)) {
+    const before = locked.mcp[id];
+    if (before === undefined) {
+      drift.push({
+        asset: "mcp",
+        id,
+        change: "added",
+        severity: "high",
+        message: `new MCP server ${id}`,
+      });
+      continue;
+    }
+    if (before.configHash !== asset.configHash) {
+      drift.push({
+        asset: "mcp",
+        id,
+        change: "changed",
+        field: "config",
+        severity: "medium",
+        message: `MCP server ${id}: command, URL or environment changed`,
+      });
+    }
+    if (!compareTools) continue;
+    const beforeTools = before.tools ?? {};
+    const currentTools = asset.tools ?? {};
+    for (const [tool, toolAsset] of Object.entries(currentTools)) {
+      const previous = beforeTools[tool];
+      if (previous === undefined) {
+        drift.push({
+          asset: "mcp-tool",
+          id: tool,
+          parent: id,
+          change: "added",
+          severity: "high",
+          message: `MCP server ${id}: new tool ${tool}${(toolAsset.suspicious ?? []).length > 0 ? ` [suspicious: ${(toolAsset.suspicious ?? []).join(", ")}]` : ""}`,
+        });
+        continue;
+      }
+      const fields: string[] = [];
+      if (previous.descriptionHash !== toolAsset.descriptionHash) fields.push("description");
+      if (previous.inputHash !== toolAsset.inputHash) fields.push("input schema");
+      if (fields.length > 0 || previous.descriptorHash !== toolAsset.descriptorHash) {
+        drift.push({
+          asset: "mcp-tool",
+          id: tool,
+          parent: id,
+          change: "changed",
+          field: fields.join(", ") || "descriptor",
+          severity: "high",
+          message: `MCP server ${id}: tool ${tool} changed (${fields.join(", ") || "descriptor"})${(toolAsset.suspicious ?? []).length > 0 ? ` [suspicious: ${(toolAsset.suspicious ?? []).join(", ")}]` : ""}`,
+        });
+      }
+    }
+    for (const tool of Object.keys(beforeTools)) {
+      if (currentTools[tool] === undefined) {
+        drift.push({
+          asset: "mcp-tool",
+          id: tool,
+          parent: id,
+          change: "removed",
+          severity: "medium",
+          message: `MCP server ${id}: tool ${tool} removed`,
+        });
+      }
+    }
+  }
+  for (const id of Object.keys(locked.mcp)) {
+    if (current.mcp[id] === undefined) {
+      drift.push({
+        asset: "mcp",
+        id,
+        change: "removed",
+        severity: "medium",
+        message: `MCP server ${id} removed`,
+      });
+    }
+  }
+
+  for (const [id, asset] of Object.entries(current.skills)) {
+    const before = locked.skills[id];
+    if (before === undefined) {
+      drift.push({
+        asset: "skill",
+        id,
+        change: "added",
+        severity: "high",
+        message: `new skill ${id}`,
+      });
+      continue;
+    }
+    if (before.truncated === true || asset.truncated === true) {
+      drift.push({
+        asset: "skill",
+        id,
+        change: "changed",
+        field: "hash incomplete",
+        severity: "high",
+        message: `skill ${id}: directory too large to hash completely; inspect manually`,
+      });
+      continue;
+    }
+    if (
+      before.contentHash !== asset.contentHash ||
+      before.path !== asset.path ||
+      before.directoryHash !== asset.directoryHash
+    ) {
+      const field =
+        before.contentHash !== asset.contentHash
+          ? "content"
+          : before.path !== asset.path
+            ? "path"
+            : "files";
+      drift.push({
+        asset: "skill",
+        id,
+        change: "changed",
+        field,
+        severity: "high",
+        message: `skill ${id}: ${field} changed${(asset.suspicious ?? []).length > 0 ? ` [suspicious: ${(asset.suspicious ?? []).join(", ")}]` : ""}`,
+      });
+    }
+  }
+  for (const id of Object.keys(locked.skills)) {
+    if (current.skills[id] === undefined) {
+      drift.push({
+        asset: "skill",
+        id,
+        change: "removed",
+        severity: "low",
+        message: `skill ${id} removed`,
+      });
+    }
+  }
+
+  return drift.sort((a, b) => a.asset.localeCompare(b.asset) || a.id.localeCompare(b.id));
+}
+
+export function audit(
+  locked: Assets | undefined,
+  current: Assets,
+  warnings: readonly string[],
+  compareTools = true
+): AuditResult {
+  if (locked === undefined) {
+    return { locked: false, ok: true, drift: [], warnings, assets: current };
+  }
+  const drift = diffAssets(locked, current, compareTools);
+  return {
+    locked: true,
+    ok: drift.length === 0,
+    drift,
+    warnings,
+    assets: current,
+    lockedAssets: locked,
+  };
+}
+
+export function formatDrift(drift: readonly DriftEntry[]): string {
+  if (drift.length === 0) return "no drift";
+  return drift
+    .map((entry) => {
+      const icon = entry.change === "added" ? "+" : entry.change === "removed" ? "-" : "~";
+      return `${icon} [${entry.severity}] ${entry.message}`;
+    })
+    .join("\n");
+}
+
+export function severityCounts(drift: readonly DriftEntry[]): Record<string, number> {
+  const output: Record<string, number> = { high: 0, medium: 0, low: 0 };
+  for (const entry of drift) output[entry.severity] = (output[entry.severity] ?? 0) + 1;
+  return output;
+}

package/src/options.ts

@@ -0,0 +1,55 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import type { AssetKind, Options } from "./types.ts";
+
+const DEFAULTS = {
+  lockfile: "opencode.lock.json",
+  mode: "warn" as const,
+  include: ["plugins", "mcp", "skills"] as readonly AssetKind[],
+  ignore: [] as readonly string[],
+  includeGlobal: false,
+};
+
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+export function expandPath(value: string, directory: string, home = homedir()): string {
+  let output = value;
+  if (output === "~") output = home;
+  else if (output.startsWith("~/")) output = resolve(home, output.slice(2));
+  return isAbsolute(output) ? resolve(output) : resolve(directory, output);
+}
+
+export function parseOptions(raw: unknown, directory: string, home = homedir()): Options {
+  const input = record(raw);
+  const include = stringArray(input.include).filter((entry): entry is AssetKind =>
+    ["plugins", "mcp", "skills"].includes(entry)
+  );
+  const lockfile =
+    typeof input.lockfile === "string" && input.lockfile.trim().length > 0
+      ? expandPath(input.lockfile, directory, home)
+      : resolve(directory, DEFAULTS.lockfile);
+  const trace =
+    typeof input.trace === "string" && input.trace.trim().length > 0
+      ? expandPath(input.trace, directory, home)
+      : undefined;
+  return {
+    lockfile,
+    mode: input.mode === "enforce" ? "enforce" : "warn",
+    include: include.length > 0 ? include : DEFAULTS.include,
+    ignore: stringArray(input.ignore),
+    includeGlobal: input.includeGlobal === true,
+    trace,
+  };
+}