@apitap/core 1.0.0

package/src/skill/importer.ts

@@ -0,0 +1,107 @@
+// src/skill/importer.ts
+import { readFile } from 'node:fs/promises';
+import { verifySignature } from './signing.js';
+import { validateSkillFileUrls } from './ssrf.js';
+import { writeSkillFile } from './store.js';
+import type { SkillFile } from '../types.js';
+
+export interface ImportValidation {
+  valid: boolean;
+  reason?: string;
+  signatureStatus: 'valid' | 'invalid' | 'unsigned';
+  summary?: {
+    domain: string;
+    endpointCount: number;
+    baseUrl: string;
+  };
+}
+
+export interface ImportResult {
+  success: boolean;
+  reason?: string;
+  skillFile?: string;
+}
+
+/**
+ * Validate a skill file for import.
+ * Checks structure, SSRF safety, and signature integrity.
+ */
+export function validateImport(skill: SkillFile, localKey?: Buffer): ImportValidation {
+  // Basic structure validation
+  if (!skill.domain || !skill.baseUrl || !Array.isArray(skill.endpoints)) {
+    return { valid: false, reason: 'Invalid skill file structure', signatureStatus: 'unsigned' };
+  }
+
+  // Signature check
+  let signatureStatus: ImportValidation['signatureStatus'] = 'unsigned';
+  if (skill.signature) {
+    if (localKey && verifySignature(skill, localKey)) {
+      signatureStatus = 'valid';
+    } else {
+      return {
+        valid: false,
+        reason: 'Skill file signature is invalid — file was tampered with or signed by a different instance',
+        signatureStatus: 'invalid',
+      };
+    }
+  }
+
+  // SSRF validation
+  const ssrfResult = validateSkillFileUrls(skill);
+  if (!ssrfResult.safe) {
+    return {
+      valid: false,
+      reason: `SSRF risk: ${ssrfResult.reason}`,
+      signatureStatus,
+    };
+  }
+
+  return {
+    valid: true,
+    signatureStatus,
+    summary: {
+      domain: skill.domain,
+      endpointCount: skill.endpoints.length,
+      baseUrl: skill.baseUrl,
+    },
+  };
+}
+
+/**
+ * Import a skill file from disk.
+ * Validates, strips foreign signatures, sets provenance to 'imported'.
+ */
+export async function importSkillFile(
+  filePath: string,
+  skillsDir?: string,
+  localKey?: Buffer,
+): Promise<ImportResult> {
+  let content: string;
+  try {
+    content = await readFile(filePath, 'utf-8');
+  } catch (err) {
+    return { success: false, reason: `Cannot read file: ${(err as Error).message}` };
+  }
+
+  let skill: SkillFile;
+  try {
+    skill = JSON.parse(content);
+  } catch {
+    return { success: false, reason: 'File is not valid JSON' };
+  }
+
+  const validation = validateImport(skill, localKey);
+  if (!validation.valid) {
+    return { success: false, reason: validation.reason };
+  }
+
+  // Strip foreign signature, set provenance
+  const importedSkill: SkillFile = {
+    ...skill,
+    provenance: 'imported',
+    signature: undefined,
+  };
+
+  const writtenPath = await writeSkillFile(importedSkill, skillsDir);
+  return { success: true, skillFile: writtenPath };
+}

package/src/skill/search.ts

@@ -0,0 +1,76 @@
+// src/skill/search.ts
+import { listSkillFiles, readSkillFile } from './store.js';
+
+export interface SearchResult {
+  domain: string;
+  endpointId: string;
+  method: string;
+  path: string;
+  tier: string;
+  verified: boolean;
+}
+
+export interface SearchResponse {
+  found: boolean;
+  results?: SearchResult[];
+  suggestion?: string;
+}
+
+/**
+ * Search skill files for endpoints matching a query.
+ * Matches against domain names, endpoint IDs, and endpoint paths.
+ * Query terms are matched case-insensitively.
+ */
+export async function searchSkills(
+  query: string,
+  skillsDir?: string,
+): Promise<SearchResponse> {
+  const summaries = await listSkillFiles(skillsDir);
+  if (summaries.length === 0) {
+    return {
+      found: false,
+      suggestion: 'No skill files found. Run `apitap capture <url>` to capture API traffic first.',
+    };
+  }
+
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const results: SearchResult[] = [];
+
+  for (const summary of summaries) {
+    const skill = await readSkillFile(summary.domain, skillsDir);
+    if (!skill) continue;
+
+    const domainLower = skill.domain.toLowerCase();
+
+    for (const ep of skill.endpoints) {
+      const endpointIdLower = ep.id.toLowerCase();
+      const pathLower = ep.path.toLowerCase();
+      const methodLower = ep.method.toLowerCase();
+
+      // Check if all query terms match against the combined searchable text
+      const searchText = `${domainLower} ${endpointIdLower} ${pathLower} ${methodLower}`;
+      const allMatch = terms.every(term => searchText.includes(term));
+
+      if (allMatch) {
+        results.push({
+          domain: skill.domain,
+          endpointId: ep.id,
+          method: ep.method,
+          path: ep.path,
+          tier: ep.replayability?.tier ?? 'unknown',
+          verified: ep.replayability?.verified ?? false,
+        });
+      }
+    }
+  }
+
+  if (results.length === 0) {
+    const domains = summaries.map(s => s.domain).join(', ');
+    return {
+      found: false,
+      suggestion: `No matches for "${query}". Available domains: ${domains}`,
+    };
+  }
+
+  return { found: true, results };
+}

