attesso 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,58 @@
-# 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. No account, no server, no dependencies.
+
+```sh
+npx attesso init
+npx attesso log --action purchase.execute --amount 12.50 --currency EUR --payee shop.example
+npx attesso verify
+npx attesso show
+```
+
+`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 and why.
+
+## What it records
+
+One signed line per proposed action:
+
+```json
+{"v":1,"seq":1,"at":"2026-10-31T12:00:00.000Z","action":"purchase.execute",
+ "amount":{"minor":1250,"currency":"EUR"},"payee":"shop.example",
+ "decision":"ALLOW","code":"ALLOW","policy_digest":"…","kid":"…","prev":"genesis","sig":"…"}
+```
+
+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 at zero, so nothing is allowed until you set it:
+
+```json
+{
+  "version": 1,
+  "action": "purchase.execute",
+  "currency": "EUR",
+  "max_amount": 25000,
+  "payees": ["shop.example"],
+  "on_or_after": "2026-11-01T00:00:00Z",
+  "on_or_before": "2026-12-01T00:00:00Z"
+}
+```
+
+Amounts are whole minor units in the policy (25000 = 250.00 EUR); `log --amount` takes the decimal form.
+
+## 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 also cannot see absence: 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 shape, 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,140 @@
+#!/usr/bin/env node
+// attesso: a local, signed ledger of what your agents attempted.
+//
+//   attesso init
+//   attesso log --action purchase.execute --amount 12.50 --currency EUR --payee shop.example
+//   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';
+
+const DIR = '.attesso';
+
+const USAGE = `attesso: a local, signed ledger of what your agents attempted
+
+  attesso init                       create .attesso with a key and a policy
+  attesso log --action A --amount 12.50 --currency EUR [--payee P] [--json]
+                                     evaluate one proposed action and record it
+  attesso verify                     recompute the chain and report the first defect
+  attesso show                       what was allowed, what was refused, and why
+
+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;
+    }
+    out[name] = next;
+    index += 1;
+  }
+  return out;
+}
+
+function requireLedger() {
+  if (!isInitialised(DIR)) {
+    console.error(`no ledger at ${paths(DIR).dir}; run attesso init first`);
+    process.exit(2);
+  }
+}
+
+function log(argv) {
+  requireLedger();
+  const options = flags(argv);
+  for (const required of ['action', 'amount', 'currency']) {
+    if (typeof options[required] !== 'string') {
+      console.error(`attesso log needs --${required}`);
+      process.exit(2);
+    }
+  }
+  const amount = { minor: toMinor(options.amount, options.currency), currency: options.currency };
+  const entry = append(DIR, { action: options.action, amount, payee: options.payee });
+  if (options.json) {
+    console.log(JSON.stringify(entry));
+    return;
+  }
+  const human = `${formatMinor(entry.amount.minor, entry.amount.currency)} ${entry.amount.currency}`;
+  const subject = entry.payee ? ` at ${entry.payee}` : '';
+  console.log(`#${entry.seq} ${entry.decision} ${entry.action} ${human}${subject} (${entry.code})`);
+  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 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 (key ${key.kid})`);
+  for (const [label, count] of [...counts.entries()].sort()) {
+    console.log(`  ${String(count).padStart(4)}  ${label}`);
+  }
+  const last = entries.slice(-5);
+  console.log('latest:');
+  for (const entry of last) {
+    const human = `${formatMinor(entry.amount.minor, entry.amount.currency)} ${entry.amount.currency}`;
+    console.log(`  #${entry.seq} ${entry.at} ${entry.decision} ${entry.action} ${human} (${entry.code})`);
+  }
+}
+
+const [command, ...rest] = process.argv.slice(2);
+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 zero)');
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    break;
+  }
+  case 'log':
+    log(rest);
+    break;
+  case 'verify':
+    verify();
+    break;
+  case 'show':
+    show();
+    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,33 @@
 {
   "name": "attesso",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "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"
+  },
+  "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,82 @@
+// 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, amount, payee, decision, code, policyDigest, kid, at }) {
+  return {
+    v: ENTRY_VERSION,
+    seq,
+    at: at ?? new Date().toISOString(),
+    action,
+    amount,
+    payee: payee ?? null,
+    decision,
+    code,
+    policy_digest: policyDigest,
+    kid,
+    prev,
+  };
+}
+
+// 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,83 @@
+// Deterministic local policy. Same code names the hosted engine returns, so a
+// local refusal reads the same as a server one when the log is exported.
+import { canonical } from './canonical.mjs';
+import { createHash } from 'node:crypto';
+
+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');
+}
+
+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 (!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.payees !== undefined) {
+    if (!Array.isArray(policy.payees) || policy.payees.some((payee) => typeof payee !== 'string' || payee === '')) {
+      fail('payees 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 (proposal.action !== policy.action) {
+    return { decision: 'DENY', code: 'ACTION_MISMATCH' };
+  }
+  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 (policy.payees && !policy.payees.includes(proposal.payee)) {
+    return { decision: 'DENY', code: 'VALUE_NOT_ALLOWED' };
+  }
+  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/store.mjs

@@ -0,0 +1,144 @@
+// 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';
+
+export function paths(dir) {
+  return {
+    dir,
+    key: join(dir, 'key.json'),
+    policy: join(dir, 'policy.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',
+    currency: 'EUR',
+    max_amount: 0,
+  });
+  writeJson(file.config, { version: 1, head: { count: 0, hash: 'genesis' } });
+  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),
+    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 verdict = evaluate(policy, proposal, now);
+    const seq = config.head.count + 1;
+    const entry = buildEntry({
+      seq,
+      prev: config.head.hash,
+      action: proposal.action,
+      amount: proposal.amount,
+      payee: proposal.payee,
+      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;
+  });
+}