@aamp/protocol 1.1.6 → 1.1.7

package/dist/publisher.d.ts

@@ -10,6 +10,9 @@ export declare class AAMPPublisher {
     getPolicy(): AccessPolicy;
     /**
      * Main Entry Point: Evaluate ANY visitor (Human, Bot, or Agent)
+     * STAGE 1: IDENTITY (Strict)
+     * STAGE 2: POLICY (Permissions)
+     * STAGE 3: ACCESS (HQ Content)
      */
     evaluateVisitor(reqHeaders: Record<string, string | undefined>, rawPayload?: string): Promise<EvaluationResult>;
     /**
@@ -20,9 +23,14 @@ export declare class AAMPPublisher {
      */
     private performBrowserHeuristics;
     /**
-     * Handle AAMP Protocol Logic
+     * Handle AAMP Protocol Logic (Strict Mode)
      */
+    private handleAgentStrict;
     private handleAgent;
+    /**
+     * STAGE 2: POLICY ENFORCEMENT CHECK
+     */
+    private checkPolicyStrict;
     private verifyRequestLogic;
     private verifyDnsBinding;
     private isDomain;

package/dist/publisher.js

@@ -48,54 +48,46 @@ 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, rawPayload) {
-        // 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];
-        const feedbackToken = reqHeaders[HEADERS.FEEDBACK];
-        if (feedbackToken) {
-            await this.handleFeedback(feedbackToken, reqHeaders);
-        }
         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'
+        };
     }
     /**
      * Browser Heuristics (Hardened)
@@ -127,143 +119,163 @@ export class AAMPPublisher {
         return false;
     }
     /**
-     * Handle AAMP Protocol Logic
+     * Handle AAMP Protocol Logic (Strict Mode)
      */
