@jamaynor/hal-config 1.0.1

package/publish.ps1

@@ -0,0 +1,30 @@
+$ErrorActionPreference = 'Stop'
+
+Write-Host "Publishing @jamaynor/hal-config from this directory..."
+
+# Prompt for token without echoing it to the console.
+$secure = Read-Host -Prompt "Paste npm automation token (input hidden)" -AsSecureString
+$token  = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
+  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+)
+
+if (-not $token -or -not $token.Trim()) {
+  throw "No token provided."
+}
+
+try {
+  $env:NPM_TOKEN = $token.Trim()
+
+  Write-Host ""
+  Write-Host "npm whoami:"
+  npm whoami
+
+  Write-Host ""
+  Write-Host "npm publish:"
+  npm publish
+} finally {
+  Remove-Item Env:NPM_TOKEN -ErrorAction SilentlyContinue
+  # Reduce lifetime of plaintext token in memory.
+  $token = $null
+}
+

package/security/access-control.js

@@ -0,0 +1,308 @@
+/**
+ * security/access-control.js
+ *
+ * Responsibility: Gate every file-path and URL against security rules, blocking
+ * directory traversal, sensitive filename/extension access, and outbound requests
+ * to private/reserved network ranges.
+ *
+ * Memory-file protection notice:
+ *   SOUL.md and AGENTS.md are on the filename deny list. Code must NEVER
+ *   write to those files or to any OpenClaw config files under any circumstances.
+ *
+ * All file paths are assumed to be POSIX-style (skills run inside a Linux
+ * Docker container). path/posix is used explicitly for consistent normalization
+ * across Linux (production) and Windows (local development/testing).
+ *
+ * Public Interface:
+ * access-control
+ * ├── validatePath(filePath, allowedDirs) → { allowed: true }
+ * │                                       | { allowed: false, reason: string }
+ * ├── validateUrl(url, resolver?) → Promise<{ allowed: true }>
+ * │                               | Promise<{ allowed: false, reason: string }>
+ * └── validateFilename(name) → { allowed: true }
+ *                            | { allowed: false, reason: string }
+ */
+
+import { realpathSync } from 'node:fs';
+import { posix } from 'node:path';
+import { promisify } from 'node:util';
+import { lookup } from 'node:dns';
+
+const dnsLookup = promisify(lookup);
+
+// Use POSIX path semantics throughout — all skill paths are Unix-style.
+const { normalize: posixNormalize, basename, extname } = posix;
+
+// ---------------------------------------------------------------------------
+// Deny lists
+// ---------------------------------------------------------------------------
+
+// Sensitive filenames that must never be accessed regardless of directory.
+// SOUL.md and AGENTS.md are included to prevent memory-file poisoning attacks.
+const DENIED_FILENAMES = new Set([
+  '.env',
+  'credentials.json',
+  'id_rsa',
+  'id_rsa.pub',
+  'id_ed25519',
+  'id_ed25519.pub',
+  'id_ecdsa',
+  'id_ecdsa.pub',
+  'id_dsa',
+  'id_dsa.pub',
+  // OpenClaw memory files — writing to these creates a permanent backdoor
+  'SOUL.md',
+  'AGENTS.md',
+  // OpenClaw config filenames
+  'system-config.json',
+  'hal-skills.json',
+  'security-checksums.json',
+]);
+
+// Sensitive file extensions that must never be accessed.
+const DENIED_EXTENSIONS = new Set([
+  '.pem',
+  '.key',
+  '.p12',
+  '.pfx',
+  '.cer',
+  '.crt',
+  '.der',
+]);
+
+// ---------------------------------------------------------------------------
+// Private IP range detection helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a dotted-decimal IPv4 address string into its four octets.
+ * Returns null if the string is not a valid IPv4 address.
+ * @param {string} ip
+ * @returns {number[] | null}
+ */
+function parseIPv4Octets(ip) {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return null;
+  const octets = parts.map(Number);
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
+  return octets;
+}
+
+/**
+ * Return a reserved-range descriptor if the IP string falls within a reserved or
+ * private range, or { reserved: false } if the IP is publicly routable.
+ * @param {string} ip
+ * @returns {{ reserved: true, reason: string } | { reserved: false }}
+ */
+function checkReservedIP(ip) {
+  const octets = parseIPv4Octets(ip);
+  if (!octets) {
+    return { reserved: false };
+  }
+
+  const [a, b] = octets;
+
+  if (a === 127) {
+    return { reserved: true, reason: `loopback address (${ip})` };
+  }
+  if (a === 10) {
+    return { reserved: true, reason: `private RFC 1918 address (${ip}) — 10.x range` };
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return { reserved: true, reason: `private RFC 1918 address (${ip}) — 172.16-31.x range` };
+  }
+  if (a === 192 && b === 168) {
+    return { reserved: true, reason: `private RFC 1918 address (${ip}) — 192.168.x range` };
+  }
+  if (a === 169 && b === 254) {
+    return { reserved: true, reason: `link-local address (${ip})` };
+  }
+
+  return { reserved: false };
+}
+
+// Patterns that identify private/reserved IP literals embedded in a hostname string.
+const EMBEDDED_PRIVATE_IP_PATTERNS = [
+  /(?:^|\.)127\.\d{1,3}\.\d{1,3}\.\d{1,3}(?:\.|$)/,                   // loopback embedded
+  /(?:^|\.)10\.\d{1,3}\.\d{1,3}\.\d{1,3}(?:\.|$)/,                    // RFC 1918 10.x
+  /(?:^|\.)192\.168\.\d{1,3}\.\d{1,3}(?:\.|$)/,                       // RFC 1918 192.168.x
+  /(?:^|\.)172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}(?:\.|$)/,     // RFC 1918 172.16-31
+  /(?:^|\.)169\.254\.\d{1,3}\.\d{1,3}(?:\.|$)/,                       // link-local
+];
+
+/**
+ * Return true if a hostname string contains an embedded private IP literal.
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function containsEmbeddedPrivateIP(hostname) {
+  return EMBEDDED_PRIVATE_IP_PATTERNS.some((re) => re.test(hostname));
+}
+
+// ---------------------------------------------------------------------------
+// Path normalization helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a POSIX-style file path string, collapsing any `..` traversal sequences.
+ * @param {string} filePath
+ * @returns {string}
+ */
+function normalizePosixPath(filePath) {
+  const abs = filePath.startsWith('/') ? filePath : `/${filePath}`;
+  return posixNormalize(abs);
+}
+
+// ---------------------------------------------------------------------------
+// validateFilename
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a filename (basename only, no directory) is safe to access.
+ * Checks against the filename deny list and the extension deny list.
+ *
+ * @param {string} name — the filename (basename) to validate
+ * @returns {{ allowed: true } | { allowed: false, reason: string }}
+ */
+export function validateFilename(name) {
+  const lower = name.toLowerCase();
+  if (DENIED_FILENAMES.has(name) || DENIED_FILENAMES.has(lower)) {
+    return { allowed: false, reason: `access denied: filename '${name}' is on the security deny list` };
+  }
+  const ext = lower.slice(lower.lastIndexOf('.'));
+  if (ext && ext !== lower && DENIED_EXTENSIONS.has(ext)) {
+    return { allowed: false, reason: `access denied: extension '${ext}' is on the security deny list` };
+  }
+  return { allowed: true };
+}
+
+// ---------------------------------------------------------------------------
+// validatePath
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a file path is safe to access.
+ *
+ * Resolution order:
+ *  1. Attempt to resolve symlinks via fs.realpathSync.
+ *     If the path does not exist, fall back to posix normalize.
+ *  2. Check the basename against the filename deny list and extension deny list
+ *     via validateFilename().
+ *  3. Check that the resolved path starts with one of the allowedDirs.
+ *
+ * @param {string} filePath      — the POSIX file path to validate
+ * @param {string[]} allowedDirs — list of allowed workspace directory prefixes (POSIX)
+ * @returns {{ allowed: true } | { allowed: false, reason: string }}
+ */
+export function validatePath(filePath, allowedDirs = []) {
+  // Step 1 — Resolve the canonical path.
+  let resolvedPath;
+  try {
+    resolvedPath = realpathSync(filePath);
+    // On Windows, realpathSync returns a Windows path — convert to POSIX.
+    resolvedPath = resolvedPath.replace(/\\/g, '/');
+    // Strip any Windows drive prefix (e.g. "C:") so POSIX path comparison is clean.
+    resolvedPath = resolvedPath.replace(/^[A-Za-z]:/, '');
+  } catch {
+    resolvedPath = normalizePosixPath(filePath);
+  }
+
+  // Step 2 — Filename and extension deny-list check via validateFilename.
+  const name = basename(resolvedPath);
+  const filenameCheck = validateFilename(name);
+  if (!filenameCheck.allowed) {
+    return filenameCheck;
+  }
+
+  // Step 3 — Verify the resolved path is within one of the allowed directories.
+  if (allowedDirs.length > 0) {
+    const withinAllowed = allowedDirs.some((dir) => {
+      const normalizedDir = posixNormalize(dir);
+      return (
+        resolvedPath === normalizedDir ||
+        resolvedPath.startsWith(normalizedDir + '/')
+      );
+    });
+
+    if (!withinAllowed) {
+      return {
+        allowed: false,
+        reason: `access denied: path '${resolvedPath}' is outside the allowed workspace directories`,
+      };
+    }
+  }
+
+  return { allowed: true };
+}
+
+// ---------------------------------------------------------------------------
+// validateUrl
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a URL is safe to request.
+ *
+ * Checks performed:
+ *  1. Only http and https schemes are permitted.
+ *  2. The hostname is inspected for embedded private IP literals.
+ *  3. The hostname is resolved and checked against reserved ranges.
+ *
+ * @param {string} url          — the URL to validate
+ * @param {((hostname: string) => Promise<string>) | undefined} [resolver]
+ *   Optional DNS resolver for dependency injection in tests.
+ * @returns {Promise<{ allowed: true } | { allowed: false, reason: string }>}
+ */
+export async function validateUrl(url, resolver) {
+  // Step 1 — Parse the URL; reject malformed URLs.
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { allowed: false, reason: `access denied: URL '${url}' could not be parsed` };
+  }
+
+  // Step 2 — Scheme check: only http and https are permitted.
+  const scheme = parsed.protocol.replace(/:$/, '');
+  if (scheme !== 'http' && scheme !== 'https') {
+    return {
+      allowed: false,
+      reason: `access denied: URL scheme '${scheme}' is not allowed; only http and https are permitted`,
+    };
+  }
+
+  const hostname = parsed.hostname;
+
+  // Step 3 — DNS rebinding bypass: reject hostnames containing embedded private IP literals.
+  if (containsEmbeddedPrivateIP(hostname)) {
+    return {
+      allowed: false,
+      reason: `access denied: hostname '${hostname}' contains an embedded private or reserved IP address (DNS rebinding bypass pattern)`,
+    };
+  }
+
+  // Step 4 — DNS resolution: resolve the hostname and check the IP against reserved ranges.
+  let resolvedIP;
+  try {
+    if (typeof resolver === 'function') {
+      resolvedIP = await resolver(hostname);
+    } else {
+      const result = await dnsLookup(hostname, { family: 4 });
+      resolvedIP = result.address;
+    }
+  } catch (err) {
+    return {
+      allowed: false,
+      reason: `access denied: DNS resolution failed for '${hostname}': ${err.message}`,
+    };
+  }
+
+  const ipCheck = checkReservedIP(resolvedIP);
+  if (ipCheck.reserved) {
+    return {
+      allowed: false,
+      reason: `access denied: URL resolves to a reserved address — ${ipCheck.reason}`,
+    };
+  }
+
+  return { allowed: true };
+}

