@nullsquare/agent-authority 0.4.0

package/src/mcp-remote.js

@@ -0,0 +1,102 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { MissionMcpGateway } from './mcp-gateway.js';
+
+export class RemoteMcpUpstream {
+  constructor({ url, name = 'agent-authority-upstream', fetchImpl } = {}) {
+    if (!url) throw new Error('upstream MCP URL is required');
+    this.url = new URL(url);
+    this.name = name;
+    this.fetchImpl = fetchImpl;
+    this.client = null;
+    this.connecting = null;
+  }
+
+  async ensureClient() {
+    if (this.client) return this.client;
+    if (this.connecting) return this.connecting;
+
+    this.connecting = (async () => {
+      const client = new Client(
+        { name: this.name, version: '0.3.0' },
+        { versionNegotiation: { mode: 'auto' } }
+      );
+      const transport = new StreamableHTTPClientTransport(
+        this.url,
+        this.fetchImpl ? { fetch: this.fetchImpl } : undefined
+      );
+      await client.connect(transport);
+      this.client = client;
+      return client;
+    })();
+
+    try {
+      return await this.connecting;
+    } finally {
+      this.connecting = null;
+    }
+  }
+
+  async listTools(params = undefined) {
+    return (await this.ensureClient()).listTools(params);
+  }
+
+  async callTool(params) {
+    return (await this.ensureClient()).callTool(params);
+  }
+
+  async close() {
+    const client = this.client;
+    this.client = null;
+    if (client) await client.close();
+  }
+}
+
+export function createMcpGatewayHandler({
+  mission,
+  runtime,
+  upstream,
+  upstreamUrl,
+  service = 'mcp:upstream',
+  readOnly = true
+} = {}) {
+  const resolvedUpstream = upstream || new RemoteMcpUpstream({ url: upstreamUrl });
+  const gateway = new MissionMcpGateway({
+    mission,
+    runtime,
+    upstream: resolvedUpstream,
+    service,
+    readOnly
+  });
+
+  const handler = createMcpHandler(() => {
+    const server = new McpServer(
+      {
+        name: 'agent-authority-gateway',
+        version: '0.3.0',
+        description: 'Mission-aware policy gateway for MCP tools'
+      },
+      { capabilities: { tools: {} } }
+    );
+
+    server.server.setRequestHandler('tools/list', async (request) => {
+      return gateway.listTools(request.params);
+    });
+
+    server.server.setRequestHandler('tools/call', async (request) => {
+      return gateway.callTool(request.params);
+    });
+
+    return server;
+  });
+
+  return {
+    handler,
+    gateway,
+    upstream: resolvedUpstream,
+    async close() {
+      await handler.close();
+      if (typeof resolvedUpstream.close === 'function') await resolvedUpstream.close();
+    }
+  };
+}

package/src/mcp-server.js

