@nullsquare/agent-authority 0.4.3 → 0.4.5

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, {}); }

package/src/task-lease.js

@@ -24,6 +24,19 @@ function sameValue(a, b) {
   return hashObject(a) === hashObject(b);
 }
 
+function requiredString(value, code, message) {
+  if (typeof value !== 'string' || value.trim() === '') throw authorityError(code, message);
+  return value;
+}
+
+function validDate(value, code, message, { nullable = false } = {}) {
+  if ((value === null || value === undefined) && nullable) return value ?? null;
+  if (typeof value !== 'string' || Number.isNaN(new Date(value).getTime())) {
+    throw authorityError(code, message);
+  }
+  return value;
+}
+
 function validateBinding(binding) {
   if (!binding?.service) throw new Error('binding.service is required');
   if (!binding?.action) throw new Error('binding.action is required');
@@ -37,6 +50,201 @@ function validateBinding(binding) {
   };
 }
 
+function validateSnapshotFact(fact, leaseId) {
+  if (!fact || typeof fact !== 'object' || Array.isArray(fact)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease fact must be an object');
+  }
+  const factId = requiredString(
+    fact.fact_id,
+    'task_lease_snapshot_invalid',
+    'task lease fact_id is required'
+  );
+  if (fact.value === undefined) {
+    throw authorityError('task_lease_snapshot_invalid', `task lease fact ${factId} is missing its value`);
+  }
+  requiredString(
+    fact.created_at,
+    'task_lease_snapshot_invalid',
+    `task lease fact ${factId} is missing created_at`
+  );
+  validDate(
+    fact.created_at,
+    'task_lease_snapshot_invalid',
+    `task lease fact ${factId} created_at is invalid`
+  );
+
+  const provenance = fact.provenance;
+  if (!provenance || typeof provenance !== 'object' || Array.isArray(provenance)) {
+    throw authorityError('task_lease_snapshot_invalid', `task lease fact ${factId} is missing provenance`);
+  }
+
+  if (provenance.type === 'root') {
+    requiredString(
+      provenance.source,
+      'task_lease_snapshot_invalid',
+      `root fact ${factId} is missing its authority source`
+    );
+  } else if (provenance.type === 'derived') {
+    if (!['host-trusted', 'execution-evidence-v1'].includes(provenance.derivation_mode)) {
+      throw authorityError('task_lease_snapshot_invalid', `derived fact ${factId} has an unsupported derivation mode`);
+    }
+    if (!Array.isArray(provenance.from) || provenance.from.length === 0) {
+      throw authorityError('task_lease_snapshot_invalid', `derived fact ${factId} must retain parent lineage`);
+    }
+    for (const parentId of provenance.from) {
+      requiredString(
+        parentId,
+        'task_lease_snapshot_invalid',
+        `derived fact ${factId} contains an invalid parent fact id`
+      );
+    }
+    if (provenance.task_lease_id !== leaseId) {
+      throw authorityError('task_lease_snapshot_invalid', `derived fact ${factId} belongs to another task lease`);
+    }
+    for (const [field, label] of [
+      ['receipt_id', 'receipt id'],
+      ['receipt_hash', 'receipt hash'],
+      ['source_service', 'source service'],
+      ['source_action', 'source action'],
+      ['source_request_hash', 'source request hash'],
+      ['selector', 'selector']
+    ]) {
+      requiredString(
+        provenance[field],
+        'task_lease_snapshot_invalid',
+        `derived fact ${factId} is missing ${label}`
+      );
+    }
+
+    if (provenance.derivation_mode === 'execution-evidence-v1') {
+      for (const [field, label] of [
+        ['extractor_id', 'extractor id'],
+        ['source_output_hash', 'source output hash'],
+        ['execution_evidence_hash', 'execution evidence hash']
+      ]) {
+        requiredString(
+          provenance[field],
+          'task_lease_snapshot_invalid',
+          `evidence-derived fact ${factId} is missing ${label}`
+        );
+      }
+    }
+  } else {
+    throw authorityError('task_lease_snapshot_invalid', `task lease fact ${factId} has unknown provenance type`);
+  }
+
+  return structuredClone({
+    fact_id: factId,
+    kind: fact.kind ?? 'opaque',
+    value: fact.value,
+    provenance,
+    created_at: fact.created_at
+  });
+}
+
+function validateFactGraph(facts) {
+  const byId = new Map();
+  for (const fact of facts) {
+    if (byId.has(fact.fact_id)) {
+      throw authorityError('task_lease_snapshot_invalid', `duplicate authority fact ${fact.fact_id}`);
+    }
+    byId.set(fact.fact_id, fact);
+  }
+
+  for (const fact of facts) {
+    if (fact.provenance.type !== 'derived') continue;
+    for (const parentId of fact.provenance.from) {
+      if (!byId.has(parentId)) {
+        throw authorityError(
+          'task_lease_snapshot_invalid',
+          `derived fact ${fact.fact_id} references missing parent ${parentId}`
+        );
+      }
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(factId) {
+    if (visited.has(factId)) return;
+    if (visiting.has(factId)) {
+      throw authorityError('task_lease_snapshot_invalid', 'task lease fact lineage contains a cycle');
+    }
+    visiting.add(factId);
+    const fact = byId.get(factId);
+    if (fact?.provenance.type === 'derived') {
+      for (const parentId of fact.provenance.from) visit(parentId);
+    }
+    visiting.delete(factId);
+    visited.add(factId);
+  }
+  for (const factId of byId.keys()) visit(factId);
+  return byId;
+}
+
+function validateSnapshot(mission, snapshot) {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease snapshot must be an object');
+  }
+  if (snapshot.version !== '0.1') {
+    throw authorityError('task_lease_snapshot_version_unsupported', `unsupported task lease snapshot version ${snapshot.version}`);
+  }
+
+  const leaseId = requiredString(
+    snapshot.lease_id,
+    'task_lease_snapshot_invalid',
+    'task lease snapshot lease_id is required'
+  );
+  if (snapshot.mission_id !== mission.mission_id) {
+    throw authorityError('task_lease_snapshot_mission_mismatch', 'task lease snapshot belongs to another mission');
+  }
+  if (snapshot.principal_id !== mission.principal.id || snapshot.agent_id !== mission.agent.id) {
+    throw authorityError('task_lease_snapshot_mission_mismatch', 'task lease snapshot principal or agent does not match mission');
+  }
+  if (snapshot.mission_hash !== hashObject(mission)) {
+    throw authorityError(
+      'task_lease_snapshot_mission_mismatch',
+      'task lease snapshot mission hash does not match the exact recovery mission'
+    );
+  }
+
+  if (!['active', 'completed'].includes(snapshot.status)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease snapshot status must be active or completed');
+  }
+  validDate(snapshot.created_at, 'task_lease_snapshot_invalid', 'task lease snapshot created_at is invalid');
+  validDate(snapshot.expires_at, 'task_lease_snapshot_invalid', 'task lease snapshot expires_at is invalid', { nullable: true });
+  validDate(snapshot.completed_at, 'task_lease_snapshot_invalid', 'task lease snapshot completed_at is invalid', { nullable: true });
+
+  if (snapshot.status === 'active' && snapshot.completed_at !== null) {
+    throw authorityError('task_lease_snapshot_invalid', 'active task lease snapshot cannot contain completed_at');
+  }
+  if (snapshot.status === 'completed' && snapshot.completed_at === null) {
+    throw authorityError('task_lease_snapshot_invalid', 'completed task lease snapshot must contain completed_at');
+  }
+  if (snapshot.completion_reason !== null && typeof snapshot.completion_reason !== 'string') {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease completion_reason must be a string or null');
+  }
+  if (!Array.isArray(snapshot.bindings) || !Array.isArray(snapshot.facts)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease snapshot bindings and facts must be arrays');
+  }
+
+  const bindings = snapshot.bindings.map(validateBinding);
+  const facts = snapshot.facts.map((fact) => validateSnapshotFact(fact, leaseId));
+  const byId = validateFactGraph(facts);
+
+  return {
+    lease_id: leaseId,
+    request: structuredClone(snapshot.request),
+    created_at: snapshot.created_at,
+    expires_at: snapshot.expires_at,
+    status: snapshot.status,
+    completed_at: snapshot.completed_at,
+    completion_reason: snapshot.completion_reason,
+    bindings,
+    facts: byId
+  };
+}
+
 function taskReceipt(lease, request, result) {
   const base = createReceipt({ mission: lease.mission, request, result });
   const { receipt_hash: _oldHash, ...unsigned } = base;
@@ -82,6 +290,35 @@ export class TaskLease {
     for (const root of roots) this.addRoot(root);
   }
 
+  /**
+   * Restore an already-authenticated Task Lease snapshot.
+   *
+   * This method validates state shape, exact mission identity and lineage but
+   * does not authenticate where the snapshot came from. Persisted authority
+   * should be loaded through an authenticated store such as
+   * JsonFileTaskLeaseStore rather than from arbitrary caller-controlled JSON.
+   */
+  static restore({ mission, snapshot } = {}) {
+    const resolvedMission = assertMission(mission);
+    const state = validateSnapshot(resolvedMission, snapshot);
+    const lease = new TaskLease({
+      mission: resolvedMission,
+      lease_id: state.lease_id,
+      request: state.request,
+      roots: [],
+      bindings: state.bindings,
+      expires_at: state.expires_at,
+      created_at: state.created_at
+    });
+    lease.status = state.status;
+    lease.completed_at = state.completed_at;
+    lease.completion_reason = state.completion_reason;
+    lease.facts = new Map(
+      [...state.facts.entries()].map(([factId, fact]) => [factId, structuredClone(fact)])
+    );
+    return lease;
+  }
+
   addRoot({ fact_id, kind = 'opaque', value, source = 'human' } = {}) {
     if (!fact_id) throw new Error('root fact_id is required');
     if (value === undefined) throw new Error('root value is required');
@@ -245,9 +482,10 @@ export class TaskLease {
       version: '0.1',
       lease_id: this.lease_id,
       mission_id: this.mission.mission_id,
+      mission_hash: hashObject(this.mission),
       principal_id: this.mission.principal.id,
       agent_id: this.mission.agent.id,
-      request: this.request,
+      request: structuredClone(this.request),
       status: this.status,
       created_at: this.created_at,
       expires_at: this.expires_at,
@@ -341,3 +579,7 @@ export class TaskLease {
 export function createTaskLease(options) {
   return new TaskLease(options);
 }
+
+export function restoreTaskLease(options) {
+  return TaskLease.restore(options);
+}