@nullsquare/agent-authority 0.4.0

package/src/idempotency.js

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { hashObject } from './index.js';
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  try { chmodSync(path, 0o700); } catch {}
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function atomicJson(path, value) {
+  ensureDir(dirname(path));
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  try { chmodSync(tmp, 0o600); } catch {}
+  renameSync(tmp, path);
+  try { chmodSync(path, 0o600); } catch {}
+}
+
+function guardError(code, message, record = null) {
+  const error = new Error(message);
+  error.code = code;
+  error.execution_record = record;
+  return error;
+}
+
+function fingerprintRequest(request = {}) {
+  const { approval_id, ...rest } = request;
+  return rest;
+}
+
+export function executionFingerprint(mission, request) {
+  return hashObject({ mission_hash: hashObject(mission), request: fingerprintRequest(request) });
+}
+
+export class JsonFileExecutionGuard {
+  constructor(path) {
+    this.path = path;
+    ensureDir(dirname(path));
+  }
+
+  all() { return readJson(this.path); }
+  write(value) { atomicJson(this.path, value); }
+  key(missionId, idempotencyKey) { return `${missionId}\u0000${idempotencyKey}`; }
+
+  begin({ mission, request, now = Date.now() }) {
+    const idempotencyKey = request?.idempotency_key;
+    if (!idempotencyKey) throw guardError('idempotency_key_required', 'mutating actions require request.idempotency_key');
+    if (String(idempotencyKey).length > 200) throw guardError('invalid_idempotency_key', 'idempotency key is too long');
+
+    const all = this.all();
+    const key = this.key(mission.mission_id, idempotencyKey);
+    const fingerprint = executionFingerprint(mission, request);
+    const existing = all[key];
+    if (existing) {
+      if (existing.fingerprint !== fingerprint) {
+        throw guardError('idempotency_conflict', 'idempotency key was already used for a different request', existing);
+      }
+      throw guardError(
+        existing.status === 'succeeded' ? 'duplicate_execution' : 'execution_already_started',
+        `idempotent execution is already ${existing.status}`,
+        existing
+      );
+    }
+
+    const record = {
+      execution_id: `execution:${randomUUID()}`,
+      mission_id: mission.mission_id,
+      agent_id: mission.agent.id,
+      idempotency_key: String(idempotencyKey),
+      fingerprint,
+      service: request.service,
+      action: request.action,
+      status: 'in_progress',
+      started_at: new Date(Number(now)).toISOString(),
+      completed_at: null,
+      receipt_id: null,
+      error_code: null
+    };
+    all[key] = record;
+    this.write(all);
+    return { ...record };
+  }
+
+  complete({ mission, request, receipt_id = null, now = Date.now() }) {
+    return this.finish({ mission, request, status: 'succeeded', receipt_id, now });
+  }
+
+  uncertain({ mission, request, error_code = 'execution_uncertain', now = Date.now() }) {
+    return this.finish({ mission, request, status: 'uncertain', error_code, now });
+  }
+
+  finish({ mission, request, status, receipt_id = null, error_code = null, now = Date.now() }) {
+    const all = this.all();
+    const key = this.key(mission.mission_id, request.idempotency_key);
+    const record = all[key];
+    if (!record) throw guardError('execution_record_missing', 'execution guard record is missing');
+    record.status = status;
+    record.completed_at = new Date(Number(now)).toISOString();
+    record.receipt_id = receipt_id;
+    record.error_code = error_code;
+    all[key] = record;
+    this.write(all);
+    return { ...record };
+  }
+
+  list({ mission_id, status } = {}) {
+    return Object.values(this.all())
+      .filter((record) => !mission_id || record.mission_id === mission_id)
+      .filter((record) => !status || record.status === status)
+      .map((record) => ({ ...record }));
+  }
+}

package/src/index.js