@@ -0,0 +1,102 @@
+import http from 'node:http';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { createMcpGatewayHandler } from './mcp-remote.js';
+
+function isLoopback(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+
+function hostnameFromHostHeader(value = '') {
+  if (value.startsWith('[')) return value.slice(1, value.indexOf(']'));
+  return value.split(':')[0];
+}
+
+function sendJson(res, status, value) {
+  const body = JSON.stringify(value);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff'
+  });
+  res.end(body);
+}
+
+/**
+ * Start the first safe Agent Authority MCP proxy surface.
+ *
+ * v0.3 intentionally binds loopback only and defaults to read-only MCP tools.
+ * Remote web hosts should reach it through a trusted tunnel. Public binding is
+ * deferred until OAuth protected-resource mode is implemented.
+ */
+export function createMcpProxyServer({
+  mission,
+  runtime,
+  upstream,
+  upstreamUrl,
+  service = 'mcp:upstream',
+  host = '127.0.0.1',
+  port = 8790
+} = {}) {
+  if (!isLoopback(host)) {
+    throw new Error('public MCP binding is not supported yet; bind loopback and use a trusted MCP tunnel');
+  }
+
+  const gateway = createMcpGatewayHandler({
+    mission,
+    runtime,
+    upstream,
+    upstreamUrl,
+    service,
+    readOnly: true
+  });
+  const nodeHandler = toNodeHandler(gateway.handler);
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const requestHost = hostnameFromHostHeader(req.headers.host || '');
+      if (requestHost && !isLoopback(requestHost)) {
+        return sendJson(res, 403, { error: 'host_not_allowed' });
+      }
+
+      const url = new URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`);
+      if (req.method === 'GET' && url.pathname === '/health') {
+        return sendJson(res, 200, {
+          ok: true,
+          service: 'agent-authority-mcp-gateway',
+          mode: 'read-only',
+          upstream: upstreamUrl || 'injected'
+        });
+      }
+      if (url.pathname !== '/mcp') return sendJson(res, 404, { error: 'not_found' });
+      return nodeHandler(req, res);
+    } catch (error) {
+      return sendJson(res, 500, { error: error.message });
+    }
+  });
+
+  return {
+    server,
+    gateway,
+    host,
+    port: Number(port),
+    async close() {
+      await new Promise((resolve, reject) => {
+        if (!server.listening) return resolve();
+        server.close((error) => error ? reject(error) : resolve());
+      });
+      await gateway.close();
+    }
+  };
+}
+
+export async function startMcpProxyServer(options = {}) {
+  const instance = createMcpProxyServer(options);
+  await new Promise((resolve, reject) => {
+    instance.server.once('error', reject);
+    instance.server.listen(instance.port, instance.host, () => {
+      instance.server.off('error', reject);
+      resolve();
+    });
+  });
+  return instance;
+}

package/src/providers/github.js

@@ -0,0 +1,149 @@
+import { brokeredProviderAdapter } from '../connections.js';
+
+const MUTATING_ACTIONS = new Set(['issue.create', 'pull_request.create', 'repo.contents.write']);
+
+function required(value, name) {
+  if (value === undefined || value === null || value === '') throw new Error(`${name} is required`);
+  return value;
+}
+
+function repoParts(context = {}) {
+  const repository = required(context.repository, 'context.repository');
+  const [owner, repo, ...extra] = String(repository).split('/');
+  if (!owner || !repo || extra.length) throw new Error('context.repository must be owner/repo');
+  return { owner, repo };
+}
+
+function encodedPath(path) {
+  return String(path)
+    .split('/')
+    .filter(Boolean)
+    .map(encodeURIComponent)
+    .join('/');
+}
+
+function buildOperation(request) {
+  const context = request.context || {};
+  const { owner, repo } = repoParts(context);
+  const root = `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+
+  switch (request.action) {
+    case 'repo.read':
+      return { method: 'GET', path: root };
+
+    case 'repo.contents.read': {
+      const path = required(context.path, 'context.path');
+      const query = context.ref ? `?ref=${encodeURIComponent(context.ref)}` : '';
+      return { method: 'GET', path: `${root}/contents/${encodedPath(path)}${query}` };
+    }
+
+    case 'issue.create':
+      return {
+        method: 'POST',
+        path: `${root}/issues`,
+        body: {
+          title: required(context.title, 'context.title'),
+          body: context.body || undefined,
+          labels: context.labels || undefined,
+          assignees: context.assignees || undefined
+        }
+      };
+
+    case 'pull_request.create':
+      return {
+        method: 'POST',
+        path: `${root}/pulls`,
+        body: {
+          title: required(context.title, 'context.title'),
+          head: required(context.head, 'context.head'),
+          base: required(context.base, 'context.base'),
+          body: context.body || undefined,
+          draft: Boolean(context.draft)
+        }
+      };
+
+    case 'repo.contents.write': {
+      const path = required(context.path, 'context.path');
+      const content = required(context.content_base64, 'context.content_base64');
+      return {
+        method: 'PUT',
+        path: `${root}/contents/${encodedPath(path)}`,
+        body: {
+          message: required(context.message, 'context.message'),
+          content,
+          sha: context.sha || undefined,
+          branch: context.branch || undefined
+        }
+      };
+    }
+
+    default: {
+      const error = new Error(`GitHub action ${request.action} has no provider operation mapping`);
+      error.code = 'unsupported_action';
+      throw error;
+    }
+  }
+}
+
+function sanitizeBody(body) {
+  if (!body || typeof body !== 'object') return body;
+  const clone = structuredClone(body);
+  for (const key of ['token', 'access_token', 'refresh_token', 'authorization']) {
+    if (key in clone) clone[key] = '[redacted]';
+  }
+  return clone;
+}
+
+export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fetch, baseUrl = 'https://api.github.com' } = {}) {
+  if (!broker) throw new Error('credential broker is required');
+  if (typeof fetchImpl !== 'function') throw new Error('fetch implementation is required');
+
+  const adapter = brokeredProviderAdapter({
+    kind: 'github-rest',
+    services: ['github'],
+    broker,
+    async execute({ request, credential }) {
+      const operation = buildOperation(request);
+      const token = typeof credential === 'string' ? credential : credential?.access_token;
+      if (!token) throw new Error('GitHub credential does not contain an access token');
+
+      const response = await fetchImpl(`${baseUrl}${operation.path}`, {
+        method: operation.method,
+        headers: {
+          accept: 'application/vnd.github+json',
+          authorization: `Bearer ${token}`,
+          'content-type': 'application/json',
+          'x-github-api-version': '2022-11-28',
+          'user-agent': 'nullsquare-agent-authority/0.3'
+        },
+        body: operation.body ? JSON.stringify(operation.body) : undefined
+      });
+
+      const text = await response.text();
+      let body = text;
+      if (text) {
+        try { body = JSON.parse(text); } catch { /* preserve text */ }
+      }
+
+      const output = {
+        provider: 'github',
+        status: response.status,
+        ok: response.ok,
+        body: sanitizeBody(body),
+        request_id: response.headers?.get?.('x-github-request-id') || null
+      };
+
+      if (!response.ok) {
+        const error = new Error(`GitHub API ${response.status}`);
+        error.code = 'provider_error';
+        error.provider_output = output;
+        throw error;
+      }
+
+      return output;
+    }
+  });
+
+  adapter.isMutation = (request) => MUTATING_ACTIONS.has(request?.action);
+  return adapter;
+}

