@aamp/protocol 1.1.0

package/dist/test/handshake.spec.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Integration Test: Protocol Handshake
+ * Run using: npm test
+ * Location: sdk/typescript/test/handshake.spec.ts
+ */
+const agent_1 = require("../src/agent");
+const publisher_1 = require("../src/publisher");
+const types_1 = require("../src/types");
+function base64ToUint8Array(base64) {
+    const binaryString = atob(base64);
+    const len = binaryString.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}
+async function runTest() {
+    console.log("--- STARTING AAMP HANDSHAKE TEST ---");
+    // 1. Setup Publisher with Economic Policy
+    const publisher = new publisher_1.AAMPPublisher({
+        version: '1.1',
+        allowTraining: false,
+        allowRAG: true,
+        attributionRequired: true,
+        requiresPayment: true, // Publisher wants money...
+        allowAdSupportedAccess: true, // ...OR ads
+        paymentPointer: '$wallet.example.com/publisher'
+    });
+    // 2. Initialize Agent
+    const agent = new agent_1.AAMPAgent();
+    await agent.initialize();
+    // TEST CASE A: Requesting RAG without Ads (Should FAIL due to Payment Requirement)
+    console.log("\n[TEST A] Requesting RAG (No Ads)...");
+    const reqA = await agent.createAccessRequest('/doc/1', types_1.AccessPurpose.RAG_RETRIEVAL, { adsDisplayed: false });
+    // Fix: Cast to any to avoid TS2769 error (Uint8Array vs BufferSource mismatch in ts-node)
+    const keyA = await crypto.subtle.importKey("spki", base64ToUint8Array(reqA.publicKey), { name: "ECDSA", namedCurve: "P-256" }, true, ["verify"]);
+    const resA = await publisher.verifyRequest(reqA, keyA);
+    console.log("Result A (Expect Deny):", resA);
+    if (resA.allowed)
+        throw new Error("Test A Failed (Should require payment)");
+    // TEST CASE B: Requesting RAG WITH Ads (Should SUCCEED via Exemption)
+    console.log("\n[TEST B] Requesting RAG (With Ads)...");
+    const reqB = await agent.createAccessRequest('/doc/1', types_1.AccessPurpose.RAG_RETRIEVAL, { adsDisplayed: true });
+    const resB = await publisher.verifyRequest(reqB, keyA);
+    console.log("Result B (Expect Allow):", resB);
+    if (!resB.allowed)
+        throw new Error("Test B Failed (Should allow via Ad exemption)");
+    console.log("\n--- ALL TESTS PASSED ---");
+}
+runTest().catch(console.error);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@aamp/protocol",
+  "version": "1.1.0",
+  "description": "TypeScript reference implementation of AAMP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "ts-node test/handshake.spec.ts",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aamp-protocol/aamp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "ts-node": "^10.9.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,72 @@
+/**
+ * Layer 2: Agent SDK
+ */
+import { AccessPurpose, ProtocolHeader, SignedAccessRequest, FeedbackSignal, QualityFlag } from './types';
+import { generateKeyPair, signData, exportPublicKey } from './crypto';
+import { AAMP_VERSION } from './constants';
+
+export interface AccessOptions {
+  adsDisplayed?: boolean;
+}
+
+export class AAMPAgent {
+  private keyPair: CryptoKeyPair | null = null;
+  public agentId: string = "pending";
+
+  /**
+   * Initialize the Agent Identity (Ephemeral or Persisted)
+   * @param customAgentId Optional persistent ID for this agent. If omitted, generates a session ID.
+   */
+  async initialize(customAgentId?: string) {
+    this.keyPair = await generateKeyPair();
+    // Use the provided ID (authentic) or generate a session ID (ephemeral)
+    this.agentId = customAgentId || "agent_" + Math.random().toString(36).substring(7);
+  }
+
+  async createAccessRequest(
+    resource: string, 
+    purpose: AccessPurpose, 
+    options: AccessOptions = {}
+  ): Promise<SignedAccessRequest> {
+    if (!this.keyPair) throw new Error("Agent not initialized. Call initialize() first.");
+
+    const header: ProtocolHeader = {
+      v: AAMP_VERSION,
+      ts: new Date().toISOString(),
+      agent_id: this.agentId,
+      resource,
+      purpose,
+      context: {
+        ads_displayed: options.adsDisplayed || false
+      }
+    };
+
+    const signature = await signData(this.keyPair.privateKey, JSON.stringify(header));
+    const publicKeyExport = await exportPublicKey(this.keyPair.publicKey);
+
+    return { header, signature, publicKey: publicKeyExport };
+  }
+
+  /**
+   * NEW IN V1.1: Quality Feedback Loop
+   * Allows the Agent to report spam or verify quality of a resource.
+   */
+  async generateFeedback(
+    resource: string,
+    score: number,
+    flags: QualityFlag[]
+  ): Promise<{ signal: FeedbackSignal, signature: string }> {
+    if (!this.keyPair) throw new Error("Agent not initialized.");
+    
+    const signal: FeedbackSignal = {
+      target_resource: resource,
+      agent_id: this.agentId,
+      quality_score: Math.max(0, Math.min(1, score)),
+      flags,
+      timestamp: new Date().toISOString()
+    };
+
+    const signature = await signData(this.keyPair.privateKey, JSON.stringify(signal));
+    return { signal, signature };
+  }
+}

