@hamzaabili/opencode-integrity 0.0.0-stage → 0.1.0

package/src/policy.ts

@@ -0,0 +1,25 @@
+import type { Assets } from "./types.ts";
+
+export interface PolicyStatement {
+  readonly action: "mcp.use" | "skill.use" | "plugin.use";
+  readonly resource: string;
+  readonly effect: "allow";
+}
+
+/** Generate a native OpenCode allowlist from the locked asset names. */
+export function generatePolicy(assets: Assets): { policies: PolicyStatement[] } {
+  const policies: PolicyStatement[] = [];
+  for (const id of Object.keys(assets.mcp).sort()) {
+    policies.push({ action: "mcp.use", resource: id, effect: "allow" });
+  }
+  for (const id of Object.keys(assets.skills).sort()) {
+    policies.push({ action: "skill.use", resource: id, effect: "allow" });
+  }
+  for (const asset of Object.values(assets.plugins)) {
+    const resource = asset.source.startsWith(".")
+      ? asset.source
+      : asset.source.split("@").slice(0, 2).join("@");
+    policies.push({ action: "plugin.use", resource, effect: "allow" });
+  }
+  return { policies };
+}

package/src/runtime.ts

@@ -0,0 +1,213 @@
+import { dirname } from "node:path";
+import {
+  mcpConfigAsset,
+  mcpToolsForServer,
+  pluginAsset,
+  pluginIDFromRuntime,
+  skillAssetFromInfo,
+} from "./assets.ts";
+import { filterAssets, filterIgnored } from "./audit.ts";
+import { loadGlobalMcp, loadProjectConfig } from "./config.ts";
+import { audit, createLockfile, readLockfile, writeLockfile } from "./lockfile.ts";
+import type { Assets, AuditResult, Lockfile, Options } from "./types.ts";
+import { hashDirectory, isInside } from "./util.ts";
+import { VERSION as PLUGIN_VERSION } from "./version.ts";
+
+export interface RuntimeContext {
+  readonly app?: { readonly version?: string };
+  readonly plugin?: { list(): Promise<unknown> };
+  readonly mcp?: { list(): Promise<unknown> };
+  readonly skill?: { list(): Promise<unknown> };
+  readonly tool?: { list(): Promise<readonly unknown[]> };
+}
+
+interface RuntimeData {
+  readonly plugins: readonly unknown[];
+  readonly mcpNames: readonly string[];
+  readonly skills: readonly unknown[];
+  readonly tools: readonly unknown[];
+  readonly version?: string;
+}
+
+function dataArray(value: unknown): readonly unknown[] {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "object" && value !== null) {
+    const data = (value as { data?: unknown }).data;
+    if (Array.isArray(data)) return data;
+  }
+  return [];
+}
+
+function object(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+async function readRuntime(ctx: RuntimeContext, include: readonly string[]): Promise<RuntimeData> {
+  const plugins =
+    include.includes("plugins") && ctx.plugin !== undefined
+      ? dataArray(await ctx.plugin.list())
+      : [];
+  const mcp =
+    include.includes("mcp") && ctx.mcp !== undefined ? dataArray(await ctx.mcp.list()) : [];
+  const skills =
+    include.includes("skills") && ctx.skill !== undefined ? dataArray(await ctx.skill.list()) : [];
+  const tools =
+    include.includes("mcp") && ctx.tool !== undefined ? ((await ctx.tool.list()) ?? []) : [];
+  const mcpNames = mcp
+    .map((entry) =>
+      typeof object(entry).name === "string" ? (object(entry).name as string) : undefined
+    )
+    .filter((entry): entry is string => entry !== undefined);
+  return { plugins, mcpNames, skills, tools, version: ctx.app?.version };
+}
+
+export interface RuntimeSnapshot {
+  readonly assets: Assets;
+  readonly warnings: readonly string[];
+  readonly version?: string;
+}
+
+/** Collect the assets OpenCode actually loaded, including live MCP tool descriptors. */
+export async function collectRuntime(
+  ctx: RuntimeContext,
+  directory: string,
+  home: string,
+  options?: Pick<Options, "include" | "includeGlobal">
+): Promise<RuntimeSnapshot> {
+  const include = options?.include ?? ["plugins", "mcp", "skills"];
+  const runtime = await readRuntime(ctx, include);
+  const config = await loadProjectConfig(directory);
+  const includeGlobal = options?.includeGlobal === true;
+  const projectTargets = new Set(config.plugins.map((ref) => ref.target));
+  const warnings = [...config.warnings];
+  const plugins: Record<string, Assets["plugins"][string]> = {};
+
+  for (const entry of runtime.plugins) {
+    const id = pluginIDFromRuntime(entry);
+    if (id === undefined) continue;
+    const source = object(object(entry).source);
+    const ref =
+      source.type === "local" && typeof source.path === "string"
+        ? { target: source.path, localPath: source.path }
+        : source.type === "package" && typeof source.target === "string"
+          ? {
+              target: source.target,
+              version: typeof source.version === "string" ? source.version : undefined,
+            }
+          : undefined;
+    if (ref === undefined) continue;
+    const included =
+      includeGlobal ||
+      projectTargets.has(ref.target) ||
+      (source.type === "local" &&
+        typeof source.path === "string" &&
+        isInside(directory, source.path));
+    if (!included) continue;
+    const result = await pluginAsset(id, ref, directory, home, includeGlobal);
+    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 = includeGlobal ? { ...(await loadGlobalMcp(home)), ...config.mcp } : config.mcp;
+  for (const [name, value] of Object.entries(mcpConfig)) {
+    const asset = mcpConfigAsset(name, value);
+    if (asset === undefined) continue;
+    if (runtime.mcpNames.length > 0 && !runtime.mcpNames.includes(name)) continue;
+    const tools = mcpToolsForServer(runtime.tools, name);
+    mcp[name] = {
+      ...asset,
+      tools,
+      toolsSource: Object.keys(tools).length > 0 ? "runtime" : "none",
+    };
+  }
+
+  const skills: Record<string, Assets["skills"][string]> = {};
+  for (const entry of runtime.skills) {
+    const entryPath = typeof object(entry).path === "string" ? (object(entry).path as string) : "";
+    if (entryPath.startsWith("skill://")) continue;
+    if (!includeGlobal && !isInside(directory, entryPath)) continue;
+    const pair = await skillAssetFromInfo(entry, directory);
+    if (pair !== undefined) skills[pair[0]] = pair[1];
+  }
+
+  return {
+    assets: filterAssets({ plugins, mcp, skills }, include),
+    warnings,
+    version: runtime.version,
+  };
+}
+
+export interface RuntimeAudit extends AuditResult {
+  readonly snapshot: RuntimeSnapshot;
+  readonly lockfile?: Lockfile;
+}
+
+export async function inspectRuntime(
+  ctx: RuntimeContext,
+  options: Options,
+  directory: string,
+  home: string
+): Promise<RuntimeAudit> {
+  const snapshot = await collectRuntime(ctx, directory, home, options);
+  const lockfile = await readLockfile(options.lockfile);
+  const filteredLock =
+    lockfile === undefined ? undefined : filterAssets(lockfile.assets, options.include);
+  const result = audit(filteredLock, snapshot.assets, snapshot.warnings);
+  const drift = filterIgnored(result.drift, options.ignore);
+  return {
+    ...result,
+    drift,
+    ok: drift.length === 0,
+    snapshot,
+    lockfile,
+  };
+}
+
+export async function lockRuntime(
+  ctx: RuntimeContext,
+  options: Options,
+  directory: string,
+  home: string
+): Promise<{ lockfile: Lockfile; path: string; snapshot: RuntimeSnapshot }> {
+  const snapshot = await collectRuntime(ctx, directory, home, options);
+  const lockfile = createLockfile(snapshot.assets, snapshot.version, PLUGIN_VERSION);
+  await writeLockfile(options.lockfile, lockfile);
+  return { lockfile, path: options.lockfile, snapshot };
+}
+
+export function changedMCPServers(result: AuditResult): Set<string> {
+  return new Set(
+    result.drift
+      .filter((entry) => entry.asset === "mcp" || entry.asset === "mcp-tool")
+      .map((entry) => (entry.asset === "mcp-tool" ? entry.parent : entry.id))
+      .filter((entry): entry is string => entry !== undefined)
+  );
+}
+
+export async function skillDirectoryHashes(
+  ctx: RuntimeContext,
+  _directory: string
+): Promise<Map<string, { hash: string; truncated: boolean }>> {
+  const output = new Map<string, { hash: string; truncated: boolean }>();
+  if (ctx.skill === undefined) return output;
+  for (const entry of dataArray(await ctx.skill.list())) {
+    const value = object(entry);
+    const id = typeof value.id === "string" ? value.id : undefined;
+    const path = typeof value.path === "string" ? value.path : undefined;
+    if (id === undefined || path === undefined || path.startsWith("skill://")) continue;
+    const hash = await hashDirectory(dirname(path));
+    output.set(id, { hash: hash.hash, truncated: hash.truncated });
+  }
+  return output;
+}
+
+export function changedSkills(result: AuditResult): Set<string> {
+  return new Set(result.drift.filter((entry) => entry.asset === "skill").map((entry) => entry.id));
+}
+
+export function changedPlugins(result: AuditResult): Set<string> {
+  return new Set(result.drift.filter((entry) => entry.asset === "plugin").map((entry) => entry.id));
+}

package/src/sarif.ts

@@ -0,0 +1,71 @@
+import type { DriftEntry } from "./types.ts";
+
+const RULES = [
+  "plugin-changed",
+  "plugin-added",
+  "plugin-removed",
+  "mcp-changed",
+  "mcp-added",
+  "mcp-removed",
+  "mcp-tool-changed",
+  "mcp-tool-added",
+  "mcp-tool-removed",
+  "skill-changed",
+  "skill-added",
+  "skill-removed",
+  "lockfile-missing",
+] as const;
+
+function ruleID(entry: DriftEntry): string {
+  const suffix =
+    entry.asset === "mcp-tool" ? `mcp-tool-${entry.change}` : `${entry.asset}-${entry.change}`;
+  return `integrity/${RULES.includes(suffix as (typeof RULES)[number]) ? suffix : "plugin-changed"}`;
+}
+
+/** SARIF 2.1.0 for GitHub code scanning and other CI dashboards. */
+export function toSarif(
+  drift: readonly DriftEntry[],
+  version: string,
+  lockfile: string,
+  missingLockfile = false
+): unknown {
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "opencode-integrity",
+            informationUri: "https://github.com/Hamza-Abili/opencode-integrity",
+            version,
+            rules: RULES.map((id) => ({ id: `integrity/${id}` })),
+          },
+        },
+        results: [
+          ...(missingLockfile
+            ? [
+                {
+                  ruleId: "integrity/lockfile-missing",
+                  level: "error",
+                  message: { text: `no lockfile at ${lockfile}; run integrity lock` },
+                  locations: [{ physicalLocation: { artifactLocation: { uri: lockfile } } }],
+                },
+              ]
+            : []),
+          ...drift.map((entry) => ({
+            ruleId: ruleID(entry),
+            level:
+              entry.severity === "high"
+                ? "error"
+                : entry.severity === "medium"
+                  ? "warning"
+                  : "note",
+            message: { text: entry.message },
+            locations: [{ physicalLocation: { artifactLocation: { uri: lockfile } } }],
+          })),
+        ],
+      },
+    ],
+  };
+}