package/src/runtime-env.js

@@ -0,0 +1,53 @@
+import { dirname, join } from 'node:path';
+import { AdapterRegistry, descriptorAdapter } from './index.js';
+import { CredentialBroker } from './connections.js';
+import { ExecutingAuthorityRuntime } from './execution.js';
+import { createGitHubProviderAdapter } from './providers/github.js';
+import { JsonFileApprovalStore } from './approvals.js';
+import { JsonFileExecutionGuard } from './idempotency.js';
+import { readOrCreateSecretKey } from './keys.js';
+import {
+  EncryptedFileSecretStore,
+  JsonFileConnectionRegistry,
+  JsonFileRevocationStore,
+  JsonFileUsageLedger,
+  loadConfig
+} from './storage.js';
+
+export function createRuntimeEnvironment({ home } = {}) {
+  const config = loadConfig({ home });
+  const connections = new JsonFileConnectionRegistry(config.paths.connections);
+  const secrets = new EncryptedFileSecretStore({ path: config.paths.secrets, keyPath: config.paths.master_key });
+  const broker = new CredentialBroker({ connections, secrets });
+  const revocations = new JsonFileRevocationStore(config.paths.revocations);
+  const usage = new JsonFileUsageLedger(config.paths.usage);
+  const stateDir = dirname(config.paths.connections);
+  const vaultDir = dirname(config.paths.master_key);
+  const approvals = new JsonFileApprovalStore(join(stateDir, 'approvals.json'));
+  const executions = new JsonFileExecutionGuard(join(stateDir, 'executions.json'));
+  const agentAuthKeyPath = join(vaultDir, 'agent-auth.key');
+  const agentAuthKey = readOrCreateSecretKey(agentAuthKeyPath);
+
+  const adapters = new AdapterRegistry()
+    .register(createGitHubProviderAdapter({ broker }))
+    .register(descriptorAdapter('oauth', ['google', 'slack', 'microsoft']))
+    .register(descriptorAdapter('mcp', ['mcp:*']))
+    .register(descriptorAdapter('api-key', ['cloudflare', 'apollo']))
+    .register(descriptorAdapter('cli', ['cli:*']));
+
+  const runtime = new ExecutingAuthorityRuntime({ adapters, revocations, usage, approvals, executions });
+  return {
+    config,
+    connections,
+    secrets,
+    broker,
+    revocations,
+    usage,
+    approvals,
+    executions,
+    adapters,
+    runtime,
+    agentAuthKey,
+    agentAuthKeyPath
+  };
+}

