@keynv/testers 0.1.0-rc.23

package/dist/ssrf.test.js

@@ -0,0 +1,104 @@
+import { describe, expect, it, vi } from 'vitest';
+// Deterministic, offline DNS: a couple of "malicious" names resolve to
+// internal addresses, one resolves to a public address.
+vi.mock('node:dns/promises', () => ({
+    lookup: vi.fn(async (host) => {
+        if (host === 'rebind.evil.test')
+            return [{ address: '127.0.0.1', family: 4 }];
+        if (host === 'metadata.evil.test')
+            return [{ address: '169.254.169.254', family: 4 }];
+        if (host === 'split.evil.test')
+            return [
+                { address: '93.184.216.34', family: 4 },
+                { address: '10.0.0.5', family: 4 },
+            ];
+        if (host === 'public.test')
+            return [{ address: '93.184.216.34', family: 4 }];
+        throw Object.assign(new Error('ENOTFOUND'), { code: 'ENOTFOUND' });
+    }),
+}));
+import { isBlockedHost, isBlockedHostResolved, isBlockedUrl, isBlockedUrlResolved, } from './ssrf.js';
+describe('isBlockedHost — literal IPv4', () => {
+    it.each([
+        ['loopback', '127.0.0.1'],
+        ['loopback /8', '127.1.2.3'],
+        ['10/8', '10.0.0.5'],
+        ['172.16/12', '172.16.0.1'],
+        ['172.31 edge', '172.31.255.255'],
+        ['192.168/16', '192.168.1.1'],
+        ['link-local + metadata', '169.254.169.254'],
+        ['0.0.0.0/8', '0.0.0.0'],
+        ['CGNAT 100.64/10', '100.64.0.1'],
+        ['TEST-NET-1', '192.0.2.1'],
+        ['TEST-NET-2', '198.51.100.7'],
+        ['TEST-NET-3', '203.0.113.7'],
+        ['multicast', '224.0.0.1'],
+        ['reserved 240/4', '240.0.0.1'],
+        ['decimal integer form of 127.0.0.1', '2130706433'],
+        ['hex form of 127.0.0.1', '0x7f000001'],
+    ])('blocks %s', (_label, host) => {
+        expect(isBlockedHost(host)).toBe(true);
+    });
+    it.each([
+        ['public DNS', '8.8.8.8'],
+        ['public', '93.184.216.34'],
+        ['172.15 (just below private)', '172.15.0.1'],
+        ['172.32 (just above private)', '172.32.0.1'],
+        ['198.51.99 (not TEST-NET-2)', '198.51.99.7'],
+    ])('allows %s', (_label, host) => {
+        expect(isBlockedHost(host)).toBe(false);
+    });
+});
+describe('isBlockedHost — literal IPv6 + hostnames', () => {
+    it.each([
+        ['v6 loopback', '::1'],
+        ['v6 loopback bracketed', '[::1]'],
+        ['v6 unspecified', '::'],
+        ['v6 link-local', 'fe80::1'],
+        ['v6 ULA', 'fd00::1'],
+        ['v6 ULA fc', 'fc00::1'],
+        ['v6 multicast', 'ff02::1'],
+        ['v4-mapped loopback', '::ffff:127.0.0.1'],
+        ['localhost', 'localhost'],
+        ['gcp metadata', 'metadata.google.internal'],
+    ])('blocks %s', (_label, host) => {
+        expect(isBlockedHost(host)).toBe(true);
+    });
+    it('allows a public IPv6 address', () => {
+        expect(isBlockedHost('2606:4700:4700::1111')).toBe(false);
+    });
+    it('does not classify a bare hostname synchronously', () => {
+        expect(isBlockedHost('rebind.evil.test')).toBe(false);
+    });
+});
+describe('isBlockedHostResolved — DNS-aware (closes the rebinding bypass)', () => {
+    it('blocks a public hostname that resolves to loopback', async () => {
+        expect(await isBlockedHostResolved('rebind.evil.test')).toBe(true);
+    });
+    it('blocks a public hostname that resolves to the cloud metadata IP', async () => {
+        expect(await isBlockedHostResolved('metadata.evil.test')).toBe(true);
+    });
+    it('blocks when ANY resolved address is internal', async () => {
+        expect(await isBlockedHostResolved('split.evil.test')).toBe(true);
+    });
+    it('allows a hostname that resolves only to public addresses', async () => {
+        expect(await isBlockedHostResolved('public.test')).toBe(false);
+    });
+    it('does not block an unresolvable host (tester surfaces its own error)', async () => {
+        expect(await isBlockedHostResolved('nope.invalid.test')).toBe(false);
+    });
+});
+describe('isBlockedUrl / isBlockedUrlResolved', () => {
+    it('blocks non-http(s) protocols', () => {
+        expect(isBlockedUrl('file:///etc/passwd')).toBe(true);
+        expect(isBlockedUrl('gopher://x')).toBe(true);
+    });
+    it('blocks a malformed URL', () => {
+        expect(isBlockedUrl('not a url')).toBe(true);
+    });
+    it('resolves the URL host via DNS', async () => {
+        expect(await isBlockedUrlResolved('http://rebind.evil.test/path')).toBe(true);
+        expect(await isBlockedUrlResolved('https://public.test/path')).toBe(false);
+    });
+});
+//# sourceMappingURL=ssrf.test.js.map

