@apitap/core 1.4.0 → 1.4.1

package/src/discovery/fetch.ts

@@ -27,9 +27,9 @@ export async function safeFetch(
   url: string,
   options: SafeFetchOptions = {},
 ): Promise<FetchResult | null> {
-  // SSRF check
+  // M18: Use DNS-resolving SSRF check to prevent rebinding attacks
   if (!options.skipSsrf) {
-    const ssrfResult = validateUrl(url);
+    const ssrfResult = await resolveAndValidateUrl(url);
     if (!ssrfResult.safe) return null;
   }
 

package/src/mcp.ts

@@ -49,14 +49,40 @@ export interface McpServerOptions {
   skillsDir?: string;
   /** @internal Skip SSRF check in replay — for testing only */
   _skipSsrfCheck?: boolean;
+  /** Rate limit: max outbound requests per minute (default: 60). Set 0 to disable. */
+  rateLimitPerMinute?: number;
 }
 
 const MAX_SESSIONS = 3;
 
+/**
+ * M23: Simple sliding-window rate limiter for outbound MCP tool calls.
+ * Prevents misconfigured agents from flooding target APIs.
+ */
+class RateLimiter {
+  private timestamps: number[] = [];
+  private readonly maxPerMinute: number;
+
+  constructor(maxPerMinute: number) {
+    this.maxPerMinute = maxPerMinute;
+  }
+
+  check(): boolean {
+    if (this.maxPerMinute <= 0) return true; // Disabled
+    const now = Date.now();
+    const windowStart = now - 60_000;
+    this.timestamps = this.timestamps.filter(t => t > windowStart);
+    if (this.timestamps.length >= this.maxPerMinute) return false;
+    this.timestamps.push(now);
+    return true;
+  }
+}
+
 export function createMcpServer(options: McpServerOptions = {}): McpServer {
   const skillsDir = options.skillsDir;
   const sessions = new Map<string, CaptureSession>();
   const sessionCache = new SessionCache();
+  const rateLimiter = new RateLimiter(options.rateLimitPerMinute ?? 60);
 
   const server = new McpServer({
     name: 'apitap',
@@ -80,9 +106,7 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
     },
     async ({ query }) => {
       const result = await searchSkills(query, skillsDir);
-      return {
-        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
-      };
+      return wrapExternalContent(result, 'apitap_search');
     },
   );
 
@@ -103,6 +127,9 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       },
     },
     async ({ url }) => {
+      if (!rateLimiter.check()) {
+        return { content: [{ type: 'text' as const, text: 'Rate limit exceeded. Try again in a moment.' }], isError: true };
+      }
       try {
         if (!options._skipSsrfCheck) {
           const validation = await resolveAndValidateUrl(url);
@@ -112,18 +139,18 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
         }
         const result = await discover(url);
 
-        // If we got a skill file, save it automatically
+        // If we got a skill file, sign and save it automatically
         if (result.skillFile && (result.confidence === 'high' || result.confidence === 'medium')) {
           const { writeSkillFile } = await import('./skill/store.js');
+          const { signSkillFile } = await import('./skill/signing.js');
+          const machineId = await getMachineId();
+          const sigKey = deriveSigningKey(machineId);
+          result.skillFile = signSkillFile(result.skillFile, sigKey);
           const path = await writeSkillFile(result.skillFile, skillsDir);
-          return {
-            content: [{ type: 'text' as const, text: JSON.stringify({ ...result, savedTo: path }) }],
-          };
+          return wrapExternalContent({ ...result, savedTo: path }, 'apitap_discover');
         }
 
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result) }],
-        };
+        return wrapExternalContent(result, 'apitap_discover');
       } catch (err: any) {
         return {
           content: [{ type: 'text' as const, text: `Discovery failed: ${err.message}` }],
@@ -154,6 +181,9 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       },
     },
     async ({ domain, endpointId, params, fresh, maxBytes }) => {
+      if (!rateLimiter.check()) {
+        return { content: [{ type: 'text' as const, text: 'Rate limit exceeded. Try again in a moment.' }], isError: true };
+      }
       const machineId = await getMachineId();
       const signingKey = deriveSigningKey(machineId);
       const skill = await readSkillFile(domain, skillsDir, { verifySignature: true, signingKey });
@@ -258,6 +288,9 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       },
     },
     async ({ url, task, maxBytes }) => {
+      if (!rateLimiter.check()) {
+        return { content: [{ type: 'text' as const, text: 'Rate limit exceeded. Try again in a moment.' }], isError: true };
+      }
       if (!options._skipSsrfCheck) {
         const validation = await resolveAndValidateUrl(url);
         if (!validation.safe) {
@@ -274,13 +307,8 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
         // In test mode, disable bridge to avoid connecting to real socket
         ...(options._skipSsrfCheck ? { _bridgeSocketPath: '/nonexistent' } : {}),
       });
-      // Only mark as untrusted if it contains external data
-      if (result.success && result.data) {
-        return wrapExternalContent(result, 'apitap_browse');
-      }
-      return {
-        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
-      };
+      // Always mark as untrusted — failed results may contain attacker-controlled strings (H7 fix)
+      return wrapExternalContent(result, 'apitap_browse');
     },
   );
 
