getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/ask-rules.ts

@@ -0,0 +1,181 @@
+import { isAbsolute, join, resolve } from 'node:path';
+import { actionKey, HttpError } from './store.ts';
+import { orNull, truncate } from './util.ts';
+
+// Ask first rules are Claude Code permission rules (`Bash(git push:*)`, `mcp__slack__send_message`).
+// Claude Code decides when a call matches; matchRule only finds which rule it was, so it errs towards matching.
+
+const ASK_FIRST_MAX = 50;
+const RULE_MAX = 200;
+
+/** `Tool` or `Tool(specifier)`: a tool name (an MCP one may end in `*`), and anything but a line break inside the parentheses. */
+const RULE = /^([A-Za-z][\w-]*\*?)(?:\((.+)\))?$/;
+
+function askRule(v: unknown): string {
+  const field = 'each askFirst rule';
+  if (typeof v !== 'string') throw new HttpError(400, `${field} must be a string`);
+  const rule = v.trim();
+  if (!rule) throw new HttpError(400, `${field} is empty`);
+  if (rule.length > RULE_MAX) throw new HttpError(400, `${field} is too long (max ${RULE_MAX} characters)`);
+  if (/[\r\n]/.test(rule) || !RULE.test(rule)) {
+    throw new HttpError(400, `${field} must be a Claude Code permission rule, such as Bash(git push:*), WebFetch(domain:example.com) or mcp__slack__send_message (got "${rule}")`);
+  }
+  return rule;
+}
+
+/** Bot.askFirst as given: valid rules, without repeats. */
+export function askFirstList(v: unknown): string[] {
+  if (!Array.isArray(v)) throw new HttpError(400, 'askFirst must be a list of permission rules');
+  const list = [...new Set(v.map(askRule))];
+  if (list.length > ASK_FIRST_MAX) throw new HttpError(400, `askFirst can hold at most ${ASK_FIRST_MAX} rules`);
+  return list;
+}
+
+/** What "Always allow" adds to Bot.alwaysAllow for a rule, or null if no action kind can hold it. */
+export function ruleKey(rule: string): string | null {
+  return orNull(() => actionKey(rule));
+}
+
+/** The rules a turn asks about, and the always-allowed ones (never in a sandboxed turn). */
+export function splitRules(askFirst: string[], alwaysAllow: string[], sandboxed: boolean): { ask: string[]; allow: string[] } {
+  const always = new Set(alwaysAllow);
+  const allow = sandboxed ? [] : askFirst.filter((r) => always.has(ruleKey(r) ?? ''));
+  return { ask: askFirst.filter((r) => !allow.includes(r)), allow };
+}
+
+/** A glob as a regex: `**` any path, `*` any part of one, `?` one character. */
+function globRegex(glob: string): RegExp {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      out += '.*';
+      i++;
+      if (glob[i + 1] === '/') i++;
+    } else if (c === '*') out += '[^/]*';
+    else if (c === '?') out += '[^/]';
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** The line itself and each command in it (split on && || ; | & and line breaks), without leading VAR=value assignments. */
+function commandsOf(line: string): string[] {
+  const parts = [line, ...line.split(/&&|\|\||[;|&\n]/)].map((p) => p.trim().replace(/^(?:\w+=\S*\s+)+/, '').trim());
+  return [...new Set(parts.filter(Boolean))];
+}
+
+function bashMatches(spec: string, command: string): boolean {
+  const commands = commandsOf(command);
+  // Prefix rules, Claude Code's `:*` form: `git push:*`.
+  if (spec.endsWith(':*')) {
+    const prefix = spec.slice(0, -2).trim();
+    return commands.some((c) => c.startsWith(prefix));
+  }
+  if (spec.includes('*')) {
+    // `*` is anything (slashes too), and `git push *` also matches a bare `git push`.
+    const body = spec
+      .trim()
+      .split('*')
+      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+      .join('.*');
+    const re = new RegExp(`^${body.endsWith(' .*') ? `${body.slice(0, -3)}(?: .*)?` : body}$`, 's');
+    return commands.some((c) => re.test(c));
+  }
+  return commands.some((c) => c === spec.trim());
+}
+
+/** A path rule as an absolute glob: `//abs`, `~/home`, else relative to the working folder. */
+function pathGlob(spec: string, ctx: { cwd: string; home: string }): string {
+  if (spec.startsWith('//')) return spec.slice(1);
+  if (spec.startsWith('~/')) return join(ctx.home, spec.slice(2));
+  if (spec.startsWith('/')) return join(ctx.cwd, spec.slice(1));
+  return join(ctx.cwd, spec.replace(/^\.\//, ''));
+}
+
+function pathMatches(spec: string, file: string, ctx: { cwd: string; home: string }): boolean {
+  const abs = isAbsolute(file) ? resolve(file) : resolve(ctx.cwd, file);
+  const glob = pathGlob(spec, ctx);
+  // `dir` alone covers what is in it too.
+  return globRegex(glob).test(abs) || (!/[*?]/.test(glob) && abs.startsWith(`${glob.replace(/\/$/, '')}/`));
+}
+
+const EDIT_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS']);
+const str = (v: unknown) => (typeof v === 'string' ? v : '');
+
+function covers(rule: string, toolName: string, input: Record<string, unknown>, ctx: { cwd: string; home: string }): boolean {
+  const m = RULE.exec(rule);
+  if (!m) return false;
+  const [, name, spec] = m;
+  if (name.startsWith('mcp__')) {
+    // `mcp__server`, `mcp__server__*` and `mcp__server__tool` (an MCP rule has no specifier).
+    const base = name.replace(/(?:__)?\*$/, '');
+    return toolName === base || toolName.startsWith(`${base}__`);
+  }
+  if (spec === undefined || spec === '*') return name === toolName || (name === 'Edit' && EDIT_TOOLS.has(toolName)) || (name === 'Read' && READ_TOOLS.has(toolName));
+  if (name === 'Bash') return toolName === 'Bash' && bashMatches(spec, str(input.command));
+  if (name === 'Edit' || name === 'Read') {
+    const tools = name === 'Edit' ? EDIT_TOOLS : READ_TOOLS;
+    if (!tools.has(toolName)) return false;
+    const file = str(input.file_path) || str(input.notebook_path) || str(input.path);
+    // No path (a search of the working folder): ask rather than miss it.
+    return !file || pathMatches(spec, file, ctx);
+  }
+  if (name === 'WebFetch' && spec.startsWith('domain:')) {
+    if (toolName !== 'WebFetch') return false;
+    const domain = spec.slice(7).toLowerCase();
+    try {
+      const host = new URL(str(input.url)).hostname.toLowerCase();
+      return host === domain || host.endsWith(`.${domain}`);
+    } catch {
+      return true;
+    }
+  }
+  // A specifier this doesn't know: any call of the tool.
+  return name === toolName;
+}
+
+/** The first of `rules` that covers a tool call, or null. `ctx` resolves path rules. */
+export function matchRule(rules: string[], toolName: string, input: unknown, ctx: { cwd: string; home: string }): string | null {
+  const args = input && typeof input === 'object' ? (input as Record<string, unknown>) : {};
+  return rules.find((r) => covers(r, toolName, args, ctx)) ?? null;
+}
+
+/**
+ * Identifies exactly the call the owner approves, so only that same call is allowed: every argument, in any key
+ * order. Only Bash's description is left out, since Claude Code defines it as the model's words about the command;
+ * any other tool's description (an MCP tool's, say) may be what the call does.
+ */
+export function callKey(toolName: string, input: unknown): string {
+  const args: Record<string, unknown> = input && typeof input === 'object' && !Array.isArray(input) ? { ...(input as Record<string, unknown>) } : { value: input };
+  if (toolName === 'Bash') delete args.description;
+  return JSON.stringify([toolName, sortKeys(args)]);
+}
+
+function sortKeys(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === 'object') {
+    return Object.fromEntries(
+      Object.keys(v as object)
+        .sort()
+        .map((k) => [k, sortKeys((v as Record<string, unknown>)[k])]),
+    );
+  }
+  return v;
+}
+
+/** A tool call's card, made from the call itself, never from what the Boton says about it. */
+export function describeCall(toolName: string, input: unknown): { title: string; details: string } {
+  const args = input && typeof input === 'object' ? (input as Record<string, unknown>) : {};
+  const mcp = /^mcp__(.+?)__(.+)$/.exec(toolName);
+  let title = mcp ? `Use ${mcp[2]} (${mcp[1]})` : `Use ${toolName}`;
+  let details = JSON.stringify(input ?? {}, null, 2);
+  if (toolName === 'Bash') {
+    title = `Run \`${str(args.command).replace(/\s+/g, ' ').trim()}\``;
+    details = str(args.command);
+  } else if (EDIT_TOOLS.has(toolName)) title = `${toolName === 'Write' ? 'Write' : 'Edit'} ${str(args.file_path) || str(args.notebook_path) || 'a file'}`;
+  else if (toolName === 'Read') title = `Read ${str(args.file_path) || 'a file'}`;
+  else if (toolName === 'WebFetch') title = `Fetch ${str(args.url) || 'a web page'}`;
+  return { title: truncate(title, 200), details };
+}

package/payload/server/src/audit.ts

@@ -0,0 +1,158 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { AuditAction, AuditActorKind, AuditEvent } from '../../shared/types.ts';
+import type { Principal } from './auth.ts';
+import { log } from './log.ts';
+import { nowIso, parseJson, type Row } from './util.ts';
+
+/*
+ * The audit log: who did what to which thing, for the actions that change who
+ * can reach the server or what a Boton may do. Callers pass ids, names and
+ * small facts only, never a token, code, secret, URL query or message text;
+ * `clean` drops anything else that looks like one.
+ */
+
+/** Newest rows kept; older ones are deleted as new ones arrive. */
+export const AUDIT_KEEP = 10_000;
+
+export interface AuditActor {
+  kind: AuditActorKind;
+  id: string | null;
+  label: string;
+}
+
+type Detail = string | number | boolean | null | string[];
+
+export interface AuditEntry {
+  action: AuditAction;
+  target?: { kind: string; id: string; label?: string } | null;
+  details?: Record<string, Detail | undefined>;
+}
+
+/** Someone at the server's machine (`npm run pair`): proven by access to the data folder. */
+export const HOST_ACTOR: AuditActor = { kind: 'host', id: null, label: 'Server machine' };
+export const SYSTEM_ACTOR: AuditActor = { kind: 'system', id: null, label: 'Botons' };
+
+const SECRETISH = /(token|secret|password|code|key|authorization|cookie)/i;
+
+function clean(details: Record<string, Detail | undefined> = {}): Record<string, Detail> {
+  const out: Record<string, Detail> = {};
+  for (const [k, v] of Object.entries(details)) {
+    if (v === undefined || SECRETISH.test(k)) continue;
+    if (Array.isArray(v)) out[k] = v.slice(0, 50).map((x) => String(x).slice(0, 200));
+    else out[k] = typeof v === 'string' ? v.slice(0, 200) : v;
+  }
+  return out;
+}
+
+/**
+ * Also used by `npm run pair`, which works on the database directly. Never throws: an audit row must not undo the
+ * action. With `required`, it throws instead: inside the caller's transaction, so the action and its record are kept
+ * together or not at all.
+ */
+export function recordAudit(db: DatabaseSync, actor: AuditActor, entry: AuditEntry, opts: { required?: boolean } = {}): void {
+  try {
+    db.prepare(
+      'insert into audit_events (at, actor_kind, actor_id, actor_label, action, target_kind, target_id, target_label, details) values (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    ).run(
+      nowIso(),
+      actor.kind,
+      actor.id,
+      actor.label.slice(0, 120),
+      entry.action,
+      entry.target?.kind ?? null,
+      entry.target?.id ?? null,
+      (entry.target?.label ?? '').slice(0, 120),
+      JSON.stringify(clean(entry.details)),
+    );
+    db.prepare('delete from audit_events where seq <= (select max(seq) from audit_events) - ?').run(AUDIT_KEEP);
+  } catch (err) {
+    log.error('could not write an audit event', { action: entry.action, required: opts.required || undefined, err });
+    if (opts.required) throw err;
+  }
+}
+
+function toEvent(r: Row): AuditEvent {
+  return {
+    seq: Number(r.seq),
+    at: r.at,
+    actor: { kind: r.actor_kind, id: r.actor_id ?? null, label: r.actor_label },
+    action: r.action,
+    target: r.target_kind ? { kind: r.target_kind, id: r.target_id ?? '', label: r.target_label } : null,
+    details: parseJson(r.details, {}),
+  };
+}
+
+export class Audit {
+  #db: DatabaseSync;
+
+  constructor(db: DatabaseSync) {
+    this.#db = db;
+  }
+
+  /** The device's label or the Boton's name as they are now, so the row still reads after either is gone. */
+  actorOf(principal: Principal | null): AuditActor {
+    if (principal?.kind === 'boton') {
+      const name = this.#db.prepare('select name from bots where id = ?').get(principal.botId)?.name;
+      return { kind: 'boton', id: principal.botId, label: String(name ?? principal.botId) };
+    }
+    if (principal?.kind === 'device' && principal.deviceId) {
+      const label = this.#db.prepare('select label from auth_tokens where id = ?').get(principal.deviceId)?.label;
+      return { kind: 'device', id: principal.deviceId, label: String(label ?? principal.deviceId) };
+    }
+    // Only with BOTONS_AUTH=off and no token.
+    return { kind: 'device', id: null, label: 'Unpaired (auth off)' };
+  }
+
+  record(by: Principal | null | AuditActor, entry: AuditEntry): void {
+    const actor = by && 'label' in by ? by : this.actorOf(by);
+    recordAudit(this.#db, actor, entry);
+  }
+
+  /** For an action that must not happen unrecorded: throws if the row can't be written, so the caller's transaction rolls back. */
+  require(by: Principal | null | AuditActor, entry: AuditEntry): void {
+    const actor = by && 'label' in by ? by : this.actorOf(by);
+    recordAudit(this.#db, actor, entry, { required: true });
+  }
+
+  /**
+   * Newest first: the connector's (or skill's) own events and projections of grant events naming it, read only from
+   * that kind's own fields.
+   * The global audit keeps the complete event; this view never includes unrelated grants or rules.
+   */
+  about(targets: { kind: string; id: string }[], mention: string, limit = 50, of: 'connector' | 'skill' = 'connector'): AuditEvent[] {
+    const keys = of === 'skill' ? ['skills', 'skillsAdded', 'skillsRemoved'] : ['connections', 'connectionsAdded', 'connectionsRemoved'];
+    const quoted = JSON.stringify(mention).replace(/[\\%_]/g, (ch) => `\\${ch}`);
+    const where = [...targets.map(() => '(target_kind = ? and target_id = ?)'), "details like ? escape '\\'"].join(' or ');
+    const rows = this.#db
+      .prepare(`select * from audit_events where ${where} order by seq desc limit 1000`)
+      .all(...targets.flatMap((t) => [t.kind, t.id]), `%${quoted}%`)
+      .map(toEvent);
+    return rows.flatMap((e): AuditEvent[] => {
+      if (e.target && targets.some((t) => t.kind === e.target!.kind && t.id === e.target!.id)) return [e];
+      const details: AuditEvent['details'] = {};
+      for (const key of keys) {
+        const value = e.details[key];
+        if (Array.isArray(value) && value.includes(mention)) details[key] = [mention];
+      }
+      if (of === 'connector' && e.details.connector === mention) {
+        details.connector = mention;
+        for (const key of ['connectorName', 'boton', 'kind', 'status', 'always', 'grant', 'decision']) {
+          if (Object.hasOwn(e.details, key)) details[key] = e.details[key];
+        }
+      }
+      if (!Object.keys(details).length) return [];
+      if (e.details.via === of) details.via = of;
+      if (of === 'skill' && e.details.everySkill === true) details.everySkill = true;
+      return [{ ...e, details }];
+    }).slice(0, limit);
+  }
+
+  /** Newest first. */
+  list(opts: { before?: number; limit?: number } = {}): AuditEvent[] {
+    const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100) || 100, 1), 500);
+    const rows = opts.before
+      ? this.#db.prepare('select * from audit_events where seq < ? order by seq desc limit ?').all(opts.before, limit)
+      : this.#db.prepare('select * from audit_events order by seq desc limit ?').all(limit);
+    return rows.map(toEvent);
+  }
+}