@aamp/protocol 1.1.2 → 1.1.4

package/dist/types.d.ts

@@ -21,31 +21,37 @@ export declare enum QualityFlag {
     HIGH_QUALITY = "HIGH_QUALITY"
 }
 /**
- * Optional Rate Limiting (The Speed Limit)
- * Defines technical boundaries for the handshake.
+ * DNS Identity Manifest
+ * Hosted at: https://{agent_id}/.well-known/aamp-agent.json
  */
-export interface RateLimitConfig {
-    requestsPerMinute: number;
-    tokensPerMinute?: number;
+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)
- *
- * AAMP is neutral. Settlement can happen via:
- * 1. BROKER: A 3rd party clearing house (e.g., "AI-AdSense").
- * 2. CRYPTO: Direct on-chain settlement.
- * 3. TREATY: A private legal contract signed offline (Enterprise).
  */
 export interface MonetizationConfig {
     method: 'BROKER' | 'CRYPTO' | 'PRIVATE_TREATY';
-    /**
-     * The destination for settlement.
-     * - If BROKER: The API URL of the clearing house.
-     * - If CRYPTO: The wallet address.
-     * - If TREATY: The Contract ID or "Contact Sales".
-     */
     location: 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;
@@ -54,7 +60,7 @@ export interface AccessPolicy {
     allowAdSupportedAccess: boolean;
     requiresPayment: boolean;
     paymentPointer?: string;
-    rateLimit?: RateLimitConfig;
+    requireIdentityBinding?: boolean;
     monetization?: MonetizationConfig;
 }
 export interface ProtocolHeader {
@@ -79,3 +85,10 @@ export interface FeedbackSignal {
     flags: QualityFlag[];
     timestamp: string;
 }
+export interface EvaluationResult {
+    allowed: boolean;
+    status: 200 | 400 | 401 | 403;
+    reason: string;
+    visitorType: 'VERIFIED_AGENT' | 'LIKELY_HUMAN' | 'UNIDENTIFIED_BOT';
+    metadata?: any;
+}

package/package.json

@@ -1,24 +1,24 @@
-{
-  "name": "@aamp/protocol",
-  "version": "1.1.2",
-  "description": "TypeScript reference implementation of AAMP",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "ts-node test/handshake.spec.ts",
-    "prepublishOnly": "npm run test && npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/aamp-protocol/aamp.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "ts-node": "^10.9.0",
-    "@types/node": "^20.0.0"
-  }
+{
+  "name": "@aamp/protocol",
+  "version": "1.1.4",
+  "description": "TypeScript reference implementation of AAMP v1.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "ts-node test/handshake.spec.ts",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aamp-protocol/aamp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "ts-node": "^10.9.0",
+    "@types/node": "^20.0.0"
+  }
 }

package/src/agent.ts

@@ -1,72 +1,88 @@
-/**
- * Layer 2: Agent SDK
- */
-import { AccessPurpose, ProtocolHeader, SignedAccessRequest, FeedbackSignal, QualityFlag } from './types';
-import { generateKeyPair, signData, exportPublicKey } from './crypto';
-import { AAMP_VERSION } from './constants';
-
-export interface AccessOptions {
-  adsDisplayed?: boolean;
-}
-
-export class AAMPAgent {
-  private keyPair: CryptoKeyPair | null = null;
-  public agentId: string = "pending";
-
-  /**
-   * Initialize the Agent Identity (Ephemeral or Persisted)
-   * @param customAgentId Optional persistent ID for this agent. If omitted, generates a session ID.
-   */
-  async initialize(customAgentId?: string) {
-    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: string, 
-    purpose: AccessPurpose, 
-    options: AccessOptions = {}
-  ): Promise<SignedAccessRequest> {
-    if (!this.keyPair) throw new Error("Agent not initialized. Call initialize() first.");
-
-    const header: ProtocolHeader = {
-      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 };
-  }
-
-  /**
-   * NEW IN V1.1: Quality Feedback Loop
-   * Allows the Agent to report spam or verify quality of a resource.
-   */
-  async generateFeedback(
-    resource: string,
-    score: number,
-    flags: QualityFlag[]
-  ): Promise<{ signal: FeedbackSignal, signature: string }> {
-    if (!this.keyPair) throw new Error("Agent not initialized.");
-    
-    const signal: FeedbackSignal = {
-      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 };
-  }
+/**
+ * Layer 2: Agent SDK
+ */
+import { AccessPurpose, ProtocolHeader, SignedAccessRequest, FeedbackSignal, QualityFlag, AgentIdentityManifest } from './types';
+import { generateKeyPair, signData, exportPublicKey } from './crypto';
+import { AAMP_VERSION } from './constants';
+
+export interface AccessOptions {
+  adsDisplayed?: boolean;
+}
+
+export class AAMPAgent {
+  private keyPair: CryptoKeyPair | null = null;
+  public agentId: string = "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?: string) {
+    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: string, 
+    purpose: AccessPurpose, 
+    options: AccessOptions = {}
+  ): Promise<SignedAccessRequest> {
+    if (!this.keyPair) throw new Error("Agent not initialized. Call initialize() first.");
+
+    const header: ProtocolHeader = {
+      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?: string): Promise<AgentIdentityManifest> {
+    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: string,
+    score: number,
+    flags: QualityFlag[]
+  ): Promise<{ signal: FeedbackSignal, signature: string }> {
+    if (!this.keyPair) throw new Error("Agent not initialized.");
+    
+    const signal: FeedbackSignal = {
+      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/src/constants.ts

@@ -1,35 +1,39 @@
-/**
- * Layer 1: Protocol Constants
- * These values are immutable and defined by the AAMP Specification.
- */
-
-export const AAMP_VERSION = '1.1';
-
-// 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'
-} as const;
-
-// Cryptographic Settings
-export const CRYPTO_CONFIG = {
-  ALGORITHM_NAME: 'ECDSA',
-  CURVE: 'P-256',
-  HASH: 'SHA-256',
-} as const;
-
-// Tolerance
+/**
+ * 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'
+} 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

@@ -1,69 +1,69 @@
-/**
- * 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);
-
-  return await crypto.subtle.verify(
-    { name: "ECDSA", hash: { name: "SHA-256" } },
-    publicKey,
-    signatureBytes as any,
-    encodedData as any
-  );
-}
-
-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)));
+/**
+ * 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);
+
+  return await crypto.subtle.verify(
+    { name: "ECDSA", hash: { name: "SHA-256" } },
+    publicKey,
+    signatureBytes as any,
+    encodedData as any
+  );
+}
+
+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)));
 }