attesso 0.4.0 → 0.6.0

package/src/toolpin.mjs

@@ -0,0 +1,131 @@
+// A tool manifest is small, local and hashable. Pin the definitions a harness
+// reviewed so a changed description or schema is a refusal, not a quiet edit.
+// This module never fetches a server's manifest; the caller supplies it.
+import { createHash } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+
+const fail = (message) => {
+  throw new Error(`tool manifest is invalid: ${message}`);
+};
+
+export function toolsDigest(tools) {
+  return createHash('sha256').update(canonical(tools)).digest('base64url');
+}
+
+function definitionOf(tool) {
+  const name = String(tool?.name ?? '').trim();
+  if (name === '') fail('every tool needs a name');
+  const definition = {
+    name,
+    description: typeof tool.description === 'string' ? tool.description : '',
+    inputSchema: tool.inputSchema ?? tool.input_schema ?? null,
+  };
+  // A tool can change what it returns without touching its input schema. Pin
+  // the output contract and annotations too, or a server can alter the effect
+  // while the lock still says the definition is unchanged.
+  if (tool.title !== undefined) definition.title = tool.title;
+  if (tool.outputSchema !== undefined) definition.outputSchema = tool.outputSchema;
+  if (tool.annotations !== undefined) definition.annotations = tool.annotations;
+  return definition;
+}
+
+function digestOf(value) {
+  return createHash('sha256').update(canonical(value)).digest('base64url');
+}
+
+export function manifestDigest(manifest) {
+  return digestOf(manifest);
+}
+
+export function definitionHash(tool) {
+  return createHash('sha256').update(canonical(definitionOf(tool))).digest('base64url');
+}
+
+function manifestTools(manifest) {
+  if (Array.isArray(manifest)) return manifest;
+  if (manifest && Array.isArray(manifest.tools)) return manifest.tools;
+  fail('expected a tools array');
+}
+
+export function pinManifest(manifest, tools) {
+  const list = manifestTools(manifest);
+  const pins = {};
+  for (const tool of list) {
+    const definition = definitionOf(tool);
+    if (pins[definition.name] !== undefined) fail(`duplicate tool ${definition.name}`);
+    pins[definition.name] = definitionHash(tool);
+  }
+  const lock = { version: 1, tools_digest: toolsDigest(tools), tools: pins };
+  lock.manifest_digest = digestOf(manifest);
+  // The server handshake and prompts are model-visible too. Their digests are
+  // optional so a tools-only manifest keeps the original lock shape.
+  if (manifest.server !== undefined) lock.server_digest = digestOf(manifest.server);
+  if (manifest.prompts !== undefined) lock.prompts_digest = digestOf(manifest.prompts);
+  if (manifest.resources !== undefined) lock.resources_digest = digestOf(manifest.resources);
+  if (manifest.resourceTemplates !== undefined) lock.resource_templates_digest = digestOf(manifest.resourceTemplates);
+  return lock;
+}
+
+export function validateToolLock(lock) {
+  if (!lock || typeof lock !== 'object' || Array.isArray(lock)) fail('lock is not an object');
+  if (lock.version !== 1) fail('lock version must be 1');
+  if (typeof lock.tools_digest !== 'string' || lock.tools_digest === '') fail('lock has no tools digest');
+  if (!lock.tools || typeof lock.tools !== 'object' || Array.isArray(lock.tools)) fail('lock has no tool map');
+  for (const field of ['server_digest', 'prompts_digest', 'resources_digest', 'resource_templates_digest', 'manifest_digest']) {
+    if (lock[field] !== undefined && (typeof lock[field] !== 'string' || lock[field] === '')) {
+      fail(`lock has an invalid ${field}`);
+    }
+  }
+  for (const [name, hash] of Object.entries(lock.tools)) {
+    if (name === '' || typeof hash !== 'string' || hash === '') fail('lock has an invalid tool pin');
+  }
+  return lock;
+}
+
+export function comparePin(lock, manifest, tools) {
+  validateToolLock(lock);
+  const expected = pinManifest(manifest, tools);
+  const names = new Set([...Object.keys(lock.tools), ...Object.keys(expected.tools)]);
+  const changed = [];
+  const added = [];
+  const removed = [];
+  for (const name of [...names].sort()) {
+    const before = lock.tools[name];
+    const after = expected.tools[name];
+    if (before === undefined) added.push(name);
+    else if (after === undefined) removed.push(name);
+    else if (before !== after) changed.push(name);
+  }
+  const surfaces = [];
+  for (const field of ['server', 'prompts', 'resources', 'resource_templates']) {
+    if (lock[`${field}_digest`] !== expected[`${field}_digest`]) surfaces.push(field);
+  }
+  if (lock.manifest_digest !== undefined && lock.manifest_digest !== expected.manifest_digest) surfaces.push('manifest');
+  const digestChanged = lock.tools_digest !== expected.tools_digest;
+  return {
+    ok: !digestChanged && changed.length === 0 && added.length === 0 && removed.length === 0 && surfaces.length === 0,
+    digestChanged,
+    changed,
+    added,
+    removed,
+    surfaces,
+    expected,
+  };
+}
+
+export function toolGate(lock, currentToolsDigest, proposal) {
+  if (!lock) return null;
+  validateToolLock(lock);
+  if (lock.tools_digest !== currentToolsDigest) {
+    return { decision: 'DENY', code: 'TOOL_CHANGED', rule: 'tool.pin', tool_pin: 'changed' };
+  }
+  if (!proposal.tool_hash) return null;
+  const pinned = lock.tools[proposal.subject];
+  if (pinned === undefined) {
+    return { decision: 'DENY', code: 'TOOL_UNPINNED', rule: 'tool.pin', tool_pin: 'unpinned' };
+  }
+  if (pinned !== proposal.tool_hash) {
+    return { decision: 'DENY', code: 'TOOL_CHANGED', rule: 'tool.pin', tool_pin: 'changed' };
+  }
+  return null;
+}

