@imagxp/protocol 1.0.0

package/src/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * 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'
+} as const;
+
+// Cryptographic Settings
+export const CRYPTO_CONFIG = {
+  ALGORITHM_NAME: 'ECDSA',
+  CURVE: 'P-256',
+  HASH: 'SHA-256',
+} as const;
+
+// Tolerance
+export const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000; // 5 minutes

package/src/crypto.ts

@@ -0,0 +1,74 @@
+/**
+ * Layer 1: Cryptographic Primitives
+ * Implementation of ECDSA P-256 signing/verification.
+ */
+
+export async function generateKeyPair(): Promise<CryptoKeyPair> {
+  // 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: CryptoKey, data: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const encoded = encoder.encode(data);
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: { name: "SHA-256" } },
+    privateKey,
+    encoded as any
+  );
+  return bufToHex(signature);
+}
+
+export async function verifySignature(publicKey: CryptoKey, data: string, signatureHex: string): Promise<boolean> {
+  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 as any,
+    encodedData as any
+  );
+
+  console.log(`   ${isValid ? "✅" : "❌"} [IMAGXP Crypto] Signature Result: ${isValid ? "VALID" : "INVALID"}`);
+  return isValid;
+}
+
+export async function exportPublicKey(key: CryptoKey): Promise<string> {
+  const exported = await crypto.subtle.exportKey("spki", key);
+  return btoa(String.fromCharCode(...new Uint8Array(exported)));
+}
+
+export async function importPublicKey(keyData: string): Promise<CryptoKey> {
+  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: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function hexToBuf(hex: string): Uint8Array {
+  return new Uint8Array(hex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
+}

package/src/express.ts

@@ -0,0 +1,96 @@
+/**
+ * Layer 3: Framework Adapters
+ * Zero-friction integration for Express/Node.js.
+ */
+import { IMAGXPPublisher } from './publisher.js';
+import { AccessPolicy, ContentOrigin, UnauthenticatedStrategy, IdentityCache } from './types.js';
+import { generateKeyPair } from './crypto.js';
+
+export interface IMAGXPConfig {
+  policy: Omit<AccessPolicy, 'version'>;
+  meta: {
+    origin: keyof typeof ContentOrigin;
+    paymentPointer?: string;
+  };
+  strategy?: UnauthenticatedStrategy;
+  // Optional: Provide a Redis/Memcached adapter here for production
+  cache?: IdentityCache;
+}
+
+export class IMAGXP {
+  private publisher: IMAGXPPublisher;
+  private origin: ContentOrigin;
+  private ready: Promise<void>;
+
+  private constructor(config: IMAGXPConfig) {
+    this.publisher = new IMAGXPPublisher(
+      { version: '1.1', ...config.policy } as AccessPolicy,
+      config.strategy || 'PASSIVE',
+      config.cache
+    );
+
+    this.origin = ContentOrigin[config.meta.origin];
+
+    this.ready = generateKeyPair().then(keys => {
+      return this.publisher.initialize(keys);
+    });
+  }
+
+  static init(config: IMAGXPConfig): IMAGXP {
+    return new IMAGXP(config);
+  }
+
+  /**
+   * Express Middleware
+   */
+  middleware() {
+    return async (req: any, res: any, next: any) => {
+      await this.ready;
+
+      // Normalize headers to lowercase dictionary
+      const headers: Record<string, string> = {};
+      Object.keys(req.headers).forEach(key => {
+        headers[key.toLowerCase()] = req.headers[key] as string;
+      });
+
+      // 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: any, res: any) => {
+      res.setHeader('Content-Type', 'application/json');
+      res.send(JSON.stringify(this.publisher.getPolicy(), null, 2));
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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/src/nextjs.ts

@@ -0,0 +1,94 @@
+/**
+ * Layer 3: Framework Adapters
+ * Serverless integration for Next.js (App Router & API Routes).
+ */
+import { IMAGXPPublisher } from './publisher.js';
+import { AccessPolicy, ContentOrigin, UnauthenticatedStrategy, IdentityCache } from './types.js';
+import { generateKeyPair } from './crypto.js';
+
+type NextRequest = any;
+type NextResponse = any;
+
+const createJsonResponse = (body: any, status = 200) => {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+};
+
+export interface IMAGXPConfig {
+  policy: Omit<AccessPolicy, 'version'>;
+  meta: {
+    origin: keyof typeof ContentOrigin;
+    paymentPointer?: string;
+  };
+  strategy?: UnauthenticatedStrategy;
+  // Optional: Provide a KV/Redis adapter here for production
+  cache?: IdentityCache;
+}
+
+export class IMAGXPNext {
+  private publisher: IMAGXPPublisher;
+  private origin: ContentOrigin;
+  private ready: Promise<void>;
+
+  private constructor(config: IMAGXPConfig) {
+    this.publisher = new IMAGXPPublisher(
+      { version: '1.1', ...config.policy } as AccessPolicy,
+      config.strategy || 'PASSIVE',
+      config.cache
+    );
+    this.origin = ContentOrigin[config.meta.origin];
+    this.ready = generateKeyPair().then(keys => this.publisher.initialize(keys));
+  }
+
+  static init(config: IMAGXPConfig): IMAGXPNext {
+    return new IMAGXPNext(config);
+  }
+
+
+  /**
+   * Serverless Route Wrapper
+   */
+  withProtection(handler: (req: NextRequest) => Promise<NextResponse>) {
+    return async (req: NextRequest) => {
+      await this.ready;
+
+      // Extract Headers map
+      const headers: Record<string, string> = {};
+      req.headers.forEach((value: string, key: string) => {
+        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/src/proof.ts

@@ -0,0 +1,36 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+// In-memory cache for JWKS to avoid repeated fetches
+// Jose's createRemoteJWKSet handles caching/cooldowns internally.
+
+/**
+ * Verifies a JWT (Proof Token or Payment Credential) using JWKS.
+ * 
+ * @param token The JWT string 
+ * @param jwksUrl The URL to fetch Public Keys
+ * @param issuer The expected issuer
+ * @param audience The expected audience range
+ */
+export async function verifyJwt(
+    token: string,
+    jwksUrl: string,
+    issuer: string,
+    audience?: string
+): Promise<boolean> {
+    try {
+        const JWKS = createRemoteJWKSet(new URL(jwksUrl));
+
+        const { payload } = await jwtVerify(token, JWKS, {
+            issuer: issuer,
+            audience: audience // specific audience check if provided
+        });
+
+        // Check specific 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;
+    }
+}