@jrpool/kilotest 50.0.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/requestFeature.test.ts

@@ -7,6 +7,20 @@
 
 import {test, beforeEach, after} from 'node:test';
 import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// Blank the alert configuration unconditionally, before ./requestFeature.ts (which
+// calls sendAlert) is ever imported below, so this file sends no real alert emails
+// even when run directly rather than via `npm test`.
+for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
+  process.env[key] = '';
+}
+
+// ENVIRONMENT
+
+const testDir = path.join(import.meta.dirname, '../test/fixtures/featureRequests');
+process.env.FEATURE_REQUESTS_PATH = path.join(testDir, 'featureRequests.json');
 
 // SETUP AND TEARDOWN
 
@@ -14,16 +28,19 @@ let logged: any[] = [];
 const originalLog = console.log;
 
 // Capture console.log so the alert sendAlert emits can be observed. The alert
-// configuration is empty in tests, so sendAlert logs a WARNING instead of sending.
-beforeEach(() => {
+// configuration is blanked above, so sendAlert logs a WARNING instead of sending.
+beforeEach(async () => {
   logged = [];
   console.log = (...args) => logged.push(args.join(' '));
+  await fs.mkdir(testDir, {recursive: true});
+  await fs.writeFile(process.env.FEATURE_REQUESTS_PATH!, '[]\n');
 });
 
 import {response} from './requestFeature.ts';
 
-after(() => {
+after(async () => {
   console.log = originalLog;
+  await fs.rm(testDir, {recursive: true, force: true});
 });
 
 // TESTS
@@ -72,3 +89,64 @@ test('requestFeature includes tool name and metadata', async () => {
   assert.equal(body['tool name'], 'requestFeature');
   assert.ok(body['response metadata'].identifier);
 });
+
+test('requestFeature records a valid feature request to the feature-requests file', async () => {
+  await response(['Add a dark mode toggle to the reports page']);
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  assert.equal(featureRequests.length, 1);
+  assert.equal(featureRequests[0].content, 'Add a dark mode toggle to the reports page');
+  assert.ok(featureRequests[0].timeStamp);
+});
+
+test('requestFeature appends to, rather than overwrites, existing feature requests', async () => {
+  await response(['First feature request of at least 20 characters']);
+  await response(['Second feature request of at least 20 characters']);
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  assert.equal(featureRequests.length, 2);
+});
+
+test('requestFeature does not record an invalid feature request', async () => {
+  await response(['short']);
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  assert.equal(featureRequests.length, 0);
+});
+
+test('requestFeature creates the feature-requests file when it does not exist', async () => {
+  await fs.unlink(process.env.FEATURE_REQUESTS_PATH!);
+  await response(['A feature request when no file yet exists']);
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  assert.equal(featureRequests.length, 1);
+  assert.equal(featureRequests[0].content, 'A feature request when no file yet exists');
+});
+
+test('requestFeature rejects a feature request identical to one already on file', async () => {
+  const feature = 'Add a dark mode toggle to the reports page';
+  const firstBody = await response([feature]);
+  const firstDetails = firstBody['response content']['details about your request'] as any;
+  assert.equal(firstDetails.error, undefined);
+  const secondBody = await response([feature]);
+  const secondDetails = secondBody['response content']['details about your request'] as any;
+  assert.ok(secondDetails.error.includes('identical to one already submitted'));
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  // The duplicate was not recorded a second time.
+  assert.equal(featureRequests.length, 1);
+});
+
+test('requestFeature does not notify the manager of a duplicate feature request', async () => {
+  const feature = 'Add a dark mode toggle to the settings page';
+  await response([feature]);
+  logged = [];
+  await response([feature]);
+  assert.ok(
+    !logged.some(line => line.startsWith('WARNING (Kilotest: MCP feature request received)'))
+  );
+});
+
+test('requestFeature accepts a feature request that differs from an existing one', async () => {
+  await response(['An existing feature request on file']);
+  const body = await response(['A different feature request entirely']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  assert.equal(featureRequests.length, 2);
+});

package/api/requestFeature.ts

@@ -8,14 +8,20 @@
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
 import {sendAlert} from '../alerts.ts';
-import {checkLength} from '../util.ts';
+import {checkCommentDuplicate, checkLength, getJSON, getNowStamp} from '../util.ts';
 import {requestFeatureResponseSchema} from './schemas.ts';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 
 // TYPES
 
 // The response content defined by the response schema.
 type ResponseContent = z.infer<typeof requestFeatureResponseSchema>['response content'];
 
+// FUNCTIONS (helpers)
+
+const getFeatureRequestsPath = () => process.env.FEATURE_REQUESTS_PATH || path.join(import.meta.dirname, '../db/featureRequests.json');
+
 // FUNCTIONS
 
 // Returns the response body.
@@ -35,15 +41,45 @@ export const response = async (args: string[]) => {
   }
   // Otherwise, i.e. if it is valid:
   else {
-    // Notify the manager.
-    await sendAlert('Kilotest: MCP feature request received', feature);
-    // Add the disposition to the response content.
-    responseContent = {
-      'details about your request': {
-        'date and time received': new Date().toISOString(),
-        disposition: 'received and logged; manager notified'
-      }
-    };
+    // Get the feature requests already on file.
+    const featureRequestsPath = getFeatureRequestsPath();
+    let featureRequests: {timeStamp: string; content: string}[] = [];
+    try {
+      const existing = await fs.readFile(featureRequestsPath, 'utf8');
+      featureRequests = JSON.parse(existing);
+    }
+    catch {
+      // Initialize an empty feature-requests array.
+    }
+    // If the request is identical to one already on file:
+    const duplicateCheck = checkCommentDuplicate(featureRequests, feature);
+    if (duplicateCheck.status === 'error') {
+      responseContent = {
+        'details about your request': {
+          error: 'request invalid: your feature request is identical to one already submitted, ' +
+            'but you are welcome to submit a different one'
+        }
+      };
+    }
+    // Otherwise, i.e. if it is not a duplicate:
+    else {
+      // Record the feature request alongside the existing ones.
+      featureRequests.push({
+        timeStamp: getNowStamp(),
+        content: feature
+      });
+      await fs.mkdir(path.dirname(featureRequestsPath), {recursive: true});
+      await fs.writeFile(featureRequestsPath, getJSON(featureRequests));
+      // Notify the manager.
+      await sendAlert('Kilotest: MCP feature request received', feature);
+      // Add the disposition to the response content.
+      responseContent = {
+        'details about your request': {
+          'date and time received': new Date().toISOString(),
+          disposition: 'received and logged; manager notified'
+        }
+      };
+    }
   }
   // Create a response body.
   const body = {

package/api/requestRetest.test.ts

@@ -11,6 +11,13 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {fixtureDBDir} from '../test/dbFixture.ts';
 
+// Blank the alert configuration unconditionally, before ./requestRetest.ts (whose
+// processTestRequest calls sendAlert) is ever imported below, so this file sends no
+// real alert emails even when run directly rather than via `npm test`.
+for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
+  process.env[key] = '';
+}
+
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;

package/api/requestTest.test.ts

@@ -11,6 +11,17 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {fixtureDBDir} from '../test/dbFixture.ts';
 
+// Blank the alert configuration unconditionally, before ./requestTest.ts (whose
+// processTestRequest calls sendAlert) is ever imported below, so this file sends no
+// real alert emails even when run directly rather than via `npm test`.
+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
 
 const savedDBDir = process.env.DB_DIR;
@@ -70,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/api/util.test.ts

@@ -7,6 +7,15 @@
 
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
+
+// Blank the alert configuration unconditionally, before ../util.ts (which
+// processTestRequest calls sendAlert from) is ever imported below, so this file sends
+// no real alert emails even when run directly (e.g. `npx tsx --test api/util.test.ts`)
+// rather than via `npm test`, which normally guards against this via test/setup.ts.
+for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
+  process.env[key] = '';
+}
+
 import {getReportBasics, getResponseMetadata, getRuleEngineFacts, getRuleEnginesFacts, getIssueSpec, getToolsFacts} from './util.ts';
 import {processTestRequest} from '../util.ts';
 

package/apiIntegration.test.ts

@@ -8,19 +8,29 @@
 import {test, before, after} from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import {requestHandler} from './index.ts';
 
 // CONSTANTS
 
 const port = 3998;
+const featureRequestsPath = path.join(import.meta.dirname, 'test/fixtures/apiIntegration/featureRequests.json');
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
+const savedFeatureRequestsPath = process.env.FEATURE_REQUESTS_PATH;
 let server: http.Server;
 
 before(async () => {
   process.env.DB_DIR = (await import('./test/dbFixture.ts')).fixtureDBDir;
+  // Use a fixture path, rather than the real default, for feature requests, so this
+  // test's submission neither pollutes real data nor is rejected as a duplicate of
+  // whatever a prior run of this same test already left on disk.
+  process.env.FEATURE_REQUESTS_PATH = featureRequestsPath;
+  await fs.mkdir(path.dirname(featureRequestsPath), {recursive: true});
+  await fs.writeFile(featureRequestsPath, '[]\n');
   server = http.createServer(requestHandler);
   await new Promise<void>(resolve => server.listen(port, () => resolve()));
 });
@@ -32,6 +42,13 @@ after(async () => {
   else {
     delete process.env.DB_DIR;
   }
+  if (savedFeatureRequestsPath !== undefined) {
+    process.env.FEATURE_REQUESTS_PATH = savedFeatureRequestsPath;
+  }
+  else {
+    delete process.env.FEATURE_REQUESTS_PATH;
+  }
+  await fs.rm(path.dirname(featureRequestsPath), {recursive: true, force: true});
   server.closeAllConnections?.();
   await new Promise<void>(resolve => {
     const timer = setTimeout(() => {

package/docs/SERVICE.md

@@ -256,14 +256,21 @@ kilotest.com {
   }
   # Enable Zstandard and Gzip compression of responses.
   encode zstd gzip
-  # Specify the only paths of forwardable requests. UptimeRobet uses HEAD.
+  # Specify the only paths of forwardable requests.
   @allowedGET {
-    method GET HEAD
+    method GET
     path /mcp / /index.html /robots.txt /openapi.yaml /openapi.json /swagger.yaml /swagger.json /api-docs /llms.txt /llms-full.txt /capability.md *.html* /fullReport.json/* /api/* /tutorialWeb/images/* /tutorialAI/images/* /qai /qai/comments /favicon.* /style.css /sitemap.xml
   }
+  # UptimeRobot's uptime check is the only known HEAD caller, and it targets only the site
+  # root (see "Health monitoring" below), so HEAD is forwarded only for that path, not the
+  # full GET allowlist above. index.ts's HEAD branch matches this same scope.
+  @allowedHEAD {
+    method HEAD
+    path / /index.html
+  }
   @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
@@ -275,13 +282,19 @@ kilotest.com {
     }
     respond 204
   }
-  # Forward any other GET, POST, or OPTIONS request, if allowed, to port 3000.
+  # Forward any other GET, HEAD, or POST request, if allowed, to port 3000.
   handle @allowedGET {
     reverse_proxy localhost:3000 {
       # Improve SSE latency.
       flush_interval -1
     }
   }
+  handle @allowedHEAD {
+    reverse_proxy localhost:3000 {
+      # Improve SSE latency.
+      flush_interval -1
+    }
+  }
   handle @allowedPOST {
     reverse_proxy localhost:3000 {
       # Improve SSE latency.
@@ -362,7 +375,7 @@ The deployment is monitored for external health and availability using [UptimeRo
 
 UptimeRobot also sends a recovery message when the service recovers and a subsequent check succeeds after a prior failure.
 
-This monitoring service requires `Caddyfile` to permit `HEAD` requests, not only `GET` requests, to the root path.
+This monitoring service requires both `Caddyfile` and Kilotest itself to permit `HEAD` requests, not only `GET` requests, to the root path: `Caddyfile`’s `@allowedHEAD` matcher forwards such a request to port 3000, and `index.ts`’s own dedicated `HEAD` branch in `handleRequest` answers it. Before that branch existed, Kilotest treated `HEAD` as an invalid method for every path (its dispatch recognized only `GET` and `POST`), so UptimeRobot’s hourly check received a `400` response and reported the service as down even while it was actually up.
 
 ## Alerting
 
@@ -386,7 +399,7 @@ Alerts are sent to the maintainer in the following conditions:
 
 7. **Test request received via API**: When a test request is submitted via the API, an alert is sent with subject `"Kilotest: new test request in the API"` (via the `requestTest` API operation) or `"Kilotest: new retest request in the API"` (via the `requestRetest` API operation), including the target URL, description, and the user's stated reason. A request is treated as a duplicate, and no alert is sent for it, only if a request already pending in `db/jobs/testRequests.json`, i.e., submitted but not yet manually approved by the maintainer into an actual job, for the same URL has the identical description; this check ignores the stated reason and the test-versus-retest distinction, and is not limited to a recent time window, it compares against every request still pending approval for that URL. Once the maintainer approves a pending request (turning it into a job via `/enqueue.html`), all pending requests for that URL are cleared, so this check cannot detect a duplicate against a request that has already been approved, is currently running, or has already completed; an identical request submitted after approval alerts again. The check and its dedup key are identical for the UI and API paths, since both funnel through the same underlying request-queuing function.
 
-8. **MCP feature request received**: When a user submits a feature request via the MCP server's `requestFeature` tool, an alert is sent with subject `"MCP feature request received"`, including the text of the feature request.
+8. **MCP feature request received**: When a user submits a feature request via the MCP server's `requestFeature` tool, an alert is sent with subject `"MCP feature request received"`, including the text of the feature request, and the request is also appended to `db/featureRequests.json`, the same way tutorial comments are appended to their own files (see item 1), so that a manager can review or delete it later via `/deleteNotesForm.html`.
 
 9. **WAVE balance low**: When Kilotest detects that the account balance for the WAVE API service (used for accessibility testing) has fallen below a threshold, an alert is sent with subject `"Kilotest: WAVE balance low"`, indicating the number of credits remaining.
 
@@ -582,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: