aap-agent-core 2.0.0

package/README.md

@@ -0,0 +1,92 @@
+# @aap/core
+
+Core cryptographic utilities for Agent Attestation Protocol.
+
+## Installation
+
+```bash
+npm install @aap/core
+```
+
+## Usage
+
+### Cryptographic Functions
+
+```javascript
+import { generateKeyPair, sign, verify, generateNonce, derivePublicId } from '@aap/core';
+
+// Generate a new key pair
+const { publicKey, privateKey } = generateKeyPair();
+
+// Derive public ID
+const publicId = derivePublicId(publicKey);
+
+// Sign data
+const signature = sign('Hello, World!', privateKey);
+
+// Verify signature
+const isValid = verify('Hello, World!', signature, publicKey);
+
+// Generate nonce
+const nonce = generateNonce(); // 32-char hex string
+```
+
+### Identity Management
+
+```javascript
+import { Identity } from '@aap/core';
+
+// Create identity manager
+const identity = new Identity({
+  storagePath: '/path/to/identity.json' // optional
+});
+
+// Initialize (loads or generates)
+const publicInfo = identity.init();
+console.log(publicInfo.publicId);
+
+// Sign with identity
+const signature = identity.sign('data to sign');
+
+// Get public info (safe to share)
+const pub = identity.getPublic();
+```
+
+### Constants
+
+```javascript
+import { 
+  PROTOCOL_VERSION,
+  DEFAULT_CHALLENGE_EXPIRY_MS,
+  DEFAULT_MAX_RESPONSE_TIME_MS,
+  CHALLENGE_TYPES
+} from '@aap/core';
+```
+
+## API Reference
+
+### Crypto Functions
+
+| Function | Description |
+|----------|-------------|
+| `generateKeyPair()` | Generate secp256k1 key pair |
+| `derivePublicId(publicKey)` | Derive 20-char hex ID from public key |
+| `sign(data, privateKey)` | Sign data, return Base64 signature |
+| `verify(data, signature, publicKey)` | Verify signature |
+| `generateNonce(bytes?)` | Generate random hex nonce |
+| `safeCompare(a, b)` | Timing-safe string comparison |
+| `createProofData({...})` | Create canonical proof JSON |
+
+### Identity Class
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Initialize identity (load/generate) |
+| `getPublic()` | Get public identity info |
+| `sign(data)` | Sign data with identity key |
+| `exists()` | Check if identity file exists |
+| `Identity.verify(...)` | Static: verify any signature |
+
+## License
+
+MIT

package/crypto.js

