@nullsquare/agent-authority 0.4.0

package/src/storage.js

@@ -0,0 +1,213 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+export function authorityHome(env = process.env) {
+  return resolve(env.AGENT_AUTHORITY_HOME || join(homedir(), '.agent-authority'));
+}
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  try { chmodSync(path, 0o700); } catch {}
+}
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function atomicJson(path, value, mode = 0o600) {
+  ensureDir(dirname(path));
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });
+  try { chmodSync(tmp, mode); } catch {}
+  renameSync(tmp, path);
+  try { chmodSync(path, mode); } catch {}
+}
+
+export function defaultConfig(home = authorityHome()) {
+  return {
+    version: 1,
+    principal_id: 'user:local',
+    server: { host: '127.0.0.1', port: 8787 },
+    paths: {
+      connections: join(home, 'state', 'connections.json'),
+      secrets: join(home, 'vault', 'secrets.enc.json'),
+      master_key: join(home, 'vault', 'master.key'),
+      revocations: join(home, 'state', 'revocations.json'),
+      usage: join(home, 'state', 'usage.json'),
+      receipts: join(home, 'receipts')
+    }
+  };
+}
+
+export function ensureAuthorityHome({ home = authorityHome(), principal_id } = {}) {
+  ensureDir(home);
+  ensureDir(join(home, 'state'));
+  ensureDir(join(home, 'vault'));
+  ensureDir(join(home, 'missions'));
+  ensureDir(join(home, 'receipts'));
+  const configPath = join(home, 'config.json');
+  if (!existsSync(configPath)) {
+    const config = defaultConfig(home);
+    if (principal_id) config.principal_id = principal_id;
+    atomicJson(configPath, config, 0o600);
+  }
+  return { home, configPath };
+}
+
+export function loadConfig({ home = authorityHome() } = {}) {
+  const { configPath } = ensureAuthorityHome({ home });
+  const stored = readJson(configPath, {});
+  const defaults = defaultConfig(home);
+  return {
+    ...defaults,
+    ...stored,
+    server: { ...defaults.server, ...(stored.server || {}) },
+    paths: { ...defaults.paths, ...(stored.paths || {}) }
+  };
+}
+
+export function saveConfig(config, { home = authorityHome() } = {}) {
+  ensureAuthorityHome({ home });
+  atomicJson(join(home, 'config.json'), config, 0o600);
+  return config;
+}
+
+function connectionKey(principalId, service, accountId = 'default') {
+  return `${principalId}\u0000${service}\u0000${accountId}`;
+}
+
+export class JsonFileConnectionRegistry {
+  constructor(path) { this.path = path; ensureDir(dirname(path)); }
+  all() { return readJson(this.path, {}); }
+  write(value) { atomicJson(this.path, value, 0o600); }
+
+  connect({ principal_id, service, account_id = 'default', auth_kind, credential_ref, scopes = [], metadata = {} }) {
+    if (!principal_id || !service || !auth_kind || !credential_ref) throw new Error('principal_id, service, auth_kind, and credential_ref are required');
+    const all = this.all();
+    const k = connectionKey(principal_id, service, account_id);
+    const previous = all[k];
+    const now = new Date().toISOString();
+    const connection = {
+      connection_id: previous?.connection_id || `connection:${randomUUID()}`,
+      principal_id,
+      service,
+      account_id,
+      auth_kind,
+      credential_ref,
+      scopes: [...new Set(scopes)],
+      metadata,
+      status: 'active',
+      connected_at: previous?.connected_at || now,
+      updated_at: now
+    };
+    all[k] = connection;
+    this.write(all);
+    return { ...connection };
+  }
+
+  get({ principal_id, service, account_id = 'default' }) {
+    const value = this.all()[connectionKey(principal_id, service, account_id)];
+    return value ? { ...value } : null;
+  }
+
+  list(principal_id) {
+    return Object.values(this.all()).filter((c) => !principal_id || c.principal_id === principal_id).map((c) => ({ ...c }));
+  }
+
+  disconnect({ principal_id, service, account_id = 'default' }) {
+    const all = this.all();
+    const k = connectionKey(principal_id, service, account_id);
+    if (!all[k]) return null;
+    all[k] = { ...all[k], status: 'revoked', updated_at: new Date().toISOString() };
+    this.write(all);
+    return { ...all[k] };
+  }
+}
+
+export class EncryptedFileSecretStore {
+  constructor({ path, keyPath }) {
+    this.path = path;
+    this.keyPath = keyPath;
+    ensureDir(dirname(path));
+    ensureDir(dirname(keyPath));
+  }
+
+  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;
+  }
+
+  all() { return readJson(this.path, {}); }
+  write(value) { atomicJson(this.path, value, 0o600); }
+
+  put(value) {
+    const ref = `secret:${randomUUID()}`;
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.key(), iv);
+    const plaintext = Buffer.from(JSON.stringify(value));
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const all = this.all();
+    all[ref] = { v: 1, alg: 'A256GCM', iv: iv.toString('base64'), tag: tag.toString('base64'), ciphertext: ciphertext.toString('base64') };
+    this.write(all);
+    return ref;
+  }
+
+  get(ref) {
+    const record = this.all()[ref];
+    if (!record) throw new Error('credential secret is unavailable');
+    const decipher = createDecipheriv('aes-256-gcm', this.key(), Buffer.from(record.iv, 'base64'));
+    decipher.setAuthTag(Buffer.from(record.tag, 'base64'));
+    const plaintext = Buffer.concat([decipher.update(Buffer.from(record.ciphertext, 'base64')), decipher.final()]);
+    return JSON.parse(plaintext.toString('utf8'));
+  }
+
+  delete(ref) {
+    const all = this.all();
+    if (!all[ref]) return false;
+    delete all[ref];
+    this.write(all);
+    return true;
+  }
+}
+
+export class JsonFileRevocationStore {
+  constructor(path) { this.path = path; ensureDir(dirname(path)); }
+  all() { return readJson(this.path, {}); }
+  revoke(missionId, reason = 'revoked by principal') {
+    const all = this.all();
+    const record = { reason, revoked_at: new Date().toISOString() };
+    all[missionId] = record;
+    atomicJson(this.path, all, 0o600);
+    return record;
+  }
+  get(missionId) { return this.all()[missionId] || null; }
+}
+
+export class JsonFileUsageLedger {
+  constructor(path) { this.path = path; ensureDir(dirname(path)); }
+  all() { return readJson(this.path, {}); }
+  key(missionId, currency) { return `${missionId}\u0000${currency || 'UNSPECIFIED'}`; }
+  spent(missionId, currency) { return Number(this.all()[this.key(missionId, currency)] || 0); }
+  record(missionId, currency, amount) {
+    const all = this.all();
+    const k = this.key(missionId, currency);
+    all[k] = Number(all[k] || 0) + Number(amount);
+    atomicJson(this.path, all, 0o600);
+    return all[k];
+  }
+}
+
+export function writeReceipt(receiptsDir, receipt) {
+  ensureDir(receiptsDir);
+  const safe = String(receipt.receipt_id || randomUUID()).replace(/[^a-zA-Z0-9._-]/g, '_');
+  atomicJson(join(receiptsDir, `${safe}.json`), receipt, 0o600);
+}

