@gmickel/gno 1.28.0 → 1.29.0

package/src/cli/commands/collection/policy.ts

@@ -0,0 +1,126 @@
+/** Collection egress policy management commands. */
+
+import type { EgressPolicy } from "../../../config/types";
+import type {
+  EgressAction,
+  EgressContentClass,
+  EgressDestinationZone,
+} from "../../../core/egress-policy";
+
+import { loadConfig } from "../../../config";
+import { projectCollectionEgressPolicy } from "../../../core/collection-egress-policy-projection";
+import { CollectionEgressPolicyService } from "../../../core/collection-egress-policy-service";
+import { applyConfigChange } from "../../../core/config-mutation";
+import { CliError } from "../../errors";
+import { initStore } from "../shared";
+
+interface PolicyOptions {
+  configPath?: string;
+  indexName?: string;
+}
+
+const writeJson = (value: unknown): void => {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+};
+
+export const collectionPolicyGet = async (
+  name: string,
+  options: PolicyOptions = {}
+): Promise<void> => {
+  const loaded = await loadConfig(options.configPath);
+  if (!loaded.ok) throw new CliError("RUNTIME", loaded.error.message);
+  const state = new CollectionEgressPolicyService({
+    getConfig: () => loaded.value,
+  }).get(name);
+  if (!state.ok) throw new CliError("VALIDATION", state.error);
+  writeJson(state.value);
+};
+
+export const collectionPolicySet = async (
+  name: string,
+  policy: EgressPolicy,
+  options: PolicyOptions & { confirmRelaxation?: string } = {}
+): Promise<void> => {
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+  });
+  if (!initialized.ok) throw new CliError("RUNTIME", initialized.error);
+  let config = initialized.config;
+  try {
+    const currentResult = new CollectionEgressPolicyService({
+      getConfig: () => config,
+    }).get(name);
+    const service = new CollectionEgressPolicyService({
+      getConfig: () => config,
+      mutateConfig: async (mutate) => {
+        const result = await applyConfigChange(
+          {
+            store: initialized.store,
+            configPath: initialized.actualConfigPath,
+            onConfigUpdated: (next) => {
+              config = next;
+            },
+            projectStore: (store, next) =>
+              projectCollectionEgressPolicy(store, next, name),
+          },
+          mutate
+        );
+        return result;
+      },
+    });
+    const result = await service.set({
+      collection: name,
+      policy,
+      confirmation:
+        currentResult.ok && options.confirmRelaxation
+          ? {
+              collection: currentResult.value.collection,
+              currentPolicy: currentResult.value.effectivePolicy,
+              currentRevision: Number(options.confirmRelaxation),
+              targetPolicy: policy,
+              acknowledged: true,
+            }
+          : undefined,
+    });
+    if (!result.ok) {
+      throw new CliError("VALIDATION", result.error, {
+        details: { policyCode: result.code },
+      });
+    }
+    writeJson(result.value);
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+export const collectionPolicyCheck = async (
+  input: {
+    collections?: string[];
+    action: EgressAction;
+    destinationZone: EgressDestinationZone;
+    contentClass: EgressContentClass;
+    authenticated: boolean;
+    authorized: boolean;
+    partial?: boolean;
+  },
+  options: PolicyOptions = {}
+): Promise<void> => {
+  const loaded = await loadConfig(options.configPath);
+  if (!loaded.ok) throw new CliError("RUNTIME", loaded.error.message);
+  const result = new CollectionEgressPolicyService({
+    getConfig: () => loaded.value,
+  }).explain({
+    collections: input.collections,
+    action: input.action,
+    destinationZone: input.destinationZone,
+    caller: {
+      authenticated: input.authenticated,
+      operationAuthorized: input.authorized,
+    },
+    contentClass: input.contentClass,
+    partialResults: input.partial ? "explicit" : "deny",
+  });
+  if (!result.ok) throw new CliError("VALIDATION", result.error);
+  writeJson(result.value);
+};

package/src/cli/commands/context-build.ts

@@ -149,7 +149,11 @@ export const contextBuild = async (
       const progress = showProgress
         ? createThrottledProgressRenderer(createProgressRenderer())
         : undefined;
+      const egressCollections = options.collections?.length
+        ? options.collections
+        : ("all" as const);
       const embedResult = await llm.createEmbeddingPort(embedUri, {
+        egressCollections,
         policy,
         onProgress: progress ? (value) => progress("embed", value) : undefined,
       });
@@ -165,6 +169,7 @@ export const contextBuild = async (
         }
       }
       const rerankResult = await llm.createRerankPort(rerankUri, {
+        egressCollections,
         policy,
         onProgress: progress ? (value) => progress("rerank", value) : undefined,
       });

package/src/cli/commands/daemon.ts

@@ -3,6 +3,11 @@ import type { HttpGatewayOverrides } from "../../mcp/http-security";
 import type { BackgroundRuntimeResult } from "../../serve/background-runtime";
 import type { ResidentRuntime } from "../../serve/resident-runtime";
 
+import {
+  enforceCollectionEgress,
+  EGRESS_DENIED_MESSAGE,
+  EgressDeniedError,
+} from "../../core/egress-enforcement";
 import {
   DEFAULT_HTTP_GATEWAY_PORT,
   isHttpGatewayLoopbackBind,
@@ -42,6 +47,40 @@ function formatCollectionSyncSummary(result: CollectionSyncResult): string {
   return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors`;
 }
 
+export const authorizeDaemonStatus = async (
+  runtime: ResidentRuntime,
+  gateway: Awaited<ReturnType<typeof createMcpHttpGateway>>,
+  request: Request,
+  server: Parameters<typeof gateway.route>[1]
+): Promise<Response> => {
+  const authorization = await gateway.security.authorize(request, server);
+  if (!authorization.ok) return authorization.response;
+  try {
+    enforceCollectionEgress({
+      collections: runtime.config.collections,
+      action: "serve",
+      destinationZone: authorization.value.peerClassification.zone,
+      caller: {
+        authenticated: authorization.value.authenticated,
+        operationAuthorized: true,
+      },
+      contentClass: "metadata",
+    });
+    return handleResidentStatus(() => runtime.getStatus());
+  } catch (error) {
+    if (!(error instanceof EgressDeniedError)) throw error;
+    return Response.json(
+      {
+        error: "EGRESS_DENIED",
+        message: EGRESS_DENIED_MESSAGE,
+        reason: error.decision.reason,
+        audit: error.decision.audit,
+      },
+      { status: 403 }
+    );
+  }
+};
+
 export function handleDaemonAppStatus(
   runtime: ResidentRuntime,
   host: string
@@ -161,9 +200,12 @@ export async function daemon(
             ),
         },
         "/api/resident/status": {
-          GET: () =>
-            handleResidentStatus(() =>
-              (runtime as ResidentRuntime).getStatus()
+          GET: (request, peerServer) =>
+            authorizeDaemonStatus(
+              runtime as ResidentRuntime,
+              gateway as Awaited<ReturnType<typeof createMcpHttpGateway>>,
+              request,
+              peerServer
             ),
         },
       },

package/src/cli/commands/egress-audit.ts

@@ -0,0 +1,68 @@
+/** Local, content-free egress audit management commands. */
+
+import { EgressAuditService } from "../../core/egress-audit";
+import { CliError } from "../errors";
+import { initStore } from "./shared";
+
+interface AuditOptions {
+  configPath?: string;
+  indexName?: string;
+}
+
+const run = async (
+  options: AuditOptions,
+  operation: (service: EgressAuditService) => Promise<unknown>
+): Promise<void> => {
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) throw new CliError("RUNTIME", initialized.error);
+  try {
+    const result = await operation(new EgressAuditService(initialized.store));
+    if (
+      typeof result === "object" &&
+      result !== null &&
+      "ok" in result &&
+      !(result as { ok: boolean }).ok
+    ) {
+      const failure = result as {
+        ok: false;
+        error: { code: string; message: string };
+      };
+      throw new CliError("RUNTIME", failure.error.message, {
+        details: { auditCode: failure.error.code },
+      });
+    }
+    const value =
+      typeof result === "object" && result !== null && "value" in result
+        ? (result as { value: unknown }).value
+        : result;
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+export const egressAuditList = (
+  input: { limit?: number; cursor?: string },
+  options: AuditOptions = {}
+): Promise<void> => run(options, (service) => service.list(input));
+
+export const egressAuditShow = (
+  auditId: string,
+  options: AuditOptions = {}
+): Promise<void> => run(options, (service) => service.show(auditId));
+
+export const egressAuditStatus = (options: AuditOptions = {}): Promise<void> =>
+  run(options, (service) => service.status());
+
+export const egressAuditDelete = (
+  auditId: string,
+  options: AuditOptions = {}
+): Promise<void> => run(options, (service) => service.delete(auditId));
+
+export const egressAuditPurge = (options: AuditOptions = {}): Promise<void> =>
+  run(options, (service) => service.purge());

package/src/cli/commands/embed.ts

@@ -492,6 +492,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       }
       await llm.getManager().dispose(modelUri);
       const recreated = await llm.createEmbeddingPort(modelUri, {
+        egressCollections: options.collection ? [options.collection] : "all",
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("embed", progress)
@@ -508,6 +509,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       return { ok: true as const, value: recreated.value };
     };
     const embedResult = await llm.createEmbeddingPort(modelUri, {
+      egressCollections: options.collection ? [options.collection] : "all",
       policy,
       onProgress: downloadProgress
         ? (progress) => downloadProgress("embed", progress)

package/src/cli/commands/query.ts

@@ -195,6 +195,9 @@ export async function query(
     }
     traceSession = traceStart.value ?? undefined;
     const llm = new LlmAdapter(config);
+    const egressCollections = options.collection
+      ? [options.collection]
+      : ("all" as const);
 
     // Resolve download policy from env/flags
     const globals = getGlobals();
@@ -210,6 +213,7 @@ export async function query(
 
     // Create embedding port (for vector search)
     const embedResult = await llm.createEmbeddingPort(embedUri, {
+      egressCollections,
       policy,
       onProgress: downloadProgress
         ? (progress) => downloadProgress("embed", progress)
@@ -223,6 +227,7 @@ export async function query(
     // Skip when structured query modes are provided.
     if (expandUri) {
       const genResult = await llm.createExpansionPort(expandUri, {
+        egressCollections,
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("expand", progress)
@@ -236,6 +241,7 @@ export async function query(
     // Create rerank port - optional
     if (rerankUri) {
       const rerankResult = await llm.createRerankPort(rerankUri, {
+        egressCollections,
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("rerank", progress)
@@ -354,12 +360,16 @@ export async function queryDiagnose(
     const shouldCreateAnyModel =
       shouldCreateEmbeddingPort || !options.noExpand || !options.noRerank;
     const llm = shouldCreateAnyModel ? new LlmAdapter(config) : null;
+    const egressCollections = options.collection
+      ? [options.collection]
+      : ("all" as const);
 
     const embedUri = shouldCreateEmbeddingPort
       ? resolveModelUri(config, "embed", options.embedModel, options.collection)
       : null;
     if (embedUri && llm) {
       const embedResult = await llm.createEmbeddingPort(embedUri, {
+        egressCollections,
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("embed", progress)
@@ -378,6 +388,7 @@ export async function queryDiagnose(
         options.collection
       );
       const genResult = await llm.createExpansionPort(expandUri, {
+        egressCollections,
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("expand", progress)
@@ -396,6 +407,7 @@ export async function queryDiagnose(
         options.collection
       );
       const rerankResult = await llm.createRerankPort(rerankUri, {
+        egressCollections,
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("rerank", progress)

package/src/cli/commands/replay.ts

@@ -91,16 +91,26 @@ export const traceReplay = async (
     const policy = resolveDownloadPolicy(process.env, {
       offline: options.offline,
     });
+    const egressCollections = "all" as const;
     if (embedUri) {
-      const created = await llm.createEmbeddingPort(embedUri, { policy });
+      const created = await llm.createEmbeddingPort(embedUri, {
+        egressCollections,
+        policy,
+      });
       if (created.ok) embedPort = created.value;
     }
     if (expandUri) {
-      const created = await llm.createExpansionPort(expandUri, { policy });
+      const created = await llm.createExpansionPort(expandUri, {
+        egressCollections,
+        policy,
+      });
       if (created.ok) expandPort = created.value;
     }
     if (rerankUri) {
-      const created = await llm.createRerankPort(rerankUri, { policy });
+      const created = await llm.createRerankPort(rerankUri, {
+        egressCollections,
+        policy,
+      });
       if (created.ok) rerankPort = created.value;
     }
     if (embedPort && embedUri) {

package/src/cli/commands/vsearch.ts

@@ -128,7 +128,9 @@ export async function vsearch(
 
     // Create LLM adapter for embeddings
     const llm = new LlmAdapter(config);
-    const embedResult = await llm.createEmbeddingPort(modelUri);
+    const embedResult = await llm.createEmbeddingPort(modelUri, {
+      egressCollections: options.collection ? [options.collection] : "all",
+    });
     if (!embedResult.ok) {
       await traceSession?.finish("failed");
       return { success: false, error: embedResult.error.message };

package/src/cli/program.ts

@@ -2105,6 +2105,129 @@ function wireManagementCommands(program: Command): void {
       });
     });
 
+  const collectionPolicyCmd = collectionCmd
+    .command("policy")
+    .description("Inspect and change collection egress policy");
+
+  collectionPolicyCmd
+    .command("get <name>")
+    .description("Show effective policy, source, and confirmation revision")
+    .action(async (name: string) => {
+      const { collectionPolicyGet } = await import("./commands/collection");
+      await collectionPolicyGet(name, { configPath: getGlobals().config });
+    });
+
+  collectionPolicyCmd
+    .command("set <name> <policy>")
+    .description("Set local_only, lan, or remote policy")
+    .option(
+      "--confirm-relaxation <current-revision>",
+      "confirm relaxation against the current policy revision"
+    )
+    .action(
+      async (
+        name: string,
+        policy: string,
+        cmdOpts: Record<string, unknown>
+      ) => {
+        if (!["local_only", "lan", "remote"].includes(policy)) {
+          throw new CliError(
+            "VALIDATION",
+            "Policy must be local_only, lan, or remote"
+          );
+        }
+        const { collectionPolicySet } = await import("./commands/collection");
+        await collectionPolicySet(
+          name,
+          policy as "local_only" | "lan" | "remote",
+          {
+            configPath: getGlobals().config,
+            confirmRelaxation: cmdOpts.confirmRelaxation as string | undefined,
+          }
+        );
+      }
+    );
+
+  collectionPolicyCmd
+    .command("check")
+    .description("Check or explain an exact egress decision without acting")
+    .requiredOption("--action <action>", "egress action")
+    .requiredOption(
+      "--destination <zone>",
+      "local_process, loopback, lan, remote"
+    )
+    .requiredOption("--content-class <class>", "content class")
+    .option(
+      "-c, --collection <name>",
+      "collection scope (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--authenticated", "caller authentication succeeded")
+    .option("--authorized", "operation authorization succeeded")
+    .option("--partial", "explicitly permit partial collection results")
+    .option(
+      "--explain-egress",
+      "return the same decision contract without performing an action"
+    )
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { collectionPolicyCheck } = await import("./commands/collection");
+      await collectionPolicyCheck(
+        {
+          collections: cmdOpts.collection as string[],
+          action: cmdOpts.action as Parameters<
+            typeof collectionPolicyCheck
+          >[0]["action"],
+          destinationZone: cmdOpts.destination as Parameters<
+            typeof collectionPolicyCheck
+          >[0]["destinationZone"],
+          contentClass: cmdOpts.contentClass as Parameters<
+            typeof collectionPolicyCheck
+          >[0]["contentClass"],
+          authenticated: Boolean(cmdOpts.authenticated),
+          authorized: Boolean(cmdOpts.authorized),
+          partial: Boolean(cmdOpts.partial),
+        },
+        { configPath: getGlobals().config }
+      );
+    });
+
+  const egressAuditCmd = program
+    .command("egress-audit")
+    .description("Manage local content-free egress audit receipts");
+  egressAuditCmd
+    .command("list")
+    .option("--limit <count>", "page size", Number)
+    .option("--cursor <cursor>", "opaque next-page cursor")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { egressAuditList } = await import("./commands/egress-audit");
+      await egressAuditList(
+        {
+          limit: cmdOpts.limit as number | undefined,
+          cursor: cmdOpts.cursor as string | undefined,
+        },
+        { configPath: getGlobals().config }
+      );
+    });
+  egressAuditCmd.command("show <audit-id>").action(async (auditId: string) => {
+    const { egressAuditShow } = await import("./commands/egress-audit");
+    await egressAuditShow(auditId, { configPath: getGlobals().config });
+  });
+  egressAuditCmd.command("status").action(async () => {
+    const { egressAuditStatus } = await import("./commands/egress-audit");
+    await egressAuditStatus({ configPath: getGlobals().config });
+  });
+  egressAuditCmd
+    .command("delete <audit-id>")
+    .action(async (auditId: string) => {
+      const { egressAuditDelete } = await import("./commands/egress-audit");
+      await egressAuditDelete(auditId, { configPath: getGlobals().config });
+    });
+  egressAuditCmd.command("purge").action(async () => {
+    const { egressAuditPurge } = await import("./commands/egress-audit");
+    await egressAuditPurge({ configPath: getGlobals().config });
+  });
+
   // context subcommands
   const contextCmd = program
     .command("context")

package/src/config/index.ts

@@ -59,6 +59,7 @@ export {
   CollectionSchema,
   type Config,
   ConfigSchema,
+  DEFAULT_EGRESS_POLICY,
   HttpGatewayConfigSchema,
   HttpGatewayLimitsSchema,
   CONTENT_TYPE_GRAPH_HINTS,
@@ -70,11 +71,19 @@ export {
   DEFAULT_EXCLUDES,
   DEFAULT_FTS_TOKENIZER,
   DEFAULT_PATTERN,
+  type EffectiveConfiguredEgressPolicy,
+  EGRESS_POLICIES,
+  EGRESS_POLICY_SOURCES,
+  type EgressPolicy,
+  EgressPolicySchema,
+  type EgressPolicySource,
+  EgressPolicySourceSchema,
   FTS_TOKENIZERS,
   type FtsTokenizer,
   getCollectionFromScope,
   isValidLanguageHint,
   parseScope,
+  resolveConfiguredEgressPolicy,
   type ProjectProfileBinding,
   ProjectProfileBindingSchema,
   type ScopeType,

package/src/config/types.ts

@@ -48,6 +48,28 @@ export type FtsTokenizer = (typeof FTS_TOKENIZERS)[number];
 /** Default FTS tokenizer - snowball english for multilingual stemming */
 export const DEFAULT_FTS_TOKENIZER: FtsTokenizer = "snowball english";
 
+/** Collection-owned boundary for where indexed content may travel. */
+export const EGRESS_POLICIES = ["local_only", "lan", "remote"] as const;
+export const EgressPolicySchema = z.enum(EGRESS_POLICIES);
+export type EgressPolicy = z.infer<typeof EgressPolicySchema>;
+
+/** Missing policy is always interpreted as the fail-closed local-only default. */
+export const DEFAULT_EGRESS_POLICY: EgressPolicy = "local_only";
+
+/** Provenance for an effective collection egress policy. */
+export const EGRESS_POLICY_SOURCES = [
+  "explicit",
+  "config_default",
+  "legacy_default",
+] as const;
+export const EgressPolicySourceSchema = z.enum(EGRESS_POLICY_SOURCES);
+export type EgressPolicySource = z.infer<typeof EgressPolicySourceSchema>;
+
+export interface EffectiveConfiguredEgressPolicy {
+  policy: EgressPolicy;
+  source: Extract<EgressPolicySource, "explicit" | "config_default">;
+}
+
 /**
  * BCP-47 language tag pattern (simplified, case-insensitive).
  * Matches: en, de, fr, zh-CN, zh-Hans, und, en-US, etc.
@@ -104,6 +126,18 @@ export const CollectionSchema = z.object({
     })
     .optional(),
 
+  /**
+   * Explicit collection egress boundary. Absence remains valid for legacy
+   * configs and resolves to local_only rather than relaxing access.
+   */
+  egressPolicy: EgressPolicySchema.optional(),
+
+  /**
+   * Durable monotonic token for egress policy/source changes. Legacy configs
+   * start at zero; guarded mutations advance it under the config write lock.
+   */
+  egressPolicyRevision: z.number().int().nonnegative().optional(),
+
   /** Optional per-collection model overrides */
   models: z
     .object({
@@ -133,6 +167,22 @@ export const CollectionSchema = z.object({
 export type Collection = z.infer<typeof CollectionSchema>;
 export type CollectionModelOverrides = NonNullable<Collection["models"]>;
 
+/** Resolve config input without erasing whether the user made an explicit choice. */
+export function resolveConfiguredEgressPolicy(
+  collection: Pick<Collection, "egressPolicy">
+): EffectiveConfiguredEgressPolicy {
+  if (collection.egressPolicy === undefined) {
+    return {
+      policy: DEFAULT_EGRESS_POLICY,
+      source: "config_default",
+    };
+  }
+  return {
+    policy: collection.egressPolicy,
+    source: "explicit",
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Project Affinity Input
 // ─────────────────────────────────────────────────────────────────────────────