@apitap/core 1.3.1 → 1.4.1

package/src/replay/engine.ts

@@ -139,6 +139,41 @@ function normalizeOptions(
   return { params: optionsOrParams as Record<string, string> };
 }
 
+/**
+ * Check if redirect host is safe to send auth to.
+ * Allows exact match or single-level subdomain only (H4 fix).
+ */
+function isSafeAuthRedirectHost(originalHost: string, redirectHost: string): boolean {
+  if (redirectHost === originalHost) return true;
+  if (redirectHost.endsWith('.' + originalHost)) {
+    const prefix = redirectHost.slice(0, -(originalHost.length + 1));
+    // Only allow single-level subdomain (no dots in prefix)
+    return !prefix.includes('.');
+  }
+  return false;
+}
+
+/**
+ * Strip auth headers from redirect request if cross-domain (H4 fix).
+ * Shared between initial and retry redirect paths.
+ */
+function stripAuthForRedirect(
+  headers: Record<string, string>,
+  originalHost: string,
+  redirectHost: string,
+): Record<string, string> {
+  const redirectHeaders = { ...headers };
+  if (!isSafeAuthRedirectHost(originalHost, redirectHost)) {
+    delete redirectHeaders['authorization'];
+    for (const key of Object.keys(redirectHeaders)) {
+      if (key.toLowerCase() === 'authorization' || redirectHeaders[key] === '[stored]') {
+        delete redirectHeaders[key];
+      }
+    }
+  }
+  return redirectHeaders;
+}
+
 /**
  * Wrap a 401/403 response with structured auth guidance.
  */