package/security/governor.js

@@ -0,0 +1,313 @@
+/**
+ * security/governor.js
+ *
+ * Responsibility: Runtime governor class — wraps LLM calls with spend limits,
+ * volume limits, a lifetime counter, and duplicate-prompt detection.
+ * All state is in-memory; no persistence across process restarts.
+ * Exports the class and defaults so each skill instantiates its own governor.
+ *
+ * Public Interface:
+ * governor
+ * ├── Governor                  — class; construct with optional config overrides
+ * │   ├── register(callerName, overrides) → void
+ * │   ├── wrap(callerName, callFn, opts)  → Promise<any>
+ * │   ├── stats()                         → GovernorStats
+ * │   └── resetForTesting(cfg?)           → void
+ * ├── GovernorError             — Error subclass with .code property
+ * └── DEFAULTS                  — default config object (callers: {} — skills register own)
+ */
+
+import { createHash } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Default configuration — all values are overridable via skill config
+// ---------------------------------------------------------------------------
+export const DEFAULTS = {
+  spendWarnThreshold:      5.00,   // USD per window before warning
+  spendHardCapThreshold:  15.00,   // USD per window before hard cap
+  spendWindowMinutes:       5,     // rolling window duration
+  volumeGlobalCap:        200,     // global call count per window
+  volumeWindowMinutes:     10,     // rolling window duration for volume
+  lifetimeCap:            300,     // absolute call count for this process
+  duplicateCacheTtlSeconds: 300,   // TTL for duplicate-prompt cache entries
+  callers: {},  // empty — skills register their own callers
+};
+
+// ---------------------------------------------------------------------------
+// GovernorError — thrown by wrap() when a limit is exceeded.
+// ---------------------------------------------------------------------------
+export class GovernorError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'GovernorError';
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Governor — in-memory class that tracks spend, volume, and prompt hashes.
+// ---------------------------------------------------------------------------
+export class Governor {
+  #cfg;
+
+  // Spend tracking: array of { timestampMs, costUsd }
+  #spendWindow = [];
+
+  // Volume tracking: global window and per-caller windows
+  // Each entry: { timestampMs }
+  #globalVolumeWindow = [];
+  #callerVolumeWindows = new Map();  // callerName → [{ timestampMs }]
+
+  // Lifetime counter
+  #lifetimeCount = 0;
+
+  // Per-caller registered overrides (from register())
+  #callerOverrides = new Map();
+
+  // Duplicate-detection: promptHash → { response, expiresMs }
+  #promptCache = new Map();
+
+  // Per-caller aggregate stats (total calls, all-time)
+  #callerStats = new Map();
+
+  constructor(cfg = {}) {
+    this.#cfg = this.#mergeConfig(cfg);
+  }
+
+  // -------------------------------------------------------------------------
+  // register(callerName, overrides)
+  // Registers a named caller with per-caller config overrides.
+  // -------------------------------------------------------------------------
+  register(callerName, overrides = {}) {
+    const existing = this.#callerOverrides.get(callerName) ?? {};
+    this.#callerOverrides.set(callerName, { ...existing, ...overrides });
+  }
+
+  // -------------------------------------------------------------------------
+  // wrap(callerName, callFn, opts) → Promise<any>
+  // Applies all governor checks before calling callFn.
+  //
+  // opts: {
+  //   promptText?:   string,   // text to hash for duplicate detection
+  //   estimatedCost?: number,  // USD to debit against the spend window
+  //   bypassCache?:  boolean,  // skip duplicate detection
+  // }
+  // -------------------------------------------------------------------------
+  async wrap(callerName, callFn, opts = {}) {
+    this.#pruneWindows();
+
+    // 1. Lifetime cap
+    this.#checkLifetimeCap();
+
+    // 2. Spend hard cap
+    this.#checkSpendCap();
+
+    // 3. Volume cap — global then per-caller
+    this.#checkGlobalVolumeCap();
+    this.#checkCallerVolumeCap(callerName);
+
+    // 4. Duplicate detection
+    if (!opts.bypassCache && opts.promptText !== undefined) {
+      const cached = this.#getCached(opts.promptText);
+      if (cached !== undefined) {
+        return cached;
+      }
+    }
+
+    // 5. Execute the call
+    const nowMs = Date.now();
+    const result = await callFn();
+
+    // 6. Record the call
+    this.#lifetimeCount += 1;
+
+    const cost = typeof opts.estimatedCost === 'number' ? opts.estimatedCost : 0;
+    this.#spendWindow.push({ timestampMs: nowMs, costUsd: cost });
+    this.#globalVolumeWindow.push({ timestampMs: nowMs });
+    this.#recordCallerVolume(callerName, nowMs);
+    this.#updateCallerStats(callerName);
+
+    // Warn on spend threshold
+    const windowSpend = this.#currentWindowSpend();
+    if (windowSpend > this.#cfg.spendWarnThreshold) {
+      console.warn(
+        `[governor] spend warning: $${windowSpend.toFixed(4)} in last ` +
+        `${this.#cfg.spendWindowMinutes} min (threshold $${this.#cfg.spendWarnThreshold})`
+      );
+    }
+
+    // 7. Cache the response for duplicate detection
+    if (!opts.bypassCache && opts.promptText !== undefined) {
+      this.#cacheResponse(opts.promptText, result);
+    }
+
+    return result;
+  }
+
+  // -------------------------------------------------------------------------
+  // stats() → GovernorStats
+  // Returns a snapshot of the current governor state.
+  // -------------------------------------------------------------------------
+  stats() {
+    this.#pruneWindows();
+
+    const callers = {};
+    for (const [name, entry] of this.#callerStats.entries()) {
+      const windowEntries = this.#callerVolumeWindows.get(name) ?? [];
+      callers[name] = {
+        count:       entry.count,
+        windowCount: windowEntries.length,
+      };
+    }
+
+    return {
+      windowSpendUsd: this.#currentWindowSpend(),
+      lifetimeCount:  this.#lifetimeCount,
+      callers,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // resetForTesting() — resets all in-memory state.
+  // Not part of the production API; exposed for test isolation only.
+  // -------------------------------------------------------------------------
+  resetForTesting(cfg = {}) {
+    this.#cfg                = this.#mergeConfig(cfg);
+    this.#spendWindow        = [];
+    this.#globalVolumeWindow = [];
+    this.#callerVolumeWindows.clear();
+    this.#callerOverrides.clear();
+    this.#promptCache.clear();
+    this.#callerStats.clear();
+    this.#lifetimeCount      = 0;
+  }
+
+  // =========================================================================
+  // Private helpers
+  // =========================================================================
+
+  #mergeConfig(overrides) {
+    const govOverrides = overrides?.governor ?? overrides ?? {};
+    return {
+      spendWarnThreshold:       govOverrides.spendWarnThreshold      ?? DEFAULTS.spendWarnThreshold,
+      spendHardCapThreshold:    govOverrides.spendHardCapThreshold   ?? DEFAULTS.spendHardCapThreshold,
+      spendWindowMinutes:       govOverrides.spendWindowMinutes      ?? DEFAULTS.spendWindowMinutes,
+      volumeGlobalCap:          govOverrides.volumeGlobalCap         ?? DEFAULTS.volumeGlobalCap,
+      volumeWindowMinutes:      govOverrides.volumeWindowMinutes     ?? DEFAULTS.volumeWindowMinutes,
+      lifetimeCap:              govOverrides.lifetimeCap             ?? DEFAULTS.lifetimeCap,
+      duplicateCacheTtlSeconds: govOverrides.duplicateCacheTtlSeconds ?? DEFAULTS.duplicateCacheTtlSeconds,
+      callers: {
+        ...DEFAULTS.callers,
+        ...(govOverrides.callers ?? {}),
+      },
+    };
+  }
+
+  // Remove expired entries from all sliding windows.
+  #pruneWindows() {
+    const nowMs = Date.now();
+    const spendCutoff  = nowMs - this.#cfg.spendWindowMinutes  * 60_000;
+    const volCutoff    = nowMs - this.#cfg.volumeWindowMinutes * 60_000;
+
+    this.#spendWindow        = this.#spendWindow.filter(e => e.timestampMs >= spendCutoff);
+    this.#globalVolumeWindow = this.#globalVolumeWindow.filter(e => e.timestampMs >= volCutoff);
+
+    for (const [name, window] of this.#callerVolumeWindows.entries()) {
+      this.#callerVolumeWindows.set(name, window.filter(e => e.timestampMs >= volCutoff));
+    }
+
+    // Evict expired prompt cache entries.
+    for (const [hash, entry] of this.#promptCache.entries()) {
+      if (entry.expiresMs <= nowMs) {
+        this.#promptCache.delete(hash);
+      }
+    }
+  }
+
+  #currentWindowSpend() {
+    return this.#spendWindow.reduce((sum, e) => sum + e.costUsd, 0);
+  }
+
+  #checkLifetimeCap() {
+    if (this.#lifetimeCount >= this.#cfg.lifetimeCap) {
+      throw new GovernorError(
+        `[governor] lifetime cap reached (${this.#lifetimeCount}/${this.#cfg.lifetimeCap} calls)`,
+        'LIFETIME_CAP'
+      );
+    }
+  }
+
+  #checkSpendCap() {
+    const spend = this.#currentWindowSpend();
+    if (spend >= this.#cfg.spendHardCapThreshold) {
+      throw new GovernorError(
+        `[governor] spend hard cap reached ($${spend.toFixed(4)} >= ` +
+        `$${this.#cfg.spendHardCapThreshold} in ${this.#cfg.spendWindowMinutes} min)`,
+        'SPEND_CAP'
+      );
+    }
+  }
+
+  #checkGlobalVolumeCap() {
+    if (this.#globalVolumeWindow.length >= this.#cfg.volumeGlobalCap) {
+      throw new GovernorError(
+        `[governor] global volume cap reached (${this.#globalVolumeWindow.length}/` +
+        `${this.#cfg.volumeGlobalCap} calls in ${this.#cfg.volumeWindowMinutes} min)`,
+        'VOLUME_CAP'
+      );
+    }
+  }
+
+  #checkCallerVolumeCap(callerName) {
+    const callerCfg    = this.#resolveCallerConfig(callerName);
+    const callerWindow = this.#callerVolumeWindows.get(callerName) ?? [];
+
+    if (callerCfg.volumeCap !== undefined && callerWindow.length >= callerCfg.volumeCap) {
+      throw new GovernorError(
+        `[governor] volume cap for '${callerName}' reached ` +
+        `(${callerWindow.length}/${callerCfg.volumeCap} calls in ${this.#cfg.volumeWindowMinutes} min)`,
+        'VOLUME_CAP'
+      );
+    }
+  }
+
+  // Merge per-caller config from: DEFAULTS.callers → cfg.callers → registered overrides.
+  #resolveCallerConfig(callerName) {
+    const fromDefaults   = DEFAULTS.callers[callerName]          ?? {};
+    const fromCfgCallers = this.#cfg.callers[callerName]         ?? {};
+    const fromOverrides  = this.#callerOverrides.get(callerName) ?? {};
+    return { ...fromDefaults, ...fromCfgCallers, ...fromOverrides };
+  }
+
+  #recordCallerVolume(callerName, timestampMs) {
+    const window = this.#callerVolumeWindows.get(callerName) ?? [];
+    window.push({ timestampMs });
+    this.#callerVolumeWindows.set(callerName, window);
+  }
+
+  #updateCallerStats(callerName) {
+    const entry = this.#callerStats.get(callerName) ?? { count: 0 };
+    entry.count += 1;
+    this.#callerStats.set(callerName, entry);
+  }
+
+  // SHA-256 hash of the prompt string for cache key.
+  #hashPrompt(promptText) {
+    return createHash('sha256').update(promptText).digest('hex');
+  }
+
+  #getCached(promptText) {
+    const hash  = this.#hashPrompt(promptText);
+    const entry = this.#promptCache.get(hash);
+    if (entry && entry.expiresMs > Date.now()) {
+      return entry.response;
+    }
+    return undefined;
+  }
+
+  #cacheResponse(promptText, response) {
+    const hash      = this.#hashPrompt(promptText);
+    const expiresMs = Date.now() + this.#cfg.duplicateCacheTtlSeconds * 1000;
+    this.#promptCache.set(hash, { response, expiresMs });
+  }
+}

