attesso 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# attesso
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused. Any action, not only payments. No account, no server, no dependencies.
+
+```sh
+npx attesso init
+npx attesso log --action tool.call --subject read_file --meta tokens=1200 --meta cost_usd=0.0004
+npx attesso log --action purchase.execute --subject shop.example --amount 12.50 --currency EUR
+npx attesso verify
+npx attesso show
+npx attesso report
+```
+
+`init` writes `.attesso/` with an Ed25519 key, a policy and an empty ledger. `log` evaluates one proposed action against the policy, records the decision and its reason, and exits 1 when it refuses. `verify` recomputes the hash chain and every signature. `show` prints what was allowed, what was refused, which subjects dominate, and any tokens or cost you passed in `--meta`. `--dir PATH` points any command at a different ledger.
+
+## The overview
+
+`attesso report` is the view that answers what the thing cost and what it stopped, per task:
+
+```
+2059 entries, key 1qTU-tGyjuQwt3kI: 2058 actions, 455 refused (22%), 3,922,488 tokens, 3.1932 USD
+
+task                                actions  refused    top              tokens     cached       cost
+──────────────────────────────────  ───────  ─────────  ───────────────  ─────────  ───────────  ──────
+hermes-local-9552aa28437e88c0610a…  2058     455 (22%)  PATH_DENIED×455  3,922,488  645,785,088  3.1932
+```
+
+Actions are tool calls; refusals carry the reason; tokens are input plus output, with cache reads shown separately because they bill at a different rate and dwarf the rest. Cost comes from a `llm.session` entry the recorder writes from the agent's own usage record, never from a number the report invents. `--json` gives the same data for a dashboard.
+
+## What it records
+
+One signed line per proposed action:
+
+```json
+{"v":1,"seq":1,"at":"2026-10-31T12:00:00.000Z","action":"tool.call",
+ "subject":"read_file","decision":"ALLOW","code":"ALLOW","policy_digest":"…",
+ "kid":"…","prev":"genesis","meta":{"tokens":1200,"cost_usd":0.0004},"sig":"…"}
+```
+
+`subject` is the thing acted on: a tool name, a payee, a repo, a recipient. `amount` appears only for money actions. Refusal codes match the hosted engine: `ACTION_MISMATCH`, `ABOVE_MAXIMUM`, `VALUE_NOT_ALLOWED`, `VALUE_MISMATCH`, `OUTSIDE_DATE_RANGE`, `REQUIRED_ATTRIBUTE_MISSING`.
+
+## The policy
+
+`.attesso/policy.json` starts empty, so nothing is allowed until you set it. A policy governs one action; `"action": "*"` covers every action and is what a recording-only ledger uses.
+
+```json
+{ "version": 1, "action": "tool.call", "subjects": ["read_file", "search_files", "grep_repo"] }
+```
+
+```json
+{
+  "version": 1,
+  "action": "purchase.execute",
+  "currency": "EUR",
+  "max_amount": 25000,
+  "subjects": ["shop.example"],
+  "on_or_after": "2026-11-01T00:00:00Z",
+  "on_or_before": "2026-12-01T00:00:00Z"
+}
+```
+
+Money is optional: without `max_amount` and `currency` the policy is judged on action, subject and window alone. Amounts in the policy are whole minor units (25000 = 250.00 EUR); `log --amount` takes the decimal form.
+
+## Policies on paths
+
+A single step can look fine and the sequence still be wrong: reading an untrusted page and then sending it somewhere is an exfiltration no per-step check can see. `attesso` judges an action against the path of its task, not in isolation. Three flags give it the shape of the step, and `.attesso/rules.json` says what a path may not do.
+
+```sh
+npx attesso log --action web.read   --subject docs.example         --task job-1 --trust untrusted --capability read
+npx attesso log --action mail.send  --subject partner@example.com  --task job-1 --capability send
+# #2 DENY mail.send partner@example.com (PATH_DENIED by step #1 under no-send-after-untrusted-read)
+
+npx attesso log --action file.read  --subject src/app.ts           --task job-2 --trust internal  --capability read
+npx attesso log --action mail.send  --subject partner@example.com  --task job-2 --capability send
+# #4 ALLOW mail.send partner@example.com (ALLOW)
+```
+
+`init` ships one rule, and it is the one worth having:
+
+```json
+{ "version": 1,
+  "rules": [
+    { "id": "no-send-after-untrusted-read",
+      "deny": { "capabilities": ["send", "execute"] },
+      "if_path": { "trust": "untrusted", "capability": "read", "within_minutes": 30 } }
+  ] }
+```
+
+`--task` scopes the history, so one job cannot taint another. `within_minutes` limits how long a read stays relevant; without it a taint lasts for the whole task. `--capability` is one of `read`, `send`, `execute`, `spend`. The refusal names the rule and the step that tainted the path, so a reader can see the sequence rather than a verdict.
+
+Rules are ordinary files you own and version. Run them in observe mode first: `node scripts/hermes-ledger.mjs --observe` records what the rules would have refused without touching the agent, which is how you learn where a rule is too broad before it costs you a day.
+
+## Recording a real agent
+
+`attesso` is a CLI, so anything that can run a command can record an action. To see what a Hermes session actually did, the repo ships `scripts/hermes-ledger.mjs`, which reads a session from `state.db` read-only and appends one entry per tool call.
+
+```sh
+node scripts/hermes-ledger.mjs --dir .hermes/tmp/attesso-dogfood --observe
+npx attesso --dir .hermes/tmp/attesso-dogfood show
+```
+
+`--observe` labels every verdict the rules produced and prints how many steps they would have refused; nothing in the agent is blocked. Tool calls are classified on the way in: `read_file` and the repo search tools read internal material, the web and browser tools read untrusted material, and anything that writes, executes or spawns is an effect.
+
+## What this proves, and what it does not
+
+The signature proves the ledger was not edited after the fact: change one byte and `verify` names the entry, reorder two and the chain breaks, delete the last one and the recorded head no longer matches.
+
+It does not prove a human authorized anything. The signing key lives in `.attesso/key.json`, in the same directory as the log, so anything that can write the log can also write a new one. It cannot see absence either: a process that deletes the whole directory leaves nothing to verify.
+
+Hosted Attesso is where authority lives: a passkey approval binds a named human to exact terms, the decision and the refusal are recorded server-side, and the result is evidence a third party verifies offline against a published key. The local ledger uses the same event and code vocabulary, so it can be submitted there later.
+
+## Exit codes
+
+`0` allowed or verified, `1` refused or a failed verification, `2` usage error.
+
+## License
+
+Apache-2.0.