package/src/sdk.js

@@ -0,0 +1,75 @@
+export class AgentAuthorityClient {
+  constructor({ baseUrl = 'http://127.0.0.1:8787', token = null, tokenProvider = null, fetchImpl = globalThis.fetch } = {}) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.token = token;
+    this.tokenProvider = tokenProvider;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async currentToken() {
+    if (typeof this.tokenProvider === 'function') return this.tokenProvider();
+    return this.token;
+  }
+
+  async request(path, { method = 'POST', payload, authenticated = true } = {}) {
+    const headers = {};
+    if (payload !== undefined) headers['content-type'] = 'application/json';
+    if (authenticated) {
+      const token = await this.currentToken();
+      if (!token) throw new Error('Agent Authority client requires an agent-instance token');
+      headers.authorization = `Bearer ${token}`;
+    }
+
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: payload === undefined ? undefined : JSON.stringify(payload)
+    });
+
+    const text = await response.text();
+    let body = text;
+    if (text) {
+      try { body = JSON.parse(text); } catch { /* preserve text */ }
+    }
+
+    if (!response.ok) {
+      const error = new Error(`Agent Authority ${response.status}: ${typeof body === 'string' ? body : body?.error || 'request failed'}`);
+      error.status = response.status;
+      error.response = body;
+      throw error;
+    }
+    return body;
+  }
+
+  health() {
+    return this.request('/health', { method: 'GET', authenticated: false });
+  }
+
+  discover() {
+    return this.request('/.well-known/agent-authority', { method: 'GET', authenticated: false });
+  }
+
+  evaluate(mission, request) {
+    return this.request('/v1/evaluate', { payload: { mission, request } });
+  }
+
+  prepare(mission, request) {
+    return this.request('/v1/prepare', { payload: { mission, request } });
+  }
+
+  execute(mission, request) {
+    return this.request('/v1/execute', { payload: { mission, request } });
+  }
+
+  approval(approval_id) {
+    return this.request(`/v1/approvals/${encodeURIComponent(approval_id)}`, { method: 'GET' });
+  }
+
+  revoke(mission_id, reason) {
+    return this.request('/v1/revoke', { payload: { mission_id, reason } });
+  }
+
+  listConnections() {
+    return this.request('/v1/connections', { method: 'GET' });
+  }
+}

package/src/server.js

