@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/org/policy.ts

@@ -0,0 +1,398 @@
+// brain org: the organisation's content policy, as pure functions. No I/O, no model.
+//
+// Used twice: by the client (a courtesy: denied items never leave the machine) and by the server (the real check: it never
+// trusts the client). Both call the same code, so the answers cannot drift.
+//
+// Everything here is written to be run on hostile input:
+//   * globs are matched by a segment-level matcher, never compiled to a regex, so a glob cannot cause backtracking;
+//   * regex deny terms (`/pattern/flags`) are accepted only when a static guard proves they cannot backtrack badly
+//     (no nested or overlapping repetition, no backreferences, no lookaround, at most two unbounded repeats, 200 chars);
+//     a term that fails the guard is rejected by normalizePolicy; if one still reaches checkItem it FAILS CLOSED (item refused).
+
+import type { MemoryItem, MemoryKind } from "../memory/types.ts"
+import { DEFAULT_POLICY, SCOPES, scopeRank } from "./types.ts"
+import type { Policy, Scope } from "./types.ts"
+
+export const MEMORY_KINDS: MemoryKind[] = ["decision", "constraint", "preference", "failed", "file", "command", "summary", "state"]
+
+const MAX_GLOB = 500
+const MAX_TERM = 500
+const MAX_ENTRIES = 500
+const MAX_REGEX = 200
+/** Items bigger than this (all text fields together) are refused rather than scanned partly: a partial scan would be a bypass. */
+const MAX_ITEM_CHARS = 64_000
+const MAX_UNBOUNDED_REPEATS = 2
+
+// ---- paths and globs ----------------------------------------------------------------------------------------------
+
+/** Splits a path (or glob) into segments: `\` counts as `/`, a leading `./`, `~/`, `/` or drive (`C:/`) is dropped, `.` and `..` are resolved. */
+function segmentsOf(p: string, keepWild = false): string[] {
+  let s = p.replace(/\\/g, "/")
+  s = s.replace(/^[A-Za-z]:(?=\/|$)/, "")
+  const out: string[] = []
+  for (const seg of s.split("/")) {
+    if (seg === "" || seg === ".") continue
+    if (seg === "~" && out.length === 0) continue
+    if (seg === "..") {
+      if (!keepWild || out.length > 0) out.pop()
+      continue
+    }
+    out.push(seg)
+  }
+  return out
+}
+
+/** `*` and `?` inside one segment; iterative, linear-ish, no regex. */
+function segMatch(pat: string, s: string): boolean {
+  let p = 0
+  let i = 0
+  let star = -1
+  let mark = 0
+  while (i < s.length) {
+    if (p < pat.length && (pat[p] === "?" || pat[p] === s[i]) && pat[p] !== "*") {
+      p++
+      i++
+    } else if (p < pat.length && pat[p] === "*") {
+      star = p++
+      mark = i
+    } else if (star >= 0) {
+      p = star + 1
+      i = ++mark
+    } else return false
+  }
+  while (p < pat.length && pat[p] === "*") p++
+  return p === pat.length
+}
+
+function matchSegs(g: string[], s: string[]): boolean {
+  // dp over (glob index, path index); a `**` segment matches zero or more whole segments.
+  const gl = g.length
+  const sl = s.length
+  let row: boolean[] = new Array(sl + 1).fill(false)
+  row[sl] = true
+  for (let gi = gl - 1; gi >= 0; gi--) {
+    const next: boolean[] = new Array(sl + 1).fill(false)
+    const isStar2 = g[gi] === "**"
+    for (let si = sl; si >= 0; si--) {
+      if (isStar2) next[si] = row[si] === true || (si < sl && next[si + 1] === true)
+      else next[si] = si < sl && row[si + 1] === true && segMatch(g[gi]!, s[si]!)
+    }
+    row = next
+  }
+  return row[0] === true
+}
+
+/**
+ * Case-sensitive, anchored glob match on `/`-separated paths (`\` is read as `/`).
+ *   `*`  any characters within one segment      `?`  one character within a segment      `**`  (as a whole segment) any number of segments
+ * A leading `./`, `~/`, `/` or drive letter is ignored on both sides, and `.`/`..` segments are resolved in the path.
+ * A glob that names a directory matches everything under it and the directory itself: `secrets/**` matches `secrets`, `secrets/a/b.txt`.
+ * So does a plain `secrets` (every ancestor directory of the path is tried).
+ */
+export function globMatch(glob: string, path: string): boolean {
+  if (typeof glob !== "string" || typeof path !== "string" || glob.length === 0 || glob.length > MAX_GLOB) return false
+  // Collapse `a**b` inside a segment to `a*b`; a segment of only stars becomes `**`.
+  const g = segmentsOf(glob, true).map((x) => (/^\*{2,}$/.test(x) ? "**" : x.replace(/\*{2,}/g, "*")))
+  if (g.length === 0) return false
+  const s = segmentsOf(path)
+  for (let n = s.length; n >= 1; n--) if (matchSegs(g, s.slice(0, n))) return true
+  return false
+}
+
+/** Like globMatch, but also when the glob matches any trailing part of the path: `secrets/**` catches `/home/me/app/secrets/k.pem`. Denial errs on the side of denying. */
+function globHits(glob: string, path: string): boolean {
+  const s = segmentsOf(path)
+  for (let from = 0; from < s.length; from++) if (globMatch(glob, s.slice(from).join("/"))) return true
+  return false
+}
+
+const EXTENSIONS = new Set(
+  (
+    "ts tsx js jsx mjs cjs json jsonc yaml yml toml ini cfg conf env pem key crt cer p12 pfx kdbx md txt log csv tsv sql db sqlite " +
+    "py rb go rs java kt swift c h cc cpp hpp cs php sh bash zsh fish ps1 bat cmd html htm css scss less vue svelte xml lock " +
+    "tf tfvars hcl dockerfile gradle properties plist npmrc netrc pdf docx xlsx pptx zip tar gz tgz"
+  ).split(" "),
+)
+
+const stripTail = (t: string): string =>
+  t
+    .replace(/(?::\d+)+$/, "") // file.ts:12:3
+    .replace(/[.,:;!?]+$/, "")
+
+/** Tokens in a text that look like file paths: contain a `/` (or `\`), or end in a known extension, or are dotfiles like `.env`; not URLs. Backslashes come back as `/`. */
+export function pathsIn(text: string): string[] {
+  if (typeof text !== "string" || text.length === 0) return []
+  const noUrls = text.replace(/[A-Za-z][A-Za-z0-9+.-]*:\/\/\S*/g, " ").replace(/\bwww\.\S*/gi, " ").replace(/\bmailto:\S*/gi, " ")
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const raw of noUrls.split(/[\s"'`()[\]{}<>,;|=*]+/)) {
+    if (!raw) continue
+    // `PATH=/a:/b`-style lists: split on a colon that starts another path, but keep `C:\` drive prefixes.
+    const drive = /^[A-Za-z]:[\\/]/.test(raw) ? raw.slice(0, 2) : ""
+    const rest = drive ? raw.slice(2) : raw
+    const parts = rest.split(/:(?=[\\/~]|\.\.?[\\/])/)
+    parts.forEach((part, idx) => {
+      const tok = stripTail((idx === 0 ? drive : "") + part).replace(/\\/g, "/")
+      if (tok.length < 2 || tok.length > 1000) return
+      if (!/[A-Za-z0-9_]/.test(tok)) return
+      let isPath = tok.includes("/")
+      if (!isPath) {
+        const dot = tok.lastIndexOf(".")
+        if (dot >= 0 && dot < tok.length - 1) isPath = EXTENSIONS.has(tok.slice(dot + 1).toLowerCase()) && /^[\w.@+-]+$/.test(tok)
+        if (!isPath && /^\.[A-Za-z][\w-]{2,}(\.[\w-]+)*$/.test(tok)) isPath = true
+      }
+      if (isPath && !seen.has(tok)) {
+        seen.add(tok)
+        out.push(tok)
+      }
+    })
+  }
+  return out
+}
+
+// ---- deny terms: substrings and guarded regexes -------------------------------------------------------------------
+
+interface Quant {
+  len: number
+  /** Can repeat (max > 1). */
+  loops: boolean
+  /** No upper bound, or a large one. */
+  unbounded: boolean
+}
+
+function quantAt(src: string, i: number): Quant | undefined {
+  const c = src[i]
+  let q: Quant | undefined
+  if (c === "*" || c === "+") q = { len: 1, loops: true, unbounded: true }
+  else if (c === "?") q = { len: 1, loops: false, unbounded: false }
+  else if (c === "{") {
+    const m = /^\{(\d+)(?:(,)(\d*))?\}/.exec(src.slice(i, i + 24))
+    if (m) {
+      const min = Number(m[1])
+      const max = m[2] ? (m[3] === "" ? Infinity : Number(m[3])) : min
+      q = { len: m[0].length, loops: max > 1, unbounded: max > 50 }
+    }
+  }
+  if (q && src[i + q.len] === "?") q.len++ // lazy
+  return q
+}
+
+/** Throws a plain Error saying why a regex deny term is refused. Returns the compiled RegExp when it is safe. */
+export function safeRegex(src: string, flags: string): RegExp {
+  if (src.length === 0) throw new Error("empty regex")
+  if (src.length > MAX_REGEX) throw new Error(`regex longer than ${MAX_REGEX} characters`)
+  if (!/^[imsu]*$/.test(flags) || new Set(flags).size !== flags.length) throw new Error(`unsupported regex flags "${flags}" (allowed: i m s u)`)
+  if (/\(\?<?[=!]/.test(src)) throw new Error("lookahead and lookbehind are not allowed")
+  type Frame = { quant: boolean; alt: boolean }
+  const stack: Frame[] = [{ quant: false, alt: false }]
+  let unbounded = 0
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i]!
+    if (c === "\\") {
+      const n = src[i + 1]
+      if (n === undefined) throw new Error("dangling backslash")
+      if (/[1-9]/.test(n) || n === "k") throw new Error("backreferences are not allowed")
+      i++
+      const q = quantAt(src, i + 1)
+      if (q) {
+        stack[stack.length - 1]!.quant = true
+        if (q.unbounded) unbounded++
+        i += q.len
+      }
+      continue
+    }
+    if (c === "[") {
+      let j = i + 1
+      if (src[j] === "^") j++
+      if (src[j] === "]") j++
+      while (j < src.length && src[j] !== "]") j += src[j] === "\\" ? 2 : 1
+      if (j >= src.length) throw new Error("unterminated character class")
+      i = j
+      const q = quantAt(src, i + 1)
+      if (q) {
+        stack[stack.length - 1]!.quant = true
+        if (q.unbounded) unbounded++
+        i += q.len
+      }
+      continue
+    }
+    if (c === "(") {
+      stack.push({ quant: false, alt: false })
+      if (src[i + 1] === "?") {
+        if (src[i + 2] === ":") i += 2
+        else if (src[i + 2] === "<" && /^\(\?<[A-Za-z_$][\w$]*>/.test(src.slice(i, i + 40))) i = src.indexOf(">", i)
+        else throw new Error("only plain and non-capturing groups are allowed")
+      }
+      continue
+    }
+    if (c === ")") {
+      if (stack.length < 2) throw new Error("unbalanced parenthesis")
+      const f = stack.pop()!
+      const q = quantAt(src, i + 1)
+      const parent = stack[stack.length - 1]!
+      if (q) {
+        if (q.loops && (f.quant || f.alt)) throw new Error("a repeated group may not contain another repeat or an alternation (catastrophic backtracking)")
+        if (q.unbounded) unbounded++
+        parent.quant = true
+        i += q.len
+      } else if (f.quant) parent.quant = true
+      continue
+    }
+    if (c === "|") {
+      stack[stack.length - 1]!.alt = true
+      continue
+    }
+    const q = quantAt(src, i + 1)
+    if (q) {
+      stack[stack.length - 1]!.quant = true
+      if (q.unbounded) unbounded++
+      i += q.len
+    }
+  }
+  if (stack.length !== 1) throw new Error("unbalanced parenthesis")
+  if (unbounded > MAX_UNBOUNDED_REPEATS) throw new Error(`more than ${MAX_UNBOUNDED_REPEATS} unbounded repeats (*, +, {n,}) can backtrack too much`)
+  try {
+    return new RegExp(src, flags)
+  } catch (e) {
+    throw new Error(`invalid regex: ${(e as Error).message}`)
+  }
+}
+
+type Term = { kind: "substr"; needle: string } | { kind: "regex"; re: RegExp }
+
+/** `/pattern/flags` with valid flags is a regex; anything else (`/etc/passwd`, `/usr/bin/`... see the note) is a plain case-insensitive substring. */
+function parseTerm(term: string): Term {
+  const m = /^\/(.+)\/([a-z]*)$/s.exec(term)
+  if (m && /^[imsu]*$/.test(m[2]!) && new Set(m[2]).size === m[2]!.length) return { kind: "regex", re: safeRegex(m[1]!, m[2]!) }
+  return { kind: "substr", needle: term.toLowerCase() }
+}
+
+const termCache = new Map<string, Term | Error>()
+function termFor(term: string): Term | Error {
+  let t = termCache.get(term)
+  if (!t) {
+    try {
+      t = parseTerm(term)
+    } catch (e) {
+      t = e as Error
+    }
+    if (termCache.size > 2000) termCache.clear()
+    termCache.set(term, t)
+  }
+  return t
+}
+
+// ---- checkItem ----------------------------------------------------------------------------------------------------
+
+/** All the text an item carries, in one string. */
+function textOf(item: MemoryItem): string {
+  const parts: string[] = [item.name, item.text]
+  for (const e of item.entities ?? []) parts.push(e.name, e.type ?? "")
+  for (const r of item.relations ?? []) parts.push(r.from, r.to, r.type)
+  for (const p of item.procedures ?? []) parts.push(p.trigger ?? "", p.action)
+  return parts.filter((x) => typeof x === "string").join("\n")
+}
+
+/**
+ * Does the item pass the organisation's policy? Refused when its kind is not allowed, it mentions a denied path, or it contains a denied term.
+ * The reason names the rule (the glob or the term: the policy is visible to every member), never the item's text.
+ */
+export function checkItem(item: MemoryItem, policy: Policy): { ok: true } | { ok: false; reason: string } {
+  if (policy.allowedKinds && !policy.allowedKinds.includes(item.kind)) return { ok: false, reason: `kind "${String(item.kind)}" is not allowed by policy` }
+  const blob = textOf(item)
+  if (blob.length > MAX_ITEM_CHARS) return { ok: false, reason: "item is too large to check against policy" }
+  if (policy.denyPaths.length > 0) {
+    const paths = pathsIn(blob)
+    for (const glob of policy.denyPaths) for (const p of paths) if (globHits(glob, p)) return { ok: false, reason: `mentions a path denied by policy (${glob})` }
+  }
+  if (policy.denyTerms.length > 0) {
+    const lower = blob.toLowerCase()
+    for (const term of policy.denyTerms) {
+      const t = termFor(term)
+      if (t instanceof Error) return { ok: false, reason: `policy term "${term}" is unusable (${t.message}); item refused` }
+      if (t.kind === "substr" ? lower.includes(t.needle) : t.re.test(blob)) return { ok: false, reason: `contains a term denied by policy (${term})` }
+    }
+  }
+  return { ok: true }
+}
+
+// ---- scope --------------------------------------------------------------------------------------------------------
+
+/** The scope an item gets: the requested one (never above `policy.maxScope`), or the policy default (clamped to the ceiling). */
+export function effectiveScope(requested: Scope | undefined, policy: Policy): { ok: true; scope: Scope } | { ok: false; code: "scope_above_policy"; reason: string } {
+  if (requested === undefined) {
+    const d = scopeRank(policy.defaultScope) > scopeRank(policy.maxScope) ? policy.maxScope : policy.defaultScope
+    return { ok: true, scope: d }
+  }
+  if (!SCOPES.includes(requested)) return { ok: false, code: "scope_above_policy", reason: `unknown scope "${String(requested)}"` }
+  if (scopeRank(requested) > scopeRank(policy.maxScope)) {
+    return { ok: false, code: "scope_above_policy", reason: `scope "${requested}" is wider than this organisation allows (maximum: "${policy.maxScope}")` }
+  }
+  return { ok: true, scope: requested }
+}
+
+// ---- normalizePolicy ----------------------------------------------------------------------------------------------
+
+const KEYS = new Set(["maxScope", "defaultScope", "denyPaths", "denyTerms", "allowedKinds", "retentionDays"])
+
+function stringList(name: string, v: unknown, max: number, check?: (s: string) => void): string[] {
+  if (!Array.isArray(v)) throw new Error(`${name} must be an array of strings`)
+  if (v.length > MAX_ENTRIES) throw new Error(`${name} has more than ${MAX_ENTRIES} entries`)
+  const out: string[] = []
+  for (const s of v) {
+    if (typeof s !== "string") throw new Error(`${name} must contain only strings`)
+    if (s.trim().length === 0) throw new Error(`${name} must not contain empty entries`)
+    if (s.length > max) throw new Error(`${name} entry longer than ${max} characters`)
+    if (s.includes("\0")) throw new Error(`${name} entry contains a NUL character`)
+    if (check) check(s)
+    if (!out.includes(s)) out.push(s)
+  }
+  return out
+}
+
+/** Validates a policy as received (a JSON body, a file) and fills the defaults. Throws a plain Error with the reason. Unknown keys are errors. */
+export function normalizePolicy(raw: unknown): Policy {
+  if (raw === undefined) return { ...DEFAULT_POLICY, denyPaths: [], denyTerms: [] }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("policy must be a JSON object")
+  const o = raw as Record<string, unknown>
+  for (const k of Object.keys(o)) if (!KEYS.has(k)) throw new Error(`unknown policy field "${k}"`)
+  const scopeOf = (name: string, v: unknown, fallback: Scope): Scope => {
+    if (v === undefined) return fallback
+    if (typeof v !== "string" || !SCOPES.includes(v as Scope)) throw new Error(`${name} must be one of ${SCOPES.join(", ")}`)
+    return v as Scope
+  }
+  const maxScope = scopeOf("maxScope", o.maxScope, DEFAULT_POLICY.maxScope)
+  const defaultScope = scopeOf("defaultScope", o.defaultScope, DEFAULT_POLICY.defaultScope)
+  if (scopeRank(defaultScope) > scopeRank(maxScope)) throw new Error(`defaultScope "${defaultScope}" is wider than maxScope "${maxScope}"`)
+  const policy: Policy = {
+    maxScope,
+    defaultScope,
+    denyPaths: o.denyPaths === undefined ? [] : stringList("denyPaths", o.denyPaths, MAX_GLOB),
+    denyTerms:
+      o.denyTerms === undefined
+        ? []
+        : stringList("denyTerms", o.denyTerms, MAX_TERM, (s) => {
+            try {
+              parseTerm(s)
+            } catch (e) {
+              throw new Error(`denyTerms entry ${JSON.stringify(s.slice(0, 60))}: ${(e as Error).message}`)
+            }
+          }),
+  }
+  if (o.allowedKinds !== undefined && o.allowedKinds !== null) {
+    if (!Array.isArray(o.allowedKinds)) throw new Error("allowedKinds must be an array of kinds")
+    if (o.allowedKinds.length === 0) throw new Error("allowedKinds must not be empty (omit it to allow every kind)")
+    const kinds: MemoryKind[] = []
+    for (const k of o.allowedKinds) {
+      if (typeof k !== "string" || !MEMORY_KINDS.includes(k as MemoryKind)) throw new Error(`allowedKinds: unknown kind ${JSON.stringify(k)} (known: ${MEMORY_KINDS.join(", ")})`)
+      if (!kinds.includes(k as MemoryKind)) kinds.push(k as MemoryKind)
+    }
+    policy.allowedKinds = kinds
+  }
+  if (o.retentionDays !== undefined && o.retentionDays !== null) {
+    const d = o.retentionDays
+    if (typeof d !== "number" || !Number.isInteger(d) || d < 1 || d > 36500) throw new Error("retentionDays must be a whole number of days between 1 and 36500")
+    policy.retentionDays = d
+  }
+  return policy
+}