feat: Custom lint rules

packages/insomnia-inso/src/cli.ts

@@ -886,7 +886,11 @@ export const go = (args?: string[]) => {
     )
     .command('spec [identifier]')
     .description('Lint an API Specification, identifier can be an API Spec id or a file path')
-    .action(async identifier => {
+    .option(
+      '-r, --ruleset <path>',
+      'path to a Spectral ruleset file, overrides default OAS ruleset and any ruleset in the API Spec folder',
+    )
+    .action(async (identifier, cmd: { ruleset?: string }) => {
       const options = await mergeOptionsAndInit({});
 
       // Assert identifier is a file
@@ -899,11 +903,16 @@ export const go = (args?: string[]) => {
       const pathToSearch = '';
       let specContent: string | undefined;
       let rulesetFileName: string | undefined;
+      if (cmd.ruleset) {
+        rulesetFileName = getAbsoluteFilePath({ workingDir: options.workingDir, file: cmd.ruleset });
+      }
       if (isIdentifierAFile) {
         // try load as a file
         logger.trace(`Linting specification file from identifier: \`${identifierAsAbsPath}\``);
         specContent = await fs.promises.readFile(identifierAsAbsPath, 'utf8');
-        rulesetFileName = await getRuleSetFileFromFolderByFilename(identifierAsAbsPath);
+        if (!rulesetFileName) {
+          rulesetFileName = await getRuleSetFileFromFolderByFilename(identifierAsAbsPath);
+        }
         if (!specContent) {
           logger.fatal(`Specification content not found using path: ${identifier} in ${identifierAsAbsPath}`);
           return process.exit(1);

packages/insomnia-inso/src/commands/lint-specification.ts

@@ -7,6 +7,8 @@ import path from 'node:path';
 
 import { oas } from '@stoplight/spectral-rulesets';
 import { DiagnosticSeverity } from '@stoplight/types';
+import { safeRefResolver } from 'insomnia/src/common/safe-ref-resolver';
+import { validateSpectralRuleset } from 'insomnia/src/common/spectral-ruleset-validator';
 
 import { InsoError } from '../errors';
 import { logger } from '../logger';
@@ -31,11 +33,17 @@ export async function lintSpecification({
   specContent: string;
   rulesetFileName?: string;
 }) {
-  const spectral = new Spectral();
+  const spectral = new Spectral({ resolver: safeRefResolver });
   // Use custom ruleset if present
   let ruleset = oas;
   try {
     if (rulesetFileName) {
+      const rulesetContent = await fs.promises.readFile(rulesetFileName, 'utf8');
+      const validation = validateSpectralRuleset(rulesetContent);
+      if (!validation.isValid) {
+        logger.fatal(`Invalid Spectral ruleset: ${validation.error}`);
+        return { isValid: false };
+      }
       ruleset = await bundleAndLoadRuleset(rulesetFileName, { fs });
     }
   } catch (error) {
@@ -45,6 +53,7 @@ export async function lintSpecification({
 
   spectral.setRuleset(ruleset as RulesetDefinition);
   const results = await spectral.run(specContent);
+
   if (!results.length) {
     logger.log('No linting errors or warnings.');
     return { results, isValid: true };

packages/insomnia/package.json

@@ -68,6 +68,7 @@
     "@sentry/electron": "^6.5.0",
     "@stoplight/spectral-core": "^1.22.0",
     "@stoplight/spectral-formats": "^1.8.2",
+    "@stoplight/spectral-ref-resolver": "^1.0.5",
     "@stoplight/spectral-ruleset-bundler": "1.7.0",
     "@stoplight/spectral-rulesets": "^1.22.1",
     "@tailwindcss/typography": "^0.5.16",
@@ -113,6 +114,7 @@
     "https-proxy-agent": "^7.0.5",
     "httpsnippet": "^3.0.10",
     "iconv-lite": "^0.6.3",
+    "ipaddr.js": "^1.9.1",
     "isbot": "^5",
     "isomorphic-git": "1.25.7",
     "js-yaml": "^4.1.0",

packages/insomnia/src/common/__tests__/safe-ref-resolver.test.ts

@@ -0,0 +1,240 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { safeRefResolver } from '../safe-ref-resolver';
+
+function getHttpResolver() {
+  return (safeRefResolver as any).resolvers.http;
+}
+
+describe('safeHttpResolver', () => {
+  const httpResolver = getHttpResolver();
+
+  beforeEach(() => {
+    vi.stubGlobal('fetch', vi.fn());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('URL validation', () => {
+    it('rejects invalid URLs', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'not-a-url',
+        }),
+      ).rejects.toThrow('Failed to resolve $ref "not-a-url"');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects relative URLs', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => '/foo/bar.yaml',
+        }),
+      ).rejects.toThrow('Failed to resolve $ref "/foo/bar.yaml"');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects http URLs', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'http://example.com/schema.yaml',
+        }),
+      ).rejects.toThrow('only https URLs to public hosts are allowed');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects ftp URLs', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'ftp://example.com/schema.yaml',
+        }),
+      ).rejects.toThrow('only https URLs to public hosts are allowed');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects localhost', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://localhost/schema.yaml',
+        }),
+      ).rejects.toThrow('only https URLs to public hosts are allowed');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects loopback IPv4 addresses', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://127.0.0.1/schema.yaml',
+        }),
+      ).rejects.toThrow('only https URLs to public hosts are allowed');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects private IPv4 addresses', async () => {
+      const urls = [
+        'https://10.0.0.1/schema.yaml',
+        'https://172.16.0.1/schema.yaml',
+        'https://192.168.1.1/schema.yaml',
+      ];
+
+      for (const url of urls) {
+        await expect(
+          httpResolver.resolve({
+            href: () => url,
+          }),
+        ).rejects.toThrow('only https URLs to public hosts are allowed');
+      }
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects link-local IP addresses', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://169.254.169.254/latest/meta-data',
+        }),
+      ).rejects.toThrow('only https URLs to public hosts are allowed');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('rejects IPv6 loopback addresses', async () => {
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://[::1]/schema.yaml',
+        }),
+      ).rejects.toThrow('only https URLs to public hosts are allowed');
+
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('allows public HTTPS URLs', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        text: vi.fn().mockResolvedValue('openapi: 3.1.0'),
+      } as unknown as Response);
+
+      const result = await httpResolver.resolve({
+        href: () => 'https://example.com/schema.yaml',
+      });
+
+      expect(result).toBe('openapi: 3.1.0');
+
+      expect(fetch).toHaveBeenCalledTimes(1);
+      expect(fetch).toHaveBeenCalledWith('https://example.com/schema.yaml');
+    });
+
+    it('allows HTTPS URLs with ports', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        text: vi.fn().mockResolvedValue('ok'),
+      } as unknown as Response);
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com:8443/schema.yaml',
+        }),
+      ).resolves.toBe('ok');
+
+      expect(fetch).toHaveBeenCalledOnce();
+    });
+
+    it('allows HTTPS URLs with query strings', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        text: vi.fn().mockResolvedValue('ok'),
+      } as unknown as Response);
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com/schema.yaml?raw=1',
+        }),
+      ).resolves.toBe('ok');
+
+      expect(fetch).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('fetch handling', () => {
+    it('returns response text for successful fetches', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        text: vi.fn().mockResolvedValue('test-content'),
+      } as unknown as Response);
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com/test.yaml',
+        }),
+      ).resolves.toBe('test-content');
+    });
+
+    it('throws on 404 responses', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+      } as unknown as Response);
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com/missing.yaml',
+        }),
+      ).rejects.toThrow('Failed to fetch $ref "https://example.com/missing.yaml": 404 Not Found');
+    });
+
+    it('throws on 500 responses', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+      } as unknown as Response);
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com/error.yaml',
+        }),
+      ).rejects.toThrow('Failed to fetch $ref "https://example.com/error.yaml": 500 Internal Server Error');
+    });
+
+    it('propagates fetch network errors', async () => {
+      vi.mocked(fetch).mockRejectedValue(new Error('network failure'));
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com/schema.yaml',
+        }),
+      ).rejects.toThrow('network failure');
+    });
+
+    it('propagates response.text() failures', async () => {
+      vi.mocked(fetch).mockResolvedValue({
+        ok: true,
+        text: vi.fn().mockRejectedValue(new Error('failed reading body')),
+      } as unknown as Response);
+
+      await expect(
+        httpResolver.resolve({
+          href: () => 'https://example.com/schema.yaml',
+        }),
+      ).rejects.toThrow('failed reading body');
+    });
+  });
+
+  describe('resolver wiring', () => {
+    it('uses the same resolver for http and https keys', () => {
+      // @ts-expect-error internal access for test verification
+      const resolvers = safeRefResolver.resolvers;
+
+      expect(resolvers.http).toBe(resolvers.https);
+    });
+  });
+});