@apitap/core 1.3.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apitap/core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Intercept web API traffic during browsing. Generate portable skill files so AI agents can call APIs directly instead of scraping.",
   "type": "module",
   "main": "dist/index.js",

package/src/auth/crypto.ts

@@ -53,6 +53,24 @@ export function deriveKey(machineId: string, saltFile?: string): Buffer {
   }
 }
 
+/**
+ * Derive a purpose-specific encryption key from the master key.
+ * Uses HKDF-like expansion: HMAC-SHA256(masterKey, purpose-string).
+ */
+export function deriveEncryptionKey(machineId: string, saltFile?: string): Buffer {
+  const master = deriveKey(machineId, saltFile);
+  return createHmac('sha256', master).update('apitap-encryption-v1').digest();
+}
+
+/**
+ * Derive a purpose-specific signing key from the master key.
+ * Uses HKDF-like expansion: HMAC-SHA256(masterKey, purpose-string).
+ */
+export function deriveSigningKey(machineId: string, saltFile?: string): Buffer {
+  const master = deriveKey(machineId, saltFile);
+  return createHmac('sha256', master).update('apitap-signing-v1').digest();
+}
+
 /**
  * Encrypt plaintext using AES-256-GCM.
  * Each call generates a random IV for semantic security.

package/src/auth/manager.ts

@@ -1,7 +1,7 @@
 // src/auth/manager.ts
 import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
 import { join } from 'node:path';
-import { encrypt, decrypt, deriveKey, type EncryptedData } from './crypto.js';
+import { encrypt, decrypt, deriveKey, deriveEncryptionKey, type EncryptedData } from './crypto.js';
 import type { StoredAuth, StoredToken, StoredSession } from '../types.js';
 
 const AUTH_FILENAME = 'auth.enc';
@@ -12,10 +12,12 @@ const AUTH_FILENAME = 'auth.enc';
  */
 export class AuthManager {
   private key: Buffer;
+  private legacyKey: Buffer;
   private authPath: string;
 
   constructor(baseDir: string, machineId: string, saltFile?: string) {
-    this.key = deriveKey(machineId, saltFile);
+    this.key = deriveEncryptionKey(machineId, saltFile);
+    this.legacyKey = deriveKey(machineId, saltFile);
     this.authPath = join(baseDir, AUTH_FILENAME);
   }
 
@@ -141,8 +143,13 @@ export class AuthManager {
     try {
       const content = await readFile(this.authPath, 'utf-8');
       const encrypted: EncryptedData = JSON.parse(content);
-      const plaintext = decrypt(encrypted, this.key);
-      return JSON.parse(plaintext);
+      try {
+        // Try new encryption key first
+        return JSON.parse(decrypt(encrypted, this.key));
+      } catch {
+        // Fall back to legacy key (pre-key-separation installs)
+        return JSON.parse(decrypt(encrypted, this.legacyKey));
+      }
     } catch {
       return {};
     }

package/src/capture/session.ts

@@ -10,7 +10,7 @@ import { verifyEndpoints } from './verifier.js';
 import { signSkillFile } from '../skill/signing.js';
 import { writeSkillFile } from '../skill/store.js';
 import { AuthManager, getMachineId } from '../auth/manager.js';
-import { deriveKey } from '../auth/crypto.js';
+import { deriveSigningKey } from '../auth/crypto.js';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { CapturedExchange, PageSnapshot, PageElement, InteractionResult, FinishResult } from '../types.js';
@@ -204,7 +204,7 @@ export class CaptureSession {
 
     // Finalize: generate skill files, verify, sign, write
     const machineId = await getMachineId();
-    const key = deriveKey(machineId);
+    const key = deriveSigningKey(machineId);
     const authManager = new AuthManager(APITAP_DIR, machineId);
 
     const domains: FinishResult['domains'] = [];

package/src/cli.ts

@@ -4,7 +4,7 @@ import { capture } from './capture/monitor.js';
 import { writeSkillFile, readSkillFile, listSkillFiles } from './skill/store.js';
 import { replayEndpoint } from './replay/engine.js';
 import { AuthManager, getMachineId } from './auth/manager.js';
-import { deriveKey } from './auth/crypto.js';
+import { deriveSigningKey } from './auth/crypto.js';
 import { signSkillFile } from './skill/signing.js';
 import { importSkillFile } from './skill/importer.js';
 import { resolveAndValidateUrl } from './skill/ssrf.js';
@@ -194,7 +194,7 @@ async function handleCapture(positional: string[], flags: Record<string, string
 
   // Get machine ID for signing and auth storage
   const machineId = await getMachineId();
-  const key = deriveKey(machineId);
+  const key = deriveSigningKey(machineId);
   const authManager = new AuthManager(APITAP_DIR, machineId);
 
   // Write skill files for each domain
@@ -378,7 +378,9 @@ async function handleReplay(positional: string[], flags: Record<string, string |
     process.exit(1);
   }
 
-  const skill = await readSkillFile(domain, SKILLS_DIR);
+  const machineId = await getMachineId();
+  const signingKey = deriveSigningKey(machineId);
+  const skill = await readSkillFile(domain, SKILLS_DIR, { verifySignature: true, signingKey });
   if (!skill) {
     console.error(`Error: No skill file found for "${domain}".`);
     process.exit(1);
@@ -394,7 +396,6 @@ async function handleReplay(positional: string[], flags: Record<string, string |
   }
 
   // Merge stored auth into endpoint headers for replay
-  const machineId = await getMachineId();
   const authManager = new AuthManager(APITAP_DIR, machineId);
   const storedAuth = await authManager.retrieve(domain);
 
@@ -446,7 +447,7 @@ async function handleImport(positional: string[], flags: Record<string, string |
 
   // Get local key for signature verification
   const machineId = await getMachineId();
-  const key = deriveKey(machineId);
+  const key = deriveSigningKey(machineId);
 
   // DNS-resolving SSRF check before importing (prevents DNS rebinding attacks)
   try {
@@ -863,9 +864,9 @@ async function handleDiscover(positional: string[], flags: Record<string, string
   if (save && result.skillFile) {
     const { writeSkillFile } = await import('./skill/store.js');
     const { signSkillFile } = await import('./skill/signing.js');
-    const { deriveKey } = await import('./auth/crypto.js');
+    const { deriveSigningKey } = await import('./auth/crypto.js');
     const machineId = await getMachineId();
-    const key = deriveKey(machineId);
+    const key = deriveSigningKey(machineId);
 
     const signed = signSkillFile(result.skillFile, key);
     const path = await writeSkillFile(signed, SKILLS_DIR);

package/src/mcp.ts

@@ -7,6 +7,7 @@ import { searchSkills } from './skill/search.js';
 import { readSkillFile } from './skill/store.js';
 import { replayEndpoint } from './replay/engine.js';
 import { AuthManager, getMachineId } from './auth/manager.js';
+import { deriveSigningKey } from './auth/crypto.js';
 import { requestAuth } from './auth/handoff.js';
 import { CaptureSession } from './capture/session.js';
 import { discover } from './discovery/index.js';
@@ -153,7 +154,9 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       },
     },
     async ({ domain, endpointId, params, fresh, maxBytes }) => {
-      const skill = await readSkillFile(domain, skillsDir);
+      const machineId = await getMachineId();
+      const signingKey = deriveSigningKey(machineId);
+      const skill = await readSkillFile(domain, skillsDir, { verifySignature: true, signingKey });
       if (!skill) {
         return {
           content: [{ type: 'text' as const, text: `No skill file found for "${domain}". Use apitap_capture to capture it first.` }],
@@ -170,7 +173,6 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       }
 
       // Get auth manager for token injection and header auth
-      const machineId = await getMachineId();
       const authManager = new AuthManager(APITAP_DIR, machineId);
 
       try {

package/src/native-host.ts

@@ -7,7 +7,7 @@ import path from 'node:path';
 import os from 'node:os';
 import net from 'node:net';
 import { signSkillFile } from './skill/signing.js';
-import { deriveKey } from './auth/crypto.js';
+import { deriveSigningKey } from './auth/crypto.js';
 import { getMachineId } from './auth/manager.js';
 
 const SKILLS_DIR = path.join(os.homedir(), '.apitap', 'skills');
@@ -18,7 +18,7 @@ async function signSkillJson(skillJson: string): Promise<string> {
   try {
     const skill = JSON.parse(skillJson);
     const machineId = await getMachineId();
-    const key = deriveKey(machineId);
+    const key = deriveSigningKey(machineId);
     const signed = signSkillFile(skill, key);
     return JSON.stringify(signed);
   } catch {

package/src/read/decoders/reddit.ts

@@ -58,6 +58,10 @@ async function recoverDeletedComments(
   const recovered = new Map<string, { author: string; body: string }>();
   if (commentIds.length === 0) return recovered;
 
+  // Third-party disclosure: PullPush is an external service.
+  // Users can opt out via APITAP_NO_THIRD_PARTY=1.
+  if (process.env.APITAP_NO_THIRD_PARTY === '1') return recovered;
+
   try {
     const ids = commentIds.join(',');
     const ppUrl = `https://api.pullpush.io/reddit/search/comment/?ids=${ids}`;

package/src/replay/engine.ts

@@ -569,17 +569,20 @@ export async function replayMultiple(
 
   const { readSkillFile } = await import('../skill/store.js');
   const { AuthManager, getMachineId } = await import('../auth/manager.js');
+  const { deriveSigningKey } = await import('../auth/crypto.js');
+
+  const machineId = await getMachineId();
+  const signingKey = deriveSigningKey(machineId);
 
   // Deduplicate skill file reads
   const skillCache = new Map<string, SkillFile | null>();
   const uniqueDomains = [...new Set(requests.map(r => r.domain))];
   await Promise.all(uniqueDomains.map(async (domain) => {
-    const skill = await readSkillFile(domain, options.skillsDir);
+    const skill = await readSkillFile(domain, options.skillsDir, { verifySignature: true, signingKey });
     skillCache.set(domain, skill);
   }));
 
   // Shared auth manager
-  const machineId = await getMachineId();
   const authManager = new AuthManager(
     (await import('node:os')).homedir() + '/.apitap',
     machineId,

package/src/skill/store.ts

@@ -3,6 +3,7 @@ import { readFile, writeFile, mkdir, readdir, access } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import type { SkillFile, SkillSummary } from '../types.js';
+import { validateSkillFile } from './validate.js';
 
 const DEFAULT_SKILLS_DIR = join(homedir(), '.apitap', 'skills');
 
@@ -52,7 +53,8 @@ export async function readSkillFile(
   const path = skillPath(domain, skillsDir);
   try {
     const content = await readFile(path, 'utf-8');
-    const skill = JSON.parse(content) as SkillFile;
+    const raw = JSON.parse(content);
+    const skill = validateSkillFile(raw);
 
     // If verification requested, check signature
     if (options?.verifySignature && options.signingKey) {
@@ -60,8 +62,9 @@ export async function readSkillFile(
         // Imported files had foreign signature stripped — can't verify, warn only
         // Future: re-sign on import with local key
       } else if (!skill.signature) {
-        // No signature present on non-imported file
-        throw new Error(`Skill file for ${domain} has no signature — file may be tampered`);
+        // Phase 2: warn for unsigned files, don't reject
+        // (user-created or pre-signing files are legitimately unsigned)
+        console.error(`[apitap] Warning: skill file for ${domain} is unsigned`);
       } else {
         const { verifySignature } = await import('./signing.js');
         if (!verifySignature(skill, options.signingKey)) {

package/src/skill/validate.ts

@@ -0,0 +1,72 @@
+// src/skill/validate.ts
+import type { SkillFile } from '../types.js';
+import { validateUrl } from './ssrf.js';
+
+const ALLOWED_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+
+/**
+ * Validate a parsed JSON object as a SkillFile.
+ * Throws on invalid input — fail fast, fail loud.
+ * SSRF checks are optional here (default: off) because the replay engine
+ * already enforces SSRF at request time with DNS resolution.
+ */
+export function validateSkillFile(raw: unknown, options?: { checkSsrf?: boolean }): SkillFile {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('Skill file must be an object');
+  }
+  const obj = raw as Record<string, unknown>;
+
+  // domain
+  if (typeof obj.domain !== 'string' || obj.domain.length === 0 || obj.domain.length > 253) {
+    throw new Error('Invalid domain: must be a string of 1-253 characters');
+  }
+
+  // baseUrl — must be a valid URL; SSRF checked at replay time
+  if (typeof obj.baseUrl !== 'string') {
+    throw new Error('Missing baseUrl');
+  }
+  try {
+    const url = new URL(obj.baseUrl);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      throw new Error('non-HTTP scheme');
+    }
+  } catch {
+    throw new Error(`Invalid baseUrl: must be a valid HTTP(S) URL`);
+  }
+  if (options?.checkSsrf) {
+    const ssrf = validateUrl(obj.baseUrl);
+    if (!ssrf.safe) {
+      throw new Error(`Unsafe baseUrl: ${ssrf.reason}`);
+    }
+  }
+
+  // endpoints
+  if (!Array.isArray(obj.endpoints)) {
+    throw new Error('Missing or invalid endpoints array');
+  }
+  if (obj.endpoints.length > 500) {
+    throw new Error('Too many endpoints (max 500)');
+  }
+
+  for (let i = 0; i < obj.endpoints.length; i++) {
+    const ep = obj.endpoints[i];
+    if (!ep || typeof ep !== 'object') {
+      throw new Error(`Endpoint ${i}: must be an object`);
+    }
+    const e = ep as Record<string, unknown>;
+    if (typeof e.id !== 'string' || e.id.length === 0 || e.id.length > 200) {
+      throw new Error(`Endpoint ${i}: id must be a string of 1-200 characters`);
+    }
+    if (typeof e.method !== 'string' || !ALLOWED_METHODS.has(e.method)) {
+      throw new Error(`Endpoint ${i}: method must be one of ${[...ALLOWED_METHODS].join(', ')}`);
+    }
+    if (typeof e.path !== 'string' || !e.path.startsWith('/')) {
+      throw new Error(`Endpoint ${i}: path must start with /`);
+    }
+    if (e.path.length > 2000) {
+      throw new Error(`Endpoint ${i}: path exceeds 2000 characters`);
+    }
+  }
+
+  return raw as SkillFile;
+}