@nullsquare/agent-authority 0.4.4 → 0.4.5

package/src/durable-task-lease.js

@@ -0,0 +1,185 @@
+import { TaskLease } from './task-lease.js';
+
+function sessionError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function assertStore(store) {
+  if (!store || typeof store !== 'object') {
+    throw new Error('durable Task Lease store is required');
+  }
+  for (const method of ['save', 'load', 'transact']) {
+    if (typeof store[method] !== 'function') {
+      throw new Error(`durable Task Lease store must implement ${method}()`);
+    }
+  }
+  return store;
+}
+
+function assertLease(lease) {
+  if (!(lease instanceof TaskLease)) throw new Error('TaskLease instance is required');
+  return lease;
+}
+
+/**
+ * A small stateful facade over JsonFileTaskLeaseStore-style transactional
+ * persistence.
+ *
+ * The session never exposes its mutable TaskLease instance. Reads come from the
+ * cached recovered lease, explicit refresh() reloads authenticated state, and
+ * evaluate() refreshes before every security decision so another worker's
+ * completion or narrowing is observed before the next guarded effect.
+ *
+ * Mutations use optimistic compare-and-swap against the session's current lease
+ * hash. A stale session receives task_lease_state_conflict and must refresh and
+ * reconsider the intended authority mutation; semantic mutations are never
+ * silently replayed against a newer authority state.
+ */
+export class DurableTaskLeaseSession {
+  constructor({ store, mission, lease_id, lease, lease_hash } = {}) {
+    this.store = assertStore(store);
+    if (!mission || typeof mission !== 'object') throw new Error('mission is required');
+    if (!lease_id) throw new Error('lease_id is required');
+    assertLease(lease);
+    if (lease.lease_id !== lease_id || lease.mission.mission_id !== mission.mission_id) {
+      throw sessionError('durable_task_lease_identity_mismatch', 'session lease identity does not match mission and lease_id');
+    }
+
+    this._mission = structuredClone(mission);
+    this.lease_id = lease_id;
+    this._lease = lease;
+    this._leaseHash = lease_hash || lease.hash();
+    if (this._leaseHash !== lease.hash()) {
+      throw sessionError('durable_task_lease_hash_mismatch', 'session lease hash does not match recovered Task Lease state');
+    }
+  }
+
+  get mission() {
+    return structuredClone(this._mission);
+  }
+
+  get status() {
+    return this._lease.status;
+  }
+
+  get expires_at() {
+    return this._lease.expires_at;
+  }
+
+  get completed_at() {
+    return this._lease.completed_at;
+  }
+
+  get completion_reason() {
+    return this._lease.completion_reason;
+  }
+
+  hash() {
+    return this._leaseHash;
+  }
+
+  snapshot() {
+    return structuredClone(this._lease.snapshot());
+  }
+
+  fact(factId) {
+    return this._lease.fact(factId);
+  }
+
+  listFacts() {
+    return this._lease.listFacts();
+  }
+
+  refresh() {
+    const lease = this.store.load({
+      mission: this._mission,
+      lease_id: this.lease_id
+    });
+    if (!lease) {
+      throw sessionError(
+        'task_lease_state_missing',
+        `task lease ${this.lease_id} has no durable state`,
+        { lease_id: this.lease_id }
+      );
+    }
+    this._lease = lease;
+    this._leaseHash = lease.hash();
+    return this;
+  }
+
+  evaluate(runtime, request, now = new Date()) {
+    this.refresh();
+    return this._lease.evaluate(runtime, request, now);
+  }
+
+  _commit(mutator) {
+    const result = this.store.transact({
+      mission: this._mission,
+      lease_id: this.lease_id,
+      expected_lease_hash: this._leaseHash,
+      mutate: mutator
+    });
+    this._lease = result.lease;
+    this._leaseHash = result.lease_hash;
+    return result.value;
+  }
+
+  addRoot(options) {
+    return this._commit((lease) => lease.addRoot(options));
+  }
+
+  derive(options) {
+    return this._commit((lease) => lease.derive(options));
+  }
+
+  deriveFromEvidence(options) {
+    return this._commit((lease) => lease.deriveFromEvidence(options));
+  }
+
+  bind(binding) {
+    return this._commit((lease) => lease.bind(binding));
+  }
+
+  complete(reason = 'task completed') {
+    return this._commit((lease) => lease.complete(reason));
+  }
+}
+
+export function createDurableTaskLeaseSession({ store, lease } = {}) {
+  assertStore(store);
+  assertLease(lease);
+  const mission = structuredClone(lease.mission);
+  const saved = store.save(lease);
+  const recovered = store.load({ mission, lease_id: lease.lease_id });
+  if (!recovered) {
+    throw sessionError('task_lease_state_missing', `task lease ${lease.lease_id} was not recoverable after creation`);
+  }
+  return new DurableTaskLeaseSession({
+    store,
+    mission,
+    lease_id: lease.lease_id,
+    lease: recovered,
+    lease_hash: saved.lease_hash
+  });
+}
+
+export function openDurableTaskLeaseSession({ store, mission, lease_id } = {}) {
+  assertStore(store);
+  if (!mission || typeof mission !== 'object') throw new Error('mission is required');
+  if (!lease_id) throw new Error('lease_id is required');
+  const missionSnapshot = structuredClone(mission);
+  const lease = store.load({ mission: missionSnapshot, lease_id });
+  if (!lease) {
+    throw sessionError('task_lease_state_missing', `task lease ${lease_id} has no durable state`, { lease_id });
+  }
+  return new DurableTaskLeaseSession({
+    store,
+    mission: missionSnapshot,
+    lease_id,
+    lease,
+    lease_hash: lease.hash()
+  });
+}

