@hamzaabili/opencode-integrity 0.0.0-stage → 0.1.1

package/index.ts

@@ -0,0 +1 @@
+export { default, plugin, server, VERSION } from "./src/index.ts";

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@hamzaabili/opencode-integrity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Lock what your OpenCode agent can load: MCP tool definitions, skills and plugins. Detect drift, tool poisoning and rug pulls at runtime. Zero runtime dependencies, V1+V2.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hamza-Abili",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-v1",
+    "opencode-v2",
+    "mcp",
+    "mcp-security",
+    "tool-poisoning",
+    "rug-pull",
+    "supply-chain",
+    "integrity",
+    "lockfile",
+    "skills",
+    "security"
+  ],
+  "homepage": "https://github.com/Hamza-Abili/opencode-integrity#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hamza-Abili/opencode-integrity.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Hamza-Abili/opencode-integrity/issues"
+  },
+  "main": "./index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "opencode-integrity": "./dist/cli.mjs"
+  },
+  "oc-plugin": [
+    "server"
+  ],
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "index.ts",
+    "dist/cli.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "bun test",
+    "build": "bun run scripts/build.ts",
+    "ci": "bun run lint && bun run typecheck && bun run test && bun run build && bun run smoke",
+    "smoke": "bun scripts/smoke.ts",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.6",
+    "@types/bun": "^1.4.4",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "bun": ">=1.1.0",
+    "opencode": ">=1.19.5 <2 || >=2.2.1"
+  }
+}

package/scripts/build.ts

