@gmickel/gno 1.12.3 → 1.13.0

package/src/core/activation-verifier.ts

@@ -0,0 +1,416 @@
+/**
+ * Deterministic, local-only retrieval activation verification.
+ *
+ * Probe terms exist only in memory. Persisted receipts contain a SHA-256 probe
+ * hash plus exact result identity, never the query, snippet, or passage.
+ */
+
+import type {
+  ActivationStageReceipt,
+  ActivationVerificationCode,
+  ActivationVerificationReceipt,
+  StorePort,
+  StoreResult,
+} from "../store/types";
+import type { EphemeralActivationProbePlan } from "./activation-probe-plan";
+
+import { err, ok } from "../store/types";
+import {
+  extractActivationProbeTerms,
+  fingerprintActivationIndex,
+} from "./activation-probe";
+import {
+  createEphemeralActivationProbePlan,
+  findEphemeralActivationProbeMatch,
+  populateEphemeralActivationProbePlan,
+  revalidateEphemeralActivationProbePlan,
+} from "./activation-probe-plan";
+import { persistActivationReceiptForKnownCollection } from "./activation-receipt-store";
+
+export {
+  extractActivationProbeTerms,
+  fingerprintActivationIndex,
+} from "./activation-probe";
+
+export type {
+  ActivationStageName,
+  ActivationStageReceipt,
+  ActivationStageStatus,
+  ActivationVerificationCode,
+  ActivationVerificationReceipt,
+} from "../store/types";
+
+const RECEIPT_SCHEMA_VERSION = "1.0" as const;
+const REUSABLE_NEGATIVE_CODES = new Set<ActivationVerificationCode>([
+  "no_documents",
+  "no_probe_term",
+  "index_out_of_sync",
+]);
+const MAX_VERIFICATION_ATTEMPTS = 2;
+const CONCURRENT_INDEX_CHANGE_MESSAGE =
+  "Activation index changed repeatedly during verification; retry";
+export interface ActivationVerifierOptions {
+  /** Re-run proof instead of reusing a current fingerprint-matched receipt. */
+  force?: boolean;
+  now?: () => Date;
+  monotonicNow?: () => number;
+  /** Precomputed, in-memory plan used to fingerprint-scope coalesced callers. */
+  plan?: EphemeralActivationProbePlan;
+}
+
+function elapsedMs(startedAt: number, monotonicNow: () => number): number {
+  return Math.max(0, Math.round(monotonicNow() - startedAt));
+}
+
+function completedStage(
+  status: "passed" | "failed" | "skipped",
+  startedAt: string | null,
+  completedAt: string,
+  latencyMs: number | null,
+  code?: ActivationVerificationCode
+): ActivationStageReceipt {
+  return {
+    status,
+    startedAt,
+    completedAt,
+    latencyMs,
+    ...(code ? { code } : {}),
+  };
+}
+
+function pendingStage(
+  status: "pending" | "skipped",
+  code: ActivationVerificationCode
+): ActivationStageReceipt {
+  return {
+    status,
+    startedAt: null,
+    completedAt: null,
+    latencyMs: null,
+    code,
+  };
+}
+
+function isReusableLexicalReceipt(
+  receipt: ActivationVerificationReceipt
+): boolean {
+  if (receipt.ready) {
+    return true;
+  }
+  const code = receipt.stages.index.code ?? receipt.stages.lexical.code;
+  return code !== undefined && REUSABLE_NEGATIVE_CODES.has(code);
+}
+
+function buildReceipt(input: {
+  collection: string;
+  fingerprint: string;
+  generatedAt: string;
+  index: ActivationStageReceipt;
+  lexical: ActivationStageReceipt;
+  probeHash?: string;
+  result?: { uri: string; sourceHash: string };
+}): ActivationVerificationReceipt {
+  const ready =
+    input.index.status === "passed" && input.lexical.status === "passed";
+  return {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    collection: input.collection,
+    fingerprint: input.fingerprint,
+    ready,
+    generatedAt: input.generatedAt,
+    stages: {
+      index: input.index,
+      lexical: input.lexical,
+      semantic: pendingStage("pending", "semantic_not_checked"),
+      connector: pendingStage("skipped", "connector_not_requested"),
+    },
+    evidence: {
+      ...(input.probeHash ? { probeHash: input.probeHash } : {}),
+      ...(input.result
+        ? {
+            resultUri: input.result.uri,
+            resultSourceHash: input.result.sourceHash,
+          }
+        : {}),
+    },
+  };
+}
+
+async function persistReceipt(
+  store: StorePort,
+  receipt: ActivationVerificationReceipt
+): Promise<StoreResult<ActivationVerificationReceipt>> {
+  return persistActivationReceiptForKnownCollection(store, receipt);
+}
+
+interface ActivationVerificationAttempt {
+  receipt: ActivationVerificationReceipt;
+  cached: boolean;
+}
+
+async function verifyLexicalActivationAttempt(
+  store: StorePort,
+  collection: string,
+  plan: EphemeralActivationProbePlan,
+  options: ActivationVerifierOptions
+): Promise<StoreResult<ActivationVerificationAttempt>> {
+  const now = options.now ?? (() => new Date());
+  const monotonicNow = options.monotonicNow ?? (() => performance.now());
+  const indexStartedAt = now().toISOString();
+  const indexStartedClock = monotonicNow();
+  const { activeDocuments, fingerprint } = plan;
+
+  if (!options.force) {
+    const current = await store.getActivationReceipt(collection, fingerprint);
+    if (!current.ok) {
+      return err(
+        current.error.code,
+        current.error.message,
+        current.error.cause
+      );
+    }
+    // Deterministic negatives are stable for this exact fingerprint. Query and
+    // result mismatches remain recoverable and are retried without a TTL.
+    if (current.value && isReusableLexicalReceipt(current.value)) {
+      return ok({ receipt: current.value, cached: true });
+    }
+  }
+
+  const indexCompletedAt = now().toISOString();
+  if (activeDocuments.length === 0) {
+    return ok({
+      cached: false,
+      receipt: buildReceipt({
+        collection,
+        fingerprint,
+        generatedAt: indexCompletedAt,
+        index: completedStage(
+          "failed",
+          indexStartedAt,
+          indexCompletedAt,
+          elapsedMs(indexStartedClock, monotonicNow),
+          "no_documents"
+        ),
+        lexical: completedStage(
+          "skipped",
+          null,
+          indexCompletedAt,
+          null,
+          "no_documents"
+        ),
+      }),
+    });
+  }
+
+  if (!plan.identity.ftsSynchronized) {
+    return ok({
+      cached: false,
+      receipt: buildReceipt({
+        collection,
+        fingerprint,
+        generatedAt: indexCompletedAt,
+        index: completedStage(
+          "failed",
+          indexStartedAt,
+          indexCompletedAt,
+          elapsedMs(indexStartedClock, monotonicNow),
+          "index_out_of_sync"
+        ),
+        lexical: completedStage(
+          "skipped",
+          null,
+          indexCompletedAt,
+          null,
+          "index_out_of_sync"
+        ),
+      }),
+    });
+  }
+
+  const indexStage = completedStage(
+    "passed",
+    indexStartedAt,
+    indexCompletedAt,
+    elapsedMs(indexStartedClock, monotonicNow)
+  );
+  const lexicalStartedAt = now().toISOString();
+  const lexicalStartedClock = monotonicNow();
+  const populatedPlan = await populateEphemeralActivationProbePlan(store, plan);
+  const matchResult = populatedPlan.ok
+    ? await findEphemeralActivationProbeMatch(store, populatedPlan.value)
+    : populatedPlan;
+  const completedAt = now().toISOString();
+
+  if (!matchResult.ok) {
+    return ok({
+      cached: false,
+      receipt: buildReceipt({
+        collection,
+        fingerprint,
+        generatedAt: completedAt,
+        index: indexStage,
+        lexical: completedStage(
+          "failed",
+          lexicalStartedAt,
+          completedAt,
+          elapsedMs(lexicalStartedClock, monotonicNow),
+          "index_query_failed"
+        ),
+      }),
+    });
+  }
+
+  const match = matchResult.value;
+  if (match.kind === "no_probe_term") {
+    return ok({
+      cached: false,
+      receipt: buildReceipt({
+        collection,
+        fingerprint,
+        generatedAt: completedAt,
+        index: indexStage,
+        lexical: completedStage(
+          "failed",
+          lexicalStartedAt,
+          completedAt,
+          elapsedMs(lexicalStartedClock, monotonicNow),
+          "no_probe_term"
+        ),
+      }),
+    });
+  }
+
+  if (match.kind === "matched") {
+    return ok({
+      cached: false,
+      receipt: buildReceipt({
+        collection,
+        fingerprint,
+        generatedAt: completedAt,
+        index: indexStage,
+        lexical: completedStage(
+          "passed",
+          lexicalStartedAt,
+          completedAt,
+          elapsedMs(lexicalStartedClock, monotonicNow)
+        ),
+        probeHash: match.value.probeHash,
+        result: {
+          uri: match.value.resultUri,
+          sourceHash: match.value.resultSourceHash,
+        },
+      }),
+    });
+  }
+
+  return ok({
+    cached: false,
+    receipt: buildReceipt({
+      collection,
+      fingerprint,
+      generatedAt: completedAt,
+      index: indexStage,
+      lexical: completedStage(
+        "failed",
+        lexicalStartedAt,
+        completedAt,
+        elapsedMs(lexicalStartedClock, monotonicNow),
+        "retrieval_mismatch"
+      ),
+      probeHash: match.probeHash,
+    }),
+  });
+}
+
+async function discardObsoleteLexicalReceipt(
+  store: StorePort,
+  collection: string,
+  currentFingerprint: string
+): Promise<StoreResult<void>> {
+  const current = await store.getActivationReceipt(
+    collection,
+    currentFingerprint
+  );
+  return current.ok
+    ? ok(undefined)
+    : err(current.error.code, current.error.message, current.error.cause);
+}
+
+/**
+ * Prove that one collection can retrieve a deterministic corpus-derived term.
+ * The verifier never loads embeddings or sends content outside the local store.
+ */
+export async function verifyLexicalActivation(
+  store: StorePort,
+  collection: string,
+  options: ActivationVerifierOptions = {}
+): Promise<StoreResult<ActivationVerificationReceipt>> {
+  const planResult =
+    options.plan?.collection === collection
+      ? ok(options.plan)
+      : await createEphemeralActivationProbePlan(store, collection, {
+          collectCandidates: false,
+        });
+  if (!planResult.ok) {
+    return planResult;
+  }
+  let plan = planResult.value;
+
+  for (let attempt = 0; attempt < MAX_VERIFICATION_ATTEMPTS; attempt += 1) {
+    const verification = await verifyLexicalActivationAttempt(
+      store,
+      collection,
+      plan,
+      options
+    );
+    if (!verification.ok) {
+      return verification;
+    }
+
+    const beforeAcceptance = await revalidateEphemeralActivationProbePlan(
+      store,
+      plan
+    );
+    if (!beforeAcceptance.ok) {
+      return beforeAcceptance;
+    }
+    if (!beforeAcceptance.value.stable) {
+      plan = beforeAcceptance.value.currentPlan;
+      continue;
+    }
+
+    if (verification.value.cached) {
+      return ok(verification.value.receipt);
+    }
+
+    // A configured collection may be checked before its first sync has created
+    // the store row. The persistence helper returns the bounded receipt without
+    // violating the receipt table's collection foreign key.
+    const persisted = await persistReceipt(store, verification.value.receipt);
+    if (!persisted.ok) {
+      return persisted;
+    }
+    const afterPersistence = await revalidateEphemeralActivationProbePlan(
+      store,
+      plan
+    );
+    if (!afterPersistence.ok) {
+      return afterPersistence;
+    }
+    if (afterPersistence.value.stable) {
+      return persisted;
+    }
+
+    plan = afterPersistence.value.currentPlan;
+  }
+
+  const cleanup = await discardObsoleteLexicalReceipt(
+    store,
+    collection,
+    plan.fingerprint
+  );
+  if (!cleanup.ok) {
+    return cleanup;
+  }
+  return err("INTERNAL", CONCURRENT_INDEX_CHANGE_MESSAGE);
+}