package/src/tool.ts

@@ -0,0 +1,53 @@
+import type { RuntimeAudit } from "./runtime.ts";
+
+export const STATUS_TOOL_NAME = "integrity_status";
+
+export const STATUS_TOOL_DESCRIPTION =
+  "Report OpenCode plugin, MCP tool and skill integrity against opencode.lock.json, including drift and detected capabilities.";
+
+export const STATUS_TOOL_INPUT = {
+  type: "object",
+  properties: {
+    format: {
+      type: "string",
+      enum: ["text", "json"],
+      description: "text for a readable report, json for machine-readable output",
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+export const LOCK_TOOL_NAME = "integrity_lock";
+
+export const LOCK_TOOL_DESCRIPTION =
+  "Write or refresh opencode.lock.json from the currently loaded plugins, MCP tool descriptors and skills. Ask the user before calling this.";
+
+export const LOCK_TOOL_INPUT = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+} as const;
+
+export const INTEGRITY_COMMAND = {
+  name: "integrity",
+  description: "Audit or lock plugins, MCP tools and skills (audit | lock | check)",
+} as const;
+
+export async function statusTool(
+  refresh: () => Promise<RuntimeAudit>,
+  input: unknown
+): Promise<{ content: string }> {
+  const format =
+    typeof input === "object" && input !== null && (input as { format?: unknown }).format === "json"
+      ? "json"
+      : "text";
+  const result = await refresh();
+  if (format === "json") return { content: JSON.stringify(result, null, 2) };
+  const lines = [
+    `opencode-integrity ${result.locked ? "locked" : "unlocked"} — ${result.ok ? "OK" : "DRIFT"}`,
+    `assets: ${Object.keys(result.assets.plugins).length} plugin(s), ${Object.keys(result.assets.mcp).length} MCP server(s), ${Object.keys(result.assets.skills).length} skill(s)`,
+  ];
+  for (const entry of result.drift) lines.push(`${entry.severity}: ${entry.message}`);
+  for (const warning of result.warnings) lines.push(`warning: ${warning}`);
+  return { content: lines.join("\n") };
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+export const SCHEMA_VERSION = 1 as const;
+
+export type AssetKind = "plugins" | "mcp" | "skills";
+
+export interface PluginAsset {
+  readonly source: string;
+  readonly version?: string;
+  readonly contentHash?: string;
+  readonly packageHash?: string;
+  readonly files?: number;
+  readonly bytes?: number;
+  readonly capabilities?: readonly string[];
+  readonly truncated?: boolean;
+}
+
+export interface McpToolAsset {
+  readonly descriptorHash: string;
+  readonly descriptionHash: string;
+  readonly inputHash: string;
+  readonly suspicious?: readonly string[];
+}
+
+export interface McpAsset {
+  readonly transport: "local" | "remote";
+  readonly configHash: string;
+  readonly command?: string;
+  readonly url?: string;
+  readonly envKeys?: readonly string[];
+  readonly tools?: Readonly<Record<string, McpToolAsset>>;
+  readonly toolsSource?: "runtime" | "none";
+}
+
+export interface SkillAsset {
+  readonly path: string;
+  readonly contentHash: string;
+  readonly directoryHash?: string;
+  readonly files?: number;
+  readonly bytes: number;
+  readonly truncated?: boolean;
+  readonly suspicious?: readonly string[];
+}
+
+export interface Assets {
+  readonly plugins: Readonly<Record<string, PluginAsset>>;
+  readonly mcp: Readonly<Record<string, McpAsset>>;
+  readonly skills: Readonly<Record<string, SkillAsset>>;
+}
+
+export interface Lockfile {
+  readonly schemaVersion: typeof SCHEMA_VERSION;
+  readonly generatedBy: string;
+  readonly opencode?: string;
+  readonly assets: Assets;
+}
+
+export type Change = "added" | "removed" | "changed";
+export type Severity = "high" | "medium" | "low";
+
+export interface DriftEntry {
+  readonly asset: "plugin" | "mcp" | "mcp-tool" | "skill";
+  readonly id: string;
+  readonly parent?: string;
+  readonly change: Change;
+  readonly field?: string;
+  readonly severity: Severity;
+  readonly message: string;
+}
+
+export interface AuditResult {
+  readonly locked: boolean;
+  readonly ok: boolean;
+  readonly drift: readonly DriftEntry[];
+  readonly warnings: readonly string[];
+  readonly assets: Assets;
+  readonly lockedAssets?: Assets;
+}
+
+export interface Options {
+  readonly lockfile: string;
+  readonly mode: "warn" | "enforce";
+  readonly include: readonly AssetKind[];
+  readonly ignore: readonly string[];
+  readonly includeGlobal: boolean;
+  readonly trace?: string;
+}
+
+export interface Host {
+  readonly directory: string;
+  readonly home: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly version?: string;
+  readonly status?: (message: string) => void;
+}
+
+/** Test seam: adapters fall back to the real home directory. */
+export interface AdapterEnvironment {
+  readonly home?: string;
+}
+
+export function emptyAssets(): Assets {
+  return { plugins: {}, mcp: {}, skills: {} };
+}