@aamp/protocol 1.1.7 → 1.1.8

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@aamp/protocol",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "TypeScript reference implementation of AAMP v1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./dist/nextjs": "./dist/nextjs.js",
+    "./dist/agent": "./dist/agent.js",
+    "./dist/types": "./dist/types.js"
+  },
   "type": "module",
   "scripts": {
     "build": "tsc",

package/src/publisher.ts

@@ -352,7 +352,7 @@ export class AAMPPublisher {
     }
 
     // Return verified status so handleAgentStrict can proceed to Policy Check
-    return { allowed: true, reason: 'OK', identityVerified: true };
+    return { allowed: true, reason: 'OK', identityVerified: identityVerified };
   }
 
   private async verifyDnsBinding(domain: string, requestKeySpki: string): Promise<boolean> {

package/dist/agent.d.ts

@@ -1,30 +0,0 @@
-/**
- * Layer 2: Agent SDK
- */
-import { AccessPurpose, SignedAccessRequest, FeedbackSignal, QualityFlag, AgentIdentityManifest } from './types.js';
-export interface AccessOptions {
-    adsDisplayed?: boolean;
-}
-export declare class AAMPAgent {
-    private keyPair;
-    agentId: string;
-    /**
-     * Initialize the Agent Identity (Ephemeral or Persisted)
-     * @param customAgentId For PRODUCTION, this should be your domain (e.g., "bot.openai.com")
-     */
-    initialize(customAgentId?: string): Promise<void>;
-    createAccessRequest(resource: string, purpose: AccessPurpose, options?: AccessOptions): Promise<SignedAccessRequest>;
-    /**
-     * Helper: Generate the JSON file you must host on your domain
-     * Host this at: https://{agentId}/.well-known/aamp-agent.json
-     */
-    getIdentityManifest(contactEmail?: string): Promise<AgentIdentityManifest>;
-    /**
-     * NEW IN V1.1: Quality Feedback Loop
-     * Allows the Agent to report spam or verify quality of a resource.
-     */
-    generateFeedback(resource: string, score: number, flags: QualityFlag[]): Promise<{
-        signal: FeedbackSignal;
-        signature: string;
-    }>;
-}

package/dist/agent.js

@@ -1,65 +0,0 @@
-import { generateKeyPair, signData, exportPublicKey } from './crypto.js';
-import { AAMP_VERSION } from './constants.js';
-export class AAMPAgent {
-    constructor() {
-        this.keyPair = null;
-        this.agentId = "pending";
-    }
-    /**
-     * Initialize the Agent Identity (Ephemeral or Persisted)
-     * @param customAgentId For PRODUCTION, this should be your domain (e.g., "bot.openai.com")
-     */
-    async initialize(customAgentId) {
-        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, purpose, options = {}) {
-        if (!this.keyPair)
-            throw new Error("Agent not initialized. Call initialize() first.");
-        const header = {
-            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 };
-    }
-    /**
-     * Helper: Generate the JSON file you must host on your domain
-     * Host this at: https://{agentId}/.well-known/aamp-agent.json
-     */
-    async getIdentityManifest(contactEmail) {
-        if (!this.keyPair)
-            throw new Error("Agent not initialized.");
-        const publicKey = await exportPublicKey(this.keyPair.publicKey);
-        return {
-            agent_id: this.agentId,
-            public_key: publicKey,
-            contact_email: contactEmail
-        };
-    }
-    /**
-     * NEW IN V1.1: Quality Feedback Loop
-     * Allows the Agent to report spam or verify quality of a resource.
-     */
-    async generateFeedback(resource, score, flags) {
-        if (!this.keyPair)
-            throw new Error("Agent not initialized.");
-        const signal = {
-            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/dist/constants.d.ts

@@ -1,25 +0,0 @@
-/**
- * Layer 1: Protocol Constants
- * These values are immutable and defined by the AAMP Specification.
- */
-export declare const AAMP_VERSION = "1.1";
-export declare const WELL_KNOWN_AGENT_PATH = "/.well-known/aamp-agent.json";
-export declare const HEADERS: {
-    readonly PAYLOAD: "x-aamp-payload";
-    readonly SIGNATURE: "x-aamp-signature";
-    readonly PUBLIC_KEY: "x-aamp-public-key";
-    readonly AGENT_ID: "x-aamp-agent-id";
-    readonly TIMESTAMP: "x-aamp-timestamp";
-    readonly ALGORITHM: "x-aamp-alg";
-    readonly CONTENT_ORIGIN: "x-aamp-content-origin";
-    readonly PROVENANCE_SIG: "x-aamp-provenance-sig";
-    readonly PROOF_TOKEN: "x-aamp-proof";
-    readonly PAYMENT_CREDENTIAL: "x-aamp-credential";
-    readonly FEEDBACK: "x-aamp-feedback";
-};
-export declare const CRYPTO_CONFIG: {
-    readonly ALGORITHM_NAME: "ECDSA";
-    readonly CURVE: "P-256";
-    readonly HASH: "SHA-256";
-};
-export declare const MAX_CLOCK_SKEW_MS: number;

package/dist/constants.js

@@ -1,38 +0,0 @@
-/**
- * Layer 1: Protocol Constants
- * These values are immutable and defined by the AAMP Specification.
- */
-export const AAMP_VERSION = '1.1';
-// The path where Agents MUST host their public key to prove identity.
-// Example: https://bot.openai.com/.well-known/aamp-agent.json
-export const WELL_KNOWN_AGENT_PATH = '/.well-known/aamp-agent.json';
-// 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',
-    // v1.2 Proof of Value
-    PROOF_TOKEN: 'x-aamp-proof',
-    // v1.2 Payment Credential (The "Digital Receipt")
-    PAYMENT_CREDENTIAL: 'x-aamp-credential',
-    // v1.2 Quality Feedback (The "Dispute Token")
-    FEEDBACK: 'x-aamp-feedback'
-};
-// Cryptographic Settings
-export const CRYPTO_CONFIG = {
-    ALGORITHM_NAME: 'ECDSA',
-    CURVE: 'P-256',
-    HASH: 'SHA-256',
-};
-// Tolerance
-export const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000; // 5 minutes

package/dist/crypto.d.ts

@@ -1,9 +0,0 @@
-/**
- * Layer 1: Cryptographic Primitives
- * Implementation of ECDSA P-256 signing/verification.
- */
-export declare function generateKeyPair(): Promise<CryptoKeyPair>;
-export declare function signData(privateKey: CryptoKey, data: string): Promise<string>;
-export declare function verifySignature(publicKey: CryptoKey, data: string, signatureHex: string): Promise<boolean>;
-export declare function exportPublicKey(key: CryptoKey): Promise<string>;
-export declare function importPublicKey(keyData: string): Promise<CryptoKey>;

package/dist/crypto.js

@@ -1,44 +0,0 @@
-/**
- * Layer 1: Cryptographic Primitives
- * Implementation of ECDSA P-256 signing/verification.
- */
-export async function generateKeyPair() {
-    // 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, data) {
-    const encoder = new TextEncoder();
-    const encoded = encoder.encode(data);
-    const signature = await crypto.subtle.sign({ name: "ECDSA", hash: { name: "SHA-256" } }, privateKey, encoded);
-    return bufToHex(signature);
-}
-export async function verifySignature(publicKey, data, signatureHex) {
-    const encoder = new TextEncoder();
-    const encodedData = encoder.encode(data);
-    const signatureBytes = hexToBuf(signatureHex);
-    console.log("   🔐 [AAMP Crypto] Verifying ECDSA P-256 Signature...");
-    const isValid = await crypto.subtle.verify({ name: "ECDSA", hash: { name: "SHA-256" } }, publicKey, signatureBytes, encodedData);
-    console.log(`   ${isValid ? "✅" : "❌"} [AAMP Crypto] Signature Result: ${isValid ? "VALID" : "INVALID"}`);
-    return isValid;
-}
-export async function exportPublicKey(key) {
-    const exported = await crypto.subtle.exportKey("spki", key);
-    return btoa(String.fromCharCode(...new Uint8Array(exported)));
-}
-export async function importPublicKey(keyData) {
-    const binaryString = atob(keyData);
-    const bytes = new Uint8Array(binaryString.length);
-    for (let i = 0; i < binaryString.length; i++) {
-        bytes[i] = binaryString.charCodeAt(i);
-    }
-    return await crypto.subtle.importKey("spki", bytes, { name: "ECDSA", namedCurve: "P-256" }, true, ["verify"]);
-}
-// Helpers
-function bufToHex(buffer) {
-    return Array.from(new Uint8Array(buffer))
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-}
-function hexToBuf(hex) {
-    return new Uint8Array(hex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
-}

package/dist/express.d.ts

@@ -1,22 +0,0 @@
-import { AccessPolicy, ContentOrigin, UnauthenticatedStrategy, IdentityCache } from './types.js';
-export interface AAMPConfig {
-    policy: Omit<AccessPolicy, 'version'>;
-    meta: {
-        origin: keyof typeof ContentOrigin;
-        paymentPointer?: string;
-    };
-    strategy?: UnauthenticatedStrategy;
-    cache?: IdentityCache;
-}
-export declare class AAMP {
-    private publisher;
-    private origin;
-    private ready;
-    private constructor();
-    static init(config: AAMPConfig): AAMP;
-    /**
-     * Express Middleware
-     */
-    middleware(): (req: any, res: any, next: any) => Promise<void>;
-    discoveryHandler(): (req: any, res: any) => void;
-}

package/dist/express.js

@@ -1,64 +0,0 @@
-/**
- * Layer 3: Framework Adapters
- * Zero-friction integration for Express/Node.js.
- */
-import { AAMPPublisher } from './publisher.js';
-import { ContentOrigin } from './types.js';
-import { generateKeyPair } from './crypto.js';
-export class AAMP {
-    constructor(config) {
-        this.publisher = new AAMPPublisher({ version: '1.1', ...config.policy }, config.strategy || 'PASSIVE', config.cache);
-        this.origin = ContentOrigin[config.meta.origin];
-        this.ready = generateKeyPair().then(keys => {
-            return this.publisher.initialize(keys);
-        });
-    }
-    static init(config) {
-        return new AAMP(config);
-    }
-    /**
-     * Express Middleware
-     */
-    middleware() {
-        return async (req, res, next) => {
-            await this.ready;
-            // Normalize headers to lowercase dictionary
-            const headers = {};
-            Object.keys(req.headers).forEach(key => {
-                headers[key.toLowerCase()] = req.headers[key];
-            });
-            // Retrieve Raw Payload if available (optional but good for crypto)
-            // Note: Express body parsing might interfere, so we usually rely on the header content.
-            const rawPayload = headers['x-aamp-payload'];
-            // Evaluate Visitor
-            const result = await this.publisher.evaluateVisitor(headers, rawPayload);
-            // Enforce Decision
-            if (!result.allowed) {
-                res.status(result.status).json({
-                    error: result.reason,
-                    visitor_type: result.visitorType,
-                    proof_used: result.proofUsed
-                });
-                return;
-            }
-            // Inject Provenance Headers (For the humans/agents that got through)
-            const respHeaders = await this.publisher.generateResponseHeaders(this.origin);
-            Object.entries(respHeaders).forEach(([k, v]) => {
-                res.setHeader(k, v);
-            });
-            // Attach metadata to request for downstream use
-            req.aamp = {
-                verified: result.visitorType === 'VERIFIED_AGENT',
-                type: result.visitorType,
-                ...result.metadata
-            };
-            next();
-        };
-    }
-    discoveryHandler() {
-        return (req, res) => {
-            res.setHeader('Content-Type', 'application/json');
-            res.send(JSON.stringify(this.publisher.getPolicy(), null, 2));
-        };
-    }
-}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/nextjs.d.ts

@@ -1,25 +0,0 @@
-import { AccessPolicy, ContentOrigin, UnauthenticatedStrategy, IdentityCache } from './types.js';
-type NextRequest = any;
-type NextResponse = any;
-export interface AAMPConfig {
-    policy: Omit<AccessPolicy, 'version'>;
-    meta: {
-        origin: keyof typeof ContentOrigin;
-        paymentPointer?: string;
-    };
-    strategy?: UnauthenticatedStrategy;
-    cache?: IdentityCache;
-}
-export declare class AAMPNext {
-    private publisher;
-    private origin;
-    private ready;
-    private constructor();
-    static init(config: AAMPConfig): AAMPNext;
-    /**
-     * Serverless Route Wrapper
-     */
-    withProtection(handler: (req: NextRequest) => Promise<NextResponse>): (req: NextRequest) => Promise<any>;
-    discoveryHandler(): () => Promise<Response>;
-}
-export {};

package/dist/nextjs.js

@@ -1,60 +0,0 @@
-/**
- * Layer 3: Framework Adapters
- * Serverless integration for Next.js (App Router & API Routes).
- */
-import { AAMPPublisher } from './publisher.js';
-import { ContentOrigin } from './types.js';
-import { generateKeyPair } from './crypto.js';
-const createJsonResponse = (body, status = 200) => {
-    return new Response(JSON.stringify(body), {
-        status,
-        headers: { 'Content-Type': 'application/json' }
-    });
-};
-export class AAMPNext {
-    constructor(config) {
-        this.publisher = new AAMPPublisher({ version: '1.1', ...config.policy }, config.strategy || 'PASSIVE', config.cache);
-        this.origin = ContentOrigin[config.meta.origin];
-        this.ready = generateKeyPair().then(keys => this.publisher.initialize(keys));
-    }
-    static init(config) {
-        return new AAMPNext(config);
-    }
-    /**
-     * Serverless Route Wrapper
-     */
-    withProtection(handler) {
-        return async (req) => {
-            await this.ready;
-            // Extract Headers map
-            const headers = {};
-            req.headers.forEach((value, key) => {
-                headers[key.toLowerCase()] = value;
-            });
-            // Evaluate
-            const result = await this.publisher.evaluateVisitor(headers, headers['x-aamp-payload']);
-            if (!result.allowed) {
-                return createJsonResponse({
-                    error: result.reason,
-                    visitor_type: result.visitorType,
-                    proof_used: result.proofUsed
-                }, result.status);
-            }
-            // Execute Handler
-            const response = await handler(req);
-            // Inject Provenance
-            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/dist/proof.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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 declare function verifyJwt(token: string, jwksUrl: string, issuer: string, audience?: string): Promise<boolean>;

package/dist/proof.js

@@ -1,27 +0,0 @@
-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, jwksUrl, issuer, audience) {
-    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/dist/publisher.d.ts

@@ -1,43 +0,0 @@
-import { AccessPolicy, ContentOrigin, EvaluationResult, IdentityCache, UnauthenticatedStrategy } from './types.js';
-export declare class AAMPPublisher {
-    private policy;
-    private keyPair;
-    private unauthenticatedStrategy;
-    private cache;
-    private readonly CACHE_TTL_SECONDS;
-    constructor(policy: AccessPolicy, strategy?: UnauthenticatedStrategy, cacheImpl?: IdentityCache);
-    initialize(keyPair: CryptoKeyPair): Promise<void>;
-    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>;
-    /**
-     * Browser Heuristics (Hardened)
-     * 1. Checks Known Bot Signatures (Fast Fail)
-     * 2. Checks Trusted Upstream Signals (Cloudflare/Vercel)
-     * 3. Checks Browser Header Consistency
-     */
-    private performBrowserHeuristics;
-    /**
-     * Handle AAMP Protocol Logic (Strict Mode)
-     */
-    private handleAgentStrict;
-    private handleAgent;
-    /**
-     * STAGE 2: POLICY ENFORCEMENT CHECK
-     */
-    private checkPolicyStrict;
-    private verifyRequestLogic;
-    private verifyDnsBinding;
-    private isDomain;
-    generateResponseHeaders(origin: ContentOrigin): Promise<Record<string, string>>;
-    /**
-     * Handling Quality Feedback (The "Dispute" Layer)
-     * This runs when an Agent sends 'x-aamp-feedback'.
-     */
-    private handleFeedback;
-}

package/dist/publisher.js

@@ -1,350 +0,0 @@
-/**
- * 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.js';
-import { exportPublicKey, signData, verifySignature } from './crypto.js';
-import { AccessPurpose } from './types.js';
-import { verifyJwt } from './proof.js';
-/**
- * Default In-Memory Cache (Fallback only)
- * NOT recommended for high-traffic Serverless production.
- */
-class MemoryCache {
-    constructor() {
-        this.store = new Map();
-    }
-    async get(key) {
-        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, value, ttlSeconds) {
-        this.store.set(key, {
-            val: value,
-            exp: Date.now() + (ttlSeconds * 1000)
-        });
-    }
-}
-export class AAMPPublisher {
-    constructor(policy, strategy = 'PASSIVE', cacheImpl) {
-        this.keyPair = null;
-        // Default TTL: 1 Hour
-        this.CACHE_TTL_SECONDS = 3600;
-        this.policy = policy;
-        this.unauthenticatedStrategy = strategy;
-        this.cache = cacheImpl || new MemoryCache();
-    }
-    async initialize(keyPair) {
-        this.keyPair = keyPair;
-    }
-    getPolicy() {
-        return this.policy;
-    }
-    /**
-     * 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) {
-        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) {
-            // It claims to be an Agent. Verify it STRICTLY.
-            return await this.handleAgentStrict(reqHeaders, rawPayload);
-        }
-        // 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: "IDENTITY_REQUIRED: Missing AAMP Headers.",
-                visitorType: 'UNIDENTIFIED_BOT'
-            };
-        }
-        console.log(`[IDENTITY] ⚠️ SKIPPED (Legacy Mode). Checking Browser Heuristics...`);
-        const isHuman = this.performBrowserHeuristics(reqHeaders);
-        if (isHuman) {
-            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)
-     * 1. Checks Known Bot Signatures (Fast Fail)
-     * 2. Checks Trusted Upstream Signals (Cloudflare/Vercel)
-     * 3. Checks Browser Header Consistency
-     */
-    performBrowserHeuristics(headers) {
-        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;
-        }
-        // B. Trusted Infrastructure Signals (The Real World Solution)
-        if (headers['cf-visitor'] || headers['cf-ray'])
-            return true;
-        if (headers['x-vercel-id'])
-            return true;
-        if (headers['cloudfront-viewer-address'])
-            return true;
-        // C. The "Browser Fingerprint" (Fallback for direct connections)
-        const hasAcceptLanguage = !!headers['accept-language'];
-        const hasSecFetchDest = !!headers['sec-fetch-dest'];
-        const hasUpgradeInsecure = !!headers['upgrade-insecure-requests'];
-        if (hasAcceptLanguage && (hasSecFetchDest || hasUpgradeInsecure)) {
-            return true;
-        }
-        return false;
-    }
-    /**
-     * Handle AAMP Protocol Logic (Strict Mode)
-     */
-    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];
-            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,
-                proofUsed: policyResult.proofUsed
-            };
-        }
-        catch (e) {
-            console.error(`[AAMP ERROR]`, e);
-            return { allowed: false, status: 400, reason: "INVALID_SIGNATURE", visitorType: 'UNIDENTIFIED_BOT' };
-        }
-    }
-    // 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 (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' };
-    }
-    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);
-            }
-        }
-        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 {
-            // 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;
-            }
-            const manifest = await response.json();
-            console.log(`   📄 [AAMP DNS] Manifest received. Agent ID: ${manifest.agent_id}`);
-            // CHECK 1: Does the manifest actually belong to the domain?
-            if (manifest.agent_id !== domain) {
-                console.log(`   ❌ [AAMP DNS] Mismatch: Manifest ID ${manifest.agent_id} != Claimed ${domain}`);
-                return false;
-            }
-            // 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] Identity Confirmed.`);
-            return true;
-        }
-        catch (e) {
-            console.log(`   ❌ [AAMP DNS] Error: ${e.message}`);
-            return false;
-        }
-    }
-    isDomain(s) {
-        // Basic regex, allows localhost with ports
-        return /^[a-zA-Z0-9.-]+(:\d+)?$/.test(s) || /^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(s);
-    }
-    async generateResponseHeaders(origin) {
-        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
-        };
-    }
-    /**
-     * Handling Quality Feedback (The "Dispute" Layer)
-     * This runs when an Agent sends 'x-aamp-feedback'.
-     */
-    async handleFeedback(token, headers) {
-        // 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/dist/types.d.ts

@@ -1,113 +0,0 @@
-/**
- * Layer 1: Protocol Definitions
- * Shared types used by both Agent and Publisher.
- */
-export declare enum AccessPurpose {
-    CRAWL_TRAINING = "CRAWL_TRAINING",
-    RAG_RETRIEVAL = "RAG_RETRIEVAL",
-    SUMMARY = "SUMMARY",
-    QUOTATION = "QUOTATION",
-    EMBEDDING = "EMBEDDING"
-}
-export declare enum ContentOrigin {
-    HUMAN = "HUMAN",// Created by humans. High training value.
-    SYNTHETIC = "SYNTHETIC",// Created by AI. Risk of model collapse.
-    HYBRID = "HYBRID"
-}
-export declare 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;
-    public_key: string;
-    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>;
-    set(key: string, value: string, ttlSeconds: number): Promise<void>;
-}
-/**
- * Optional Monetization (The Settlement Layer)
- */
-/**
- * Optional Monetization (The Settlement Layer)
- */
-export interface MonetizationConfig {
-    checkPayment?: (agentId: string, purpose: string) => boolean | Promise<boolean>;
-    adNetwork?: {
-        jwksUrl: string;
-        issuer: string;
-    };
-    paymentConfig?: {
-        jwksUrl: string;
-        issuer: 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;
-    allowAdSupportedAccess: boolean;
-    requiresPayment: boolean;
-    paymentPointer?: string;
-    requireIdentityBinding?: boolean;
-    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;
-}
-export interface EvaluationResult {
-    allowed: boolean;
-    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;
-}
-export interface FeedbackSignalToken {
-    url: string;
-    agent_id: string;
-    quality_score: number;
-    reason: string;
-    timestamp: number;
-}

package/dist/types.js

@@ -1,25 +0,0 @@
-/**
- * Layer 1: Protocol Definitions
- * Shared types used by both Agent and Publisher.
- */
-export var AccessPurpose;
-(function (AccessPurpose) {
-    AccessPurpose["CRAWL_TRAINING"] = "CRAWL_TRAINING";
-    AccessPurpose["RAG_RETRIEVAL"] = "RAG_RETRIEVAL";
-    AccessPurpose["SUMMARY"] = "SUMMARY";
-    AccessPurpose["QUOTATION"] = "QUOTATION";
-    AccessPurpose["EMBEDDING"] = "EMBEDDING";
-})(AccessPurpose || (AccessPurpose = {}));
-export var ContentOrigin;
-(function (ContentOrigin) {
-    ContentOrigin["HUMAN"] = "HUMAN";
-    ContentOrigin["SYNTHETIC"] = "SYNTHETIC";
-    ContentOrigin["HYBRID"] = "HYBRID"; // Edited by humans, drafted by AI.
-})(ContentOrigin || (ContentOrigin = {}));
-export var QualityFlag;
-(function (QualityFlag) {
-    QualityFlag["SEO_SPAM"] = "SEO_SPAM";
-    QualityFlag["INACCURATE"] = "INACCURATE";
-    QualityFlag["HATE_SPEECH"] = "HATE_SPEECH";
-    QualityFlag["HIGH_QUALITY"] = "HIGH_QUALITY";
-})(QualityFlag || (QualityFlag = {}));