package/src/core/connector-environment.ts

@@ -0,0 +1,68 @@
+/** Audited environment contract for local MCP connector execution. */
+
+// node:path has no Bun equivalent for portable absolute-path validation.
+import { isAbsolute, normalize } from "node:path";
+
+export const CONNECTOR_WORKSPACE_ENV_KEYS = [
+  "GNO_DATA_DIR",
+  "GNO_CACHE_DIR",
+] as const;
+
+export type ConnectorWorkspaceEnvKey =
+  (typeof CONNECTOR_WORKSPACE_ENV_KEYS)[number];
+export type ConnectorWorkspaceEnvironment = Partial<
+  Record<ConnectorWorkspaceEnvKey, string>
+>;
+
+function hasControlCharacter(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint <= 31 || codePoint === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Accept no execution environment semantics except absolute data/cache roots.
+ * An absent environment is valid for legacy, manually configured entries.
+ */
+export function normalizeConnectorWorkspaceEnvironment(
+  input: unknown
+): ConnectorWorkspaceEnvironment | null {
+  if (input === undefined) {
+    return {};
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return null;
+  }
+  const prototype = Object.getPrototypeOf(input);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return null;
+  }
+
+  const record = input as Record<string, unknown>;
+  const allowed = new Set<string>(CONNECTOR_WORKSPACE_ENV_KEYS);
+  if (Object.keys(record).some((key) => !allowed.has(key))) {
+    return null;
+  }
+
+  const normalized: ConnectorWorkspaceEnvironment = {};
+  for (const key of CONNECTOR_WORKSPACE_ENV_KEYS) {
+    const value = record[key];
+    if (value === undefined) {
+      continue;
+    }
+    if (
+      typeof value !== "string" ||
+      !value ||
+      !isAbsolute(value) ||
+      hasControlCharacter(value)
+    ) {
+      return null;
+    }
+    normalized[key] = normalize(value);
+  }
+  return normalized;
+}

