@openape/proxy 0.1.2 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openape/proxy",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "OpenApe agent HTTP gateway — forward proxy with grant-based access control",
   "author": "Patrick Hofmann",
   "license": "AGPL-3.0-or-later",

package/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+shellEmulator: true
+
+trustPolicy: no-downgrade
+
+overrides:
+  '@openape/core': link:../core
+  '@openape/grants': link:../grants

package/src/auth.ts

@@ -5,18 +5,33 @@ export interface AgentIdentity {
   act: 'agent'
 }
 
+export class AuthError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'AuthError'
+  }
+}
+
 /**
  * Verify agent JWT from Proxy-Authorization header.
- * Returns the agent identity or null if invalid.
+ * Returns the agent identity or null if invalid/missing.
+ * When mandatory is true, throws AuthError if no valid JWT is provided.
  */
 export async function verifyAgentAuth(
   authHeader: string | null,
   idpUrl: string,
+  mandatory: boolean = false,
 ): Promise<AgentIdentity | null> {
-  if (!authHeader) return null
+  if (!authHeader) {
+    if (mandatory) throw new AuthError('JWT required')
+    return null
+  }
 
   const match = authHeader.match(/^Bearer\s+(.+)$/i)
-  if (!match) return null
+  if (!match) {
+    if (mandatory) throw new AuthError('Invalid authorization header')
+    return null
+  }
 
   const token = match[1]
 
@@ -25,6 +40,7 @@ export async function verifyAgentAuth(
     const { payload } = await verifyJWT(token, jwks, { issuer: idpUrl })
 
     if (payload.act !== 'agent' || !payload.sub) {
+      if (mandatory) throw new AuthError('Invalid agent token')
       return null
     }
 
@@ -32,7 +48,10 @@ export async function verifyAgentAuth(
       email: payload.sub as string,
       act: 'agent',
     }
-  } catch {
+  }
+  catch (err) {
+    if (err instanceof AuthError) throw err
+    if (mandatory) throw new AuthError('JWT verification failed')
     return null
   }
 }

package/src/config.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { parse as parseTOML } from 'smol-toml'
-import type { ProxyConfig } from './types.js'
+import type { AgentConfig, MultiAgentProxyConfig, ProxyConfig } from './types.js'
 
 export function loadConfig(path: string): ProxyConfig {
   const raw = readFileSync(path, 'utf-8')
@@ -8,7 +8,8 @@ export function loadConfig(path: string): ProxyConfig {
   let parsed: Record<string, unknown>
   if (path.endsWith('.json')) {
     parsed = JSON.parse(raw)
-  } else {
+  }
+  else {
     parsed = parseTOML(raw) as Record<string, unknown>
   }
 
@@ -26,3 +27,58 @@ export function loadConfig(path: string): ProxyConfig {
     grant_required: (parsed.grant_required ?? []) as ProxyConfig['grant_required'],
   }
 }
+
+/**
+ * Load config as multi-agent format.
+ * If the config has an `agents` array, use it directly.
+ * Otherwise, convert single-agent format to multi-agent for backward-compat.
+ */
+export function loadMultiAgentConfig(path: string, overrides?: { mandatoryAuth?: boolean }): MultiAgentProxyConfig {
+  const raw = readFileSync(path, 'utf-8')
+
+  let parsed: Record<string, unknown>
+  if (path.endsWith('.json')) {
+    parsed = JSON.parse(raw)
+  }
+  else {
+    parsed = parseTOML(raw) as Record<string, unknown>
+  }
+
+  const proxy = parsed.proxy as Record<string, unknown>
+  if (!proxy?.listen) {
+    throw new Error('Config must have [proxy] with listen')
+  }
+
+  const baseProxy: MultiAgentProxyConfig['proxy'] = {
+    listen: proxy.listen as string,
+    default_action: (proxy.default_action as MultiAgentProxyConfig['proxy']['default_action']) ?? 'block',
+    audit_log: proxy.audit_log as string | undefined,
+    mandatory_auth: overrides?.mandatoryAuth ?? (proxy.mandatory_auth as boolean | undefined),
+  }
+
+  // Multi-agent format: has agents array
+  if (Array.isArray(parsed.agents)) {
+    return {
+      proxy: baseProxy,
+      agents: parsed.agents as AgentConfig[],
+    }
+  }
+
+  // Single-agent format: convert to multi-agent
+  const idpUrl = proxy.idp_url as string
+  const agentEmail = proxy.agent_email as string
+  if (!idpUrl || !agentEmail) {
+    throw new Error('Single-agent config requires proxy.idp_url and proxy.agent_email')
+  }
+
+  return {
+    proxy: baseProxy,
+    agents: [{
+      email: agentEmail,
+      idp_url: idpUrl,
+      allow: (parsed.allow ?? []) as AgentConfig['allow'],
+      deny: (parsed.deny ?? []) as AgentConfig['deny'],
+      grant_required: (parsed.grant_required ?? []) as AgentConfig['grant_required'],
+    }],
+  }
+}

package/src/connect.ts

@@ -0,0 +1,111 @@
+import type { IncomingMessage } from 'node:http'
+import type { Socket } from 'node:net'
+import { connect } from 'node:net'
+import type { MultiAgentProxyConfig } from './types.js'
+import { AuthError, verifyAgentAuth } from './auth.js'
+import { isPrivateOrLoopback } from './ssrf.js'
+import { writeAudit } from './audit.js'
+
+/**
+ * Handle HTTP CONNECT requests for tunneling (used by HTTP_PROXY clients).
+ * Flow: Auth check → SSRF check → TCP connect → bidirectional pipe.
+ */
+export async function handleConnect(
+  config: MultiAgentProxyConfig,
+  req: IncomingMessage,
+  clientSocket: Socket,
+  _head: Buffer,
+): Promise<void> {
+  const target = req.url ?? ''
+  const [host, portStr] = target.split(':')
+  const port = Number.parseInt(portStr || '443')
+
+  if (!host || !port) {
+    clientSocket.write('HTTP/1.1 400 Bad Request\r\n\r\n')
+    clientSocket.destroy()
+    return
+  }
+
+  const mandatoryAuth = config.proxy.mandatory_auth ?? false
+
+  // Auth check — CONNECT always requires auth in mandatory mode
+  let agentEmail: string | undefined
+  try {
+    const authHeader = req.headers['proxy-authorization'] as string | undefined
+    let identity: { email: string, act: 'agent' } | null = null
+
+    for (const agentConf of config.agents) {
+      identity = await verifyAgentAuth(
+        authHeader ?? null,
+        agentConf.idp_url,
+        mandatoryAuth && config.agents.length === 1,
+      )
+      if (identity) break
+    }
+
+    if (mandatoryAuth && !identity) {
+      throw new AuthError('JWT required')
+    }
+
+    agentEmail = identity?.email
+
+    // Verify agent is known
+    if (agentEmail) {
+      const known = config.agents.find(a => a.email === agentEmail)
+      if (!known) {
+        clientSocket.write('HTTP/1.1 403 Forbidden\r\n\r\n')
+        clientSocket.destroy()
+        return
+      }
+    }
+    else if (config.agents.length > 1) {
+      throw new AuthError('JWT required for multi-agent proxy')
+    }
+  }
+  catch (err) {
+    if (err instanceof AuthError) {
+      clientSocket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')
+      clientSocket.destroy()
+      return
+    }
+    throw err
+  }
+
+  // SSRF check
+  if (await isPrivateOrLoopback(host)) {
+    writeAudit({
+      ts: new Date().toISOString(),
+      agent: agentEmail ?? config.agents[0]?.email ?? 'unknown',
+      action: 'deny',
+      domain: host,
+      method: 'CONNECT',
+      path: target,
+      rule: 'ssrf-blocked',
+    })
+    clientSocket.write('HTTP/1.1 403 Forbidden\r\n\r\n')
+    clientSocket.destroy()
+    return
+  }
+
+  // Connect to target
+  const targetSocket = connect(port, host, () => {
+    clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n')
+
+    // Bidirectional pipe
+    targetSocket.pipe(clientSocket)
+    clientSocket.pipe(targetSocket)
+  })
+
+  targetSocket.on('error', () => {
+    clientSocket.write('HTTP/1.1 502 Bad Gateway\r\n\r\n')
+    clientSocket.destroy()
+  })
+
+  clientSocket.on('error', () => {
+    targetSocket.destroy()
+  })
+
+  // Cleanup on close
+  clientSocket.on('close', () => targetSocket.destroy())
+  targetSocket.on('close', () => clientSocket.destroy())
+}

package/src/index.ts

@@ -1,62 +1,69 @@
 #!/usr/bin/env bun
+import { createServer } from 'node:http'
 import { parseArgs } from 'node:util'
-import { loadConfig } from './config.js'
-import { createProxy } from './proxy.js'
+import { loadMultiAgentConfig } from './config.js'
+import { createNodeHandler } from './proxy.js'
 import { initAudit } from './audit.js'
 
 const { values } = parseArgs({
   options: {
     config: { type: 'string', short: 'c', default: 'config.toml' },
     'dry-run': { type: 'boolean', default: false },
+    'mandatory-auth': { type: 'boolean', default: false },
   },
 })
 
 const configPath = values.config!
 
 console.log(`[openape-proxy] Loading config from ${configPath}`)
-const config = loadConfig(configPath)
+const config = loadMultiAgentConfig(configPath, {
+  mandatoryAuth: values['mandatory-auth'] || undefined,
+})
 
 // Init audit log
 initAudit(config.proxy.audit_log)
 
 if (values['dry-run']) {
   console.log('[openape-proxy] DRY RUN mode — logging only, not blocking')
-  // In dry-run mode, we could override deny rules to just log
-  // For now, just print config and exit
   console.log('[openape-proxy] Config loaded:')
   console.log(`  Listen: ${config.proxy.listen}`)
-  console.log(`  IdP: ${config.proxy.idp_url}`)
-  console.log(`  Agent: ${config.proxy.agent_email}`)
   console.log(`  Default action: ${config.proxy.default_action}`)
-  console.log(`  Allow rules: ${config.allow.length}`)
-  console.log(`  Deny rules: ${config.deny.length}`)
-  console.log(`  Grant rules: ${config.grant_required.length}`)
+  console.log(`  Mandatory auth: ${config.proxy.mandatory_auth ?? false}`)
+  console.log(`  Agents: ${config.agents.length}`)
+  for (const agent of config.agents) {
+    const allowCount = agent.allow?.length ?? 0
+    const denyCount = agent.deny?.length ?? 0
+    const grantCount = agent.grant_required?.length ?? 0
+    console.log(`    ${agent.email} (${agent.idp_url}) — ${allowCount} allow, ${denyCount} deny, ${grantCount} grant`)
+  }
   process.exit(0)
 }
 
-const proxy = createProxy(config)
+const handler = createNodeHandler(config)
 
-const server = Bun.serve({
-  port: proxy.port,
-  hostname: proxy.hostname,
-  fetch: proxy.fetch,
-})
+const port = Number.parseInt(config.proxy.listen.split(':')[1] || '9090')
+const hostname = config.proxy.listen.split(':')[0] || '127.0.0.1'
 
-console.log(`[openape-proxy] 🐾 Listening on http://${server.hostname}:${server.port}`)
-console.log(`[openape-proxy] IdP: ${config.proxy.idp_url}`)
-console.log(`[openape-proxy] Agent: ${config.proxy.agent_email}`)
-console.log(`[openape-proxy] Rules: ${config.allow.length} allow, ${config.deny.length} deny, ${config.grant_required.length} grant-required`)
-console.log(`[openape-proxy] Default action: ${config.proxy.default_action}`)
+const server = createServer(handler.handleRequest)
+server.on('connect', handler.handleConnect)
+
+server.listen(port, hostname, () => {
+  console.log(`[openape-proxy] Listening on http://${hostname}:${port}`)
+  console.log(`[openape-proxy] CONNECT tunneling enabled`)
+  console.log(`[openape-proxy] Mandatory auth: ${config.proxy.mandatory_auth ?? false}`)
+  console.log(`[openape-proxy] Agents: ${config.agents.map(a => a.email).join(', ')}`)
+  console.log(`[openape-proxy] Default action: ${config.proxy.default_action}`)
+})
 
 // Graceful shutdown
 process.on('SIGINT', () => {
   console.log('\n[openape-proxy] Shutting down...')
-  server.stop()
+  server.close()
   process.exit(0)
 })
 
 process.on('SIGTERM', () => {
   console.log('[openape-proxy] Shutting down...')
-  server.stop()
+  server.close()
   process.exit(0)
 })

package/src/proxy.ts

@@ -1,9 +1,13 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Socket } from 'node:net'
 import { createHash } from 'node:crypto'
-import type { ProxyConfig, AuditEntry } from './types.js'
+import type { AgentConfig, AuditEntry, MultiAgentProxyConfig, ProxyConfig } from './types.js'
 import { evaluateRules } from './matcher.js'
-import { verifyAgentAuth } from './auth.js'
+import { AuthError, verifyAgentAuth } from './auth.js'
 import { GrantsClient } from './grants-client.js'
 import { writeAudit } from './audit.js'
+import { isPrivateOrLoopback } from './ssrf.js'
+import { handleConnect } from './connect.js'
 
 /**
  * Compute a request hash that uniquely identifies the intent.
@@ -19,11 +23,37 @@ async function computeRequestHash(method: string, targetUrl: string, body: Array
   return hash.digest('hex')
 }
 
+/** Legacy single-agent proxy */
 export function createProxy(config: ProxyConfig) {
-  const grantsClient = new GrantsClient(config.proxy.idp_url)
+  const multiConfig: MultiAgentProxyConfig = {
+    proxy: {
+      listen: config.proxy.listen,
+      default_action: config.proxy.default_action,
+      audit_log: config.proxy.audit_log,
+      mandatory_auth: config.proxy.mandatory_auth,
+    },
+    agents: [{
+      email: config.proxy.agent_email,
+      idp_url: config.proxy.idp_url,
+      allow: config.allow,
+      deny: config.deny,
+      grant_required: config.grant_required,
+    }],
+  }
+  return createMultiAgentProxy(multiConfig)
+}
+
+/** Multi-agent proxy with SSRF protection and mandatory auth */
+export function createMultiAgentProxy(config: MultiAgentProxyConfig) {
+  const grantsClients = new Map<string, GrantsClient>()
+  for (const agent of config.agents) {
+    grantsClients.set(agent.email, new GrantsClient(agent.idp_url))
+  }
+
+  const mandatoryAuth = config.proxy.mandatory_auth ?? false
 
   return {
-    port: parseInt(config.proxy.listen.split(':')[1] || '9090'),
+    port: Number.parseInt(config.proxy.listen.split(':')[1] || '9090'),
     hostname: config.proxy.listen.split(':')[0] || '127.0.0.1',
 
     async fetch(req: Request): Promise<Response> {
@@ -32,17 +62,19 @@ export function createProxy(config: ProxyConfig) {
 
       // Health endpoint
       if (url.pathname === '/healthz') {
-        return Response.json({ status: 'ok', agent: config.proxy.agent_email })
+        return Response.json({
+          status: 'ok',
+          agents: config.agents.map(a => a.email),
+        })
       }
 
-      // Parse target URL from the path.
-      // The agent sends: http://proxy:9090/https://api.github.com/repos/x/issues
-      // So the target URL is everything after the first /
+      // Parse target URL from the path
       const targetUrl = url.pathname.slice(1) + url.search
       let targetParsed: URL
       try {
         targetParsed = new URL(targetUrl)
-      } catch {
+      }
+      catch {
         return new Response(
           'Invalid target URL. Send requests as: http://proxy:port/https://target.com/path',
           { status: 400 },
@@ -53,23 +85,80 @@ export function createProxy(config: ProxyConfig) {
       const method = req.method
       const path = targetParsed.pathname
 
+      // SSRF protection — block private/loopback IPs before any rule evaluation
+      if (await isPrivateOrLoopback(domain)) {
+        return new Response('Blocked: private/loopback IP', { status: 403 })
+      }
+
       // Read body once (needed for hash + forwarding)
       const bodyBuffer = req.body ? await req.arrayBuffer() : null
 
-      // Verify agent identity
-      const agent = await verifyAgentAuth(
-        req.headers.get('proxy-authorization'),
-        config.proxy.idp_url,
-      )
+      // Verify agent identity — find IdP URL from first agent (for JWKS verification)
+      // In multi-agent mode, we need the JWT to identify the agent first.
+      // We try verification against each agent's IdP until one succeeds.
+      let agentIdentity: { email: string, act: 'agent' } | null = null
+      try {
+        for (const agentConf of config.agents) {
+          agentIdentity = await verifyAgentAuth(
+            req.headers.get('proxy-authorization'),
+            agentConf.idp_url,
+            mandatoryAuth && config.agents.length === 1,
+          )
+          if (agentIdentity) break
+        }
+
+        // If mandatory auth and no identity found from any IdP
+        if (mandatoryAuth && !agentIdentity) {
+          throw new AuthError('JWT required')
+        }
+      }
+      catch (err) {
+        if (err instanceof AuthError) {
+          return new Response(`Unauthorized: ${err.message}`, { status: 401 })
+        }
+        throw err
+      }
+
+      // Find the matching agent config
+      const agentEmail = agentIdentity?.email
+      let agentConf: AgentConfig | undefined
+
+      if (agentEmail) {
+        agentConf = config.agents.find(a => a.email === agentEmail)
+        if (!agentConf) {
+          return new Response(`Forbidden: unknown agent ${agentEmail}`, { status: 403 })
+        }
+      }
+      else if (config.agents.length === 1) {
+        // Non-mandatory auth, single agent: use the only agent config
+        agentConf = config.agents[0]
+      }
+      else {
+        return new Response('Unauthorized: JWT required for multi-agent proxy', { status: 401 })
+      }
 
-      const agentEmail = agent?.email ?? config.proxy.agent_email
+      const effectiveEmail = agentEmail ?? agentConf.email
+      const grantsClient = grantsClients.get(agentConf.email)!
+
+      // Build a ProxyConfig-shaped object for evaluateRules
+      const rulesConfig: ProxyConfig = {
+        proxy: {
+          listen: config.proxy.listen,
+          idp_url: agentConf.idp_url,
+          agent_email: agentConf.email,
+          default_action: config.proxy.default_action,
+        },
+        allow: agentConf.allow ?? [],
+        deny: agentConf.deny ?? [],
+        grant_required: agentConf.grant_required ?? [],
+      }
 
       // Evaluate rules
-      const action = evaluateRules(config, domain, method, path)
+      const action = evaluateRules(rulesConfig, domain, method, path)
 
       const baseAudit: Omit<AuditEntry, 'action' | 'rule'> = {
         ts: new Date().toISOString(),
-        agent: agentEmail,
+        agent: effectiveEmail,
         domain,
         method,
         path,
@@ -96,7 +185,7 @@ export function createProxy(config: ProxyConfig) {
 
       // Check for existing grant
       const existing = await grantsClient.findExistingGrant(
-        agentEmail,
+        effectiveEmail,
         domain,
         permissions,
       ).catch(() => null)
@@ -121,7 +210,7 @@ export function createProxy(config: ProxyConfig) {
       if (config.proxy.default_action === 'request-async') {
         // Create grant request, return 407 immediately
         const grant = await grantsClient.requestGrant({
-          requester: agentEmail,
+          requester: effectiveEmail,
           target: domain,
           grantType: rule.grant_type,
           permissions,
@@ -152,7 +241,7 @@ export function createProxy(config: ProxyConfig) {
 
       try {
         const grant = await grantsClient.requestGrant({
-          requester: agentEmail,
+          requester: effectiveEmail,
           target: domain,
           grantType: rule.grant_type,
           permissions,
@@ -185,8 +274,8 @@ export function createProxy(config: ProxyConfig) {
           waited_ms: waitedMs,
         })
         return new Response(`Grant denied by ${approved.decided_by}`, { status: 403 })
-
-      } catch (err) {
+      }
+      catch (err) {
         const msg = err instanceof Error ? err.message : 'Unknown error'
         writeAudit({
           ...baseAudit,
@@ -200,6 +289,73 @@ export function createProxy(config: ProxyConfig) {
   }
 }
 
+/**
+ * Create a node:http compatible handler for use with http.createServer().
+ * Returns both a request handler and a CONNECT handler.
+ */
+export function createNodeHandler(config: MultiAgentProxyConfig): {
+  handleRequest: (req: IncomingMessage, res: ServerResponse) => void
+  handleConnect: (req: IncomingMessage, socket: Socket, head: Buffer) => void
+} {
+  const proxy = createMultiAgentProxy(config)
+
+  return {
+    handleRequest(req: IncomingMessage, res: ServerResponse) {
+      // Convert IncomingMessage to Request and use existing fetch logic
+      const url = `http://${req.headers.host || 'localhost'}${req.url || '/'}`
+      const chunks: Buffer[] = []
+
+      req.on('data', (chunk: Buffer) => chunks.push(chunk))
+      req.on('end', async () => {
+        try {
+          const body = chunks.length > 0 ? Buffer.concat(chunks) : undefined
+          const headers = new Headers()
+          for (const [key, value] of Object.entries(req.headers)) {
+            if (value) {
+              headers.set(key, Array.isArray(value) ? value.join(', ') : value)
+            }
+          }
+
+          const request = new Request(url, {
+            method: req.method,
+            headers,
+            body: body && req.method !== 'GET' && req.method !== 'HEAD' ? body : undefined,
+            duplex: 'half',
+          } as RequestInit)
+
+          const response = await proxy.fetch(request)
+
+          res.writeHead(response.status, response.statusText, Object.fromEntries(response.headers))
+          if (response.body) {
+            const reader = response.body.getReader()
+            const pump = async (): Promise<void> => {
+              const { done, value } = await reader.read()
+              if (done) {
+                res.end()
+                return
+              }
+              res.write(value)
+              return pump()
+            }
+            await pump()
+          }
+          else {
+            res.end()
+          }
+        }
+        catch {
+          res.writeHead(502)
+          res.end('Proxy error')
+        }
+      })
+    },
+
+    handleConnect(req: IncomingMessage, socket: Socket, head: Buffer) {
+      handleConnect(config, req, socket, head)
+    },
+  }
+}
+
 /**
  * Forward a request to the target URL.
  * Strips proxy-specific headers, preserves the rest.

package/src/ssrf.ts

@@ -0,0 +1,85 @@
+import { resolve4, resolve6 } from 'node:dns/promises'
+import { isIP } from 'node:net'
+
+const PRIVATE_RANGES_V4 = [
+  { prefix: 0x7F000000, mask: 0xFF000000 }, // 127.0.0.0/8
+  { prefix: 0x0A000000, mask: 0xFF000000 }, // 10.0.0.0/8
+  { prefix: 0xAC100000, mask: 0xFFF00000 }, // 172.16.0.0/12
+  { prefix: 0xC0A80000, mask: 0xFFFF0000 }, // 192.168.0.0/16
+  { prefix: 0xA9FE0000, mask: 0xFFFF0000 }, // 169.254.0.0/16
+  { prefix: 0x00000000, mask: 0xFF000000 }, // 0.0.0.0/8
+]
+
+function ipv4ToNumber(ip: string): number {
+  const parts = ip.split('.').map(Number)
+  return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0
+}
+
+function isPrivateIPv4(ip: string): boolean {
+  const num = ipv4ToNumber(ip)
+  return PRIVATE_RANGES_V4.some(r => ((num & r.mask) >>> 0) === r.prefix)
+}
+
+function isPrivateIPv6(ip: string): boolean {
+  const normalized = ip.toLowerCase()
+
+  // Loopback ::1
+  if (normalized === '::1') return true
+
+  // Unspecified ::
+  if (normalized === '::') return true
+
+  // Link-local fe80::/10
+  if (normalized.startsWith('fe8') || normalized.startsWith('fe9')
+    || normalized.startsWith('fea') || normalized.startsWith('feb')) {
+    return true
+  }
+
+  // Unique local fd00::/8
+  if (normalized.startsWith('fd')) return true
+
+  // IPv4-mapped ::ffff:x.x.x.x
+  const v4mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
+  if (v4mapped) return isPrivateIPv4(v4mapped[1])
+
+  return false
+}
+
+function isPrivateIP(ip: string): boolean {
+  if (isIP(ip) === 4) return isPrivateIPv4(ip)
+  if (isIP(ip) === 6) return isPrivateIPv6(ip)
+  return false
+}
+
+/**
+ * Check if a hostname resolves to a private or loopback IP.
+ * If the hostname is already an IP literal, check directly.
+ * Otherwise, resolve via DNS and check all results.
+ */
+export async function isPrivateOrLoopback(hostname: string): Promise<boolean> {
+  // Direct IP literal
+  if (isIP(hostname)) {
+    return isPrivateIP(hostname)
+  }
+
+  // localhost shortcut
+  if (hostname === 'localhost') return true
+
+  // DNS resolution — check both A and AAAA records
+  try {
+    const [v4, v6] = await Promise.allSettled([
+      resolve4(hostname),
+      resolve6(hostname),
+    ])
+    const addrs: string[] = []
+    if (v4.status === 'fulfilled') addrs.push(...v4.value)
+    if (v6.status === 'fulfilled') addrs.push(...v6.value)
+
+    if (addrs.length === 0) return true // no records — block to be safe
+    return addrs.some(addr => isPrivateIP(addr))
+  }
+  catch {
+    // DNS failure — block to be safe
+    return true
+  }
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-/** Proxy configuration (parsed from TOML/JSON) */
+/** Single-agent proxy configuration (legacy format, parsed from TOML/JSON) */
 export interface ProxyConfig {
   proxy: {
     listen: string
@@ -6,12 +6,32 @@ export interface ProxyConfig {
     agent_email: string
     default_action: 'block' | 'request' | 'request-async'
     audit_log?: string
+    mandatory_auth?: boolean
   }
   allow: RuleEntry[]
   deny: RuleEntry[]
   grant_required: GrantRuleEntry[]
 }
 
+/** Multi-agent proxy configuration */
+export interface MultiAgentProxyConfig {
+  proxy: {
+    listen: string
+    default_action: 'block' | 'request' | 'request-async'
+    audit_log?: string
+    mandatory_auth?: boolean
+  }
+  agents: AgentConfig[]
+}
+
+export interface AgentConfig {
+  email: string
+  idp_url: string
+  allow?: RuleEntry[]
+  deny?: RuleEntry[]
+  grant_required?: GrantRuleEntry[]
+}
+
 export interface RuleEntry {
   domain: string
   methods?: string[]

package/test/auth.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { AuthError, verifyAgentAuth } from '../src/auth.js'
+
+describe('verifyAgentAuth', () => {
+  const idpUrl = 'https://id.example.com'
+
+  describe('non-mandatory mode', () => {
+    it('returns null when no header provided', async () => {
+      const result = await verifyAgentAuth(null, idpUrl, false)
+      expect(result).toBeNull()
+    })
+
+    it('returns null for invalid header format', async () => {
+      const result = await verifyAgentAuth('Basic abc123', idpUrl, false)
+      expect(result).toBeNull()
+    })
+
+    it('returns null for invalid JWT', async () => {
+      const result = await verifyAgentAuth('Bearer invalid.token.here', idpUrl, false)
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('mandatory mode', () => {
+    it('throws AuthError when no header provided', async () => {
+      await expect(
+        verifyAgentAuth(null, idpUrl, true),
+      ).rejects.toThrow(AuthError)
+    })
+
+    it('throws AuthError with "JWT required" message', async () => {
+      await expect(
+        verifyAgentAuth(null, idpUrl, true),
+      ).rejects.toThrow('JWT required')
+    })
+
+    it('throws AuthError for invalid header format', async () => {
+      await expect(
+        verifyAgentAuth('Basic abc123', idpUrl, true),
+      ).rejects.toThrow(AuthError)
+    })
+
+    it('throws AuthError for invalid JWT token', async () => {
+      await expect(
+        verifyAgentAuth('Bearer invalid.token.here', idpUrl, true),
+      ).rejects.toThrow(AuthError)
+    })
+  })
+
+  describe('authError', () => {
+    it('is an instance of Error', () => {
+      const err = new AuthError('test')
+      expect(err).toBeInstanceOf(Error)
+      expect(err.name).toBe('AuthError')
+    })
+  })
+})

package/test/connect.test.ts

@@ -0,0 +1,131 @@
+import { createServer } from 'node:http'
+import { connect } from 'node:net'
+import { describe, expect, it, afterEach } from 'vitest'
+import type { MultiAgentProxyConfig } from '../src/types.js'
+import { handleConnect } from '../src/connect.js'
+
+function makeConfig(overrides?: Partial<MultiAgentProxyConfig['proxy']>): MultiAgentProxyConfig {
+  return {
+    proxy: {
+      listen: '127.0.0.1:0',
+      default_action: 'block',
+      mandatory_auth: true,
+      ...overrides,
+    },
+    agents: [{
+      email: 'bot@example.com',
+      idp_url: 'https://id.example.com',
+    }],
+  }
+}
+
+function startProxy(config: MultiAgentProxyConfig): Promise<{ port: number, close: () => Promise<void> }> {
+  return new Promise((resolve) => {
+    const server = createServer((_req, res) => {
+      res.writeHead(200)
+      res.end('ok')
+    })
+    server.on('connect', (req, socket, head) => {
+      handleConnect(config, req, socket, head)
+    })
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address() as { port: number }
+      resolve({
+        port: addr.port,
+        close: () => new Promise<void>(r => server.close(() => r())),
+      })
+    })
+  })
+}
+
+function sendConnect(proxyPort: number, target: string, headers?: Record<string, string>): Promise<{ statusLine: string }> {
+  return new Promise((resolve, reject) => {
+    const socket = connect(proxyPort, '127.0.0.1', () => {
+      let headerStr = `CONNECT ${target} HTTP/1.1\r\nHost: ${target}\r\n`
+      if (headers) {
+        for (const [k, v] of Object.entries(headers)) {
+          headerStr += `${k}: ${v}\r\n`
+        }
+      }
+      headerStr += '\r\n'
+      socket.write(headerStr)
+    })
+
+    let data = ''
+    socket.on('data', (chunk) => {
+      data += chunk.toString()
+      if (data.includes('\r\n\r\n')) {
+        const statusLine = data.split('\r\n')[0]
+        socket.destroy()
+        resolve({ statusLine })
+      }
+    })
+
+    socket.on('error', reject)
+    socket.setTimeout(3000, () => {
+      socket.destroy()
+      reject(new Error('Timeout'))
+    })
+  })
+}
+
+describe('connect handler', () => {
+  let cleanup: (() => Promise<void>) | undefined
+
+  afterEach(async () => {
+    if (cleanup) {
+      await cleanup()
+      cleanup = undefined
+    }
+  })
+
+  it('blocks CONNECT to loopback IP (SSRF)', async () => {
+    const config = makeConfig({ mandatory_auth: false })
+    config.agents = [{ email: 'bot@example.com', idp_url: 'https://id.example.com' }]
+    const { port, close } = await startProxy(config)
+    cleanup = close
+
+    const { statusLine } = await sendConnect(port, '127.0.0.1:3000')
+    expect(statusLine).toContain('403')
+  })
+
+  it('blocks CONNECT to private IP (SSRF)', async () => {
+    const config = makeConfig({ mandatory_auth: false })
+    config.agents = [{ email: 'bot@example.com', idp_url: 'https://id.example.com' }]
+    const { port, close } = await startProxy(config)
+    cleanup = close
+
+    const { statusLine } = await sendConnect(port, '10.0.0.1:80')
+    expect(statusLine).toContain('403')
+  })
+
+  it('returns 401 without JWT when mandatory auth is enabled', async () => {
+    const config = makeConfig({ mandatory_auth: true })
+    const { port, close } = await startProxy(config)
+    cleanup = close
+
+    const { statusLine } = await sendConnect(port, 'httpbin.org:443')
+    expect(statusLine).toContain('401')
+  })
+
+  it('returns 401 with invalid JWT when mandatory auth is enabled', async () => {
+    const config = makeConfig({ mandatory_auth: true })
+    const { port, close } = await startProxy(config)
+    cleanup = close
+
+    const { statusLine } = await sendConnect(port, 'httpbin.org:443', {
+      'Proxy-Authorization': 'Bearer invalid.token.here',
+    })
+    expect(statusLine).toContain('401')
+  })
+
+  it('blocks malformed target (treated as SSRF)', async () => {
+    const config = makeConfig({ mandatory_auth: false })
+    config.agents = [{ email: 'bot@example.com', idp_url: 'https://id.example.com' }]
+    const { port, close } = await startProxy(config)
+    cleanup = close
+
+    const { statusLine } = await sendConnect(port, 'not-a-host')
+    expect(statusLine).toContain('403')
+  })
+})

package/test/multi-agent.test.ts

@@ -0,0 +1,122 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { describe, expect, it } from 'vitest'
+import { loadMultiAgentConfig } from '../src/config.js'
+
+function tmpFile(name: string, content: string): string {
+  const dir = mkdtempSync(join(tmpdir(), 'proxy-test-'))
+  const path = join(dir, name)
+  writeFileSync(path, content)
+  return path
+}
+
+describe('loadMultiAgentConfig', () => {
+  it('loads multi-agent TOML config', () => {
+    const path = tmpFile('proxy.toml', `
+[proxy]
+listen = "127.0.0.1:9090"
+default_action = "block"
+mandatory_auth = true
+
+[[agents]]
+email = "bot1@example.com"
+idp_url = "https://id1.example.com"
+
+[[agents.allow]]
+domain = "api.github.com"
+
+[[agents]]
+email = "bot2@example.com"
+idp_url = "https://id2.example.com"
+`)
+
+    const config = loadMultiAgentConfig(path)
+
+    expect(config.proxy.listen).toBe('127.0.0.1:9090')
+    expect(config.proxy.default_action).toBe('block')
+    expect(config.proxy.mandatory_auth).toBe(true)
+    expect(config.agents).toHaveLength(2)
+    expect(config.agents[0].email).toBe('bot1@example.com')
+    expect(config.agents[0].idp_url).toBe('https://id1.example.com')
+    expect(config.agents[0].allow).toHaveLength(1)
+    expect(config.agents[0].allow![0].domain).toBe('api.github.com')
+    expect(config.agents[1].email).toBe('bot2@example.com')
+  })
+
+  it('converts single-agent config to multi-agent format', () => {
+    const path = tmpFile('legacy.toml', `
+[proxy]
+listen = "127.0.0.1:9090"
+idp_url = "https://id.example.com"
+agent_email = "agent@example.com"
+default_action = "request-async"
+
+[[allow]]
+domain = "*.github.com"
+
+[[deny]]
+domain = "evil.com"
+
+[[grant_required]]
+domain = "api.openai.com"
+grant_type = "once"
+`)
+
+    const config = loadMultiAgentConfig(path)
+
+    expect(config.proxy.listen).toBe('127.0.0.1:9090')
+    expect(config.proxy.default_action).toBe('request-async')
+    expect(config.agents).toHaveLength(1)
+    expect(config.agents[0].email).toBe('agent@example.com')
+    expect(config.agents[0].idp_url).toBe('https://id.example.com')
+    expect(config.agents[0].allow).toHaveLength(1)
+    expect(config.agents[0].deny).toHaveLength(1)
+    expect(config.agents[0].grant_required).toHaveLength(1)
+  })
+
+  it('applies mandatory-auth override', () => {
+    const path = tmpFile('override.toml', `
+[proxy]
+listen = "127.0.0.1:9090"
+idp_url = "https://id.example.com"
+agent_email = "agent@example.com"
+`)
+
+    const config = loadMultiAgentConfig(path, { mandatoryAuth: true })
+    expect(config.proxy.mandatory_auth).toBe(true)
+  })
+
+  it('loads multi-agent JSON config', () => {
+    const path = tmpFile('proxy.json', JSON.stringify({
+      proxy: {
+        listen: '127.0.0.1:9090',
+        default_action: 'block',
+      },
+      agents: [
+        { email: 'a@b.com', idp_url: 'https://id.example.com' },
+      ],
+    }))
+
+    const config = loadMultiAgentConfig(path)
+    expect(config.agents).toHaveLength(1)
+    expect(config.agents[0].email).toBe('a@b.com')
+  })
+
+  it('throws on missing listen', () => {
+    const path = tmpFile('bad.toml', `
+[proxy]
+default_action = "block"
+`)
+    expect(() => loadMultiAgentConfig(path)).toThrow('listen')
+  })
+
+  it('throws on single-agent without idp_url', () => {
+    const path = tmpFile('bad2.toml', `
+[proxy]
+listen = "127.0.0.1:9090"
+agent_email = "agent@example.com"
+`)
+    expect(() => loadMultiAgentConfig(path)).toThrow('idp_url')
+  })
+})

package/test/ssrf.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import { isPrivateOrLoopback } from '../src/ssrf.js'
+
+describe('isPrivateOrLoopback', () => {
+  // IPv4 loopback
+  it('blocks 127.0.0.1', async () => {
+    expect(await isPrivateOrLoopback('127.0.0.1')).toBe(true)
+  })
+
+  it('blocks 127.255.255.255', async () => {
+    expect(await isPrivateOrLoopback('127.255.255.255')).toBe(true)
+  })
+
+  // RFC 1918
+  it('blocks 10.0.0.1', async () => {
+    expect(await isPrivateOrLoopback('10.0.0.1')).toBe(true)
+  })
+
+  it('blocks 172.16.0.1', async () => {
+    expect(await isPrivateOrLoopback('172.16.0.1')).toBe(true)
+  })
+
+  it('blocks 172.31.255.255', async () => {
+    expect(await isPrivateOrLoopback('172.31.255.255')).toBe(true)
+  })
+
+  it('blocks 192.168.1.1', async () => {
+    expect(await isPrivateOrLoopback('192.168.1.1')).toBe(true)
+  })
+
+  // Link-local
+  it('blocks 169.254.0.1', async () => {
+    expect(await isPrivateOrLoopback('169.254.0.1')).toBe(true)
+  })
+
+  // Unspecified
+  it('blocks 0.0.0.0', async () => {
+    expect(await isPrivateOrLoopback('0.0.0.0')).toBe(true)
+  })
+
+  // IPv6
+  it('blocks ::1', async () => {
+    expect(await isPrivateOrLoopback('::1')).toBe(true)
+  })
+
+  it('blocks ::', async () => {
+    expect(await isPrivateOrLoopback('::')).toBe(true)
+  })
+
+  // localhost
+  it('blocks localhost', async () => {
+    expect(await isPrivateOrLoopback('localhost')).toBe(true)
+  })
+
+  // Public IPs — should NOT be blocked
+  it('allows 8.8.8.8', async () => {
+    expect(await isPrivateOrLoopback('8.8.8.8')).toBe(false)
+  })
+
+  it('allows 1.1.1.1', async () => {
+    expect(await isPrivateOrLoopback('1.1.1.1')).toBe(false)
+  })
+
+  // 172.15.x.x is NOT in 172.16.0.0/12
+  it('allows 172.15.255.255', async () => {
+    expect(await isPrivateOrLoopback('172.15.255.255')).toBe(false)
+  })
+
+  // 172.32.x.x is NOT in 172.16.0.0/12
+  it('allows 172.32.0.1', async () => {
+    expect(await isPrivateOrLoopback('172.32.0.1')).toBe(false)
+  })
+})