package/bin/attesso.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// attesso: a local, signed ledger of what your agents attempted.
+//
+//   attesso init
+//   attesso log --action tool.call --subject read_file --meta tokens=1200 --meta cost_usd=0.0004
+//   attesso log --action purchase.execute --subject shop.example --amount 12.50 --currency EUR
+//   attesso verify
+//   attesso show
+import { verifyChain } from './../src/ledger.mjs';
+import { formatMinor, toMinor } from './../src/policy.mjs';
+import { append, init, isInitialised, paths, readState } from './../src/store.mjs';
+import { buildReport, renderReport } from './../src/report.mjs';
+
+const argv = process.argv.slice(2);
+const dirAt = argv.indexOf('--dir');
+const DIR = dirAt === -1 ? '.attesso' : argv[dirAt + 1];
+if (dirAt !== -1) argv.splice(dirAt, 2);
+
+const USAGE = `attesso: a local, signed ledger of what your agents attempted
+
+  attesso init [--dir PATH]          create .attesso with a key and a policy
+  attesso log --action A [--subject S] [--amount 12.50 --currency EUR]
+              [--task T] [--trust internal|untrusted] [--capability read|send|execute|spend]
+              [--meta k=v ...] [--json]
+                                     evaluate one proposed action against the policy
+                                     and the path of its task, then record it
+  attesso verify                     recompute the chain and report the first defect
+  attesso show                       what was allowed, what was refused, and why
+  attesso report [--json]            per task: actions, refusals with reasons, tokens and cost
+
+Any action can be logged, not only payments. --subject is the thing acted on (a
+tool name, a payee, a repo). --task scopes the path, --trust marks where the
+content came from, and --capability says what the step does; with those three, a
+rule in .attesso/rules.json can refuse a send that follows an untrusted read,
+which no per-step check can see. --meta carries whatever you want counted later
+(tokens, cost_usd, duration_ms, model).
+
+The log is signed with a key that lives in .attesso/key.json. That proves the
+ledger was not edited; it does not prove a human authorized anything. Hosted
+Attesso adds passkey approval and evidence a third party verifies offline.`;
+
+function flags(argv) {
+  const out = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) continue;
+    const name = token.slice(2);
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith('--')) {
+      out[name] = true;
+      continue;
+    }
+    if (name === 'meta') {
+      out.meta = [...(out.meta ?? []), next];
+    } else {
+      out[name] = next;
+    }
+    index += 1;
+  }
+  return out;
+}
+
+function parseMeta(pairs = []) {
+  const meta = {};
+  for (const pair of pairs) {
+    const at = pair.indexOf('=');
+    if (at <= 0) throw new Error(`--meta expects key=value, got ${pair}`);
+    const key = pair.slice(0, at);
+    const raw = pair.slice(at + 1);
+    meta[key] = raw !== '' && !Number.isNaN(Number(raw)) ? Number(raw) : raw;
+  }
+  return meta;
+}
+
+function requireLedger() {
+  if (!isInitialised(DIR)) {
+    console.error(`no ledger at ${paths(DIR).dir}; run attesso init first`);
+    process.exit(2);
+  }
+}
+
+function describe(entry) {
+  const subject = entry.subject ? ` ${entry.subject}` : '';
+  const amount = entry.amount ? ` ${formatMinor(entry.amount.minor, entry.amount.currency)} ${entry.amount.currency}` : '';
+  return `${entry.action}${subject}${amount}`;
+}
+
+function log(argv) {
+  requireLedger();
+  const options = flags(argv);
+  if (typeof options.action !== 'string') {
+    console.error('attesso log needs --action');
+    process.exit(2);
+  }
+  if ((options.amount === undefined) !== (options.currency === undefined)) {
+    console.error('--amount and --currency go together');
+    process.exit(2);
+  }
+  let amount;
+  if (options.amount !== undefined) {
+    try {
+      amount = { minor: toMinor(options.amount, options.currency), currency: options.currency };
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+  }
+  let meta;
+  try {
+    meta = parseMeta(options.meta);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(2);
+  }
+
+  if (options.trust !== undefined && !['internal', 'untrusted', 'unknown'].includes(options.trust)) {
+    console.error('--trust takes internal, untrusted or unknown');
+    process.exit(2);
+  }
+  if (options.capability !== undefined && !['read', 'send', 'execute', 'spend'].includes(options.capability)) {
+    console.error('--capability takes read, send, execute or spend');
+    process.exit(2);
+  }
+  const entry = append(DIR, {
+    action: options.action,
+    subject: options.subject,
+    amount,
+    meta,
+    task: typeof options.task === 'string' ? options.task : undefined,
+    trust: options.trust,
+    capability: options.capability,
+  });
+  if (options.json) {
+    console.log(JSON.stringify(entry));
+    return;
+  }
+  const taint = entry.meta?.tainted_by === undefined ? '' : ` by step #${entry.meta.tainted_by} under ${entry.meta.rule}`;
+  console.log(`#${entry.seq} ${entry.decision} ${describe(entry)} (${entry.code}${taint})`);
+  process.exitCode = entry.decision === 'ALLOW' ? 0 : 1;
+}
+
+function verify() {
+  requireLedger();
+  const state = readState(DIR);
+  const result = verifyChain(state.entries, state.key.public, state.config.head);
+  if (!result.ok) {
+    console.error(`ledger does not verify: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`ledger verifies: ${result.reason}, key ${state.key.kid}`);
+}
+
+function totals(entries) {
+  const sum = (field) =>
+    entries.reduce((total, entry) => total + (Number(entry.meta?.[field]) || 0), 0);
+  const tokens = sum('tokens');
+  const cost = sum('cost_usd');
+  const parts = [];
+  if (tokens > 0) parts.push(`${tokens.toLocaleString('en-US')} tokens`);
+  if (cost > 0) parts.push(`${cost.toFixed(4)} USD`);
+  return parts.length > 0 ? `, ${parts.join(', ')}` : '';
+}
+
+function show() {
+  requireLedger();
+  const { entries, key } = readState(DIR);
+  if (entries.length === 0) {
+    console.log('no decisions yet');
+    return;
+  }
+  const counts = new Map();
+  for (const entry of entries) {
+    const label = `${entry.decision} ${entry.code}`;
+    counts.set(label, (counts.get(label) ?? 0) + 1);
+  }
+  const allowed = entries.filter((entry) => entry.decision === 'ALLOW').length;
+  console.log(
+    `${entries.length} decisions: ${allowed} allowed, ${entries.length - allowed} refused${totals(entries)} (key ${key.kid})`,
+  );
+  for (const [label, count] of [...counts.entries()].sort()) {
+    console.log(`  ${String(count).padStart(4)}  ${label}`);
+  }
+  const bySubject = new Map();
+  for (const entry of entries) {
+    const label = entry.subject ?? '(none)';
+    bySubject.set(label, (bySubject.get(label) ?? 0) + 1);
+  }
+  if (bySubject.size > 0 && [...bySubject.keys()].some((label) => label !== '(none)')) {
+    console.log('subjects:');
+    for (const [label, count] of [...bySubject.entries()].sort((left, right) => right[1] - left[1])) {
+      console.log(`  ${String(count).padStart(4)}  ${label}`);
+    }
+  }
+  console.log('latest:');
+  for (const entry of entries.slice(-5)) {
+    console.log(`  #${entry.seq} ${entry.at} ${entry.decision} ${describe(entry)} (${entry.code})`);
+  }
+}
+
+const [command, ...rest] = argv;
+switch (command) {
+  case 'init': {
+    try {
+      const result = init(DIR);
+      console.log(`created ${result.dir} with key ${result.kid}`);
+      console.log('edit .attesso/policy.json to set what is allowed (it starts at nothing)');
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    break;
+  }
+  case 'log':
+    log(rest);
+    break;
+  case 'verify':
+    verify();
+    break;
+  case 'show':
+    show();
+    break;
+  case 'report': {
+    requireLedger();
+    const report = buildReport(DIR);
+    if (rest.includes('--json')) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      process.stdout.write(renderReport(report));
+    }
+    break;
+  }
+  case undefined:
+    console.log(USAGE);
+    break;
+  default:
+    if (command === '--help' || command === '-h' || command === 'help') {
+      console.log(USAGE);
+      break;
+    }
+    console.error(`unknown command ${command}\n`);
+    console.log(USAGE);
+    process.exit(2);
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "attesso",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "attesso": "./bin/attesso.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-governance",
+    "audit",
+    "ledger",
+    "guardrails"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/douwe/attesso.git",
+    "directory": "packages/attesso"
+  }
+}

package/src/canonical.mjs

@@ -0,0 +1,8 @@
+// One canonical form for anything that is hashed or signed. Key order must not
+// depend on how a caller happened to build the object.
+export function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}

