@aamp/protocol 1.1.5 → 1.1.7

package/src/proof.ts

@@ -0,0 +1,36 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+// In-memory cache for JWKS to avoid repeated fetches
+// Jose's createRemoteJWKSet handles caching/cooldowns internally.
+
+/**
+ * Verifies a JWT (Proof Token or Payment Credential) using JWKS.
+ * 
+ * @param token The JWT string 
+ * @param jwksUrl The URL to fetch Public Keys
+ * @param issuer The expected issuer
+ * @param audience The expected audience range
+ */
+export async function verifyJwt(
+    token: string,
+    jwksUrl: string,
+    issuer: string,
+    audience?: string
+): Promise<boolean> {
+    try {
+        const JWKS = createRemoteJWKSet(new URL(jwksUrl));
+
+        const { payload } = await jwtVerify(token, JWKS, {
+            issuer: issuer,
+            audience: audience // specific audience check if provided
+        });
+
+        // Check specific AAMP claims if we standardize them
+        // if (payload.type !== 'AD_IMPRESSION') return false;
+
+        return true;
+    } catch (error) {
+        // console.error("Ad Proof Verification Failed:", error);
+        return false;
+    }
+}

package/src/publisher.ts

@@ -2,14 +2,17 @@
  * Layer 2: Publisher Middleware
  * Used by content owners to enforce policy, log access, and filter bots.
  */
-import { HEADERS, MAX_CLOCK_SKEW_MS, WELL_KNOWN_AGENT_PATH } from './constants';
-import { exportPublicKey, signData, verifySignature } from './crypto';
-import { AccessPolicy, AccessPurpose, AgentIdentityManifest, ContentOrigin, EvaluationResult, IdentityCache, SignedAccessRequest, UnauthenticatedStrategy } from './types';
+import { HEADERS, MAX_CLOCK_SKEW_MS, WELL_KNOWN_AGENT_PATH } from './constants.js';
+import { exportPublicKey, signData, verifySignature } from './crypto.js';
+import { AccessPolicy, AccessPurpose, AgentIdentityManifest, ContentOrigin, EvaluationResult, IdentityCache, SignedAccessRequest, UnauthenticatedStrategy } from './types.js';
+import { verifyJwt } from './proof.js';
 
 interface VerificationResult {
   allowed: boolean;
   reason: string;
   identityVerified: boolean;
+  proofUsed?: string; // "WHITELIST", "CREDENTIAL_JWT", "AD_JWT"
+  visitorType?: string; // For audit logs
 }
 
 /**
@@ -18,7 +21,7 @@ interface VerificationResult {
  */
 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;
@@ -28,11 +31,11 @@ class MemoryCache implements IdentityCache {
     }
     return item.val;
   }