package/src/storage.js

@@ -1,7 +1,24 @@
-import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  randomBytes,
+  randomUUID,
+  timingSafeEqual
+} from 'node:crypto';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { TaskLease } from './task-lease.js';
 
 export function authorityHome(env = process.env) {
   return resolve(env.AGENT_AUTHORITY_HOME || join(homedir(), '.agent-authority'));
@@ -26,6 +43,68 @@ function atomicJson(path, value, mode = 0o600) {
   try { chmodSync(path, mode); } catch {}
 }
 
+function loadOrCreateMasterKey(keyPath) {
+  ensureDir(dirname(keyPath));
+  if (!existsSync(keyPath)) {
+    writeFileSync(keyPath, randomBytes(32), { mode: 0o600 });
+    try { chmodSync(keyPath, 0o600); } catch {}
+  }
+  const key = readFileSync(keyPath);
+  if (key.length !== 32) throw new Error('Agent Authority master key is invalid');
+  return key;
+}
+
+function deriveLocalKey(keyPath, purpose) {
+  return createHmac('sha256', loadOrCreateMasterKey(keyPath))
+    .update(`agent-authority/${purpose}/v1`)
+    .digest();
+}
+
+function safeLeaseFileName(leaseId) {
+  if (typeof leaseId !== 'string' || leaseId.trim() === '') throw new Error('lease_id is required');
+  return `${Buffer.from(leaseId, 'utf8').toString('base64url')}.json`;
+}
+
+function taskLeaseEnvelopePayload(envelope) {
+  return JSON.stringify({
+    version: envelope.version,
+    lease_id: envelope.lease_id,
+    mission_id: envelope.mission_id,
+    lease_hash: envelope.lease_hash,
+    snapshot: envelope.snapshot
+  });
+}
+
+function taskLeaseMac(key, envelope) {
+  return createHmac('sha256', key).update(taskLeaseEnvelopePayload(envelope)).digest('hex');
+}
+
+function authenticationError(message) {
+  const error = new Error(message);
+  error.code = 'task_lease_state_authentication_failed';
+  return error;
+}
+
+function stateConflictError(message, details = {}) {
+  const error = new Error(message);
+  error.code = 'task_lease_state_conflict';
+  Object.assign(error, details);
+  return error;
+}
+
+function stateLockedError(leaseId) {
+  const error = new Error(`task lease ${leaseId} is already being updated by another local worker`);
+  error.code = 'task_lease_state_locked';
+  error.lease_id = leaseId;
+  return error;
+}
+
+function transactionError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
 export function defaultConfig(home = authorityHome()) {
   return {
     version: 1,
@@ -37,6 +116,7 @@ export function defaultConfig(home = authorityHome()) {
       master_key: join(home, 'vault', 'master.key'),
       revocations: join(home, 'state', 'revocations.json'),
       usage: join(home, 'state', 'usage.json'),
+      task_leases: join(home, 'state', 'task-leases'),
       receipts: join(home, 'receipts')
     }
   };
@@ -136,13 +216,7 @@ export class EncryptedFileSecretStore {
   }
 
   key() {
-    if (!existsSync(this.keyPath)) {
-      writeFileSync(this.keyPath, randomBytes(32), { mode: 0o600 });
-      try { chmodSync(this.keyPath, 0o600); } catch {}
-    }
-    const key = readFileSync(this.keyPath);
-    if (key.length !== 32) throw new Error('Agent Authority master key is invalid');
-    return key;
+    return loadOrCreateMasterKey(this.keyPath);
   }
 
   all() { return readJson(this.path, {}); }
@@ -179,6 +253,221 @@ export class EncryptedFileSecretStore {
   }
 }
 
+/**
+ * Local authenticated persistence for Task Lease authority state.
+ *
+ * The entire snapshot is written atomically and authenticated with an HMAC key
+ * derived from the Agent Authority local master key. Loading verifies the MAC,
+ * exact lease/mission identity, snapshot hash and TaskLease lineage validation
+ * before reconstructed authority is returned to the caller.
+ *
+ * Durable mutations should go through transact(). The per-lease lock serializes
+ * local read-modify-write transactions, while expected_lease_hash provides an
+ * optimistic compare-and-swap check for workers operating on recovered views.
+ *
+ * This protects against accidental/caller-controlled state-file modification and
+ * stale local writers on the trusted host. It is not designed to contain a
+ * malicious host or an attacker that can read the local master key.
+ */
+export class JsonFileTaskLeaseStore {
+  constructor({ dir, keyPath }) {
+    if (!dir) throw new Error('task lease store dir is required');
+    if (!keyPath) throw new Error('task lease store keyPath is required');
+    this.dir = dir;
+    this.keyPath = keyPath;
+    ensureDir(dir);
+    ensureDir(dirname(keyPath));
+  }
+
+  key() {
+    return deriveLocalKey(this.keyPath, 'task-lease-state');
+  }
+
+  path(leaseId) {
+    return join(this.dir, safeLeaseFileName(leaseId));
+  }
+
+  lockPath(leaseId) {
+    return `${this.path(leaseId)}.lock`;
+  }
+
+  withLeaseLock(leaseId, fn) {
+    const lockPath = this.lockPath(leaseId);
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+    } catch (error) {
+      if (error?.code === 'EEXIST') throw stateLockedError(leaseId);
+      throw error;
+    }
+
+    try {
+      return fn();
+    } finally {
+      rmSync(lockPath, { recursive: true, force: true });
+    }
+  }
+
+  envelopeFor(lease) {
+    const snapshot = lease.snapshot();
+    const envelope = {
+      version: 1,
+      lease_id: lease.lease_id,
+      mission_id: lease.mission.mission_id,
+      lease_hash: lease.hash(),
+      snapshot
+    };
+    envelope.mac = taskLeaseMac(this.key(), envelope);
+    return envelope;
+  }
+
+  writeLease(lease, path = this.path(lease.lease_id)) {
+    const envelope = this.envelopeFor(lease);
+    atomicJson(path, envelope, 0o600);
+    return {
+      lease_id: envelope.lease_id,
+      mission_id: envelope.mission_id,
+      lease_hash: envelope.lease_hash
+    };
+  }
+
+  save(lease, { expected_lease_hash = null } = {}) {
+    if (!(lease instanceof TaskLease)) throw new Error('TaskLease instance is required');
+    return this.withLeaseLock(lease.lease_id, () => {
+      const path = this.path(lease.lease_id);
+      if (existsSync(path)) {
+        const current = this.load({ mission: lease.mission, lease_id: lease.lease_id });
+        const currentHash = current.hash();
+        const nextHash = lease.hash();
+
+        if (expected_lease_hash !== null && currentHash !== expected_lease_hash) {
+          throw stateConflictError('task lease state changed since the caller recovered it', {
+            lease_id: lease.lease_id,
+            expected_lease_hash,
+            current_lease_hash: currentHash
+          });
+        }
+        if (expected_lease_hash === null && currentHash !== nextHash) {
+          throw stateConflictError(
+            'changed durable Task Lease state requires expected_lease_hash or transact()',
+            { lease_id: lease.lease_id, current_lease_hash: currentHash, attempted_lease_hash: nextHash }
+          );
+        }
+        if (currentHash === nextHash) {
+          return {
+            lease_id: lease.lease_id,
+            mission_id: lease.mission.mission_id,
+            lease_hash: currentHash
+          };
+        }
+      } else if (expected_lease_hash !== null) {
+        throw stateConflictError('task lease state does not exist for the supplied expected hash', {
+          lease_id: lease.lease_id,
+          expected_lease_hash,
+          current_lease_hash: null
+        });
+      }
+
+      const validated = TaskLease.restore({ mission: lease.mission, snapshot: lease.snapshot() });
+      return this.writeLease(validated, path);
+    });
+  }
+
+  load({ mission, lease_id } = {}) {
+    if (!mission) throw new Error('mission is required');
+    if (!lease_id) throw new Error('lease_id is required');
+    const path = this.path(lease_id);
+    if (!existsSync(path)) return null;
+
+    const envelope = readJson(path, null);
+    if (!envelope || envelope.version !== 1) {
+      throw authenticationError('task lease state envelope is invalid or unsupported');
+    }
+    if (envelope.lease_id !== lease_id || envelope.mission_id !== mission.mission_id) {
+      throw authenticationError('task lease state identity does not match the requested lease and mission');
+    }
+    if (typeof envelope.mac !== 'string' || !/^[a-f0-9]{64}$/.test(envelope.mac)) {
+      throw authenticationError('task lease state authentication tag is invalid');
+    }
+
+    const expected = Buffer.from(taskLeaseMac(this.key(), envelope), 'hex');
+    const actual = Buffer.from(envelope.mac, 'hex');
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+      throw authenticationError('task lease state authentication failed');
+    }
+
+    let lease;
+    try {
+      // Recover against an isolated mission snapshot so a transaction callback
+      // cannot mutate the caller's authority ceiling through shared references.
+      lease = TaskLease.restore({ mission: structuredClone(mission), snapshot: envelope.snapshot });
+    } catch (error) {
+      if (!error.code) error.code = 'task_lease_snapshot_invalid';
+      throw error;
+    }
+    if (lease.lease_id !== lease_id || lease.hash() !== envelope.lease_hash) {
+      throw authenticationError('task lease state hash does not match recovered authority');
+    }
+    return lease;
+  }
+
+  /**
+   * Apply one synchronous durable mutation to the authenticated current lease.
+   *
+   * The mutation runs against a freshly recovered lease while holding an
+   * exclusive local per-lease lock. If expected_lease_hash is supplied, a stale
+   * worker fails before its mutation is applied. The resulting snapshot is fully
+   * validated and atomically replaced before the updated lease is returned.
+   */
+  transact({ mission, lease_id, expected_lease_hash = null, mutate } = {}) {
+    if (!mission) throw new Error('mission is required');
+    if (!lease_id) throw new Error('lease_id is required');
+    if (typeof mutate !== 'function') throw new Error('transaction mutate function is required');
+
+    return this.withLeaseLock(lease_id, () => {
+      const current = this.load({ mission, lease_id });
+      if (!current) {
+        throw transactionError('task_lease_state_missing', `task lease ${lease_id} has no durable state`);
+      }
+
+      const previousHash = current.hash();
+      if (expected_lease_hash !== null && previousHash !== expected_lease_hash) {
+        throw stateConflictError('task lease state changed since the caller recovered it', {
+          lease_id,
+          expected_lease_hash,
+          current_lease_hash: previousHash
+        });
+      }
+
+      const value = mutate(current);
+      if (value && typeof value.then === 'function') {
+        throw transactionError(
+          'task_lease_transaction_async_unsupported',
+          'durable Task Lease transactions must be synchronous and side-effect free outside lease state'
+        );
+      }
+      if (current.lease_id !== lease_id || current.mission.mission_id !== mission.mission_id) {
+        throw transactionError('task_lease_transaction_identity_changed', 'transaction changed Task Lease identity');
+      }
+
+      const validated = TaskLease.restore({ mission, snapshot: current.snapshot() });
+      const saved = this.writeLease(validated, this.path(lease_id));
+      return {
+        lease: validated,
+        value,
+        previous_lease_hash: previousHash,
+        lease_hash: saved.lease_hash
+      };
+    });
+  }
+
+  delete(leaseId) {
+    const path = this.path(leaseId);
+    if (!existsSync(path)) return false;
+    unlinkSync(path);
+    return true;
+  }
+}
+
 export class JsonFileRevocationStore {
   constructor(path) { this.path = path; ensureDir(dirname(path)); }
   all() { return readJson(this.path, {}); }