@gmickel/gno 1.28.0 → 1.29.1

package/src/core/egress-enforcement.ts

@@ -0,0 +1,264 @@
+/** Shared fail-closed enforcement helpers for content-transfer boundaries. */
+
+import type { Collection } from "../config/types";
+import type { StorePort } from "../store/types";
+import type {
+  EgressAction,
+  EgressCallerContext,
+  EgressContentClass,
+  EgressDecision,
+  EgressDestinationZone,
+} from "./egress-policy";
+import type { EgressLineage, EgressLineageInput } from "./egress-provenance";
+
+import { resolveConfiguredEgressPolicy } from "../config/types";
+import { EgressAuditService } from "./egress-audit";
+import { evaluateEgressPolicy } from "./egress-policy";
+import {
+  EgressProvenanceError,
+  resolveEgressLineage,
+} from "./egress-provenance";
+
+export const EGRESS_DENIED_MESSAGE =
+  "Operation blocked by collection egress policy";
+
+export class EgressDeniedError extends Error {
+  readonly code = "EGRESS_DENIED";
+  readonly decision: EgressDecision;
+
+  constructor(decision: EgressDecision) {
+    super(`${decision.code}: ${EGRESS_DENIED_MESSAGE}`);
+    this.name = "EgressDeniedError";
+    this.decision = decision;
+    this.stack = `${this.name}: ${this.message}`;
+  }
+
+  toJSON(): {
+    code: "EGRESS_DENIED";
+    message: string;
+    reason: EgressDecision["reason"];
+    audit: EgressDecision["audit"];
+  } {
+    return {
+      code: this.code,
+      message: EGRESS_DENIED_MESSAGE,
+      reason: this.decision.reason,
+      audit: this.decision.audit,
+    };
+  }
+}
+
+const collectionLineageInputs = (
+  collections: readonly Collection[]
+): readonly EgressLineageInput[] => {
+  try {
+    if (!Array.isArray(collections)) {
+      throw new EgressProvenanceError(
+        "INVALID_EGRESS_LINEAGE",
+        "Collection policy scope must be a readable dense bounded array"
+      );
+    }
+    const { length } = collections;
+    if (!Number.isSafeInteger(length) || length > 128) {
+      throw new EgressProvenanceError(
+        "INVALID_EGRESS_LINEAGE",
+        "Collection policy scope must be a readable dense bounded array"
+      );
+    }
+    const inputs: EgressLineageInput[] = [];
+    for (let index = 0; index < length; index += 1) {
+      if (!(index in collections)) {
+        throw new EgressProvenanceError(
+          "INVALID_EGRESS_LINEAGE",
+          "Collection policy scope must be a readable dense bounded array"
+        );
+      }
+      const collection: unknown = collections[index];
+      if (collection === null || typeof collection !== "object") {
+        throw new EgressProvenanceError(
+          "INVALID_EGRESS_LINEAGE",
+          "Collection policy scope contains an invalid collection"
+        );
+      }
+      const candidate = collection as Partial<Collection>;
+      const name = candidate.name;
+      const egressPolicy = candidate.egressPolicy;
+      const effective = resolveConfiguredEgressPolicy({ egressPolicy });
+      inputs.push({
+        collection: name as string,
+        policy: effective.policy,
+        source: effective.source,
+      });
+    }
+    return inputs;
+  } catch (error) {
+    if (error instanceof EgressProvenanceError) throw error;
+    throw new EgressProvenanceError(
+      "INVALID_EGRESS_LINEAGE",
+      "Collection policy scope could not be validated"
+    );
+  }
+};
+
+const resolveCollectionEgressLineage = (
+  collections: readonly Collection[],
+  names?: readonly string[]
+): EgressLineage =>
+  resolveEgressLineage(collectionLineageInputs(collections), names);
+
+export const collectionEgressStates = (
+  collections: readonly Collection[],
+  names?: readonly string[]
+) => {
+  return resolveCollectionEgressLineage(collections, names).sources;
+};
+
+export interface EnforceCollectionEgressInput {
+  collections: readonly Collection[];
+  collectionNames?: readonly string[];
+  action: EgressAction;
+  destinationZone: EgressDestinationZone;
+  caller: EgressCallerContext;
+  contentClass: EgressContentClass;
+}
+
+export interface MixedCollectionEgressPlan {
+  mode: "complete" | "partial";
+  sourceLineage: EgressLineage;
+  allowedCollections: string[];
+  omittedCollections: Array<{
+    collection: string;
+    reason: EgressDecision["reason"];
+  }>;
+  disclosure: null | {
+    code: "EGRESS_PARTIAL_RESULT";
+    omittedCount: number;
+    omittedCollections: string[];
+  };
+}
+
+/**
+ * Plan one mixed-source boundary. Denial is the default; partial emission
+ * requires an explicit caller opt-in and always discloses sorted omissions.
+ */
+export const planCollectionEgress = (
+  input: EnforceCollectionEgressInput & {
+    partialResults?: "deny" | "explicit";
+  }
+): MixedCollectionEgressPlan => {
+  const sourceLineage = resolveCollectionEgressLineage(
+    input.collections,
+    input.collectionNames
+  );
+  const aggregate = evaluateEgressPolicy({
+    collections: sourceLineage.sources,
+    action: input.action,
+    destination: { zone: input.destinationZone },
+    caller: input.caller,
+    contentClass: input.contentClass,
+  });
+  if (aggregate.allowed) {
+    return {
+      mode: "complete",
+      sourceLineage,
+      allowedCollections: sourceLineage.sources.map(
+        ({ collection }) => collection
+      ),
+      omittedCollections: [],
+      disclosure: null,
+    };
+  }
+  if (input.partialResults !== "explicit") {
+    throw new EgressDeniedError(aggregate);
+  }
+
+  const allowedCollections: string[] = [];
+  const omittedCollections: MixedCollectionEgressPlan["omittedCollections"] =
+    [];
+  for (const source of sourceLineage.sources) {
+    const perCollection = evaluateEgressPolicy({
+      collections: [source],
+      action: input.action,
+      destination: { zone: input.destinationZone },
+      caller: input.caller,
+      contentClass: input.contentClass,
+    });
+    if (perCollection.allowed) allowedCollections.push(source.collection);
+    else {
+      omittedCollections.push({
+        collection: source.collection,
+        reason: perCollection.reason,
+      });
+    }
+  }
+  if (allowedCollections.length === 0) {
+    throw new EgressDeniedError(aggregate);
+  }
+  return {
+    mode: "partial",
+    sourceLineage,
+    allowedCollections,
+    omittedCollections,
+    disclosure: {
+      code: "EGRESS_PARTIAL_RESULT",
+      omittedCount: omittedCollections.length,
+      omittedCollections: omittedCollections.map(
+        ({ collection }) => collection
+      ),
+    },
+  };
+};
+
+export const enforceCollectionEgress = (
+  input: EnforceCollectionEgressInput
+): EgressDecision => {
+  const plan = planCollectionEgress(input);
+  const decision = evaluateEgressPolicy({
+    collections: plan.sourceLineage.sources,
+    action: input.action,
+    destination: { zone: input.destinationZone },
+    caller: input.caller,
+    contentClass: input.contentClass,
+  });
+  if (!decision.allowed) throw new EgressDeniedError(decision);
+  return decision;
+};
+
+/** Enforce and durably record the content-free decision before transfer. */
+export const enforceCollectionEgressWithAudit = async (
+  input: EnforceCollectionEgressInput & { store: StorePort }
+): Promise<{ decision: EgressDecision; lineage: EgressLineage }> => {
+  const lineage = resolveCollectionEgressLineage(
+    input.collections,
+    input.collectionNames
+  );
+  let decision: EgressDecision;
+  let denied: EgressDeniedError | null = null;
+  try {
+    decision = enforceCollectionEgress(input);
+  } catch (error) {
+    if (!(error instanceof EgressDeniedError)) throw error;
+    decision = error.decision;
+    denied = error;
+  }
+  const recorded = await new EgressAuditService(input.store).record({
+    decision,
+    lineage,
+    contentClass: input.contentClass,
+  });
+  if (!recorded.ok) {
+    throw new Error(`Failed to record egress audit: ${recorded.error.code}`);
+  }
+  if (denied) throw denied;
+  return { decision, lineage };
+};
+
+export const maximumDestinationZoneForCollections = (
+  collections: readonly Collection[],
+  names?: readonly string[]
+): Exclude<EgressDestinationZone, "local_process"> => {
+  const states = collectionEgressStates(collections, names);
+  if (states.some(({ policy }) => policy === "local_only")) return "loopback";
+  if (states.some(({ policy }) => policy === "lan")) return "lan";
+  return "remote";
+};