-  
+
   async set(key: string, value: string, ttlSeconds: number): Promise<void> {
-    this.store.set(key, { 
-      val: value, 
-      exp: Date.now() + (ttlSeconds * 1000) 
+    this.store.set(key, {
+      val: value,
+      exp: Date.now() + (ttlSeconds * 1000)
     });
   }
 }
@@ -42,14 +45,14 @@ export class AAMPPublisher {
   private keyPair: CryptoKeyPair | null = null;
   private unauthenticatedStrategy: UnauthenticatedStrategy;
   private cache: IdentityCache;
-  
+
   // Default TTL: 1 Hour
-  private readonly CACHE_TTL_SECONDS = 3600; 
+  private readonly CACHE_TTL_SECONDS = 3600;
 
   constructor(
-    policy: AccessPolicy, 
+    policy: AccessPolicy,
     strategy: UnauthenticatedStrategy = 'PASSIVE',
-    cacheImpl?: IdentityCache 
+    cacheImpl?: IdentityCache
   ) {
     this.policy = policy;
     this.unauthenticatedStrategy = strategy;
@@ -66,58 +69,56 @@ export class AAMPPublisher {
 
   /**
    * Main Entry Point: Evaluate ANY visitor (Human, Bot, or Agent)
+   * STAGE 1: IDENTITY (Strict)
+   * STAGE 2: POLICY (Permissions)
+   * STAGE 3: ACCESS (HQ Content)
    */
   async evaluateVisitor(
-    reqHeaders: Record<string, string | undefined>, 
+    reqHeaders: Record<string, string | undefined>,
     rawPayload?: string
   ): Promise<EvaluationResult> {
-    
-    // 1. Check for AAMP Headers
+    console.log(`\n--- [AAMP LOG START] New Request ---`);
+
+    // --- STAGE 1: IDENTITY VERIFICATION ---
+    console.log(`[IDENTITY] 🔍 Checking Identity Headers...`);
+
     const hasAamp = reqHeaders[HEADERS.PAYLOAD] && reqHeaders[HEADERS.SIGNATURE] && reqHeaders[HEADERS.PUBLIC_KEY];
 
     if (hasAamp) {
-      console.log("\n🔎 [AAMP Middleware] Detected Agent Headers. Starting Verification...");
-      // It claims to be an Agent. Verify it.
-      return await this.handleAgent(reqHeaders, rawPayload);
+      // It claims to be an Agent. Verify it STRICTLY.
+      return await this.handleAgentStrict(reqHeaders, rawPayload);
     }
 
-    // 2. It's not an AAMP Agent. Apply Strategy.
+    // If NO AAMP Headers -> FAIL IDENTITY immediately.
+    console.log(`[IDENTITY] ❌ FAILED. No AAMP Headers found.`);
+
+    // For now, retaining the legacy "Passive/Hybrid" switch just to avoid breaking browser demos completely 
+    // BUT logging it as a specific "Identity Fail" flow.
     if (this.unauthenticatedStrategy === 'STRICT') {
+      console.log(`[IDENTITY] ⛔ BLOCKING. Strategy is STRICT.`);
       return {
         allowed: false,
         status: 401,
-        reason: "STRICT_MODE: Only AAMP verified agents allowed.",
+        reason: "IDENTITY_REQUIRED: Missing AAMP Headers.",
         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)
+    console.log(`[IDENTITY] ⚠️ SKIPPED (Legacy Mode). Checking Browser Heuristics...`);
     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'
-      };
+      console.log(`[POLICY] 👤 ALLOWED. Browser Heuristics Passed.`);
+      return { allowed: true, status: 200, reason: "BROWSER_VERIFIED", visitorType: 'LIKELY_HUMAN' };
     }
+
+    console.log(`[IDENTITY] ❌ FAILED. Not a Browser, No Headers.`);
+    console.log(`[ACCESS] ⛔ BLOCKED.`);
+    return {
+      allowed: false,
+      status: 403,
+      reason: "IDENTITY_FAIL: No Identity, No Browser.",
+      visitorType: 'UNIDENTIFIED_BOT'
+    };
   }
 
   /**
@@ -128,11 +129,11 @@ export class AAMPPublisher {
    */
   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'];
     if (botSignatures.some(sig => userAgent.toLowerCase().includes(sig))) {
-       return false;
+      return false;
     }
 
     // B. Trusted Infrastructure Signals (The Real World Solution)
@@ -142,7 +143,7 @@ export class AAMPPublisher {
 
     // C. The "Browser Fingerprint" (Fallback for direct connections)
     const hasAcceptLanguage = !!headers['accept-language'];
-    const hasSecFetchDest = !!headers['sec-fetch-dest']; 
+    const hasSecFetchDest = !!headers['sec-fetch-dest'];
     const hasUpgradeInsecure = !!headers['upgrade-insecure-requests'];
 
     if (hasAcceptLanguage && (hasSecFetchDest || hasUpgradeInsecure)) {
@@ -153,17 +154,24 @@ export class AAMPPublisher {
   }
 
   /**
-   * Handle AAMP Protocol Logic
+   * Handle AAMP Protocol Logic (Strict Mode)
    */
-  private async handleAgent(reqHeaders: Record<string, string | undefined>, rawPayload?: string): Promise<EvaluationResult> {
+  private async handleAgentStrict(reqHeaders: Record<string, string | undefined>, rawPayload?: string): Promise<EvaluationResult> {
+    let agentId = "UNKNOWN";
+
     try {
+      // 1. Decode Headers
       const payloadHeader = reqHeaders[HEADERS.PAYLOAD]!;
       const sigHeader = reqHeaders[HEADERS.SIGNATURE]!;
       const keyHeader = reqHeaders[HEADERS.PUBLIC_KEY]!;
 
-      const headerJson = atob(payloadHeader); 
+      const headerJson = atob(payloadHeader);
       const requestHeader = JSON.parse(headerJson);
-      
+      agentId = requestHeader.agent_id;
+
+      console.log(`[IDENTITY] 🆔 Claimed ID: ${agentId}`);
+
+      // 2. Crypto & DNS Verification
       const signedRequest: SignedAccessRequest = {
         header: requestHeader,
         signature: sigHeader,
@@ -178,63 +186,158 @@ export class AAMPPublisher {
         ["verify"]
       );
 
-      // Verify Core Logic
-      const result = await this.verifyRequestLogic(signedRequest, agentKey, headerJson);
-
-      if (!result.allowed) {
-        console.log(`⛔ [AAMP Deny] Reason: ${result.reason}`);
-        return {
-          allowed: false,
-          status: 403,
-          reason: result.reason,
-          visitorType: 'VERIFIED_AGENT'
-        };
+      // Verify Core Logic (DNS + Crypto)
+      const verification = await this.verifyRequestLogic(signedRequest, agentKey);
+
+      if (!verification.identityVerified) {
+        console.log(`[IDENTITY] ❌ FAILED. Reason: ${verification.reason}`);
+        console.log(`[ACCESS] ⛔ BLOCKED.`);
+        return { allowed: false, status: 403, reason: verification.reason, visitorType: 'UNIDENTIFIED_BOT' };
       }
 
-      console.log(`✅ [AAMP Allow] Verified Agent: ${requestHeader.agent_id}`);
+      console.log(`[IDENTITY] ✅ PASSED. DNS Binding Verified.`);
+
+      // --- STAGE 2: POLICY ENFORCEMENT ---
+      console.log(`[POLICY] 📜 Checking Permissions for ${agentId}...`);
+
+      const proofToken = reqHeaders[HEADERS.PROOF_TOKEN];
+      const paymentCredential = reqHeaders[HEADERS.PAYMENT_CREDENTIAL];
+
+      const policyResult = await this.checkPolicyStrict(requestHeader, proofToken, paymentCredential);
+
+      if (!policyResult.allowed) {
+        console.log(`[POLICY] ⛔ DENIED. Reason: ${policyResult.reason}`);
+        console.log(`[ACCESS] ⛔ BLOCKED.`);
+        return policyResult;
+      }
+
+      // --- STAGE 3: ACCESS GRANT ---
+      console.log(`[POLICY] ✅ PASSED. Requirements Met.`);
+      console.log(`[ACCESS] 🔓 GRANTED. Unlocking HQ Content.`);
+
       return {
         allowed: true,
         status: 200,
         reason: "AAMP_VERIFIED",
         visitorType: 'VERIFIED_AGENT',
-        metadata: requestHeader
+        metadata: requestHeader,
+        proofUsed: policyResult.proofUsed
       };
 
     } catch (e) {
-      console.error(e);
+      console.error(`[AAMP ERROR]`, e);
       return { allowed: false, status: 400, reason: "INVALID_SIGNATURE", visitorType: 'UNIDENTIFIED_BOT' };
     }
   }
 
+  // Legacy handler kept for interface compatibility (deprecated)
+  private async handleAgent(reqHeaders: Record<string, string | undefined>, rawPayload?: string): Promise<EvaluationResult> {
+    return this.handleAgentStrict(reqHeaders, rawPayload);
+  }
+
+  /**
+   * STAGE 2: POLICY ENFORCEMENT CHECK
+   */
+  private async checkPolicyStrict(
+    requestHeader: any,
+    proofToken?: string,
+    paymentCredential?: string
+  ): Promise<EvaluationResult> {
+
+    // 1. Policy Check: Purpose Ban (e.g. No Training)
+    if (requestHeader.purpose === AccessPurpose.CRAWL_TRAINING && !this.policy.allowTraining) {
+      return { allowed: false, status: 403, reason: 'POLICY_DENIED: Training not allowed.', visitorType: 'VERIFIED_AGENT' };
+    }
+    if (requestHeader.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
+      return { allowed: false, status: 403, reason: 'POLICY_DENIED: RAG not allowed.', visitorType: 'VERIFIED_AGENT' };
+    }
+
+    // 2. Policy Check: Economics (v1.2) - Payment & Ads
+    if (this.policy.requiresPayment) {
+      let paymentSatisfied = false;
+
+      // Method A: Flexible Payment Callback (DB / Custom Logic)
+      if (this.policy.monetization?.checkPayment) {
+        const isPaid = await this.policy.monetization.checkPayment(requestHeader.agent_id, requestHeader.purpose);
+        if (isPaid) {
+          console.log(`[POLICY] 💰 Payment Verified via Callback.`);
+          return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'WHITELIST_CALLBACK' };
+        }
+      }
+
+      // Method B: Payment Credentials (Unified JWT)
+      if (!paymentSatisfied && this.policy.monetization?.paymentConfig && paymentCredential) {
+        const { jwksUrl, issuer } = this.policy.monetization.paymentConfig;
+        console.log(`[POLICY] 🔐 Verifying Payment Credential (Issuer: ${issuer})...`);
+
+        const isValidCredential = await verifyJwt(paymentCredential, jwksUrl, issuer);
+        if (isValidCredential) {
+          console.log(`[POLICY] ✅ Credential Signature VALID.`);
+          return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'PAYMENT_CREDENTIAL_JWT' };
+        } else {
+          console.log(`[POLICY] ❌ Credential Signature INVALID.`);
+        }
+      }
+
+      // Method C: Ad-Supported (Proof Verification)
+      if (!paymentSatisfied && this.policy.allowAdSupportedAccess && requestHeader.context?.ads_displayed) {
+        if (proofToken && this.policy.monetization?.adNetwork) {
+          const { jwksUrl, issuer } = this.policy.monetization.adNetwork;
+          console.log(`[POLICY] 📺 Verifying Ad Proof (Issuer: ${issuer})...`);
+
+          const isValidProof = await verifyJwt(proofToken, jwksUrl, issuer);
+          if (isValidProof) {
+            console.log(`[POLICY] ✅ Ad Proof Signature VALID.`);
+            return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'AD_PROOF_JWT' };
+          } else {
+            console.log(`[POLICY] ❌ Ad Proof Signature INVALID.`);
+          }
+        } else {
+          console.log(`[POLICY] ⚠️ Ad Proof MISSING.`);
+        }
+      }
+
+      return {
+        allowed: false,
+        status: 402,
+        reason: 'PAYMENT_REQUIRED: Whitelist, Credential, and Ad Proof checks ALL failed.',
+        visitorType: 'VERIFIED_AGENT',
+        proofUsed: 'NONE'
+      };
+    }
+
+    // If no payment required, allow.
+    return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT' };
+  }
+
   private async verifyRequestLogic(
-    request: SignedAccessRequest, 
+    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 };
+      return { allowed: false, reason: 'TIMESTAMP_INVALID: Clock skew too large.', identityVerified: false };
     }
 
     // 2. Crypto Verification
-    const signableString = rawPayload || JSON.stringify(request.header);
+    const signableString = JSON.stringify(request.header);
     const isCryptoValid = await verifySignature(requestPublicKey, signableString, request.signature);
-    if (!isCryptoValid) return { allowed: false, reason: 'CRYPTO_FAIL', identityVerified: false };
+    if (!isCryptoValid) return { allowed: false, reason: 'CRYPTO_FAIL: Signature invalid.', identityVerified: false };
 
     // 3. Identity Verification (DNS Binding) with Cache
     let identityVerified = false;
     const claimedDomain = request.header.agent_id;
     const pubKeyString = await exportPublicKey(requestPublicKey);
-    
-    console.log(`   🆔 [AAMP Identity] Verifying DNS Binding for: ${claimedDomain}`);
+
+    console.log(`[IDENTITY] 🔍 Verifying DNS Binding for: ${claimedDomain}`);
 
     // Check Cache First
     const cachedKey = await this.cache.get(claimedDomain);
-    
+
     if (cachedKey === pubKeyString) {
-      console.log("   ⚡ [AAMP Cache] Identity found in cache.");
+      console.log("[IDENTITY] ⚡ Cache Hit. Identity Verified.");
       identityVerified = true;
     } else if (this.isDomain(claimedDomain)) {
       // Cache Miss: Perform DNS Fetch
@@ -248,23 +351,8 @@ export class AAMPPublisher {
       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 };
+    // Return verified status so handleAgentStrict can proceed to Policy Check
+    return { allowed: true, reason: 'OK', identityVerified: true };
   }
 
   private async verifyDnsBinding(domain: string, requestKeySpki: string): Promise<boolean> {
@@ -272,16 +360,16 @@ export class AAMPPublisher {
       // Allow HTTP for localhost testing
       const protocol = (domain.includes('localhost') || domain.match(/:\d+$/)) ? 'http' : 'https';
       const url = `${protocol}://${domain}${WELL_KNOWN_AGENT_PATH}`;
-      
+
       console.log(`   🌍 [AAMP DNS] Fetching Manifest: ${url} ...`);
 
       // 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) {
         console.log(`   ❌ [AAMP DNS] Fetch Failed: ${response.status}`);
         return false;
@@ -298,15 +386,15 @@ export class AAMPPublisher {
 
       // CHECK 2: Does the key match?
       if (manifest.public_key !== requestKeySpki) {
-         console.log(`   ❌ [AAMP DNS] Key Mismatch: DNS Key != Request Key`);
-         return false;
+        console.log(`   ❌ [AAMP DNS] Key Mismatch: DNS Key != Request Key`);
+        return false;
       }
 
       console.log(`   ✅ [AAMP DNS] Identity Confirmed.`);
       return true;
-    } catch (e: any) { 
-        console.log(`   ❌ [AAMP DNS] Error: ${e.message}`);
-        return false; 
+    } catch (e: any) {
+      console.log(`   ❌ [AAMP DNS] Error: ${e.message}`);
+      return false;
     }
   }
 
@@ -324,4 +412,28 @@ export class AAMPPublisher {
       [HEADERS.PROVENANCE_SIG]: signature
     };
   }
+
+  /**
+   * Handling Quality Feedback (The "Dispute" Layer)
+   * This runs when an Agent sends 'x-aamp-feedback'.
+   */
+  private async handleFeedback(token: string, headers: Record<string, string | undefined>) {
+    // NOTE: In production, you would fetch the Agent's specific key. 
+    // For now, we assume standard Discovery or a centralized Key Set (like adNetwork).
+    // Ideally, the SDK config should have a 'qualityOracle' key set.
+
+    // 1. We just Decode it to Log it (Verification is optional but recommended)
+    try {
+      const parts = token.split('.');
+      const payload = JSON.parse(atob(parts[1]));
+
+      console.log(`\n📢 [AAMP QUALITY ALERT] Feedback Received from ${payload.agent_id}`);
+      console.log(`   Reason: ${payload.reason} | Score: ${payload.quality_score}`);
+      console.log(`   Resource: ${payload.url}`);
+      console.log(`   (Signature available for dispute evidence)`);
+
+    } catch (e) {
+      console.log(`   ⚠️ [AAMP Warning] Malformed Feedback Token.`);
+    }
+  }
 }

package/src/types.ts

@@ -43,14 +43,35 @@ export interface IdentityCache {
   set(key: string, value: string, ttlSeconds: number): Promise<void>;
 }
 
+/**
+ * Optional Monetization (The Settlement Layer)
+ */
 /**
  * Optional Monetization (The Settlement Layer)
  */
 export interface MonetizationConfig {
-  method: 'BROKER' | 'CRYPTO' | 'PRIVATE_TREATY';
-  location: string; 
+  // Method 1: Payments (Flexible Callback)
+  // Developers implement their own logic (Database check, CMS lookup, etc.)
+  // Returns TRUE if the agent is a paid subscriber for this specific purpose.
+  checkPayment?: (agentId: string, purpose: string) => boolean | Promise<boolean>;
+
+  // Method 2: Ads (Proof Verification)
+  // Configuration to verify tokens from your Ad Provider (e.g. Google)
+  adNetwork?: {
+    jwksUrl: string;   // e.g. "https://www.googleapis.com/oauth2/v3/certs"
+    issuer: string;    // e.g. "https://accounts.google.com"
+  };
+
+  // Method 3: Payment Credentials (Unified JWT)
+  // Verifies "x-aamp-credential" for Broker or Direct payments.
+  paymentConfig?: {
+    jwksUrl: string;   // e.g. "https://my-site.com/.well-known/jwks.json"
+    issuer: string;    // e.g. "my-site.com"
+  };
 }
 
+
+
 /**
  * Handling Non-AAMP Visitors
  * 
@@ -65,15 +86,15 @@ export interface AccessPolicy {
   allowTraining: boolean;
   allowRAG: boolean;
   attributionRequired: boolean;
-  
+
   // Economic Signals
-  allowAdSupportedAccess: boolean; 
-  requiresPayment: boolean;        
+  allowAdSupportedAccess: boolean;
+  requiresPayment: boolean;
   paymentPointer?: string;
 
   // Identity Strictness
-  requireIdentityBinding?: boolean; 
-  
+  requireIdentityBinding?: boolean;
+
   // V1.1: Optional Settlement Info
   monetization?: MonetizationConfig;
 }
@@ -81,7 +102,7 @@ export interface AccessPolicy {
 export interface ProtocolHeader {
   v: '1.1';
   ts: string;
-  agent_id: string; 
+  agent_id: string;
   resource: string;
   purpose: AccessPurpose;
   context: {
@@ -98,16 +119,28 @@ export interface SignedAccessRequest {
 export interface FeedbackSignal {
   target_resource: string;
   agent_id: string;
-  quality_score: number; 
+  quality_score: number;
   flags: QualityFlag[];
   timestamp: string;
 }
 
+// Result of the full evaluation pipeline
 // Result of the full evaluation pipeline
 export interface EvaluationResult {
   allowed: boolean;
-  status: 200 | 400 | 401 | 403;
+  status: 200 | 400 | 401 | 402 | 403;
   reason: string;
   visitorType: 'VERIFIED_AGENT' | 'LIKELY_HUMAN' | 'UNIDENTIFIED_BOT';
   metadata?: any;
+  payment_status?: 'PAID_SUBSCRIBER' | 'AD_FUNDED' | 'UNPAID';
+  proofUsed?: string;
+}
+
+// Signed Quality Feedback (The "Report Card")
+export interface FeedbackSignalToken {
+  url: string;           // The resource being flagged
+  agent_id: string;      // Who is flagging it (e.g. "bot.openai.com")
+  quality_score: number; // 0.0 to 1.0
+  reason: string;        // e.g. "SEO_SPAM", "HATE_SPEECH"
+  timestamp: number;
 }

package/test/handshake.spec.ts

@@ -3,10 +3,10 @@
  * Run using: npm test
  * Location: sdk/typescript/test/handshake.spec.ts
  */
-import { AAMPAgent } from '../src/agent';
-import { AAMPPublisher } from '../src/publisher';
-import { AccessPurpose } from '../src/types';
-import { HEADERS } from '../src/constants';
+import { AAMPAgent } from '../src/agent.js';
+import { AAMPPublisher } from '../src/publisher.js';
+import { AccessPurpose } from '../src/types.js';
+import { HEADERS } from '../src/constants.js';
 
 async function runTest() {
   console.log("--- STARTING AAMP HANDSHAKE TEST ---");
@@ -29,7 +29,7 @@ async function runTest() {
   // 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', AccessPurpose.RAG_RETRIEVAL, { adsDisplayed: false });
-  
+
   const payloadA = JSON.stringify(reqA.header);
   const headersA = {
     [HEADERS.PAYLOAD]: btoa(payloadA),
@@ -45,7 +45,7 @@ async function runTest() {
   // 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', AccessPurpose.RAG_RETRIEVAL, { adsDisplayed: true });
-  
+
   const payloadB = JSON.stringify(reqB.header);
   const headersB = {
     [HEADERS.PAYLOAD]: btoa(payloadB),

package/tsconfig.json

@@ -1,8 +1,12 @@
 {
   "compilerOptions": {
     "target": "ES2020",
-    "module": "CommonJS",
-    "lib": ["ES2020", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "ES2020",
+      "DOM"
+    ],
     "declaration": true,
     "outDir": "./dist",
     "rootDir": "./src",
@@ -11,5 +15,7 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*"]
+  "include": [
+    "src/**/*"
+  ]
 }