@aamp/protocol 1.1.2 → 1.1.3

package/src/publisher.ts

@@ -1,107 +1,303 @@
-/**
- * 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
-    };
-  }
+/**
+ * Layer 2: Publisher Middleware
+ * Used by content owners to enforce policy, log access, and filter bots.
+ */
+import { AccessPolicy, AccessPurpose, SignedAccessRequest, ContentOrigin, FeedbackSignal, AgentIdentityManifest, EvaluationResult, UnauthenticatedStrategy, IdentityCache } from './types';
+import { verifySignature, signData, exportPublicKey } from './crypto';
+import { MAX_CLOCK_SKEW_MS, HEADERS, WELL_KNOWN_AGENT_PATH } from './constants';
+
+interface VerificationResult {
+  allowed: boolean;
+  reason: string;
+  identityVerified: boolean;
+}
+
+/**
+ * Default In-Memory Cache (Fallback only)
+ * NOT recommended for high-traffic Serverless production.
+ */
+class MemoryCache implements IdentityCache {
+  private store = new Map<string, { val: string, exp: number }>();
+  
+  async get(key: string): Promise<string | null> {
+    const item = this.store.get(key);
+    if (!item) return null;
+    if (Date.now() > item.exp) {
+      this.store.delete(key);
+      return null;
+    }
+    return item.val;
+  }
+  
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    this.store.set(key, { 
+      val: value, 
+      exp: Date.now() + (ttlSeconds * 1000) 
+    });
+  }
+}
+
+export class AAMPPublisher {
+  private policy: AccessPolicy;
+  private keyPair: CryptoKeyPair | null = null;
+  private unauthenticatedStrategy: UnauthenticatedStrategy;
+  private cache: IdentityCache;
+  
+  // Default TTL: 1 Hour
+  private readonly CACHE_TTL_SECONDS = 3600; 
+
+  constructor(
+    policy: AccessPolicy, 
+    strategy: UnauthenticatedStrategy = 'PASSIVE',
+    cacheImpl?: IdentityCache 
+  ) {
+    this.policy = policy;
+    this.unauthenticatedStrategy = strategy;
+    this.cache = cacheImpl || new MemoryCache();
+  }
+
+  async initialize(keyPair: CryptoKeyPair) {
+    this.keyPair = keyPair;
+  }
+
+  getPolicy(): AccessPolicy {
+    return this.policy;
+  }
+
+  /**
+   * Main Entry Point: Evaluate ANY visitor (Human, Bot, or Agent)
+   */
+  async evaluateVisitor(
+    reqHeaders: Record<string, string | undefined>, 
+    rawPayload?: string
+  ): Promise<EvaluationResult> {
+    
+    // 1. Check for AAMP Headers
+    const hasAamp = reqHeaders[HEADERS.PAYLOAD] && reqHeaders[HEADERS.SIGNATURE] && reqHeaders[HEADERS.PUBLIC_KEY];
+
+    if (hasAamp) {
+      // It claims to be an Agent. Verify it.
+      return await this.handleAgent(reqHeaders, rawPayload);
+    }
+
+    // 2. It's not an AAMP Agent. Apply Strategy.
+    if (this.unauthenticatedStrategy === 'STRICT') {
+      return {
+        allowed: false,
+        status: 401,
+        reason: "STRICT_MODE: Only AAMP verified agents allowed.",
+        visitorType: 'UNIDENTIFIED_BOT'
+      };
+    }
+
+    if (this.unauthenticatedStrategy === 'PASSIVE') {
+      return {
+        allowed: true,
+        status: 200,
+        reason: "PASSIVE_MODE: Allowed without verification.",
+        visitorType: 'LIKELY_HUMAN' 
+      };
+    }
+
+    // 3. HYBRID MODE: Heuristic Analysis (The "Lazy Bot" Filter)
+    const isHuman = this.performBrowserHeuristics(reqHeaders);
+    
+    if (isHuman) {
+      return {
+        allowed: true,
+        status: 200,
+        reason: "BROWSER_VERIFIED: Heuristics passed.",
+        visitorType: 'LIKELY_HUMAN'
+      };
+    } else {
+      return {
+        allowed: false,
+        status: 403,
+        reason: "BOT_DETECTED: Request lacks browser signatures and AAMP headers.",
+        visitorType: 'UNIDENTIFIED_BOT'
+      };
+    }
+  }
+
+  /**
+   * Browser Heuristics (Hardened)
+   * 1. Checks Known Bot Signatures (Fast Fail)
+   * 2. Checks Trusted Upstream Signals (Cloudflare/Vercel)
+   * 3. Checks Browser Header Consistency
+   */
+  private performBrowserHeuristics(headers: Record<string, string | undefined>): boolean {
+    const userAgent = headers['user-agent'] || '';
+    
+    // A. The "Obvious Bot" Blocklist (Fast Fail)
+    const botSignatures = ['python-requests', 'curl', 'wget', 'scrapy', 'bot', 'crawler', 'spider'];
+    // Exception: Googlebot (if you want SEO). We'll treat Googlebot as a bot, 
+    // real implementations might white-list it via IP verification (not possible in just JS headers).
+    if (botSignatures.some(sig => userAgent.toLowerCase().includes(sig))) {
+       return false;
+    }
+
+    // B. Trusted Infrastructure Signals (The Real World Solution)
+    // If Cloudflare or Vercel says "This is a real user", we trust them.
+    // Cloudflare: 'cf-visitor' exists. 'cf-ipcountry' exists.
+    if (headers['cf-visitor'] || headers['cf-ray']) return true;
+    
+    // Vercel: 'x-vercel-id'
+    if (headers['x-vercel-id']) return true;
+    
+    // AWS CloudFront: 'cloudfront-viewer-address'
+    if (headers['cloudfront-viewer-address']) return true;
+
+    // C. The "Browser Fingerprint" (Fallback for direct connections)
+    // Real browsers almost always send these headers
+    const hasAcceptLanguage = !!headers['accept-language'];
+    const hasSecFetchDest = !!headers['sec-fetch-dest']; 
+    const hasUpgradeInsecure = !!headers['upgrade-insecure-requests'];
+
+    // If it has typical browser headers, we allow it.
+    if (hasAcceptLanguage && (hasSecFetchDest || hasUpgradeInsecure)) {
+      return true;
+    }
+
+    // If it has no browser headers and no trusted proxy headers -> It's likely a script.
+    return false;
+  }
+
+  /**
+   * Handle AAMP Protocol Logic
+   */
+  private async handleAgent(reqHeaders: Record<string, string | undefined>, rawPayload?: string): Promise<EvaluationResult> {
+    try {
+      const payloadHeader = reqHeaders[HEADERS.PAYLOAD]!;
+      const sigHeader = reqHeaders[HEADERS.SIGNATURE]!;
+      const keyHeader = reqHeaders[HEADERS.PUBLIC_KEY]!;
+
+      const headerJson = atob(payloadHeader); 
+      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"]
+      );
+
+      // Verify Core Logic
+      const result = await this.verifyRequestLogic(signedRequest, agentKey, headerJson);
+
+      if (!result.allowed) {
+        return {
+          allowed: false,
+          status: 403,
+          reason: result.reason,
+          visitorType: 'VERIFIED_AGENT'
+        };
+      }
+
+      return {
+        allowed: true,
+        status: 200,
+        reason: "AAMP_VERIFIED",
+        visitorType: 'VERIFIED_AGENT',
+        metadata: requestHeader
+      };
+
+    } catch (e) {
+      return { allowed: false, status: 400, reason: "INVALID_SIGNATURE", visitorType: 'UNIDENTIFIED_BOT' };
+    }
+  }
+
+  private async verifyRequestLogic(
+    request: SignedAccessRequest, 
+    requestPublicKey: CryptoKey,
+    rawPayload?: string
+  ): Promise<VerificationResult> {
+    
+    // 1. Replay Attack Prevention
+    const requestTime = new Date(request.header.ts).getTime();
+    if (Math.abs(Date.now() - requestTime) > MAX_CLOCK_SKEW_MS) {
+      return { allowed: false, reason: 'TIMESTAMP_INVALID', identityVerified: false };
+    }
+
+    // 2. Crypto Verification
+    const signableString = rawPayload || JSON.stringify(request.header);
+    const isCryptoValid = await verifySignature(requestPublicKey, signableString, request.signature);
+    if (!isCryptoValid) return { allowed: false, reason: 'CRYPTO_FAIL', identityVerified: false };
+
+    // 3. Identity Verification (DNS Binding) with Cache
+    let identityVerified = false;
+    const claimedDomain = request.header.agent_id;
+    const pubKeyString = await exportPublicKey(requestPublicKey);
+    
+    // Check Cache First
+    const cachedKey = await this.cache.get(claimedDomain);
+    
+    if (cachedKey === pubKeyString) {
+      identityVerified = true;
+    } else if (this.isDomain(claimedDomain)) {
+      // Cache Miss: Perform DNS Fetch
+      identityVerified = await this.verifyDnsBinding(claimedDomain, pubKeyString);
+      if (identityVerified) {
+        await this.cache.set(claimedDomain, pubKeyString, this.CACHE_TTL_SECONDS);
+      }
+    }
+
+    if (this.policy.requireIdentityBinding && !identityVerified) {
+      return { allowed: false, reason: 'IDENTITY_FAIL: DNS Binding could not be verified.', identityVerified: false };
+    }
+
+    // 4. Policy Check: Purpose
+    if (request.header.purpose === AccessPurpose.CRAWL_TRAINING && !this.policy.allowTraining) {
+      return { allowed: false, reason: 'POLICY_DENIED: Training not allowed.', identityVerified };
+    }
+    if (request.header.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
+      return { allowed: false, reason: 'POLICY_DENIED: RAG not allowed.', identityVerified };
+    }
+
+    // 5. Policy Check: Economics
+    if (this.policy.requiresPayment) {
+      const isAdExempt = this.policy.allowAdSupportedAccess && request.header.context.ads_displayed;
+      if (!isAdExempt) {
+        return { allowed: false, reason: 'PAYMENT_REQUIRED: Content requires payment or ads.', identityVerified };
+      }
+    }
+
+    return { allowed: true, reason: 'OK', identityVerified };
+  }
+
+  private async verifyDnsBinding(domain: string, requestKeySpki: string): Promise<boolean> {
+    try {
+      const url = `https://${domain}${WELL_KNOWN_AGENT_PATH}`;
+      // In production, we need a short timeout to prevent hanging
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 1500); // 1.5s max for DNS check
+      
+      const response = await fetch(url, { signal: controller.signal });
+      clearTimeout(timeoutId);
+      
+      if (!response.ok) return false;
+      const manifest = await response.json() as AgentIdentityManifest;
+      return manifest.agent_id === domain && manifest.public_key === requestKeySpki;
+    } catch { return false; }
+  }
+
+  private isDomain(s: string): boolean {
+    return /^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(s);
+  }
+
+  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