package/src/task-lease.js

@@ -0,0 +1,266 @@
+import { randomUUID } from 'node:crypto';
+import { assertMission, createReceipt, hashObject, matchPattern } from './index.js';
+
+function authorityError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function deny(code, reason, extra = {}) {
+  return { decision: 'deny', code, reason, ...extra };
+}
+
+function approval(code, reason, extra = {}) {
+  return { decision: 'require_approval', code, reason, ...extra };
+}
+
+function sameValue(a, b) {
+  return hashObject(a) === hashObject(b);
+}
+
+function validateBinding(binding) {
+  if (!binding?.service) throw new Error('binding.service is required');
+  if (!binding?.action) throw new Error('binding.action is required');
+  if (!binding?.context_field) throw new Error('binding.context_field is required');
+  if (!binding?.fact_id) throw new Error('binding.fact_id is required');
+  return {
+    service: binding.service,
+    action: binding.action,
+    context_field: binding.context_field,
+    fact_id: binding.fact_id
+  };
+}
+
+function taskReceipt(lease, request, result) {
+  const base = createReceipt({ mission: lease.mission, request, result });
+  const { receipt_hash: _oldHash, ...unsigned } = base;
+  const receipt = {
+    ...unsigned,
+    task_lease_id: lease.lease_id,
+    task_lease_hash: lease.hash()
+  };
+  return { ...receipt, receipt_hash: hashObject(receipt) };
+}
+
+/**
+ * A TaskLease adds temporary, provenance-bound resource restrictions on top of
+ * an existing mission. It never grants an action that the mission itself does
+ * not already authorize.
+ *
+ * Roots are values explicitly approved at task entry. Derived facts must be
+ * anchored to an ALLOW receipt produced inside the same lease and to at least
+ * one existing authority fact. This lets authority follow resources discovered
+ * during authorized execution without becoming a standing wildcard permission.
+ */
+export class TaskLease {
+  constructor({
+    mission,
+    lease_id = `lease:${randomUUID()}`,
+    request = null,
+    roots = [],
+    bindings = [],
+    expires_at = null,
+    created_at = new Date().toISOString()
+  } = {}) {
+    this.mission = assertMission(mission);
+    this.lease_id = lease_id;
+    this.request = request;
+    this.created_at = created_at;
+    this.expires_at = expires_at;
+    this.status = 'active';
+    this.completed_at = null;
+    this.completion_reason = null;
+    this.facts = new Map();
+    this.bindings = bindings.map(validateBinding);
+
+    for (const root of roots) this.addRoot(root);
+  }
+
+  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');
+    if (this.facts.has(fact_id)) throw authorityError('fact_exists', `authority fact ${fact_id} already exists`);
+    const fact = {
+      fact_id,
+      kind,
+      value,
+      provenance: {
+        type: 'root',
+        source
+      },
+      created_at: new Date().toISOString()
+    };
+    this.facts.set(fact_id, fact);
+    return structuredClone(fact);
+  }
+
+  derive({ fact_id, kind = 'opaque', value, from = [], receipt, selector } = {}) {
+    if (!fact_id) throw new Error('derived fact_id is required');
+    if (value === undefined) throw new Error('derived value is required');
+    if (this.facts.has(fact_id)) throw authorityError('fact_exists', `authority fact ${fact_id} already exists`);
+    if (!receipt) throw authorityError('receipt_required', 'derived authority requires an authorized source receipt');
+    if (receipt.decision !== 'allow') throw authorityError('receipt_not_authorized', 'derived authority requires an ALLOW receipt');
+    if (receipt.mission_id !== this.mission.mission_id) {
+      throw authorityError('receipt_mission_mismatch', 'source receipt belongs to another mission');
+    }
+    if (receipt.task_lease_id !== this.lease_id) {
+      throw authorityError('receipt_lease_mismatch', 'source receipt belongs to another task lease');
+    }
+    if (typeof selector !== 'string' || selector.trim() === '') {
+      throw authorityError('selector_required', 'derived authority must record the trusted output selector used to obtain the value');
+    }
+
+    const parents = [...new Set(from)];
+    if (parents.length === 0) {
+      throw authorityError('parent_fact_required', 'derived authority must descend from at least one existing task authority fact');
+    }
+    for (const parentId of parents) {
+      if (!this.facts.has(parentId)) throw authorityError('parent_fact_missing', `authority fact ${parentId} does not exist`);
+    }
+
+    const fact = {
+      fact_id,
+      kind,
+      value,
+      provenance: {
+        type: 'derived',
+        from: parents,
+        task_lease_id: this.lease_id,
+        receipt_id: receipt.receipt_id,
+        receipt_hash: receipt.receipt_hash,
+        source_service: receipt.service,
+        source_action: receipt.action,
+        source_request_hash: receipt.request_hash,
+        selector: selector.trim()
+      },
+      created_at: new Date().toISOString()
+    };
+    this.facts.set(fact_id, fact);
+    return structuredClone(fact);
+  }
+
+  bind(binding) {
+    const normalized = validateBinding(binding);
+    this.bindings.push(normalized);
+    return { ...normalized };
+  }
+
+  fact(factId) {
+    const fact = this.facts.get(factId);
+    return fact ? structuredClone(fact) : null;
+  }
+
+  listFacts() {
+    return [...this.facts.values()].map((fact) => structuredClone(fact));
+  }
+
+  complete(reason = 'task completed') {
+    if (this.status === 'completed') return this.snapshot();
+    this.status = 'completed';
+    this.completed_at = new Date().toISOString();
+    this.completion_reason = reason;
+    return this.snapshot();
+  }
+
+  snapshot() {
+    return {
+      version: '0.1',
+      lease_id: this.lease_id,
+      mission_id: this.mission.mission_id,
+      principal_id: this.mission.principal.id,
+      agent_id: this.mission.agent.id,
+      request: this.request,
+      status: this.status,
+      created_at: this.created_at,
+      expires_at: this.expires_at,
+      completed_at: this.completed_at,
+      completion_reason: this.completion_reason,
+      bindings: this.bindings.map((binding) => ({ ...binding })),
+      facts: this.listFacts()
+    };
+  }
+
+  hash() {
+    return hashObject(this.snapshot());
+  }
+
+  matchingBindings(request = {}) {
+    return this.bindings.filter((binding) =>
+      matchPattern(binding.service, request.service) && matchPattern(binding.action, request.action)
+    );
+  }
+
+  evaluate(runtime, request, now = new Date()) {
+    if (!runtime || typeof runtime.evaluate !== 'function') throw new Error('authority runtime is required');
+
+    if (this.status !== 'active') {
+      const result = deny('task_lease_completed', this.completion_reason || 'task lease has completed');
+      return { result, receipt: taskReceipt(this, request, result) };
+    }
+
+    if (this.expires_at) {
+      const expires = new Date(this.expires_at);
+      if (Number.isNaN(expires.getTime())) {
+        const result = deny('invalid_task_lease_expiry', 'task lease expiry is not a valid date');
+        return { result, receipt: taskReceipt(this, request, result) };
+      }
+      if (now >= expires) {
+        const result = deny('task_lease_expired', `task lease expired at ${this.expires_at}`);
+        return { result, receipt: taskReceipt(this, request, result) };
+      }
+    }
+
+    // The mission remains the ceiling. A task lease can only narrow an action
+    // that the mission already permits; it can never override DENY or approval.
+    const base = runtime.evaluate(this.mission, request, now);
+    if (base.result.decision !== 'allow') {
+      return { result: base.result, receipt: taskReceipt(this, request, base.result) };
+    }
+
+    for (const binding of this.matchingBindings(request)) {
+      const fact = this.facts.get(binding.fact_id);
+      if (!fact) {
+        const result = deny(
+          'authority_fact_unresolved',
+          `task has not established authority fact ${binding.fact_id}`,
+          { binding }
+        );
+        return { result, receipt: taskReceipt(this, request, result) };
+      }
+
+      const actual = request?.context?.[binding.context_field];
+      if (actual === undefined || actual === null) {
+        const result = deny(
+          'authority_context_missing',
+          `request context.${binding.context_field} is required by task authority`,
+          { binding }
+        );
+        return { result, receipt: taskReceipt(this, request, result) };
+      }
+
+      if (!sameValue(actual, fact.value)) {
+        const result = approval(
+          'authority_delta_required',
+          `request context.${binding.context_field} is outside the task's derived authority`,
+          {
+            authority_delta: {
+              service: request.service,
+              action: request.action,
+              context_field: binding.context_field,
+              requested_value: actual,
+              current_fact_id: fact.fact_id
+            }
+          }
+        );
+        return { result, receipt: taskReceipt(this, request, result) };
+      }
+    }
+
+    return { result: base.result, receipt: taskReceipt(this, request, base.result) };
+  }
+}
+
+export function createTaskLease(options) {
+  return new TaskLease(options);
+}