aap-agent-server 2.0.0

package/README.md

@@ -0,0 +1,177 @@
+# @aap/server
+
+Server middleware for Agent Attestation Protocol verification.
+
+## Installation
+
+```bash
+npm install @aap/server @aap/core
+```
+
+## Quick Start
+
+### Express Integration
+
+```javascript
+import express from 'express';
+import { createRouter } from '@aap/server';
+
+const app = express();
+
+// Add AAP verification endpoints at /aap/v1
+app.use('/aap/v1', createRouter());
+
+app.listen(3000, () => {
+  console.log('AAP Verifier running on http://localhost:3000');
+});
+```
+
+This adds three endpoints:
+- `GET /aap/v1/health` - Health check
+- `POST /aap/v1/challenge` - Request a challenge
+- `POST /aap/v1/verify` - Submit proof for verification
+
+### Custom Configuration
+
+```javascript
+import express from 'express';
+import { aapMiddleware } from '@aap/server';
+
+const app = express();
+const router = express.Router();
+router.use(express.json());
+
+// Configure middleware
+const middleware = aapMiddleware({
+  challengeExpiryMs: 60000,  // 60 seconds
+  maxResponseTimeMs: 2000,   // 2 seconds
+  
+  onVerified: (result, req) => {
+    console.log(`Agent ${result.publicId} verified!`);
+    // Store verified agent, grant access, etc.
+  },
+  
+  onFailed: (error, req) => {
+    console.log(`Verification failed: ${error.error}`);
+    // Log suspicious activity, rate limit, etc.
+  }
+});
+
+middleware(router);
+app.use('/aap/v1', router);
+```
+
+## API Reference
+
+### `createRouter(options?)`
+
+Creates a pre-configured Express router with AAP endpoints.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `challengeExpiryMs` | number | 30000 | Challenge expiration time |
+| `maxResponseTimeMs` | number | 1500 | Max response time for liveness check |
+| `onVerified` | function | - | Callback when verification succeeds |
+| `onFailed` | function | - | Callback when verification fails |
+
+### `aapMiddleware(options?)`
+
+Lower-level middleware factory for custom router setup.
+
+```javascript
+const middleware = aapMiddleware(options);
+middleware(yourRouter);
+```
+
+### Challenges
+
+```javascript
+import { challenges } from '@aap/server';
+
+// Get available types
+const types = challenges.getTypes();
+// ['poem', 'math', 'reverse', 'wordplay', 'description']
+
+// Generate a challenge
+const nonce = 'abc123...';
+const { type, challenge_string, validate } = challenges.generate(nonce);
+
+// Validate a solution
+const isValid = validate(solution);
+```
+
+## Endpoints
+
+### GET /health
+
+```json
+{
+  "status": "ok",
+  "protocol": "AAP",
+  "version": "1.0.0",
+  "challengeTypes": ["poem", "math", "reverse", "wordplay", "description"]
+}
+```
+
+### POST /challenge
+
+**Response:**
+```json
+{
+  "challenge_string": "Write a short 2-line poem...",
+  "nonce": "a1b2c3d4e5f6...",
+  "type": "poem",
+  "difficulty": 1,
+  "timestamp": 1706745600000,
+  "expiresAt": 1706745630000
+}
+```
+
+### POST /verify
+
+**Request:**
+```json
+{
+  "solution": "Code a1b2c3d4 flows...",
+  "signature": "MEUCIQDx...",
+  "publicKey": "-----BEGIN PUBLIC KEY-----...",
+  "publicId": "7306df1332e239783e88",
+  "nonce": "a1b2c3d4e5f6...",
+  "timestamp": 1706745601234,
+  "responseTimeMs": 342
+}
+```
+
+**Success Response:**
+```json
+{
+  "verified": true,
+  "role": "AI_AGENT",
+  "publicId": "7306df1332e239783e88",
+  "challengeType": "poem",
+  "checks": {
+    "challengeExists": true,
+    "notExpired": true,
+    "solutionExists": true,
+    "solutionValid": true,
+    "responseTimeValid": true,
+    "signatureValid": true
+  }
+}
+```
+
+## Challenge Types
+
+| Type | Description | Validation |
+|------|-------------|------------|
+| `poem` | Write poem with nonce | Contains nonce substring |
+| `math` | Solve math + include nonce | Correct answer + nonce |
+| `reverse` | Reverse string | Original + reversed |
+| `wordplay` | Acrostic from nonce | First letters match |
+| `description` | Describe AI + append code | Ends with `[nonce]` |
+
+## License
+
+MIT

package/challenges.js

