comisai 1.0.42 → 1.0.44

package/node_modules/@comis/core/dist/reflection/delta-ops.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reflection delta-ops APPLY — the v2.31 Reflection engine's byte-stable
+ * doc-refresh primitive (REFLECT-04, Hindsight's drift-killer). The runtime
+ * counterpart to the type-only `../ports/reflection-port.ts` (the runtime values
+ * live HERE because `core/src/ports/*.ts` is type-only by the port-shape rule —
+ * the no-op-factory / `profile-id` precedent). Re-exported on the public
+ * `@comis/core` surface via `../exports/ports.ts`.
+ *
+ * ## The drift-killer (the load-bearing invariant)
+ *
+ * {@link applyDeltaOps} copies every section NOT targeted by an op **by
+ * reference** — the same object survives into the result. Reference identity IS
+ * the byte-identity guarantee: an untouched section is never re-serialized, so a
+ * one-section refresh produces a one-section diff and the slow drift a
+ * full-rewrite causes (Hindsight's failure mode) cannot happen. The function is
+ * PURE (no IO, no clock, no randomness) and TOTAL (an op whose target id does not
+ * exist is a no-op for that op — never a throw, never a doc-corruption), and it
+ * never mutates `prev`.
+ *
+ * {@link renderStructuredBody} projects the AST to the markdown `body` column
+ * deterministically (`## heading\n\nbody`, sections joined by a blank line) — the
+ * same AST renders to the byte-identical string on every call.
+ *
+ * @module
+ */
+import type { StructuredBody, DeltaOp } from "../ports/reflection-port.js";
+/**
+ * Apply a list of {@link DeltaOp}s to a structured body, returning the NEXT body.
+ *
+ * THE DRIFT-KILLER (REFLECT-04): every section NOT targeted by an op is copied
+ * **by reference** — `result.sections[i] === prev.sections[i]` for an untouched
+ * section. Only an `add`'s/`replace`'s `section` object is new. Pure (never
+ * mutates `prev`), total (a target id that does not exist is a no-op for that op,
+ * never a throw), deterministic (ops applied in order). An empty op list returns
+ * a body whose sections are all the same references as `prev` — an empty refresh
+ * never drifts.
+ */
+export declare function applyDeltaOps(prev: StructuredBody, ops: DeltaOp[]): StructuredBody;
+/**
+ * Project a {@link StructuredBody} to the markdown `body` column. Each section
+ * renders as `## heading\n\nbody`; sections are joined by a blank line. Pure +
+ * deterministic — the same AST yields the byte-identical string on every call.
+ * An empty section list renders to the empty string.
+ */
+export declare function renderStructuredBody(ast: StructuredBody): string;

package/node_modules/@comis/core/dist/reflection/delta-ops.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Reflection delta-ops APPLY — the v2.31 Reflection engine's byte-stable
+ * doc-refresh primitive (REFLECT-04, Hindsight's drift-killer). The runtime
+ * counterpart to the type-only `../ports/reflection-port.ts` (the runtime values
+ * live HERE because `core/src/ports/*.ts` is type-only by the port-shape rule —
+ * the no-op-factory / `profile-id` precedent). Re-exported on the public
+ * `@comis/core` surface via `../exports/ports.ts`.
+ *
+ * ## The drift-killer (the load-bearing invariant)
+ *
+ * {@link applyDeltaOps} copies every section NOT targeted by an op **by
+ * reference** — the same object survives into the result. Reference identity IS
+ * the byte-identity guarantee: an untouched section is never re-serialized, so a
+ * one-section refresh produces a one-section diff and the slow drift a
+ * full-rewrite causes (Hindsight's failure mode) cannot happen. The function is
+ * PURE (no IO, no clock, no randomness) and TOTAL (an op whose target id does not
+ * exist is a no-op for that op — never a throw, never a doc-corruption), and it
+ * never mutates `prev`.
+ *
+ * {@link renderStructuredBody} projects the AST to the markdown `body` column
+ * deterministically (`## heading\n\nbody`, sections joined by a blank line) — the
+ * same AST renders to the byte-identical string on every call.
+ *
+ * @module
+ */
+/**
+ * Apply a list of {@link DeltaOp}s to a structured body, returning the NEXT body.
+ *
+ * THE DRIFT-KILLER (REFLECT-04): every section NOT targeted by an op is copied
+ * **by reference** — `result.sections[i] === prev.sections[i]` for an untouched
+ * section. Only an `add`'s/`replace`'s `section` object is new. Pure (never
+ * mutates `prev`), total (a target id that does not exist is a no-op for that op,
+ * never a throw), deterministic (ops applied in order). An empty op list returns
+ * a body whose sections are all the same references as `prev` — an empty refresh
+ * never drifts.
+ */
+export function applyDeltaOps(prev, ops) {
+    // Start from a shallow copy of the section array — the ELEMENTS are the SAME
+    // object references as prev (byte-identity); only the array container is new
+    // (so prev is never mutated).
+    let sections = prev.sections.slice();
+    for (const op of ops) {
+        switch (op.op) {
+            case "replace": {
+                const idx = sections.findIndex((s) => s.id === op.id);
+                // Non-existent target → no-op for this op (graceful; no throw, no corruption).
+                if (idx === -1)
+                    break;
+                // Replace ONLY the target; all other elements remain the same references.
+                sections = sections.map((s, i) => (i === idx ? op.section : s));
+                break;
+            }
+            case "remove": {
+                const idx = sections.findIndex((s) => s.id === op.id);
+                if (idx === -1)
+                    break; // no-op for a non-existent id
+                // filter() preserves the references of the survivors.
+                sections = sections.filter((_, i) => i !== idx);
+                break;
+            }
+            case "add": {
+                const afterId = op.after;
+                // Omitted `after`, or an `after` that does not match any section, appends
+                // at the END (graceful). Otherwise insert immediately after the match.
+                const afterIdx = afterId === undefined ? -1 : sections.findIndex((s) => s.id === afterId);
+                if (afterIdx === -1) {
+                    sections = [...sections, op.section];
+                }
+                else {
+                    sections = [...sections.slice(0, afterIdx + 1), op.section, ...sections.slice(afterIdx + 1)];
+                }
+                break;
+            }
+        }
+    }
+    return { sections };
+}
+/**
+ * Project a {@link StructuredBody} to the markdown `body` column. Each section
+ * renders as `## heading\n\nbody`; sections are joined by a blank line. Pure +
+ * deterministic — the same AST yields the byte-identical string on every call.
+ * An empty section list renders to the empty string.
+ */
+export function renderStructuredBody(ast) {
+    return ast.sections.map((s) => `## ${s.heading}\n\n${s.body}`).join("\n\n");
+}

package/node_modules/@comis/core/dist/runtime/file-lock.js

@@ -233,7 +233,7 @@ export function createFileLock() {
                 if (!entry.endsWith(".lock"))
                     continue;
                 // safePath ensures the cleanup walk cannot escape lockDir even when
-                // the directory contains an attacker-injected entry. AGENTS.md §2.2.
+                // the directory contains an attacker-injected entry.
                 const fullPath = safePath(lockDir, entry);
                 try {
                     const stat = await fs.stat(fullPath);

package/node_modules/@comis/core/dist/runtime/poll-deadline.d.ts

@@ -0,0 +1,47 @@
+/** An absolute-deadline view over an injectable clock. */
+export interface PollDeadline {
+    /** True once the clock has reached or passed the captured deadline. */
+    exceeded(): boolean;
+    /** Milliseconds left until the deadline; floors at 0 (never negative). */
+    remainingMs(): number;
+}
+/**
+ * Capture an absolute deadline from a `timeoutMs` budget. Inject `nowMs` for
+ * fake-clock tests; defaults to the sanctioned `systemNowMs`.
+ */
+export declare function createPollDeadline(timeoutMs: number, nowMs?: () => number): PollDeadline;
+/**
+ * Outcome discriminator — a terminal success status, a failed short-circuit, or
+ * a deadline timeout. The caller (the adapter's `execute()`) maps `timeout` to
+ * its domain `job_timeout` error and `failed` to the last thrown provider error.
+ */
+export type PollOutcome<S> = {
+    kind: "done";
+    status: S;
+} | {
+    kind: "failed";
+    status: S;
+} | {
+    kind: "timeout";
+};
+/**
+ * Bounded poll loop. Calls `poll()` until `isDone(status)` (→ done),
+ * `isFailed(status)` (→ failed short-circuit, VPORT-02), or the deadline
+ * (→ timeout). Sleeps `pollIntervalMs` (clamped to the remaining budget) between
+ * attempts. Inject `nowMs` (via the `deadline`) and `sleep` for fake-timer
+ * tests. Honors `signal?.aborted` (returns `timeout` so the caller surfaces a
+ * single bounded-loop-ended branch).
+ *
+ * NEVER throws: a thrown `poll()` is the CALLER's concern — the FAL adapter
+ * wraps `poll()` in `fromPromise` and maps a thrown HTTP error to the `failed`
+ * branch itself; this helper only ever sees status snapshots + the deadline.
+ */
+export declare function pollUntilDone<S>(opts: {
+    poll: () => Promise<S>;
+    isDone: (s: S) => boolean;
+    isFailed: (s: S) => boolean;
+    deadline: PollDeadline;
+    pollIntervalMs: number;
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+}): Promise<PollOutcome<S>>;

package/node_modules/@comis/core/dist/runtime/poll-deadline.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared bounded-poll helper (DIVERGENCE 5).
+ *
+ * There is no other bounded-poll utility in the repo. It is authored in
+ * `@comis/core/runtime` — NOT in `@comis/skills` — so Phase 189's daemon
+ * background poller imports it without a package-boundary violation (it needs
+ * the SAME loop the inline `execute()` baseline uses, byte-for-byte). The
+ * `@comis/skills` FAL adapter consumes it in `execute()`.
+ *
+ * Sanctioned-clock discipline: the only clock/sleep this module touches are the
+ * `systemNowMs` / `systemSleep` DEFAULTS from `./system-time.js` (themselves a
+ * BOOTSTRAP_PATH_PATTERNS-exempt runtime root). Tests inject `nowMs`/`sleep`
+ * (AGENTS.md §2.5) so they never touch a real timer.
+ *
+ * The helper is deliberately PROVIDER-AGNOSTIC: it returns a `PollOutcome`
+ * discriminator (`done` / `failed` / `timeout`) and constructs no domain error.
+ * The FAL adapter maps `{ kind: "timeout" }` onto a `VideoErrorKind:"job_timeout"`
+ * Result carrying the loggable jobId — keeping this loop reusable by Phase 189.
+ *
+ * @module
+ */
+import { systemNowMs, systemSleep } from "./system-time.js";
+/**
+ * Capture an absolute deadline from a `timeoutMs` budget. Inject `nowMs` for
+ * fake-clock tests; defaults to the sanctioned `systemNowMs`.
+ */
+export function createPollDeadline(timeoutMs, nowMs = systemNowMs) {
+    const deadlineMs = nowMs() + timeoutMs;
+    return {
+        exceeded: () => nowMs() >= deadlineMs,
+        remainingMs: () => Math.max(0, deadlineMs - nowMs()),
+    };
+}
+/**
+ * Bounded poll loop. Calls `poll()` until `isDone(status)` (→ done),
+ * `isFailed(status)` (→ failed short-circuit, VPORT-02), or the deadline
+ * (→ timeout). Sleeps `pollIntervalMs` (clamped to the remaining budget) between
+ * attempts. Inject `nowMs` (via the `deadline`) and `sleep` for fake-timer
+ * tests. Honors `signal?.aborted` (returns `timeout` so the caller surfaces a
+ * single bounded-loop-ended branch).
+ *
+ * NEVER throws: a thrown `poll()` is the CALLER's concern — the FAL adapter
+ * wraps `poll()` in `fromPromise` and maps a thrown HTTP error to the `failed`
+ * branch itself; this helper only ever sees status snapshots + the deadline.
+ */
+export async function pollUntilDone(opts) {
+    const sleep = opts.sleep ?? systemSleep;
+    for (;;) {
+        if (opts.signal?.aborted)
+            return { kind: "timeout" };
+        const status = await opts.poll();
+        if (opts.isFailed(status))
+            return { kind: "failed", status };
+        if (opts.isDone(status))
+            return { kind: "done", status };
+        if (opts.deadline.exceeded())
+            return { kind: "timeout" };
+        await sleep(Math.min(opts.pollIntervalMs, opts.deadline.remainingMs()));
+        if (opts.deadline.exceeded())
+            return { kind: "timeout" };
+    }
+}

package/node_modules/@comis/core/dist/security/action-classifier.js

@@ -32,7 +32,7 @@ const ACTION_REGISTRY = new Map([
     ["session.get", "read"],
     ["log.read", "read"],
     // -------------------------------------------------------------------------
-    // Read operations (v2.0 tool actions)
+    // Read operations (tool actions)
     // -------------------------------------------------------------------------
     ["tool.execute", "read"],
     ["cron.list", "read"],
@@ -70,7 +70,7 @@ const ACTION_REGISTRY = new Map([
     ["skill.install", "mutate"],
     ["skill.execute", "mutate"],
     // -------------------------------------------------------------------------
-    // Mutate operations (v2.0 tool actions)
+    // Mutate operations (tool actions)
     // -------------------------------------------------------------------------
     ["message.reply", "mutate"],
     ["message.react", "mutate"],
@@ -95,11 +95,11 @@ const ACTION_REGISTRY = new Map([
     ["system.shutdown", "destructive"],
     ["system.exec", "destructive"],
     // -------------------------------------------------------------------------
-    // Mutate operations (v2.0 — reversible scheduling)
+    // Mutate operations (reversible scheduling)
     // -------------------------------------------------------------------------
     ["cron.add", "mutate"],
     // -------------------------------------------------------------------------
-    // Destructive operations (v2.0 tool actions)
+    // Destructive operations (tool actions)
     // -------------------------------------------------------------------------
     ["cron.remove", "destructive"],
     ["message.delete", "destructive"],

package/node_modules/@comis/core/dist/security/audit.d.ts

@@ -1,10 +1,40 @@
 import { z } from "zod";
 import type { ActionClassification } from "./action-classifier.js";
+/**
+ * Audit event KIND — the closed event-family discriminator (AUDIT-03 / E4).
+ *
+ * The original schema conflated two concepts into one required
+ * `classification` enum (`read|mutate|destructive`). Live emit sites were
+ * passing values OUTSIDE that enum (`"security"`/`"write"`/`"neutral"`),
+ * silently violating it because the event-bus payload types
+ * `classification` as a loose `string`. E4 splits the event FAMILY (`kind`,
+ * required, closed) from the access-class (`classification`, optional,
+ * present only when meaningful — chiefly the generic `audit` kind).
+ *
+ * Closed string-literal union (AGENTS §2.8) — NEVER `kind: string`. Adding a
+ * member here without handling it in {@link kindIsSecuritySignal} fails the
+ * build via the `const _exhaustive: never` guard.
+ *
+ * `AUDIT_KINDS` is the single source of truth: the Zod schema uses
+ * `z.enum(AUDIT_KINDS)` so the runtime validator and the static `AuditKind`
+ * type can never drift.
+ */
+export declare const AUDIT_KINDS: readonly ["audit", "secret_access", "injection_detected", "injection_rate_exceeded", "canary_leak", "implied_tool_call", "command_blocked", "hook_blocked", "auth_mutation", "sandbox_downgrade_refused", "capability_denied", "ssrf_blocked"];
+/** The closed audit event-family union (inferred from {@link AUDIT_KINDS}). */
+export type AuditKind = (typeof AUDIT_KINDS)[number];
+/**
+ * Whether an audit kind represents a security signal (vs a routine audit
+ * record). The `switch` is exhaustive over {@link AuditKind}; the
+ * `const _exhaustive: never` guard (AGENTS §2.8) fails the build if a kind is
+ * added to {@link AUDIT_KINDS} without being classified here.
+ */
+export declare function kindIsSecuritySignal(kind: AuditKind): boolean;
 /**
  * Audit event schema for structured security logging.
  *
- * Every significant action produces an audit event with
- * classification, outcome, tracing, and timing information.
+ * Every significant action produces an audit event with a `kind` (event
+ * family), an optional `classification` (risk class), outcome, tracing, and
+ * timing information.
  */
 export declare const AuditEventSchema: z.ZodObject<{
     id: z.ZodGUID;
@@ -13,11 +43,25 @@ export declare const AuditEventSchema: z.ZodObject<{
     agentId: z.ZodString;
     userId: z.ZodString;
     actionType: z.ZodString;
-    classification: z.ZodEnum<{
+    kind: z.ZodEnum<{
+        capability_denied: "capability_denied";
+        audit: "audit";
+        secret_access: "secret_access";
+        injection_detected: "injection_detected";
+        injection_rate_exceeded: "injection_rate_exceeded";
+        canary_leak: "canary_leak";
+        implied_tool_call: "implied_tool_call";
+        command_blocked: "command_blocked";
+        hook_blocked: "hook_blocked";
+        auth_mutation: "auth_mutation";
+        sandbox_downgrade_refused: "sandbox_downgrade_refused";
+        ssrf_blocked: "ssrf_blocked";
+    }>;
+    classification: z.ZodOptional<z.ZodEnum<{
         read: "read";
         mutate: "mutate";
         destructive: "destructive";
-    }>;
+    }>>;
     outcome: z.ZodEnum<{
         success: "success";
         failure: "failure";
@@ -32,13 +76,17 @@ export type AuditEvent = z.infer<typeof AuditEventSchema>;
 /**
  * Parameters for creating an audit event.
  * The id and timestamp are auto-generated; everything else must be provided.
+ *
+ * `kind` (the event family) is required; `classification` is optional (E4 —
+ * present only when the access-class is meaningful).
  */
 export interface CreateAuditEventParams {
     tenantId: string;
     agentId: string;
     userId: string;
     actionType: string;
-    classification: ActionClassification;
+    kind: AuditKind;
+    classification?: ActionClassification;
     outcome: "success" | "failure" | "denied";
     metadata?: Record<string, unknown>;
     traceId?: string;
@@ -47,6 +95,11 @@ export interface CreateAuditEventParams {
 /**
  * Create a new audit event with auto-generated id and timestamp.
  *
+ * This is the SOLE constructor for an {@link AuditEvent} — every emit site
+ * routes through it so every event is schema-valid before it can be
+ * persisted (Plan 03's sink). `classification` is only included when
+ * provided (E4 — the schema makes it optional).
+ *
  * @param params - Event parameters (id and timestamp are auto-generated)
  * @returns A validated AuditEvent
  */

package/node_modules/@comis/core/dist/security/audit.js

@@ -2,11 +2,91 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { systemNowDate } from "../runtime/system-time.js";
+/**
+ * Audit event KIND — the closed event-family discriminator (AUDIT-03 / E4).
+ *
+ * The original schema conflated two concepts into one required
+ * `classification` enum (`read|mutate|destructive`). Live emit sites were
+ * passing values OUTSIDE that enum (`"security"`/`"write"`/`"neutral"`),
+ * silently violating it because the event-bus payload types
+ * `classification` as a loose `string`. E4 splits the event FAMILY (`kind`,
+ * required, closed) from the access-class (`classification`, optional,
+ * present only when meaningful — chiefly the generic `audit` kind).
+ *
+ * Closed string-literal union (AGENTS §2.8) — NEVER `kind: string`. Adding a
+ * member here without handling it in {@link kindIsSecuritySignal} fails the
+ * build via the `const _exhaustive: never` guard.
+ *
+ * `AUDIT_KINDS` is the single source of truth: the Zod schema uses
+ * `z.enum(AUDIT_KINDS)` so the runtime validator and the static `AuditKind`
+ * type can never drift.
+ */
+export const AUDIT_KINDS = [
+    /** Generic audit record (the access-class `classification` is meaningful here). */
+    "audit",
+    /** A secret was accessed (secrets.get) — secrets-handlers.ts. */
+    "secret_access",
+    /** A prompt-injection attempt was detected (output/response guard) — executor-response-filter.ts. */
+    "injection_detected",
+    /** The per-session injection rate threshold was crossed — executor-input-guard.ts. */
+    "injection_rate_exceeded",
+    /** A canary token leaked into model output — critic isolation. */
+    "canary_leak",
+    /** An implied/unauthorized tool call was detected — critic isolation. */
+    "implied_tool_call",
+    /** A command was blocked by policy — command guard. */
+    "command_blocked",
+    /** A hook modified or blocked an action — hook-runner.ts. */
+    "hook_blocked",
+    /** An auth-state mutation (auth.set) — auth-handlers.ts. */
+    "auth_mutation",
+    /** A sandbox downgrade was refused (fail-closed) — sandbox governance. */
+    "sandbox_downgrade_refused",
+    /** A capability or deny-by-origin gate rejected a call — capability.ts /
+     *  assert-not-agent-origin (Phase 210). */
+    "capability_denied",
+    /** An outbound URL was blocked by the SSRF guard (validateUrl) — metadata IP /
+     *  RFC1918 / loopback / non-http target. hermes-usecases obs-loop 2026-06-25. */
+    "ssrf_blocked",
+];
+/**
+ * Whether an audit kind represents a security signal (vs a routine audit
+ * record). The `switch` is exhaustive over {@link AuditKind}; the
+ * `const _exhaustive: never` guard (AGENTS §2.8) fails the build if a kind is
+ * added to {@link AUDIT_KINDS} without being classified here.
+ */
+export function kindIsSecuritySignal(kind) {
+    switch (kind) {
+        case "secret_access":
+        case "injection_detected":
+        case "injection_rate_exceeded":
+        case "canary_leak":
+        case "implied_tool_call":
+        case "command_blocked":
+        case "hook_blocked":
+        case "sandbox_downgrade_refused":
+        case "capability_denied":
+        case "ssrf_blocked":
+            return true;
+        case "audit":
+        case "auth_mutation":
+            return false;
+        default: {
+            // Exhaustiveness guard — adding an AuditKind without handling it here
+            // is a compile error. Fail-closed at runtime: treat an unknown kind as
+            // a security signal so it is never silently downgraded.
+            const _exhaustive = kind;
+            void _exhaustive;
+            return true;
+        }
+    }
+}
 /**
  * Audit event schema for structured security logging.
  *
- * Every significant action produces an audit event with
- * classification, outcome, tracing, and timing information.
+ * Every significant action produces an audit event with a `kind` (event
+ * family), an optional `classification` (risk class), outcome, tracing, and
+ * timing information.
  */
 export const AuditEventSchema = z.strictObject({
     /** Unique event identifier (UUIDv4). */
@@ -21,8 +101,14 @@ export const AuditEventSchema = z.strictObject({
     userId: z.string().min(1),
     /** The action that was performed (e.g., "file.delete"). */
     actionType: z.string().min(1),
-    /** Risk classification of the action. */
-    classification: z.enum(["read", "mutate", "destructive"]),
+    /** Event family (closed union — the single source is AUDIT_KINDS). */
+    kind: z.enum(AUDIT_KINDS),
+    /**
+     * Risk classification of the action — OPTIONAL (E4). Present only when
+     * meaningful (chiefly the generic `audit` kind); security-signal kinds
+     * leave it unset.
+     */
+    classification: z.enum(["read", "mutate", "destructive"]).optional(),
     /** Whether the action succeeded or failed. */
     outcome: z.enum(["success", "failure", "denied"]),
     /** Arbitrary metadata about the event. */
@@ -35,6 +121,11 @@ export const AuditEventSchema = z.strictObject({
 /**
  * Create a new audit event with auto-generated id and timestamp.
  *
+ * This is the SOLE constructor for an {@link AuditEvent} — every emit site
+ * routes through it so every event is schema-valid before it can be
+ * persisted (Plan 03's sink). `classification` is only included when
+ * provided (E4 — the schema makes it optional).
+ *
  * @param params - Event parameters (id and timestamp are auto-generated)
  * @returns A validated AuditEvent
  */
@@ -46,7 +137,10 @@ export function createAuditEvent(params) {
         agentId: params.agentId,
         userId: params.userId,
         actionType: params.actionType,
-        classification: params.classification,
+        kind: params.kind,
+        // Only carry classification when meaningful (E4 — present chiefly for
+        // the generic `audit` kind; security-signal kinds leave it unset).
+        ...(params.classification !== undefined ? { classification: params.classification } : {}),
         outcome: params.outcome,
         metadata: params.metadata ?? {},
         traceId: params.traceId,

package/node_modules/@comis/core/dist/security/bind-mount-validator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validate a host path requested as a bwrap bind source.
+ *
+ * @param hostPath - The host path the jail would `--bind`.
+ * @param home - The daemon user's HOME (the credential-dir base). PASSED IN for purity.
+ * @returns `{ ok: true }` when the bind is safe, else `{ ok: false, reason }`.
+ */
+export declare function validateBindMount(hostPath: string, home: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/node_modules/@comis/core/dist/security/bind-mount-validator.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * JAIL-03 bind-mount validator — a PURE denylist backstop on top of the
+ * allow-list jail binds (v8 invariant 10: the validator does NOT decide what to
+ * bind, it only refuses dangerous binds).
+ *
+ * It rejects three classic jail-escape shapes (escapes are symlink/parent-mount,
+ * not kernel bugs):
+ *   1. Direct hit  — `hostPath` IS or is UNDER a denylisted dir.
+ *   2. Parent-cover — `hostPath` is a coarse ancestor that COVERS a blocked
+ *      descendant (binding `/` or `~` would expose `~/.ssh`).
+ *   3. Symlink-escape — a leaf (or any ancestor segment) is a symlink whose
+ *      realpath resolves INTO a denylisted path. Resolved THROUGH ancestors via
+ *      per-segment `realpathSync` (the `safe-path.ts` checkSymlinks primitive),
+ *      NEVER a string-prefix check on the unresolved path.
+ *
+ * Purity: `home` is a PARAMETER (never read from the ambient environment),
+ * mirroring `getUserRoPaths(home)` in bwrap-provider.ts. The only I/O is
+ * `fs.realpathSync` for symlink resolution — no environment reads, no writes.
+ */
+/** System directories never safe to bind into the jail (`/` itself + any path under them). */
+const DENYLIST_SYSTEM_DIRS = ["/etc", "/proc", "/sys", "/dev", "/root", "/run"];
+/** Credential directories under the daemon HOME — `~` resolved to the `home` param. */
+function denylistedHomeDirs(home) {
+    // eslint-disable-next-line no-restricted-syntax -- this is a path VALIDATOR (the inverse of safePath); it builds the BLOCKED set from constant credential-dir basenames under HOME. safePath would confine to a base and throw on the system paths this validator must also inspect.
+    return [".ssh", ".aws", ".gnupg", ".config", ".npm", ".netrc"].map((d) => path.join(home, d));
+}
+/**
+ * Resolve `abs` to a fully symlink-resolved absolute path, tolerating a
+ * not-yet-created leaf. Walk from the filesystem root, `realpathSync` the
+ * longest existing prefix (which follows any symlinked ancestor), then re-append
+ * the remaining non-existent tail. A leaf symlink pointing at `/etc` therefore
+ * resolves to `/etc`; a bind path whose parents exist but leaf does not still
+ * validates by its real ancestors. Mirrors the existence-tolerant loop in
+ * `safe-path.ts` checkSymlinks.
+ */
+function resolveThroughAncestors(abs) {
+    // Fast path: the whole path exists — realpath resolves every symlink segment.
+    try {
+        return fs.realpathSync(abs);
+    }
+    catch {
+        // Leaf (or deeper) does not exist yet — resolve the longest existing prefix.
+    }
+    const parts = abs.split(path.sep).filter((p) => p.length > 0);
+    let resolvedPrefix = path.sep; // POSIX root (widened from the path.sep literal)
+    let tailIndex = 0;
+    for (let i = 0; i < parts.length; i++) {
+        // eslint-disable-next-line no-restricted-syntax -- resolve-through-ancestors needs raw path.join to rebuild each absolute segment from the kernel-resolved prefix; safePath's base-confinement would reject the symlink-to-blocked-target cases this loop exists to DETECT.
+        const candidate = path.join(resolvedPrefix, parts[i]);
+        try {
+            // realpathSync resolves a symlinked segment to its real target.
+            resolvedPrefix = fs.realpathSync(candidate);
+            tailIndex = i + 1;
+        }
+        catch {
+            // This segment does not exist — stop; everything from here is literal tail.
+            break;
+        }
+    }
+    const tail = parts.slice(tailIndex);
+    // eslint-disable-next-line no-restricted-syntax -- re-append the not-yet-created tail to the resolved prefix; this is absolute-path reconstruction inside a validator, not a base-confined join.
+    return tail.length > 0 ? path.join(resolvedPrefix, ...tail) : resolvedPrefix;
+}
+/** True when `child` IS `parent` or sits strictly UNDER it (boundary-safe, not a bare prefix). */
+function isAtOrUnder(child, parent) {
+    if (child === parent)
+        return true;
+    const normalizedParent = parent.endsWith(path.sep) ? parent : parent + path.sep;
+    return child.startsWith(normalizedParent);
+}
+/**
+ * Validate a host path requested as a bwrap bind source.
+ *
+ * @param hostPath - The host path the jail would `--bind`.
+ * @param home - The daemon user's HOME (the credential-dir base). PASSED IN for purity.
+ * @returns `{ ok: true }` when the bind is safe, else `{ ok: false, reason }`.
+ */
+export function validateBindMount(hostPath, home) {
+    // 1. Canonical absolute path, then resolve symlinks through ancestors so a
+    //    symlinked leaf cannot smuggle a blocked path past the compare below.
+    const abs = path.resolve(hostPath);
+    const resolved = resolveThroughAncestors(abs);
+    // 2. The blocked set: system dirs + the HOME credential dirs (resolved too, so
+    //    a symlinked HOME or credential dir is compared by its real location).
+    const blocked = [
+        ...DENYLIST_SYSTEM_DIRS.map((b) => resolveThroughAncestors(b)),
+        ...denylistedHomeDirs(home).map((b) => resolveThroughAncestors(b)),
+    ];
+    // 3. Direct/under check: the resolved bind IS or is UNDER a blocked dir.
+    for (const b of blocked) {
+        if (isAtOrUnder(resolved, b)) {
+            return { ok: false, reason: `bind path resolves into blocked dir ${b}` };
+        }
+    }
+    // 4. Parent-cover check: the resolved bind is an ancestor that COVERS a
+    //    blocked descendant (a coarse `/` or `~` bind must not smuggle `~/.ssh`).
+    for (const b of blocked) {
+        if (isAtOrUnder(b, resolved)) {
+            return { ok: false, reason: `bind path is a parent covering blocked descendant ${b}` };
+        }
+    }
+    return { ok: true };
+}