@imagxp/protocol 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# @imagxp/protocol
+
+The official TypeScript reference implementation of the **Identity Monetization Auto Governance Exchange Protocol (IMAGXP)**.
+
+IMAGXP is an open standard that enables "Transactional Content Negotiation" between AI Agents and Web Publishers, replacing `robots.txt` with cryptographic signatures and micro-payments.
+
+**Keywords:** `imagxp`, `aamp`, `protocol`, `ai agent`, `web monetization`, `content negotiation`, `rag`, `llm`, `crawler`, `publisher tool`
+
+**Website:** https://imagxp.com (Coming Soon)  
+**Repository:** [GitHub](https://github.com/imagxp-protocol/imagxp)
+
+## 📦 Installation
+
+```bash
+npm install @imagxp/protocol
+# Optional: Install 'jose' for crypto signing if you are building a custom implementation
+npm install jose
+```
+
+## 🚀 Usage
+
+### 1. For AI Agents (Clients)
+
+Use `IMAGXPAgent` to crawl websites with automatic protocol negotiation.
+
+```typescript
+import { IMAGXPAgent } from '@imagxp/protocol';
+
+async function main() {
+    // 1. Initialize Identity (Loads from IMAGXP_PRIVATE_KEY env var)
+    const agent = await IMAGXPAgent.init();
+
+    // 2. Fetch URL (Automatically signs request if IMAGXP is detected)
+    const response = await agent.fetch('https://example.com/article', {
+        purpose: 'RAG_RETRIEVAL'
+    });
+
+    if (response.status === 200) {
+        console.log('Success:', response.data);
+    } else {
+        console.error('Blocked:', response.status);
+    }
+}
+```
+
+### 2. For Publishers (Next.js Middleware)
+
+Use `IMAGXPNext` to protect your routes.
+
+```typescript
+// src/middleware.ts
+import { IMAGXPNext } from '@imagxp/protocol';
+import { NextResponse } from 'next/server';
+
+const imagxp = IMAGXPNext.init({
+    meta: {
+        origin: 'HUMAN',
+        paymentPointer: '$wallet.example.com'
+    },
+    policy: {
+        // Security: Verify DNS Binding
+        requireIdentityBinding: true, 
+        
+        // Economics: Connect to Broker
+        monetization: {
+            brokerUrl: "https://broker.imagxp.network"
+        }
+    }
+});
+
+// Create the middleware handler
+export const middleware = imagxp.withProtection(async (req) => {
+    return NextResponse.next();
+});
+
+export const config = {
+    matcher: ['/api/premium/:path*', '/articles/:path*']
+};
+```
+
+## 🔑 Key Features
+
+- **Zero Dependencies:** The core logic is dependency-free.
+- **Isomorphic:** Works in Node.js, Edge Runtime (Vercel/Cloudflare), and Browsers.
+- **Cryptographically Secure:** Implements ECDSA P-256 signatures and JSON Web Tokens.
+- **Type Safe:** Written in strict TypeScript with full definition files included.
+
+## 📚 API Reference
+
+### `IMAGXPAgent`
+- `init(options?)`: Create a new agent instance.
+- `fetch(url, options)`: IMAGXP-aware fetch wrapper.
+- `sendFeedback(url, feedback)`: Send Quality/Spam reports.
+
+### `IMAGXPNext` (Adapter)
+- `init(config)`: Configure the Publisher Policy Engine.
+- `withProtection(handler)`: Wrap a Next.js Middleware or Route Handler.
+
+## 📄 License
+
+Apache 2.0
+
+By the IMAGXP Community.

package/dist/agent.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Layer 2: Agent SDK
+ */
+import { AccessPurpose, SignedAccessRequest, FeedbackSignal, QualityFlag, AgentIdentityManifest } from './types.js';
+export interface AccessOptions {
+    adsDisplayed?: boolean;
+}
+export declare class IMAGXPAgent {
+    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/imagxp-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

@@ -0,0 +1,65 @@
+import { generateKeyPair, signData, exportPublicKey } from './crypto.js';
+import { IMAGXP_VERSION } from './constants.js';
+export class IMAGXPAgent {
+    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: IMAGXP_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/imagxp-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

@@ -0,0 +1,25 @@
+/**
+ * Layer 1: Protocol Constants
+ * These values are immutable and defined by the IMAGXP Specification.
+ */
+export declare const IMAGXP_VERSION = "1.1";
+export declare const WELL_KNOWN_AGENT_PATH = "/.well-known/imagxp-agent.json";
+export declare const HEADERS: {
+    readonly PAYLOAD: "x-imagxp-payload";
+    readonly SIGNATURE: "x-imagxp-signature";
+    readonly PUBLIC_KEY: "x-imagxp-public-key";
+    readonly AGENT_ID: "x-imagxp-agent-id";
+    readonly TIMESTAMP: "x-imagxp-timestamp";
+    readonly ALGORITHM: "x-imagxp-alg";
+    readonly CONTENT_ORIGIN: "x-imagxp-content-origin";
+    readonly PROVENANCE_SIG: "x-imagxp-provenance-sig";
+    readonly PROOF_TOKEN: "x-imagxp-proof";
+    readonly PAYMENT_CREDENTIAL: "x-imagxp-credential";
+    readonly FEEDBACK: "x-imagxp-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

@@ -0,0 +1,38 @@
+/**
+ * Layer 1: Protocol Constants
+ * These values are immutable and defined by the IMAGXP Specification.
+ */
+export const IMAGXP_VERSION = '1.1';
+// The path where Agents MUST host their public key to prove identity.
+// Example: https://bot.openai.com/.well-known/imagxp-agent.json
+export const WELL_KNOWN_AGENT_PATH = '/.well-known/imagxp-agent.json';
+// HTTP Headers used for the handshake
+export const HEADERS = {
+    // Transport: The signed payload (Base64 encoded JSON of ProtocolHeader)
+    PAYLOAD: 'x-imagxp-payload',
+    // Transport: The cryptographic signature (Hex)
+    SIGNATURE: 'x-imagxp-signature',
+    // Transport: The Agent's Public Key (Base64 SPKI)
+    PUBLIC_KEY: 'x-imagxp-public-key',
+    // Informational / Legacy (Optional if Payload is present)
+    AGENT_ID: 'x-imagxp-agent-id',
+    TIMESTAMP: 'x-imagxp-timestamp',
+    ALGORITHM: 'x-imagxp-alg',
+    // v1.1 Addition: Provenance (Server to Agent)
+    CONTENT_ORIGIN: 'x-imagxp-content-origin',
+    PROVENANCE_SIG: 'x-imagxp-provenance-sig',
+    // v1.2 Proof of Value
+    PROOF_TOKEN: 'x-imagxp-proof',
+    // v1.2 Payment Credential (The "Digital Receipt")
+    PAYMENT_CREDENTIAL: 'x-imagxp-credential',
+    // v1.2 Quality Feedback (The "Dispute Token")
+    FEEDBACK: 'x-imagxp-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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,44 @@
+/**
+ * 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("   🔐 [IMAGXP Crypto] Verifying ECDSA P-256 Signature...");
+    const isValid = await crypto.subtle.verify({ name: "ECDSA", hash: { name: "SHA-256" } }, publicKey, signatureBytes, encodedData);
+    console.log(`   ${isValid ? "✅" : "❌"} [IMAGXP 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

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

package/dist/express.js

@@ -0,0 +1,64 @@
+/**
+ * Layer 3: Framework Adapters
+ * Zero-friction integration for Express/Node.js.
+ */
+import { IMAGXPPublisher } from './publisher.js';
+import { ContentOrigin } from './types.js';
+import { generateKeyPair } from './crypto.js';
+export class IMAGXP {
+    constructor(config) {
+        this.publisher = new IMAGXPPublisher({ 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 IMAGXP(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-imagxp-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

@@ -0,0 +1,12 @@
+/**
+ * IMAGXP 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 { IMAGXPNext } from './nextjs.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * IMAGXP 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 { IMAGXPNext } from './nextjs.js'; // Serverless / Next.js Adapter

package/dist/nextjs.d.ts

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

package/dist/nextjs.js

@@ -0,0 +1,60 @@
+/**
+ * Layer 3: Framework Adapters
+ * Serverless integration for Next.js (App Router & API Routes).
+ */
+import { IMAGXPPublisher } 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 IMAGXPNext {
+    constructor(config) {
+        this.publisher = new IMAGXPPublisher({ 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 IMAGXPNext(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-imagxp-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 imagxpHeaders = await this.publisher.generateResponseHeaders(this.origin);
+            if (response && response.headers) {
+                Object.entries(imagxpHeaders).forEach(([k, v]) => {
+                    response.headers.set(k, v);
+                });
+            }
+            return response;
+        };
+    }
+    discoveryHandler() {
+        return async () => {
+            return createJsonResponse(this.publisher.getPolicy());
+        };
+    }
+}

package/dist/proof.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,27 @@
+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 IMAGXP 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

@@ -0,0 +1,48 @@
+import { AccessPolicy, ContentOrigin, EvaluationResult, IdentityCache, UnauthenticatedStrategy } from './types.js';
+export declare class IMAGXPPublisher {
+    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 IMAGXP Protocol Logic (Strict Mode)
+     */
+    private handleAgentStrict;
+    private handleAgent;
+    /**
+     * STAGE 2: POLICY ENFORCEMENT CHECK
+     */
+    private checkPolicyStrict;
+    private verifyRequestLogic;
+    private verifyDnsBinding;
+    /**
+     * NEW: Verify a Broker-Issued Token (JWT)
+     * Checks if the request contains a valid "Visa" from the Broker.
+     */
+    private verifyBrokerCred;
+    private isDomain;
+    generateResponseHeaders(origin: ContentOrigin): Promise<Record<string, string>>;
+    /**
+     * Handling Quality Feedback (The "Dispute" Layer)
+     * This runs when an Agent sends 'x-imagxp-feedback'.
+     */
+    private handleFeedback;
+}