@tuent/sentinel 0.1.2 → 0.1.4

package/SECURITY_MODEL.md

@@ -68,6 +68,15 @@ All target paths are normalized with `path.normalize()` before pattern matching.
 - `src/../.env` is normalized to `.env` before checking against `**/.env`
 - `project/subdir/../../.ssh/id_rsa` is normalized to `.ssh/id_rsa`
 
+Conversely, `command_exec` targets (whole shell command strings) are **never glob-matched as if they were a path**. They are screened by a scanner: the command is tokenized, path-shaped tokens are resolved and matched against the forbidden patterns, and every argv token's basename is matched against each pattern's basename component with **component-boundary** semantics (the basename must match as a whole, not as a substring). So `process.env` and similarly-shaped code constructs are not treated as file access (the basename `process.env` is not the basename `.env`), while a real operand like `payroll.csv` against a `payroll.csv` forbid pattern is denied — in any command position, not only at the end. This screen is the single source of truth for command screening on **both** the gateway and the embedded-SDK (`wrap()`/`check()`) paths; the gateway additionally keeps its inline L1/L2 scan as defense-in-depth. Correspondingly, `command_exec` is **exempt from the allowed-target allowlist** (and session `SCOPE:` narrowing): those are path globs, and a command string is not a path, so matching it there only produced false `scope_violation`s — which the sensitivity scorer could escalate to a hard block when the command merely named a credential token (e.g. `process.env`). Whether an agent may run commands at all is governed by `allowedActions`; whether a given command is forbidden is the command screen above.
+
+Two residuals of letting operators forbid bare basenames in commands (both pre-existing, narrower than the prior whole-string glob, and operator-self-inflicted):
+
+- **R1 — generic-word custom basenames.** A custom forbid pattern whose basename is a common word (e.g. a pattern ending in `build`) will also match a command that uses that word as a non-file argument (e.g. `npm run build`). This is intrinsic to forbidding a bare common word; prefer specific basenames for custom command-forbid patterns. The same property holds for path-target matching.
+- **R2 — positional-safety scope.** The echo-class positional-safety suppression (`isPositionallySafeMention`) is scoped to the built-in basename list, not to operator-custom patterns, so a custom basename mentioned in an otherwise-safe position (e.g. as an `echo` argument) is still denied.
+
+SDK-path residual: obfuscated/encoded command operands are de-obfuscated only on the gateway path (the translator's resolver pipeline); a direct `wrap()`/`check()` caller gets tokenized + basename + substring screening but not the decode layer.
+
 ### Self-Protection: Policy and Hook-Wiring Files
 
 The agent's own tool-writes to the live policy file (`.sentinel.yaml`) and to Claude Code's hook-wiring settings files (`.claude/settings.json` and `.claude/settings.local.json`, project- and user-level) are **denied by default**. Without this, an agent could rewrite its own policy or remove the hook entries that route its tool calls through the gateway with an ordinary file write. The corresponding forbid patterns ship in the defaults and the starter policy; the read carve-out is appended **code-side at ceiling-role construction** and is deliberately not authorable from the workspace yaml (workspace-authored exceptions are dropped by the ceiling merge, so a policy file can never widen its own protection away).

package/dist/Sentinel-4QKPFHTI.js

@@ -0,0 +1,10 @@
+import {
+  Sentinel
+} from "./chunk-I2FVDDSG.js";
+import "./chunk-FIEIGBYL.js";
+import "./chunk-KWZ7JKKO.js";
+import "./chunk-NUXSUSYY.js";
+export {
+  Sentinel
+};
+//# sourceMappingURL=Sentinel-4QKPFHTI.js.map

package/dist/{Sentinel-xFCyXH45.d.ts → Sentinel-DT0IyGQi.d.ts}

@@ -16,6 +16,7 @@ interface SkillNode {
     core?: boolean;
     sharable?: boolean;
     files?: string[];
+    eventCount?: number;
 }
 
 interface DataPoint {
@@ -29,6 +30,7 @@ interface DataPoint {
     files?: string[];
     sharable?: boolean;
     core?: boolean;
+    eventCount?: number;
 }
 
 interface StoredProfile {
@@ -89,16 +91,41 @@ declare class ProfileStore {
     private petalCount;
     private engine;
     private profile;
+    /** Snapshot (label → serialized point) of the on-disk-synced dataPoint set,
+     *  refreshed on every load/create/write. The base for save()'s three-way merge
+     *  of concurrent external writes — lets us tell "I deleted this" (in baseline,
+     *  gone from memory) from "another writer added this" (on disk, not in baseline). */
+    private baseline;
     constructor(options: {
         backend: StorageBackend;
         eventBus?: EventBus;
         petalCount?: number;
     });
     load(): Promise<StoredProfile | null>;
+    /** Snapshot the on-disk-synced dataPoint set for save()'s three-way merge. */
+    private captureBaseline;
     create(name: string): Promise<StoredProfile>;
     addPoint(point: DataPoint): Promise<void>;
     addPoints(points: DataPoint[]): void;
     save(): Promise<void>;
+    /**
+     * Three-way merge of a concurrent external write into the in-memory profile,
+     * invoked by save() when the backend reports the file changed since we last
+     * synced. Writers in this app are single-user but multi-process (agent scanner,
+     * diary watcher, dev server, CLI), so concurrent writes are real but rare.
+     *
+     * Model (base = the dataPoint set at our last load/write, see `baseline`):
+     *   - a point present in memory → kept as-is (the SAVING process's adds/edits
+     *     win on a same-point conflict — save() is an explicit "persist my state");
+     *   - a disk point whose label is NEW since baseline → another writer's
+     *     addition → preserved;
+     *   - a point we dropped (in baseline, absent from memory) → our deletion is
+     *     honored, UNLESS the other writer modified it (then their version is kept
+     *     so a concurrent edit is never silently lost).
+     * Net: nothing vanishes except a same-point simultaneous edit, resolved
+     * last-writer (this save) — a deliberate, documented tie-break.
+     */
+    private mergeExternalChanges;
     build(): SkillNode[];
     getProfile(): StoredProfile | null;
 }
@@ -299,6 +326,21 @@ interface SecurityFinding {
      * finding is its own distinct entry (never merged).
      */
     dedupKey?: string;
+    /**
+     * Sprint 26B F-5a (corroboration-by-distinct-target). Identity of the RESOLVED
+     * forbidden target the deny fired on: the L1-resolved path when one exists,
+     * else a basename-family fallback (`l2:<sorted basenames>`) for L2-only hits
+     * that never produced a resolved path (unparseable / construct ambiguity).
+     * When present, getEffectiveBlockCount keys distinct-counting on it INSTEAD of
+     * dedupKey, so repeated denials against the same forbidden target — e.g. many
+     * differently-shaped commands all naming one token during self-hosted
+     * development — contribute ONE count toward the escalation ladder, while
+     * distinct forbidden targets still accumulate (a real multi-file sweep
+     * escalates as before). Additive and conditional (soft-signal discipline):
+     * absent on pre-F-5a entries, which keep counting by dedupKey / keyless
+     * exactly as before. NEVER changes the per-command deny disposition.
+     */
+    targetKey?: string;
 }
 /** Computed behavioral baseline for an agent over a time window. */
 /**
@@ -365,7 +407,6 @@ interface SentinelConfig {
         mcpLogDir?: string;
         webhookPort?: number;
         webhookApiKey?: string;
-        roleDefinitionPath?: string;
         readExisting?: boolean;
     }[];
     alerts?: {
@@ -385,9 +426,6 @@ interface SentinelConfig {
             minKind?: "informational" | "actionable";
         }[];
     };
-    alertWebhook?: string;
-    baselineWindowDays?: number;
-    checkIntervalMs?: number;
 }
 /** A declared task/intent for an agent. */
 interface TaskIntent {
@@ -432,13 +470,18 @@ interface IntentAlignmentResult {
     bypassed?: boolean;
     bypassReason?: string | null;
 }
-/** Configuration for intent alignment scoring. */
+/**
+ * Configuration for intent alignment scoring.
+ *
+ * NOTE: the keywordBoost / acceptableActionBoost / baseScore /
+ * missingTaskScore knobs were removed — they were defined, defaulted, and
+ * typed but never read by any scoring path (vestiges of a pre-weighted
+ * scoring model superseded by SimilarityEngine.keywordSimilarity). They
+ * promised tunability that did not exist; the live weights are fixed in
+ * SimilarityEngine. defaultTtlMs is the only consumed numeric knob.
+ */
 interface IntentAlignmentConfig {
     defaultTtlMs: number;
-    keywordBoost: number;
-    acceptableActionBoost: number;
-    baseScore: number;
-    missingTaskScore: number;
     disableDefaultAcceptable?: boolean;
     denyAcceptable?: string[];
     similarityThreshold?: number;
@@ -849,6 +892,20 @@ declare class AuditTrail {
      * the file when an external append actually happened.
      */
     private reanchorFromDiskTail;
+    /**
+     * Scan the on-disk log backward for the last entry carrying a valid (64-hex)
+     * hash, SKIPPING torn/corrupt trailing lines, and return that hash (or null
+     * when no parseable hashed entry exists).
+     *
+     * Shared by open() (chain resume) and reanchorFromDiskTail() (live
+     * re-anchor). The earlier inline versions inspected only the LAST non-empty
+     * line and broke: a torn tail line (a partial write) left the head at genesis
+     * (open) or stale (reanchor), so the next append forked a fresh chain from
+     * genesis — destroying all prior linkage. Walking back leaves the torn line
+     * as a single localized gap that verify() still flags, while the chain head
+     * stays anchored to the last good entry.
+     */
+    private lastHashOnDisk;
     private readAllEntries;
     private loadCumulativeStats;
     /**
@@ -901,6 +958,54 @@ interface AgentClassifierConfig {
     minDurationMs: number;
 }
 
+interface SensitivityRule {
+    pattern: string;
+    sensitivity: number;
+    category: string;
+    description: string;
+}
+interface TargetSensitivityResult {
+    sensitivity: number;
+    category: string;
+    description: string;
+    matchedRule: string;
+    actionMultiplier: number;
+    effectiveScore: number;
+    groundedInRepoMap: boolean;
+}
+declare class TargetSensitivityScorer {
+    private rules;
+    private repoMap;
+    private repoRoot;
+    private overlay;
+    constructor(customRules?: SensitivityRule[], repoMap?: RepoSensitivityMap, repoRoot?: string, overlay?: SensitivityOverlay);
+    scoreTarget(target: string, action: string): TargetSensitivityResult;
+    /** Pattern-only scoring (Tier 2). Used directly by reject decisions. */
+    private _scoreByPatterns;
+    /**
+     * URL-aware component scoring (Sprint 6b W1 fix).
+     * Parses the URL, extracts path/query-values/fragment, decodes each once,
+     * scores each against forbidden-pattern rules, takes MAX.
+     */
+    private _scoreUrlTarget;
+    scoreEvent(event: AgentActivityEvent): TargetSensitivityResult;
+    /**
+     * Replaces the active repo sensitivity map. Pass null to clear.
+     * If newRepoRoot is provided, it overrides the map's repoRoot.
+     */
+    updateRepoMap(newMap: RepoSensitivityMap | null, newRepoRoot?: string): void;
+    /**
+     * Replaces the active sensitivity overlay. Pass null to clear.
+     */
+    updateOverlay(newOverlay: SensitivityOverlay | null): void;
+    /**
+     * Returns all pattern-based rules that match the target. Does NOT
+     * consult the repo map. Used by RepoSensitivityScanner during
+     * scan-time enumeration.
+     */
+    getAllMatchingRules(target: string): SensitivityRule[];
+}
+
 /** Lazy-init wrapper passed via RoleValidatorOptions so Sentinel can own the cache. */
 interface ForbiddenInodeCacheRef {
     getOrBuild: () => Set<bigint>;
@@ -1214,6 +1319,7 @@ declare class SentinelRunner {
     private _hookEngine?;
     private _maturityConfig?;
     private _validatorOptions?;
+    private _sensitivityScorer?;
     private intentTracker;
     private similarityEngine;
     private recentAlignmentScores;
@@ -1234,6 +1340,12 @@ declare class SentinelRunner {
     setMaturityConfig(config: Partial<BaselineMaturityConfig>): void;
     /** Set RoleValidator options (exception approval fn, audit callback). */
     setRoleValidatorOptions(options: RoleValidatorOptions): void;
+    /**
+     * Inject the facade's shared sensitivity scorer (overlay + repo map aware)
+     * so processEvent's validator scores identically to the facade's check().
+     * Must be called BEFORE start() builds the validator.
+     */
+    setSensitivityScorer(scorer: TargetSensitivityScorer): void;
     /** Set the behavioral baseline and start periodic gap checking. */
     setBaseline(baseline: AgentBaseline): void;
     /** Declare a new task intent for this agent. */
@@ -1250,6 +1362,12 @@ declare class SentinelRunner {
     getActiveTask(): TaskIntent | null;
     /** Expose the similarity engine for pre-execution intent checks. */
     getSimilarityEngine(): SimilarityEngine;
+    /**
+     * Read-only view of the rolling misaligned-score window, for the
+     * pre-execution gate (Sentinel.check) to apply the SAME sustained-drift
+     * severity upgrade as the recording path — without mutating the window.
+     */
+    getRecentAlignmentScores(): readonly number[];
     /**
      * Side-effect-free pre-execution gate: evaluate an event and fire pre_execution
      * hooks WITHOUT running processEvent's full pipeline.

package/dist/{chunk-PDWWRZXF.js → chunk-2IPSTUNH.js}

@@ -16,6 +16,9 @@ var LogAdapter = class {
   pendingFragment = "";
   running = false;
   polling = false;
+  /** The in-flight poll (if any), so stop() can let it finish emitting its
+   *  already-read batch before persisting the cursor. */
+  pollInFlight = null;
   pollTimer = null;
   onEvent = null;
   readExisting;
@@ -33,6 +36,7 @@ var LogAdapter = class {
     if (this.running) return;
     this.onEvent = onEvent;
     this.running = true;
+    this.pendingFragment = "";
     const savedPosition = await this.loadCursor();
     if (savedPosition !== null) {
       this.lastReadPosition = savedPosition;
@@ -47,7 +51,9 @@ var LogAdapter = class {
     } else {
       this.lastReadPosition = 0;
     }
-    this.pollTimer = setInterval(() => this.poll(), this.pollIntervalMs);
+    this.pollTimer = setInterval(() => {
+      this.pollInFlight = this.poll();
+    }, this.pollIntervalMs);
     console.log(`LogAdapter watching ${this.logPath} for agent ${this.agentId}`);
   }
   async stop() {
@@ -55,6 +61,13 @@ var LogAdapter = class {
       clearInterval(this.pollTimer);
       this.pollTimer = null;
     }
+    if (this.pollInFlight) {
+      try {
+        await this.pollInFlight;
+      } catch {
+      }
+      this.pollInFlight = null;
+    }
     await this.saveCursor();
     this.running = false;
     this.onEvent = null;
@@ -66,7 +79,6 @@ var LogAdapter = class {
     try {
       const lines = await this.readNewLines();
       for (const line of lines) {
-        if (!this.running) break;
         const event = this.parseLine(line);
         if (event) {
           try {
@@ -194,10 +206,9 @@ var LogAdapter = class {
     try {
       const { writeFile, mkdir } = await import("fs/promises");
       await mkdir(this.stateDir, { recursive: true });
-      await writeFile(
-        path,
-        JSON.stringify({ position: this.lastReadPosition, logPath: this.logPath }) + "\n"
-      );
+      const fragmentBytes = Buffer.byteLength(this.pendingFragment, "utf-8");
+      const position = Math.max(0, this.lastReadPosition - fragmentBytes);
+      await writeFile(path, JSON.stringify({ position, logPath: this.logPath }) + "\n");
     } catch (err) {
       console.warn(`Failed to save log cursor: ${err}`);
     }
@@ -235,4 +246,4 @@ var LogAdapter = class {
 export {
   LogAdapter
 };
-//# sourceMappingURL=chunk-PDWWRZXF.js.map
+//# sourceMappingURL=chunk-2IPSTUNH.js.map

package/dist/chunk-B6S2PBS4.js

@@ -0,0 +1,47 @@
+// src/setup/policyDiscovery.ts
+import { existsSync, statSync } from "fs";
+import { resolve, join, dirname } from "path";
+function isTrustedPolicyStat(stats, processUid) {
+  if ((stats.mode & 2) !== 0) {
+    return { trusted: false, reason: "file is world-writable" };
+  }
+  if (processUid !== void 0 && stats.uid !== processUid) {
+    return {
+      trusted: false,
+      reason: `file is owned by uid ${stats.uid}, not the current user (uid ${processUid})`
+    };
+  }
+  return { trusted: true, reason: null };
+}
+function isTrustedOnDisk(candidate) {
+  if (process.platform === "win32") return true;
+  let stats;
+  try {
+    stats = statSync(candidate);
+  } catch {
+    return false;
+  }
+  const processUid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  const verdict = isTrustedPolicyStat({ uid: stats.uid, mode: stats.mode }, processUid);
+  if (!verdict.trusted) {
+    console.warn(`[Sentinel] Ignoring untrusted policy file ${candidate}: ${verdict.reason}`);
+  }
+  return verdict.trusted;
+}
+function discoverPolicy(startDir, home) {
+  let dir = resolve(startDir);
+  const homeAbs = resolve(home);
+  while (true) {
+    const candidate = join(dir, ".sentinel.yaml");
+    if (existsSync(candidate) && isTrustedOnDisk(candidate)) return candidate;
+    if (dir === homeAbs) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export {
+  discoverPolicy
+};
+//# sourceMappingURL=chunk-B6S2PBS4.js.map