@nullsquare/agent-authority 0.4.0

package/src/connections.js

@@ -0,0 +1,203 @@
+import { randomUUID } from 'node:crypto';
+
+function key(principalId, service, accountId = 'default') {
+  return `${principalId}\u0000${service}\u0000${accountId}`;
+}
+
+export class AccountConnectionRegistry {
+  constructor() {
+    this.connections = new Map();
+  }
+
+  connect({ principal_id, service, account_id = 'default', auth_kind, credential_ref, scopes = [], metadata = {} }) {
+    if (!principal_id) throw new Error('principal_id is required');
+    if (!service) throw new Error('service is required');
+    if (!auth_kind) throw new Error('auth_kind is required');
+    if (!credential_ref) throw new Error('credential_ref is required');
+
+    const connection = {
+      connection_id: `connection:${randomUUID()}`,
+      principal_id,
+      service,
+      account_id,
+      auth_kind,
+      credential_ref,
+      scopes: [...new Set(scopes)],
+      metadata,
+      status: 'active',
+      connected_at: new Date().toISOString(),
+      updated_at: new Date().toISOString()
+    };
+
+    this.connections.set(key(principal_id, service, account_id), connection);
+    return { ...connection };
+  }
+
+  get({ principal_id, service, account_id = 'default' }) {
+    const connection = this.connections.get(key(principal_id, service, account_id));
+    return connection ? { ...connection } : null;
+  }
+
+  list(principal_id) {
+    return [...this.connections.values()]
+      .filter((connection) => !principal_id || connection.principal_id === principal_id)
+      .map((connection) => ({ ...connection }));
+  }
+
+  disconnect({ principal_id, service, account_id = 'default' }) {
+    const current = this.connections.get(key(principal_id, service, account_id));
+    if (!current) return null;
+    const connection = {
+      ...current,
+      status: 'revoked',
+      updated_at: new Date().toISOString()
+    };
+    this.connections.set(key(principal_id, service, account_id), connection);
+    return { ...connection };
+  }
+}
+
+/**
+ * Development/test secret store only. Production deployments MUST replace this
+ * with an encrypted OS keychain, HSM/KMS-backed vault, or remote secrets service.
+ */
+export class InMemorySecretStore {
+  constructor() {
+    this.secrets = new Map();
+  }
+
+  put(value) {
+    const ref = `secret:${randomUUID()}`;
+    this.secrets.set(ref, value);
+    return ref;
+  }
+
+  get(ref) {
+    if (!this.secrets.has(ref)) throw new Error('credential secret is unavailable');
+    return this.secrets.get(ref);
+  }
+
+  delete(ref) {
+    return this.secrets.delete(ref);
+  }
+}
+
+export class CredentialBroker {
+  constructor({ connections = new AccountConnectionRegistry(), secrets = new InMemorySecretStore() } = {}) {
+    this.connections = connections;
+    this.secrets = secrets;
+  }
+
+  connect({ principal_id, service, account_id = 'default', auth_kind, credential, scopes = [], metadata = {} }) {
+    if (credential === undefined || credential === null) throw new Error('credential is required');
+
+    const previous = this.connections.get({ principal_id, service, account_id });
+    const credential_ref = this.secrets.put(credential);
+    let connection;
+
+    try {
+      connection = this.connections.connect({
+        principal_id,
+        service,
+        account_id,
+        auth_kind,
+        credential_ref,
+        scopes,
+        metadata
+      });
+    } catch (error) {
+      this.secrets.delete(credential_ref);
+      throw error;
+    }
+
+    if (previous?.credential_ref && previous.credential_ref !== credential_ref) {
+      this.secrets.delete(previous.credential_ref);
+    }
+    return connection;
+  }
+
+  getConnection({ principal_id, service, account_id = 'default' }) {
+    return this.connections.get({ principal_id, service, account_id });
+  }
+
+  listConnections(principal_id) {
+    return this.connections.list(principal_id).map(({ credential_ref, ...safe }) => safe);
+  }
+
+  resolveInternal({ principal_id, service, account_id = 'default' }) {
+    const connection = this.connections.get({ principal_id, service, account_id });
+    if (!connection || connection.status !== 'active') {
+      const error = new Error(`no active ${service} connection for this principal`);
+      error.code = 'connection_required';
+      throw error;
+    }
+
+    return {
+      connection,
+      credential: this.secrets.get(connection.credential_ref)
+    };
+  }
+
+  disconnect({ principal_id, service, account_id = 'default' }) {
+    const current = this.connections.get({ principal_id, service, account_id });
+    if (!current) return null;
+    this.secrets.delete(current.credential_ref);
+    const connection = this.connections.disconnect({ principal_id, service, account_id });
+    if (!connection) return null;
+    const { credential_ref, ...safe } = connection;
+    return safe;
+  }
+}
+
+export function brokeredProviderAdapter({ kind, services, broker, execute, prepare }) {
+  if (!kind) throw new Error('adapter kind is required');
+  if (!Array.isArray(services) || services.length === 0) throw new Error('adapter services are required');
+  if (!broker) throw new Error('credential broker is required');
+  if (typeof execute !== 'function') throw new Error('adapter execute function is required');
+
+  const supports = (service) => services.some((pattern) => {
+    if (pattern === '*' || pattern === service) return true;
+    return pattern.endsWith('*') && service.startsWith(pattern.slice(0, -1));
+  });
+
+  return {
+    kind,
+    supports,
+    async prepare({ mission, request }) {
+      const connection = broker.getConnection({
+        principal_id: mission.principal.id,
+        service: request.service,
+        account_id: request.account_id || 'default'
+      });
+
+      if (!connection || connection.status !== 'active') {
+        return {
+          kind,
+          service: request.service,
+          action: request.action,
+          connection_required: true
+        };
+      }
+
+      return prepare
+        ? prepare({ mission, request, connection })
+        : {
+            kind,
+            service: request.service,
+            action: request.action,
+            connection_id: connection.connection_id,
+            account_id: connection.account_id,
+            scopes: connection.scopes
+          };
+    },
+    async execute({ mission, request }) {
+      const { connection, credential } = broker.resolveInternal({
+        principal_id: mission.principal.id,
+        service: request.service,
+        account_id: request.account_id || 'default'
+      });
+
+      return execute({ mission, request, connection, credential });
+    }
+  };
+}