package/src/core/egress-policy.ts

@@ -0,0 +1,440 @@
+import {
+  EGRESS_POLICIES,
+  EGRESS_POLICY_SOURCES,
+  type EgressPolicy,
+  type EgressPolicySource,
+} from "../config/types";
+
+export const EGRESS_ACTIONS = [
+  "retrieve",
+  "serve",
+  "publish",
+  "remote_inference",
+  "export",
+  "clip_write",
+] as const;
+export type EgressAction = (typeof EGRESS_ACTIONS)[number];
+
+export const EGRESS_DESTINATION_ZONES = [
+  "local_process",
+  "loopback",
+  "lan",
+  "remote",
+] as const;
+export type EgressDestinationZone = (typeof EGRESS_DESTINATION_ZONES)[number];
+
+/**
+ * Source and derived classes retain the same collection-owned policy.
+ * Transformation never declassifies indexed content.
+ */
+export const EGRESS_CONTENT_CLASSES = [
+  "source",
+  "snippet",
+  "metadata",
+  "attachment",
+  "embedding",
+  "capsule",
+  "audit_log",
+  "retrieval_trace",
+] as const;
+export type EgressContentClass = (typeof EGRESS_CONTENT_CLASSES)[number];
+
+/** Hard cap for one decision and its bounded audit projection. */
+export const EGRESS_MAX_COLLECTIONS = 64;
+
+export const EGRESS_REASON_CODES = [
+  "LOCAL_DESTINATION",
+  "LAN_POLICY_AUTHENTICATED",
+  "REMOTE_POLICY_AUTHENTICATED",
+  "INVALID_INPUT",
+  "NO_COLLECTION_POLICY",
+  "COLLECTION_LIMIT_EXCEEDED",
+  "INVALID_COLLECTION",
+  "UNKNOWN_ACTION",
+  "UNKNOWN_DESTINATION",
+  "ACTION_DESTINATION_MISMATCH",
+  "UNKNOWN_CONTENT_CLASS",
+  "UNKNOWN_POLICY",
+  "UNKNOWN_POLICY_SOURCE",
+  "INVALID_POLICY_SOURCE_PAIR",
+  "INVALID_CALLER",
+  "CALLER_NOT_AUTHORIZED",
+  "AUTHENTICATION_REQUIRED",
+  "POLICY_LOCAL_ONLY",
+  "POLICY_LAN_ONLY",
+] as const;
+export type EgressReasonCode = (typeof EGRESS_REASON_CODES)[number];
+
+export interface CollectionEgressState {
+  /** Stable configured collection identifier; never a filesystem path. */
+  collection: string;
+  policy: EgressPolicy;
+  source: EgressPolicySource;
+}
+
+export interface EgressCallerContext {
+  /**
+   * Transport or feature authentication succeeded. Network destinations
+   * always require this; policy cannot make authentication optional.
+   */
+  authenticated: boolean;
+  /**
+   * The surrounding authorization layer permits this operation. A false value
+   * narrows access even for a policy that would otherwise allow it.
+   */
+  operationAuthorized: boolean;
+}
+
+export interface EgressDestination {
+  zone: EgressDestinationZone;
+  /**
+   * Optional classifier inputs are deliberately excluded from decisions and
+   * audit metadata so hosts, provider names, and credentials cannot leak.
+   */
+  host?: string;
+  provider?: string;
+}
+
+export interface EgressEvaluationInput {
+  collections: readonly CollectionEgressState[];
+  action: EgressAction;
+  destination: EgressDestination;
+  caller: EgressCallerContext;
+  contentClass: EgressContentClass;
+}
+
+export interface EgressDecisionMetadata {
+  action: EgressAction | "unknown";
+  destinationZone: EgressDestinationZone | "unknown";
+  contentClass: EgressContentClass | "unknown";
+  collectionCount: number;
+  collections: readonly string[];
+  effectivePolicy: EgressPolicy | "unknown";
+  effectivePolicySource: EgressPolicySource | "mixed" | "unknown";
+  callerAuthenticated: boolean | null;
+  callerOperationAuthorized: boolean | null;
+}
+
+export interface EgressDecision {
+  allowed: boolean;
+  code: "EGRESS_ALLOWED" | "EGRESS_DENIED";
+  reason: EgressReasonCode;
+  audit: EgressDecisionMetadata;
+}
+
+export interface EgressPolicyPort {
+  evaluate(input: EgressEvaluationInput): EgressDecision;
+}
+
+interface RuntimeCollectionEgressState {
+  collection: unknown;
+  policy: unknown;
+  source: unknown;
+}
+
+interface EgressEvaluationSnapshot {
+  collections: RuntimeCollectionEgressState[];
+  action: unknown;
+  destinationZone: unknown;
+  callerAuthenticated: unknown;
+  callerOperationAuthorized: unknown;
+  contentClass: unknown;
+}
+
+type EgressSnapshotResult =
+  | { kind: "invalid" }
+  | { kind: "limit_exceeded" }
+  | { kind: "snapshot"; value: EgressEvaluationSnapshot };
+
+const ACTIONS = new Set<unknown>(EGRESS_ACTIONS);
+const DESTINATION_ZONES = new Set<unknown>(EGRESS_DESTINATION_ZONES);
+const CONTENT_CLASSES = new Set<unknown>(EGRESS_CONTENT_CLASSES);
+const POLICIES = new Set<unknown>(EGRESS_POLICIES);
+const POLICY_SOURCES = new Set<unknown>(EGRESS_POLICY_SOURCES);
+const COLLECTION_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+const POLICY_ORDER: Record<EgressPolicy, number> = {
+  local_only: 0,
+  lan: 1,
+  remote: 2,
+};
+
+const isAction = (value: unknown): value is EgressAction => ACTIONS.has(value);
+const isDestinationZone = (value: unknown): value is EgressDestinationZone =>
+  DESTINATION_ZONES.has(value);
+const isContentClass = (value: unknown): value is EgressContentClass =>
+  CONTENT_CLASSES.has(value);
+const isPolicy = (value: unknown): value is EgressPolicy => POLICIES.has(value);
+const isPolicySource = (value: unknown): value is EgressPolicySource =>
+  POLICY_SOURCES.has(value);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+function invalidInputAudit(): EgressDecisionMetadata {
+  return {
+    action: "unknown",
+    destinationZone: "unknown",
+    contentClass: "unknown",
+    collectionCount: 0,
+    collections: [],
+    effectivePolicy: "unknown",
+    effectivePolicySource: "unknown",
+    callerAuthenticated: null,
+    callerOperationAuthorized: null,
+  };
+}
+
+function limitExceededAudit(): EgressDecisionMetadata {
+  return {
+    ...invalidInputAudit(),
+    collectionCount: EGRESS_MAX_COLLECTIONS + 1,
+  };
+}
+
+/**
+ * Read untrusted object graphs once into bounded plain data. Any throwing
+ * getter or revoked proxy escapes to the evaluator's fixed fail-closed catch.
+ */
+function snapshotInput(input: unknown): EgressSnapshotResult {
+  if (!isRecord(input)) return { kind: "invalid" };
+
+  const rawCollections = input.collections;
+  if (!Array.isArray(rawCollections)) return { kind: "invalid" };
+  const collectionCount = rawCollections.length;
+  if (collectionCount > EGRESS_MAX_COLLECTIONS) {
+    return { kind: "limit_exceeded" };
+  }
+
+  const collections: RuntimeCollectionEgressState[] = [];
+  for (let index = 0; index < collectionCount; index += 1) {
+    const collection = rawCollections[index];
+    if (!isRecord(collection)) {
+      collections.push({
+        collection: undefined,
+        policy: undefined,
+        source: undefined,
+      });
+      continue;
+    }
+    collections.push({
+      collection: collection.collection,
+      policy: collection.policy,
+      source: collection.source,
+    });
+  }
+
+  const destination = input.destination;
+  const caller = input.caller;
+  return {
+    kind: "snapshot",
+    value: {
+      collections,
+      action: input.action,
+      destinationZone: isRecord(destination) ? destination.zone : undefined,
+      callerAuthenticated: isRecord(caller) ? caller.authenticated : undefined,
+      callerOperationAuthorized: isRecord(caller)
+        ? caller.operationAuthorized
+        : undefined,
+      contentClass: input.contentClass,
+    },
+  };
+}
+
+function snapshotAudit(
+  snapshot: EgressEvaluationSnapshot
+): EgressDecisionMetadata {
+  const collections = snapshot.collections
+    .map(({ collection }) =>
+      typeof collection === "string" && COLLECTION_NAME_PATTERN.test(collection)
+        ? collection
+        : "unknown"
+    )
+    .sort();
+  return {
+    action: isAction(snapshot.action) ? snapshot.action : "unknown",
+    destinationZone: isDestinationZone(snapshot.destinationZone)
+      ? snapshot.destinationZone
+      : "unknown",
+    contentClass: isContentClass(snapshot.contentClass)
+      ? snapshot.contentClass
+      : "unknown",
+    collectionCount: snapshot.collections.length,
+    collections,
+    effectivePolicy: "unknown",
+    effectivePolicySource: "unknown",
+    callerAuthenticated:
+      typeof snapshot.callerAuthenticated === "boolean"
+        ? snapshot.callerAuthenticated
+        : null,
+    callerOperationAuthorized:
+      typeof snapshot.callerOperationAuthorized === "boolean"
+        ? snapshot.callerOperationAuthorized
+        : null,
+  };
+}
+
+function decision(
+  allowed: boolean,
+  reason: EgressReasonCode,
+  audit: EgressDecisionMetadata
+): EgressDecision {
+  return {
+    allowed,
+    code: allowed ? "EGRESS_ALLOWED" : "EGRESS_DENIED",
+    reason,
+    audit,
+  };
+}
+
+function effectiveCollectionPolicy(
+  collections: readonly CollectionEgressState[]
+): {
+  policy: EgressPolicy;
+  source: EgressPolicySource | "mixed";
+} {
+  let policy: EgressPolicy = "remote";
+  for (const collection of collections) {
+    if (POLICY_ORDER[collection.policy] < POLICY_ORDER[policy]) {
+      policy = collection.policy;
+    }
+  }
+
+  const restrictiveSources = new Set(
+    collections
+      .filter((collection) => collection.policy === policy)
+      .map((collection) => collection.source)
+  );
+  const source =
+    restrictiveSources.size === 1
+      ? (restrictiveSources.values().next().value ?? "mixed")
+      : "mixed";
+  return { policy, source };
+}
+
+function actionAllowsDestination(
+  action: EgressAction,
+  destination: EgressDestinationZone
+): boolean {
+  switch (action) {
+    case "publish":
+      return destination === "remote";
+    case "remote_inference":
+      return destination !== "local_process";
+    case "serve":
+      return destination !== "local_process";
+    case "export":
+      return destination !== "loopback";
+    case "retrieve":
+    case "clip_write":
+      return true;
+  }
+}
+
+/**
+ * Evaluate one content-transfer boundary. Runtime guards intentionally accept
+ * malformed JavaScript callers fail-closed even though TypeScript callers get
+ * the narrower contract.
+ */
+function evaluateSnapshot(snapshot: EgressEvaluationSnapshot): EgressDecision {
+  const audit = snapshotAudit(snapshot);
+  if (snapshot.collections.length === 0) {
+    return decision(false, "NO_COLLECTION_POLICY", audit);
+  }
+  if (!isAction(snapshot.action)) {
+    return decision(false, "UNKNOWN_ACTION", audit);
+  }
+  if (!isDestinationZone(snapshot.destinationZone)) {
+    return decision(false, "UNKNOWN_DESTINATION", audit);
+  }
+  if (!actionAllowsDestination(snapshot.action, snapshot.destinationZone)) {
+    return decision(false, "ACTION_DESTINATION_MISMATCH", audit);
+  }
+  if (!isContentClass(snapshot.contentClass)) {
+    return decision(false, "UNKNOWN_CONTENT_CLASS", audit);
+  }
+  if (
+    typeof snapshot.callerAuthenticated !== "boolean" ||
+    typeof snapshot.callerOperationAuthorized !== "boolean"
+  ) {
+    return decision(false, "INVALID_CALLER", audit);
+  }
+
+  const collections: CollectionEgressState[] = [];
+  const collectionNames = new Set<string>();
+  for (const collection of snapshot.collections) {
+    if (
+      typeof collection.collection !== "string" ||
+      !COLLECTION_NAME_PATTERN.test(collection.collection)
+    ) {
+      return decision(false, "INVALID_COLLECTION", audit);
+    }
+    if (!isPolicy(collection.policy)) {
+      return decision(false, "UNKNOWN_POLICY", audit);
+    }
+    if (!isPolicySource(collection.source)) {
+      return decision(false, "UNKNOWN_POLICY_SOURCE", audit);
+    }
+    if (
+      collection.source !== "explicit" &&
+      collection.policy !== "local_only"
+    ) {
+      return decision(false, "INVALID_POLICY_SOURCE_PAIR", audit);
+    }
+    if (collectionNames.has(collection.collection)) {
+      return decision(false, "INVALID_COLLECTION", audit);
+    }
+    collectionNames.add(collection.collection);
+    collections.push({
+      collection: collection.collection,
+      policy: collection.policy,
+      source: collection.source,
+    });
+  }
+
+  const effective = effectiveCollectionPolicy(collections);
+  audit.effectivePolicy = effective.policy;
+  audit.effectivePolicySource = effective.source;
+
+  if (!snapshot.callerOperationAuthorized) {
+    return decision(false, "CALLER_NOT_AUTHORIZED", audit);
+  }
+  if (
+    snapshot.destinationZone === "local_process" ||
+    snapshot.destinationZone === "loopback"
+  ) {
+    return decision(true, "LOCAL_DESTINATION", audit);
+  }
+  if (effective.policy === "local_only") {
+    return decision(false, "POLICY_LOCAL_ONLY", audit);
+  }
+  if (snapshot.destinationZone === "remote" && effective.policy === "lan") {
+    return decision(false, "POLICY_LAN_ONLY", audit);
+  }
+  if (!snapshot.callerAuthenticated) {
+    return decision(false, "AUTHENTICATION_REQUIRED", audit);
+  }
+  if (snapshot.destinationZone === "lan") {
+    return decision(true, "LAN_POLICY_AUTHENTICATED", audit);
+  }
+  return decision(true, "REMOTE_POLICY_AUTHENTICATED", audit);
+}
+
+export function evaluateEgressPolicy(input: unknown): EgressDecision {
+  try {
+    const result = snapshotInput(input);
+    if (result.kind === "invalid") {
+      return decision(false, "INVALID_INPUT", invalidInputAudit());
+    }
+    if (result.kind === "limit_exceeded") {
+      return decision(false, "COLLECTION_LIMIT_EXCEEDED", limitExceededAudit());
+    }
+    return evaluateSnapshot(result.value);
+  } catch {
+    return decision(false, "INVALID_INPUT", invalidInputAudit());
+  }
+}
+
+export const defaultEgressPolicyPort: EgressPolicyPort = Object.freeze({
+  evaluate: evaluateEgressPolicy,
+});