package/security/index.js

@@ -0,0 +1,31 @@
+/**
+ * security/index.js
+ *
+ * Responsibility: Barrel file — re-exports all security modules under a
+ * structured namespace for consumers that want a single require point.
+ *
+ * Public Interface:
+ * security
+ * ├── sanitize.text(text, opts?)                    → { cleaned, stats }
+ * ├── redact.secrets(text)                          → string
+ * ├── redact.pii(text, config)                      → string
+ * ├── redact.all(text, config)                      → string
+ * ├── validate.path(filePath, allowedDirs)          → { allowed, reason? }
+ * ├── validate.url(url, resolver?)                  → Promise<{ allowed, reason? }>
+ * ├── validate.filename(name)                       → { allowed, reason? }
+ * ├── governor.create(opts?)                        → Governor instance
+ * ├── governor.GovernorError                        → GovernorError class
+ * └── governor.DEFAULTS                             → default config object
+ */
+
+import { sanitize } from './sanitizer.js';
+import { redactSecrets, redactPii, redactNotification } from './redactor.js';
+import { validatePath, validateUrl, validateFilename } from './access-control.js';
+import { Governor, GovernorError, DEFAULTS } from './governor.js';
+
+export default {
+  sanitize: { text: sanitize },
+  redact: { secrets: redactSecrets, pii: redactPii, all: redactNotification },
+  validate: { path: validatePath, url: validateUrl, filename: validateFilename },
+  governor: { create: (opts) => new Governor(opts), GovernorError, DEFAULTS },
+};