@@ -1,98 +1,113 @@
-/**
- * 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;
+/**
+ * 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'
+}
+
+/**
+ * DNS Identity Manifest
+ * Hosted at: https://{agent_id}/.well-known/aamp-agent.json
+ */
+export interface AgentIdentityManifest {
+  agent_id: string;   // e.g. "bot.openai.com"
+  public_key: string; // Base64 SPKI
+  contact_email?: string;
+}
+
+/**
+ * PRODUCTION INFRASTRUCTURE: Cache Interface
+ * Required for Serverless/Edge environments to prevent repeated DNS fetches.
+ */
+export interface IdentityCache {
+  get(key: string): Promise<string | null>; // Returns stored PublicKey
+  set(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+
+/**
+ * Optional Monetization (The Settlement Layer)
+ */
+export interface MonetizationConfig {
+  method: 'BROKER' | 'CRYPTO' | 'PRIVATE_TREATY';
+  location: string; 
+}
+
+/**
+ * Handling Non-AAMP Visitors
+ * 
+ * PASSIVE: Allow everyone (Legacy web behavior).
+ * HYBRID: Allow verified Agents AND likely Humans (Browser Heuristics). Block bots.
+ * STRICT: Allow ONLY verified AAMP Agents. (API Mode).
+ */
+export type UnauthenticatedStrategy = 'PASSIVE' | 'HYBRID' | 'STRICT';
+
+export interface AccessPolicy {
+  version: '1.1';
+  allowTraining: boolean;
+  allowRAG: boolean;
+  attributionRequired: boolean;
+  
+  // Economic Signals
+  allowAdSupportedAccess: boolean; 
+  requiresPayment: boolean;        
+  paymentPointer?: string;
+
+  // Identity Strictness
+  requireIdentityBinding?: boolean; 
+  
+  // V1.1: Optional Settlement Info
+  monetization?: MonetizationConfig;
+}
+
+export interface ProtocolHeader {
+  v: '1.1';
+  ts: string;
+  agent_id: string; 
+  resource: string;
+  purpose: AccessPurpose;
+  context: {
+    ads_displayed: boolean;
+  };
+}
+
+export interface SignedAccessRequest {
+  header: ProtocolHeader;
+  signature: string;
+  publicKey?: string;
+}
+
+export interface FeedbackSignal {
+  target_resource: string;
+  agent_id: string;
+  quality_score: number; 
+  flags: QualityFlag[];
+  timestamp: string;
+}
+
+// Result of the full evaluation pipeline
+export interface EvaluationResult {
+  allowed: boolean;
+  status: 200 | 400 | 401 | 403;
+  reason: string;
+  visitorType: 'VERIFIED_AGENT' | 'LIKELY_HUMAN' | 'UNIDENTIFIED_BOT';
+  metadata?: any;
 }