@@ -0,0 +1,23 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const outdir = join(import.meta.dir, "..", "dist");
+await mkdir(outdir, { recursive: true });
+const result = await Bun.build({
+  entrypoints: [join(import.meta.dir, "..", "src", "cli.ts")],
+  outdir,
+  naming: "cli.mjs",
+  target: "node",
+  format: "esm",
+  minify: false,
+  sourcemap: "none",
+});
+if (!result.success) {
+  for (const log of result.logs) console.error(log);
+  process.exit(1);
+}
+const output = join(outdir, "cli.mjs");
+const code = await readFile(output, "utf8");
+await writeFile(output, code.replace(/^#![^\n]*\n/, "#!/usr/bin/env node\n"), "utf8");
+await chmod(output, 0o755);
+console.log(`built ${output}`);

package/scripts/smoke.ts

@@ -0,0 +1,39 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const directory = await mkdtemp(join(tmpdir(), "oi-smoke-"));
+const home = join(directory, "home");
+await mkdir(join(directory, ".opencode", "skills", "demo"), { recursive: true });
+await writeFile(
+  join(directory, "opencode.json"),
+  `${JSON.stringify(
+    {
+      mcp: {
+        demo: { type: "local", command: ["node", "server.mjs"], environment: { TOKEN: "secret" } },
+      },
+    },
+    null,
+    2
+  )}\n`
+);
+await writeFile(
+  join(directory, ".opencode", "skills", "demo", "SKILL.md"),
+  "---\nname: demo\ndescription: demo skill\n---\n# Demo\n"
+);
+
+const cli = join(import.meta.dir, "..", "src", "cli.ts");
+const run = (args: string[]) =>
+  Bun.spawn(["bun", cli, ...args], { stdout: "pipe", stderr: "pipe" });
+
+const lock = await run(["lock", "--directory", directory, "--home", home]);
+const lockOut = await new Response(lock.stdout).text();
+if ((await lock.exited) !== 0) throw new Error(`lock failed: ${lockOut}`);
+if (!(await Bun.file(join(directory, "opencode.lock.json")).exists()))
+  throw new Error("lockfile missing");
+
+const check = await run(["check", "--directory", directory, "--home", home]);
+const checkOut = await new Response(check.stdout).text();
+if ((await check.exited) !== 0) throw new Error(`check failed: ${checkOut}`);
+if (!checkOut.includes("Integrity OK")) throw new Error(`unexpected check output: ${checkOut}`);
+console.log("smoke ok (lock + clean check)");

package/src/assets.ts

@@ -0,0 +1,344 @@
+import type { Dirent } from "node:fs";
+import { readdir, realpath } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import type { PluginRef } from "./config.ts";
+import type { McpAsset, McpToolAsset, PluginAsset, SkillAsset } from "./types.ts";
+import {
+  detectCapabilities,
+  detectSuspicious,
+  hashDirectory,
+  hashObject,
+  hashText,
+  isDirectory,
+  isInside,
+  pathExists,
+  readJsonFileCapped,
+  readTextFileCapped,
+  sha256,
+  stableStringify,
+} from "./util.ts";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function secretKey(key: string): boolean {
+  return /(token|secret|password|api[-_]?key|authorization|cookie|credential)/i.test(key);
+}
+
+function redactValue(key: string, value: unknown): unknown {
+  return secretKey(key) ? "[redacted]" : value;
+}
+
+function redactRecord(value: unknown): Record<string, unknown> {
+  if (!isObject(value)) return {};
+  const output: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) output[key] = redactValue(key, entry);
+  return output;
+}
+
+function redactCommand(command: readonly string[]): string[] {
+  return command.map((entry) =>
+    entry.replace(/((?:token|secret|password|api[-_]?key)=)[^\s]+/gi, "$1[redacted]")
+  );
+}
+
+function sanitizeUrl(value: string): string {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return "[invalid-url]";
+  }
+}
+
+function packageJsonPath(root: string): string {
+  return join(root, "package.json");
+}
+
+async function walkUpToPackage(start: string): Promise<string | undefined> {
+  let current = resolve(start);
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (await pathExists(packageJsonPath(current))) return current;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return undefined;
+}
+
+/** Resolve a package or local plugin reference to its installed root. */
+export async function resolvePluginRoot(
+  ref: PluginRef,
+  directory: string,
+  home: string
+): Promise<string | undefined> {
+  const target = ref.localPath ?? ref.target;
+  if (isAbsolute(target) || target.startsWith(".") || target.startsWith("~/")) {
+    const expanded = target.startsWith("~")
+      ? resolve(home, target.slice(2))
+      : resolve(directory, target);
+    if (await isDirectory(expanded)) return expanded;
+    return await walkUpToPackage(dirname(expanded));
+  }
+  const direct = join(directory, "node_modules", target);
+  if (await isDirectory(direct)) return direct;
+  try {
+    const require = createRequire(join(directory, "package.json"));
+    const entry = require.resolve(target);
+    return await walkUpToPackage(dirname(entry));
+  } catch {
+    return undefined;
+  }
+}
+
+async function entryText(root: string, realRoot: string): Promise<string> {
+  const manifest = await readJsonFileCapped<Record<string, unknown>>(packageJsonPath(root));
+  const candidates = new Set<string>();
+  if (typeof manifest?.main === "string") candidates.add(manifest.main);
+  if (typeof manifest?.module === "string") candidates.add(manifest.module);
+  const exports = manifest?.exports;
+  if (typeof exports === "string") candidates.add(exports);
+  else if (isObject(exports)) {
+    for (const value of Object.values(exports)) {
+      if (typeof value === "string") candidates.add(value);
+      else if (isObject(value)) {
+        for (const nested of Object.values(value))
+          if (typeof nested === "string") candidates.add(nested);
+      }
+    }
+  }
+  candidates.add("index.ts");
+  candidates.add("index.js");
+  for (const candidate of candidates) {
+    const path = join(root, candidate);
+    if (!isInside(root, path)) continue;
+    const real = await realpath(path).catch(() => undefined);
+    if (real === undefined || !isInside(realRoot, real)) continue;
+    const text = await readTextFileCapped(real);
+    if (text !== undefined) return text;
+  }
+  return "";
+}
+
+export async function pluginAsset(
+  id: string,
+  ref: PluginRef,
+  directory: string,
+  home: string,
+  allowOutside = false
+): Promise<{ asset?: PluginAsset; warning?: string }> {
+  const root = await resolvePluginRoot(ref, directory, home);
+  if (root === undefined) {
+    return {
+      warning: `${id}: package not installed (${ref.target}); run the package manager first`,
+    };
+  }
+  const realRoot = await realpath(root).catch(() => root);
+  const realDirectory = await realpath(directory).catch(() => directory);
+  if (!allowOutside && !isInside(realDirectory, realRoot)) {
+    return { warning: `${id}: local plugin resolves outside the project and was ignored` };
+  }
+  const manifest = await readJsonFileCapped<Record<string, unknown>>(packageJsonPath(realRoot));
+  const version =
+    ref.version ?? (typeof manifest?.version === "string" ? manifest.version : undefined);
+  const content = await hashDirectory(root);
+  const text = await entryText(root, realRoot);
+  return {
+    asset: {
+      source: ref.target,
+      version,
+      packageHash: hashObject(manifest ?? {}),
+      contentHash: content.hash,
+      files: content.files,
+      bytes: content.bytes,
+      capabilities: detectCapabilities(text),
+      truncated: content.truncated,
+    },
+    warning: content.truncated ? `${id}: hash truncated at 5000 files / 50 MiB` : undefined,
+  };
+}
+
+async function skillFiles(root: string): Promise<string[]> {
+  const output: string[] = [];
+  async function walk(directory: string, depth: number): Promise<void> {
+    if (depth > 4) return;
+    let entries: Dirent[];
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) await walk(path, depth + 1);
+      else if (entry.isFile() && entry.name === "SKILL.md") output.push(path);
+    }
+  }
+  await walk(root, 0);
+  return output.sort();
+}
+
+function skillID(path: string, content: string): string {
+  const match = /^---\s*\n([\s\S]*?)\n---/.exec(content);
+  const name = match?.[1]?.match(/^name:\s*["']?([^"'\n]+)["']?/m)?.[1];
+  return (name ?? basename(dirname(path))).trim();
+}
+
+export async function scanSkills(
+  directory: string,
+  warnings: string[] = []
+): Promise<Record<string, SkillAsset>> {
+  const root = join(directory, ".opencode", "skills");
+  const output: Record<string, SkillAsset> = {};
+  for (const path of await skillFiles(root)) {
+    const content = await readTextFileCapped(path);
+    if (content === undefined) {
+      warnings.push(`${path}: skill too large or unreadable; not hashed`);
+      continue;
+    }
+    const directoryHash = await hashDirectory(dirname(path));
+    if (directoryHash.truncated)
+      warnings.push(`${path}: skill directory too large to hash completely`);
+    output[skillID(path, content)] = {
+      path: path.slice(directory.length + 1),
+      contentHash: hashText(content),
+      directoryHash: directoryHash.hash,
+      files: directoryHash.files,
+      bytes: directoryHash.bytes,
+      truncated: directoryHash.truncated,
+      suspicious: detectSuspicious(content),
+    };
+  }
+  return output;
+}
+
+export function mcpConfigAsset(_name: string, config: unknown): McpAsset | undefined {
+  if (!isObject(config)) return undefined;
+  const type =
+    typeof config.type === "string"
+      ? config.type
+      : typeof config.url === "string"
+        ? "remote"
+        : "local";
+  const transport = type === "remote" ? "remote" : "local";
+  if (config.disabled === true) return undefined;
+
+  const commandValue = config.command;
+  const command = Array.isArray(commandValue)
+    ? commandValue.filter((entry): entry is string => typeof entry === "string")
+    : typeof commandValue === "string"
+      ? commandValue.trim().split(/\s+/)
+      : [];
+  const environment = redactRecord(config.environment ?? config.env);
+  const headers = redactRecord(config.headers);
+  const canonical = {
+    type,
+    command: redactCommand(command),
+    cwd: typeof config.cwd === "string" ? config.cwd : undefined,
+    url: typeof config.url === "string" ? config.url : undefined,
+    environment,
+    headers,
+    codemode: config.codemode,
+  };
+  return {
+    transport,
+    configHash: hashObject(canonical),
+    command: command[0] === undefined ? undefined : basename(command[0]),
+    url: typeof config.url === "string" ? sanitizeUrl(config.url) : undefined,
+    envKeys: Object.keys(environment).sort(),
+    toolsSource: "none",
+  };
+}
+
+function toolCanonical(tool: Record<string, unknown>): unknown {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input: tool.input,
+    output: tool.output,
+    annotations: tool.annotations,
+  };
+}
+
+export function mcpToolAsset(tool: unknown): McpToolAsset | undefined {
+  if (!isObject(tool)) return undefined;
+  return {
+    descriptorHash: hashObject(toolCanonical(tool)),
+    descriptionHash: hashText(typeof tool.description === "string" ? tool.description : ""),
+    inputHash: hashObject(tool.input ?? {}),
+    suspicious: detectSuspicious(
+      `${typeof tool.name === "string" ? tool.name : ""}\n${typeof tool.description === "string" ? tool.description : ""}\n${stableStringify(tool.input ?? {})}`
+    ),
+  };
+}
+
+export function normalizeSkillPath(directory: string, path: string): string {
+  return isInside(directory, path) ? relative(directory, path) : path;
+}
+
+export async function skillAssetFromInfo(
+  skill: unknown,
+  directory?: string
+): Promise<[string, SkillAsset] | undefined> {
+  if (!isObject(skill) || typeof skill.id !== "string" || typeof skill.content !== "string") {
+    return undefined;
+  }
+  if (typeof skill.path === "string" && skill.path.startsWith("skill://")) return undefined;
+  if (Buffer.byteLength(skill.content, "utf8") > 2 * 1024 * 1024) return undefined;
+  const absolutePath = typeof skill.path === "string" ? skill.path : skill.id;
+  const path = directory === undefined ? absolutePath : normalizeSkillPath(directory, absolutePath);
+  const directoryHash = await hashDirectory(dirname(absolutePath));
+  return [
+    skill.id,
+    {
+      path,
+      contentHash: hashText(skill.content),
+      directoryHash: directoryHash.hash,
+      files: directoryHash.files,
+      bytes: directoryHash.bytes,
+      truncated: directoryHash.truncated,
+      suspicious: detectSuspicious(skill.content),
+    },
+  ];
+}
+
+export function pluginIDFromRuntime(plugin: unknown): string | undefined {
+  if (!isObject(plugin)) return undefined;
+  if (typeof plugin.id === "string") return plugin.id;
+  const source = plugin.source;
+  if (!isObject(source)) return undefined;
+  if (source.type === "local" && typeof source.path === "string") return source.path;
+  if (source.type === "package" && typeof source.target === "string") return source.target;
+  return undefined;
+}
+
+export function mcpToolsForServer(
+  tools: readonly unknown[],
+  server: string
+): Record<string, McpToolAsset> {
+  const output: Record<string, McpToolAsset> = {};
+  const normalized = server.replace(/[^A-Za-z0-9_-]/g, "_");
+  for (const value of tools) {
+    if (!isObject(value)) continue;
+    const id =
+      typeof value.id === "string" ? value.id : typeof value.name === "string" ? value.name : "";
+    if (id.length === 0) continue;
+    const namespace = isObject(value.options) ? value.options.namespace : undefined;
+    if (
+      namespace !== server &&
+      !id.startsWith(`${normalized}_`) &&
+      !id.startsWith(`mcp__${normalized}__`)
+    ) {
+      continue;
+    }
+    const asset = mcpToolAsset(value);
+    if (asset !== undefined) output[id] = asset;
+  }
+  return output;
+}
+
+export function stableAssetID(value: string): string {
+  return sha256(value).slice(0, 8);
+}

