@jrpool/kilotest 35.0.1 → 36.1.0

package/SERVICE.md

@@ -20,6 +20,8 @@ Any other application `xyz` can be installed at `/opt/jpdev/xyz` on the server.
 
 ## Process management
 
+### Process manager
+
 Kilotest is managed with [PM2](https://pm2.keymetrics.io) on the server (not on the local development host). The PM2 configuration is specified in the repository as `pm2.config.js`:
 
 ```javascript
@@ -49,6 +51,10 @@ pm2 restart kilotest --time --update-env
 pm2 save
 ```
 
+The management of the PM2 logs is [documented by PM2](https://pm2.keymetrics.io/docs/usage/log-management/).
+
+### Process tuning
+
 The server configuration has been tuned for improved performance. The file edited for this purpose is `/etc/default/zramswap`:
 
 ```properties
@@ -190,22 +196,52 @@ The Caddy configuration is maintained and tracked in `/etc/caddy/Caddyfile`. Lea
 kilotest.com {
   # Enable Zstandard and Gzip compression of responses.
   encode zstd gzip
-
-  # Truncate the initial /qai from the forwarded path.
+  # Specify the only paths of forwardable requests.
+  @allowedGET {
+    method GET
+    path /mcp / /index.html /robots.txt /openapi.yaml /openapi.json /swagger.yaml /swagger.json /api-docs /llms.txt /llms-full.txt *.html* /fullReport.json/* /api/* /tutorial/images/* /favicon.* /style.css /sitemap.xml
+  }
+  @allowedPOST {
+    method POST
+    path /mcp /retestRec.html/* /testRec.html/* /recAction.html /reannotate.html /wcagRenew.html /api/* /tutorialComment.html
+  }
+  @allowedOPTIONS method OPTIONS
+  handle @allowedOPTIONS {
+    header {
+      Access-Control-Allow-Origin *
+      Access-Control-Allow-Methods GET,POST,OPTIONS
+      Access-Control-Allow-Headers Content-Type,Authorization
+    }
+    respond 204
+  }
+  # Truncate any initial /qai from the forwarded path.
   handle_path /qai* {
-    # Forward any matching request to port 3001.
+    # Forward any QAI request to port 3001.
     reverse_proxy localhost:3001
   }
-
-  # Forward any other request to port 3000.
-  reverse_proxy localhost:3000 {
-    # Improve SSE latency.
-    flush_interval -1
+  # Forward any other GET, POST, or OPTIONS request, if allowed, to port 3000.
+  handle @allowedGET {
+    reverse_proxy localhost:3000 {
+      # Improve SSE latency.
+      flush_interval -1
+    }
+  }
+  handle @allowedPOST {
+    reverse_proxy localhost:3000 {
+      # Improve SSE latency.
+      flush_interval -1
+    }
+  }
+  # Return not-found for any other request.
+  handle {
+    respond 404
   }
 }
 ```
 
-This configuration prevents granular reporting by Testaro agents from being buffered, so the updates reach the browser without delay.
+This configuration can be futher tightened if experience warrants.
+
+The `flush_interval` setting prevents granular reporting by Testaro agents from being buffered, so the updates reach the browser without delay.
 
 ## Version management
 

package/ai0BalanceForm/index.js

@@ -47,7 +47,7 @@ exports.answer = async (_, search) => {
       // Report the error.
       return {
         status: 'error',
-        error: 'Invalid authorization code'
+        message: 'Invalid authorization code'
       }
     }
   }
@@ -60,7 +60,7 @@ exports.answer = async (_, search) => {
       oldBalance = `$${balanceData.balance} is the`;
     }
     // If the balance file does not exist or is invalid:
-    catch (error) {
+    catch {
       oldBalance = 'There is no';
     }
   }

package/diagnoses/index.js

@@ -135,6 +135,6 @@ exports.answer = async (pageArgs, search) => {
   // Otherwise, report this.
   return {
     status: 'error',
-    error: 'Invalid report specification'
+    message: 'Invalid report specification'
   };
 };

package/index.js

@@ -28,7 +28,7 @@ const {
   reportsPath,
   ruleIDs
 } = require('./util');
-const {handleMCP} = require('./mcp');
+const {handleMCP, mcpPath} = require('./mcp');
 const fs = require('fs/promises');
 const http = require('http');
 const https = require('https');
@@ -80,7 +80,8 @@ const AI_MODEL0_OUTPUT_PRICE = Number(process.env.AI_MODEL0_OUTPUT_PRICE);
 
 // Serves or sends an error message.
 const serveError = async (error, response, isHumanUser = true) => {
-  console.log(error.message || 'ERROR');
+  const errorLines = Object.entries(error).map(pair => `${pair[0]}: ${pair[1]}`);
+  console.log(errorLines.join('\n') || 'ERROR');
   if (! response.writableEnded) {
     response.statusCode = 400;
     // If the request is from a human user:
@@ -128,7 +129,7 @@ const checkBalancesForAlerts = async report => {
       // Get the recorded AI service 0 balance.
       balanceJSON = await fs.readFile(balancePath, 'utf8');
     }
-    catch (error) {
+    catch {
       console.error('ERROR: AI service 0 balance file missing');
     }
     // If the variables required for an AI service 0 balance alert are defined:
@@ -169,6 +170,21 @@ const checkBalancesForAlerts = async report => {
     }
   }
 };
+// Creates an error object about a suspicious request.
+const getAbuseError = (request, reason) => {
+  const {method, url, headers} = request;
+  const ip = headers['x-forwarded-for'] || request.socket.remoteAddress || 'unknown';
+  return {
+    message: 'Invalid request',
+    reason,
+    'IP address': ip,
+    method,
+    URL: url,
+    'user agent': headers['user-agent'] || 'none',
+    referer: headers.referer || 'none',
+    time: new Date().toISOString()
+  };
+};
 // Handles a request.
 const requestHandler = async (request, response) => {
   // Sets response headers.
@@ -194,19 +210,11 @@ const requestHandler = async (request, response) => {
   const {pathname, search} = requestURL;
   const pageName = pathname.split('/')[1];
   const pathTail = pathname.split('/').slice(2).join('/');
-  // If the request is an OPTIONS request:
-  if (method === 'OPTIONS') {
-    // Serve response headers, including one allowing requests from other applications.
-    response.setHeader('Access-Control-Allow-Origin', '*');
-    response.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    response.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
-    response.statusCode = 204;
-    response.end();
-  }
-  // Otherwise, if the request is a GET request:
-  else if (method === 'GET') {
+  // If the request is a GET request:
+  if (method === 'GET') {
     // If it is for the model context protocol server:
-    if (pathname === '/mcp') {
+    if (pathname === mcpPath) {
+      // Handle the MCP request.
       await handleMCP(request, response);
     }
     // Otherwise, if it is for the home page:
@@ -251,6 +259,13 @@ const requestHandler = async (request, response) => {
       setHeaders('text/plain', '/llms-full.txt', 'medium');
       response.end(llmsfull);
     }
+    // Otherwise, if it is for the XML sitemap:
+    else if (pageName === 'sitemap.xml') {
+      const sitemap = await fs.readFile('sitemap.xml', 'utf8');
+      // Serve it.
+      setHeaders('application/xml', '/sitemap.xml', 'medium');
+      response.end(sitemap);
+    }
     // Otherwise, if it is for a full report download:
     else if (pageName === 'fullReport.json') {
       const [timeStamp, jobID] = pathTail.split('/');
@@ -260,17 +275,17 @@ const requestHandler = async (request, response) => {
         // If the report exists and is hidden:
         if (reportHidden === true) {
           console.log(`ERROR: Hidden report ${timeStamp}-${jobID} requested`);
-          // Report this.
+          // Report this as suspected abuse.
           await serveError(
-            {message: `ERROR: requested report ${timeStamp}-${jobID} not available`},
+            getAbuseError(request, `Requested report ${timeStamp}-${jobID} not available`),
             response,
             true
           );
         }
-        // Otherwise, if any other error occurred:
+        // Otherwise, if the report does not exist or another error occurred:
         else if (typeof reportHidden === 'string') {
-          // Report it.
-          await serveError({message: reportHidden}, response, true);
+          // Report this as suspected abuse.
+          await serveError(getAbuseError(request, reportHidden), response, true);
         }
         // Otherwise, i.e. if the report log is valid and not hidden:
         else {
@@ -314,14 +329,14 @@ const requestHandler = async (request, response) => {
         }
         // Otherwise, i.e. if they are invalid:
         else {
-          // Report the error.
-          await serveError({message: answerData.error}, response, true);
+          // Report the error as suspected abuse.
+          await serveError(getAbuseError(request, answerData.message), response, true);
         }
       }
       // Otherwise, i.e. if the answer cannot be generated:
       else {
-        // Report the error.
-        await serveError({message: 'ERROR: Invalid request'}, response, true);
+        // Report the error as suspected abuse.
+        await serveError(getAbuseError(request, 'Request for nonexistent page'), response, true);
       }
     }
     // Otherwise, if it is for an API service:
@@ -377,7 +392,7 @@ const requestHandler = async (request, response) => {
         setHeaders(mimeTypes[ext] || 'application/octet-stream', null, 'low');
         response.end(img);
       }
-      catch (_) {
+      catch {
         await serveError({message: 'ERROR: Image not found'}, response, true);
       }
     }
@@ -439,7 +454,7 @@ const requestHandler = async (request, response) => {
           // Otherwise, i.e. if they are invalid:
           else {
             // Report the error.
-            await serveError({message: answerData.error}, response, true);
+            await serveError({message: answerData.message}, response, true);
           }
         }
         // Otherwise, i.e. if the request is invalid:
@@ -473,7 +488,7 @@ const requestHandler = async (request, response) => {
             // Otherwise, i.e. if they are invalid:
             else {
               // Report the error.
-              await serveError({message: answerData.error}, response, true);
+              await serveError({message: answerData.message}, response, true);
             }
           }
         }
@@ -495,18 +510,18 @@ const requestHandler = async (request, response) => {
           if (what) {
             // Set a location header for a response.
             response.setHeader('content-location', `${pathname}${search}`);
-            // Get the answer data.
+            // Get the answer data about the remaining recommendations.
             const answerData = await require(path.join(__dirname, 'testOrder', 'index'))
             .answer(url, what, authCode);
             // If the answer data are valid:
             if (answerData.status === 'ok') {
-              // Serve the answer page.
+              // Serve the test-order page with the remaining recommendations.
               response.end(answerData.answerPage);
             }
             // Otherwise, i.e. if they are invalid:
             else {
               // Report the error.
-              await serveError({message: answerData.error}, response, true);
+              await serveError({message: answerData.message}, response, true);
             }
           }
           // Otherwise, i.e. if it is a rejection:
@@ -521,7 +536,7 @@ const requestHandler = async (request, response) => {
             response.setHeader('content-location', '/recActionForm.html');
             // Get the answer data.
             const answerData = await require(path.join(__dirname, 'recActionForm', 'index')).answer();
-            // Serve the test-order form.
+            // Serve the test-order form with the remaining recommendations.
             response.end(answerData.answerPage);
           }
         }
@@ -547,7 +562,7 @@ const requestHandler = async (request, response) => {
         // Otherwise, i.e. if they are invalid:
         else {
           // Report the error.
-          await serveError({message: answerData.error}, response, true);
+          await serveError({message: answerData.message}, response, true);
         }
       }
       // Otherwise, if it is a WCAG map renewal:
@@ -566,7 +581,7 @@ const requestHandler = async (request, response) => {
         // Otherwise, i.e. if they are invalid:
         else {
           // Report the error.
-          await serveError({message: answerData.error}, response, true);
+          await serveError({message: answerData.message}, response, true);
         }
       }
       // Otherwise, if it is a request from an agent:
@@ -753,7 +768,7 @@ const requestHandler = async (request, response) => {
         }
         else {
           response.statusCode = 400;
-          response.end(JSON.stringify({status: 'error', message: answerData.error}));
+          response.end(JSON.stringify({status: 'error', message: answerData.message}));
         }
       }
       // Otherwise, i.e. if it is any other POST request:
@@ -765,7 +780,7 @@ const requestHandler = async (request, response) => {
   }
   // Otherwise, i.e. if it is neither a GET nor a POST request:
   else {
-    // Report its invalidity.
+    // Report its invalidity. (Caddy handles OPTIONS requests.)
     await serveError({message: 'ERROR: Invalid request method'}, response, true);
   }
 };

package/mcp.js

@@ -15,6 +15,10 @@ const reportIssuesAPI = require('./reportIssues/api');
 const reportIssueAPI = require('./reportIssue/api');
 const testRecFormAPI = require('./testRecForm/api');
 
+// CONSTANTS
+
+exports.mcpPath = '/mcp';
+
 // FUNCTIONS
 
 // Creates and returns an McpServer with Kilotest tools registered.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "35.0.1",
+  "version": "36.1.0",
   "description": "An ensemble testing service with a focus on accessibility",
   "main": "index.js",
   "scripts": {

package/reannotate/index.js

@@ -34,6 +34,6 @@ exports.answer = async authCode => {
   // Otherwise, i.e. if the authorization code is invalid, return an error page.
   return {
     status: 'error',
-    error: 'Invalid authorization code'
+    message: 'Invalid authorization code'
   };
 };

package/reportHideForm/index.js

@@ -32,7 +32,7 @@ exports.answer = async (_, search) => {
       // Report the error.
       return {
         status: 'error',
-        error: 'Invalid authorization code'
+        message: 'Invalid authorization code'
       }
     }
   }

package/reportIssue/index.js

@@ -176,6 +176,6 @@ exports.answer = async pageArgs => {
   // Otherwise, report this.
   return {
     status: 'error',
-    error: 'Invalid report specification'
+    message: 'Invalid report specification'
   };
 };

package/reportIssues/index.js

@@ -171,6 +171,6 @@ exports.answer = async pageArgs => {
   // Otherwise, i.e. if they were not obtained, report this.
   return {
     status: 'error',
-    error: 'Report processing failed'
+    message: 'Report processing failed'
   };
 };

package/reportUnhideForm/index.js

@@ -32,7 +32,7 @@ exports.answer = async (_, search) => {
       // Report the error.
       return {
         status: 'error',
-        error: 'Invalid authorization code'
+        message: 'Invalid authorization code'
       }
     }
   }

package/reportsExpungeForm/index.js

@@ -33,7 +33,7 @@ exports.answer = async (_, search) => {
       // Report the error.
       return {
         status: 'error',
-        error: 'Invalid authorization code'
+        message: 'Invalid authorization code'
       }
     }
   }

package/reportsPruneForm/index.js

@@ -33,7 +33,7 @@ exports.answer = async (_, search) => {
       // Report the error.
       return {
         status: 'error',
-        error: 'Invalid authorization code'
+        message: 'Invalid authorization code'
       }
     }
   }

package/reportsRewindForm/index.js

@@ -33,7 +33,7 @@ exports.answer = async (_, search) => {
       // Report the error.
       return {
         status: 'error',
-        error: 'Invalid authorization code'
+        message: 'Invalid authorization code'
       }
     }
   }

package/researchAgent.js

@@ -63,7 +63,7 @@ const getContent = async response => {
       // If it is not JSON:
       catch {
         // Return this.
-        resolve({error: `Response content not JSON (${contentString})`});
+        resolve({message: `Response content not JSON (${contentString})`});
       }
     });
   });