package/src/execution.js

@@ -0,0 +1,174 @@
+import { AuthorityRuntime, createReceipt } from './index.js';
+
+function executionFailure(mission, request, code, reason, extra = {}) {
+  const result = { decision: 'deny', code, reason, ...extra };
+  return { result, receipt: createReceipt({ mission, request, result }), output: null };
+}
+
+export class InMemoryUsageLedger {
+  constructor() { this.spending = new Map(); }
+  key(missionId, currency) { return `${missionId}\u0000${currency || 'UNSPECIFIED'}`; }
+  spent(missionId, currency) { return this.spending.get(this.key(missionId, currency)) || 0; }
+  record(missionId, currency, amount) {
+    const next = this.spent(missionId, currency) + Number(amount);
+    this.spending.set(this.key(missionId, currency), next);
+    return next;
+  }
+}
+
+/**
+ * AuthorityRuntime variant that keeps credentials and authenticated execution
+ * behind the authority boundary. The calling agent receives only sanitized
+ * provider output, never the long-lived credential.
+ */
+export class ExecutingAuthorityRuntime extends AuthorityRuntime {
+  constructor(options = {}) {
+    super(options);
+    this.usage = options.usage || new InMemoryUsageLedger();
+    this.approvals = options.approvals || null;
+    this.executions = options.executions || null;
+  }
+
+  cumulativeBudgetCheck(mission, request) {
+    const budget = mission.constraints?.budget;
+    if (!budget || request?.context?.amount === undefined) return null;
+
+    const currency = request.context.currency || budget.currency;
+    if (currency !== budget.currency) {
+      return executionFailure(mission, request, 'budget_currency_mismatch', 'request currency does not match mission budget');
+    }
+
+    const amount = Number(request.context.amount);
+    if (!Number.isFinite(amount) || amount < 0) {
+      return executionFailure(mission, request, 'invalid_amount', 'request amount must be a non-negative finite number');
+    }
+    const alreadySpent = this.usage.spent(mission.mission_id, budget.currency);
+    const nextTotal = alreadySpent + amount;
+    if (nextTotal > Number(budget.amount)) {
+      return executionFailure(
+        mission,
+        request,
+        'cumulative_budget_exceeded',
+        `mission has spent ${alreadySpent} ${budget.currency}; this action would raise total to ${nextTotal} above cap ${budget.amount}`,
+        { spent: alreadySpent, requested: amount, budget: Number(budget.amount), currency: budget.currency }
+      );
+    }
+    return { amount, currency: budget.currency, alreadySpent, nextTotal };
+  }
+
+  approvalCheck(missionInput, request, evaluation) {
+    if (evaluation.result.decision !== 'require_approval') return evaluation;
+    if (!this.approvals) return { ...evaluation, output: null };
+
+    const approvalId = request?.approval_id;
+    if (!approvalId) {
+      const approval = this.approvals.request({
+        mission: missionInput,
+        request,
+        reason: evaluation.result.reason
+      });
+      return { ...evaluation, approval, output: null };
+    }
+
+    try {
+      const approval = this.approvals.consume(approvalId, { mission: missionInput, request });
+      const result = {
+        decision: 'allow',
+        reason: 'authorized by one-time human approval',
+        approval_id: approval.approval_id
+      };
+      return {
+        result,
+        receipt: createReceipt({ mission: missionInput, request, result }),
+        approval
+      };
+    } catch (error) {
+      return executionFailure(missionInput, request, error.code || 'approval_invalid', error.message);
+    }
+  }
+
+  async readinessCheck(adapter, missionInput, request) {
+    if (typeof adapter.validateRequest === 'function') adapter.validateRequest(request);
+    if (typeof adapter.prepare !== 'function') return null;
+    const dispatch = await adapter.prepare({ mission: missionInput, request });
+    if (dispatch?.connection_required) {
+      return executionFailure(missionInput, request, 'connection_required', `no active ${request.service} connection for this principal`);
+    }
+    return null;
+  }
+
+  beginMutation(adapter, missionInput, request) {
+    if (!adapter.isMutation?.(request)) return null;
+    if (!this.executions) {
+      return executionFailure(missionInput, request, 'idempotency_store_unavailable', 'mutating action cannot run without an execution guard');
+    }
+    try {
+      return this.executions.begin({ mission: missionInput, request });
+    } catch (error) {
+      return executionFailure(
+        missionInput,
+        request,
+        error.code || 'idempotency_error',
+        error.message,
+        error.execution_record ? { execution: error.execution_record } : {}
+      );
+    }
+  }
+
+  async execute(missionInput, request) {
+    let evaluation = this.evaluate(missionInput, request);
+    if (evaluation.result.decision === 'deny') return { ...evaluation, output: null };
+
+    const adapter = this.adapters.resolve(request.service);
+    if (!adapter) {
+      return executionFailure(missionInput, request, 'adapter_unavailable', `no adapter is registered for ${request.service}`);
+    }
+    if (typeof adapter.execute !== 'function') {
+      return executionFailure(missionInput, request, 'execution_unavailable', `${adapter.kind || 'selected'} adapter cannot execute actions yet`);
+    }
+
+    const budgetCheck = this.cumulativeBudgetCheck(missionInput, request);
+    if (budgetCheck?.result?.decision === 'deny') return budgetCheck;
+
+    try {
+      const readinessFailure = await this.readinessCheck(adapter, missionInput, request);
+      if (readinessFailure) return readinessFailure;
+    } catch (error) {
+      if (error?.code === 'connection_required') {
+        return executionFailure(missionInput, request, 'connection_required', error.message);
+      }
+      return executionFailure(missionInput, request, error.code || 'invalid_provider_request', error.message);
+    }
+
+    evaluation = this.approvalCheck(missionInput, request, evaluation);
+    if (evaluation.result.decision !== 'allow') return { ...evaluation, output: null };
+
+    const executionRecord = this.beginMutation(adapter, missionInput, request);
+    if (executionRecord?.result?.decision === 'deny') return executionRecord;
+
+    try {
+      const output = await adapter.execute({ mission: missionInput, request });
+      let usage = null;
+      if (budgetCheck && !budgetCheck.result) {
+        const spent = this.usage.record(missionInput.mission_id, budgetCheck.currency, budgetCheck.amount);
+        usage = {
+          currency: budgetCheck.currency,
+          spent,
+          remaining: Math.max(0, Number(missionInput.constraints.budget.amount) - spent)
+        };
+      }
+      if (executionRecord && this.executions) {
+        this.executions.complete({ mission: missionInput, request, receipt_id: evaluation.receipt?.receipt_id || null });
+      }
+      return { ...evaluation, output, usage, execution: executionRecord || null };
+    } catch (error) {
+      if (executionRecord && this.executions) {
+        this.executions.uncertain({ mission: missionInput, request, error_code: error.code || 'provider_error' });
+      }
+      if (error?.code === 'connection_required') {
+        return executionFailure(missionInput, request, 'connection_required', error.message);
+      }
+      throw error;
+    }
+  }
+}

package/src/guard.js

@@ -0,0 +1,79 @@
+export class AuthorityDeniedError extends Error {
+  constructor({ result, receipt }) {
+    super(result?.reason || 'action denied by Agent Authority');
+    this.name = 'AuthorityDeniedError';
+    this.code = result?.code || 'authority_denied';
+    this.result = result;
+    this.receipt = receipt;
+  }
+}
+
+export class AuthorityApprovalRequiredError extends Error {
+  constructor({ result, receipt }) {
+    super(result?.reason || 'human approval required by Agent Authority');
+    this.name = 'AuthorityApprovalRequiredError';
+    this.code = result?.code || 'approval_required';
+    this.result = result;
+    this.receipt = receipt;
+  }
+}
+
+/**
+ * Minimal protocol-neutral enforcement wrapper.
+ *
+ * Put the side effect inside run(). The callback is invoked only after the
+ * authority boundary returns ALLOW. A guard can use either a static mission or
+ * a TaskLease. Task leases add provenance-bound restrictions without changing
+ * the host application's credential ownership.
+ */
+export class AuthorityGuard {
+  constructor({ mission, lease, runtime, onDecision } = {}) {
+    if ((mission && lease) || (!mission && !lease)) {
+      throw new Error('provide exactly one of mission or lease');
+    }
+    if (lease && typeof lease.evaluate !== 'function') throw new Error('lease must implement evaluate(runtime, request)');
+    if (!runtime || typeof runtime.evaluate !== 'function') throw new Error('authority runtime is required');
+    if (onDecision !== undefined && typeof onDecision !== 'function') throw new Error('onDecision must be a function');
+    this.mission = mission || null;
+    this.lease = lease || null;
+    this.runtime = runtime;
+    this.onDecision = onDecision || null;
+  }
+
+  evaluate(request) {
+    const evaluation = this.lease
+      ? this.lease.evaluate(this.runtime, request)
+      : this.runtime.evaluate(this.mission, request);
+    if (this.onDecision) this.onDecision(evaluation, request);
+    return evaluation;
+  }
+
+  async run(request, effect) {
+    if (typeof effect !== 'function') throw new Error('effect callback is required');
+    const evaluation = this.evaluate(request);
+
+    if (evaluation.result.decision === 'deny') {
+      throw new AuthorityDeniedError(evaluation);
+    }
+    if (evaluation.result.decision === 'require_approval') {
+      throw new AuthorityApprovalRequiredError(evaluation);
+    }
+    if (evaluation.result.decision !== 'allow') {
+      throw new AuthorityDeniedError({
+        ...evaluation,
+        result: { ...evaluation.result, code: 'unknown_decision', reason: 'authority returned an unsupported decision' }
+      });
+    }
+
+    const output = await effect();
+    return { output, result: evaluation.result, receipt: evaluation.receipt };
+  }
+}
+
+export function createAuthorityGuard(options) {
+  return new AuthorityGuard(options);
+}
+
+export function createTaskLeaseGuard({ lease, ...options } = {}) {
+  return new AuthorityGuard({ ...options, lease });
+}

package/src/harness-bridge.js

@@ -0,0 +1,131 @@
+import { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
+import { hashObject } from './index.js';
+
+function b64url(input) {
+  return Buffer.from(input).toString('base64url');
+}
+
+function unb64url(input) {
+  return Buffer.from(input, 'base64url');
+}
+
+function sign(key, body) {
+  return createHmac('sha256', key).update(body).digest();
+}
+
+function safeEqual(a, b) {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+export function grantRequestFingerprint(mission, request) {
+  return hashObject({
+    mission_id: mission.mission_id,
+    principal_id: mission.principal.id,
+    agent_id: mission.agent.id,
+    request
+  });
+}
+
+/**
+ * Issue a short-lived execution grant for a harness-managed connector.
+ *
+ * This mode is for environments where the harness already owns the provider
+ * connection (for example ChatGPT connectors, an IDE's GitHub integration, or
+ * an enterprise agent platform). Agent Authority never receives the provider
+ * OAuth token. Instead, trusted connector middleware verifies this grant before
+ * allowing the exact service/action/request to execute.
+ */
+export function issueHarnessActionGrant({ key, mission, request, ttl_seconds = 30, now = Date.now() }) {
+  if (!key) throw new Error('harness grant signing key is required');
+  if (!mission?.mission_id || !mission?.principal?.id || !mission?.agent?.id) throw new Error('valid mission is required');
+  if (!request?.service || !request?.action) throw new Error('request.service and request.action are required');
+  if (!Number.isFinite(Number(ttl_seconds)) || Number(ttl_seconds) <= 0 || Number(ttl_seconds) > 300) {
+    throw new Error('ttl_seconds must be between 1 and 300');
+  }
+
+  const issued = Math.floor(now / 1000);
+  const claims = {
+    v: 1,
+    typ: 'agent-authority-harness-grant',
+    grant_id: `grant:${randomUUID()}`,
+    principal_id: mission.principal.id,
+    agent_id: mission.agent.id,
+    mission_id: mission.mission_id,
+    service: request.service,
+    action: request.action,
+    request_hash: grantRequestFingerprint(mission, request),
+    iat: issued,
+    exp: issued + Number(ttl_seconds)
+  };
+
+  const body = b64url(JSON.stringify(claims));
+  const signature = b64url(sign(key, body));
+  return { token: `${body}.${signature}`, claims };
+}
+
+export function verifyHarnessActionGrant(token, { key, mission, request, now = Date.now() } = {}) {
+  if (!key) throw new Error('harness grant signing key is required');
+  if (!token || typeof token !== 'string') throw new Error('harness action grant is required');
+  const [body, signature, extra] = token.split('.');
+  if (!body || !signature || extra !== undefined) throw new Error('invalid harness action grant format');
+
+  const expected = sign(key, body);
+  const actual = unb64url(signature);
+  if (!safeEqual(expected, actual)) {
+    const error = new Error('invalid harness action grant signature');
+    error.code = 'grant_signature_invalid';
+    throw error;
+  }
+
+  let claims;
+  try { claims = JSON.parse(unb64url(body).toString('utf8')); }
+  catch {
+    const error = new Error('invalid harness action grant payload');
+    error.code = 'grant_payload_invalid';
+    throw error;
+  }
+
+  if (claims.typ !== 'agent-authority-harness-grant' || claims.v !== 1) {
+    const error = new Error('unsupported harness action grant');
+    error.code = 'grant_type_invalid';
+    throw error;
+  }
+  if (Math.floor(now / 1000) >= Number(claims.exp)) {
+    const error = new Error('harness action grant expired');
+    error.code = 'grant_expired';
+    throw error;
+  }
+
+  if (mission) {
+    if (claims.principal_id !== mission.principal?.id) throw Object.assign(new Error('grant principal mismatch'), { code: 'grant_principal_mismatch' });
+    if (claims.agent_id !== mission.agent?.id) throw Object.assign(new Error('grant agent mismatch'), { code: 'grant_agent_mismatch' });
+    if (claims.mission_id !== mission.mission_id) throw Object.assign(new Error('grant mission mismatch'), { code: 'grant_mission_mismatch' });
+  }
+  if (request) {
+    if (claims.service !== request.service || claims.action !== request.action) {
+      throw Object.assign(new Error('grant action mismatch'), { code: 'grant_action_mismatch' });
+    }
+    if (!mission) throw new Error('mission is required when verifying an exact request');
+    const fingerprint = grantRequestFingerprint(mission, request);
+    if (claims.request_hash !== fingerprint) {
+      throw Object.assign(new Error('grant request mismatch'), { code: 'grant_request_mismatch' });
+    }
+  }
+
+  return claims;
+}
+
+/**
+ * Small helper intended for harness/plugin authors. A connector wrapper calls
+ * this immediately before the provider connector. The wrapper, not the model,
+ * must own this verification boundary.
+ */
+export function createHarnessConnectorGate({ key }) {
+  return {
+    verify({ grant, mission, request }) {
+      return verifyHarnessActionGrant(grant, { key, mission, request });
+    }
+  };
+}