@ijfw/memory-server 1.5.6 → 1.6.0

package/src/profile/schema.js

@@ -0,0 +1,244 @@
+/**
+ * profile/schema.js — Cross-system profile bus, P0.1.
+ *
+ * The portable user-profile atom + container schema, plus a lossless
+ * markdown+YAML-frontmatter (de)serialization. ZERO dependencies, Node
+ * built-ins only. NO LLM calls (a later CI guard enforces this module never
+ * reaches the LLM tier).
+ *
+ * Storage format (human-readable + hand-editable, per design-v2 §4):
+ *   ---
+ *   schema_version: N
+ *   <scalar summary frontmatter>
+ *   ---
+ *
+ *   # IJFW User Profile
+ *   ...prose...
+ *
+ *   ```json
+ *   { ...the full structured UserProfile... }
+ *   ```
+ *
+ * The fenced JSON block is the canonical, lossless record (round-trip
+ * identity). The frontmatter carries human-glanceable scalars + the
+ * schema_version. We hand-roll a *minimal* flat-scalar frontmatter
+ * parse/serialize (no YAML dep); nested structure lives in the JSON block so
+ * round-trip fidelity never depends on a hand-rolled recursive YAML parser.
+ */
+
+export const SCHEMA_VERSION = 1;
+
+/** The four EMA+Beta style axes (design-v2 §4). */
+export const STYLE_AXES = Object.freeze(['formality', 'energy', 'terseness', 'emoji_use']);
+
+const SENSITIVITIES = Object.freeze(['low', 'med', 'high']);
+
+/**
+ * Deterministic, stable id for an inference so two sessions deriving the "same"
+ * trait dedupe to one atom on merge. Keyed on kind+subject (NOT value — a
+ * changed value for the same subject is an *update*, not a new atom).
+ */
+export function inferenceId(kind, subject) {
+  return `${String(kind)}::${String(subject)}`;
+}
+
+/**
+ * makeInference — the best-in-field atom (Honcho + Copilot + BEP):
+ * { id, kind, subject, value, confidence, evidence_count, last_confirmed,
+ *   source_sessions[], source_hosts[], sensitivity }.
+ */
+export function makeInference(fields = {}) {
+  const {
+    kind,
+    subject,
+    value,
+    confidence = 0.0,
+    evidence_count = 0,
+    last_confirmed = new Date(0).toISOString(),
+    source_sessions = [],
+    source_hosts = [],
+    sensitivity = 'low',
+  } = fields;
+
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new TypeError('makeInference: kind must be a non-empty string');
+  }
+  if (typeof subject !== 'string' || subject.length === 0) {
+    throw new TypeError('makeInference: subject must be a non-empty string');
+  }
+  if (!SENSITIVITIES.includes(sensitivity)) {
+    throw new TypeError(
+      `makeInference: sensitivity must be one of ${SENSITIVITIES.join('|')} (got ${JSON.stringify(sensitivity)})`,
+    );
+  }
+  const c = Number(confidence);
+  if (!Number.isFinite(c) || c < 0 || c > 1) {
+    throw new TypeError(`makeInference: confidence must be in [0,1] (got ${JSON.stringify(confidence)})`);
+  }
+
+  return {
+    id: inferenceId(kind, subject),
+    kind,
+    subject,
+    value: value === undefined ? null : value,
+    confidence: c,
+    evidence_count: Number(evidence_count) || 0,
+    last_confirmed,
+    source_sessions: [...source_sessions],
+    source_hosts: [...source_hosts],
+    sensitivity,
+  };
+}
+
+/** One style axis: EMA point estimate + Beta(α,β) uncertainty (graceful cold start). */
+function makeStyleAxis() {
+  // Uniform Beta(1,1) prior = "unconfirmed" until evidence accrues.
+  return { ema: 0.5, alpha: 1, beta: 1, evidence_count: 0 };
+}
+
+/**
+ * makeProfile — the partitioned UserProfile container (design-v2 §4):
+ * global.style (4 EMA+Beta axes) + global.dialectic[] + overlays + expertise +
+ * provenance + egress_log_ref + schema_version.
+ */
+export function makeProfile() {
+  const style = {};
+  for (const axis of STYLE_AXES) style[axis] = makeStyleAxis();
+  return {
+    schema_version: SCHEMA_VERSION,
+    global: {
+      style,
+      dialectic: [],
+    },
+    overlays: {},
+    expertise: {},
+    provenance: {
+      created: new Date(0).toISOString(),
+      updated: new Date(0).toISOString(),
+    },
+    egress_log_ref: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Minimal flat-scalar YAML frontmatter (no dependency).
+// Only string/number/boolean/null scalars are supported — nested data lives in
+// the canonical JSON block, so we never need a recursive YAML parser.
+// ---------------------------------------------------------------------------
+
+function serializeFrontmatterValue(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : 'null';
+  // Quote strings to keep them unambiguous (colons, leading spaces, etc.).
+  return JSON.stringify(String(v));
+}
+
+function parseFrontmatterValue(raw) {
+  const s = raw.trim();
+  if (s === 'null' || s === '~' || s === '') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  // eslint-disable-next-line security/detect-unsafe-regex -- anchored ^...$, \d+ then a disambiguated optional group; linear.
+  if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+  if (s.startsWith('"')) {
+    try {
+      return JSON.parse(s);
+    } catch {
+      return s;
+    }
+  }
+  return s;
+}
+
+function parseFrontmatter(block) {
+  const out = {};
+  for (const line of block.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    if (!key) continue;
+    out[key] = parseFrontmatterValue(line.slice(idx + 1));
+  }
+  return out;
+}
+
+/** Human-glanceable summary scalars surfaced in the frontmatter. */
+function summaryScalars(profile) {
+  const fm = {
+    schema_version:
+      typeof profile.schema_version === 'number' ? profile.schema_version : SCHEMA_VERSION,
+  };
+  if (profile.provenance && typeof profile.provenance === 'object') {
+    if (profile.provenance.updated) fm.updated = profile.provenance.updated;
+    if (profile.provenance.created) fm.created = profile.provenance.created;
+  }
+  const dialectic = profile.global && Array.isArray(profile.global.dialectic)
+    ? profile.global.dialectic.length : 0;
+  fm.dialectic_count = dialectic;
+  fm.expertise_domains = profile.expertise ? Object.keys(profile.expertise).length : 0;
+  return fm;
+}
+
+/**
+ * serializeProfile(profile) -> markdown text. Lossless via the canonical JSON
+ * block; the frontmatter is a convenience surface only.
+ */
+export function serializeProfile(profile) {
+  const fm = summaryScalars(profile);
+  const fmLines = Object.entries(fm)
+    .map(([k, v]) => `${k}: ${serializeFrontmatterValue(v)}`)
+    .join('\n');
+  const json = JSON.stringify(profile, null, 2);
+  return (
+    `---\n${fmLines}\n---\n\n`
+    + '# IJFW User Profile\n\n'
+    + 'Portable, user-global interaction profile. Inspect or hand-edit the\n'
+    + 'canonical record in the JSON block below. Re-derived at SessionEnd.\n\n'
+    + '```json\n'
+    + `${json}\n`
+    + '```\n'
+  );
+}
+
+/**
+ * parseProfile(text) -> profile object. Tolerant of unknown fields and of a
+ * hand-edited file missing schema_version (stamped on parse). Throws only when
+ * the canonical JSON block is absent/unparseable (structurally unrecoverable).
+ */
+export function parseProfile(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError('parseProfile: text must be a string');
+  }
+
+  // Frontmatter (optional, advisory).
+  let frontmatter = {};
+  const fmMatch = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (fmMatch) frontmatter = parseFrontmatter(fmMatch[1]);
+
+  // Canonical JSON block (required).
+  const jsonMatch = /```json\s*\n([\s\S]*?)\n```/.exec(text);
+  if (!jsonMatch) {
+    throw new Error('parseProfile: no canonical ```json``` profile block found');
+  }
+  let obj;
+  try {
+    obj = JSON.parse(jsonMatch[1]);
+  } catch (err) {
+    throw new Error(`parseProfile: canonical JSON block is unparseable: ${err.message}`);
+  }
+  if (!obj || typeof obj !== 'object') {
+    throw new Error('parseProfile: canonical JSON block did not yield an object');
+  }
+
+  // schema_version invariant: never undefined. Prefer the block, fall back to
+  // frontmatter, then the current SCHEMA_VERSION.
+  if (typeof obj.schema_version !== 'number') {
+    obj.schema_version =
+      typeof frontmatter.schema_version === 'number'
+        ? frontmatter.schema_version
+        : SCHEMA_VERSION;
+  }
+  return obj;
+}

package/src/profile/sensitivity.js

@@ -0,0 +1,249 @@
+/**
+ * profile/sensitivity.js — Cross-system profile bus, PHASE P4 (exfiltration guard).
+ *
+ * The data-minimization gate that decides WHAT may leave the machine when a
+ * brief is rendered (design-v2 §6 "data minimization" + §7 "exfiltration").
+ * Three concerns live here, all pure and zero-dep / zero-LLM:
+ *
+ *   1. SENSITIVITY TIERING — every renderable field is low / med / high.
+ *        - low : style axes (formality/energy/terseness/emoji_use) + expertise
+ *                bands. Behavioural fingerprint, not content. Shared by default.
+ *        - med : preferences / corrections / rules — what the user asked for.
+ *        - high: anything an inference explicitly tags `high` (e.g. a derived
+ *                dialectic belief about the user). Never shared unless opted in.
+ *      `brief` returns ONLY low-sensitivity fields by default; med/high require
+ *      a per-host opt-in AND the resolved host being on the share-hosts
+ *      allowlist (audit MED-2). The opt-in alone (env flag / arg) is necessary
+ *      but NOT sufficient — a self-declared host can never grant itself
+ *      sensitive fields; an operator must add it to the allowlist.
+ *
+ *   2. REDACTION LIST — a user-controlled denylist of field ids / substrings
+ *      that must NEVER leave, honored BEFORE any field is emitted. Sourced from
+ *      the env (IJFW_PROFILE_REDACT, comma/newline separated) AND a plaintext
+ *      file at ~/.ijfw/profile/redact.txt (one pattern per line, # comments).
+ *
+ *   3. KILL-SWITCH — a global "share nothing" override. Engaged by the env var
+ *      IJFW_PROFILE_KILL (truthy) or a bare `*` / `KILL` line in redact.txt.
+ *      When engaged, renderBrief emits an EMPTY brief regardless of everything
+ *      else — the user's hard stop on profile egress.
+ *
+ * Zero deps, Node built-ins only. NO LLM calls.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { profileDir } from './store.js';
+
+/** Sensitivity levels, ordered low → high (index = severity). */
+export const SENSITIVITY_ORDER = Object.freeze(['low', 'med', 'high']);
+
+/** The four style axes are always low-sensitivity (behavioural fingerprint). */
+const STYLE_LOW = 'low';
+/** Expertise bands are low-sensitivity (a competence summary, not content). */
+const EXPERTISE_LOW = 'low';
+
+/**
+ * fieldSensitivity(field) -> 'low' | 'med' | 'high'.
+ *
+ * `field` is a descriptor `{ kind, sensitivity? }`:
+ *   - kind 'style'      -> low (always).
+ *   - kind 'expertise'  -> low (always).
+ *   - kind 'inference'  -> the inference's OWN sensitivity tag (schema.js sets
+ *                          it; preferences default to 'med'), clamped to a known
+ *                          level. Unknown/absent -> 'med' (fail-safe: an
+ *                          un-tagged inference is treated as at least med, never
+ *                          silently low).
+ */
+export function fieldSensitivity(field) {
+  if (!field || typeof field !== 'object') return 'med';
+  if (field.kind === 'style') return STYLE_LOW;
+  if (field.kind === 'expertise') return EXPERTISE_LOW;
+  // inference (preference/trait/dialectic): honor its own tag, fail-safe to med.
+  const tag = String(field.sensitivity || '').toLowerCase();
+  if (SENSITIVITY_ORDER.includes(tag)) return tag;
+  return 'med';
+}
+
+/**
+ * sensitivityAllowed(level, opts) -> boolean. Low is ALWAYS allowed. med/high
+ * require BOTH (audit MED-2 + MED-3):
+ *   - the per-call/per-env share-sensitive opt-in (shareSensitive), AND
+ *   - the resolved host being on the share-hosts allowlist (hostAllowedSensitive).
+ *   - and NOT opts.forceLowOnly (the passive resource path forces low-only —
+ *     audit MED-3: the user cannot consent per passive read, so a passive
+ *     injection NEVER honors a sensitive opt-in).
+ * Either factor missing => low-only. The opt-in alone can never elevate a
+ * non-allowlisted (or self-declared) host.
+ */
+export function sensitivityAllowed(level, opts = {}) {
+  const lvl = SENSITIVITY_ORDER.includes(level) ? level : 'med';
+  if (lvl === 'low') return true;
+  if (opts.forceLowOnly === true) return false; // passive read: low-only, always.
+  if (!shareSensitive(opts)) return false; // no opt-in => never sensitive.
+  // MED-2 host allowlist: enforced whenever the serve layer engages it
+  // (opts.enforceHostAllowlist === true — set for EVERY production read path in
+  // serve.js). Direct unit callers of renderBrief that don't engage it fall back
+  // to opt-in-only (the legacy P4.2 contract) — but they are NOT a production
+  // egress surface, so the moat is intact: every real read goes through serve.js.
+  if (opts.enforceHostAllowlist === true) return hostAllowedSensitive(opts);
+  return true;
+}
+
+/** Truthy env values that engage a boolean flag. */
+function isTruthy(v) {
+  if (v === undefined || v === null) return false;
+  const s = String(v).trim().toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
+/**
+ * shareSensitive(opts) -> boolean. The per-host opt-in to include med/high
+ * fields in a brief. Read from opts.shareSensitive (explicit override, for
+ * tests / programmatic callers) else the IJFW_PROFILE_SHARE_SENSITIVE env var.
+ */
+export function shareSensitive(opts = {}) {
+  if (typeof opts.shareSensitive === 'boolean') return opts.shareSensitive;
+  const env = opts.env || process.env;
+  return isTruthy(env.IJFW_PROFILE_SHARE_SENSITIVE);
+}
+
+/** The share-hosts allowlist path (sibling of the profile). */
+export function shareHostsFilePath() {
+  return join(profileDir(), 'share-hosts.txt');
+}
+
+/**
+ * loadShareHosts(opts) -> { hosts:Set<string>, all:boolean }.
+ *
+ * Reads the per-host sensitive-field allowlist from `~/.ijfw/profile/
+ * share-hosts.txt` (one host per line, `#` comments) AND the env var
+ * IJFW_PROFILE_SHARE_HOSTS (comma/newline separated). Hosts are lowercased for
+ * case-insensitive matching. A bare `*` line opts ALL hosts in (operator escape
+ * hatch — explicit and auditable). A missing/unreadable file -> empty set
+ * (default-deny: no host gets sensitive fields). Never throws.
+ *
+ * @param {{ env?:object, shareHostsFile?:string }} [opts]
+ */
+export function loadShareHosts(opts = {}) {
+  const env = opts.env || process.env;
+  const raw = [];
+  raw.push(...parsePatterns(env.IJFW_PROFILE_SHARE_HOSTS));
+  const file = opts.shareHostsFile || shareHostsFilePath();
+  try {
+    if (existsSync(file)) {
+      raw.push(...parsePatterns(readFileSync(file, 'utf8')));
+    }
+  } catch {
+    // unreadable allowlist -> no hosts (default-deny). Never throw.
+  }
+  const hosts = new Set();
+  let all = false;
+  for (const h of raw) {
+    if (h === '*') { all = true; continue; }
+    hosts.add(h.toLowerCase());
+  }
+  return { hosts, all };
+}
+
+/**
+ * hostAllowedSensitive(opts) -> boolean. True iff the resolved host is on the
+ * share-hosts allowlist (audit MED-2). The host comes from opts.host (resolved
+ * by the serve layer from the caller context, NOT self-declared by the field
+ * payload). No host, or a host absent from the allowlist => false (default-deny).
+ *
+ * @param {{ host?:string, env?:object, shareHostsFile?:string,
+ *           shareHosts?:{hosts:Set<string>,all:boolean} }} [opts]
+ */
+export function hostAllowedSensitive(opts = {}) {
+  const host = typeof opts.host === 'string' ? opts.host.trim().toLowerCase() : '';
+  if (!host) return false; // unknown host can never receive sensitive fields.
+  const allow = opts.shareHosts || loadShareHosts(opts);
+  if (allow.all) return true;
+  return allow.hosts.has(host);
+}
+
+/** The redaction file path (sibling of the profile). */
+export function redactFilePath() {
+  return join(profileDir(), 'redact.txt');
+}
+
+/**
+ * Parse a raw redaction blob (env value or file contents) into pattern lines.
+ * Splits on commas AND newlines, trims, drops blanks and `#` comments.
+ */
+function parsePatterns(raw) {
+  if (!raw) return [];
+  return String(raw)
+    .split(/[\n,]/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0 && !s.startsWith('#'));
+}
+
+/**
+ * loadRedaction(opts) -> { patterns: string[], kill: boolean }.
+ *
+ * Merges the env denylist (IJFW_PROFILE_REDACT) and the redact.txt file. The
+ * kill-switch is engaged by IJFW_PROFILE_KILL (truthy) OR a bare `*` / `KILL`
+ * (case-insensitive) pattern in either source. File read is best-effort — a
+ * missing/unreadable file is simply no patterns (never throws).
+ *
+ * @param {{ env?:object, redactFile?:string }} [opts]
+ */
+export function loadRedaction(opts = {}) {
+  const env = opts.env || process.env;
+  const patterns = [];
+
+  // Env denylist.
+  patterns.push(...parsePatterns(env.IJFW_PROFILE_REDACT));
+
+  // File denylist (best-effort).
+  const file = opts.redactFile || redactFilePath();
+  try {
+    if (existsSync(file)) {
+      patterns.push(...parsePatterns(readFileSync(file, 'utf8')));
+    }
+  } catch {
+    // unreadable redact file -> treat as no file patterns (never throw).
+  }
+
+  // Kill-switch: explicit env flag OR a bare `*`/`KILL` token in the patterns.
+  const killTokens = new Set(['*', 'kill']);
+  const killFromPatterns = patterns.some((p) => killTokens.has(p.toLowerCase()));
+  const kill = isTruthy(env.IJFW_PROFILE_KILL) || killFromPatterns;
+
+  // Drop the kill tokens from the substring denylist — they're a switch, not a
+  // field pattern (a literal `*` would otherwise redact everything via substring
+  // match, which is the same outcome, but we keep the two mechanisms distinct).
+  const cleaned = patterns.filter((p) => !killTokens.has(p.toLowerCase()));
+
+  return { patterns: cleaned, kill };
+}
+
+/**
+ * killSwitchEngaged(redaction) -> boolean. Thin reader over loadRedaction's
+ * result so callers can branch without re-parsing.
+ */
+export function killSwitchEngaged(redaction) {
+  return !!(redaction && redaction.kill);
+}
+
+/**
+ * isRedacted(fieldId, redaction) -> boolean. A field is redacted when its id
+ * EXACTLY equals OR CONTAINS any denylist pattern (substring match mirrors the
+ * memory `forget <pattern>` UX). Case-insensitive on both sides so a user need
+ * not match casing exactly. An empty/absent denylist redacts nothing.
+ */
+export function isRedacted(fieldId, redaction) {
+  if (!redaction || !Array.isArray(redaction.patterns) || redaction.patterns.length === 0) {
+    return false;
+  }
+  const id = String(fieldId || '').toLowerCase();
+  if (!id) return false;
+  for (const p of redaction.patterns) {
+    const needle = String(p).toLowerCase();
+    if (!needle) continue;
+    if (id === needle || id.includes(needle)) return true;
+  }
+  return false;
+}