package/robots.txt

@@ -1,4 +1,16 @@
 # robots.txt
 User-agent: *
 Allow: /
+Disallow: /ai0BalanceForm.html
+Disallow: /recActionForm.html
+Disallow: /recAction.html
+Disallow: /reannotateForm.html
+Disallow: /reannotate.html
+Disallow: /reportHideForm.html
+Disallow: /reportUnhideForm.html
+Disallow: /reportsPruneForm.html
+Disallow: /reportsRewindForm.html
+Disallow: /reportsExpungeForm.html
+Disallow: /wcagRenewForm.html
+Disallow: /wcagRenew.html
 Sitemap: https://kilotest.com/sitemap.xml

package/sitemap.xml

@@ -8,4 +8,5 @@
   <url><loc>https://kilotest.com/tutorial.html</loc></url>
   <url><loc>https://kilotest.com/openapi.yaml</loc></url>
   <url><loc>https://kilotest.com/llms.txt</loc></url>
+  <url><loc>https://kilotest.com/llms-full.txt</loc></url>
 </urlset>

package/style.css

@@ -57,7 +57,7 @@ code.thin {
   margin-top: 0;
 }
 details {
-  padding: rem;
+  padding: 0.5rem;
   border: solid #000 1px;
 }
 .error {

package/targets/index.js

@@ -12,7 +12,6 @@ const {
   getObject,
   getPageDataStrings,
   getRecs,
-  getToolNamesString,
   getLogs,
   getReportData,
   isRecommendable,

package/testOrder/index.js

@@ -11,7 +11,7 @@ const path = require('path');
 
 // FUNCTIONS
 
-// Implements a test order and returns an acknowledgement page.
+// Implements a test order and returns a revised recommendations page.
 exports.answer = async (url, what, authCode) => {
   // If the arguments are valid:
   if (isURL(url) && what && authCode === process.env.AUTH_CODE) {
@@ -57,6 +57,6 @@ exports.answer = async (url, what, authCode) => {
   // Otherwise, i.e. if the authorization code is invalid, return an error page.
   return {
     status: 'error',
-    error: 'Invalid authorization code'
+    message: 'Invalid authorization code'
   };
 };

package/testRec/index.js

@@ -17,7 +17,7 @@ exports.answer = async (what, url, why) => {
     // Return an answer reporting this.
     return {
       status: 'error',
-      error: `Page is already ${status}`
+      message: `Page is already ${status}`
     };
   }
   // Otherwise, i.e. if it is recommendable, process the recommendation.

package/tutorial/index.js

@@ -33,11 +33,11 @@ exports.answer = async () => {
 // Sanitizes and saves a tutorial comment to comments.json.
 exports.saveComment = async content => {
   if (!content || typeof content !== 'string') {
-    return {status: 'error', error: 'No content provided'};
+    return {status: 'error', message: 'No content provided'};
   }
   const sanitized = sanitize(content);
   if (!sanitized) {
-    return {status: 'error', error: 'Comment is empty after sanitization'};
+    return {status: 'error', message: 'Comment is empty after sanitization'};
   }
   let comments = [];
   try {

package/util.js

@@ -679,7 +679,7 @@ exports.processRec = async (testType, dirName, what, url, why) => {
   }
   return {
     status: 'error',
-    error: 'Invalid recommendation'
+    message: 'Invalid recommendation'
   };
 };
 // Gets the WCAG Understanding link for a numeric WCAG standard identifier.

package/wcagRenew/index.js

@@ -50,21 +50,21 @@ exports.answer = async authCode => {
         // Report this.
         return {
           status: 'error',
-          error: 'No entries found in WCAG map source'
+          message: 'No entries found in WCAG map source'
         };
       }
     }
     else {
       return {
         status: 'error',
-        error: 'WCAG map source not retrieved'
+        message: 'WCAG map source not retrieved'
       };
     }
   }
   else {
     return {
       status: 'error',
-      error: 'Authorization code invalid'
+      message: 'Authorization code invalid'
     };
   }
 };