@apitap/core 1.0.22 → 1.2.0

package/src/extension/install.ts

@@ -0,0 +1,73 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const HOST_NAME = 'com.apitap.native';
+
+export interface HostManifest {
+  name: string;
+  description: string;
+  path: string;
+  type: 'stdio';
+  allowed_origins: string[];
+}
+
+export function generateHostManifest(hostPath: string, extensionId: string): HostManifest {
+  return {
+    name: HOST_NAME,
+    description: 'ApiTap native messaging host — saves captured skill files to ~/.apitap/skills/',
+    path: hostPath,
+    type: 'stdio',
+    allowed_origins: [`chrome-extension://${extensionId}/`],
+  };
+}
+
+export function getBrowserPaths(platform: string = process.platform): string[] {
+  const home = os.homedir();
+
+  if (platform === 'linux') {
+    return [
+      path.join(home, '.config', 'google-chrome', 'NativeMessagingHosts'),
+      path.join(home, '.config', 'chromium', 'NativeMessagingHosts'),
+      path.join(home, '.config', 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts'),
+      path.join(home, '.config', 'microsoft-edge', 'NativeMessagingHosts'),
+    ];
+  }
+
+  if (platform === 'darwin') {
+    return [
+      path.join(home, 'Library', 'Application Support', 'Google', 'Chrome', 'NativeMessagingHosts'),
+      path.join(home, 'Library', 'Application Support', 'Chromium', 'NativeMessagingHosts'),
+      path.join(home, 'Library', 'Application Support', 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts'),
+      path.join(home, 'Library', 'Application Support', 'Microsoft Edge', 'NativeMessagingHosts'),
+    ];
+  }
+
+  return [];
+}
+
+export async function installNativeHost(
+  hostPath: string,
+  extensionId: string,
+  browserDirs?: string[],
+): Promise<{ installed: string[]; errors: string[] }> {
+  const dirs = browserDirs ?? getBrowserPaths();
+  const manifest = generateHostManifest(hostPath, extensionId);
+  const manifestJson = JSON.stringify(manifest, null, 2);
+
+  const installed: string[] = [];
+  const errors: string[] = [];
+
+  for (const dir of dirs) {
+    try {
+      await fs.mkdir(dir, { recursive: true });
+      const manifestPath = path.join(dir, `${HOST_NAME}.json`);
+      await fs.writeFile(manifestPath, manifestJson, 'utf-8');
+      installed.push(manifestPath);
+    } catch (err) {
+      errors.push(`${dir}: ${err}`);
+    }
+  }
+
+  return { installed, errors };
+}

package/src/native-host.ts

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+// ApiTap Native Messaging Host
+// Receives skill files from the Chrome extension and saves to ~/.apitap/skills/
+
+import { promises as fs } from 'node:fs';
+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 { getMachineId } from './auth/manager.js';
+
+const SKILLS_DIR = path.join(os.homedir(), '.apitap', 'skills');
+const VERSION = '1.0.0';
+
+// Sign skill JSON using the CLI's HMAC signing infrastructure
+async function signSkillJson(skillJson: string): Promise<string> {
+  try {
+    const skill = JSON.parse(skillJson);
+    const machineId = await getMachineId();
+    const key = deriveKey(machineId);
+    const signed = signSkillFile(skill, key);
+    return JSON.stringify(signed);
+  } catch {
+    return skillJson; // Return unsigned if signing fails
+  }
+}
+
+export interface NativeRequest {
+  action: 'save_skill' | 'save_batch' | 'ping' | 'capture_request';
+  domain?: string;
+  skillJson?: string;
+  skills?: Array<{ domain: string; skillJson: string }>;
+}
+
+export interface NativeResponse {
+  success: boolean;
+  action?: string;
+  path?: string;
+  paths?: string[];
+  error?: string;
+  version?: string;
+  skillsDir?: string;
+}
+
+// Domain validation — must match src/skill/store.ts conventions
+function isValidDomain(domain: string): boolean {
+  if (!domain || domain.length === 0 || domain.length > 253) return false;
+  if (domain.includes('/') || domain.includes('\\')) return false;
+  if (domain.includes('..')) return false;
+  if (domain.startsWith('.') || domain.startsWith('-')) return false;
+  if (!/^[a-zA-Z0-9._-]+$/.test(domain)) return false;
+  return true;
+}
+
+export async function handleNativeMessage(
+  request: NativeRequest,
+  skillsDir: string = SKILLS_DIR,
+): Promise<NativeResponse> {
+  try {
+    if (request.action === 'ping') {
+      return {
+        success: true,
+        action: 'pong',
+        version: VERSION,
+        skillsDir,
+      };
+    }
+
+    if (request.action === 'save_skill') {
+      if (!request.domain || !isValidDomain(request.domain)) {
+        return { success: false, error: `Invalid domain: ${request.domain}` };
+      }
+      if (!request.skillJson) {
+        return { success: false, error: 'Missing skillJson' };
+      }
+      // Validate JSON
+      try {
+        JSON.parse(request.skillJson);
+      } catch {
+        return { success: false, error: 'Invalid JSON in skillJson' };
+      }
+
+      await fs.mkdir(skillsDir, { recursive: true });
+      const filePath = path.join(skillsDir, `${request.domain}.json`);
+      // Sign the skill file on receive (CLI is the signing authority)
+      const signed = await signSkillJson(request.skillJson);
+      await fs.writeFile(filePath, signed, 'utf-8');
+      return { success: true, path: filePath };
+    }
+
+    if (request.action === 'save_batch') {
+      if (!Array.isArray(request.skills) || request.skills.length === 0) {
+        return { success: false, error: 'Missing or empty skills array' };
+      }
+
+      await fs.mkdir(skillsDir, { recursive: true });
+      const paths: string[] = [];
+
+      for (const { domain, skillJson } of request.skills) {
+        if (!isValidDomain(domain)) {
+          return { success: false, error: `Invalid domain: ${domain}` };
+        }
+        try {
+          JSON.parse(skillJson);
+        } catch {
+          return { success: false, error: `Invalid JSON for domain ${domain}` };
+        }
+        const filePath = path.join(skillsDir, `${domain}.json`);
+        const signed = await signSkillJson(skillJson);
+        await fs.writeFile(filePath, signed, 'utf-8');
+        paths.push(filePath);
+      }
+
+      return { success: true, paths };
+    }
+
+    return { success: false, error: `Unknown action: ${request.action}` };
+  } catch (err) {
+    return { success: false, error: String(err) };
+  }
+}
+
+// --- Relay handler ---
+
+// Actions handled locally by the native host (filesystem operations)
+const LOCAL_ACTIONS = new Set(['save_skill', 'save_batch', 'ping']);
+
+// Actions relayed to the extension (browser operations)
+const EXTENSION_ACTIONS = new Set(['capture_request']);
+
+export function createRelayHandler(
+  sendToExtension: (msg: any) => Promise<any>,
+  skillsDir: string = SKILLS_DIR,
+): MessageHandler {
+  return async (message: any) => {
+    if (LOCAL_ACTIONS.has(message.action)) {
+      return handleNativeMessage(message, skillsDir);
+    }
+
+    if (EXTENSION_ACTIONS.has(message.action)) {
+      try {
+        return await sendToExtension(message);
+      } catch (err) {
+        return { success: false, error: String(err) };
+      }
+    }
+
+    return { success: false, error: `Unknown action: ${message.action}` };
+  };
+}
+
+// --- Unix socket server for CLI relay ---
+
+export type MessageHandler = (message: any) => Promise<any>;
+
+let socketServer: net.Server | null = null;
+
+export async function startSocketServer(
+  socketPath: string,
+  handler: MessageHandler,
+): Promise<void> {
+  // Clean up stale socket
+  try { await fs.unlink(socketPath); } catch { /* doesn't exist — fine */ }
+
+  return new Promise((resolve, reject) => {
+    socketServer = net.createServer((conn) => {
+      let buffer = '';
+
+      conn.on('data', (chunk) => {
+        buffer += chunk.toString();
+        const newlineIdx = buffer.indexOf('\n');
+        if (newlineIdx === -1) return;
+
+        const line = buffer.slice(0, newlineIdx);
+        buffer = buffer.slice(newlineIdx + 1);
+
+        let request: any;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          conn.end(JSON.stringify({ success: false, error: 'Invalid JSON' }) + '\n');
+          return;
+        }
+
+        handler(request).then(
+          (response) => conn.end(JSON.stringify(response) + '\n'),
+          (err) => conn.end(JSON.stringify({ success: false, error: String(err) }) + '\n'),
+        );
+      });
+
+      conn.on('error', () => { /* client disconnect — ignore */ });
+    });
+
+    socketServer.on('error', reject);
+    socketServer.listen(socketPath, () => resolve());
+  });
+}
+
+export async function stopSocketServer(): Promise<void> {
+  if (!socketServer) return;
+  return new Promise((resolve) => {
+    socketServer!.close(() => resolve());
+    socketServer = null;
+  });
+}
+
+// --- stdio framing (only runs when executed directly, not when imported for tests) ---
+
+function readMessage(): Promise<NativeRequest | null> {
+  return new Promise((resolve) => {
+    const headerBuf = Buffer.alloc(4);
+    let headerRead = 0;
+
+    function onData(chunk: Buffer) {
+      let offset = 0;
+
+      // Read header
+      if (headerRead < 4) {
+        const needed = 4 - headerRead;
+        const toCopy = Math.min(needed, chunk.length);
+        chunk.copy(headerBuf, headerRead, 0, toCopy);
+        headerRead += toCopy;
+        offset = toCopy;
+
+        if (headerRead < 4) return; // need more data for header
+      }
+
+      const messageLength = headerBuf.readUInt32LE(0);
+      if (messageLength > 1024 * 1024) {
+        process.stderr.write(`Message too large: ${messageLength}\n`);
+        resolve(null);
+        return;
+      }
+
+      // Accumulate message body
+      const bodyBuf = Buffer.alloc(messageLength);
+      let bodyRead = 0;
+
+      if (offset < chunk.length) {
+        const remaining = chunk.subarray(offset);
+        const toCopy = Math.min(remaining.length, messageLength);
+        remaining.copy(bodyBuf, 0, 0, toCopy);
+        bodyRead = toCopy;
+      }
+
+      if (bodyRead >= messageLength) {
+        process.stdin.removeListener('data', onData);
+        try {
+          resolve(JSON.parse(bodyBuf.toString('utf-8')));
+        } catch {
+          resolve(null);
+        }
+        return;
+      }
+
+      // Need more data
+      function onMoreData(moreChunk: Buffer) {
+        const toCopy = Math.min(moreChunk.length, messageLength - bodyRead);
+        moreChunk.copy(bodyBuf, bodyRead, 0, toCopy);
+        bodyRead += toCopy;
+
+        if (bodyRead >= messageLength) {
+          process.stdin.removeListener('data', onMoreData);
+          process.stdin.removeListener('data', onData);
+          try {
+            resolve(JSON.parse(bodyBuf.toString('utf-8')));
+          } catch {
+            resolve(null);
+          }
+        }
+      }
+      process.stdin.on('data', onMoreData);
+    }
+
+    process.stdin.on('data', onData);
+    process.stdin.on('end', () => resolve(null));
+  });
+}
+
+function sendMessage(message: NativeResponse) {
+  const json = Buffer.from(JSON.stringify(message), 'utf-8');
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(json.length, 0);
+  process.stdout.write(header);
+  process.stdout.write(json);
+}
+
+// Main loop — only runs when executed as a script
+const isMainModule = process.argv[1] &&
+  (process.argv[1].endsWith('native-host.ts') || process.argv[1].endsWith('native-host.js'));
+
+if (isMainModule) {
+  const bridgeDir = path.join(os.homedir(), '.apitap');
+  const socketPath = path.join(bridgeDir, 'bridge.sock');
+
+  // Pending CLI requests waiting for extension responses
+  const pendingRequests = new Map<string, {
+    resolve: (value: any) => void;
+    timer: ReturnType<typeof setTimeout>;
+  }>();
+  let requestCounter = 0;
+
+  // Send a message to the extension via stdout and wait for response
+  function sendToExtension(message: any): Promise<any> {
+    return new Promise((resolve) => {
+      const id = String(++requestCounter);
+      const timer = setTimeout(() => {
+        pendingRequests.delete(id);
+        resolve({ success: false, error: 'approval_timeout' });
+      }, 60_000);
+
+      pendingRequests.set(id, { resolve, timer });
+
+      // Tag message with ID so we can match the response
+      sendMessage({ ...message, _relayId: id } as any);
+    });
+  }
+
+  const handler = createRelayHandler(sendToExtension);
+
+  (async () => {
+    // Ensure bridge directory exists
+    await fs.mkdir(bridgeDir, { recursive: true });
+
+    // Start socket server for CLI connections
+    await startSocketServer(socketPath, handler);
+
+    // Read messages from extension via stdin
+    while (true) {
+      const message = await readMessage();
+      if (!message) break;
+
+      // Check if this is a response to a relayed request
+      const relayId = (message as any)._relayId;
+      if (relayId && pendingRequests.has(relayId)) {
+        const pending = pendingRequests.get(relayId)!;
+        clearTimeout(pending.timer);
+        pendingRequests.delete(relayId);
+        const { _relayId, ...response } = message as any;
+        pending.resolve(response);
+        continue;
+      }
+
+      // Otherwise, handle as a direct extension message (save_skill, etc.)
+      const response = await handleNativeMessage(message);
+      sendMessage(response);
+    }
+
+    // Extension disconnected — clean up
+    await stopSocketServer();
+    try { await fs.unlink(socketPath); } catch { /* already gone */ }
+  })();
+}

package/src/orchestration/browse.ts

@@ -3,6 +3,7 @@ import { readSkillFile } from '../skill/store.js';
 import { replayEndpoint } from '../replay/engine.js';
 import { SessionCache } from './cache.js';
 import { read } from '../read/index.js';
+import { bridgeAvailable, requestBridgeCapture, DEFAULT_SOCKET } from '../bridge/client.js';
 
 export interface BrowseOptions {
   skillsDir?: string;
@@ -13,6 +14,10 @@ export interface BrowseOptions {
   maxBytes?: number;
   /** @internal Skip SSRF check — for testing only */
   _skipSsrfCheck?: boolean;
+  /** @internal Override bridge socket path — for testing only */
+  _bridgeSocketPath?: string;
+  /** @internal Override bridge timeout — for testing only */
+  _bridgeTimeout?: number;
 }
 
 export interface BrowseSuccess {
@@ -22,7 +27,7 @@ export interface BrowseSuccess {
   domain: string;
   endpointId: string;
   tier: string;
-  skillSource: 'disk' | 'discovered' | 'captured';
+  skillSource: 'disk' | 'discovered' | 'captured' | 'bridge';
   capturedAt: string;
   task?: string;
   truncated?: boolean;
@@ -40,6 +45,106 @@ export interface BrowseGuidance {
 
 export type BrowseResult = BrowseSuccess | BrowseGuidance;
 
+/**
+ * Try escalating to the Chrome extension bridge for authenticated capture.
+ * Returns a BrowseResult if the bridge handled it, or null to fall through.
+ */
+async function tryBridgeCapture(
+  domain: string,
+  fullUrl: string,
+  options: BrowseOptions,
+): Promise<BrowseResult | null> {
+  const socketPath = options._bridgeSocketPath ?? DEFAULT_SOCKET;
+  if (!await bridgeAvailable(socketPath)) return null;
+
+  const result = await requestBridgeCapture(domain, socketPath, { timeout: options._bridgeTimeout });
+
+  if (result.success && result.skillFiles && result.skillFiles.length > 0) {
+    const skillFiles = result.skillFiles;
+    // Save each skill file to disk
+    try {
+      const { writeSkillFile: writeSF } = await import('../skill/store.js');
+      for (const skill of skillFiles) {
+        await writeSF(skill, options.skillsDir);
+      }
+    } catch {
+      // Saving failed — still have the data in memory
+    }
+
+    // Find the skill file matching the requested domain
+    const primarySkill = skillFiles.find((s: any) => s.domain === domain)
+      ?? skillFiles[0];
+
+    if (primarySkill?.endpoints?.length > 0) {
+      // Pick the best endpoint and replay it
+      let urlPath = '/';
+      try { urlPath = new URL(fullUrl).pathname; } catch { /* use default */ }
+      const endpoint = pickEndpoint(primarySkill, urlPath);
+
+      if (endpoint) {
+        try {
+          const replayResult = await replayEndpoint(primarySkill, endpoint.id, {
+            maxBytes: options.maxBytes,
+            _skipSsrfCheck: options._skipSsrfCheck,
+          });
+          if (replayResult.status >= 200 && replayResult.status < 300) {
+            return {
+              success: true,
+              data: replayResult.data,
+              status: replayResult.status,
+              domain,
+              endpointId: endpoint.id,
+              tier: endpoint.replayability?.tier ?? 'unknown',
+              skillSource: 'bridge',
+              capturedAt: primarySkill.capturedAt ?? new Date().toISOString(),
+              task: options.task,
+              ...(replayResult.truncated ? { truncated: true } : {}),
+            };
+          }
+        } catch {
+          // Replay failed — but skill file is saved for next time
+        }
+      }
+    }
+
+    // Skill file saved but replay didn't work
+    return {
+      success: false,
+      reason: 'bridge_capture_saved',
+      suggestion: `Captured ${skillFiles.length} skill file(s) from browser. Replay failed — try 'apitap replay ${domain}'.`,
+      domain,
+      url: fullUrl,
+      task: options.task,
+    };
+  }
+
+  // Bridge returned an error
+  if (result.error === 'user_denied') {
+    return {
+      success: false,
+      reason: 'user_denied',
+      suggestion: `User denied browser access to ${domain}. Use 'apitap auth request ${domain}' for manual login instead.`,
+      domain,
+      url: fullUrl,
+      task: options.task,
+    };
+  }
+
+  if (result.error === 'approval_timeout') {
+    return {
+      success: false,
+      reason: 'approval_timeout',
+      suggestion: `User approval pending for ${domain}. Click Allow in the ApiTap extension and try again.`,
+      domain,
+      url: fullUrl,
+      task: options.task,
+    };
+  }
+
+  // Other bridge errors — fall through to existing fallback
+  return null;
+}
+
 /**
  * High-level browse: check cache → disk → discover → replay.
  * Auto-escalates cheap steps. Returns guidance for expensive ones.
@@ -121,6 +226,10 @@ export async function browse(
         } catch {
           // Read failed — fall through to capture_needed
         }
+        // Try extension bridge before giving up
+        const bridgeResult1 = await tryBridgeCapture(domain, fullUrl, options);
+        if (bridgeResult1) return bridgeResult1;
+
         return {
           success: false,
           reason: 'no_replayable_endpoints',
@@ -158,6 +267,10 @@ export async function browse(
         // Read failed — fall through to capture_needed
       }
     }
+    // Try extension bridge before giving up
+    const bridgeResult2 = await tryBridgeCapture(domain, fullUrl, options);
+    if (bridgeResult2) return bridgeResult2;
+
     return {
       success: false,
       reason: 'no_skill_file',
@@ -171,6 +284,10 @@ export async function browse(
   // Step 4: Pick best endpoint
   const endpoint = pickEndpoint(skill, urlPath);
   if (!endpoint) {
+    // Try extension bridge before giving up
+    const bridgeResult3 = await tryBridgeCapture(domain, fullUrl, options);
+    if (bridgeResult3) return bridgeResult3;
+
     return {
       success: false,
       reason: 'no_replayable_endpoints',
@@ -213,6 +330,10 @@ export async function browse(
       ...(result.truncated ? { truncated: true } : {}),
     };
   } catch {
+    // Try extension bridge before giving up
+    const bridgeResult4 = await tryBridgeCapture(domain, fullUrl, options);
+    if (bridgeResult4) return bridgeResult4;
+
     return {
       success: false,
       reason: 'replay_failed',