package/src/constants.ts

@@ -0,0 +1,35 @@
+/**
+ * Layer 1: Protocol Constants
+ * These values are immutable and defined by the AAMP Specification.
+ */
+
+export const AAMP_VERSION = '1.1';
+
+// HTTP Headers used for the handshake
+export const HEADERS = {
+  // Transport: The signed payload (Base64 encoded JSON of ProtocolHeader)
+  PAYLOAD: 'x-aamp-payload',
+  // Transport: The cryptographic signature (Hex)
+  SIGNATURE: 'x-aamp-signature',
+  // Transport: The Agent's Public Key (Base64 SPKI)
+  PUBLIC_KEY: 'x-aamp-public-key',
+  
+  // Informational / Legacy (Optional if Payload is present)
+  AGENT_ID: 'x-aamp-agent-id',
+  TIMESTAMP: 'x-aamp-timestamp',
+  ALGORITHM: 'x-aamp-alg', 
+  
+  // v1.1 Addition: Provenance (Server to Agent)
+  CONTENT_ORIGIN: 'x-aamp-content-origin',
+  PROVENANCE_SIG: 'x-aamp-provenance-sig'
+} as const;
+
+// Cryptographic Settings
+export const CRYPTO_CONFIG = {
+  ALGORITHM_NAME: 'ECDSA',
+  CURVE: 'P-256',
+  HASH: 'SHA-256',
+} as const;
+
+// Tolerance
+export const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000; // 5 minutes

package/src/crypto.ts

