@jrpool/kilotest 51.1.0 → 55.0.0

package/.devin/config.local.json

@@ -36,7 +36,10 @@
       "Exec(git mv)",
       "Exec(perl)",
       "Exec(ssh)",
-      "Exec(scp)"
+      "Exec(scp)",
+      "Exec(sqlite3)",
+      "Exec(npm update)",
+      "Exec(npm ls)"
     ]
   }
 }

package/.github/workflows/ci.yml

@@ -12,16 +12,19 @@ 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'
 
       - name: Install dependencies
         run: npm ci
 
+      - name: Run typecheck
+        run: npm run typecheck
+
       - name: Run lint
         run: npm run lint
 

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

@@ -81,9 +81,45 @@ test('requestFeature accepts a non-empty feature request and notifies the manage
   assert.ok(logged.some(line =>
     line.startsWith('WARNING (Kilotest: MCP feature request received)')
     && line.includes('Add a dark mode toggle')
+    // The alert reports the resulting queue size, so a maintainer who has been away can
+    // see at a glance how close the queue is to full.
+    && line.includes('Feature requests now awaiting review: 1 of 20')
   ));
 });
 
+test('requestFeature rejects a request with a fallback channel when the queue is full', async () => {
+  // Fill featureRequests.json with 20 distinct requests, reaching the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', content: `Filler feature request number ${i}, long enough to pass the length check.`
+  }));
+  await fs.writeFile(process.env.FEATURE_REQUESTS_PATH!, JSON.stringify(filler));
+  const body = await response(['One feature request too many, long enough to pass the length check.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('too many feature requests are awaiting review right now.'));
+  assert.ok(details.error.includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(details.error.includes('info@kilotest.com'));
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  // The rejected request was not recorded.
+  assert.equal(featureRequests.length, 20);
+});
+
+test('requestFeature never rejects for a full inbox when FEATURE_REQUESTS_MAX is 0 (no limit)', async () => {
+  process.env.FEATURE_REQUESTS_MAX = '0';
+  try {
+    // Fill featureRequests.json past the default cap.
+    const filler = Array.from({length: 25}, (_, i) => ({
+      timeStamp: '260101T0000', content: `Filler feature request number ${i}, long enough to pass the length check.`
+    }));
+    await fs.writeFile(process.env.FEATURE_REQUESTS_PATH!, JSON.stringify(filler));
+    const body = await response(['One more feature request, long enough to pass the length check.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+  }
+  finally {
+    delete process.env.FEATURE_REQUESTS_MAX;
+  }
+});
+
 test('requestFeature includes tool name and metadata', async () => {
   const body = await response(['A sufficiently long feature description']);
   assert.equal(body['tool name'], 'requestFeature');

package/api/requestFeature.ts

@@ -8,7 +8,7 @@
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
 import {sendAlert} from '../alerts.ts';
-import {checkCommentDuplicate, checkLength, getJSON, getNowStamp} from '../util.ts';
+import {checkCommentDuplicate, checkLength, describeMax, getEnvMax, getJSON, getNowStamp} from '../util.ts';
 import {requestFeatureResponseSchema} from './schemas.ts';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -21,6 +21,13 @@ type ResponseContent = z.infer<typeof requestFeatureResponseSchema>['response co
 // FUNCTIONS (helpers)
 
 const getFeatureRequestsPath = () => process.env.FEATURE_REQUESTS_PATH || path.join(import.meta.dirname, '../db/featureRequests.json');
+// Maximum number of feature requests held at once. Once reached, a new, distinct request
+// is rejected rather than stored, so the feature-requests file and the manager alert
+// emails it generates cannot grow without bound (modeled on a full mailbox rejecting new
+// mail; see GitHub issue #3, abuse type 3). Configurable via FEATURE_REQUESTS_MAX, since
+// different Kilotest deployments' maintainers may want a different size; a value of 0
+// means no limit.
+const getFeatureRequestsMax = () => getEnvMax('FEATURE_REQUESTS_MAX', 20);
 
 // FUNCTIONS
 
@@ -61,7 +68,18 @@ export const response = async (args: string[]) => {
         }
       };
     }
-    // Otherwise, i.e. if it is not a duplicate:
+    // Otherwise, if the feature requests already on file have reached the cap (a cap of 0
+    // means no limit, so the queue is never full):
+    else if (getFeatureRequestsMax() > 0 && featureRequests.length >= getFeatureRequestsMax()) {
+      responseContent = {
+        'details about your request': {
+          error: 'request invalid: too many feature requests are awaiting review right now. ' +
+            'Please try again later, or post your request at https://github.com/jrpool/kilotest/issues ' +
+            'or email info@kilotest.com.'
+        }
+      };
+    }
+    // Otherwise, i.e. if it is not a duplicate and the queue is not full:
     else {
       // Record the feature request alongside the existing ones.
       featureRequests.push({
@@ -70,8 +88,12 @@ export const response = async (args: string[]) => {
       });
       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);
+      // Notify the manager, including the resulting count, so a maintainer who has been
+      // away sees at a glance how urgently the requests need review.
+      await sendAlert(
+        'Kilotest: MCP feature request received',
+        `${feature}\nFeature requests now awaiting review: ${featureRequests.length} of ${describeMax(getFeatureRequestsMax())}`
+      );
       // Add the disposition to the response content.
       responseContent = {
         'details about your request': {

package/api/requestRetest.test.ts

@@ -173,5 +173,23 @@ test('requestRetest accepts a valid retest request for the latest report of a pa
     line.startsWith('WARNING (Kilotest: new retest request awaits approval)')
     && line.includes('Mixed Outcomes Page')
     && line.includes('https://example.com/mixed')
+    // The alert reports the resulting queue size, so a maintainer who has been away can
+    // see at a glance how close the queue is to full.
+    && line.includes('Requests now awaiting approval: 1 of 20')
   ));
 });
+
+test('requestRetest rejects a request with a fallback channel when the queue is full', async () => {
+  // Fill testRequests.json with 20 pending requests, all for one URL, to reach the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', description: `Filler Page ${i}`, reason: 'Filler reason.'
+  }));
+  await fs.writeFile(testRequestsPath, JSON.stringify({'https://example.com/filler': filler}));
+  const body = await response(['260101T0003', 'ret', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('too many requests are awaiting approval right now.'));
+  assert.ok(disposition['what happens next'].includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(disposition['what happens next'].includes('info@kilotest.com'));
+});

package/api/requestRetest.ts

@@ -79,6 +79,10 @@ export const response = async (args: string[]) => {
         else if (requestResult === 'superseded') {
           failureReason = 'a later report about a page with the same description is available.'
         }
+        else if (requestResult === 'queueFull') {
+          failureReason = 'too many requests are awaiting approval right now. Please try again later, ' +
+            'or post your request at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.'
+        }
         else {
           failureReason = 'an identical request is already awaiting approval.'
         }

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,34 @@ 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 a URL that redirects to a disallowed target, and alerts a manager', async (t) => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  t.mock.method(globalThis, 'fetch', async () => ({url: 'https://10.0.0.5/page'}) as Response);
+  try {
+    const body = await response(['Redirecting Page', 'https://example.com/redirector', '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('WARNING (Kilotest: request rejected for redirecting to a disallowed target)')
+      && line.includes('https://example.com/redirector')
+    ));
+  } 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;
@@ -149,6 +181,9 @@ test('requestTest accepts a valid new page request', async () => {
     line.startsWith('WARNING (Kilotest: new test request awaits approval)')
     && line.includes('Brand New Page')
     && line.includes('https://example.com/brandnew')
+    // The alert reports the resulting queue size, so a maintainer who has been away can
+    // see at a glance how close the queue is to full.
+    && line.includes('Requests now awaiting approval: 1 of 20')
   ));
 });
 
@@ -158,3 +193,18 @@ test('requestTest includes disposition information for a valid request', async (
   assert.ok(disposition);
   assert.ok(disposition['what happens next']);
 });
+
+test('requestTest rejects a request with a fallback channel when the queue is full', async () => {
+  // Fill testRequests.json with 20 pending requests, all for one URL, to reach the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', description: `Filler Page ${i}`, reason: 'Filler reason.'
+  }));
+  await fs.writeFile(testRequestsPath, JSON.stringify({'https://example.com/filler': filler}));
+  const body = await response(['One Too Many Page', 'https://example.com/one-too-many', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('too many requests are awaiting approval right now.'));
+  assert.ok(disposition['what happens next'].includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(disposition['what happens next'].includes('info@kilotest.com'));
+});

package/api/requestTest.ts

@@ -7,8 +7,9 @@
 
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {checkLength, isURL, processTestRequest} from '../util.ts';
+import {checkLength, isAllowedRedirectTarget, isAllowedTarget, isURL, processTestRequest} from '../util.ts';
 import {requestTestResponseSchema} from './schemas.ts';
+import {sendAlert} from '../alerts.ts';
 
 // TYPES
 
@@ -43,6 +44,25 @@ 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 URL redirects to a target this deployment does not allow:
+  else if (!(await isAllowedRedirectTarget(url))) {
+    requestDetails = {
+      error: 'request invalid: the URL you specified does not resolve to a page that this deployment can test'
+    };
+    // Alert a manager, since a redirect to a disallowed target on a request that
+    // itself named an allowed hostname suggests an attempted or accidental SSRF,
+    // rather than an ordinary mistake by a legitimate submitter.
+    await sendAlert(
+      'Kilotest: request rejected for redirecting to a disallowed target',
+      `A request to test ${url} (described as "${description}") was rejected because it redirects to a target this deployment does not allow (e.g. a private, loopback, or link-local address).`
+    );
+  }
   // Otherwise, i.e. if the description and URL are valid:
   else {
     // Process the request.
@@ -76,6 +96,10 @@ export const response = async (args: string[]) => {
       else if (requestResult === 'retest') {
         failureReason = 'a report about a page with the same description and URL is available.'
       }
+      else if (requestResult === 'queueFull') {
+        failureReason = 'too many requests are awaiting approval right now. Please try again later, ' +
+          'or post your request at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.'
+      }
       else {
         failureReason = 'an identical request is already awaiting approval.'
       }

package/capability.md

@@ -2,7 +2,7 @@
 
 ## Capability
 
-Web-page front-end quality audit. Kilotest tests public web pages for front-end quality, namely accessibility, usability, and standards conformity, and makes structured findings available for retrieval.
+Web-page front-end quality audit. Kilotest tests web pages for front-end quality, namely accessibility, usability, and standards conformity, and makes structured findings available for retrieval.
 
 ## Purpose
 
@@ -36,7 +36,7 @@ A list of available reports.
 
 ## Side effects
 
-Kilotest reads the specified public web page during testing. It does not modify the target site. Testing is asynchronous and may take up to approximately one day before reports are available for newly requested pages.
+Kilotest reads the specified web page during testing. It does not modify the target site. Testing is asynchronous and may take up to approximately one day before reports are available for newly requested pages.
 
 ## Cost
 

package/docs/AI-TOOLS.md

@@ -42,7 +42,7 @@ The external features that support the use of Kilotest as a collection of AI too
 - A [pull request](https://github.com/public-apis/public-apis/pull/6346/changes) to add Kilotest to the list of public APIs in the `public-apis` repository.
 - An [issue](https://github.com/APIs-guru/openapi-directory/issues/2677) to add Kilotest to `openapi-directory`.
 - A [pull request](https://github.com/w3c/wai-evaluation-tools-list/pull/1153) to add Kilotest to the WAI evaluation tools list.
-- Registration of Kilotest as an active server in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=kilotest) (`io.github.jrpool/kilotest`), maintained by the [Model Context Protocol](https://modelcontextprotocol.io/) project. The [PulseMCP](https://www.pulsemcp.com/servers) directory and the VS Code MCP gallery both crawl this registry, so Kilotest is discoverable through them with no separate submission.
+- Registration of Kilotest as an active server in the [official MCP Registry](https://registry.modelcontextprotocol.io) (`io.github.jrpool/kilotest`), maintained by the [Model Context Protocol](https://modelcontextprotocol.io/) project. The [PulseMCP](https://www.pulsemcp.com/servers) directory and the VS Code MCP gallery both crawl this registry, so Kilotest is discoverable through them with no separate submission.
 - Registration of Kilotest with the [Smithery](https://smithery.ai/servers/pool/kilotest) MCP server registry.
 - Registration of Kilotest with the [Glama](https://glama.ai/mcp/connectors/com.kilotest/kilotest) MCP server registry, including a claim of ownership of the MCP connector by the maintainer via a `TXT` DNS record for `_glama-claim.kilotest.com`, with the value `glama_claim_gVV4HrPdcXr9TEfj1p3icEUBJ3_OVJGX`.
 - Registration of Kilotest with [Awesome MCP Servers](https://www.tensorblock.co/mcp/servers/github-jrpool-kilotest-f518ba36).
@@ -107,7 +107,7 @@ Other future work:
     Capability: web-page-quality-audit
 
     Purpose:
-      Test a public web page for accessibility,
+      Test a web page for accessibility,
       usability, HTML and web-standards problems.
 
     Interfaces:
@@ -123,7 +123,7 @@ Other future work:
       rule-engine diagnoses, WCAG mappings
 
     Side effects:
-      Reads the specified public web page.
+      Reads the specified web page.
       Does not modify the target site.
 
     Cost:

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
@@ -417,6 +417,19 @@ Alerts are sent via the `sendAlert()` function in [alerts.ts](../alerts.ts), whi
 
 If any of these five variables is missing or empty at alert time, the alert is not sent. Instead, a warning message is logged to the console, and the application continues normal operation. The warning includes the alert subject and body so the maintainer can manually review what would have been sent.
 
+### Inbox size limits
+
+Four submission types (test requests and retest requests together, web tutorial comments, AI tutorial comments, and MCP feature requests) are each held in a pending "inbox" (`db/jobs/testRequests.json`, `db/comments/tutorialWeb.json`, `db/comments/tutorialAI.json`, and `db/featureRequests.json` respectively) awaiting manual review by the maintainer. Each inbox has a maximum size; once reached, a new, distinct submission is rejected (with a message suggesting the requester instead post to the [GitHub issues page](https://github.com/jrpool/kilotest/issues) or email `info@kilotest.com`) rather than added, so neither the inbox file nor the manager alert emails it generates can grow without bound (see GitHub issue #3, abuse type 3, repeated/automated submissions). This is modeled on a full mailbox rejecting new mail, rather than on a submission rate limit: it is the backlog size itself, not how quickly it grows, that costs the maintainer review time and risks unbounded storage. Every alert sent for an accepted submission reports the resulting inbox count against its cap, so a maintainer returning after an absence can immediately see how close an inbox is to full.
+
+Each cap defaults to 20 and can be set independently via an environment variable:
+
+1. **`TEST_REQUEST_QUEUE_MAX`**: The maximum number of test and retest requests awaiting approval at once, summed across all requested URLs.
+2. **`TUTORIAL_WEB_COMMENTS_MAX`**: The maximum number of comments held on the web tutorial page (`/tutorialWeb.html`).
+3. **`TUTORIAL_AI_COMMENTS_MAX`**: The maximum number of comments held on the AI agent tutorial page (`/tutorialAI.html`).
+4. **`FEATURE_REQUESTS_MAX`**: The maximum number of feature requests held via the MCP server's `requestFeature` tool.
+
+Each variable, if set, must be a non-negative integer; if unset, empty, or not a non-negative integer, the default of 20 is used instead. A value of `0` means no limit: that inbox is never treated as full, regardless of size. Unlike the alert-configuration variables above, these are not required: an unset value never disables the limit, it only selects the default size.
+
 ### Resend integration
 
 Kilotest uses [Resend](https://resend.com/) as its transactional email delivery service. Resend is configured through the environment variables above.
@@ -489,7 +502,7 @@ Kilotest records basic counts of how it is used, so the maintainer can answer qu
 
 - The generic `.html` GET dispatch in `index.ts`, once per successfully served web page, recorded under the `pageViews` category by page name (for example `tutorialWeb`, `listReports`), unless the page is a manager-only page (see "Manager page activity" below), in which case it is recorded there instead.
 - The home page (`/` and `/index.html`), served by its own branch in `index.ts` rather than through the generic `.html` dispatch, recorded under `pageViews` as `index`.
-- Each of the 8 MCP tool handlers in `mcp.ts`, once per successful tool call, recorded under the `mcpToolCalls` category by tool name (for example `listReports`, `requestTest`).
+- Each of the 9 MCP tool handlers in `mcp.ts`, once per successful tool call, recorded under the `mcpToolCalls` category by tool name (for example `listReports`, `requestTest`).
 - The `/api/*` GET and POST service branches in `index.ts`, once per call, recorded under the `apiOperations` category by operation name.
 
 `db/metrics.json` also stores a `since` time stamp, set when the file is first created, so the counts can be read as "since this date" rather than assumed to cover Kilotest's entire history. `getMetrics()` backfills any category absent from an existing `db/metrics.json` (for example one written before a category such as `managerActivity` existed), so an older file remains readable rather than causing every subsequent request to error.
@@ -595,6 +608,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

@@ -2,6 +2,12 @@
 ENVIRONMENT=__placeholder__
 # http (local or reverse-proxied server) or https.
 PROTOCOL=__placeholder__
+# Port the server listens on (defaults to 3000).
+PORT=__placeholder__
+# Path of the private key file. Required only when PROTOCOL is https.
+KEY=__placeholder__
+# Path of the certificate file. Required only when PROTOCOL is https.
+CERT=__placeholder__
 # 3-character password for manager operations.
 AUTH_CODE=__placeholder__
 # ID of each Testaro worker and, for each, its secret and published name.
@@ -15,6 +21,32 @@ 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__
+# Path of the web tutorial comments file (defaults to db/comments/tutorialWeb.json).
+TUTORIAL_WEB_COMMENTS_PATH=__placeholder__
+# Path of the AI tutorial comments file (defaults to db/comments/tutorialAI.json).
+TUTORIAL_AI_COMMENTS_PATH=__placeholder__
+# Path of the feature requests file (defaults to db/featureRequests.json).
+FEATURE_REQUESTS_PATH=__placeholder__
+
+# Inbox size limits: each defaults to 20 if unset, empty, or not a non-negative integer.
+# A value of 0 means no limit.
+
+# Maximum number of test/retest requests awaiting approval at once, across all URLs.
+TEST_REQUEST_QUEUE_MAX=__placeholder__
+# Maximum number of comments held on the web tutorial page.
+TUTORIAL_WEB_COMMENTS_MAX=__placeholder__
+# Maximum number of comments held on the AI agent tutorial page.
+TUTORIAL_AI_COMMENTS_MAX=__placeholder__
+# Maximum number of feature requests held via the MCP server's requestFeature tool.
+FEATURE_REQUESTS_MAX=__placeholder__
 
 # Alert configuration: