aap-agent-server 2.5.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aap-agent-server",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Server middleware for Agent Attestation Protocol - verify AI agents",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,7 +21,8 @@
   },
   "homepage": "https://github.com/ira-hash/agent-attestation-protocol#readme",
   "dependencies": {
-    "aap-agent-core": "^2.5.0"
+    "aap-agent-core": "^2.6.0",
+    "ws": "^8.16.0"
   },
   "peerDependencies": {
     "express": "^4.18.0 || ^5.0.0"

package/persistence.js

@@ -0,0 +1,238 @@
+/**
+ * AAP Challenge Persistence
+ * 
+ * Optional: Persist challenges to survive server restarts
+ * Supports: Memory (default), File, Redis
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/**
+ * Create in-memory store (default, no persistence)
+ */
+export function createMemoryStore() {
+  const challenges = new Map();
+
+  return {
+    type: 'memory',
+    
+    async get(nonce) {
+      return challenges.get(nonce) || null;
+    },
+
+    async set(nonce, data) {
+      challenges.set(nonce, data);
+    },
+
+    async delete(nonce) {
+      challenges.delete(nonce);
+    },
+
+    async has(nonce) {
+      return challenges.has(nonce);
+    },
+
+    async size() {
+      return challenges.size;
+    },
+
+    async keys() {
+      return [...challenges.keys()];
+    },
+
+    async clear() {
+      challenges.clear();
+    },
+
+    async cleanup(now = Date.now()) {
+      for (const [nonce, data] of challenges.entries()) {
+        if (now > data.expiresAt) {
+          challenges.delete(nonce);
+        }
+      }
+    }
+  };
+}
+
+/**
+ * Create file-based store (survives restarts)
+ * @param {string} filePath - Path to store file
+ */
+export function createFileStore(filePath = '.aap/challenges.json') {
+  const fullPath = join(process.cwd(), filePath);
+  let challenges = new Map();
+
+  // Load existing data
+  try {
+    if (existsSync(fullPath)) {
+      const data = JSON.parse(readFileSync(fullPath, 'utf8'));
+      challenges = new Map(Object.entries(data));
+      console.log(`[AAP] Loaded ${challenges.size} challenges from ${fullPath}`);
+    }
+  } catch (error) {
+    console.warn('[AAP] Could not load challenges:', error.message);
+  }
+
+  // Save to file
+  const save = () => {
+    try {
+      const dir = dirname(fullPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      
+      const data = Object.fromEntries(challenges);
+      // Remove validator functions (not serializable)
+      for (const key of Object.keys(data)) {
+        delete data[key].validators;
+      }
+      
+      writeFileSync(fullPath, JSON.stringify(data, null, 2));
+    } catch (error) {
+      console.error('[AAP] Could not save challenges:', error.message);
+    }
+  };
+
+  // Auto-save periodically
+  const saveInterval = setInterval(save, 30000);
+
+  return {
+    type: 'file',
+    
+    async get(nonce) {
+      return challenges.get(nonce) || null;
+    },
+
+    async set(nonce, data) {
+      challenges.set(nonce, data);
+      save();
+    },
+
+    async delete(nonce) {
+      challenges.delete(nonce);
+      save();
+    },
+
+    async has(nonce) {
+      return challenges.has(nonce);
+    },
+
+    async size() {
+      return challenges.size;
+    },
+
+    async keys() {
+      return [...challenges.keys()];
+    },
+
+    async clear() {
+      challenges.clear();
+      save();
+    },
+
+    async cleanup(now = Date.now()) {
+      let cleaned = 0;
+      for (const [nonce, data] of challenges.entries()) {
+        if (now > data.expiresAt) {
+          challenges.delete(nonce);
+          cleaned++;
+        }
+      }
+      if (cleaned > 0) save();
+      return cleaned;
+    },
+
+    close() {
+      clearInterval(saveInterval);
+      save();
+    }
+  };
+}
+
+/**
+ * Create Redis-based store (for distributed deployments)
+ * @param {Object} redisClient - Redis client instance (ioredis or redis)
+ * @param {string} [prefix='aap:challenge:'] - Key prefix
+ */
+export function createRedisStore(redisClient, prefix = 'aap:challenge:') {
+  return {
+    type: 'redis',
+    
+    async get(nonce) {
+      const data = await redisClient.get(prefix + nonce);
+      return data ? JSON.parse(data) : null;
+    },
+
+    async set(nonce, data, ttlMs = 60000) {
+      // Store without validators (not serializable)
+      const { validators, ...storable } = data;
+      await redisClient.set(
+        prefix + nonce,
+        JSON.stringify(storable),
+        'PX',
+        ttlMs
+      );
+    },
+
+    async delete(nonce) {
+      await redisClient.del(prefix + nonce);
+    },
+
+    async has(nonce) {
+      return (await redisClient.exists(prefix + nonce)) === 1;
+    },
+
+    async size() {
+      const keys = await redisClient.keys(prefix + '*');
+      return keys.length;
+    },
+
+    async keys() {
+      const keys = await redisClient.keys(prefix + '*');
+      return keys.map(k => k.slice(prefix.length));
+    },
+
+    async clear() {
+      const keys = await redisClient.keys(prefix + '*');
+      if (keys.length > 0) {
+        await redisClient.del(...keys);
+      }
+    },
+
+    async cleanup() {
+      // Redis handles TTL automatically
+      return 0;
+    }
+  };
+}
+
+/**
+ * Auto-detect and create appropriate store
+ * @param {Object} options
+ * @param {'memory'|'file'|'redis'} [options.type='memory']
+ * @param {string} [options.filePath]
+ * @param {Object} [options.redisClient]
+ */
+export function createStore(options = {}) {
+  const { type = 'memory', filePath, redisClient } = options;
+
+  switch (type) {
+    case 'file':
+      return createFileStore(filePath);
+    case 'redis':
+      if (!redisClient) {
+        throw new Error('Redis client required for redis store');
+      }
+      return createRedisStore(redisClient);
+    default:
+      return createMemoryStore();
+  }
+}
+
+export default {
+  createMemoryStore,
+  createFileStore,
+  createRedisStore,
+  createStore
+};

package/ratelimit.js

@@ -0,0 +1,117 @@
+/**
+ * AAP Rate Limiter
+ * 
+ * Simple in-memory rate limiting (no external dependencies)
+ */
+
+/**
+ * Create a rate limiter
+ * @param {Object} options
+ * @param {number} [options.windowMs=60000] - Time window in ms
+ * @param {number} [options.max=10] - Max requests per window
+ * @param {string} [options.message] - Error message
+ * @returns {Function} Express middleware
+ */
+export function createRateLimiter(options = {}) {
+  const {
+    windowMs = 60000,
+    max = 10,
+    message = 'Too many requests, please try again later'
+  } = options;
+
+  const requests = new Map();
+
+  // Cleanup old entries periodically
+  setInterval(() => {
+    const now = Date.now();
+    for (const [key, data] of requests.entries()) {
+      if (now - data.firstRequest > windowMs) {
+        requests.delete(key);
+      }
+    }
+  }, windowMs);
+
+  return (req, res, next) => {
+    const key = req.ip || req.connection.remoteAddress || 'unknown';
+    const now = Date.now();
+
+    let data = requests.get(key);
+
+    if (!data || now - data.firstRequest > windowMs) {
+      // New window
+      data = { count: 1, firstRequest: now };
+      requests.set(key, data);
+    } else {
+      data.count++;
+    }
+
+    // Set headers
+    const remaining = Math.max(0, max - data.count);
+    const resetTime = Math.ceil((data.firstRequest + windowMs) / 1000);
+    
+    res.setHeader('X-RateLimit-Limit', max);
+    res.setHeader('X-RateLimit-Remaining', remaining);
+    res.setHeader('X-RateLimit-Reset', resetTime);
+
+    if (data.count > max) {
+      res.setHeader('Retry-After', Math.ceil((data.firstRequest + windowMs - now) / 1000));
+      return res.status(429).json({
+        error: message,
+        retryAfter: Math.ceil((data.firstRequest + windowMs - now) / 1000)
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * Create rate limiter for failed attempts
+ * Stricter limits after failures
+ */
+export function createFailureLimiter(options = {}) {
+  const {
+    windowMs = 60000,
+    maxFailures = 5,
+    message = 'Too many failed attempts'
+  } = options;
+
+  const failures = new Map();
+
+  return {
+    middleware: (req, res, next) => {
+      const key = req.ip || req.connection.remoteAddress || 'unknown';
+      const data = failures.get(key);
+
+      if (data && data.count >= maxFailures && Date.now() - data.firstFailure < windowMs) {
+        return res.status(429).json({
+          error: message,
+          retryAfter: Math.ceil((data.firstFailure + windowMs - Date.now()) / 1000)
+        });
+      }
+
+      next();
+    },
+
+    recordFailure: (req) => {
+      const key = req.ip || req.connection.remoteAddress || 'unknown';
+      const now = Date.now();
+      let data = failures.get(key);
+
+      if (!data || now - data.firstFailure > windowMs) {
+        data = { count: 1, firstFailure: now };
+      } else {
+        data.count++;
+      }
+
+      failures.set(key, data);
+    },
+
+    clearFailures: (req) => {
+      const key = req.ip || req.connection.remoteAddress || 'unknown';
+      failures.delete(key);
+    }
+  };
+}
+
+export default { createRateLimiter, createFailureLimiter };

package/websocket.js

@@ -0,0 +1,282 @@
+/**
+ * AAP WebSocket Server v2.7
+ * 
+ * Sequential challenge delivery over persistent connection.
+ * Humans cannot preview questions - each arrives with strict time limit.
+ */
+
+import { WebSocketServer } from 'ws';
+import { randomBytes, createVerify } from 'node:crypto';
+import { generate as generateChallenge, getTypes } from './challenges.js';
+
+// Constants
+const CHALLENGE_COUNT = 7;
+const TIME_PER_CHALLENGE_MS = 1200;  // 1.2 seconds per challenge
+const CONNECTION_TIMEOUT_MS = 15000; // 15 seconds total
+const PROTOCOL_VERSION = '2.7.0';
+
+/**
+ * Create AAP WebSocket server
+ * @param {Object} options
+ * @param {number} [options.port] - Standalone port (if no httpServer)
+ * @param {Object} [options.httpServer] - Existing HTTP server
+ * @param {string} [options.path='/aap'] - WebSocket path
+ * @param {Function} [options.onVerified] - Callback on successful verification
+ * @param {Function} [options.onFailed] - Callback on failed verification
+ */
+export function createAAPWebSocket(options = {}) {
+  const {
+    port,
+    httpServer,
+    path = '/aap',
+    onVerified = null,
+    onFailed = null,
+    challengeCount = CHALLENGE_COUNT,
+    timePerChallengeMs = TIME_PER_CHALLENGE_MS
+  } = options;
+
+  const wssOptions = httpServer 
+    ? { server: httpServer, path }
+    : { port, path };
+  
+  const wss = new WebSocketServer(wssOptions);
+  
+  // Track active sessions
+  const sessions = new Map();
+
+  wss.on('connection', (ws, req) => {
+    const sessionId = randomBytes(16).toString('hex');
+    const nonce = randomBytes(16).toString('hex');
+    const startTime = Date.now();
+    
+    const session = {
+      id: sessionId,
+      nonce,
+      ws,
+      startTime,
+      currentChallenge: 0,
+      challenges: [],
+      validators: [],
+      answers: [],
+      timings: [],
+      publicKey: null,
+      publicId: null,
+      challengeStartTime: null,
+      timeout: null,
+      connectionTimeout: null
+    };
+    
+    sessions.set(sessionId, session);
+    
+    // Connection timeout
+    session.connectionTimeout = setTimeout(() => {
+      sendError(ws, 'Connection timeout');
+      ws.close();
+    }, CONNECTION_TIMEOUT_MS);
+    
+    // Generate all challenges upfront (but send one at a time)
+    const types = getTypes();
+    for (let i = 0; i < challengeCount; i++) {
+      const type = types[i % types.length];
+      const challenge = generateChallenge(nonce + i, type);
+      session.challenges.push({
+        id: i,
+        type,
+        challenge_string: challenge.challenge_string
+      });
+      session.validators.push(challenge.validate);
+    }
+    
+    // Send handshake
+    send(ws, {
+      type: 'handshake',
+      sessionId,
+      nonce,
+      protocol: 'AAP',
+      version: PROTOCOL_VERSION,
+      mode: 'websocket',
+      challengeCount,
+      timePerChallengeMs,
+      message: 'Connected. Send "ready" with publicKey to begin.'
+    });
+    
+    ws.on('message', (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        handleMessage(session, msg, { onVerified, onFailed, timePerChallengeMs });
+      } catch (e) {
+        sendError(ws, 'Invalid JSON');
+      }
+    });
+    
+    ws.on('close', () => {
+      clearTimeout(session.timeout);
+      clearTimeout(session.connectionTimeout);
+      sessions.delete(sessionId);
+    });
+    
+    ws.on('error', () => {
+      sessions.delete(sessionId);
+    });
+  });
+
+  return {
+    wss,
+    sessions,
+    close: () => wss.close()
+  };
+}
+
+function send(ws, data) {
+  if (ws.readyState === 1) { // OPEN
+    ws.send(JSON.stringify(data));
+  }
+}
+
+function sendError(ws, message, code = 'ERROR') {
+  send(ws, { type: 'error', code, message });
+}
+
+function handleMessage(session, msg, options) {
+  const { ws, currentChallenge, challenges, validators, answers, timings } = session;
+  const { onVerified, onFailed, timePerChallengeMs } = options;
+
+  switch (msg.type) {
+    case 'ready':
+      // Client ready to start, optionally provides identity
+      if (currentChallenge !== 0) {
+        sendError(ws, 'Already started');
+        return;
+      }
+      
+      session.publicKey = msg.publicKey || null;
+      session.publicId = msg.publicId || null;
+      
+      // Send first challenge
+      sendNextChallenge(session, timePerChallengeMs);
+      break;
+      
+    case 'answer':
+      // Client submitting answer
+      if (session.challengeStartTime === null) {
+        sendError(ws, 'No active challenge');
+        return;
+      }
+      
+      const responseTime = Date.now() - session.challengeStartTime;
+      clearTimeout(session.timeout);
+      
+      // Check if too slow
+      if (responseTime > timePerChallengeMs) {
+        send(ws, {
+          type: 'timeout',
+          challengeId: currentChallenge,
+          responseTimeMs: responseTime,
+          limit: timePerChallengeMs
+        });
+        finishSession(session, false, 'Too slow on challenge ' + currentChallenge, { onVerified, onFailed });
+        return;
+      }
+      
+      // Record answer and timing
+      answers.push(msg.answer);
+      timings.push(responseTime);
+      
+      // Validate immediately
+      const valid = validators[currentChallenge](msg.answer);
+      
+      send(ws, {
+        type: 'ack',
+        challengeId: currentChallenge,
+        responseTimeMs: responseTime,
+        valid  // Real-time feedback
+      });
+      
+      session.currentChallenge++;
+      
+      // More challenges?
+      if (session.currentChallenge < challenges.length) {
+        // Small delay then next challenge
+        setTimeout(() => sendNextChallenge(session, timePerChallengeMs), 100);
+      } else {
+        // All done - calculate result
+        const passed = answers.filter((_, i) => validators[i](answers[i])).length;
+        const allPassed = passed === challenges.length;
+        const totalTime = Date.now() - session.startTime;
+        
+        finishSession(session, allPassed, allPassed ? 'Verified' : `Failed: ${passed}/${challenges.length}`, {
+          onVerified,
+          onFailed,
+          passed,
+          total: challenges.length,
+          timings,
+          totalTime
+        });
+      }
+      break;
+      
+    default:
+      sendError(ws, 'Unknown message type: ' + msg.type);
+  }
+}
+
+function sendNextChallenge(session, timePerChallengeMs) {
+  const { ws, currentChallenge, challenges } = session;
+  const challenge = challenges[currentChallenge];
+  
+  session.challengeStartTime = Date.now();
+  
+  send(ws, {
+    type: 'challenge',
+    id: currentChallenge,
+    total: challenges.length,
+    challenge: challenge.challenge_string,
+    timeLimit: timePerChallengeMs
+  });
+  
+  // Timeout for this challenge
+  session.timeout = setTimeout(() => {
+    send(ws, {
+      type: 'timeout',
+      challengeId: currentChallenge,
+      message: 'Time expired'
+    });
+    finishSession(session, false, 'Timeout on challenge ' + currentChallenge, {});
+  }, timePerChallengeMs + 100); // Small grace period for network
+}
+
+function finishSession(session, success, message, options) {
+  const { ws, nonce, publicId, startTime } = session;
+  const { onVerified, onFailed, passed, total, timings, totalTime } = options;
+  
+  clearTimeout(session.timeout);
+  clearTimeout(session.connectionTimeout);
+  
+  const result = {
+    type: 'result',
+    verified: success,
+    nonce,
+    publicId,
+    message,
+    passed,
+    total,
+    timings,
+    totalTimeMs: totalTime || (Date.now() - startTime),
+    avgResponseMs: timings?.length ? Math.round(timings.reduce((a, b) => a + b, 0) / timings.length) : null
+  };
+  
+  if (success) {
+    result.role = 'AI_AGENT';
+    result.sessionToken = randomBytes(32).toString('hex');
+    if (onVerified) onVerified(result, session);
+  } else {
+    if (onFailed) onFailed(result, session);
+  }
+  
+  send(ws, result);
+  
+  // Close after sending result
+  setTimeout(() => ws.close(), 500);
+}
+
+export default { createAAPWebSocket };