@jrpool/kilotest 51.1.0 → 52.0.0

package/.github/workflows/ci.yml

@@ -12,10 +12,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set Node.js version
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '>=24.16.0'
 

package/.github/workflows/periodic-smoke-tests.yml

@@ -14,10 +14,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set Node.js version
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '>=24.16.0'
 

package/.github/workflows/publish-mcp.yml

@@ -19,7 +19,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set Node.js version
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '>=24.16.0'
 

package/README.md

@@ -10,7 +10,7 @@ An ensemble testing and reporting service for front-end web quality
 
 ## Features
 
-This application uses an ensemble of 12 rule engines to test public web pages for front-end quality (i.e. accessibility, usability, and standards conformity).
+This application uses an ensemble of 12 rule engines to test web pages for front-end quality (i.e. accessibility, usability, and standards conformity).
 
 The testing paradigm employed by Kilotest is discussed in these papers:
 
@@ -20,11 +20,11 @@ The testing paradigm employed by Kilotest is discussed in these papers:
 
 Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access.
 
-Testing for Kilotest is performed by one or more testing agents that obtain jobs from Kilotest, perform them, and send reports of the results back to Kilotest. Those agents are instances of the [Testaro](https://www.npmjs.com/package/testaro) package.
+Testing for Kilotest is performed by one or more workers (testing agents) that obtain jobs from Kilotest, perform them, and send reports of the results back to Kilotest. Those agents are instances of the [Testaro](https://www.npmjs.com/package/testaro) package. Thus, the pages that Kilotest tests need not be on the public Internet. They need only be reachable by the Testaro workers that do the testing for Kilotest. So, one or more Testaro workers running inside a private intranet can test internal pages, as well as any external ones reachable from inside the intranet.
 
-An active production instance of Kilotest may require multiple testing agents to handle the load, because testing one web page typically takes about 3 minutes and agents test only one page at a time.
+An active production instance of Kilotest may require multiple Testaro workers to handle the load, because testing one web page typically takes about 3 minutes and workers test only one page at a time.
 
-## Getting started locally with 1 testing worker
+## Getting started locally with 1 worker
 
 ### Installation
 
@@ -36,7 +36,7 @@ In the steps below, hosts `T` and `K` may be the same host or two different host
 1. Clone the Kilotest repository into a new directory on host `K`.
 1. In that directory, install the Kilotest dependencies: `npm install`.
 1. Copy the `env.testaro` file from the `kilotest` directory to `.env` in the `testaro` directory and replace the `__placeholder__` values in `.env` with actual values.
-1. Copy the `env.example` file in the `kilotest` directory to a new `.env` file in the same directory and replace the `__placeholder__` values in `.env` with actual values. `TESTARO_WORKERS` is a JSON object mapping each Testaro worker's ID to an object with its `secret` and its `name`; the ID and secret for a worker must match the `NETWATCH_URL_WORKER_ID` and `NETWATCH_URL_AUTH` values in that worker's `.env`. A worker authenticates each request with an HTTP Basic `Authorization` header (`id:secret`, base64-encoded); as of this writing that header is not yet sent by the published Testaro package, so this scheme requires a matching update to Testaro's `netWatch.js` request code (only to send the header; no change to Testaro's handling of jobs or reports is needed). The ID is a credential and is never published; the `name` is written by Kilotest into a job's and report's `sources.worker` property, which Testaro does not read or alter, so it is a distinct property from `sources.agent` (Testaro's own, untrusted, self-reported label, which Kilotest ignores). Choose a `name` that is safe to appear in every report Kilotest serves.
+1. Copy the `env.example` file in the `kilotest` directory to a new `.env` file in the same directory and replace the `__placeholder__` values in `.env` with actual values. `TESTARO_WORKERS` is a JSON object mapping each Testaro worker's ID to an object with its `secret` and its `name`; the ID and secret for a worker must match the `NETWATCH_URL_WORKER_ID` and `NETWATCH_URL_AUTH` values in that worker's `.env`. A worker authenticates each request with an HTTP Basic `Authorization` header (`id:secret`, base64-encoded); as of this writing that header is not yet sent by the published Testaro package, so this scheme requires a matching update to Testaro's `netWatch.js` request code (only to send the header; no change to Testaro's handling of jobs or reports is needed). The ID is a credential and is never published; the `name` is written by Kilotest into a job's and report's `sources.worker` property, which Testaro does not read or alter, so it is a distinct property from `sources.agent` (Testaro's own, untrusted, self-reported label, which Kilotest ignores). Choose a `name` that is safe to appear in every report Kilotest serves. `ALLOW_INTERNAL_TARGETS` controls whether this deployment can be induced to test pages at private, loopback, or link-local addresses; see [`SERVICE.md`](docs/SERVICE.md#testing-target-restrictions) before changing it from its default.
 
 ### Usage
 

package/api/requestTest.test.ts

@@ -17,6 +17,10 @@ import {fixtureDBDir} from '../test/dbFixture.ts';
 for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
   process.env[key] = '';
 }
+// Allow internal targets by default, so tests that submit an ordinary https://example.com/...
+// URL do not depend on real DNS/network access to pass the resolution check that
+// isAllowedTarget performs. The test of the check itself (below) overrides this.
+process.env.ALLOW_INTERNAL_TARGETS = 'true';
 
 // SETUP AND TEARDOWN
 
@@ -77,6 +81,18 @@ test('requestTest rejects a syntactically invalid URL with the correct length',
   assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
+test('requestTest rejects a private-address URL unless internal targets are allowed', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  try {
+    const body = await response(['Internal Page', 'https://192.168.1.1/page', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.ok(details.error.includes('does not resolve to a page that this deployment can test'));
+    assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  }
+});
+
 test('requestTest rejects an already-tested page', async () => {
   const body = await response(['Mixed Outcomes Page', 'https://example.com/mixed', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;

package/api/requestTest.ts

@@ -7,7 +7,7 @@
 
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {checkLength, isURL, processTestRequest} from '../util.ts';
+import {checkLength, isAllowedTarget, isURL, processTestRequest} from '../util.ts';
 import {requestTestResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -43,6 +43,12 @@ export const response = async (args: string[]) => {
       error: 'request invalid: you specified an invalid URL for the page'
     };
   }
+  // Otherwise, i.e. if the URL does not resolve to an allowed target:
+  else if (!(await isAllowedTarget(url))) {
+    requestDetails = {
+      error: 'request invalid: the URL you specified does not resolve to a page that this deployment can test'
+    };
+  }
   // Otherwise, i.e. if the description and URL are valid:
   else {
     // Process the request.

package/docs/SERVICE.md

@@ -270,7 +270,7 @@ kilotest.com {
   }
   @allowedPOST {
     method POST
-    path /mcp /requestRetest.html/* /requestTest.html /requestAction.html /reannotate.html /renewWCAG.html /ai0BalanceForm.html /expungeReportsForm.html /hideReportForm.html /metrics.html /pruneReportsForm.html /rewindReportsForm.html /showHiddenReportsForm.html /unhideReportForm.html /api/* /tutorialWebComment.html /tutorialAIComment.html /worker/job /worker/report
+    path /mcp /requestRetest.html/* /requestTest.html /requestAction.html /reannotate.html /renewWCAG.html /ai0BalanceForm.html /deleteNotesForm.html /expungeReportsForm.html /hideReportForm.html /metrics.html /pruneReportsForm.html /rewindReportsForm.html /showHiddenReportsForm.html /unhideReportForm.html /api/* /tutorialWebComment.html /tutorialAIComment.html /worker/job /worker/report
   }
   # Respond to OPTIONS requests.
   @allowedOPTIONS method OPTIONS
@@ -595,6 +595,14 @@ If restoration becomes necessary, the files can be copied in the opposite direct
 
 After that the maintainer can inspect the original and restored directories and delete or move report files as needed. After that the `db/reportsExtract.json` file should be deleted, so it will be regenerated when next needed.
 
+### Testing target restrictions
+
+A page submitted for testing need not be publicly accessible; it need only be reachable from the Testaro worker assigned the job. Without a restriction on which addresses a worker may be sent to, an arbitrary requester could induce a worker to fetch a target it has no legitimate reason to reach, such as [a private or link-local address](https://developer.mozilla.org/en-US/docs/Glossary/Private_network) on the network local to that worker, including a metadata service run by a cloud host. This class of attack is known as [server-side request forgery (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF).
+
+Kilotest guards against this with the `ALLOW_INTERNAL_TARGETS` environment variable (documented in `env.example`). Left unset, a deployment restricts testing to addresses that resolve to the public address space, checked both when a URL is submitted and again against the actually visited URL of each report before that report is stored (since a redirect could otherwise route a worker to a disallowed target after submission-time validation passed). Setting it to `true` opts a deployment in to testing private, loopback, and link-local addresses, and removes this protection entirely for that Kilotest instance.
+
+Setting `ALLOW_INTERNAL_TARGETS` to `true` is not safe merely because every Testaro worker able to poll that Kilotest instance is confined to a private network. A report on an internal page is stored and served by Kilotest itself, so if that Kilotest instance is reachable from the public Internet, anyone able to reach it, not only someone with access to the private network, can read the content of that report, including page text and, depending on job configuration, a screenshot or the HTML source of the page. Setting this variable to `true` is appropriate only for a Kilotest instance that is itself kept off the public Internet, or otherwise restricts who can request and retrieve reports, in addition to confining every one of its Testaro workers to the private network being tested.
+
 ### Possible future Testaro integration
 
 Kilotest uses Testaro to run jobs. In previous versions of Kilotest, Testaro was a dependency. It is currently not a dependency. Instead, Testaro instances are installed on one or more other hosts, and each instance polls Kilotest to ask for jobs to run.

package/env.example

@@ -15,6 +15,14 @@ DEPLOYED_KILOTEST_HOST=https://kilotest.com
 # Path of the data directory (defaults to the db subdirectory of the project root). Tests set
 # this to a fixture directory so they never read or write the real db.
 DB_DIR=__placeholder__
+# Whether this deployment allows testing pages at private, loopback, or link-local addresses
+# (true) or restricts testing to publicly routable addresses (any other value or omission).
+# Set this to true only when every Testaro worker that can poll this Kilotest instance is
+# intentionally deployed on a private network to test that network’s own internal pages;
+# leave it unset for a deployment whose Testaro workers accept jobs from arbitrary requesters,
+# since such a worker could otherwise be induced to fetch a target it has no legitimate reason
+# to reach, such as its own host’s cloud-metadata service.
+ALLOW_INTERNAL_TARGETS=__placeholder__
 
 # Alert configuration:
 

package/index.test.ts

@@ -19,6 +19,10 @@ process.env.FEATURE_REQUESTS_PATH = path.join(testCommentsDir, 'featureRequests.
 process.env.TESTARO_WORKERS = JSON.stringify({
   worker1: {secret: 'secret1', name: 'Worker One'}
 });
+// Allow internal targets by default, so tests that submit an ordinary https://example.com/...
+// URL do not depend on real DNS/network access to pass the resolution check that
+// isAllowedTarget performs. Tests of the check itself (below) override this per test.
+process.env.ALLOW_INTERNAL_TARGETS = 'true';
 // Blank the alert configuration unconditionally, so this file sends no real alert
 // emails (e.g. from the requestTest/requestRetest/tutorial-comment tests below) even
 // when run directly (e.g. `npx tsx --test index.test.ts`) rather than via `npm test`,
@@ -905,6 +909,21 @@ test('POST /requestTest.html with non-https URL returns an error', async () => {
   assert.ok(res.body.includes('Invalid test request'));
 });
 
+test('POST /requestTest.html with a private-address URL returns an error unless internal targets are allowed', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  try {
+    const res = await formRequest('POST', '/requestTest.html', {
+      description: 'Internal Page',
+      url: 'https://192.168.1.1/page',
+      why: 'Because accessibility matters'
+    });
+    assert.equal(res.statusCode, 400);
+    assert.ok(res.body.includes('Invalid test request'));
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  }
+});
+
 test('POST /requestRetest.html/260202T0000/new with missing why returns an error', async () => {
   const res = await formRequest('POST', '/requestRetest.html/260202T0000/new', {
     why: ''
@@ -1227,6 +1246,62 @@ test('POST /worker/report with a claimed job but an unusable report returns an e
   await fs.unlink(failedJobPath).catch(() => {});
 });
 
+test('POST /worker/report with a report on a disallowed target rejects it and reclassifies the job', {timeout: 500}, async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  // Use a unique job ID that does not conflict with existing fixtures.
+  const jobID = '990101T0002-ssr';
+  const reportPath = path.join(fixtureDBDir, 'reports', `${jobID}.json`);
+  const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
+  const failedDir = path.join(fixtureDBDir, 'jobs', 'failed');
+  const jobFile = `${jobID}.json`;
+  const claimedJobPath = path.join(claimedDir, jobFile);
+  const failedJobPath = path.join(failedDir, jobFile);
+  try {
+    // Clean up any leftover files.
+    await fs.unlink(reportPath).catch(() => {});
+    await fs.unlink(failedJobPath).catch(() => {});
+    // Create a claimed job assigned to Worker One.
+    await fs.writeFile(claimedJobPath, JSON.stringify({
+      id: jobID,
+      target: {what: 'Test', url: 'https://example.com/test'},
+      sources: {worker: 'Worker One'}
+    }));
+    const auth = Buffer.from('worker1:secret1').toString('base64');
+    // A report that is otherwise usable, but whose test act was redirected (actualURL)
+    // to a private address that this deployment does not allow as a testing target.
+    const report = {
+      id: jobID,
+      target: {what: 'Test', url: 'https://example.com/test'},
+      acts: [{
+        type: 'test', which: 'axe', actualURL: 'https://192.168.1.1/test',
+        result: {standardResult: {instances: []}}
+      }],
+      jobData: {endTime: '26-01-01T00:00'},
+      catalog: {}
+    };
+    const res = await request('POST', '/worker/report', {report}, {
+      authorization: `Basic ${auth}`
+    });
+    assert.equal(res.statusCode, 400);
+    const body = jsonBody(res);
+    assert.ok(body.error.message.includes('disallowed target'));
+    // The report should not have been recorded.
+    const reportExists = await fs.access(reportPath).then(() => true).catch(() => false);
+    assert.equal(reportExists, false, 'Report on a disallowed target should not be saved');
+    // Wait for the async rename to complete.
+    await new Promise<void>(resolve => setTimeout(resolve, 100));
+    // The job should have been reclassified as failed rather than left claimed.
+    const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
+    assert.ok(failedExists, 'Job should be moved to the failed directory');
+    const claimedExists = await fs.access(claimedJobPath).then(() => true).catch(() => false);
+    assert.equal(claimedExists, false, 'Job should be removed from the claimed directory');
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+    // Clean up.
+    await fs.unlink(failedJobPath).catch(() => {});
+  }
+});
+
 // TESTS: remaining error branches and web pages
 
 test('GET /style.css with a read error returns an error page', async () => {

package/index.ts

@@ -17,6 +17,8 @@ import {
   getObject,
   getPOSTData,
   getReport,
+  isAllowedReport,
+  isAllowedTarget,
   isReportError,
   getReportPath,
   hiddenReportsPath,
@@ -899,7 +901,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       else if (pageName === 'requestTest.html') {
         const {description, url, why} = postData as {description?: string; url: string; why?: string};
         // If the request is valid:
-        if (description && isURL(url) && why) {
+        if (description && isURL(url) && why && await isAllowedTarget(url)) {
           // If a report on the page is already available:
           if (await isReportAvailable(description, url)) {
             // Report the error.
@@ -1103,8 +1105,28 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
               }
               // If the job was actually assigned to this worker:
               if (typeof claimedJob === 'object' && claimedJob !== null && (claimedJob as {sources?: {worker?: string}}).sources?.worker === workerName) {
-                // If the report is usable by Kilotest (as any report of an assigned job should be):
-                if (isUsableReport(reportObj)) {
+                // If the report is on a target this deployment allows (a redirect during
+                // navigation, possibly via DNS rebinding, can take a worker to a target that
+                // was disallowed even though the originally submitted URL passed that check
+                // at submission time):
+                if (!(await isAllowedReport(reportObj))) {
+                  console.error(`ERROR: Report ${id} from worker ${workerName} is on a disallowed target`);
+                  // Alert a manager, since this indicates an attempted or accidental SSRF
+                  // rather than an ordinary usability problem with the report.
+                  await sendAlert(
+                    'Kilotest: report on disallowed target rejected',
+                    `Job ${id} from worker ${workerName} resulted in a visit to a target this deployment does not allow (e.g. a private, loopback, or link-local address), possibly via a redirect. The report was discarded and the job was reclassified as failed.`
+                  );
+                  // Reclassify the job as failed, instead of recording the disallowed report or
+                  // leaving the job claimed indefinitely.
+                  await fs.rename(
+                    path.join(claimedPath(), `${id}.json`), path.join(failedPath(), `${id}.json`)
+                  );
+                  // Report the error.
+                  await serveError({message: `ERROR: Report ${id} is on a disallowed target`}, response, false);
+                }
+                // Otherwise, if the report is usable by Kilotest (as any report of an assigned job should be):
+                else if (isUsableReport(reportObj)) {
                   console.log(`Testaro report ${id} was received from worker ${workerName}`);
                   // Add the public worker name to the report.
                   report!.sources = {...report!.sources, worker: workerName};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "51.1.0",
+  "version": "52.0.0",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",

package/test/setup.ts

@@ -12,3 +12,8 @@
 for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
   process.env[key] = '';
 }
+// Allow internal targets by default, so that tests submitting an ordinary
+// https://example.com/... URL for testing do not depend on real DNS/network access
+// to pass the resolution check that isAllowedTarget performs. A test of that check
+// itself sets this env var back to unset (or false) around the specific call being tested.
+process.env.ALLOW_INTERNAL_TARGETS = 'true';

package/util.test.ts

@@ -7,6 +7,7 @@
 
 import {test, before, after} from 'node:test';
 import assert from 'node:assert/strict';
+import net from 'node:net';
 import path from 'node:path';
 import fs from 'node:fs/promises';
 
@@ -51,6 +52,8 @@ import {
   getWeightName,
   hiddenReportsPath,
   htmlSafe,
+  isAllowedReport,
+  isAllowedTarget,
   isJobID,
   isReportAvailable,
   isTimeStamp,
@@ -366,6 +369,160 @@ test('isURL returns false for an invalid URL', () => {
   assert.equal(isURL('not-a-url'), false);
 });
 
+// A fake resolver, so isAllowedTarget tests need no real DNS/network access.
+const fakeLookup = (address: string) => async () => [{address, family: net.isIP(address)}];
+
+// isAllowedTarget and isAllowedReport branch on ALLOW_INTERNAL_TARGETS, which other test
+// files (sharing this process) set to "true" for their own unrelated tests, so every test
+// below sets the env var itself, rather than relying on it being unset by default, and
+// restores whatever value preceded it.
+let savedAllowInternalTargets: string | undefined;
+
+before(() => {
+  savedAllowInternalTargets = process.env.ALLOW_INTERNAL_TARGETS;
+});
+
+after(() => {
+  if (savedAllowInternalTargets === undefined) {
+    delete process.env.ALLOW_INTERNAL_TARGETS;
+  }
+  else {
+    process.env.ALLOW_INTERNAL_TARGETS = savedAllowInternalTargets;
+  }
+});
+
+test('isAllowedTarget returns true for a URL resolving to a public address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('93.184.216.34')), true);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a loopback address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('127.0.0.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a private address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('10.0.0.5')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a 172.16/12 private address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('172.20.0.5')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a carrier-grade NAT address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('100.70.0.5')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a link-local/cloud-metadata address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('169.254.169.254')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an IPv6 loopback address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('::1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an IPv6 unspecified address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('::')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an IPv4-mapped private IPv6 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('::ffff:10.0.0.5')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an IPv6 unique-local address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('fd12:3456:789a:1::1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an IPv6 link-local address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('fe80::1')), false);
+});
+
+test('isAllowedTarget returns true for a URL resolving to a public IPv6 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('2606:2800:220:1:248:1893:25c8:1946')), true);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an address family net.isIP does not recognize', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', async () => [{address: 'not-an-ip', family: 0}]), false);
+});
+
+test('isAllowedTarget returns false when the DNS lookup rejects', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  const lookup = async () => { throw new Error('lookup failed'); };
+  assert.equal(await isAllowedTarget('https://nonexistent.invalid/page', lookup), false);
+});
+
+test('isAllowedTarget returns false for a URL whose literal host is a private IP', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://192.168.1.1/page'), false);
+});
+
+test('isAllowedTarget returns true for a URL whose literal host is a public IP', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://93.184.216.34/page'), true);
+});
+
+test('isAllowedTarget returns false for a syntactically invalid URL', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('not-a-url'), false);
+});
+
+test('isAllowedTarget returns true for a private-address target when ALLOW_INTERNAL_TARGETS is true', async () => {
+  process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  assert.equal(await isAllowedTarget('https://192.168.1.1/page'), true);
+});
+
+test('isAllowedReport returns true when every act has a public actualURL', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  const report = {
+    target: {what: 'Example', url: 'https://example.com/page'},
+    acts: [
+      {type: 'test', actualURL: 'https://example.com/page'},
+      {type: 'test', actualURL: 'https://example.com/page2'}
+    ]
+  };
+  assert.equal(await isAllowedReport(report, fakeLookup('93.184.216.34')), true);
+});
+
+test('isAllowedReport returns false when any act has a disallowed actualURL', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  const report = {
+    target: {what: 'Example', url: 'https://example.com/page'},
+    acts: [
+      {type: 'test', actualURL: 'https://example.com/page'},
+      {type: 'test', actualURL: 'https://internal.example.net/page'}
+    ]
+  };
+  let callCount = 0;
+  const lookup = async (hostname: string) => {
+    callCount++;
+    return hostname === 'internal.example.net'
+      ? [{address: '10.0.0.5', family: 4}]
+      : [{address: '93.184.216.34', family: 4}];
+  };
+  assert.equal(await isAllowedReport(report, lookup), false);
+  assert.ok(callCount > 0);
+});
+
+test('isAllowedReport falls back to the report target URL when an act has no actualURL', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  const report = {
+    target: {what: 'Example', url: 'https://example.com/page'},
+    acts: [{type: 'test'}]
+  };
+  assert.equal(await isAllowedReport(report, fakeLookup('93.184.216.34')), true);
+});
+
 test('isValidAuthCode returns true when the code matches AUTH_CODE', () => {
   const saved = process.env.AUTH_CODE;
   process.env.AUTH_CODE = 'secret-code';

package/util.ts

@@ -12,7 +12,9 @@ import {sendAlert} from './alerts.ts';
 import {issues as issueSpecs, rules as ruleSpecs} from 'testaro-issues';
 import type {Act, Catalog, Report, StandardInstance} from 'testaro';
 import crypto from 'node:crypto';
+import dns from 'node:dns/promises';
 import fs from 'node:fs/promises';
+import net from 'node:net';
 import path from 'node:path';
 import querystring from 'node:querystring';
 /* c8 ignore stop */
@@ -549,6 +551,95 @@ export const isURL = (string: string): boolean => {
     return false;
   }
 };
+// Returns whether an IPv4 address (in dotted-decimal form) is in a private,
+// loopback, link-local, or otherwise non-public range, including the
+// 169.254.169.254 cloud-metadata address (which falls under link-local).
+const isNonPublicIPv4 = (address: string): boolean => {
+  const octets = address.split('.').map(Number);
+  const [a, b = 0] = octets;
+  return (
+    a === 127 || // loopback
+    a === 10 || // private
+    a === 0 || // "this network"
+    (a === 172 && b >= 16 && b <= 31) || // private
+    (a === 192 && b === 168) || // private
+    (a === 169 && b === 254) || // link-local, incl. cloud metadata
+    (a === 100 && b >= 64 && b <= 127) // carrier-grade NAT
+  );
+};
+// Returns whether an IPv6 address is in a loopback, unique-local, or
+// link-local range.
+const isNonPublicIPv6 = (address: string): boolean => {
+  const normalized = address.toLowerCase();
+  return (
+    normalized === '::1' // loopback
+    || normalized === '::' // unspecified
+    || /^::ffff:/.test(normalized) && isNonPublicIPv4(normalized.replace(/^::ffff:/, '')) // IPv4-mapped
+    || /^f[cd][0-9a-f]{2}:/.test(normalized) // unique local (fc00::/7)
+    || /^fe[89ab][0-9a-f]:/.test(normalized) // link-local (fe80::/10)
+  );
+};
+// Returns whether an IP address (v4 or v6) is outside the public address
+// space, i.e. is a loopback, private, link-local, or other reserved address
+// that a public deployment should never intend to test.
+const isNonPublicIP = (address: string): boolean => {
+  const version = net.isIP(address);
+  if (version === 4) {
+    return isNonPublicIPv4(address);
+  }
+  if (version === 6) {
+    return isNonPublicIPv6(address);
+  }
+  // Not a recognizable IP address, so treat it as non-public, i.e. as unsafe.
+  return true;
+};
+// Returns whether ALLOW_INTERNAL_TARGETS opts this deployment in to testing
+// pages at private, loopback, or link-local addresses. A deployment that
+// intentionally runs a Testaro worker inside a private network to test
+// intranet pages sets this to "true"; a public deployment, whose Testaro
+// workers may run on hosts with access to their own cloud metadata service,
+// leaves it unset so private addresses are rejected by default (fail safe).
+const allowsInternalTargets = (): boolean => process.env.ALLOW_INTERNAL_TARGETS === 'true';
+// The signature of dns.lookup with {all: true}, extracted so tests can inject
+// a fake resolver and avoid depending on real network/DNS access.
+type LookupAll = (hostname: string, options: {all: true}) => Promise<{address: string; family: number}[]>;
+// Returns whether the host a URL resolves to consists only of addresses this
+// deployment is configured to allow as testing targets. This governs where
+// the Testaro browser is allowed to navigate, so it is the control against
+// submitting (or, via a redirect, being routed to) an unintended internal
+// target such as a cloud metadata service or another host on a private
+// network. It is deliberately independent of the syntax check that isURL
+// performs, because it requires a DNS lookup, and therefore an internal
+// deployment can use it to check both a requested URL (at submission time)
+// and the actual, possibly redirected, URL of a report (at report-ingestion
+// time). The lookup parameter defaults to the real dns.lookup and exists so
+// tests can inject a fake resolver.
+export const isAllowedTarget = async (url: string, lookup: LookupAll = dns.lookup): Promise<boolean> => {
+  // If this deployment allows internal targets, every syntactically valid URL is allowed.
+  if (allowsInternalTargets()) {
+    return true;
+  }
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  // If the hostname is itself a literal IP address, check it directly.
+  if (net.isIP(hostname)) {
+    return !isNonPublicIP(hostname);
+  }
+  // Otherwise, resolve the hostname and reject it if any address it resolves
+  // to is non-public, since a hostname can resolve to more than one address
+  // and an attacker need control only one of them.
+  try {
+    const addresses = await lookup(hostname, {all: true});
+    return addresses.length > 0 && addresses.every(({address}) => !isNonPublicIP(address));
+  } catch {
+    // An unresolvable hostname cannot be a usable testing target either way.
+    return false;
+  }
+};
 // Returns whether a string is the authorization code, the shared check every
 // manager-facing page and action uses to gate a submission. Centralized so all call
 // sites compare against process.env.AUTH_CODE the same way.
@@ -601,6 +692,31 @@ export const deleteTestRequests = (url: string) => testRequestsLock(async (): Pr
 // Returns the test acts of a report.
 export const getTestActs = (report: UsableReport): AnnotatedAct[] =>
   report.acts.filter(act => act.type === 'test');
+// Returns whether all URLs actually visited for a report are allowed targets.
+// A URL submitted for testing can pass isAllowedTarget at submission time and
+// still result in a report on a disallowed target, because the browser
+// running in a worker can be redirected (possibly through DNS rebinding, so
+// the same hostname resolves differently at fetch time) to a host this
+// deployment does not allow as a testing target. Since each test act records
+// the URL it actually visited (actualURL, defaulting to the requested URL of
+// the job if a tool did not report one), checking every act here, right
+// before a report is stored or served, is what actually closes that gap,
+// independently of whatever happened during navigation.
+export const isAllowedReport = async (
+  report: Partial<Report>, lookup: LookupAll = dns.lookup
+): Promise<boolean> => {
+  const acts = Array.isArray(report.acts) ? report.acts : [];
+  const testActs = acts.filter((act): act is AnnotatedAct => act?.type === 'test');
+  const urlsVisited = new Set(
+    testActs.map(act => act.actualURL ?? report.target?.url).filter((url): url is string => !!url)
+  );
+  for (const url of urlsVisited) {
+    if (!(await isAllowedTarget(url, lookup))) {
+      return false;
+    }
+  }
+  return true;
+};
 // Returns the standard instances of a report's test acts, optionally filtered.
 export const getTestActInstances = (
   report: UsableReport,