@@ -0,0 +1,146 @@
+import http from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { createRuntimeEnvironment } from './runtime-env.js';
+import { writeReceipt } from './storage.js';
+import { bearerToken, verifyAgentToken } from './agent-auth.js';
+
+async function readJson(req, maxBytes = 1024 * 1024) {
+  let body = '';
+  for await (const chunk of req) {
+    body += chunk;
+    if (Buffer.byteLength(body) > maxBytes) {
+      const error = new Error('request body too large');
+      error.code = 'payload_too_large';
+      throw error;
+    }
+  }
+  return body ? JSON.parse(body) : {};
+}
+
+function send(res, status, value) {
+  const body = JSON.stringify(value, null, 2);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer'
+  });
+  res.end(body);
+}
+
+function persistReceipt(config, output) {
+  if (output?.receipt) writeReceipt(config.paths.receipts, output.receipt);
+  return output;
+}
+
+function authenticate(req, env, options = {}) {
+  const token = bearerToken(req.headers);
+  return verifyAgentToken(token, {
+    key: env.agentAuthKey,
+    principal_id: env.config.principal_id,
+    ...options
+  });
+}
+
+function authStatus(error) {
+  if (['missing_agent_token', 'invalid_agent_token', 'agent_token_expired'].includes(error?.code)) return 401;
+  if (['principal_mismatch', 'mission_binding_mismatch', 'agent_identity_mismatch', 'agent_capability_denied'].includes(error?.code)) return 403;
+  return null;
+}
+
+export function createAgentAuthorityServer({ home, host, port } = {}) {
+  const env = createRuntimeEnvironment({ home });
+  const bindHost = host ?? process.env.AGENT_AUTHORITY_HOST ?? env.config.server.host ?? '127.0.0.1';
+  const bindPort = Number(port ?? process.env.AGENT_AUTHORITY_PORT ?? env.config.server.port ?? 8787);
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, `http://${req.headers.host || `${bindHost}:${bindPort}`}`);
+
+      if (req.method === 'GET' && url.pathname === '/health') {
+        return send(res, 200, { ok: true, service: 'agent-authority', version: '0.3.0' });
+      }
+
+      if (req.method === 'GET' && url.pathname === '/.well-known/agent-authority') {
+        return send(res, 200, {
+          service: 'agent-authority',
+          version: '0.3.0',
+          api_version: 'v1',
+          authorization: { scheme: 'Bearer', token_type: 'agent-instance', mission_binding: true },
+          endpoints: {
+            evaluate: '/v1/evaluate',
+            prepare: '/v1/prepare',
+            execute: '/v1/execute',
+            approval: '/v1/approvals/{approval_id}'
+          }
+        });
+      }
+
+      if (req.method === 'GET' && url.pathname === '/v1/connections') {
+        authenticate(req, env, { capability: 'connections.read' });
+        return send(res, 200, { connections: env.broker.listConnections(env.config.principal_id) });
+      }
+
+      if (req.method === 'GET' && url.pathname.startsWith('/v1/approvals/')) {
+        const approvalId = decodeURIComponent(url.pathname.slice('/v1/approvals/'.length));
+        const approval = env.approvals.get(approvalId);
+        if (!approval) return send(res, 404, { error: 'approval not found' });
+        const claims = authenticate(req, env, { capability: 'approval.read', mission_id: approval.mission_id });
+        if (claims.sub !== approval.agent_id) return send(res, 403, { error: 'approval belongs to another agent', code: 'agent_identity_mismatch' });
+        return send(res, 200, { approval });
+      }
+
+      if (req.method === 'POST' && url.pathname === '/v1/evaluate') {
+        const { mission, request } = await readJson(req);
+        authenticate(req, env, { capability: 'evaluate', mission });
+        return send(res, 200, persistReceipt(env.config, env.runtime.evaluate(mission, request)));
+      }
+
+      if (req.method === 'POST' && url.pathname === '/v1/prepare') {
+        const { mission, request } = await readJson(req);
+        authenticate(req, env, { capability: 'prepare', mission });
+        return send(res, 200, persistReceipt(env.config, await env.runtime.prepare(mission, request)));
+      }
+
+      if (req.method === 'POST' && url.pathname === '/v1/execute') {
+        const { mission, request } = await readJson(req);
+        authenticate(req, env, { capability: 'execute', mission });
+        const result = persistReceipt(env.config, await env.runtime.execute(mission, request));
+        const status = result.result?.code === 'connection_required' ? 409 : 200;
+        return send(res, status, result);
+      }
+
+      if (req.method === 'POST' && url.pathname === '/v1/revoke') {
+        const { mission_id, reason } = await readJson(req);
+        if (!mission_id) return send(res, 400, { error: 'mission_id is required' });
+        authenticate(req, env, { capability: 'mission.revoke', mission_id });
+        return send(res, 200, { mission_id, ...env.runtime.revoke(mission_id, reason) });
+      }
+
+      return send(res, 404, { error: 'not found' });
+    } catch (error) {
+      if (error?.code === 'provider_error' && error.provider_output) {
+        return send(res, 502, { error: error.message, provider: error.provider_output });
+      }
+      const authenticationStatus = authStatus(error);
+      if (authenticationStatus) return send(res, authenticationStatus, { error: error.message, code: error.code });
+      const status = error?.code === 'payload_too_large' ? 413 : 400;
+      return send(res, status, { error: error.message, code: error.code || 'bad_request' });
+    }
+  });
+
+  return { server, env, host: bindHost, port: bindPort };
+}
+
+export function startServer(options = {}) {
+  const instance = createAgentAuthorityServer(options);
+  instance.server.listen(instance.port, instance.host, () => {
+    const address = instance.server.address();
+    const actualPort = typeof address === 'object' && address ? address.port : instance.port;
+    console.log(`Agent Authority listening on http://${instance.host}:${actualPort}`);
+    console.log('API authentication: signed agent-instance bearer tokens required');
+  });
+  return instance;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) startServer();