package/dist/ssrf.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf.test.js","sourceRoot":"","sources":["../src/ssrf.test.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+import type { z } from 'zod';
+import type { ZodType, ZodTypeDef } from 'zod';
+export declare const testerEnum: z.ZodEnum<["postgres", "mysql", "redis", "ssh", "http"]>;
+export type TesterType = z.infer<typeof testerEnum>;
+/**
+ * The plaintext value resolved from an alias, plus optional auxiliary
+ * fields some testers need (e.g., username for SSH keypair auth).
+ *
+ * The runner constructs this once, hands it to the tester, and never
+ * persists or logs the value.
+ */
+export interface ResolvedSecret {
+    readonly alias: string;
+    readonly value: string;
+    readonly fields?: Readonly<Record<string, string>>;
+}
+/**
+ * Per-tester target shape (database host/port/db, ssh host/user, http
+ * url/auth-style, etc.). Each tester ships its own zod schema.
+ */
+export type TesterTarget = Readonly<Record<string, unknown>>;
+export interface TestResult {
+    readonly ok: boolean;
+    readonly latency_ms: number;
+    /** Sanitized — must NEVER carry the resolved secret value. */
+    readonly error?: string;
+    /** Optional structured info (server version, identity hash, etc.). */
+    readonly info?: Readonly<Record<string, unknown>>;
+}
+export interface Tester<T extends TesterTarget = TesterTarget> {
+    readonly type: TesterType;
+    /**
+     * The schema's *input* type stays unknown so callers (the CLI's
+     * --target k=v parser, the MCP tool) can hand untyped objects in;
+     * zod's defaults / coercions turn them into the strongly-typed
+     * output the tester sees.
+     */
+    readonly schema: ZodType<T, ZodTypeDef, unknown>;
+    test(secret: ResolvedSecret, target: T): Promise<TestResult>;
+}
+export declare const DEFAULT_TIMEOUT_MS = 5000;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAE/C,eAAO,MAAM,UAAU,0DAAwB,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IAC3D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,kBAAkB,OAAQ,CAAC"}

package/dist/types.js

@@ -0,0 +1,4 @@
+import { validation } from '@keynv/core';
+export const testerEnum = validation.testerName;
+export const DEFAULT_TIMEOUT_MS = 5_000;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;AA2ChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@keynv/testers",
+  "version": "0.1.0-rc.23",
+  "description": "keynv pluggable connection testers (postgres, mysql, redis, ssh, http, cloud IAM).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keynv-labs/keynv.git",
+    "directory": "packages/testers"
+  },
+  "homepage": "https://github.com/keynv-labs/keynv#readme",
+  "bugs": {
+    "url": "https://github.com/keynv-labs/keynv/issues"
+  },
+  "dependencies": {
+    "ioredis": "^5.4.1",
+    "mysql2": "^3.11.5",
+    "pg": "^8.13.1",
+    "ssh2": "^1.16.0",
+    "zod": "^3.23.8",
+    "@keynv/core": "0.1.0-rc.23",
+    "@keynv/redactor": "0.1.0-rc.23"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.10",
+    "@types/ssh2": "^1.15.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}