@@ -0,0 +1,53 @@
+/**
+ * Layer 1: Cryptographic Primitives
+ * Implementation of ECDSA P-256 signing/verification.
+ */
+
+export async function generateKeyPair(): Promise<CryptoKeyPair> {
+  // Uses standard Web Crypto API (Node 19+ compatible)
+  return await crypto.subtle.generateKey(
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["sign", "verify"]
+  );
+}
+
+export async function signData(privateKey: CryptoKey, data: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const encoded = encoder.encode(data);
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: { name: "SHA-256" } },
+    privateKey,
+    encoded as any
+  );
+  return bufToHex(signature);
+}
+
+export async function verifySignature(publicKey: CryptoKey, data: string, signatureHex: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const encodedData = encoder.encode(data);
+  const signatureBytes = hexToBuf(signatureHex);
+
+  return await crypto.subtle.verify(
+    { name: "ECDSA", hash: { name: "SHA-256" } },
+    publicKey,
+    signatureBytes as any,
+    encodedData as any
+  );
+}
+
+export async function exportPublicKey(key: CryptoKey): Promise<string> {
+  const exported = await crypto.subtle.exportKey("spki", key);
+  return btoa(String.fromCharCode(...new Uint8Array(exported)));
+}
+
+// Helpers
+function bufToHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function hexToBuf(hex: string): Uint8Array {
+  return new Uint8Array(hex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
+}

package/src/express.ts

@@ -0,0 +1,104 @@
+/**
+ * Layer 3: Framework Adapters
+ * Zero-friction integration for Express/Node.js.
+ */
+import { AAMPPublisher } from './publisher';
+import { AccessPolicy, ContentOrigin, SignedAccessRequest } from './types';
+import { generateKeyPair, verifySignature } from './crypto';
+import { HEADERS } from './constants';
+
+export interface AAMPConfig {
+  policy: Omit<AccessPolicy, 'version'>;
+  meta: {
+    origin: keyof typeof ContentOrigin;
+    paymentPointer?: string;
+  };
+}
+
+export class AAMP {
+  private publisher: AAMPPublisher;
+  private origin: ContentOrigin;
+  private ready: Promise<void>;
+
+  private constructor(config: AAMPConfig) {
+    this.publisher = new AAMPPublisher({
+      version: '1.1',
+      ...config.policy
+    } as AccessPolicy);
+    
+    this.origin = ContentOrigin[config.meta.origin];
+    
+    this.ready = generateKeyPair().then(keys => {
+      return this.publisher.initialize(keys);
+    });
+  }
+
+  static init(config: AAMPConfig): AAMP {
+    return new AAMP(config);
+  }
+
+  /**
+   * Express Middleware
+   */
+  middleware() {
+    return async (req: any, res: any, next: any) => {
+      await this.ready;
+
+      // 1. Inject Provenance Headers (Passive Protection)
+      const headers = await this.publisher.generateResponseHeaders(this.origin);
+      Object.entries(headers).forEach(([k, v]) => {
+        res.setHeader(k, v);
+      });
+
+      // 2. Active Verification (If Agent sends signed headers)
+      const payloadHeader = req.headers[HEADERS.PAYLOAD];
+      const sigHeader = req.headers[HEADERS.SIGNATURE];
+      const keyHeader = req.headers[HEADERS.PUBLIC_KEY];
+
+      if (payloadHeader && sigHeader && keyHeader) {
+        try {
+          const headerJson = atob(payloadHeader); // RAW STRING
+          const requestHeader = JSON.parse(headerJson);
+          
+          const signedRequest: SignedAccessRequest = {
+            header: requestHeader,
+            signature: sigHeader,
+            publicKey: keyHeader
+          };
+
+          const agentKey = await crypto.subtle.importKey(
+            "spki",
+            new Uint8Array(atob(keyHeader).split('').map(c => c.charCodeAt(0))),
+            { name: "ECDSA", namedCurve: "P-256" },
+            true,
+            ["verify"]
+          );
+
+          // Pass raw headerJson to ensure signature matches exactly what was signed
+          const result = await this.publisher.verifyRequest(signedRequest, agentKey, headerJson);
+
+          if (!result.allowed) {
+            res.status(403).json({ error: result.reason });
+            return;
+          }
+
+          // Verified!
+          req.aamp = { verified: true, ...requestHeader };
+
+        } catch (e) {
+          res.status(400).json({ error: "Invalid AAMP Signature" });
+          return;
+        }
+      }
+
+      next();
+    };
+  }
+
+  discoveryHandler() {
+    return (req: any, res: any) => {
+      res.setHeader('Content-Type', 'application/json');
+      res.send(JSON.stringify(this.publisher.getPolicy(), null, 2));
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * AAMP SDK Public API
+ * 
+ * This is the main entry point for the library.
+ */
+
+export * from './types';
+export * from './constants';
+export * from './agent';
+export * from './publisher';
+export * from './crypto';
+export * from './express'; // Node.js / Express Adapter
+export { AAMPNext } from './nextjs';  // Serverless / Next.js Adapter

package/src/nextjs.ts

@@ -0,0 +1,109 @@
+/**
+ * Layer 3: Framework Adapters
+ * Serverless integration for Next.js (App Router & API Routes).
+ */
+import { AAMPPublisher } from './publisher';
+import { AccessPolicy, ContentOrigin, SignedAccessRequest } from './types';
+import { generateKeyPair } from './crypto';
+import { HEADERS } from './constants';
+
+type NextRequest = any; 
+type NextResponse = any; 
+
+const createJsonResponse = (body: any, status = 200) => {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+};
+
+export interface AAMPConfig {
+  policy: Omit<AccessPolicy, 'version'>;
+  meta: {
+    origin: keyof typeof ContentOrigin;
+    paymentPointer?: string;
+  };
+}
+
+export class AAMPNext {
+  private publisher: AAMPPublisher;
+  private origin: ContentOrigin;
+  private ready: Promise<void>;
+
+  private constructor(config: AAMPConfig) {
+    this.publisher = new AAMPPublisher({
+      version: '1.1',
+      ...config.policy
+    } as AccessPolicy);
+    this.origin = ContentOrigin[config.meta.origin];
+    
+    this.ready = generateKeyPair().then(keys => this.publisher.initialize(keys));
+  }
+
+  static init(config: AAMPConfig): AAMPNext {
+    return new AAMPNext(config);
+  }
+
+  /**
+   * Serverless Route Wrapper
+   */
+  withProtection(handler: (req: NextRequest) => Promise<NextResponse>) {
+    return async (req: NextRequest) => {
+      await this.ready;
+
+      // 1. Active Verification
+      const payloadHeader = req.headers.get(HEADERS.PAYLOAD);
+      const sigHeader = req.headers.get(HEADERS.SIGNATURE);
+      const keyHeader = req.headers.get(HEADERS.PUBLIC_KEY);
+
+      if (payloadHeader && sigHeader && keyHeader) {
+        try {
+          const headerJson = atob(payloadHeader); // RAW STRING
+          const requestHeader = JSON.parse(headerJson);
+          
+          const signedRequest: SignedAccessRequest = {
+            header: requestHeader,
+            signature: sigHeader,
+            publicKey: keyHeader
+          };
+
+          const agentKey = await crypto.subtle.importKey(
+            "spki",
+            new Uint8Array(atob(keyHeader).split('').map(c => c.charCodeAt(0))),
+            { name: "ECDSA", namedCurve: "P-256" },
+            true,
+            ["verify"]
+          );
+
+          // Pass raw headerJson to ensure signature matches exactly what was signed
+          const result = await this.publisher.verifyRequest(signedRequest, agentKey, headerJson);
+
+          if (!result.allowed) {
+            return createJsonResponse({ error: result.reason }, 403);
+          }
+        } catch (e) {
+          return createJsonResponse({ error: "Invalid AAMP Signature" }, 400);
+        }
+      }
+
+      // 2. Execute Handler
+      const response = await handler(req);
+
+      // 3. Inject Provenance Headers (Passive)
+      const aampHeaders = await this.publisher.generateResponseHeaders(this.origin);
+      if (response && response.headers) {
+         Object.entries(aampHeaders).forEach(([k, v]) => {
+           response.headers.set(k, v);
+         });
+      }
+
+      return response;
+    };
+  }
+
+  discoveryHandler() {
+    return async () => {
+      return createJsonResponse(this.publisher.getPolicy());
+    };
+  }
+}

package/src/publisher.ts

@@ -0,0 +1,107 @@
+/**
+ * Layer 2: Publisher Middleware
+ * Used by content owners to enforce policy and log access.
+ */
+import { AccessPolicy, AccessPurpose, SignedAccessRequest, ContentOrigin, FeedbackSignal } from './types';
+import { verifySignature, signData } from './crypto';
+import { MAX_CLOCK_SKEW_MS, HEADERS } from './constants';
+
+export interface VerificationResult {
+  allowed: boolean;
+  reason: string;
+  responseHeaders?: Record<string, string>;
+}
+
+export class AAMPPublisher {
+  private policy: AccessPolicy;
+  private keyPair: CryptoKeyPair | null = null;
+  
+  constructor(policy: AccessPolicy) {
+    this.policy = policy;
+  }
+
+  // Publishers now need keys too, to sign their Content Origin declarations
+  async initialize(keyPair: CryptoKeyPair) {
+    this.keyPair = keyPair;
+  }
+
+  getPolicy(): AccessPolicy {
+    return this.policy;
+  }
+
+  /**
+   * Verifies an incoming AI access request.
+   * 
+   * @param request The parsed request object
+   * @param requestPublicKey The agent's public key
+   * @param rawPayload (Optional) The raw string received over the wire. REQUIRED for robust verification.
+   */
+  async verifyRequest(
+    request: SignedAccessRequest, 
+    requestPublicKey: CryptoKey,
+    rawPayload?: string
+  ): Promise<VerificationResult> {
+    
+    // 1. Replay Attack Prevention (Timestamp Check)
+    const requestTime = new Date(request.header.ts).getTime();
+    const now = Date.now();
+    if (Math.abs(now - requestTime) > MAX_CLOCK_SKEW_MS) {
+      return { allowed: false, reason: 'TIMESTAMP_INVALID: Clock skew exceeded.' };
+    }
+
+    // 2. Policy Enforcement (Usage Type)
+    // STRICT CHECK: Training
+    if (request.header.purpose === AccessPurpose.CRAWL_TRAINING && !this.policy.allowTraining) {
+      return { allowed: false, reason: 'POLICY_DENIED: Training not allowed by site owner.' };
+    }
+    // STRICT CHECK: RAG / Retrieval
+    if (request.header.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
+      return { allowed: false, reason: 'POLICY_DENIED: RAG Retrieval not allowed.' };
+    }
+
+    // 3. Economic Policy Enforcement
+    if (this.policy.requiresPayment) {
+      const isExemptViaAds = this.policy.allowAdSupportedAccess && request.header.context.ads_displayed;
+      
+      if (!isExemptViaAds) {
+        return { 
+          allowed: false, 
+          reason: 'PAYMENT_REQUIRED: Site requires payment or ad-supported access.' 
+        };
+      }
+    }
+
+    // 4. Cryptographic Verification (The "Proof")
+    // CRITICAL: We prefer the rawPayload if available to avoid JSON parsing/stringify mismatches.
+    const signableString = rawPayload || JSON.stringify(request.header);
+    
+    const isValid = await verifySignature(requestPublicKey, signableString, request.signature);
+
+    if (!isValid) {
+      return { allowed: false, reason: 'CRYPTO_FAIL: Signature verification failed.' };
+    }
+
+    return { allowed: true, reason: 'OK' };
+  }
+
+  /**
+   * Verifies a Feedback Signal (Spam Report) from an Agent.
+   * Part of the AAMP Immune System.
+   */
+  async verifyFeedback(signal: FeedbackSignal, signature: string, agentPublicKey: CryptoKey): Promise<boolean> {
+    const signableString = JSON.stringify(signal);
+    return await verifySignature(agentPublicKey, signableString, signature);
+  }
+
+  async generateResponseHeaders(origin: ContentOrigin): Promise<Record<string, string>> {
+    if (!this.keyPair) throw new Error("Publisher keys not initialized");
+
+    const payload = JSON.stringify({ origin, ts: Date.now() });
+    const signature = await signData(this.keyPair.privateKey, payload);
+
+    return {
+      [HEADERS.CONTENT_ORIGIN]: origin,
+      [HEADERS.PROVENANCE_SIG]: signature
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Layer 1: Protocol Definitions
+ * Shared types used by both Agent and Publisher.
+ */
+
+export enum AccessPurpose {
+  CRAWL_TRAINING = 'CRAWL_TRAINING',
+  RAG_RETRIEVAL = 'RAG_RETRIEVAL',
+  SUMMARY = 'SUMMARY',
+  QUOTATION = 'QUOTATION',
+  EMBEDDING = 'EMBEDDING'
+}
+
+export enum ContentOrigin {
+  HUMAN = 'HUMAN',         // Created by humans. High training value.
+  SYNTHETIC = 'SYNTHETIC', // Created by AI. Risk of model collapse.
+  HYBRID = 'HYBRID'        // Edited by humans, drafted by AI.
+}
+
+export enum QualityFlag {
+  SEO_SPAM = 'SEO_SPAM',
+  INACCURATE = 'INACCURATE',
+  HATE_SPEECH = 'HATE_SPEECH',
+  HIGH_QUALITY = 'HIGH_QUALITY'
+}
+
+/**
+ * Optional Rate Limiting (The Speed Limit)
+ * Defines technical boundaries for the handshake.
+ */
+export interface RateLimitConfig {
+  requestsPerMinute: number;
+  tokensPerMinute?: number;
+}
+
+/**
+ * Optional Monetization (The Settlement Layer)
+ * 
+ * AAMP is neutral. Settlement can happen via:
+ * 1. BROKER: A 3rd party clearing house (e.g., "AI-AdSense").
+ * 2. CRYPTO: Direct on-chain settlement.
+ * 3. TREATY: A private legal contract signed offline (Enterprise).
+ */
+export interface MonetizationConfig {
+  method: 'BROKER' | 'CRYPTO' | 'PRIVATE_TREATY';
+  /**
+   * The destination for settlement. 
+   * - If BROKER: The API URL of the clearing house.
+   * - If CRYPTO: The wallet address.
+   * - If TREATY: The Contract ID or "Contact Sales".
+   */
+  location: string; 
+}
+
+export interface AccessPolicy {
+  version: '1.1';
+  allowTraining: boolean;
+  allowRAG: boolean;
+  attributionRequired: boolean;
+  
+  // Economic Signals
+  allowAdSupportedAccess: boolean; // If true, Agents showing ads are exempt from payment
+  requiresPayment: boolean;        // If true, Access is denied unless Ad-Supported condition is met
+  paymentPointer?: string;         // @deprecated (Legacy support)
+
+  // V1.1: Optional Traffic Control
+  rateLimit?: RateLimitConfig;
+  
+  // V1.1: Optional Settlement Info
+  // If undefined, parties are assumed to have no economic relationship or settled offline.
+  monetization?: MonetizationConfig;
+}
+
+export interface ProtocolHeader {
+  v: '1.1';
+  ts: string;
+  agent_id: string;
+  resource: string;
+  purpose: AccessPurpose;
+  // Access Context
+  context: {
+    ads_displayed: boolean; // Is the AI Agent displaying ads alongside this content?
+  };
+}
+
+export interface SignedAccessRequest {
+  header: ProtocolHeader;
+  signature: string;
+  publicKey?: string;
+}
+
+export interface FeedbackSignal {
+  target_resource: string;
+  agent_id: string;
+  quality_score: number; // 0.0 to 1.0
+  flags: QualityFlag[];
+  timestamp: string;
+}