package/src/skill/signing.ts

@@ -0,0 +1,36 @@
+// src/skill/signing.ts
+import { hmacSign, hmacVerify } from '../auth/crypto.js';
+import type { SkillFile } from '../types.js';
+
+/**
+ * Create a canonical JSON string from a skill file,
+ * excluding `signature` and `provenance` fields.
+ * This is the payload that gets signed.
+ */
+export function canonicalize(skill: SkillFile): string {
+  const { signature: _sig, provenance: _prov, ...rest } = skill;
+  return JSON.stringify(rest, Object.keys(rest).sort());
+}
+
+/**
+ * Sign a skill file. Returns a new object with signature and provenance: 'self'.
+ */
+export function signSkillFile(skill: SkillFile, key: Buffer): SkillFile {
+  const payload = canonicalize(skill);
+  const signature = hmacSign(payload, key);
+  return {
+    ...skill,
+    provenance: 'self',
+    signature,
+  };
+}
+
+/**
+ * Verify a skill file's signature.
+ * Returns true if the signature is valid for the given key.
+ */
+export function verifySignature(skill: SkillFile, key: Buffer): boolean {
+  if (!skill.signature) return false;
+  const payload = canonicalize(skill);
+  return hmacVerify(payload, skill.signature, key);
+}

package/src/skill/ssrf.ts