package/src/audit.ts

@@ -0,0 +1,129 @@
+import { mcpConfigAsset, pluginAsset, scanSkills } from "./assets.ts";
+import { loadGlobalMcp, loadProjectConfig } from "./config.ts";
+import { audit, formatDrift, severityCounts } from "./lockfile.ts";
+import type { AssetKind, Assets, AuditResult, DriftEntry, Lockfile, Options } from "./types.ts";
+import { ignored } from "./util.ts";
+
+export interface StaticAudit {
+  readonly assets: Assets;
+  readonly warnings: readonly string[];
+  readonly files: readonly string[];
+}
+
+export function filterAssets(assets: Assets, include: readonly AssetKind[]): Assets {
+  return {
+    plugins: include.includes("plugins") ? assets.plugins : {},
+    mcp: include.includes("mcp") ? assets.mcp : {},
+    skills: include.includes("skills") ? assets.skills : {},
+  };
+}
+
+export async function collectStaticAssets(
+  directory: string,
+  home: string,
+  options?: Pick<Options, "include" | "includeGlobal">
+): Promise<StaticAudit> {
+  const config = await loadProjectConfig(directory);
+  const warnings = [...config.warnings];
+  const plugins: Record<string, Assets["plugins"][string]> = {};
+  for (const ref of config.plugins) {
+    const id = ref.target;
+    const result = await pluginAsset(id, ref, directory, home);
+    if (result.asset !== undefined) plugins[id] = result.asset;
+    if (result.warning !== undefined) warnings.push(result.warning);
+  }
+  const mcp: Record<string, Assets["mcp"][string]> = {};
+  const mcpConfig =
+    options?.includeGlobal === true
+      ? { ...(await loadGlobalMcp(home)), ...config.mcp }
+      : config.mcp;
+  for (const [name, value] of Object.entries(mcpConfig)) {
+    const asset = mcpConfigAsset(name, value);
+    if (asset !== undefined) mcp[name] = asset;
+  }
+  const include = options?.include ?? ["plugins", "mcp", "skills"];
+  return {
+    assets: filterAssets({ plugins, mcp, skills: await scanSkills(directory) }, include),
+    warnings,
+    files: config.files,
+  };
+}
+
+/**
+ * Keep runtime-collected MCP tool descriptors when the server configuration did
+ * not change. A CLI lock must not silently erase the tool fingerprints that
+ * only OpenCode can observe.
+ */
+export function mergeRuntimeTools(current: Assets, previous?: Lockfile): Assets {
+  if (previous === undefined) return current;
+  const mcp: Record<string, Assets["mcp"][string]> = {};
+  for (const [name, asset] of Object.entries(current.mcp)) {
+    const old = previous.assets.mcp[name];
+    mcp[name] =
+      old !== undefined && old.configHash === asset.configHash && old.tools !== undefined
+        ? { ...asset, tools: old.tools, toolsSource: old.toolsSource ?? "runtime" }
+        : asset;
+  }
+  return { ...current, mcp };
+}
+
+export function filterIgnored(
+  drift: readonly DriftEntry[],
+  patterns: readonly string[]
+): DriftEntry[] {
+  if (patterns.length === 0) return [...drift];
+  return drift.filter((entry) => {
+    const id = entry.asset === "mcp-tool" ? `${entry.parent}:${entry.id}` : entry.id;
+    return !ignored(id, patterns) && !ignored(`${entry.asset}:${id}`, patterns);
+  });
+}
+
+export function buildAudit(
+  current: Assets,
+  previous: Lockfile | undefined,
+  warnings: readonly string[]
+): AuditResult {
+  return audit(previous?.assets, current, warnings);
+}
+
+export function describeAudit(result: AuditResult, verbose = false): string {
+  const lines: string[] = [];
+  if (!result.locked) {
+    lines.push("No lockfile found. This is an audit only.");
+  } else if (result.ok) {
+    lines.push("Integrity OK: no drift from opencode.lock.json.");
+  } else {
+    const counts = severityCounts(result.drift);
+    lines.push(
+      `Drift detected: ${result.drift.length} change(s) — ${counts.high ?? 0} high, ${counts.medium ?? 0} medium, ${counts.low ?? 0} low.`
+    );
+    lines.push(formatDrift(result.drift));
+  }
+  const pluginCount = Object.keys(result.assets.plugins).length;
+  const mcpCount = Object.keys(result.assets.mcp).length;
+  const toolCount = Object.values(result.assets.mcp).reduce(
+    (sum, asset) => sum + Object.keys(asset.tools ?? {}).length,
+    0
+  );
+  const skillCount = Object.keys(result.assets.skills).length;
+  lines.push(
+    `Assets: ${pluginCount} plugin(s), ${mcpCount} MCP server(s), ${toolCount} MCP tool(s), ${skillCount} skill(s).`
+  );
+  if (verbose) {
+    for (const [id, asset] of Object.entries(result.assets.plugins)) {
+      lines.push(
+        `  plugin ${id}${asset.version === undefined ? "" : `@${asset.version}`} ${asset.files ?? 0} files [${(asset.capabilities ?? []).join(", ") || "no detected capabilities"}]`
+      );
+    }
+    for (const [id, asset] of Object.entries(result.assets.mcp)) {
+      lines.push(`  mcp ${id} (${asset.transport}) ${asset.command ?? asset.url ?? ""}`);
+    }
+    for (const [id, asset] of Object.entries(result.assets.skills)) {
+      lines.push(
+        `  skill ${id} ${asset.bytes} bytes${(asset.suspicious ?? []).length > 0 ? ` suspicious: ${(asset.suspicious ?? []).join(", ")}` : ""}`
+      );
+    }
+  }
+  for (const warning of result.warnings) lines.push(`warning: ${warning}`);
+  return lines.join("\n");
+}