-    async handleAgent(reqHeaders, rawPayload) {
+    async handleAgentStrict(reqHeaders, rawPayload) {
+        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 requestHeader = JSON.parse(headerJson);
+            agentId = requestHeader.agent_id;
+            console.log(`[IDENTITY] 🆔 Claimed ID: ${agentId}`);
+            // 2. Crypto & DNS Verification
             const signedRequest = {
                 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 (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(`[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];
-            // Verify Core Logic
-            const result = await this.verifyRequestLogic(signedRequest, agentKey, proofToken, paymentCredential, headerJson);
-            if (!result.allowed) {
-                console.log(`⛔ [AAMP BLOCK] 
-        Agent: ${requestHeader.agent_id}
-        Reason: ${result.reason}
-        VisitorType: ${result.visitorType}
-        Proof: ${result.proofUsed || 'None'}
-        Identity Verified: ${result.identityVerified}`);
-                return {
-                    allowed: false,
-                    status: 403,
-                    reason: result.reason,
-                    visitorType: 'VERIFIED_AGENT'
-                };
+            const policyResult = await this.checkPolicyStrict(requestHeader, proofToken, paymentCredential);
+            if (!policyResult.allowed) {
+                console.log(`[POLICY] ⛔ DENIED. Reason: ${policyResult.reason}`);
+                console.log(`[ACCESS] ⛔ BLOCKED.`);
+                return policyResult;
             }
-            console.log(`✅ [AAMP ALLOW] 
-      Agent: ${requestHeader.agent_id}
-      Reason: AAMP_VERIFIED
-      Payment Method: ${result.proofUsed}
-      Identity Verified: ${result.identityVerified}`);
+            // --- 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' };
         }
     }
-    async verifyRequestLogic(request, requestPublicKey, proofToken, paymentCredential, rawPayload) {
-        // 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);
-        console.log(`   🆔 [AAMP 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.");
-            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 };
+    // Legacy handler kept for interface compatibility (deprecated)
+    async handleAgent(reqHeaders, rawPayload) {
+        return this.handleAgentStrict(reqHeaders, rawPayload);
+    }
+    /**
+     * STAGE 2: POLICY ENFORCEMENT CHECK
+     */
+    async checkPolicyStrict(requestHeader, proofToken, paymentCredential) {
+        // 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 (request.header.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
-            return { allowed: false, reason: 'POLICY_DENIED: RAG not allowed.', identityVerified };
+        if (requestHeader.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
+            return { allowed: false, status: 403, reason: 'POLICY_DENIED: RAG not allowed.', visitorType: 'VERIFIED_AGENT' };
         }
-        // 5. Policy Check: Economics (v1.2)
+        // 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(request.header.agent_id, request.header.purpose);
+                const isPaid = await this.policy.monetization.checkPayment(requestHeader.agent_id, requestHeader.purpose);
                 if (isPaid) {
-                    console.log(`   💰 [AAMP Audit] Whitelist Check Passed via Callback.`);
-                    return { allowed: true, reason: 'OK', identityVerified, proofUsed: 'WHITELIST_CALLBACK' };
+                    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(`   🔐 [AAMP Audit] Verifying Payment Credential (Issuer: ${issuer})...`);
+                console.log(`[POLICY] 🔐 Verifying Payment Credential (Issuer: ${issuer})...`);
                 const isValidCredential = await verifyJwt(paymentCredential, jwksUrl, issuer);
                 if (isValidCredential) {
-                    console.log(`   ✅ [AAMP Audit] Credential Signature VALID.`);
-                    return { allowed: true, reason: 'OK', identityVerified, proofUsed: 'PAYMENT_CREDENTIAL_JWT' };
+                    console.log(`[POLICY] ✅ Credential Signature VALID.`);
+                    return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'PAYMENT_CREDENTIAL_JWT' };
                 }
                 else {
-                    console.log(`   ❌ [AAMP Audit] Credential Signature INVALID.`);
+                    console.log(`[POLICY] ❌ Credential Signature INVALID.`);
                 }
             }
             // Method C: Ad-Supported (Proof Verification)
-            if (!paymentSatisfied && this.policy.allowAdSupportedAccess && request.header.context.ads_displayed) {
+            if (!paymentSatisfied && this.policy.allowAdSupportedAccess && requestHeader.context?.ads_displayed) {
                 if (proofToken && this.policy.monetization?.adNetwork) {
                     const { jwksUrl, issuer } = this.policy.monetization.adNetwork;
-                    console.log(`   📺 [AAMP Audit] Verifying Ad Proof (Issuer: ${issuer})...`);
+                    console.log(`[POLICY] 📺 Verifying Ad Proof (Issuer: ${issuer})...`);
                     const isValidProof = await verifyJwt(proofToken, jwksUrl, issuer);
                     if (isValidProof) {
-                        console.log(`   ✅ [AAMP Audit] Ad Proof Signature VALID.`);
-                        return { allowed: true, reason: 'OK', identityVerified, proofUsed: 'AD_PROOF_JWT' };
+                        console.log(`[POLICY] ✅ Ad Proof Signature VALID.`);
+                        return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'AD_PROOF_JWT' };
                     }
                     else {
-                        console.log(`   ❌ [AAMP Audit] Ad Proof Signature INVALID.`);
+                        console.log(`[POLICY] ❌ Ad Proof Signature INVALID.`);
                     }
                 }
                 else {
-                    console.log(`   ⚠️ [AAMP Audit] Ad Proof MISSING.`);
+                    console.log(`[POLICY] ⚠️ Ad Proof MISSING.`);
                 }
             }
-            if (!paymentSatisfied) {
-                return { allowed: false, reason: 'PAYMENT_REQUIRED: Whitelist, Credential, and Ad Proof checks ALL failed.', identityVerified, proofUsed: 'NONE', visitorType: 'VERIFIED_AGENT' };
+            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' };
+    }
+    async verifyRequestLogic(request, requestPublicKey) {
+        // 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: Clock skew too large.', identityVerified: false };
+        }
+        // 2. Crypto Verification
+        const signableString = JSON.stringify(request.header);
+        const isCryptoValid = await verifySignature(requestPublicKey, signableString, request.signature);
+        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(`[IDENTITY] 🔍 Verifying DNS Binding for: ${claimedDomain}`);
+        // Check Cache First
+        const cachedKey = await this.cache.get(claimedDomain);
+        if (cachedKey === pubKeyString) {
+            console.log("[IDENTITY] ⚡ Cache Hit. Identity Verified.");
+            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);
             }
         }
-        return { allowed: true, reason: 'OK', identityVerified };
+        if (this.policy.requireIdentityBinding && !identityVerified) {
+            return { allowed: false, reason: 'IDENTITY_FAIL: DNS Binding could not be verified.', identityVerified: false };
+        }
+        // Return verified status so handleAgentStrict can proceed to Policy Check
+        return { allowed: true, reason: 'OK', identityVerified: true };
     }
     async verifyDnsBinding(domain, requestKeySpki) {
         try {

package/dist/types.d.ts

@@ -97,7 +97,7 @@ export interface FeedbackSignal {
 }
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aamp/protocol",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "TypeScript reference implementation of AAMP v1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/publisher.ts

@@ -69,63 +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>,
     rawPayload?: string
   ): Promise<EvaluationResult> {
+    console.log(`\n--- [AAMP LOG START] New Request ---`);
 
-    // 1. Check for AAMP Headers
-    const hasAamp = reqHeaders[HEADERS.PAYLOAD] && reqHeaders[HEADERS.SIGNATURE] && reqHeaders[HEADERS.PUBLIC_KEY];
+    // --- STAGE 1: IDENTITY VERIFICATION ---
+    console.log(`[IDENTITY] 🔍 Checking Identity Headers...`);
 
-    const feedbackToken = reqHeaders[HEADERS.FEEDBACK];
-    if (feedbackToken) {
-      await this.handleFeedback(feedbackToken, reqHeaders);
-    }
+    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'
+    };
   }
 
   /**
@@ -161,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 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,
@@ -186,151 +186,173 @@ export class AAMPPublisher {
         ["verify"]
       );
 
+      // 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(`[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];
 
-      // Verify Core Logic
-      const result = await this.verifyRequestLogic(signedRequest, agentKey, proofToken, paymentCredential, headerJson);
-
-      if (!result.allowed) {
-        console.log(`⛔ [AAMP BLOCK] 
-        Agent: ${requestHeader.agent_id}
-        Reason: ${result.reason}
-        VisitorType: ${result.visitorType}
-        Proof: ${result.proofUsed || 'None'}
-        Identity Verified: ${result.identityVerified}`);
-
-        return {
-          allowed: false,
-          status: 403,
-          reason: result.reason,
-          visitorType: 'VERIFIED_AGENT'
-        };
+      const policyResult = await this.checkPolicyStrict(requestHeader, proofToken, paymentCredential);
+
+      if (!policyResult.allowed) {
+        console.log(`[POLICY] ⛔ DENIED. Reason: ${policyResult.reason}`);
+        console.log(`[ACCESS] ⛔ BLOCKED.`);
+        return policyResult;
       }
 
-      console.log(`✅ [AAMP ALLOW] 
-      Agent: ${requestHeader.agent_id}
-      Reason: AAMP_VERIFIED
-      Payment Method: ${result.proofUsed}
-      Identity Verified: ${result.identityVerified}`);
+      // --- 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' };
     }
   }
 
-  private async verifyRequestLogic(
-    request: SignedAccessRequest,
-    requestPublicKey: CryptoKey,
-    proofToken?: string,
-    paymentCredential?: string,
-    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);
-
-    console.log(`   🆔 [AAMP 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.");
-      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);
-      }
-    }
+  // Legacy handler kept for interface compatibility (deprecated)
+  private async handleAgent(reqHeaders: Record<string, string | undefined>, rawPayload?: string): Promise<EvaluationResult> {
+    return this.handleAgentStrict(reqHeaders, rawPayload);
+  }
 
-    if (this.policy.requireIdentityBinding && !identityVerified) {
-      return { allowed: false, reason: 'IDENTITY_FAIL: DNS Binding could not be verified.', identityVerified: false };
-    }
+  /**
+   * STAGE 2: POLICY ENFORCEMENT CHECK
+   */
+  private async checkPolicyStrict(
+    requestHeader: any,
+    proofToken?: string,
+    paymentCredential?: string
+  ): Promise<EvaluationResult> {
 
-    // 4. Policy Check: Purpose
-    if (request.header.purpose === AccessPurpose.CRAWL_TRAINING && !this.policy.allowTraining) {
-      return { allowed: false, reason: 'POLICY_DENIED: Training not allowed.', identityVerified };
+    // 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 (request.header.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
-      return { allowed: false, reason: 'POLICY_DENIED: RAG not allowed.', identityVerified };
+    if (requestHeader.purpose === AccessPurpose.RAG_RETRIEVAL && !this.policy.allowRAG) {
+      return { allowed: false, status: 403, reason: 'POLICY_DENIED: RAG not allowed.', visitorType: 'VERIFIED_AGENT' };
     }
 
-    // 5. Policy Check: Economics (v1.2)
+    // 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(request.header.agent_id, request.header.purpose);
+        const isPaid = await this.policy.monetization.checkPayment(requestHeader.agent_id, requestHeader.purpose);
         if (isPaid) {
-          console.log(`   💰 [AAMP Audit] Whitelist Check Passed via Callback.`);
-          return { allowed: true, reason: 'OK', identityVerified, proofUsed: 'WHITELIST_CALLBACK' };
+          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(`   🔐 [AAMP Audit] Verifying Payment Credential (Issuer: ${issuer})...`);
+        console.log(`[POLICY] 🔐 Verifying Payment Credential (Issuer: ${issuer})...`);
 
         const isValidCredential = await verifyJwt(paymentCredential, jwksUrl, issuer);
         if (isValidCredential) {
-          console.log(`   ✅ [AAMP Audit] Credential Signature VALID.`);
-          return { allowed: true, reason: 'OK', identityVerified, proofUsed: 'PAYMENT_CREDENTIAL_JWT' };
+          console.log(`[POLICY] ✅ Credential Signature VALID.`);
+          return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'PAYMENT_CREDENTIAL_JWT' };
         } else {
-          console.log(`   ❌ [AAMP Audit] Credential Signature INVALID.`);
+          console.log(`[POLICY] ❌ Credential Signature INVALID.`);
         }
       }
 
       // Method C: Ad-Supported (Proof Verification)
-      if (!paymentSatisfied && this.policy.allowAdSupportedAccess && request.header.context.ads_displayed) {
+      if (!paymentSatisfied && this.policy.allowAdSupportedAccess && requestHeader.context?.ads_displayed) {
         if (proofToken && this.policy.monetization?.adNetwork) {
           const { jwksUrl, issuer } = this.policy.monetization.adNetwork;
-          console.log(`   📺 [AAMP Audit] Verifying Ad Proof (Issuer: ${issuer})...`);
+          console.log(`[POLICY] 📺 Verifying Ad Proof (Issuer: ${issuer})...`);
 
           const isValidProof = await verifyJwt(proofToken, jwksUrl, issuer);
           if (isValidProof) {
-            console.log(`   ✅ [AAMP Audit] Ad Proof Signature VALID.`);
-            return { allowed: true, reason: 'OK', identityVerified, proofUsed: 'AD_PROOF_JWT' };
+            console.log(`[POLICY] ✅ Ad Proof Signature VALID.`);
+            return { allowed: true, status: 200, reason: 'OK', visitorType: 'VERIFIED_AGENT', proofUsed: 'AD_PROOF_JWT' };
           } else {
-            console.log(`   ❌ [AAMP Audit] Ad Proof Signature INVALID.`);
+            console.log(`[POLICY] ❌ Ad Proof Signature INVALID.`);
           }
         } else {
-          console.log(`   ⚠️ [AAMP Audit] Ad Proof MISSING.`);
+          console.log(`[POLICY] ⚠️ Ad Proof MISSING.`);
         }
       }
 
-      if (!paymentSatisfied) {
-        return { allowed: false, reason: 'PAYMENT_REQUIRED: Whitelist, Credential, and Ad Proof checks ALL failed.', identityVerified, proofUsed: 'NONE', visitorType: 'VERIFIED_AGENT' };
+      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,
+    requestPublicKey: CryptoKey,
+  ): 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: Clock skew too large.', identityVerified: false };
+    }
+
+    // 2. Crypto Verification
+    const signableString = JSON.stringify(request.header);
+    const isCryptoValid = await verifySignature(requestPublicKey, signableString, request.signature);
+    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(`[IDENTITY] 🔍 Verifying DNS Binding for: ${claimedDomain}`);
+
+    // Check Cache First
+    const cachedKey = await this.cache.get(claimedDomain);
+
+    if (cachedKey === pubKeyString) {
+      console.log("[IDENTITY] ⚡ Cache Hit. Identity Verified.");
+      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);
       }
     }
 
-    return { allowed: true, reason: 'OK', identityVerified };
+    if (this.policy.requireIdentityBinding && !identityVerified) {
+      return { allowed: false, reason: 'IDENTITY_FAIL: DNS Binding could not be verified.', identityVerified: false };
+    }
+
+    // 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> {

package/src/types.ts

@@ -128,7 +128,7 @@ export interface FeedbackSignal {
 // 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;