package/src/ui/catalog.mjs

@@ -0,0 +1,266 @@
+// A disposable day/offset catalog over the signed ledger. The ledger remains
+// the source of truth; this file only helps the local UI read bounded ranges.
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isInitialised, paths, readConfig } from '../store.mjs';
+import { forEachEntrySync } from '../stream.mjs';
+
+const INDEX_VERSION = 1;
+const CHECKPOINT_EVERY = 256;
+const INDEX_FILE = 'ui-index.json';
+
+const readJson = (file) => {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+};
+const statOf = (file) => {
+  try {
+    const stat = statSync(file);
+    return { dev: stat.dev, ino: stat.ino, size: stat.size, mtime_ms: stat.mtimeMs };
+  } catch {
+    return null;
+  }
+};
+const sameFile = (left, right) =>
+  left && right && left.dev === right.dev && left.ino === right.ino && left.size === right.size;
+
+export function validateTimeZone(value) {
+  if (value === undefined || value === null || value === '') return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value }).format(0);
+    return value;
+  } catch {
+    throw new Error(`unknown time zone: ${value}`);
+  }
+}
+
+const partsAt = (ms, timeZone) => {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  }).formatToParts(new Date(ms));
+  const value = {};
+  for (const part of parts) if (part.type !== 'literal') value[part.type] = Number(part.value);
+  return value;
+};
+
+const offsetAt = (ms, timeZone) => {
+  const p = partsAt(ms, timeZone);
+  return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - ms;
+};
+
+export function zonedMidnight(day, timeZone) {
+  const [year, month, date] = day.split('-').map(Number);
+  let guess = Date.UTC(year, month - 1, date);
+  // Two passes settle a DST boundary where the offset changes at midnight.
+  for (let pass = 0; pass < 2; pass += 1) {
+    guess = Date.UTC(year, month - 1, date) - offsetAt(guess, timeZone);
+  }
+  return guess;
+}
+
+export function dayFor(iso, timeZone) {
+  const p = partsAt(Date.parse(iso), timeZone);
+  return `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`;
+}
+
+const nextDay = (day) => {
+  const [year, month, date] = day.split('-').map(Number);
+  const value = new Date(Date.UTC(year, month - 1, date + 1));
+  return value.toISOString().slice(0, 10);
+};
+
+export function dayBounds(day, timeZone) {
+  return { start: zonedMidnight(day, timeZone), end: zonedMidnight(nextDay(day), timeZone) };
+}
+
+function checkpointAt(ms) {
+  return this.checkpoints.reduce((best, item) => (Date.parse(item.at) <= ms ? item : best), null);
+}
+
+function indexMatches(index, ledger, stat, head) {
+  return index
+    && index.version === INDEX_VERSION
+    && index.ledger
+    && sameFile(index.ledger, stat)
+    && index.head === head
+    && Array.isArray(index.checkpoints);
+}
+
+export class Catalog {
+  constructor(dir, { write = true } = {}) {
+    this.dir = dir;
+    this.file = paths(dir).ledger;
+    this.indexFile = paths(dir).uiIndex;
+    this.write = write;
+    this.checkpoints = [];
+    this.head = 0;
+    this.signature = null;
+    this.ready = false;
+    this.load();
+  }
+
+  load() {
+    if (!isInitialised(this.dir)) return;
+    const stat = statOf(this.file);
+    if (!stat) return;
+    let head;
+    try { head = readConfig(this.dir).head.count; } catch { head = null; }
+    if (head === null) return;
+    const index = readJson(this.indexFile);
+    if (indexMatches(index, this.file, stat, head)) {
+      this.checkpoints = index.checkpoints;
+      this.head = index.head;
+      this.signature = stat;
+      this.ready = true;
+      return;
+    }
+    this.rebuild();
+  }
+
+  rebuild() {
+    this.checkpoints = [];
+    this.head = 0;
+    let end = 0;
+    try {
+      forEachEntrySync(this.file, (entry, index, start, next) => {
+        if (index === 1 || index % CHECKPOINT_EVERY === 0) {
+          this.checkpoints.push({ seq: entry.seq, offset: start, at: entry.at });
+        }
+        this.head = entry.seq;
+        end = next;
+      });
+    } catch {
+      // A corrupted ledger is reported by the query, not hidden behind an index.
+      this.ready = false;
+      return;
+    }
+    const stat = statOf(this.file);
+    if (stat) {
+      this.signature = { ...stat, size: end || stat.size };
+      this.ready = true;
+      this.persist();
+    }
+  }
+
+  persist() {
+    if (!this.write || !this.ready) return;
+    const value = {
+      version: INDEX_VERSION,
+      ledger: this.signature,
+      head: this.head,
+      checkpoints: this.checkpoints,
+    };
+    try {
+      mkdirSync(dirname(this.indexFile), { recursive: true });
+      const temp = `${this.indexFile}.${process.pid}.tmp`;
+      writeFileSync(temp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+      renameSync(temp, this.indexFile);
+    } catch {
+      // A read-only ledger still works; the index stays in memory.
+    }
+  }
+
+  refresh() {
+    if (!this.ready) {
+      this.load();
+      return;
+    }
+    const stat = statOf(this.file);
+    if (!stat) {
+      this.ready = false;
+      return;
+    }
+    if (stat.size === this.signature.size && stat.ino === this.signature.ino) return;
+    // A live append can be recorded without rescanning. Anything else is a
+    // replacement or truncation and gets a full rebuild.
+    if (stat.size > this.signature.size && stat.ino === this.signature.ino) {
+      this.extendFrom(this.signature.size);
+      return;
+    }
+    this.rebuild();
+  }
+
+  extendFrom(offset) {
+    try {
+      forEachEntrySync(this.file, (entry, index, start, next) => {
+        if (index === 1 || (this.head + 1) % CHECKPOINT_EVERY === 0) {
+          this.checkpoints.push({ seq: entry.seq, offset: start, at: entry.at });
+        }
+        this.head = entry.seq;
+        this.signature.size = next;
+      }, { startOffset: offset });
+    } catch {
+      this.ready = false;
+    }
+  }
+
+  record(entry, start, end) {
+    if (!this.ready) return;
+    if ((this.head + 1) === entry.seq && (this.head % CHECKPOINT_EVERY === 0)) {
+      this.checkpoints.push({ seq: entry.seq, offset: start, at: entry.at });
+    }
+    this.head = entry.seq;
+    this.signature.size = end;
+  }
+
+  startFor(ms) {
+    const checkpoint = checkpointAt.call(this, ms);
+    return checkpoint ? checkpoint.offset : 0;
+  }
+
+  startForSeq(seq) {
+    let start = 0;
+    for (const checkpoint of this.checkpoints) {
+      if (checkpoint.seq <= seq) start = checkpoint.offset; else break;
+    }
+    return start;
+  }
+
+  scanDay(day, timeZone, onEntry) {
+    if (!isInitialised(this.dir)) return;
+    this.refresh();
+    if (!this.ready) throw new Error('ledger is not readable');
+    const { start, end } = dayBounds(day, timeZone);
+    forEachEntrySync(this.file, (entry, index, startOffset, endOffset) => {
+      const at = Date.parse(entry.at);
+      if (at < start) return;
+      if (at >= end) return false;
+      if (dayFor(entry.at, timeZone) !== day) return;
+      onEntry(entry, startOffset, endOffset);
+      return undefined;
+    }, { startOffset: this.startFor(start) });
+  }
+
+  scanAfter(seq, onEntry) {
+    if (!isInitialised(this.dir)) return;
+    this.refresh();
+    if (!this.ready) throw new Error('ledger is not readable');
+    let started = false;
+    forEachEntrySync(this.file, (entry, index, startOffset, endOffset) => {
+      if (!started && entry.seq <= seq) return;
+      started = true;
+      return onEntry(entry, startOffset, endOffset);
+    }, { startOffset: this.startForSeq(seq) });
+  }
+
+  scanRecent(days, timeZone, onEntry) {
+    if (!isInitialised(this.dir)) return;
+    this.refresh();
+    if (!this.ready) throw new Error('ledger is not readable');
+    const now = Date.now();
+    const start = now - days * 24 * 60 * 60 * 1000;
+    forEachEntrySync(this.file, (entry, index, startOffset, endOffset) => {
+      if (Date.parse(entry.at) < start) return;
+      onEntry(entry, startOffset, endOffset);
+      return undefined;
+    }, { startOffset: this.startFor(start) });
+  }
+}
+
+export { INDEX_FILE };

package/src/ui/live.mjs

@@ -0,0 +1,58 @@
+// Byte-offset tail for the signed ledger. The UI server needs new entries, not
+// a full re-read: a hook is a separate process, so the file is the boundary.
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+
+export class LedgerTail {
+  constructor(file, startOffset = 0) {
+    this.file = file;
+    this.fd = null;
+    this.offset = startOffset;
+    this.inode = null;
+    this.partial = '';
+  }
+
+  open() {
+    this.fd = openSync(this.file, 'r');
+    const stat = fstatSync(this.fd);
+    this.inode = stat.ino;
+    this.offset = stat.size;
+  }
+
+  close() {
+    if (this.fd !== null) {
+      closeSync(this.fd);
+      this.fd = null;
+    }
+  }
+
+  // Reads complete lines from the current offset. A partial final line is kept
+  // until the writer finishes it, so a reader never sees half an entry.
+  read(onLine) {
+    if (this.fd === null) return;
+    let stat;
+    try {
+      stat = fstatSync(this.fd);
+    } catch {
+      this.close();
+      return;
+    }
+    if (stat.ino !== this.inode || stat.size < this.offset) {
+      this.close();
+      this.open();
+      this.partial = '';
+      return;
+    }
+    if (stat.size === this.offset) return;
+    const size = stat.size - this.offset;
+    const buffer = Buffer.alloc(size);
+    const bytes = readSync(this.fd, buffer, 0, size, this.offset);
+    this.offset += bytes;
+    this.partial += buffer.subarray(0, bytes).toString('utf8');
+    let newline;
+    while ((newline = this.partial.indexOf('\n')) !== -1) {
+      const line = this.partial.slice(0, newline);
+      this.partial = this.partial.slice(newline + 1);
+      if (line !== '') onLine(line);
+    }
+  }
+}

package/src/ui/query.mjs

@@ -0,0 +1,163 @@
+// Query contracts over the catalog. The catalog owns byte ranges; this module
+// owns the small JSON shapes the page consumes. Nothing here decides policy.
+import { Catalog, dayFor, validateTimeZone } from './catalog.mjs';
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const CURSOR = /^v1:(\d+):(.+)$/;
+const isAction = (entry) => entry.action !== 'llm.session';
+const matches = (row, filters) => {
+  if (filters.minute !== undefined) {
+    const [hour, minute] = row[1].split(':').map(Number);
+    if (Math.floor((hour * 60 + minute) / 5) * 5 !== filters.minute) return false;
+  }
+  if (filters.hour !== undefined && row[1].slice(0, 2) !== String(filters.hour).padStart(2, '0')) return false;
+  if (filters.tool && row[2] !== filters.tool) return false;
+  if (filters.capability && row[3] !== filters.capability) return false;
+  if (filters.decision && row[4] !== filters.decision) return false;
+  if (filters.search && !row.join(' ').toLowerCase().includes(filters.search)) return false;
+  return true;
+};
+
+const pad = (value) => String(value).padStart(2, '0');
+const timeParts = (iso, timeZone) => {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone, hourCycle: 'h23', hour: '2-digit', minute: '2-digit',
+  }).formatToParts(new Date(iso));
+  const result = {};
+  for (const part of parts) if (part.type === 'hour' || part.type === 'minute') result[part.type] = Number(part.value);
+  return result;
+};
+
+export function rowFor(entry, timeZone) {
+  const time = timeParts(entry.at, timeZone);
+  return [
+    entry.seq,
+    `${pad(time.hour)}:${pad(time.minute)}`,
+    entry.subject ?? 'unknown',
+    entry.capability ?? 'unknown',
+    entry.decision ?? 'UNKNOWN',
+    entry.code ?? '',
+    entry.task ?? 'unknown',
+  ];
+}
+
+export function parseDay(value, timeZone) {
+  const day = value ?? dayFor(new Date().toISOString(), timeZone);
+  if (!DAY.test(day)) throw new Error(`invalid day: ${day}`);
+  // Reject impossible calendar dates such as 2026-02-31.
+  const [year, month, date] = day.split('-').map(Number);
+  const check = new Date(Date.UTC(year, month - 1, date));
+  if (check.getUTCFullYear() !== year || check.getUTCMonth() !== month - 1 || check.getUTCDate() !== date) {
+    throw new Error(`invalid day: ${day}`);
+  }
+  return day;
+}
+
+export function parseCursor(value, timeZone) {
+  if (value === undefined || value === null || value === '') return { seq: 0, timeZone };
+  const match = CURSOR.exec(String(value));
+  if (!match) throw new Error('invalid cursor');
+  const seq = Number(match[1]);
+  if (!Number.isSafeInteger(seq) || seq < 0) throw new Error('invalid cursor');
+  const cursorZone = validateTimeZone(match[2]);
+  if (cursorZone !== timeZone) throw new Error('cursor belongs to another time zone');
+  return { seq, timeZone };
+}
+
+export const makeCursor = (seq, timeZone) => `v1:${seq}:${timeZone}`;
+
+export function parseLimit(value, { fallback = 100, max = 200 } = {}) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1 || number > max) {
+    throw new Error(`limit must be an integer from 1 to ${max}`);
+  }
+  return number;
+}
+
+export function summary(catalog, { day, timeZone }) {
+  let calls = 0;
+  let blocked = 0;
+  let first = null;
+  let last = null;
+  catalog.scanDay(day, timeZone, (entry) => {
+    if (!isAction(entry)) return;
+    calls += 1;
+    if (entry.decision === 'DENY') blocked += 1;
+    if (first === null) first = entry.seq;
+    last = entry.seq;
+  });
+  return { day, calls, blocked, allowed: calls - blocked, first_seq: first, last_seq: last, head: catalog.head, generated_at: new Date().toISOString() };
+}
+
+export function flow(catalog, { day, timeZone, bucket = 5 }) {
+  if (!Number.isInteger(bucket) || bucket < 1 || bucket > 60) throw new Error('bucket must be between 1 and 60 minutes');
+  const buckets = new Map();
+  catalog.scanDay(day, timeZone, (entry) => {
+    if (!isAction(entry)) return;
+    const time = timeParts(entry.at, timeZone);
+    const minute = Math.floor((time.hour * 60 + time.minute) / bucket) * bucket;
+    const capability = entry.capability ?? 'unknown';
+    const key = `${minute}|${capability}`;
+    const item = buckets.get(key) ?? { minute, capability, total: 0, allowed: 0, blocked: 0, tools: new Set(), tasks: new Set(), codes: new Set() };
+    item.total += 1;
+    item.tools.add(entry.subject ?? 'unknown');
+    item.tasks.add(entry.task ?? 'unknown');
+    if (entry.decision === 'DENY') item.codes.add(entry.code ?? 'policy');
+    if (entry.decision === 'DENY') item.blocked += 1; else item.allowed += 1;
+    buckets.set(key, item);
+  });
+  return {
+    day,
+    bucket,
+    buckets: [...buckets.values()]
+      .map((item) => ({ ...item, tools: [...item.tools].sort(), tasks: [...item.tasks].sort(), codes: [...item.codes].sort() }))
+      .sort((left, right) => left.minute - right.minute || left.capability.localeCompare(right.capability)),
+  };
+}
+
+export function days(catalog, { timeZone, limit = 14 }) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 90) throw new Error('limit must be between 1 and 90');
+  const map = new Map();
+  catalog.scanRecent(limit + 1, timeZone, (entry) => {
+    if (!isAction(entry)) return;
+    const day = dayFor(entry.at, timeZone);
+    const item = map.get(day) ?? { day, calls: 0, blocked: 0 };
+    item.calls += 1;
+    if (entry.decision === 'DENY') item.blocked += 1;
+    map.set(day, item);
+  });
+  return [...map.values()].sort((left, right) => left.day.localeCompare(right.day)).slice(-limit);
+}
+
+export function page(catalog, { day, timeZone, after = 0, limit = 100, filters = null }) {
+  const rows = [];
+  let hasMore = false;
+  const collect = (entry) => {
+    if (!isAction(entry)) return;
+    if (entry.seq <= after) return;
+    const row = rowFor(entry, timeZone);
+    if (filters && !matches(row, filters)) return;
+    if (rows.length >= limit) {
+      hasMore = true;
+      return false;
+    }
+    row[7] = dayFor(entry.at, timeZone);
+    rows.push(row);
+    return undefined;
+  };
+  if (day) {
+    catalog.scanDay(day, timeZone, collect);
+  } else {
+    catalog.scanAfter(after, collect);
+  }
+  const last = rows.length ? rows[rows.length - 1][0] : after;
+  return {
+    rows,
+    next_cursor: makeCursor(last, timeZone),
+    has_more: hasMore,
+    head: catalog.head,
+  };
+}
+
+export { Catalog };