@@ -336,6 +364,9 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       },
     },
     async ({ url, maxBytes }) => {
+      if (!rateLimiter.check()) {
+        return { content: [{ type: 'text' as const, text: 'Rate limit exceeded. Try again in a moment.' }], isError: true };
+      }
       try {
         if (!options._skipSsrfCheck) {
           const validation = await resolveAndValidateUrl(url);
@@ -404,9 +435,7 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
             setTimeout(() => reject(new Error('Capture timed out')), timeoutMs),
           ),
         ]);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result) }],
-        };
+        return wrapExternalContent(result, 'apitap_capture');
       } catch (err: any) {
         try { await session.abort(); } catch { /* already closed */ }
         return {
@@ -457,9 +486,8 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
         });
         const snapshot = await session.start(url);
         sessions.set(session.id, session);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify({ sessionId: session.id, snapshot }) }],
-        };
+        // Mark as untrusted — snapshot contains external page content (H5 fix)
+        return wrapExternalContent({ sessionId: session.id, snapshot }, 'apitap_capture_start');
       } catch (err: any) {
         return {
           content: [{ type: 'text' as const, text: `Failed to start capture session: ${err.message}` }],
@@ -518,8 +546,10 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
         submit,
       });
 
+      // Mark as untrusted — result contains external page content (H5 fix)
+      const wrapped = wrapExternalContent(result, 'apitap_capture_interact');
       return {
-        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+        ...wrapped,
         ...(result.success ? {} : { isError: true }),
       };
     },