@@ -0,0 +1,525 @@
+/**
+ * @aap/server - Challenge Generator v2.0
+ * 
+ * "Deterministic Instruction Following"
+ * - Natural language instructions (requires LLM to understand)
+ * - Deterministic answers (server knows the correct answer)
+ * 
+ * Principle: Instructions in natural language, but answers are verifiable.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Word pools for dynamic challenge generation
+ */
+const WORD_POOLS = {
+  animals: ['cat', 'dog', 'rabbit', 'tiger', 'lion', 'elephant', 'giraffe', 'penguin', 'eagle', 'shark'],
+  fruits: ['apple', 'banana', 'orange', 'grape', 'strawberry', 'watermelon', 'peach', 'kiwi', 'mango', 'cherry'],
+  colors: ['red', 'blue', 'yellow', 'green', 'purple', 'orange', 'pink', 'black', 'white', 'brown'],
+  countries: ['Korea', 'Japan', 'USA', 'UK', 'France', 'Germany', 'Australia', 'Canada', 'Brazil', 'India'],
+  verbs: ['runs', 'eats', 'sleeps', 'plays', 'works', 'studies', 'travels', 'cooks'],
+  adjectives: ['big', 'small', 'fast', 'slow', 'beautiful', 'cute', 'delicious', 'interesting']
+};
+
+/**
+ * Select random items from array using nonce as seed
+ */
+function seededSelect(arr, nonce, count, offset = 0) {
+  const seed = parseInt(nonce.slice(offset, offset + 4), 16);
+  const results = [];
+  const used = new Set();
+  
+  for (let i = 0; i < count && i < arr.length; i++) {
+    let idx = (seed + i * 7) % arr.length;
+    while (used.has(idx)) {
+      idx = (idx + 1) % arr.length;
+    }
+    used.add(idx);
+    results.push(arr[idx]);
+  }
+  return results;
+}
+
+/**
+ * Generate a random number from nonce
+ */
+function seededNumber(nonce, offset, min, max) {
+  const seed = parseInt(nonce.slice(offset, offset + 4), 16);
+  return (seed % (max - min + 1)) + min;
+}
+
+/**
+ * Challenge type definitions
+ */
+export const CHALLENGE_TYPES = {
+  /**
+   * Extract entities from natural language sentence
+   */
+  nlp_extract: {
+    generate: (nonce) => {
+      const category = ['animals', 'fruits', 'colors'][parseInt(nonce[0], 16) % 3];
+      const pool = WORD_POOLS[category];
+      const targets = seededSelect(pool, nonce, 2, 0);
+      const verb = seededSelect(WORD_POOLS.verbs, nonce, 1, 4)[0];
+      
+      const sentence = `The ${targets[0]} and ${targets[1]} ${verb} in the park.`;
+      
+      return {
+        challenge_string: `Extract only the ${category} from the following sentence and respond as a JSON array.
+Sentence: "${sentence}"
+Response format: {"items": ["item1", "item2"]}`,
+        expected: targets.sort(),
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            const items = (obj.items || obj.animals || obj.fruits || obj.colors || []).map(s => s.toLowerCase()).sort();
+            return JSON.stringify(items) === JSON.stringify(targets.map(s => s.toLowerCase()).sort());
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * Math problem expressed in natural language
+   */
+  nlp_math: {
+    generate: (nonce) => {
+      const a = seededNumber(nonce, 0, 10, 50);
+      const b = seededNumber(nonce, 2, 5, 20);
+      const c = seededNumber(nonce, 4, 2, 5);
+      
+      const templates = [
+        {
+          text: `Subtract ${b} from ${a}, then multiply the result by ${c}.`,
+          answer: (a - b) * c
+        },
+        {
+          text: `Add ${a} and ${b} together, then divide by ${c}.`,
+          answer: (a + b) / c
+        },
+        {
+          text: `Divide ${a} by ${c}, then add ${b} to the result.`,
+          answer: a / c + b
+        }
+      ];
+      
+      const template = templates[parseInt(nonce[6], 16) % templates.length];
+      const expected = Math.round(template.answer * 100) / 100;
+      
+      return {
+        challenge_string: `${template.text}
+Response format: {"result": number}`,
+        expected,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            const result = parseFloat(obj.result);
+            return Math.abs(result - expected) < 0.01;
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * String transformation described in natural language
+   */
+  nlp_transform: {
+    generate: (nonce) => {
+      const input = nonce.slice(0, 6);
+      const transformType = parseInt(nonce[6], 16) % 4;
+      
+      let instruction, expected;
+      
+      switch (transformType) {
+        case 0:
+          instruction = `Reverse the string "${input}" and convert it to uppercase.`;
+          expected = input.split('').reverse().join('').toUpperCase();
+          break;
+        case 1:
+          instruction = `Extract only the digits from "${input}" and calculate their sum.`;
+          expected = input.split('').filter(c => /\d/.test(c)).reduce((a, b) => a + parseInt(b), 0);
+          break;
+        case 2:
+          instruction = `Extract only the letters from "${input}" and sort them alphabetically.`;
+          expected = input.split('').filter(c => /[a-zA-Z]/.test(c)).sort().join('');
+          break;
+        case 3:
+          instruction = `Insert a hyphen "-" between each character of "${input}".`;
+          expected = input.split('').join('-');
+          break;
+      }
+      
+      return {
+        challenge_string: `${instruction}
+Response format: {"output": "result"}`,
+        expected,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            const output = String(obj.output);
+            return output === String(expected) || output.toLowerCase() === String(expected).toLowerCase();
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * Conditional logic
+   */
+  nlp_logic: {
+    generate: (nonce) => {
+      const a = seededNumber(nonce, 0, 10, 100);
+      const b = seededNumber(nonce, 2, 10, 100);
+      const threshold = seededNumber(nonce, 4, 20, 80);
+      
+      const templates = [
+        {
+          text: `If the larger number between ${a} and ${b} is greater than ${threshold}, answer "YES". Otherwise, answer "NO".`,
+          answer: Math.max(a, b) > threshold ? "YES" : "NO"
+        },
+        {
+          text: `If the sum of ${a} and ${b} is less than ${threshold * 2}, answer "SMALL". Otherwise, answer "LARGE".`,
+          answer: (a + b) < (threshold * 2) ? "SMALL" : "LARGE"
+        },
+        {
+          text: `If ${a} is even and ${b} is odd, answer "MIXED". Otherwise, answer "SAME".`,
+          answer: (a % 2 === 0 && b % 2 === 1) ? "MIXED" : "SAME"
+        }
+      ];
+      
+      const template = templates[parseInt(nonce[6], 16) % templates.length];
+      
+      return {
+        challenge_string: `${template.text}
+Response format: {"answer": "your answer"}`,
+        expected: template.answer,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            return obj.answer?.toUpperCase() === template.answer.toUpperCase();
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * Counting task
+   */
+  nlp_count: {
+    generate: (nonce) => {
+      const category = ['animals', 'fruits', 'colors'][parseInt(nonce[0], 16) % 3];
+      const pool = WORD_POOLS[category];
+      const count1 = seededNumber(nonce, 0, 2, 4);
+      const count2 = seededNumber(nonce, 2, 1, 3);
+      
+      const items1 = seededSelect(pool, nonce, count1, 0);
+      const items2 = seededSelect(WORD_POOLS.countries, nonce, count2, 8);
+      
+      // Create sentence with mixed items
+      const allItems = [...items1, ...items2].sort(() => 
+        parseInt(nonce.slice(10, 12), 16) % 2 - 0.5
+      );
+      const sentence = `I see ${allItems.join(', ')} in the picture.`;
+      
+      return {
+        challenge_string: `Count only the ${category} in the following sentence.
+Sentence: "${sentence}"
+Response format: {"count": number}`,
+        expected: count1,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            return parseInt(obj.count) === count1;
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * Multi-step instruction following
+   */
+  nlp_multistep: {
+    generate: (nonce) => {
+      const numbers = [
+        seededNumber(nonce, 0, 1, 9),
+        seededNumber(nonce, 2, 1, 9),
+        seededNumber(nonce, 4, 1, 9),
+        seededNumber(nonce, 6, 1, 9)
+      ];
+      
+      // Step 1: Sum all
+      const sum = numbers.reduce((a, b) => a + b, 0);
+      // Step 2: Multiply by smallest
+      const min = Math.min(...numbers);
+      const step2 = sum * min;
+      // Step 3: Subtract largest
+      const max = Math.max(...numbers);
+      const final = step2 - max;
+      
+      return {
+        challenge_string: `Follow these instructions in order:
+1. Add all the numbers in [${numbers.join(', ')}] together.
+2. Multiply the result by the smallest number.
+3. Subtract the largest number from that result.
+Response format: {"result": final_value}`,
+        expected: final,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            return parseInt(obj.result) === final;
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * Pattern recognition and completion
+   */
+  nlp_pattern: {
+    generate: (nonce) => {
+      const start = seededNumber(nonce, 0, 1, 10);
+      const step = seededNumber(nonce, 2, 2, 5);
+      const patternType = parseInt(nonce[4], 16) % 3;
+      
+      let sequence, next2, instruction;
+      
+      switch (patternType) {
+        case 0: // Arithmetic
+          sequence = [start, start + step, start + step * 2, start + step * 3];
+          next2 = [start + step * 4, start + step * 5];
+          instruction = `Find the pattern and provide the next 2 numbers: [${sequence.join(', ')}, ?, ?]`;
+          break;
+        case 1: // Geometric (doubling)
+          sequence = [start, start * 2, start * 4, start * 8];
+          next2 = [start * 16, start * 32];
+          instruction = `Find the pattern and provide the next 2 numbers: [${sequence.join(', ')}, ?, ?]`;
+          break;
+        case 2: // Fibonacci-like
+          sequence = [start, step, start + step, step + (start + step)];
+          next2 = [sequence[2] + sequence[3], sequence[3] + (sequence[2] + sequence[3])];
+          instruction = `Find the pattern and provide the next 2 numbers: [${sequence.join(', ')}, ?, ?]`;
+          break;
+      }
+      
+      return {
+        challenge_string: `${instruction}
+Response format: {"next": [number1, number2]}`,
+        expected: next2,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            const next = obj.next;
+            return Array.isArray(next) && 
+                   parseInt(next[0]) === next2[0] && 
+                   parseInt(next[1]) === next2[1];
+          } catch { return false; }
+        }
+      };
+    }
+  },
+
+  /**
+   * Text analysis - find specific properties
+   */
+  nlp_analysis: {
+    generate: (nonce) => {
+      const words = seededSelect([...WORD_POOLS.animals, ...WORD_POOLS.fruits], nonce, 5, 0);
+      const analysisType = parseInt(nonce[8], 16) % 3;
+      
+      let instruction, expected;
+      const wordList = words.join(', ');
+      
+      switch (analysisType) {
+        case 0: // Longest word
+          expected = words.reduce((a, b) => a.length >= b.length ? a : b);
+          instruction = `Find the longest word from the following list: ${wordList}`;
+          break;
+        case 1: // Shortest word
+          expected = words.reduce((a, b) => a.length <= b.length ? a : b);
+          instruction = `Find the shortest word from the following list: ${wordList}`;
+          break;
+        case 2: // First alphabetically
+          expected = [...words].sort()[0];
+          instruction = `Find the word that comes first alphabetically from the following list: ${wordList}`;
+          break;
+      }
+      
+      return {
+        challenge_string: `${instruction}
+Response format: {"answer": "word"}`,
+        expected,
+        validate: (solution) => {
+          try {
+            const match = solution.match(/\{[\s\S]*\}/);
+            if (!match) return false;
+            const obj = JSON.parse(match[0]);
+            return obj.answer?.toLowerCase() === expected.toLowerCase();
+          } catch { return false; }
+        }
+      };
+    }
+  }
+};
+
+// ============== Protocol Constants ==============
+
+/**
+ * Batch challenge settings
+ */
+export const BATCH_SIZE = 3;              // Number of challenges per batch
+export const MAX_RESPONSE_TIME_MS = 12000; // 12 seconds for batch (avg 4s per challenge)
+export const CHALLENGE_EXPIRY_MS = 60000;  // 60 seconds
+
+/**
+ * Get list of available challenge types
+ * @returns {string[]}
+ */
+export function getTypes() {
+  return Object.keys(CHALLENGE_TYPES);
+}
+
+/**
+ * Generate a single random challenge
+ * @param {string} nonce - The nonce to incorporate
+ * @param {string} [type] - Specific type (random if not specified)
+ * @returns {Object} { type, challenge_string, validate, expected }
+ */
+export function generate(nonce, type) {
+  const types = getTypes();
+  const selectedType = type && types.includes(type) 
+    ? type 
+    : types[Math.floor(Math.random() * types.length)];
+  
+  const generator = CHALLENGE_TYPES[selectedType];
+  const result = generator.generate(nonce);
+  
+  return {
+    type: selectedType,
+    challenge_string: result.challenge_string,
+    validate: result.validate,
+    expected: result.expected  // For debugging only
+  };
+}
+
+/**
+ * Generate a batch of challenges
+ * @param {string} nonce - Base nonce
+ * @param {number} [count=BATCH_SIZE] - Number of challenges
+ * @returns {Object} { challenges: [...], validators: [...] }
+ */
+export function generateBatch(nonce, count = BATCH_SIZE) {
+  const types = getTypes();
+  const usedTypes = new Set();
+  const challenges = [];
+  const validators = [];
+  const expected = [];
+  
+  for (let i = 0; i < count; i++) {
+    // Use different nonce offset for each challenge
+    const offsetNonce = nonce.slice(i * 2) + nonce.slice(0, i * 2);
+    
+    // Select different type for each challenge
+    let selectedType;
+    do {
+      const seed = parseInt(offsetNonce.slice(0, 4), 16);
+      selectedType = types[(seed + i * 3) % types.length];
+    } while (usedTypes.has(selectedType) && usedTypes.size < types.length);
+    usedTypes.add(selectedType);
+    
+    const generator = CHALLENGE_TYPES[selectedType];
+    const result = generator.generate(offsetNonce);
+    
+    challenges.push({
+      id: i,
+      type: selectedType,
+      challenge_string: result.challenge_string
+    });
+    
+    validators.push(result.validate);
+    expected.push(result.expected);
+  }
+  
+  return {
+    challenges,
+    validators,  // Keep on server, don't send to client
+    expected     // For debugging
+  };
+}
+
+/**
+ * Validate batch solutions
+ * @param {Array} validators - Validator functions from generateBatch
+ * @param {Array} solutions - Array of solutions from client
+ * @returns {Object} { passed, total, results: [{id, valid}] }
+ */
+export function validateBatch(validators, solutions) {
+  const results = [];
+  let passed = 0;
+  
+  for (let i = 0; i < validators.length; i++) {
+    const solution = solutions[i];
+    const valid = solution && validators[i](
+      typeof solution === 'string' ? solution : JSON.stringify(solution)
+    );
+    
+    results.push({ id: i, valid });
+    if (valid) passed++;
+  }
+  
+  return {
+    passed,
+    total: validators.length,
+    allPassed: passed === validators.length,
+    results
+  };
+}
+
+/**
+ * Validate a single solution against a challenge
+ * @param {string} type - Challenge type
+ * @param {string} nonce - Original nonce
+ * @param {string} solution - Agent's solution
+ * @returns {boolean}
+ */
+export function validate(type, nonce, solution) {
+  const generator = CHALLENGE_TYPES[type];
+  if (!generator) {
+    return false;
+  }
+  
+  const { validate: validateFn } = generator.generate(nonce);
+  return validateFn(solution);
+}
+
+export default {
+  CHALLENGE_TYPES,
+  BATCH_SIZE,
+  MAX_RESPONSE_TIME_MS,
+  CHALLENGE_EXPIRY_MS,
+  getTypes,
+  generate,
+  generateBatch,
+  validateBatch,
+  validate
+};

package/errors.js

@@ -0,0 +1,134 @@
+/**
+ * AAP Server - Error Definitions
+ * 
+ * Consistent, client-friendly error messages
+ */
+
+export const ErrorCodes = {
+  // Challenge errors
+  CHALLENGE_NOT_FOUND: 'CHALLENGE_NOT_FOUND',
+  CHALLENGE_EXPIRED: 'CHALLENGE_EXPIRED',
+  CHALLENGE_ALREADY_USED: 'CHALLENGE_ALREADY_USED',
+  
+  // Solution errors
+  MISSING_SOLUTIONS: 'MISSING_SOLUTIONS',
+  INVALID_SOLUTIONS_COUNT: 'INVALID_SOLUTIONS_COUNT',
+  SOLUTION_VALIDATION_FAILED: 'SOLUTION_VALIDATION_FAILED',
+  
+  // Timing errors
+  RESPONSE_TOO_SLOW: 'RESPONSE_TOO_SLOW',
+  
+  // Signature errors
+  INVALID_SIGNATURE: 'INVALID_SIGNATURE',
+  MISSING_SIGNATURE: 'MISSING_SIGNATURE',
+  INVALID_PUBLIC_KEY: 'INVALID_PUBLIC_KEY',
+  
+  // General errors
+  INVALID_REQUEST: 'INVALID_REQUEST',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  RATE_LIMITED: 'RATE_LIMITED'
+};
+
+export const ErrorMessages = {
+  [ErrorCodes.CHALLENGE_NOT_FOUND]: {
+    message: 'Challenge not found',
+    hint: 'Request a new challenge via POST /challenge',
+    status: 400
+  },
+  [ErrorCodes.CHALLENGE_EXPIRED]: {
+    message: 'Challenge has expired',
+    hint: 'Challenges expire after 60 seconds. Request a new one.',
+    status: 400
+  },
+  [ErrorCodes.CHALLENGE_ALREADY_USED]: {
+    message: 'Challenge already used',
+    hint: 'Each challenge can only be used once. Request a new one.',
+    status: 400
+  },
+  [ErrorCodes.MISSING_SOLUTIONS]: {
+    message: 'Missing solutions array',
+    hint: 'Include "solutions" array in request body',
+    status: 400
+  },
+  [ErrorCodes.INVALID_SOLUTIONS_COUNT]: {
+    message: 'Invalid number of solutions',
+    hint: 'Provide exactly 3 solutions for batch challenges',
+    status: 400
+  },
+  [ErrorCodes.SOLUTION_VALIDATION_FAILED]: {
+    message: 'Solution validation failed (Proof of Intelligence)',
+    hint: 'One or more solutions are incorrect. Ensure your LLM correctly solves each challenge.',
+    status: 400
+  },
+  [ErrorCodes.RESPONSE_TOO_SLOW]: {
+    message: 'Response too slow (Proof of Liveness failed)',
+    hint: 'Response must arrive within 12 seconds for batch challenges',
+    status: 400
+  },
+  [ErrorCodes.INVALID_SIGNATURE]: {
+    message: 'Invalid signature (Proof of Identity failed)',
+    hint: 'Ensure you sign the correct data with your private key',
+    status: 400
+  },
+  [ErrorCodes.MISSING_SIGNATURE]: {
+    message: 'Missing signature',
+    hint: 'Include "signature" field with Base64-encoded ECDSA signature',
+    status: 400
+  },
+  [ErrorCodes.INVALID_PUBLIC_KEY]: {
+    message: 'Invalid public key',
+    hint: 'Public key must be PEM-encoded secp256k1 key',
+    status: 400
+  },
+  [ErrorCodes.INVALID_REQUEST]: {
+    message: 'Invalid request format',
+    hint: 'Check the API documentation for required fields',
+    status: 400
+  },
+  [ErrorCodes.INTERNAL_ERROR]: {
+    message: 'Internal server error',
+    hint: 'Please try again later',
+    status: 500
+  },
+  [ErrorCodes.RATE_LIMITED]: {
+    message: 'Too many requests',
+    hint: 'Please wait before making more requests',
+    status: 429
+  }
+};
+
+/**
+ * Create an error response
+ * @param {string} code - Error code from ErrorCodes
+ * @param {Object} [extra] - Additional fields to include
+ * @returns {Object} Error response object
+ */
+export function createError(code, extra = {}) {
+  const errorDef = ErrorMessages[code] || ErrorMessages[ErrorCodes.INTERNAL_ERROR];
+  
+  return {
+    verified: false,
+    error: errorDef.message,
+    code,
+    hint: errorDef.hint,
+    ...extra
+  };
+}
+
+/**
+ * Create error response with HTTP status
+ * @param {string} code - Error code
+ * @param {Object} res - Express response object
+ * @param {Object} [extra] - Additional fields
+ */
+export function sendError(code, res, extra = {}) {
+  const errorDef = ErrorMessages[code] || ErrorMessages[ErrorCodes.INTERNAL_ERROR];
+  res.status(errorDef.status).json(createError(code, extra));
+}
+
+export default {
+  ErrorCodes,
+  ErrorMessages,
+  createError,
+  sendError
+};

package/index.js

@@ -0,0 +1,20 @@
+/**
+ * @aap/server
+ * 
+ * Server-side utilities for Agent Attestation Protocol.
+ * Provides middleware and challenge generation for verification servers.
+ */
+
+export * from './middleware.js';
+export * from './challenges.js';
+
+import { aapMiddleware, createRouter } from './middleware.js';
+import challenges from './challenges.js';
+
+export { challenges };
+
+export default {
+  aapMiddleware,
+  createRouter,
+  challenges
+};

package/logger.js

@@ -0,0 +1,139 @@
+/**
+ * AAP Server - Logging Utilities
+ * 
+ * Safe logging that never exposes sensitive data
+ */
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+
+let currentLevel = LOG_LEVELS.info;
+
+/**
+ * Set the minimum log level
+ * @param {'debug'|'info'|'warn'|'error'} level
+ */
+export function setLogLevel(level) {
+  currentLevel = LOG_LEVELS[level] ?? LOG_LEVELS.info;
+}
+
+/**
+ * Sanitize data for safe logging
+ * Removes sensitive fields
+ */
+function sanitize(data) {
+  if (!data || typeof data !== 'object') return data;
+  
+  const sensitive = ['privateKey', 'private_key', 'apiKey', 'api_key', 'secret', 'password', 'token'];
+  const sanitized = { ...data };
+  
+  for (const key of sensitive) {
+    if (key in sanitized) {
+      sanitized[key] = '[REDACTED]';
+    }
+  }
+  
+  // Truncate long values
+  if (sanitized.publicKey && sanitized.publicKey.length > 50) {
+    sanitized.publicKey = sanitized.publicKey.slice(0, 50) + '...';
+  }
+  if (sanitized.signature && sanitized.signature.length > 50) {
+    sanitized.signature = sanitized.signature.slice(0, 50) + '...';
+  }
+  
+  return sanitized;
+}
+
+/**
+ * Format log message
+ */
+function format(level, message, data) {
+  const timestamp = new Date().toISOString();
+  const prefix = `[AAP ${level.toUpperCase()}] ${timestamp}`;
+  
+  if (data) {
+    return `${prefix} ${message} ${JSON.stringify(sanitize(data))}`;
+  }
+  return `${prefix} ${message}`;
+}
+
+/**
+ * Log debug message
+ */
+export function debug(message, data) {
+  if (currentLevel <= LOG_LEVELS.debug) {
+    console.debug(format('debug', message, data));
+  }
+}
+
+/**
+ * Log info message
+ */
+export function info(message, data) {
+  if (currentLevel <= LOG_LEVELS.info) {
+    console.info(format('info', message, data));
+  }
+}
+
+/**
+ * Log warning message
+ */
+export function warn(message, data) {
+  if (currentLevel <= LOG_LEVELS.warn) {
+    console.warn(format('warn', message, data));
+  }
+}
+
+/**
+ * Log error message
+ */
+export function error(message, data) {
+  if (currentLevel <= LOG_LEVELS.error) {
+    console.error(format('error', message, data));
+  }
+}
+
+/**
+ * Log verification attempt
+ */
+export function logVerification(result, req) {
+  const data = {
+    publicId: result.publicId,
+    verified: result.verified,
+    responseTimeMs: result.responseTimeMs,
+    batchPassed: result.batchResult?.passed,
+    batchTotal: result.batchResult?.total,
+    ip: req?.ip,
+    userAgent: req?.headers?.['user-agent']?.slice(0, 50)
+  };
+  
+  if (result.verified) {
+    info('Verification successful', data);
+  } else {
+    warn('Verification failed', { ...data, error: result.error });
+  }
+}
+
+/**
+ * Log challenge generation
+ */
+export function logChallenge(nonce, batchSize) {
+  debug('Challenge generated', { 
+    nonce: nonce.slice(0, 8) + '...', 
+    batchSize 
+  });
+}
+
+export default {
+  setLogLevel,
+  debug,
+  info,
+  warn,
+  error,
+  logVerification,
+  logChallenge
+};

package/middleware.js

@@ -0,0 +1,375 @@
+/**
+ * @aap/server - Express Middleware
+ * 
+ * Drop-in middleware for adding AAP verification to Express apps.
+ */
+
+import { verify, generateNonce, createProofData } from 'aap-agent-core';
+import { 
+  generate as generateChallenge, 
+  generateBatch,
+  validateBatch,
+  getTypes, 
+  validate as validateSolution, 
+  BATCH_SIZE,
+  MAX_RESPONSE_TIME_MS, 
+  CHALLENGE_EXPIRY_MS 
+} from './challenges.js';
+
+/**
+ * Create AAP verification middleware/router
+ * 
+ * @param {Object} [options]
+ * @param {number} [options.challengeExpiryMs=60000] - Challenge expiration time
+ * @param {number} [options.maxResponseTimeMs=12000] - Max response time for batch
+ * @param {number} [options.batchSize=3] - Number of challenges per batch
+ * @param {number} [options.minPassCount] - Minimum challenges to pass (default: all)
+ * @param {Function} [options.onVerified] - Callback when agent is verified
+ * @param {Function} [options.onFailed] - Callback when verification fails
+ * @returns {Function} Express router
+ */
+export function aapMiddleware(options = {}) {
+  const {
+    challengeExpiryMs = CHALLENGE_EXPIRY_MS,
+    maxResponseTimeMs = MAX_RESPONSE_TIME_MS,
+    batchSize = BATCH_SIZE,
+    minPassCount = null,  // null = all must pass
+    onVerified,
+    onFailed
+  } = options;
+
+  // In-memory challenge store
+  const challenges = new Map();
+
+  // Cleanup expired challenges periodically
+  const cleanup = () => {
+    const now = Date.now();
+    for (const [nonce, challenge] of challenges.entries()) {
+      if (now > challenge.expiresAt) {
+        challenges.delete(nonce);
+      }
+    }
+  };
+
+  // Return a function that creates routes
+  return (router) => {
+    /**
+     * GET /health - Health check
+     */
+    router.get('/health', (req, res) => {
+      res.json({
+        status: 'ok',
+        protocol: 'AAP',
+        version: '2.0.0',
+        mode: 'batch',
+        batchSize,
+        maxResponseTimeMs,
+        challengeTypes: getTypes(),
+        activeChallenges: challenges.size
+      });
+    });
+
+    /**
+     * POST /challenge - Request a batch of challenges
+     */
+    router.post('/challenge', (req, res) => {
+      cleanup();
+
+      const nonce = generateNonce();
+      const timestamp = Date.now();
+      const { challenges: batchChallenges, validators, expected } = generateBatch(nonce, batchSize);
+
+      const challengeData = {
+        nonce,
+        challenges: batchChallenges,
+        batchSize,
+        timestamp,
+        expiresAt: timestamp + challengeExpiryMs,
+        maxResponseTimeMs
+      };
+
+      // Store with validators (not sent to client)
+      challenges.set(nonce, { 
+        ...challengeData, 
+        validators,
+        expected  // For debugging
+      });
+
+      // Send without validators
+      res.json({
+        nonce,
+        challenges: batchChallenges,
+        batchSize,
+        timestamp,
+        expiresAt: challengeData.expiresAt,
+        maxResponseTimeMs
+      });
+    });
+
+    /**
+     * POST /verify - Verify agent's batch solutions
+     */
+    router.post('/verify', (req, res) => {
+      const {
+        solutions,
+        signature,
+        publicKey,
+        publicId,
+        nonce,
+        timestamp,
+        responseTimeMs
+      } = req.body;
+
+      const checks = {
+        challengeExists: false,
+        notExpired: false,
+        solutionsExist: false,
+        solutionsValid: false,
+        responseTimeValid: false,
+        signatureValid: false
+      };
+
+      try {
+        // Check 1: Challenge exists
+        const challenge = challenges.get(nonce);
+        if (!challenge) {
+          if (onFailed) onFailed({ error: 'Challenge not found', checks }, req);
+          return res.status(400).json({
+            verified: false,
+            error: 'Challenge not found or already used',
+            checks
+          });
+        }
+        checks.challengeExists = true;
+
+        // Remove challenge (one-time use)
+        const { validators, batchSize: size } = challenge;
+        challenges.delete(nonce);
+
+        // Check 2: Not expired
+        if (Date.now() > challenge.expiresAt) {
+          if (onFailed) onFailed({ error: 'Challenge expired', checks }, req);
+          return res.status(400).json({
+            verified: false,
+            error: 'Challenge expired',
+            checks
+          });
+        }
+        checks.notExpired = true;
+
+        // Check 3: Solutions exist
+        if (!solutions || !Array.isArray(solutions) || solutions.length !== size) {
+          if (onFailed) onFailed({ error: 'Invalid solutions array', checks }, req);
+          return res.status(400).json({
+            verified: false,
+            error: `Expected ${size} solutions, got ${solutions?.length || 0}`,
+            checks
+          });
+        }
+        checks.solutionsExist = true;
+
+        // Check 4: Validate all solutions (Proof of Intelligence)
+        const batchResult = validateBatch(validators, solutions);
+        const requiredPass = minPassCount || size;
+        
+        if (batchResult.passed < requiredPass) {
+          if (onFailed) onFailed({ error: 'Solutions validation failed', checks, batchResult }, req);
+          return res.status(400).json({
+            verified: false,
+            error: `Proof of Intelligence failed: ${batchResult.passed}/${size} correct (need ${requiredPass})`,
+            checks,
+            batchResult
+          });
+        }
+        checks.solutionsValid = true;
+
+        // Check 5: Response time (Proof of Liveness)
+        if (responseTimeMs > maxResponseTimeMs) {
+          if (onFailed) onFailed({ error: 'Response too slow', checks }, req);
+          return res.status(400).json({
+            verified: false,
+            error: `Response too slow: ${responseTimeMs}ms > ${maxResponseTimeMs}ms (Proof of Liveness failed)`,
+            checks
+          });
+        }
+        checks.responseTimeValid = true;
+
+        // Check 6: Signature (Proof of Identity)
+        // Sign over solutions array
+        const solutionsString = JSON.stringify(solutions);
+        const proofData = createProofData({ nonce, solution: solutionsString, publicId, timestamp });
+        if (!verify(proofData, signature, publicKey)) {
+          if (onFailed) onFailed({ error: 'Invalid signature', checks }, req);
+          return res.status(400).json({
+            verified: false,
+            error: 'Invalid signature (Proof of Identity failed)',
+            checks
+          });
+        }
+        checks.signatureValid = true;
+
+        // All checks passed
+        const result = {
+          verified: true,
+          role: 'AI_AGENT',
+          publicId,
+          batchResult,
+          responseTimeMs,
+          checks
+        };
+
+        if (onVerified) onVerified(result, req);
+
+        res.json(result);
+
+      } catch (error) {
+        if (onFailed) onFailed({ error: error.message, checks }, req);
+        res.status(500).json({
+          verified: false,
+          error: `Verification error: ${error.message}`,
+          checks
+        });
+      }
+    });
+
+    // ============== Legacy single-challenge endpoints ==============
+    
+    /**
+     * POST /challenge/single - Request a single challenge (legacy)
+     */
+    router.post('/challenge/single', (req, res) => {
+      cleanup();
+
+      const nonce = generateNonce();
+      const timestamp = Date.now();
+      const { type, challenge_string, validate } = generateChallenge(nonce);
+
+      const challenge = {
+        challenge_string,
+        nonce,
+        type,
+        difficulty: 1,
+        timestamp,
+        expiresAt: timestamp + challengeExpiryMs,
+        mode: 'single'
+      };
+
+      challenges.set(nonce, { ...challenge, validate });
+
+      res.json({
+        challenge_string,
+        nonce,
+        type,
+        difficulty: 1,
+        timestamp,
+        expiresAt: challenge.expiresAt,
+        mode: 'single',
+        maxResponseTimeMs: 10000  // 10s for single
+      });
+    });
+
+    /**
+     * POST /verify/single - Verify single challenge (legacy)
+     */
+    router.post('/verify/single', (req, res) => {
+      const {
+        solution,
+        signature,
+        publicKey,
+        publicId,
+        nonce,
+        timestamp,
+        responseTimeMs
+      } = req.body;
+
+      const checks = {
+        challengeExists: false,
+        notExpired: false,
+        solutionExists: false,
+        solutionValid: false,
+        responseTimeValid: false,
+        signatureValid: false
+      };
+
+      try {
+        const challenge = challenges.get(nonce);
+        if (!challenge || challenge.mode !== 'single') {
+          return res.status(400).json({
+            verified: false,
+            error: 'Single challenge not found',
+            checks
+          });
+        }
+        checks.challengeExists = true;
+
+        const { validate, type: challengeType } = challenge;
+        challenges.delete(nonce);
+
+        if (Date.now() > challenge.expiresAt) {
+          return res.status(400).json({ verified: false, error: 'Challenge expired', checks });
+        }
+        checks.notExpired = true;
+
+        if (!solution) {
+          return res.status(400).json({ verified: false, error: 'Missing solution', checks });
+        }
+        checks.solutionExists = true;
+
+        if (!validate(solution)) {
+          return res.status(400).json({ verified: false, error: 'Invalid solution', checks });
+        }
+        checks.solutionValid = true;
+
+        if (responseTimeMs > 10000) {
+          return res.status(400).json({ verified: false, error: 'Too slow', checks });
+        }
+        checks.responseTimeValid = true;
+
+        const proofData = createProofData({ nonce, solution, publicId, timestamp });
+        if (!verify(proofData, signature, publicKey)) {
+          return res.status(400).json({ verified: false, error: 'Invalid signature', checks });
+        }
+        checks.signatureValid = true;
+
+        res.json({
+          verified: true,
+          role: 'AI_AGENT',
+          publicId,
+          challengeType,
+          checks
+        });
+
+      } catch (error) {
+        res.status(500).json({ verified: false, error: error.message, checks });
+      }
+    });
+
+    return router;
+  };
+}
+
+/**
+ * Create a standalone AAP router for Express
+ * 
+ * @param {Object} [options] - Middleware options
+ * @returns {Router} Express router
+ * 
+ * @example
+ * import express from 'express';
+ * import { createRouter } from '@aap/server';
+ * 
+ * const app = express();
+ * app.use('/aap/v1', createRouter());
+ */
+export function createRouter(options = {}) {
+  const express = require('express');
+  const router = express.Router();
+  router.use(express.json());
+  
+  const middleware = aapMiddleware(options);
+  middleware(router);
+  
+  return router;
+}
+
+export default { aapMiddleware, createRouter };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "aap-agent-server",
+  "version": "2.0.0",
+  "description": "Server middleware for Agent Attestation Protocol - verify AI agents",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./middleware": "./middleware.js",
+    "./challenges": "./challenges.js"
+  },
+  "files": ["*.js", "README.md"],
+  "keywords": ["aap", "agent", "attestation", "verification", "middleware", "express", "ai"],
+  "author": "ira-hash",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ira-hash/agent-attestation-protocol.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/ira-hash/agent-attestation-protocol#readme",
+  "dependencies": {
+    "aap-agent-core": "^2.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}