@aamp/protocol 1.1.0 → 1.1.2

package/dist/{src/crypto.d.ts → crypto.d.ts}

@@ -6,3 +6,4 @@ 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/{src/crypto.js → crypto.js}

@@ -8,6 +8,7 @@ exports.generateKeyPair = generateKeyPair;
 exports.signData = signData;
 exports.verifySignature = verifySignature;
 exports.exportPublicKey = exportPublicKey;
+exports.importPublicKey = importPublicKey;
 async function generateKeyPair() {
     // Uses standard Web Crypto API (Node 19+ compatible)
     return await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
@@ -28,6 +29,14 @@ async function exportPublicKey(key) {
     const exported = await crypto.subtle.exportKey("spki", key);
     return btoa(String.fromCharCode(...new Uint8Array(exported)));
 }
+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))

package/package.json

@@ -1,24 +1,24 @@
-{
-  "name": "@aamp/protocol",
-  "version": "1.1.0",
-  "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.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"
+  }
 }

package/src/agent.ts

@@ -1,72 +1,72 @@
-/**
- * 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 } 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 };
+  }
 }

package/src/constants.ts

@@ -1,35 +1,35 @@
-/**
- * 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';
+
+// 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,53 +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)));
-}
-
-// 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)));
 }

package/src/express.ts

@@ -1,104 +1,104 @@
-/**
- * Layer 3: Framework Adapters
- * Zero-friction integration for Express/Node.js.
- */
-import { AAMPPublisher } from './publisher';
-import { AccessPolicy, ContentOrigin, SignedAccessRequest } from './types';
-import { generateKeyPair, verifySignature } from './crypto';
-import { HEADERS } from './constants';
-
-export interface AAMPConfig {
-  policy: Omit<AccessPolicy, 'version'>;
-  meta: {
-    origin: keyof typeof ContentOrigin;
-    paymentPointer?: string;
-  };
-}
-
-export class AAMP {
-  private publisher: AAMPPublisher;
-  private origin: ContentOrigin;
-  private ready: Promise<void>;
-
-  private constructor(config: AAMPConfig) {
-    this.publisher = new AAMPPublisher({
-      version: '1.1',
-      ...config.policy
-    } as AccessPolicy);
-    
-    this.origin = ContentOrigin[config.meta.origin];
-    
-    this.ready = generateKeyPair().then(keys => {
-      return this.publisher.initialize(keys);
-    });
-  }
-
-  static init(config: AAMPConfig): AAMP {
-    return new AAMP(config);
-  }
-
-  /**
-   * Express Middleware
-   */
-  middleware() {
-    return async (req: any, res: any, next: any) => {
-      await this.ready;
-
-      // 1. Inject Provenance Headers (Passive Protection)
-      const headers = await this.publisher.generateResponseHeaders(this.origin);
-      Object.entries(headers).forEach(([k, v]) => {
-        res.setHeader(k, v);
-      });
-
-      // 2. Active Verification (If Agent sends signed headers)
-      const payloadHeader = req.headers[HEADERS.PAYLOAD];
-      const sigHeader = req.headers[HEADERS.SIGNATURE];
-      const keyHeader = req.headers[HEADERS.PUBLIC_KEY];
-
-      if (payloadHeader && sigHeader && keyHeader) {
-        try {
-          const headerJson = atob(payloadHeader); // RAW STRING
-          const requestHeader = JSON.parse(headerJson);
-          
-          const signedRequest: SignedAccessRequest = {
-            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"]
-          );
-
-          // Pass raw headerJson to ensure signature matches exactly what was signed
-          const result = await this.publisher.verifyRequest(signedRequest, agentKey, headerJson);
-
-          if (!result.allowed) {
-            res.status(403).json({ error: result.reason });
-            return;
-          }
-
-          // Verified!
-          req.aamp = { verified: true, ...requestHeader };
-
-        } catch (e) {
-          res.status(400).json({ error: "Invalid AAMP Signature" });
-          return;
-        }
-      }
-
-      next();
-    };
-  }
-
-  discoveryHandler() {
-    return (req: any, res: any) => {
-      res.setHeader('Content-Type', 'application/json');
-      res.send(JSON.stringify(this.publisher.getPolicy(), null, 2));
-    };
-  }
+/**
+ * Layer 3: Framework Adapters
+ * Zero-friction integration for Express/Node.js.
+ */
+import { AAMPPublisher } from './publisher';
+import { AccessPolicy, ContentOrigin, SignedAccessRequest } from './types';
+import { generateKeyPair, verifySignature } from './crypto';
+import { HEADERS } from './constants';
+
+export interface AAMPConfig {
+  policy: Omit<AccessPolicy, 'version'>;
+  meta: {
+    origin: keyof typeof ContentOrigin;
+    paymentPointer?: string;
+  };
+}
+
+export class AAMP {
+  private publisher: AAMPPublisher;
+  private origin: ContentOrigin;
+  private ready: Promise<void>;
+
+  private constructor(config: AAMPConfig) {
+    this.publisher = new AAMPPublisher({
+      version: '1.1',
+      ...config.policy
+    } as AccessPolicy);
+    
+    this.origin = ContentOrigin[config.meta.origin];
+    
+    this.ready = generateKeyPair().then(keys => {
+      return this.publisher.initialize(keys);
+    });
+  }
+
+  static init(config: AAMPConfig): AAMP {
+    return new AAMP(config);
+  }
+
+  /**
+   * Express Middleware
+   */
+  middleware() {
+    return async (req: any, res: any, next: any) => {
+      await this.ready;
+
+      // 1. Inject Provenance Headers (Passive Protection)
+      const headers = await this.publisher.generateResponseHeaders(this.origin);
+      Object.entries(headers).forEach(([k, v]) => {
+        res.setHeader(k, v);
+      });
+
+      // 2. Active Verification (If Agent sends signed headers)
+      const payloadHeader = req.headers[HEADERS.PAYLOAD];
+      const sigHeader = req.headers[HEADERS.SIGNATURE];
+      const keyHeader = req.headers[HEADERS.PUBLIC_KEY];
+
+      if (payloadHeader && sigHeader && keyHeader) {
+        try {
+          const headerJson = atob(payloadHeader); // RAW STRING
+          const requestHeader = JSON.parse(headerJson);
+          
+          const signedRequest: SignedAccessRequest = {
+            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"]
+          );
+
+          // Pass raw headerJson to ensure signature matches exactly what was signed
+          const result = await this.publisher.verifyRequest(signedRequest, agentKey, headerJson);
+
+          if (!result.allowed) {
+            res.status(403).json({ error: result.reason });
+            return;
+          }
+
+          // Verified!
+          req.aamp = { verified: true, ...requestHeader };
+
+        } catch (e) {
+          res.status(400).json({ error: "Invalid AAMP Signature" });
+          return;
+        }
+      }
+
+      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

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