@@ -560,15 +590,11 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
       try {
         if (shouldAbort) {
           await session.abort();
-          return {
-            content: [{ type: 'text' as const, text: JSON.stringify({ aborted: true, domains: [] }) }],
-          };
+          return wrapExternalContent({ aborted: true, domains: [] }, 'apitap_capture_finish');
         }
 
         const result = await session.finish();
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result) }],
-        };
+        return wrapExternalContent(result, 'apitap_capture_finish');
       } catch (err: any) {
         return {
           content: [{ type: 'text' as const, text: `Finish failed: ${err.message}` }],
@@ -609,8 +635,9 @@ export function createMcpServer(options: McpServerOptions = {}): McpServer {
           timeout: timeout ? timeout * 1000 : undefined,
         });
 
+        const wrapped = wrapExternalContent(result, 'apitap_auth_request');
         return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+          ...wrapped,
           ...(result.success ? {} : { isError: true }),
         };
       } catch (err: any) {

package/src/orchestration/browse.ts

@@ -4,6 +4,9 @@ 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';
+import { signSkillFile } from '../skill/signing.js';
+import { deriveSigningKey } from '../auth/crypto.js';
+import { getMachineId } from '../auth/manager.js';
 
 export interface BrowseOptions {
   skillsDir?: string;
@@ -61,11 +64,14 @@ async function tryBridgeCapture(
 
   if (result.success && result.skillFiles && result.skillFiles.length > 0) {
     const skillFiles = result.skillFiles;
-    // Save each skill file to disk
+    // Sign and 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);
+      const mid = await getMachineId();
+      const sk = deriveSigningKey(mid);
+      for (let i = 0; i < skillFiles.length; i++) {
+        skillFiles[i] = signSkillFile(skillFiles[i], sk);
+        await writeSF(skillFiles[i], options.skillsDir);
       }
     } catch {
       // Saving failed — still have the data in memory
@@ -202,7 +208,10 @@ export async function browse(
         skill = discovery.skillFile;
         source = 'discovered';
 
-        // Save to disk
+        // Sign and save to disk (H1: skill files must be signed for verification)
+        const machineId = await getMachineId();
+        const sigKey = deriveSigningKey(machineId);
+        skill = signSkillFile(skill, sigKey);
         const { writeSkillFile: writeSF } = await import('../skill/store.js');
         await writeSF(skill, skillsDir);
         cache?.set(domain, skill, 'discovered');

package/src/plugin.ts

@@ -21,12 +21,17 @@ export interface Plugin {
 
 export interface PluginOptions {
   skillsDir?: string;
-  /** @internal Skip SSRF check — for testing only */
+  /** @internal Testing only — never expose to external callers (M14) */
   _skipSsrfCheck?: boolean;
 }
 
 const APITAP_DIR = join(homedir(), '.apitap');
 
+/** M20: Mark plugin responses as untrusted external content */
+function wrapUntrusted(data: unknown): unknown {
+  return { ...data as Record<string, unknown>, _meta: { externalContent: { untrusted: true } } };
+}
+
 export function createPlugin(options: PluginOptions = {}): Plugin {
   const skillsDir = options.skillsDir;
 
@@ -53,7 +58,7 @@ export function createPlugin(options: PluginOptions = {}): Plugin {
     },
     execute: async (args) => {
       const query = args.query as string;
-      return searchSkills(query, skillsDir);
+      return wrapUntrusted(await searchSkills(query, skillsDir));
     },
   };
 
@@ -88,7 +93,7 @@ export function createPlugin(options: PluginOptions = {}): Plugin {
       const endpointId = args.endpointId as string;
       const params = args.params as Record<string, string> | undefined;
 
-      const skill = await readSkillFile(domain, skillsDir);
+      const skill = await readSkillFile(domain, skillsDir, { trustUnsigned: true });
       if (!skill) {
         return {
           error: `No skill file found for "${domain}". Use apitap_capture to capture it first.`,
@@ -104,7 +109,7 @@ export function createPlugin(options: PluginOptions = {}): Plugin {
           domain,
           _skipSsrfCheck: options._skipSsrfCheck,
         });
-        return { status: result.status, data: result.data };
+        return wrapUntrusted({ status: result.status, data: result.data });
       } catch (err: any) {
         return { error: err.message };
       }
@@ -142,6 +147,13 @@ export function createPlugin(options: PluginOptions = {}): Plugin {
       const duration = (args.duration as number) ?? 30;
       const allDomains = (args.allDomains as boolean) ?? false;
 
+      // M19: SSRF validation before capture
+      const { resolveAndValidateUrl } = await import('./skill/ssrf.js');
+      const ssrfCheck = await resolveAndValidateUrl(url);
+      if (!ssrfCheck.safe) {
+        return { error: `Blocked: ${ssrfCheck.reason}` };
+      }
+
       // Shell out to CLI for capture (it handles browser lifecycle, signing, etc.)
       const { execFile } = await import('node:child_process');
       const { promisify } = await import('node:util');
@@ -155,7 +167,7 @@ export function createPlugin(options: PluginOptions = {}): Plugin {
           timeout: (duration + 30) * 1000,
           env: { ...process.env, ...(skillsDir ? { APITAP_SKILLS_DIR: skillsDir } : {}) },
         });
-        return JSON.parse(stdout);
+        return wrapUntrusted(JSON.parse(stdout));
       } catch (err: any) {
         return { error: `Capture failed: ${err.message}` };
       }

package/src/read/decoders/reddit.ts

@@ -58,9 +58,9 @@ 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;
+  // M21: Third-party requests are opt-in, not opt-out.
+  // PullPush is an external service — only contact it if explicitly enabled.
+  if (process.env.APITAP_THIRD_PARTY !== '1') return recovered;
 
   try {
     const ids = commentIds.join(',');

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',
           });

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;
 }
 
 /**