@@ -209,7 +244,7 @@ export async function replayEndpoint(
   // SSRF validation — resolve DNS and check the IP isn't private/internal.
   // We do NOT substitute the IP into the URL because that breaks TLS/SNI
   // for sites behind CDNs (Cloudflare, etc.) where the cert is for the hostname.
-  // The DNS check still prevents rebinding attacks by validating at request time.
+  // M15: We re-validate DNS after fetch to narrow the TOCTOU window.
   const fetchUrl = url.toString();
   if (!options._skipSsrfCheck) {
     const ssrfCheck = await resolveAndValidateUrl(url.toString());
@@ -237,6 +272,19 @@ export async function replayEndpoint(
     }
   }
 
+  // Domain-lock: verify request URL matches skill domain before injecting auth (C1 fix).
+  // validateSkillFile() enforces baseUrl-domain consistency at load time.
+  // This is defense-in-depth for manually-constructed SkillFile objects.
+  if (authManager && domain && !options._skipSsrfCheck) {
+    const fetchHost = url.hostname;
+    if (fetchHost !== skill.domain && !fetchHost.endsWith('.' + skill.domain)) {
+      throw new Error(
+        `Domain-lock violation: request host "${fetchHost}" does not match skill domain "${skill.domain}". ` +
+        `Auth injection blocked to prevent credential exfiltration.`
+      );
+    }
+  }
+
   // Inject auth header from auth manager (if available)
   if (authManager && domain) {
     const auth = endpoint.isolatedAuth
@@ -376,6 +424,16 @@ export async function replayEndpoint(
     redirect: 'manual',  // Don't auto-follow redirects
   });
 
+  // M15: Post-fetch DNS re-validation to narrow TOCTOU window.
+  // Re-resolves DNS and checks if the hostname now points to a private IP
+  // (indicates DNS rebinding attack between our pre-check and the actual connection).
+  if (!options._skipSsrfCheck && url.hostname && !url.hostname.match(/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/)) {
+    const postCheck = await resolveAndValidateUrl(fetchUrl);
+    if (!postCheck.safe) {
+      throw new Error(`DNS rebinding detected (post-fetch): ${postCheck.reason}`);
+    }
+  }
+
   // Handle redirects with SSRF validation (single hop only)
   if (response.status >= 300 && response.status < 400) {
     const location = response.headers.get('location');
@@ -388,18 +446,8 @@ export async function replayEndpoint(
           throw new Error(`Redirect blocked (SSRF): ${redirectCheck.reason}`);
         }
       }
-      // Strip auth headers before cross-domain redirect
-      const redirectHeaders = { ...headers };
-      const originalHost = url.hostname;
-      const redirectHost = redirectUrl.hostname;
-      if (redirectHost !== originalHost && !redirectHost.endsWith('.' + originalHost)) {
-        delete redirectHeaders['authorization'];
-        for (const key of Object.keys(redirectHeaders)) {
-          if (key.toLowerCase() === 'authorization' || redirectHeaders[key] === '[stored]') {
-            delete redirectHeaders[key];
-          }
-        }
-      }
+      // Strip auth headers before cross-domain redirect (uses shared function)
+      const redirectHeaders = stripAuthForRedirect(headers, url.hostname, redirectUrl.hostname);
       // Follow the redirect manually (single hop to prevent chains)
       response = await fetch(redirectFetchUrl, {
         method: 'GET',  // Redirects typically become GET
@@ -437,7 +485,7 @@ export async function replayEndpoint(
         redirect: 'manual',
       });
 
-      // Handle redirects on retry (single hop)
+      // Handle redirects on retry (single hop) — with auth stripping (H4 fix)
       if (retryResponse.status >= 300 && retryResponse.status < 400) {
         const location = retryResponse.headers.get('location');
         if (location) {
@@ -449,9 +497,11 @@ export async function replayEndpoint(
               throw new Error(`Redirect blocked (SSRF): ${redirectCheck.reason}`);
             }
           }
+          // Strip auth headers on cross-domain redirect (same logic as initial path)
+          const retryRedirectHeaders = stripAuthForRedirect(headers, url.hostname, redirectUrl.hostname);
           retryResponse = await fetch(retryRedirectFetchUrl, {
             method: 'GET',
-            headers,
+            headers: retryRedirectHeaders,
             signal: AbortSignal.timeout(30_000),
             redirect: 'manual',
           });
@@ -569,17 +619,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/serve.ts

@@ -75,6 +75,8 @@ export function buildServeTools(skill: SkillFile): ServeTool[] {
 export interface ServeOptions {
   skillsDir?: string;
   noAuth?: boolean;
+  /** Allow loading unsigned skill files */
+  trustUnsigned?: boolean;
   /** @internal Skip SSRF validation — for testing only */
   _skipSsrfCheck?: boolean;
 }
@@ -87,7 +89,7 @@ export async function createServeServer(
   domain: string,
   options: ServeOptions = {},
 ): Promise<McpServer> {
-  const skill = await readSkillFile(domain, options.skillsDir);
+  const skill = await readSkillFile(domain, options.skillsDir, { trustUnsigned: options.trustUnsigned });
   if (!skill) {
     throw new Error(`No skill file found for "${domain}". Run: apitap capture ${domain}`);
   }
@@ -146,11 +148,18 @@ export async function createServeServer(
             _skipSsrfCheck: options._skipSsrfCheck,
           });
 
+          // M22: Mark responses as untrusted external content
           return {
             content: [{
               type: 'text' as const,
               text: JSON.stringify({ status: result.status, data: result.data }),
             }],
+            _meta: {
+              externalContent: {
+                untrusted: true,
+                source: `apitap-serve-${domain}`,
+              },
+            },
           };
         } catch (err: any) {
           console.error('Replay failed:', err instanceof Error ? err.message : String(err));

package/src/skill/generator.ts

@@ -316,10 +316,10 @@ export class SkillGenerator {
     this.totalNetworkBytes += exchange.response.body.length;
 
     if (this.endpoints.has(key)) {
-      // Store duplicate body for cross-request diffing (Strategy 1)
+      // Store duplicate body for cross-request diffing (Strategy 1) — scrubbed (H3 fix)
       if (exchange.request.postData) {
         const bodies = this.exchangeBodies.get(key);
-        if (bodies) bodies.push(exchange.request.postData);
+        if (bodies) bodies.push(this.scrubBodyString(exchange.request.postData));
       }
       return null;
     }
@@ -455,9 +455,17 @@ export class SkillGenerator {
 
     this.endpoints.set(key, endpoint);
 
-    // Store first body for cross-request diffing
+    // Store first body for cross-request diffing (scrub sensitive fields — H3 fix)
     if (exchange.request.postData) {
-      this.exchangeBodies.set(key, [exchange.request.postData]);
+      this.exchangeBodies.set(key, [this.scrubBodyString(exchange.request.postData)]);
+    }
+
+    // Clear auth values from exchange to reduce credential exposure window (H3 fix)
+    for (const key of Object.keys(exchange.request.headers)) {
+      const lower = key.toLowerCase();
+      if (AUTH_HEADERS.has(lower) || lower === 'cookie') {
+        exchange.request.headers[key] = '[scrubbed]';
+      }
     }
 
     return endpoint;
@@ -513,6 +521,23 @@ export class SkillGenerator {
     this.totalNetworkBytes += bytes;
   }
 
+  /**
+   * Scrub sensitive fields from a POST body string for intermediate storage (H3 fix).
+   * Preserves structure for cross-request diffing while removing credentials.
+   */
+  private scrubBodyString(bodyStr: string): string {
+    try {
+      const parsed = JSON.parse(bodyStr);
+      if (typeof parsed === 'object' && parsed !== null) {
+        const scrubbed = scrubBody(parsed, true) as Record<string, unknown>;
+        return JSON.stringify(scrubbed);
+      }
+    } catch {
+      // Non-JSON body — apply PII scrubber
+    }
+    return scrubPII(bodyStr);
+  }
+
   /** Generate the complete skill file for a domain. */
   toSkillFile(domain: string, options?: { domBytes?: number; totalRequests?: number }): SkillFile {
     // Apply cross-request diffing (Strategy 1) to endpoints with multiple bodies
@@ -559,6 +584,9 @@ export class SkillGenerator {
       };
     }
 
+    // Clear intermediate body storage to reduce credential exposure window (H3 fix)
+    this.exchangeBodies.clear();
+
     return skill;
   }
 }

package/src/skill/search.ts

@@ -37,7 +37,7 @@ export async function searchSkills(
   const results: SearchResult[] = [];
 
   for (const summary of summaries) {
-    const skill = await readSkillFile(summary.domain, skillsDir);
+    const skill = await readSkillFile(summary.domain, skillsDir, { trustUnsigned: true });
     if (!skill) continue;
 
     const domainLower = skill.domain.toLowerCase();

package/src/skill/signing.ts

@@ -9,7 +9,26 @@ import type { SkillFile } from '../types.js';
  */
 export function canonicalize(skill: SkillFile): string {
   const { signature: _sig, provenance: _prov, ...rest } = skill;
-  return JSON.stringify(rest, Object.keys(rest).sort());
+  return JSON.stringify(sortKeysDeep(rest));
+}
+
+/**
+ * Recursively sort all object keys for stable canonicalization (M10 fix).
+ * Ensures identical skill files always produce the same canonical string
+ * regardless of key insertion order at any nesting level.
+ */
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
 }
 
 /**

package/src/skill/ssrf.ts

@@ -73,8 +73,12 @@ export function validateUrl(urlString: string): ValidationResult {
     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})$/);
+  // Normalize IP representations: decimal integer, octal, hex → dotted-decimal (M17 fix)
+  const normalizedIp = normalizeIpv4(hostname);
+  const ipToCheck = normalizedIp ?? hostname;
+
+  // IPv4 private/reserved ranges (M16: added CGNAT, IETF, benchmarking, reserved)
+  const ipv4Match = ipToCheck.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);
@@ -104,11 +108,70 @@ export function validateUrl(urlString: string): ValidationResult {
     if (first === 169 && second === 254) {
       return { safe: false, reason: `URL targets link-local address: ${hostname}` };
     }
+    // 100.64.0.0/10 — CGNAT (RFC 6598), used in cloud/Tailscale
+    if (first === 100 && second >= 64 && second <= 127) {
+      return { safe: false, reason: `URL targets CGNAT address: ${hostname}` };
+    }
+    // 192.0.0.0/24 — IETF Protocol Assignments (RFC 6890)
+    if (first === 192 && second === 0 && Number(ipv4Match[3]) === 0) {
+      return { safe: false, reason: `URL targets IETF reserved address: ${hostname}` };
+    }
+    // 198.18.0.0/15 — Benchmarking (RFC 2544)
+    if (first === 198 && (second === 18 || second === 19)) {
+      return { safe: false, reason: `URL targets benchmarking address: ${hostname}` };
+    }
+    // 240.0.0.0/4 — Reserved/future use
+    if (first >= 240) {
+      return { safe: false, reason: `URL targets reserved address: ${hostname}` };
+    }
   }
 
   return { safe: true };
 }
 
+/**
+ * Normalize alternative IPv4 representations to dotted-decimal.
+ * Handles decimal integer (2130706433), octal (0177.0.0.1), and hex (0x7f.0.0.1).
+ * Returns null if hostname is not an IP address or can't be parsed.
+ */
+function normalizeIpv4(hostname: string): string | null {
+  // Already standard dotted-decimal
+  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+    return hostname;
+  }
+
+  // Pure decimal integer (e.g. 2130706433 = 127.0.0.1)
+  if (/^\d+$/.test(hostname)) {
+    const num = parseInt(hostname, 10);
+    if (num >= 0 && num <= 0xFFFFFFFF) {
+      return `${(num >>> 24) & 0xFF}.${(num >>> 16) & 0xFF}.${(num >>> 8) & 0xFF}.${num & 0xFF}`;
+    }
+  }
+
+  // Dotted with octal (0-prefixed) or hex (0x-prefixed) octets
+  const parts = hostname.split('.');
+  if (parts.length === 4) {
+    const octets: number[] = [];
+    for (const part of parts) {
+      let val: number;
+      if (/^0x[0-9a-f]+$/i.test(part)) {
+        val = parseInt(part, 16);
+      } else if (/^0[0-7]+$/.test(part)) {
+        val = parseInt(part, 8);
+      } else if (/^\d+$/.test(part)) {
+        val = parseInt(part, 10);
+      } else {
+        return null; // Not an IP
+      }
+      if (val < 0 || val > 255) return null;
+      octets.push(val);
+    }
+    return octets.join('.');
+  }
+
+  return null;
+}
+
 /**
  * Check if a resolved IP address is in a private/reserved range.
  */
@@ -148,6 +211,10 @@ function isPrivateIp(ip: string): string | null {
   if (first === 192 && second === 168) return 'private (192.168.x)';
   if (first === 169 && second === 254) return 'link-local';
   if (first === 0) return 'unspecified';
+  // M16: additional reserved ranges
+  if (first === 100 && second >= 64 && second <= 127) return 'CGNAT (100.64/10)';
+  if (first === 198 && (second === 18 || second === 19)) return 'benchmarking (198.18/15)';
+  if (first >= 240) return 'reserved (240/4)';
 
   return null;
 }

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');
 
@@ -36,7 +37,7 @@ export async function writeSkillFile(
   skill: SkillFile,
   skillsDir: string = DEFAULT_SKILLS_DIR,
 ): Promise<string> {
-  await mkdir(skillsDir, { recursive: true });
+  await mkdir(skillsDir, { recursive: true, mode: 0o700 });
   await ensureGitignore(skillsDir);
   const filePath = skillPath(skill.domain, skillsDir);
   await writeFile(filePath, JSON.stringify(skill, null, 2) + '\n', { mode: 0o600 });
@@ -46,25 +47,45 @@ export async function writeSkillFile(
 export async function readSkillFile(
   domain: string,
   skillsDir: string = DEFAULT_SKILLS_DIR,
-  options?: { verifySignature?: boolean; signingKey?: Buffer }
+  options?: {
+    verifySignature?: boolean;
+    signingKey?: Buffer;
+    /** Allow loading unsigned files without throwing. Tampered signed files still reject. */
+    trustUnsigned?: boolean;
+  }
 ): 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;
+    const raw = JSON.parse(content);
+    const skill = validateSkillFile(raw);
+
+    // Signature verification is ON by default (H1 fix)
+    const shouldVerify = options?.verifySignature !== false;
+    if (shouldVerify) {
+      // Auto-derive signing key if not provided
+      let signingKey = options?.signingKey;
+      if (!signingKey) {
+        const { deriveSigningKey } = await import('../auth/crypto.js');
+        const { getMachineId } = await import('../auth/manager.js');
+        const machineId = await getMachineId();
+        signingKey = deriveSigningKey(machineId);
+      }
 
-    // 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
+        // Imported files had foreign signature stripped — can't verify
       } 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`);
+        // Unsigned files are rejected unless trustUnsigned is set
+        if (!options?.trustUnsigned) {
+          throw new Error(
+            `Skill file for ${domain} is unsigned and cannot be verified. ` +
+            `Re-capture or re-import the skill file, or use --trust-unsigned to load it.`
+          );
+        }
       } else {
         const { verifySignature } = await import('./signing.js');
-        if (!verifySignature(skill, options.signingKey)) {
+        if (!verifySignature(skill, signingKey)) {
           throw new Error(`Skill file signature verification failed for ${domain} — file may be tampered`);
         }
       }
@@ -93,7 +114,7 @@ export async function listSkillFiles(
     if (!file.endsWith('.json')) continue;
     const domain = file.replace(/\.json$/, '');
     if (!DOMAIN_RE.test(domain)) continue; // skip non-conforming filenames
-    const skill = await readSkillFile(domain, skillsDir);
+    const skill = await readSkillFile(domain, skillsDir, { trustUnsigned: true });
     if (skill) {
       summaries.push({
         domain: skill.domain,

package/src/skill/validate.ts

@@ -0,0 +1,120 @@
+// 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');
+  }
+  let baseUrlHostname: string;
+  try {
+    const url = new URL(obj.baseUrl);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      throw new Error('non-HTTP scheme');
+    }
+    baseUrlHostname = url.hostname;
+  } catch {
+    throw new Error(`Invalid baseUrl: must be a valid HTTP(S) URL`);
+  }
+
+  // Domain-lock: baseUrl hostname must match or be a subdomain of domain (C1 fix)
+  const domainStr = obj.domain as string;
+  if (baseUrlHostname !== domainStr && !baseUrlHostname.endsWith('.' + domainStr)) {
+    throw new Error(
+      `baseUrl hostname "${baseUrlHostname}" does not match domain "${domainStr}". ` +
+      `Skill files cannot redirect requests to unrelated hosts.`
+    );
+  }
+
+  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`);
+    }
+
+    // M11: Deep type validation on nested structures
+    if ('headers' in e && e.headers !== undefined) {
+      if (typeof e.headers !== 'object' || e.headers === null || Array.isArray(e.headers)) {
+        throw new Error(`Endpoint ${i}: headers must be an object`);
+      }
+      for (const [hk, hv] of Object.entries(e.headers as Record<string, unknown>)) {
+        if (typeof hv !== 'string') {
+          throw new Error(`Endpoint ${i}: header "${hk}" value must be a string`);
+        }
+      }
+    }
+
+    if ('queryParams' in e && e.queryParams !== undefined) {
+      if (typeof e.queryParams !== 'object' || e.queryParams === null || Array.isArray(e.queryParams)) {
+        throw new Error(`Endpoint ${i}: queryParams must be an object`);
+      }
+      for (const [qk, qv] of Object.entries(e.queryParams as Record<string, unknown>)) {
+        if (typeof qv !== 'object' || qv === null || typeof (qv as any).example !== 'string') {
+          throw new Error(`Endpoint ${i}: queryParam "${qk}" must have a string example`);
+        }
+      }
+    }
+
+    if ('requestBody' in e && e.requestBody !== undefined) {
+      const rb = e.requestBody as Record<string, unknown>;
+      if (typeof rb !== 'object' || rb === null) {
+        throw new Error(`Endpoint ${i}: requestBody must be an object`);
+      }
+      if (typeof rb.contentType !== 'string') {
+        throw new Error(`Endpoint ${i}: requestBody.contentType must be a string`);
+      }
+      if (rb.variables !== undefined && !Array.isArray(rb.variables)) {
+        throw new Error(`Endpoint ${i}: requestBody.variables must be an array`);
+      }
+    }
+  }
+
+  return raw as SkillFile;
+}