@@ -0,0 +1,291 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  }
+  return value;
+}
+
+export function hashObject(value) {
+  return createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+}
+
+export function matchPattern(pattern, value) {
+  if (typeof pattern !== 'string' || typeof value !== 'string') return false;
+  if (pattern === '*' || pattern === value) return true;
+  if (pattern.endsWith('*')) return value.startsWith(pattern.slice(0, -1));
+  return false;
+}
+
+function anyMatch(patterns, value) {
+  return patterns.some((pattern) => matchPattern(pattern, value));
+}
+
+function asPatterns(value) {
+  if (Array.isArray(value)) return value;
+  return value === undefined || value === null ? [] : [String(value)];
+}
+
+function contextConstraintFailure(constraints = {}, context = {}) {
+  for (const [field, allowed] of Object.entries(constraints)) {
+    if (context[field] === undefined || context[field] === null) {
+      return { code: 'resource_context_missing', reason: `request context.${field} is required by mission policy` };
+    }
+    const value = String(context[field]);
+    if (!anyMatch(asPatterns(allowed), value)) {
+      return { code: 'resource_constraint_mismatch', reason: `request context.${field} is outside mission authority` };
+    }
+  }
+  return null;
+}
+
+function patternCovers(parentPattern, childPattern) {
+  if (parentPattern === '*') return true;
+  if (parentPattern === childPattern) return true;
+  if (typeof parentPattern === 'string' && parentPattern.endsWith('*')) {
+    return String(childPattern).startsWith(parentPattern.slice(0, -1));
+  }
+  return false;
+}
+
+function constraintsAreAttenuated(parentConstraints = {}, childConstraints = {}) {
+  for (const [field, parentAllowedRaw] of Object.entries(parentConstraints)) {
+    const childAllowedRaw = childConstraints[field];
+    if (childAllowedRaw === undefined) return false;
+    const parentAllowed = asPatterns(parentAllowedRaw);
+    const childAllowed = asPatterns(childAllowedRaw);
+    if (childAllowed.length === 0) return false;
+    for (const childPattern of childAllowed) {
+      if (!parentAllowed.some((parentPattern) => patternCovers(parentPattern, childPattern))) return false;
+    }
+  }
+  return true;
+}
+
+export function validateMission(mission) {
+  const errors = [];
+  if (!mission || typeof mission !== 'object') return { ok: false, errors: ['mission must be an object'] };
+  if (!mission.version) errors.push('version is required');
+  if (!mission.mission_id) errors.push('mission_id is required');
+  if (!mission.principal?.id) errors.push('principal.id is required');
+  if (!mission.agent?.id) errors.push('agent.id is required');
+  if (!mission.objective) errors.push('objective is required');
+  if (!Array.isArray(mission.resources) || mission.resources.length === 0) {
+    errors.push('resources must contain at least one service');
+  } else {
+    mission.resources.forEach((resource, index) => {
+      if (!resource?.service) errors.push(`resources[${index}].service is required`);
+      if (!Array.isArray(resource?.allow)) errors.push(`resources[${index}].allow must be an array`);
+      if (resource?.deny !== undefined && !Array.isArray(resource.deny)) errors.push(`resources[${index}].deny must be an array`);
+      if (resource?.constraints !== undefined && (typeof resource.constraints !== 'object' || Array.isArray(resource.constraints))) {
+        errors.push(`resources[${index}].constraints must be an object`);
+      }
+    });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function assertMission(mission) {
+  const result = validateMission(mission);
+  if (!result.ok) throw new Error(`Invalid mission: ${result.errors.join('; ')}`);
+  return mission;
+}
+
+function deny(code, reason) {
+  return { decision: 'deny', code, reason };
+}
+
+export function evaluateMissionPolicy(missionInput, request, now = new Date()) {
+  const mission = assertMission(missionInput);
+  const { service, action, context = {} } = request || {};
+  if (!service || !action) return deny('invalid_request', 'service and action are required');
+
+  const expiresAt = mission.constraints?.expires_at;
+  if (expiresAt) {
+    const parsedExpiry = new Date(expiresAt);
+    if (Number.isNaN(parsedExpiry.getTime())) return deny('invalid_mission_expiry', 'mission expiry is not a valid date');
+    if (now >= parsedExpiry) return deny('mission_expired', `mission expired at ${expiresAt}`);
+  }
+
+  const depth = request.delegation_depth ?? mission.delegation?.depth ?? 0;
+  const maxDepth = mission.constraints?.max_delegation_depth;
+  if (maxDepth !== undefined && depth > maxDepth) return deny('delegation_depth_exceeded', `delegation depth ${depth} exceeds ${maxDepth}`);
+
+  const budget = mission.constraints?.budget;
+  if (budget && context.amount !== undefined) {
+    const amount = Number(context.amount);
+    if (!Number.isFinite(amount) || amount < 0) return deny('invalid_amount', 'request amount must be a non-negative number');
+    if (context.currency && context.currency !== budget.currency) return deny('budget_currency_mismatch', 'request currency does not match mission budget');
+    if (amount > Number(budget.amount)) return deny('budget_exceeded', `requested amount ${context.amount} exceeds mission cap ${budget.amount}`);
+  }
+
+  const candidates = mission.resources.filter((item) => matchPattern(item.service, service));
+  if (candidates.length === 0) return deny('service_not_authorized', `${service} is outside this mission`);
+
+  const explicitDeny = candidates.find((resource) => anyMatch(resource.deny || [], action));
+  if (explicitDeny) return deny('explicit_deny', `${service}:${action} is explicitly denied`);
+
+  const actionCandidates = candidates.filter((resource) => anyMatch(resource.allow || [], action));
+  if (actionCandidates.length === 0) return deny('action_not_authorized', `${service}:${action} is not allowed by this mission`);
+
+  let matchedResource = null;
+  let lastConstraintFailure = null;
+  for (const resource of actionCandidates) {
+    const failure = contextConstraintFailure(resource.constraints || {}, context);
+    if (!failure) {
+      matchedResource = resource;
+      break;
+    }
+    lastConstraintFailure = failure;
+  }
+
+  if (!matchedResource) {
+    return deny(
+      lastConstraintFailure?.code || 'resource_constraint_mismatch',
+      lastConstraintFailure?.reason || 'request resource is outside mission authority'
+    );
+  }
+
+  const approval = (mission.approvals || []).find((rule) => {
+    const m = rule.match || {};
+    if (m.service && !matchPattern(m.service, service)) return false;
+    if (m.action && !matchPattern(m.action, action)) return false;
+    if (m.amount_gt !== undefined && !(Number(context.amount) > Number(m.amount_gt))) return false;
+    if (m.context && contextConstraintFailure(m.context, context)) return false;
+    return rule.required;
+  });
+
+  if (approval) {
+    return {
+      decision: 'require_approval',
+      reason: approval.reason || 'human approval required by mission policy',
+      rule: approval,
+      matched_resource: matchedResource.service
+    };
+  }
+
+  return {
+    decision: 'allow',
+    reason: 'authorized by mission policy',
+    matched_resource: matchedResource.service
+  };
+}
+
+export function createReceipt({ mission, request, result, parent_receipt_id = null }) {
+  const receipt = {
+    receipt_id: `receipt:${randomUUID()}`,
+    version: '0.1',
+    timestamp: new Date().toISOString(),
+    mission_id: mission.mission_id,
+    principal_id: mission.principal.id,
+    agent_id: mission.agent.id,
+    service: request.service,
+    action: request.action,
+    decision: result.decision,
+    reason: result.reason,
+    request_hash: hashObject(request),
+    mission_hash: hashObject(mission),
+    parent_receipt_id
+  };
+  return { ...receipt, receipt_hash: hashObject(receipt) };
+}
+
+export class InMemoryRevocationStore {
+  constructor() { this.revoked = new Map(); }
+  revoke(missionId, reason = 'revoked by principal') {
+    const record = { reason, revoked_at: new Date().toISOString() };
+    this.revoked.set(missionId, record);
+    return record;
+  }
+  get(missionId) { return this.revoked.get(missionId) || null; }
+}
+
+export class AdapterRegistry {
+  constructor() { this.adapters = []; }
+  register(adapter) { this.adapters.push(adapter); return this; }
+  resolve(service) { return this.adapters.find((adapter) => adapter.supports(service)); }
+}
+
+export function descriptorAdapter(kind, services) {
+  return {
+    kind,
+    supports(service) { return services.some((pattern) => matchPattern(pattern, service)); },
+    async prepare({ mission, request }) {
+      return {
+        kind,
+        service: request.service,
+        action: request.action,
+        mission_id: mission.mission_id,
+        note: `${kind} adapter descriptor only; production credential exchange is not implemented yet`
+      };
+    }
+  };
+}
+
+export class AuthorityRuntime {
+  constructor({ adapters = new AdapterRegistry(), revocations = new InMemoryRevocationStore() } = {}) {
+    this.adapters = adapters;
+    this.revocations = revocations;
+  }
+
+  revoke(missionId, reason) { return this.revocations.revoke(missionId, reason); }
+
+  evaluate(missionInput, request, now = new Date()) {
+    const mission = assertMission(missionInput);
+    const revoked = this.revocations.get(mission.mission_id);
+    const result = revoked ? deny('mission_revoked', revoked.reason) : evaluateMissionPolicy(mission, request, now);
+    return { result, receipt: createReceipt({ mission, request, result }) };
+  }
+
+  async prepare(missionInput, request, now = new Date()) {
+    const evaluation = this.evaluate(missionInput, request, now);
+    if (evaluation.result.decision !== 'allow') return evaluation;
+    const adapter = this.adapters.resolve(request.service);
+    if (!adapter) return { ...evaluation, dispatch: null };
+    return { ...evaluation, dispatch: await adapter.prepare({ mission: missionInput, request }) };
+  }
+}
+
+export function deriveMission(parentInput, childSpec) {
+  const parent = assertMission(parentInput);
+  const parentDepth = parent.delegation?.depth ?? 0;
+  const maxDepth = parent.constraints?.max_delegation_depth ?? 0;
+  if (parentDepth >= maxDepth) throw new Error('parent mission cannot delegate further');
+  if (!childSpec?.agent?.id) throw new Error('childSpec.agent.id is required');
+  if (!Array.isArray(childSpec.resources) || childSpec.resources.length === 0) throw new Error('childSpec.resources are required');
+
+  for (const childResource of childSpec.resources) {
+    const parentResources = parent.resources.filter((r) => matchPattern(r.service, childResource.service));
+    if (parentResources.length === 0) throw new Error(`child service ${childResource.service} is not authorized by parent`);
+
+    const compatibleParent = parentResources.find((parentResource) => {
+      for (const childAllow of childResource.allow || []) {
+        if ((parentResource.deny || []).some((d) => matchPattern(d, childAllow))) return false;
+        if (!(parentResource.allow || []).some((a) => matchPattern(a, childAllow))) return false;
+      }
+      return constraintsAreAttenuated(parentResource.constraints || {}, childResource.constraints || {});
+    });
+
+    if (!compatibleParent) throw new Error(`child authority for ${childResource.service} expands parent authority`);
+  }
+
+  return assertMission({
+    version: parent.version,
+    mission_id: childSpec.mission_id || `mission:${randomUUID()}`,
+    principal: parent.principal,
+    agent: childSpec.agent,
+    objective: childSpec.objective || `Delegated task under ${parent.mission_id}`,
+    resources: childSpec.resources,
+    constraints: {
+      ...childSpec.constraints,
+      max_delegation_depth: Math.min(
+        childSpec.constraints?.max_delegation_depth ?? 0,
+        Math.max(0, maxDepth - parentDepth - 1)
+      )
+    },
+    approvals: childSpec.approvals || parent.approvals || [],
+    delegation: { parent_mission_id: parent.mission_id, depth: parentDepth + 1 }
+  });
+}

package/src/integrations/ai-sdk.js

@@ -0,0 +1,59 @@
+export class UnmappedAiSdkToolError extends Error {
+  constructor(toolName) {
+    super(`AI SDK tool ${toolName} has execute() but no Agent Authority request mapping`);
+    this.name = 'UnmappedAiSdkToolError';
+    this.code = 'ai_sdk_tool_unmapped';
+    this.tool_name = toolName;
+  }
+}
+
+function assertGuard(guard) {
+  if (!guard || typeof guard.run !== 'function') {
+    throw new Error('Agent Authority guard with run(request, effect) is required');
+  }
+}
+
+function assertRequest(toolName, request) {
+  if (!request || typeof request !== 'object') {
+    throw new Error(`request mapper for AI SDK tool ${toolName} must return an authority request`);
+  }
+  if (!request.service || !request.action) {
+    throw new Error(`authority request for AI SDK tool ${toolName} requires service and action`);
+  }
+  return request;
+}
+
+/**
+ * Wrap Vercel AI SDK Tool objects without changing their schemas, descriptions,
+ * approval metadata, or the surrounding ToolLoopAgent architecture.
+ *
+ * Every executable tool must have a request mapper. Missing mappings fail
+ * closed at execution time rather than silently bypassing Agent Authority.
+ */
+export function protectAiSdkTools({ tools, guard, requests = {} } = {}) {
+  assertGuard(guard);
+  if (!tools || typeof tools !== 'object' || Array.isArray(tools)) {
+    throw new Error('AI SDK tools object is required');
+  }
+  if (!requests || typeof requests !== 'object' || Array.isArray(requests)) {
+    throw new Error('AI SDK request mappings must be an object');
+  }
+
+  return Object.fromEntries(Object.entries(tools).map(([toolName, tool]) => {
+    if (!tool || typeof tool !== 'object') return [toolName, tool];
+    if (typeof tool.execute !== 'function') return [toolName, tool];
+
+    const originalExecute = tool.execute;
+    const mapper = requests[toolName];
+
+    return [toolName, {
+      ...tool,
+      execute: async (input, options) => {
+        if (typeof mapper !== 'function') throw new UnmappedAiSdkToolError(toolName);
+        const request = assertRequest(toolName, await mapper(input, options));
+        const { output } = await guard.run(request, () => originalExecute.call(tool, input, options));
+        return output;
+      }
+    }];
+  }));
+}

package/src/keys.js

@@ -0,0 +1,15 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export function readOrCreateSecretKey(path, bytes = 32) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  try { chmodSync(dirname(path), 0o700); } catch {}
+  if (!existsSync(path)) {
+    writeFileSync(path, randomBytes(bytes), { mode: 0o600 });
+    try { chmodSync(path, 0o600); } catch {}
+  }
+  const key = readFileSync(path);
+  if (key.length !== bytes) throw new Error(`secret key at ${path} must contain exactly ${bytes} bytes`);
+  return key;
+}

package/src/mcp-gateway.js

@@ -0,0 +1,142 @@
+import { matchPattern } from './index.js';
+
+function anyMatch(patterns = [], value) {
+  return patterns.some((pattern) => matchPattern(pattern, value));
+}
+
+export function mcpToolAction(toolName) {
+  if (!toolName) throw new Error('tool name is required');
+  return `tool.${toolName}`;
+}
+
+export function contextFromToolArguments(toolName, args = {}) {
+  const context = { tool_name: toolName };
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return context;
+
+  for (const [key, value] of Object.entries(args)) {
+    if (['string', 'number', 'boolean'].includes(typeof value)) context[key] = value;
+  }
+  return context;
+}
+
+export function toolPotentiallyVisible(mission, service, toolName) {
+  const action = mcpToolAction(toolName);
+  const resources = (mission?.resources || []).filter((resource) => matchPattern(resource.service, service));
+  if (!resources.length) return false;
+  if (resources.some((resource) => anyMatch(resource.deny || [], action))) return false;
+  return resources.some((resource) => anyMatch(resource.allow || [], action));
+}
+
+export function isDeclaredReadOnlyTool(tool) {
+  return tool?.annotations?.readOnlyHint === true;
+}
+
+function deniedToolResult(result, extra = {}) {
+  return {
+    content: [{
+      type: 'text',
+      text: `Agent Authority blocked this tool call: ${result.reason || result.code || 'not authorized'}`
+    }],
+    isError: true,
+    _meta: {
+      'io.nullsquare.agent-authority/decision': result.decision || 'deny',
+      'io.nullsquare.agent-authority/code': result.code || 'not_authorized',
+      ...extra
+    }
+  };
+}
+
+/**
+ * Small, transport-neutral policy gateway for MCP tools.
+ *
+ * The upstream object only needs two methods:
+ *   listTools(params?) -> { tools: [...] }
+ *   callTool(params)   -> MCP CallToolResult
+ *
+ * v0.1 deliberately defaults to read-only enforcement. A tool is considered
+ * read-only only when its MCP annotations explicitly set readOnlyHint=true.
+ * Write support belongs behind the existing approval + idempotency runtime and
+ * is intentionally not inferred from tool names.
+ */
+export class MissionMcpGateway {
+  constructor({
+    mission,
+    runtime,
+    upstream,
+    service = 'mcp:upstream',
+    readOnly = true,
+    contextMapper = contextFromToolArguments
+  } = {}) {
+    if (!mission) throw new Error('mission is required');
+    if (!runtime || typeof runtime.evaluate !== 'function') throw new Error('authority runtime is required');
+    if (!upstream || typeof upstream.listTools !== 'function' || typeof upstream.callTool !== 'function') {
+      throw new Error('upstream MCP client must implement listTools() and callTool()');
+    }
+    this.mission = mission;
+    this.runtime = runtime;
+    this.upstream = upstream;
+    this.service = service;
+    this.readOnly = readOnly;
+    this.contextMapper = contextMapper;
+    this.tools = new Map();
+  }
+
+  async refreshTools(params = undefined) {
+    const listed = await this.upstream.listTools(params);
+    for (const tool of listed.tools || []) this.tools.set(tool.name, tool);
+    return listed;
+  }
+
+  async listTools(params = undefined) {
+    const listed = await this.refreshTools(params);
+    const tools = (listed.tools || []).filter((tool) => {
+      if (!toolPotentiallyVisible(this.mission, this.service, tool.name)) return false;
+      if (this.readOnly && !isDeclaredReadOnlyTool(tool)) return false;
+      return true;
+    });
+    return { ...listed, tools };
+  }
+
+  async toolDefinition(toolName) {
+    if (!this.tools.has(toolName)) await this.refreshTools();
+    return this.tools.get(toolName) || null;
+  }
+
+  async callTool(params = {}) {
+    const toolName = params.name;
+    if (!toolName) return deniedToolResult({ decision: 'deny', code: 'invalid_request', reason: 'tool name is required' });
+
+    const tool = await this.toolDefinition(toolName);
+    if (!tool) return deniedToolResult({ decision: 'deny', code: 'tool_not_found', reason: `upstream tool ${toolName} was not found` });
+    if (this.readOnly && !isDeclaredReadOnlyTool(tool)) {
+      return deniedToolResult({
+        decision: 'deny',
+        code: 'mcp_write_disabled',
+        reason: `${toolName} is not explicitly declared read-only by the upstream MCP server`
+      });
+    }
+
+    const context = this.contextMapper(toolName, params.arguments || {});
+    const request = {
+      service: this.service,
+      action: mcpToolAction(toolName),
+      context
+    };
+    const evaluation = this.runtime.evaluate(this.mission, request);
+    if (evaluation.result.decision !== 'allow') {
+      return deniedToolResult(evaluation.result, {
+        'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null
+      });
+    }
+
+    const output = await this.upstream.callTool(params);
+    return {
+      ...output,
+      _meta: {
+        ...(output?._meta || {}),
+        'io.nullsquare.agent-authority/decision': 'allow',
+        'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null
+      }
+    };
+  }
+}