@@ -0,0 +1,238 @@
+// src/skill/ssrf.ts
+import { lookup } from 'node:dns/promises';
+import type { SkillFile } from '../types.js';
+
+export interface ValidationResult {
+  safe: boolean;
+  reason?: string;
+  resolvedUrl?: string;
+  resolvedIp?: string;
+  originalHost?: string;
+}
+
+const INTERNAL_HOSTNAMES = ['localhost'];
+const INTERNAL_SUFFIXES = ['.local', '.internal'];
+
+/**
+ * Check if a URL is safe to replay (not targeting internal infrastructure).
+ */
+export function validateUrl(urlString: string): ValidationResult {
+  let url: URL;
+  try {
+    url = new URL(urlString);
+  } catch {
+    return { safe: false, reason: 'Invalid URL' };
+  }
+
+  // Scheme check
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    return { safe: false, reason: `Non-HTTP scheme: ${url.protocol}` };
+  }
+
+  const hostname = url.hostname;
+
+  // Exact internal hostnames
+  if (INTERNAL_HOSTNAMES.includes(hostname)) {
+    return { safe: false, reason: `URL targets internal hostname: ${hostname}` };
+  }
+
+  // Internal domain suffixes
+  for (const suffix of INTERNAL_SUFFIXES) {
+    if (hostname.endsWith(suffix)) {
+      return { safe: false, reason: `URL targets internal domain: ${hostname}` };
+    }
+  }
+
+  // IPv6 loopback
+  if (hostname === '[::1]' || hostname === '::1') {
+    return { safe: false, reason: 'URL targets IPv6 loopback' };
+  }
+
+  // IPv4-mapped IPv6 — dotted-quad form (e.g. [::ffff:127.0.0.1])
+  const v4MappedMatch = hostname.match(/^\[?::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\]?$/i);
+  if (v4MappedMatch) {
+    return validateUrl(`${url.protocol}//${v4MappedMatch[1]}${url.port ? ':' + url.port : ''}${url.pathname}`);
+  }
+
+  // IPv4-mapped IPv6 — hex form (e.g. [::ffff:7f00:1], Node normalizes to this)
+  const v4MappedHexMatch = hostname.match(/^\[?::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})\]?$/i);
+  if (v4MappedHexMatch) {
+    const hi = parseInt(v4MappedHexMatch[1], 16);
+    const lo = parseInt(v4MappedHexMatch[2], 16);
+    const ipv4 = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    return validateUrl(`${url.protocol}//${ipv4}${url.port ? ':' + url.port : ''}${url.pathname}`);
+  }
+
+  // IPv6 link-local (fe80::/10)
+  if (/^\[?fe[89ab][0-9a-f]:/i.test(hostname)) {
+    return { safe: false, reason: `URL targets IPv6 link-local address: ${hostname}` };
+  }
+
+  // IPv6 unique local (fc00::/7 — includes fd00::/8)
+  if (/^\[?f[cd][0-9a-f]{2}:/i.test(hostname)) {
+    return { safe: false, reason: `URL targets IPv6 unique-local address: ${hostname}` };
+  }
+
+  // IPv4 private ranges
+  const ipv4Match = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4Match) {
+    const [, a, b] = ipv4Match.map(Number);
+    const first = Number(a);
+    const second = Number(b);
+
+    // 0.0.0.0 — unspecified
+    if (first === 0) {
+      return { safe: false, reason: `URL targets unspecified address: ${hostname}` };
+    }
+    // 127.x.x.x — loopback
+    if (first === 127) {
+      return { safe: false, reason: `URL targets loopback address: ${hostname}` };
+    }
+    // 10.x.x.x — private
+    if (first === 10) {
+      return { safe: false, reason: `URL targets private IP: ${hostname}` };
+    }
+    // 172.16-31.x.x — private
+    if (first === 172 && second >= 16 && second <= 31) {
+      return { safe: false, reason: `URL targets private IP: ${hostname}` };
+    }
+    // 192.168.x.x — private
+    if (first === 192 && second === 168) {
+      return { safe: false, reason: `URL targets private IP: ${hostname}` };
+    }
+    // 169.254.x.x — link-local
+    if (first === 169 && second === 254) {
+      return { safe: false, reason: `URL targets link-local address: ${hostname}` };
+    }
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Check if a resolved IP address is in a private/reserved range.
+ */
+function isPrivateIp(ip: string): string | null {
+  // IPv6 loopback
+  if (ip === '::1') return 'IPv6 loopback';
+
+  // IPv6 link-local (fe80::/10)
+  if (/^fe[89ab][0-9a-f]:/i.test(ip)) return 'IPv6 link-local';
+
+  // IPv6 unique local (fc00::/7 — includes fd00::/8)
+  if (/^f[cd][0-9a-f]{2}:/i.test(ip)) return 'IPv6 unique-local';
+
+  // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1)
+  const v4mapped = ip.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const ipv4 = v4mapped ? v4mapped[1] : ip;
+
+  const parts = ipv4.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!parts) return null; // Not an IPv4 — let it pass (non-private IPv6)
+
+  const [, a, b] = parts;
+  const first = Number(a);
+  const second = Number(b);
+
+  if (first === 127) return 'loopback';
+  if (first === 10) return 'private (10.x)';
+  if (first === 172 && second >= 16 && second <= 31) return 'private (172.16-31.x)';
+  if (first === 192 && second === 168) return 'private (192.168.x)';
+  if (first === 169 && second === 254) return 'link-local';
+  if (first === 0) return 'unspecified';
+
+  return null;
+}
+
+/**
+ * Resolve hostname and validate the resolved IP against private ranges.
+ * Prevents DNS rebinding attacks where a domain resolves to 127.0.0.1.
+ */
+export async function resolveAndValidateUrl(urlString: string): Promise<ValidationResult> {
+  // First run the sync hostname-based checks
+  const syncResult = validateUrl(urlString);
+  if (!syncResult.safe) return syncResult;
+
+  let url: URL;
+  try {
+    url = new URL(urlString);
+  } catch {
+    return { safe: false, reason: 'Invalid URL' };
+  }
+
+  const hostname = url.hostname;
+
+  // Skip DNS resolution for raw IPs (already checked by validateUrl)
+  if (hostname.match(/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/) || hostname.startsWith('[')) {
+    return { safe: true };
+  }
+
+  // Resolve DNS and check the actual IP
+  try {
+    const { address } = await lookup(hostname);
+    const privateReason = isPrivateIp(address);
+    if (privateReason) {
+      return { safe: false, reason: `DNS rebinding: ${hostname} resolves to ${address} (${privateReason})` };
+    }
+
+    // Return the resolved URL with IP pinned to prevent DNS rebinding
+    const pinnedUrl = new URL(urlString);
+    pinnedUrl.hostname = address;
+    return {
+      safe: true,
+      resolvedUrl: pinnedUrl.toString(),
+      resolvedIp: address,
+      originalHost: hostname
+    };
+  } catch {
+    // DNS resolution failed — hostname doesn't exist
+    return { safe: false, reason: `DNS resolution failed for ${hostname}` };
+  }
+}
+
+/**
+ * Validate all URLs in a skill file with DNS resolution.
+ * Checks baseUrl and all endpoint example URLs.
+ */
+export async function resolveAndValidateSkillFileUrls(skill: SkillFile): Promise<ValidationResult> {
+  const baseResult = await resolveAndValidateUrl(skill.baseUrl);
+  if (!baseResult.safe) {
+    return { safe: false, reason: `baseUrl: ${baseResult.reason}` };
+  }
+
+  for (const ep of skill.endpoints) {
+    const exUrl = ep.examples?.request?.url;
+    if (exUrl) {
+      const result = await resolveAndValidateUrl(exUrl);
+      if (!result.safe) {
+        return { safe: false, reason: `endpoint ${ep.id}: ${result.reason}` };
+      }
+    }
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Validate all URLs in a skill file (sync, hostname-based only).
+ * Checks baseUrl and all endpoint example URLs.
+ */
+export function validateSkillFileUrls(skill: SkillFile): ValidationResult {
+  // Check baseUrl
+  const baseResult = validateUrl(skill.baseUrl);
+  if (!baseResult.safe) {
+    return { safe: false, reason: `baseUrl: ${baseResult.reason}` };
+  }
+
+  // Check endpoint example URLs
+  for (const ep of skill.endpoints) {
+    const exUrl = ep.examples?.request?.url;
+    if (exUrl) {
+      const result = validateUrl(exUrl);
+      if (!result.safe) {
+        return { safe: false, reason: `endpoint ${ep.id}: ${result.reason}` };
+      }
+    }
+  }
+
+  return { safe: true };
+}

package/src/skill/store.ts

@@ -0,0 +1,107 @@
+// src/skill/store.ts
+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';
+
+const DEFAULT_SKILLS_DIR = join(homedir(), '.apitap', 'skills');
+
+const BASE_GITIGNORE = `# ApiTap — prevent accidental credential commits
+auth.enc
+*.key
+`;
+
+function skillPath(domain: string, skillsDir: string): string {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(domain)) {
+    throw new Error(`Invalid domain: ${domain}`);
+  }
+  return join(skillsDir, `${domain}.json`);
+}
+
+async function ensureGitignore(skillsDir: string): Promise<void> {
+  const baseDir = dirname(skillsDir);
+  const gitignorePath = join(baseDir, '.gitignore');
+
+  try {
+    await access(gitignorePath);
+    // File exists, don't overwrite
+  } catch {
+    // File doesn't exist, create it
+    await mkdir(baseDir, { recursive: true });
+    await writeFile(gitignorePath, BASE_GITIGNORE);
+  }
+}
+
+export async function writeSkillFile(
+  skill: SkillFile,
+  skillsDir: string = DEFAULT_SKILLS_DIR,
+): Promise<string> {
+  await mkdir(skillsDir, { recursive: true });
+  await ensureGitignore(skillsDir);
+  const filePath = skillPath(skill.domain, skillsDir);
+  await writeFile(filePath, JSON.stringify(skill, null, 2) + '\n');
+  return filePath;
+}
+
+export async function readSkillFile(
+  domain: string,
+  skillsDir: string = DEFAULT_SKILLS_DIR,
+  options?: { verifySignature?: boolean; signingKey?: Buffer }
+): Promise<SkillFile | null> {
+  // Validate domain before file I/O — path traversal should throw, not return null
+  const path = skillPath(domain, skillsDir);
+  try {
+    const content = await readFile(path, 'utf-8');
+    const skill = JSON.parse(content) as SkillFile;
+
+    // If verification requested, check signature
+    if (options?.verifySignature && options.signingKey) {
+      if (skill.provenance === 'imported') {
+        // 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`);
+      } else {
+        const { verifySignature } = await import('./signing.js');
+        if (!verifySignature(skill, options.signingKey)) {
+          throw new Error(`Skill file signature verification failed for ${domain} — file may be tampered`);
+        }
+      }
+    }
+
+    return skill;
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+export async function listSkillFiles(
+  skillsDir: string = DEFAULT_SKILLS_DIR,
+): Promise<SkillSummary[]> {
+  let files: string[];
+  try {
+    files = await readdir(skillsDir);
+  } catch {
+    return [];
+  }
+
+  const summaries: SkillSummary[] = [];
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    const domain = file.replace(/\.json$/, '');
+    const skill = await readSkillFile(domain, skillsDir);
+    if (skill) {
+      summaries.push({
+        domain: skill.domain,
+        skillFile: join(skillsDir, file),
+        endpointCount: skill.endpoints.length,
+        capturedAt: skill.capturedAt,
+        provenance: skill.provenance ?? 'unsigned',
+      });
+    }
+  }
+
+  return summaries;
+}