package/src/core/connector-policy.ts

@@ -0,0 +1,233 @@
+/** Security policy and remediation for connector activation verification. */
+
+// node:fs/promises realpath has no Bun equivalent for symlink-safe provenance.
+import { realpath } from "node:fs/promises";
+// node:path has no Bun equivalent for portable path identity checks.
+import { basename, isAbsolute } from "node:path";
+
+import type { ActivationVerificationCode } from "../store/types";
+
+import { isValidIndexName } from "../app/index-name";
+import { getCurrentGnoEntrypoint } from "./runtime-entrypoint";
+
+export type ConnectorVerificationCode = Extract<
+  ActivationVerificationCode,
+  | "connector_not_configured"
+  | "connector_probe_unavailable"
+  | "connector_unsupported_config"
+  | "connector_start_failed"
+  | "connector_timeout"
+  | "connector_missing_tools"
+  | "connector_status_failed"
+  | "connector_search_failed"
+  | "connector_result_mismatch"
+  | "target_runtime_unverifiable"
+>;
+
+export interface ConnectorCommandPolicyOptions {
+  /** Extra installer-resolved GNO entry paths; primarily for packaged runtimes. */
+  trustedGnoEntryPaths?: string[];
+}
+
+function isGnoExecutable(path: string): boolean {
+  const executable = basename(path).toLowerCase();
+  return (
+    executable === "gno" || executable === "gno.exe" || executable === "gno.cmd"
+  );
+}
+
+async function realpathOrNull(path: string): Promise<string | null> {
+  try {
+    return await realpath(path);
+  } catch {
+    return null;
+  }
+}
+
+async function resolveExecutableIdentity(
+  command: string
+): Promise<string | null> {
+  if (!isAbsolute(command)) {
+    return null;
+  }
+  return realpathOrNull(command);
+}
+
+async function trustedGnoIdentities(
+  options: ConnectorCommandPolicyOptions
+): Promise<Set<string>> {
+  // Conventional install paths are locators, not trust roots: symlinks resolve
+  // to this package entrypoint; standalone wrappers must be explicitly trusted.
+  const candidates = [
+    getCurrentGnoEntrypoint(),
+    ...(options.trustedGnoEntryPaths ?? []),
+  ];
+  const identities = new Set<string>();
+  for (const candidate of candidates) {
+    const identity = await realpathOrNull(candidate);
+    if (identity) {
+      identities.add(identity);
+    }
+  }
+  return identities;
+}
+
+async function hasTrustedGnoIdentity(
+  path: string,
+  trusted: Set<string>
+): Promise<boolean> {
+  const identity = await realpathOrNull(path);
+  return identity !== null && trusted.has(identity);
+}
+
+async function hasTrustedGnoExecutableIdentity(
+  command: string,
+  trusted: Set<string>
+): Promise<boolean> {
+  const identity = await resolveExecutableIdentity(command);
+  return identity !== null && trusted.has(identity);
+}
+
+const SAFE_GLOBAL_VALUE_FLAGS = ["--index", "--config"] as const;
+const CONTROL_CHARACTER_PATTERN = /\p{Cc}/u;
+
+function isSafeConfigPath(value: string): boolean {
+  return isAbsolute(value) && !CONTROL_CHARACTER_PATTERN.test(value);
+}
+
+function isSafeReadOnlyMcpArgs(args: string[]): boolean {
+  const seenFlags = new Set<string>();
+  let position = 0;
+  while (position < args.length) {
+    const argument = args[position];
+    if (argument === "mcp") {
+      const remainder = args.slice(position + 1);
+      return (
+        remainder.length === 0 ||
+        (remainder.length === 1 && remainder[0] === "serve")
+      );
+    }
+
+    const flag = SAFE_GLOBAL_VALUE_FLAGS.find(
+      (candidate) =>
+        argument === candidate || argument?.startsWith(`${candidate}=`)
+    );
+    if (!flag || seenFlags.has(flag)) {
+      return false;
+    }
+    seenFlags.add(flag);
+
+    if (argument === flag) {
+      const value = args[position + 1];
+      if (
+        !value ||
+        value.startsWith("-") ||
+        (flag === "--index" && !isValidIndexName(value)) ||
+        (flag === "--config" && !isSafeConfigPath(value))
+      ) {
+        return false;
+      }
+      position += 2;
+      continue;
+    }
+
+    const value = argument?.slice(flag.length + 1);
+    if (
+      !value ||
+      (flag === "--index" && !isValidIndexName(value)) ||
+      (flag === "--config" && !isSafeConfigPath(value))
+    ) {
+      return false;
+    }
+    position += 1;
+  }
+  return false;
+}
+
+/** Accept only provenance-verified direct GNO or Bun-to-local-GNO shapes. */
+export async function isSafeLocalGnoMcpCommand(
+  entry: { command: string; args: string[] },
+  options: ConnectorCommandPolicyOptions = {}
+): Promise<boolean> {
+  const commandName = basename(entry.command).toLowerCase();
+  const args = entry.args;
+  if (
+    !entry.command ||
+    !isAbsolute(entry.command) ||
+    args.length === 0 ||
+    args.includes("--enable-write") ||
+    commandName === "bunx" ||
+    commandName === "bunx.exe" ||
+    commandName === "npx" ||
+    commandName === "npx.cmd" ||
+    commandName === "npx.exe"
+  ) {
+    return false;
+  }
+
+  const trusted = await trustedGnoIdentities(options);
+  if (isGnoExecutable(entry.command)) {
+    return (
+      (await hasTrustedGnoExecutableIdentity(entry.command, trusted)) &&
+      isSafeReadOnlyMcpArgs(args)
+    );
+  }
+  if (commandName !== "bun" && commandName !== "bun.exe") {
+    return false;
+  }
+  if (args[0] === "x" || args[0] === "bunx") {
+    return false;
+  }
+  const [configuredBun, runtimeBun] = await Promise.all([
+    resolveExecutableIdentity(entry.command),
+    realpathOrNull(process.execPath),
+  ]);
+  if (!configuredBun || configuredBun !== runtimeBun) {
+    return false;
+  }
+  if (isGnoExecutable(args[0] ?? "")) {
+    return (
+      (await hasTrustedGnoIdentity(args[0] ?? "", trusted)) &&
+      isSafeReadOnlyMcpArgs(args.slice(1))
+    );
+  }
+  return (
+    args[0] === "run" &&
+    (await hasTrustedGnoIdentity(args[1] ?? "", trusted)) &&
+    isSafeReadOnlyMcpArgs(args.slice(2))
+  );
+}
+
+/** Stable, bounded remediation; never includes child output or corpus text. */
+export function getConnectorVerificationRemediation(
+  code: ConnectorVerificationCode,
+  target: string
+): string {
+  const label =
+    target
+      .replace(/[^\p{L}\p{N}._ -]/gu, "?")
+      .trim()
+      .slice(0, 80) || "connector";
+  switch (code) {
+    case "connector_not_configured":
+      return `Install or configure the ${label} connector, then retry verification.`;
+    case "target_runtime_unverifiable":
+      return `${label} exposes no safe read-only runtime verification hook; installation is present but execution is unverified.`;
+    case "connector_probe_unavailable":
+      return "Repair the local lexical activation proof before verifying the connector.";
+    case "connector_unsupported_config":
+      return `Replace the ${label} entry with a local read-only GNO MCP command.`;
+    case "connector_start_failed":
+      return `Check the configured ${label} GNO executable and local permissions.`;
+    case "connector_timeout":
+      return `Retry ${label} verification; inspect local MCP startup if it times out again.`;
+    case "connector_missing_tools":
+      return `Update the ${label} GNO MCP server so gno_status and gno_search are available.`;
+    case "connector_status_failed":
+      return `Run gno status locally and repair the index before retrying ${label}.`;
+    case "connector_search_failed":
+      return `Run a collection-scoped lexical search locally before retrying ${label}.`;
+    case "connector_result_mismatch":
+      return `Reindex the collection and retry ${label}; the connector did not return the expected source.`;
+  }
+}