package/src/ledger.mjs

@@ -0,0 +1,87 @@
+// The ledger itself: one signed entry per proposed action, chained so an edit
+// breaks every later entry. Ed25519 keys generated on first use; the private key
+// stays in the project directory, which is why a local log proves integrity and
+// not authority.
+import { createHash, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+
+export const ENTRY_VERSION = 1;
+
+export function newSigningKey() {
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+  return {
+    kid: keyId(publicKey.export({ format: 'jwk' })),
+    publicPem: publicKey.export({ type: 'spki', format: 'pem' }),
+    privatePem: privateKey.export({ type: 'pkcs8', format: 'pem' }),
+  };
+}
+
+// RFC 7638 style thumbprint: the members that identify an Ed25519 key, sorted.
+export function keyId(publicJwk) {
+  const thumbprint = canonical({ crv: publicJwk.crv, kty: publicJwk.kty, x: publicJwk.x });
+  return createHash('sha256').update(thumbprint).digest('base64url').slice(0, 16);
+}
+
+export function entryHash(entry) {
+  return createHash('sha256').update(canonical(entry)).digest('base64url');
+}
+
+function signingPayload(entry) {
+  const { sig, ...rest } = entry;
+  return Buffer.from(canonical(rest));
+}
+
+export function signEntry(entry, privatePem) {
+  return sign(null, signingPayload(entry), privatePem).toString('base64url');
+}
+
+export function verifyEntry(entry, publicPem) {
+  return verify(null, signingPayload(entry), publicPem, Buffer.from(entry.sig, 'base64url'));
+}
+
+export function buildEntry({ seq, prev, action, subject, amount, meta, task, trust, capability, decision, code, policyDigest, kid, at }) {
+  const entry = {
+    v: ENTRY_VERSION,
+    seq,
+    at: at ?? new Date().toISOString(),
+    action,
+    subject: subject ?? null,
+    decision,
+    code,
+    policy_digest: policyDigest,
+    kid,
+    prev,
+  };
+  if (amount) entry.amount = amount;
+  if (task) entry.task = task;
+  if (trust) entry.trust = trust;
+  if (capability) entry.capability = capability;
+  if (meta && Object.keys(meta).length > 0) entry.meta = meta;
+  return entry;
+}
+
+// Returns the first defect rather than a boolean, so a reader learns which entry
+// to look at. `head` comes from config, which is what makes truncation visible.
+export function verifyChain(entries, publicPem, head) {
+  let previous = 'genesis';
+  for (const [index, entry] of entries.entries()) {
+    if (entry.seq !== index + 1) {
+      return { ok: false, reason: `entry ${index + 1} carries seq ${entry.seq}` };
+    }
+    if (entry.prev !== previous) {
+      return { ok: false, reason: `entry ${entry.seq} does not chain to the entry before it` };
+    }
+    if (!verifyEntry(entry, publicPem)) {
+      return { ok: false, reason: `entry ${entry.seq} signature does not verify` };
+    }
+    previous = entryHash(entry);
+  }
+  if (!head) return { ok: false, reason: 'no recorded head, so the end of the log cannot be checked' };
+  if (head.count !== entries.length) {
+    return { ok: false, reason: `config records ${head.count} entries, the log holds ${entries.length}` };
+  }
+  if (head.hash !== previous) {
+    return { ok: false, reason: 'the last entry does not match the recorded head' };
+  }
+  return { ok: true, reason: `chain of ${entries.length} entries verifies` };
+}

package/src/policy.mjs

@@ -0,0 +1,97 @@
+// Deterministic local policy, for any agent action, money or not. Codes match
+// the hosted engine so a local refusal reads the same as a server one.
+import { createHash } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+
+export const ALLOW = 'ALLOW';
+
+const EXPONENTS = { EUR: 2, USD: 2, GBP: 2, CHF: 2, SEK: 2, JPY: 0 };
+
+export function toMinor(amount, currency) {
+  const exponent = EXPONENTS[currency];
+  if (exponent === undefined) {
+    throw new Error(`unsupported currency ${currency}; add its exponent to src/policy.mjs`);
+  }
+  if (!/^\d+(\.\d+)?$/.test(String(amount))) throw new Error(`amount ${amount} is not a positive decimal`);
+  const [whole, fraction = ''] = String(amount).split('.');
+  if (fraction.length > exponent) {
+    throw new Error(`amount ${amount} has more than ${exponent} decimal places for ${currency}`);
+  }
+  return Number(whole) * 10 ** exponent + Number(fraction.padEnd(exponent, '0'));
+}
+
+export function formatMinor(minor, currency) {
+  const exponent = EXPONENTS[currency] ?? 2;
+  const scale = 10 ** exponent;
+  return `${Math.trunc(minor / scale)}.${String(minor % scale).padStart(exponent, '0')}`;
+}
+
+export function policyDigest(policy) {
+  return createHash('sha256').update(canonical(policy)).digest('base64url');
+}
+
+// A policy is about one action. Money is optional: an action like tool.call or
+// repo.write has bounds but no amount, and saying so with max_amount is wrong.
+export function validatePolicy(policy) {
+  const fail = (message) => {
+    throw new Error(`policy is invalid: ${message}`);
+  };
+  if (policy === null || typeof policy !== 'object') fail('not an object');
+  if (policy.version !== 1) fail('version must be 1');
+  if (typeof policy.action !== 'string' || policy.action === '') fail('action must be a non-empty string');
+  if (policy.action !== '*' && policy.action.trim() === '') fail('action must be a non-empty string or *');
+
+  const money = policy.max_amount !== undefined || policy.currency !== undefined;
+  if (money) {
+    if (!EXPONENTS[policy.currency]) fail(`currency ${policy.currency} is not supported`);
+    if (!Number.isInteger(policy.max_amount) || policy.max_amount < 0) {
+      fail('max_amount must be a whole number of minor units, 0 or more');
+    }
+  }
+  if (policy.subjects !== undefined) {
+    if (!Array.isArray(policy.subjects) || policy.subjects.some((item) => typeof item !== 'string' || item === '')) {
+      fail('subjects must be a list of non-empty strings when present');
+    }
+  }
+  for (const field of ['on_or_after', 'on_or_before']) {
+    if (policy[field] !== undefined && Number.isNaN(Date.parse(policy[field]))) {
+      fail(`${field} must be an ISO date when present`);
+    }
+  }
+  return policy;
+}
+
+// Order matters for the reader: the most specific reason wins, so a refusal
+// names one cause rather than a list.
+export function evaluate(policy, proposal, now = new Date()) {
+  if (policy.action !== '*' && proposal.action !== policy.action) {
+    return { decision: 'DENY', code: 'ACTION_MISMATCH' };
+  }
+  if (policy.subjects !== undefined) {
+    if (typeof proposal.subject !== 'string') {
+      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
+    }
+    if (!policy.subjects.includes(proposal.subject)) {
+      return { decision: 'DENY', code: 'VALUE_NOT_ALLOWED' };
+    }
+  }
+  if (policy.max_amount !== undefined) {
+    if (!proposal.amount || !Number.isInteger(proposal.amount.minor)) {
+      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
+    }
+    if (proposal.amount.currency !== policy.currency) {
+      return { decision: 'DENY', code: 'VALUE_MISMATCH' };
+    }
+    if (proposal.amount.minor > policy.max_amount) {
+      return { decision: 'DENY', code: 'ABOVE_MAXIMUM' };
+    }
+  }
+  const at = now.getTime();
+  if (policy.on_or_after && at < Date.parse(policy.on_or_after)) {
+    return { decision: 'DENY', code: 'OUTSIDE_DATE_RANGE' };
+  }
+  if (policy.on_or_before && at > Date.parse(policy.on_or_before)) {
+    return { decision: 'DENY', code: 'OUTSIDE_DATE_RANGE' };
+  }
+  return { decision: ALLOW, code: ALLOW };
+}

package/src/report.mjs

@@ -0,0 +1,76 @@
+// The overview that answers "what did this actually cost me, and what did it
+// stop": per task, how many actions ran, how many were refused and why, and the
+// tokens and money the task spent. Costs come from a llm.session entry the
+// recorder writes, never from an estimate the report invents.
+import { readState } from './store.mjs';
+
+const isSpend = (entry) => entry.action === 'llm.session';
+const isAction = (entry) => !isSpend(entry);
+
+function summarise(entries) {
+  const actions = entries.filter(isAction);
+  const blocked = actions.filter((entry) => entry.decision !== 'ALLOW');
+  const reasons = new Map();
+  for (const entry of blocked) {
+    const key = entry.code ?? 'UNKNOWN';
+    reasons.set(key, (reasons.get(key) ?? 0) + 1);
+  }
+  const sum = (field) => entries.reduce((total, entry) => total + (Number(entry.meta?.[field]) || 0), 0);
+  return {
+    actions: actions.length,
+    allowed: actions.length - blocked.length,
+    blocked: blocked.length,
+    blocked_share: actions.length === 0 ? null : blocked.length / actions.length,
+    reasons: [...reasons.entries()].sort((left, right) => right[1] - left[1]).map(([code, count]) => ({ code, count })),
+    tokens: sum('tokens'),
+    cached_tokens: sum('cached_tokens'),
+    cost_usd: Number(sum('cost_usd').toFixed(6)),
+    api_calls: sum('api_calls'),
+  };
+}
+
+export function buildReport(dir) {
+  const { entries, key } = readState(dir);
+  const groups = new Map();
+  for (const entry of entries) {
+    const task = entry.task ?? '(unscoped)';
+    if (!groups.has(task)) groups.set(task, []);
+    groups.get(task).push(entry);
+  }
+  const tasks = [...groups.entries()]
+    .map(([task, rows]) => ({ task, ...summarise(rows) }))
+    .sort((left, right) => right.actions - left.actions);
+  const totals = summarise(entries);
+  return { key: key.kid, entries: entries.length, tasks, totals };
+}
+
+const percent = (share) => (share === null ? 'n/a' : `${Math.round(share * 100)}%`);
+
+export function renderReport(report) {
+  const lines = [];
+  lines.push(
+    `${report.entries} entries, key ${report.key}: ${report.totals.actions} actions, ` +
+      `${report.totals.blocked} refused (${percent(report.totals.blocked_share)}), ` +
+      `${report.totals.tokens.toLocaleString('en-US')} tokens, ${report.totals.cost_usd.toFixed(4)} USD`,
+  );
+  lines.push('');
+  const rows = report.tasks.map((task) => ({
+    task: task.task.length > 34 ? `${task.task.slice(0, 33)}…` : task.task,
+    actions: String(task.actions),
+    refused: `${task.blocked} (${percent(task.blocked_share)})`,
+    top: task.reasons.slice(0, 2).map((reason) => `${reason.code}×${reason.count}`).join(' '),
+    tokens: task.tokens.toLocaleString('en-US'),
+    cached: task.cached_tokens > 0 ? task.cached_tokens.toLocaleString('en-US') : '',
+    cost: task.cost_usd > 0 ? task.cost_usd.toFixed(4) : '',
+  }));
+  const width = (field) => Math.max(field.length, ...rows.map((row) => String(row[field]).length));
+  const columns = ['task', 'actions', 'refused', 'top', 'tokens', 'cached', 'cost'];
+  const sizes = Object.fromEntries(columns.map((column) => [column, width(column)]));
+  const header = columns.map((column) => column.padEnd(sizes[column])).join('  ');
+  lines.push(header);
+  lines.push(columns.map((column) => '─'.repeat(sizes[column])).join('  '));
+  for (const row of rows) {
+    lines.push(columns.map((column) => String(row[column]).padEnd(sizes[column])).join('  '));
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/rules.mjs

@@ -0,0 +1,65 @@
+// Policies on paths: an action is judged against the ordered history of the same
+// task, not in isolation. A read of something untrusted followed by a send is the
+// case no per-step check can catch, and it is the reason this file exists.
+import { createHash } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+
+export const CAPABILITIES = ['read', 'send', 'execute', 'spend'];
+export const TRUST_LEVELS = ['internal', 'untrusted', 'unknown'];
+
+export function rulesDigest(rules) {
+  return createHash('sha256').update(canonical(rules)).digest('base64url');
+}
+
+export function validateRules(rules) {
+  const fail = (message) => {
+    throw new Error(`rules are invalid: ${message}`);
+  };
+  if (rules === null || typeof rules !== 'object') fail('not an object');
+  if (rules.version !== 1) fail('version must be 1');
+  if (!Array.isArray(rules.rules)) fail('rules must be a list');
+  for (const rule of rules.rules) {
+    if (typeof rule.id !== 'string' || rule.id === '') fail('every rule needs an id');
+    const deny = rule.deny ?? {};
+    const denies = deny.capabilities ?? (deny.capability ? [deny.capability] : []);
+    if (denies.length === 0) fail(`rule ${rule.id} denies nothing`);
+    for (const capability of denies) {
+      if (!CAPABILITIES.includes(capability)) fail(`rule ${rule.id} denies unknown capability ${capability}`);
+    }
+    const trigger = rule.if_path ?? {};
+    if (trigger.trust && !TRUST_LEVELS.includes(trigger.trust)) fail(`rule ${rule.id} names unknown trust ${trigger.trust}`);
+    if (trigger.capability && !CAPABILITIES.includes(trigger.capability)) {
+      fail(`rule ${rule.id} triggers on unknown capability ${trigger.capability}`);
+    }
+    if (trigger.trust === undefined && trigger.capability === undefined) {
+      fail(`rule ${rule.id} has no path condition`);
+    }
+    if (trigger.within_minutes !== undefined && (!Number.isInteger(trigger.within_minutes) || trigger.within_minutes < 0)) {
+      fail(`rule ${rule.id} needs whole minutes for within_minutes`);
+    }
+  }
+  return rules;
+}
+
+// The most recent matching step taints the path; naming it is what makes the
+// refusal explainable rather than mysterious.
+export function evaluatePath(rules, history, proposal, now = new Date()) {
+  if (!rules) return null;
+  for (const rule of rules.rules ?? []) {
+    const deny = rule.deny ?? {};
+    const denied = deny.capabilities ?? (deny.capability ? [deny.capability] : []);
+    if (proposal.capability && !denied.includes(proposal.capability)) continue;
+    const trigger = rule.if_path ?? {};
+    const window = (trigger.within_minutes ?? 0) * 60_000;
+    const hit = [...history].reverse().find((entry) => {
+      if (trigger.trust && entry.trust !== trigger.trust) return false;
+      if (trigger.capability && entry.capability !== trigger.capability) return false;
+      if (window > 0 && now.getTime() - Date.parse(entry.at) > window) return false;
+      return true;
+    });
+    if (hit) {
+      return { decision: 'DENY', code: 'PATH_DENIED', rule: rule.id, tainted_by: hit.seq };
+    }
+  }
+  return null;
+}

package/src/store.mjs

@@ -0,0 +1,165 @@
+// File layout under .attesso/:
+//   key.json     Ed25519 key pair, 0600, generated by init
+//   policy.json  the bounds this project allows
+//   ledger.jsonl one signed entry per line
+//   config.json  the recorded head (count + hash), the only thing that makes a
+//                truncated log visible
+//   lock         held while appending, so two agents cannot interleave writes
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildEntry, entryHash, newSigningKey, signEntry } from './ledger.mjs';
+import { evaluate, policyDigest, validatePolicy } from './policy.mjs';
+import { evaluatePath, rulesDigest, validateRules } from './rules.mjs';
+
+export function paths(dir) {
+  return {
+    dir,
+    key: join(dir, 'key.json'),
+    policy: join(dir, 'policy.json'),
+    rules: join(dir, 'rules.json'),
+    ledger: join(dir, 'ledger.jsonl'),
+    config: join(dir, 'config.json'),
+    lock: join(dir, 'lock'),
+  };
+}
+
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
+
+function writeJson(path, value) {
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function isInitialised(dir) {
+  return existsSync(paths(dir).key);
+}
+
+export function init(dir) {
+  if (isInitialised(dir)) {
+    throw new Error(`${dir} already holds a ledger; refusing to replace its key`);
+  }
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = paths(dir);
+  const key = newSigningKey();
+  writeJson(file.key, { version: 1, kid: key.kid, public: key.publicPem, private: key.privatePem });
+  writeJson(file.policy, {
+    version: 1,
+    action: 'EXAMPLE.action',
+    subjects: [],
+  });
+  writeJson(file.config, { version: 1, head: { count: 0, hash: 'genesis' } });
+  writeJson(file.rules, {
+    version: 1,
+    rules: [
+      { id: 'no-send-after-untrusted-read', deny: { capabilities: ['send', 'execute'] }, if_path: { trust: 'untrusted', capability: 'read' } },
+    ],
+  });
+  writeFileSync(file.ledger, '', { mode: 0o600 });
+  return { dir, kid: key.kid };
+}
+
+export function readState(dir) {
+  const file = paths(dir);
+  return {
+    key: readJson(file.key),
+    config: readJson(file.config),
+    policy: readJson(file.policy),
+    rules: existsSync(file.rules) ? readJson(file.rules) : null,
+    entries: readEntries(dir),
+  };
+}
+
+export function readEntries(dir) {
+  const text = readFileSync(paths(dir).ledger, 'utf8');
+  if (text === '') return [];
+  return text
+    .split('\n')
+    .filter((line) => line !== '')
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        throw new Error(`ledger line ${index + 1} is not JSON; the file was edited or truncated mid-line`);
+      }
+    });
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function withLock(dir, run) {
+  const { lock } = paths(dir);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = openSync(lock, 'wx', 0o600);
+      writeSync(handle, String(process.pid));
+      closeSync(handle);
+      try {
+        return run();
+      } finally {
+        unlinkSync(lock);
+      }
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const holder = Number(readFileSync(lock, 'utf8'));
+      if (!processAlive(holder)) {
+        unlinkSync(lock);
+        continue;
+      }
+      throw new Error(`another attesso process (pid ${holder}) holds the ledger; retry when it finishes`);
+    }
+  }
+  throw new Error('could not take the ledger lock');
+}
+
+export function append(dir, proposal, { now = new Date() } = {}) {
+  return withLock(dir, () => {
+    const file = paths(dir);
+    const key = readJson(file.key);
+    const config = readJson(file.config);
+    const policy = validatePolicy(readJson(file.policy));
+    const rules = existsSync(file.rules) ? validateRules(readJson(file.rules)) : null;
+    const history = readEntries(dir).filter((entry) => (entry.task ?? null) === (proposal.task ?? null));
+    const policyVerdict = evaluate(policy, proposal, now);
+    const pathVerdict = policyVerdict.decision === 'ALLOW'
+      ? evaluatePath(rules, history, proposal, now)
+      : null;
+    const verdict = pathVerdict ?? policyVerdict;
+    const meta = pathVerdict?.tainted_by === undefined
+      ? proposal.meta
+      : { ...(proposal.meta ?? {}), rule: pathVerdict.rule, tainted_by: pathVerdict.tainted_by };
+    const seq = config.head.count + 1;
+    const entry = buildEntry({
+      seq,
+      prev: config.head.hash,
+      action: proposal.action,
+      subject: proposal.subject,
+      amount: proposal.amount,
+      meta,
+      task: proposal.task,
+      trust: proposal.trust,
+      capability: proposal.capability,
+      decision: verdict.decision,
+      code: verdict.code,
+      policyDigest: policyDigest(policy),
+      kid: key.kid,
+      at: now.toISOString(),
+    });
+    entry.sig = signEntry(entry, key.private);
+    const handle = openSync(file.ledger, 'a', 0o600);
+    try {
+      writeSync(handle, `${JSON.stringify(entry)}\n`);
+    } finally {
+      closeSync(handle);
+    }
+    writeJson(file.config, { version: 1, head: { count: seq, hash: entryHash(entry) } });
+    return entry;
+  });
+}