@@ -0,0 +1,130 @@
+/**
+ * @aap/core - Cryptographic utilities
+ * 
+ * Core cryptographic functions for Agent Attestation Protocol.
+ * Uses secp256k1 (same as Bitcoin/Ethereum) for compatibility.
+ */
+
+import { 
+  generateKeyPairSync, 
+  createSign, 
+  createVerify, 
+  createHash,
+  randomBytes,
+  timingSafeEqual
+} from 'node:crypto';
+
+/**
+ * Generate a new secp256k1 key pair
+ * @returns {Object} { publicKey, privateKey } in PEM format
+ */
+export function generateKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ec', {
+    namedCurve: 'secp256k1',
+    publicKeyEncoding: {
+      type: 'spki',
+      format: 'pem'
+    },
+    privateKeyEncoding: {
+      type: 'pkcs8',
+      format: 'pem'
+    }
+  });
+  
+  return { publicKey, privateKey };
+}
+
+/**
+ * Derive a short public ID from a public key
+ * @param {string} publicKey - PEM-encoded public key
+ * @returns {string} 20-character hex identifier
+ */
+export function derivePublicId(publicKey) {
+  const hash = createHash('sha256').update(publicKey).digest('hex');
+  return hash.slice(0, 20);
+}
+
+/**
+ * Sign data with a private key
+ * @param {string} data - Data to sign
+ * @param {string} privateKey - PEM-encoded private key
+ * @returns {string} Base64-encoded signature
+ */
+export function sign(data, privateKey) {
+  const signer = createSign('SHA256');
+  signer.update(data);
+  signer.end();
+  return signer.sign(privateKey, 'base64');
+}
+
+/**
+ * Verify a signature
+ * @param {string} data - Original data
+ * @param {string} signature - Base64-encoded signature
+ * @param {string} publicKey - PEM-encoded public key
+ * @returns {boolean} True if valid
+ */
+export function verify(data, signature, publicKey) {
+  try {
+    const verifier = createVerify('SHA256');
+    verifier.update(data);
+    verifier.end();
+    return verifier.verify(publicKey, signature, 'base64');
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Generate a cryptographically secure nonce
+ * @param {number} [bytes=16] - Number of random bytes
+ * @returns {string} Hex-encoded nonce
+ */
+export function generateNonce(bytes = 16) {
+  return randomBytes(bytes).toString('hex');
+}
+
+/**
+ * Timing-safe comparison of two strings
+ * Prevents timing attacks on token comparison
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {boolean} True if equal
+ */
+export function safeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+  
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  
+  if (bufA.length !== bufB.length) {
+    return false;
+  }
+  
+  return timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Create the canonical proof data object for signing/verification
+ * @param {Object} params
+ * @param {string} params.nonce - Challenge nonce
+ * @param {string} params.solution - Agent's solution
+ * @param {string} params.publicId - Agent's public ID
+ * @param {number} params.timestamp - Unix timestamp in ms
+ * @returns {string} JSON string for signing
+ */
+export function createProofData({ nonce, solution, publicId, timestamp }) {
+  return JSON.stringify({ nonce, solution, publicId, timestamp });
+}
+
+export default {
+  generateKeyPair,
+  derivePublicId,
+  sign,
+  verify,
+  generateNonce,
+  safeCompare,
+  createProofData
+};

package/identity.js

@@ -0,0 +1,144 @@
+/**
+ * @aap/core - Identity Management
+ * 
+ * Manages agent identity (key generation, storage, signing).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { generateKeyPair, derivePublicId, sign as cryptoSign, verify as cryptoVerify } from './crypto.js';
+
+/**
+ * Identity manager class
+ */
+export class Identity {
+  constructor(options = {}) {
+    this.storagePath = options.storagePath || join(homedir(), '.aap', 'identity.json');
+    this.identity = null;
+  }
+
+  /**
+   * Initialize identity (load existing or generate new)
+   * @returns {Object} Public identity info
+   */
+  init() {
+    if (this.identity) {
+      return this.getPublic();
+    }
+
+    // Ensure directory exists
+    const dir = dirname(this.storagePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Load existing identity
+    if (existsSync(this.storagePath)) {
+      try {
+        const data = readFileSync(this.storagePath, 'utf8');
+        this.identity = JSON.parse(data);
+        return this.getPublic();
+      } catch (error) {
+        console.error('[AAP] Failed to load identity:', error.message);
+      }
+    }
+
+    // Generate new identity
+    const { publicKey, privateKey } = generateKeyPair();
+    const publicId = derivePublicId(publicKey);
+
+    this.identity = {
+      publicKey,
+      privateKey,
+      publicId,
+      createdAt: new Date().toISOString(),
+      protocol: 'AAP',
+      version: '1.0.0'
+    };
+
+    // Save to file with secure permissions
+    writeFileSync(this.storagePath, JSON.stringify(this.identity, null, 2), {
+      mode: 0o600
+    });
+
+    return this.getPublic();
+  }
+
+  /**
+   * Get public identity (safe to share)
+   * @returns {Object} Public identity without private key
+   */
+  getPublic() {
+    if (!this.identity) {
+      this.init();
+    }
+
+    return {
+      publicKey: this.identity.publicKey,
+      publicId: this.identity.publicId,
+      createdAt: this.identity.createdAt,
+      protocol: this.identity.protocol,
+      version: this.identity.version
+    };
+  }
+
+  /**
+   * Sign data with the identity's private key
+   * @param {string} data - Data to sign
+   * @returns {string} Base64-encoded signature
+   */
+  sign(data) {
+    if (!this.identity) {
+      this.init();
+    }
+    return cryptoSign(data, this.identity.privateKey);
+  }
+
+  /**
+   * Verify a signature (static method for verifying others)
+   * @param {string} data - Original data
+   * @param {string} signature - Signature to verify
+   * @param {string} publicKey - Public key of signer
+   * @returns {boolean} True if valid
+   */
+  static verify(data, signature, publicKey) {
+    return cryptoVerify(data, signature, publicKey);
+  }
+
+  /**
+   * Check if identity exists
+   * @returns {boolean}
+   */
+  exists() {
+    return existsSync(this.storagePath);
+  }
+
+  /**
+   * Delete identity (for testing)
+   */
+  delete() {
+    if (existsSync(this.storagePath)) {
+      const { unlinkSync } = require('node:fs');
+      unlinkSync(this.storagePath);
+    }
+    this.identity = null;
+  }
+}
+
+// Default instance
+let defaultIdentity = null;
+
+/**
+ * Get or create the default identity instance
+ * @param {Object} [options] - Options for new instance
+ * @returns {Identity}
+ */
+export function getDefaultIdentity(options) {
+  if (!defaultIdentity) {
+    defaultIdentity = new Identity(options);
+  }
+  return defaultIdentity;
+}
+
+export default { Identity, getDefaultIdentity };

package/index.js

@@ -0,0 +1,34 @@
+/**
+ * @aap/core
+ * 
+ * Core utilities for Agent Attestation Protocol.
+ * Provides cryptographic primitives and identity management.
+ */
+
+export * from './crypto.js';
+export * from './identity.js';
+
+// Re-export defaults
+import crypto from './crypto.js';
+import identity from './identity.js';
+
+export { crypto, identity };
+
+// Protocol constants
+export const PROTOCOL_VERSION = '1.0.0';
+export const DEFAULT_CHALLENGE_EXPIRY_MS = 30000;
+export const DEFAULT_MAX_RESPONSE_TIME_MS = 1500;
+export const NONCE_BYTES = 16;
+
+// Challenge types
+export const CHALLENGE_TYPES = ['poem', 'math', 'reverse', 'wordplay', 'description'];
+
+export default {
+  ...crypto,
+  ...identity,
+  PROTOCOL_VERSION,
+  DEFAULT_CHALLENGE_EXPIRY_MS,
+  DEFAULT_MAX_RESPONSE_TIME_MS,
+  NONCE_BYTES,
+  CHALLENGE_TYPES
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "aap-agent-core",
+  "version": "2.0.0",
+  "description": "Core cryptographic utilities for Agent Attestation Protocol",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./identity": "./identity.js",
+    "./crypto": "./crypto.js"
+  },
+  "files": ["*.js", "README.md"],
+  "keywords": ["aap", "agent", "attestation", "crypto", "secp256k1", "ai", "verification"],
+  "author": "ira-hash",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ira-hash/agent-attestation-protocol.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/ira-hash/agent-attestation-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/ira-hash/agent-attestation-protocol/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}