feat: add extra e2e test safety improvements (production fail-safe, test DB credentials, AI agent rules) (#951)

* feat: add production fail-safe checks, test DB credential separation, and AI agent safety rules

- Add NODE_ENV=production and DATABASE_URL production-indicator checks
  to tests/global-setup.js and tests/test-db-clean.js
- Support DB_USER_TEST / DB_PASS_TEST env vars for least-privilege
  test database credential separation
- Add Database Safety Rules section to AGENTS.md and AI-GETTING-STARTED.md
- Create .cursorrules with database safety guidelines for AI agents

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* chore: bump version to 4.3.26-20260427 [version bump]

* remove .cursorrules — not used

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: handle promise rejection from clean() safety checks

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: remove DATABASE_URL check, update error wording, require explicit test creds in test-db-clean

- Remove DATABASE_URL production check (no such ENV exists)
- Change 'destructive test operations' to 'test operations' in error message
- test-db-clean.js now requires DB_USER_TEST/DB_PASS_TEST with no fallback

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* feat: add mmgis-stac-test DB isolation and STAC_DB_NAME env var

- Make STAC DB name configurable via STAC_DB_NAME in API/connection.js
  and scripts/init-db.js (defaults to 'mmgis-stac')
- global-setup.js creates mmgis-stac-test when STAC services are enabled
  and passes STAC_DB_NAME to the test server
- Adjacent server .env files rewritten to use mmgis-stac-test
- test-db-clean.js drops mmgis-stac-test alongside mmgis-test
- Add DB_USER_TEST, DB_PASS_TEST, STAC_DB_NAME to sample.env and ENVs.md
- Update safety rules in AGENTS.md and AI-GETTING-STARTED.md

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: comment out empty env vars in sample.env, fix STAC cleanup independence

- Comment out DB_USER_TEST, DB_PASS_TEST, STAC_DB_NAME in sample.env to
  prevent dotenv from setting them to empty/whitespace values
- Fix early return in test-db-clean.js so mmgis-stac-test cleanup runs
  independently of whether mmgis-test exists

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: move test env vars to Optional Variables section in ENVs.md

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: require DB_USER_TEST/DB_PASS_TEST in global-setup.js (no fallback)

- Remove fallback to DB_USER/DB_PASS in global-setup.js credential resolution
- Add DB_USER_TEST/DB_PASS_TEST to CI workflow .env setup
- Update ENVs.md to reflect these are now required for tests

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: remove STAC_DB_NAME env var, hardcode mmgis-stac and mmgis-stac-test

- Revert API/connection.js to hardcoded 'mmgis-stac'
- Revert scripts/init-db.js to hardcoded 'mmgis-stac'
- Test infrastructure uses hardcoded 'mmgis-stac-test' constant
- Remove STAC_DB_NAME from sample.env and ENVs.md

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: update sample.env comment — test creds required in both files, no fallback

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

* fix: add windowsHide to suppress console windows on Windows

Prevents execSync and spawn calls in global-setup.js from flashing
empty terminal windows on Windows machines.

Co-Authored-By: tariq.k.soliman <tariqksoliman@gmail.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

.github/workflows/playwright-tests.yml

@@ -64,6 +64,8 @@ jobs:
           echo "DB_NAME=mmgis-test" >> .env
           echo "DB_USER=test_user" >> .env
           echo "DB_PASS=test_password" >> .env
+          echo "DB_USER_TEST=test_user" >> .env
+          echo "DB_PASS_TEST=test_password" >> .env
           echo "ENABLE_MMGIS_WEBSOCKETS=false" >> .env
           echo "ENABLE_CONFIG_WEBSOCKETS=false" >> .env
           echo "HIDE_CONFIG=false" >> .env

AGENTS.md

@@ -717,6 +717,18 @@ ws.on("message", function (message) {
 - Review `webpack.config.js` for misconfigurations
 - Check Node.js version (requires 20+)
 
+## Database Safety Rules for AI Agents
+
+When writing or modifying code that interacts with the database, AI agents MUST follow these rules:
+
+1. **NEVER use `DROP DATABASE` in application code.** The only place `DROP DATABASE` is permitted is in `tests/test-db-clean.js`, and only against the hardcoded `mmgis-test` and `mmgis-stac-test` databases.
+2. **NEVER use `DROP TABLE` or `TRUNCATE TABLE` without proper authorization checks** and input sanitization via `Utils.forceAlphaNumUnder()`.
+3. **NEVER hardcode production database names, hosts, or credentials** in test files or scripts.
+4. **ALWAYS use the dedicated test databases** (`mmgis-test` and `mmgis-stac-test`) for any test-related database operations. Never modify the test database name constants.
+5. **ALWAYS use `DB_USER_TEST` / `DB_PASS_TEST`** environment variables for test database credentials when available, to maintain least-privilege separation.
+6. **NEVER remove or weaken** the `NODE_ENV === 'production'` safety checks in test setup files (`tests/global-setup.js`, `tests/test-db-clean.js`).
+7. When writing database-related tests, **never use destructive commands** like `DROP` or `TRUNCATE` on the main schema. Always target the `mmgis-test` (or `mmgis-stac-test` for STAC) database and implement environment safety checks.
+
 ## References
 
 - **Official Documentation**: https://nasa-ammos.github.io/MMGIS/

AI-GETTING-STARTED.md

@@ -144,3 +144,17 @@ All options are documented in `sample.env`. The critical ones:
 - Test files are located in `tests/e2e/`.
 - The accessibility test (`tests/e2e/accessibility.spec.js`) scans the landing page and map interface for WCAG 2.1 AA violations.
 - Use `npm run test:headed` to see tests run in a visible browser, or `npm run test:debug` to step through tests interactively.
+
+---
+
+## 9. Database Safety Rules for AI Agents
+
+When writing or modifying code that interacts with the database, AI agents MUST follow these rules:
+
+1. **NEVER use `DROP DATABASE` in application code.** The only place `DROP DATABASE` is permitted is in `tests/test-db-clean.js`, and only against the hardcoded `mmgis-test` and `mmgis-stac-test` databases.
+2. **NEVER use `DROP TABLE` or `TRUNCATE TABLE` without proper authorization checks** and input sanitization via `Utils.forceAlphaNumUnder()`.
+3. **NEVER hardcode production database names, hosts, or credentials** in test files or scripts.
+4. **ALWAYS use the dedicated test databases** (`mmgis-test` and `mmgis-stac-test`) for any test-related database operations. Never modify the test database name constants.
+5. **ALWAYS use `DB_USER_TEST` / `DB_PASS_TEST`** environment variables for test database credentials when available, to maintain least-privilege separation.
+6. **NEVER remove or weaken** the `NODE_ENV === 'production'` safety checks in test setup files (`tests/global-setup.js`, `tests/test-db-clean.js`).
+7. When writing database-related tests, **never use destructive commands** like `DROP` or `TRUNCATE` on the main schema. Always target the `mmgis-test` (or `mmgis-stac-test` for STAC) database and implement environment safety checks.

configure/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configure",
-  "version": "4.3.25-20260423",
+  "version": "4.3.26-20260427",
   "homepage": "./configure/build",
   "private": true,
   "dependencies": {

docs/pages/Setup/ENVs/ENVs.md

@@ -105,6 +105,14 @@ If `DB_SSL=true` and if needed, the path to a certificate for ssl | string | def
 
 Alternatively, if `DB_SSL=true` and if needed, a base64 encoded certificate for ssl. `DB_SSL_CERT_BASE64` will take priority over `DB_SSL_CERT` | string | default `null`
 
+#### `DB_USER_TEST=`
+
+Test-specific database user. Required by test infrastructure (`tests/global-setup.js`, `tests/test-db-clean.js`) for least-privilege separation. No fallback — tests will not run without this | string | default `null`
+
+#### `DB_PASS_TEST=`
+
+Test-specific database password. Required by test infrastructure for least-privilege separation. No fallback — tests will not run without this | string | default `null`
+
 #### `AUTH_LOCAL_ALLOW_SIGNUP=`
 
 If AUTH=local and set to true, this allows all guests to the site to create user accounts otherwise, they just see a login page with no signup section | boolean | default `false`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mmgis",
-  "version": "4.3.25-20260423",
+  "version": "4.3.26-20260427",
   "description": "A web-based mapping and localization solution for science operation on planetary missions.",
   "homepage": "build",
   "repository": {

sample.env

@@ -121,6 +121,10 @@ DB_PORT=5432
 DB_NAME=name
 DB_USER=user
 DB_PASS=password
+# Test database credentials for least-privilege separation.
+# Required by both tests/global-setup.js and tests/test-db-clean.js (no fallback).
+# DB_USER_TEST=
+# DB_PASS_TEST=
 # Max number connections in the database's pool. CPUs * 4 is a good number. Default is 10
 DB_POOL_MAX=
 # How many milliseconds until a DB connection times out. Default is 30000 (30 sec)

scripts/init-db.js

@@ -126,7 +126,7 @@ async function initializeDatabase() {
       process.env.WITH_TIPG === "true" ||
       process.env.WITH_TITILER_PGSTAC === "true"
     ) {
-      // mmgis-stac
+      // mmgis-stac
       await baseSequelize
         .query(`CREATE DATABASE "mmgis-stac";`)
         .then(() => {

tests/global-setup.js

@@ -30,6 +30,9 @@ import pgPromise from 'pg-promise';
 /** Hardcoded test database name — never changes. */
 const TEST_DB_NAME = 'mmgis-test';
 
+/** Hardcoded test STAC database name — used when STAC services are enabled. */
+const TEST_STAC_DB_NAME = 'mmgis-stac-test';
+
 /** Port the test server listens on. */
 const TEST_PORT = Number(process.env.TEST_PORT || 18888);
 
@@ -53,11 +56,33 @@ export default async function globalSetup() {
   // Load .env so we can read DB_HOST / DB_PORT / DB_USER / DB_PASS
   config({ path: resolve(process.cwd(), '.env') });
 
+  // ── Production environment fail-safe ──────────────────────────
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error(
+      '\u26A0\uFE0F DANGER: Refusing to run test operations because NODE_ENV is set to "production". ' +
+      'Tests must never be executed against a production environment.'
+    );
+  }
+
   // Read connection settings (with sensible defaults)
   const dbHost = process.env.DB_HOST || readDotenvValue('DB_HOST') || 'localhost';
   const dbPort = process.env.DB_PORT || readDotenvValue('DB_PORT') || '5432';
-  const dbUser = process.env.DB_USER || readDotenvValue('DB_USER') || 'mmgis';
-  const dbPass = process.env.DB_PASS || readDotenvValue('DB_PASS') || 'mmgis';
+
+  // Use dedicated test DB credentials (DB_USER_TEST / DB_PASS_TEST) to enforce
+  // least-privilege separation between CI/test and production database roles.
+  // No fallback — tests must use explicit test credentials.
+  const dbUser = process.env.DB_USER_TEST || readDotenvValue('DB_USER_TEST');
+  const dbPass = process.env.DB_PASS_TEST || readDotenvValue('DB_PASS_TEST');
+
+  if (!dbUser || !dbPass) {
+    throw new Error(
+      'DB_USER_TEST and DB_PASS_TEST must be set for test setup. ' +
+      'Set them in your environment or .env file.'
+    );
+  }
+
+  process.env.DB_USER = dbUser;
+  process.env.DB_PASS = dbPass;
 
   // Force DB_NAME to the hardcoded test database
   process.env.DB_NAME = TEST_DB_NAME;
@@ -168,6 +193,43 @@ export default async function globalSetup() {
     await testDb.$pool.end();
   }
 
+  // ── 3b. Create the STAC test database if STAC services are enabled ──
+  const stacEnabled =
+    process.env.WITH_STAC === 'true' ||
+    process.env.WITH_TIPG === 'true' ||
+    process.env.WITH_TITILER_PGSTAC === 'true';
+
+  if (stacEnabled) {
+    const stacAdminDb = pgp({
+      host: dbHost,
+      port: Number(dbPort),
+      user: dbUser,
+      password: dbPass,
+      database: 'postgres',
+    });
+
+    try {
+      const stacExists = await stacAdminDb.oneOrNone(
+        'SELECT 1 FROM pg_database WHERE datname = $1',
+        [TEST_STAC_DB_NAME],
+      );
+
+      if (!stacExists) {
+        await stacAdminDb.none('CREATE DATABASE $1:name', [TEST_STAC_DB_NAME]);
+        console.log(`[global-setup] Created database "${TEST_STAC_DB_NAME}".`);
+      } else {
+        console.log(`[global-setup] Database "${TEST_STAC_DB_NAME}" already exists.`);
+      }
+    } catch (err) {
+      console.error(`[global-setup] Failed to create database "${TEST_STAC_DB_NAME}":`, err.message);
+      throw err;
+    } finally {
+      await stacAdminDb.$pool.end();
+    }
+
+
+  }
+
   // ── 4. Check if Reference Mission already exists ────────────────
   let needsMission = true;
   const checkDb = pgp({
@@ -234,6 +296,7 @@ export default async function globalSetup() {
     cwd: process.cwd(),
     stdio: 'pipe',
     detached: true,
+    windowsHide: true,
   });
 
   server.stdout.on('data', (d) => {
@@ -398,8 +461,14 @@ function prepareAdjacentServerEnvFiles(repoRoot) {
       },
     );
 
+    // Point adjacent servers at the test STAC database
+    contents = contents.replace(
+      /^(POSTGRES_DBNAME\s*=\s*).*$/m,
+      `$1${TEST_STAC_DB_NAME}`,
+    );
+
     writeFileSync(envFile, contents, 'utf8');
-    console.log(`[global-setup] Created ${srv.dir}/.env from .env.example.`);
+    console.log(`[global-setup] Created ${srv.dir}/.env from .env.example (POSTGRES_DBNAME=${TEST_STAC_DB_NAME}).`);
   }
 }
 
@@ -484,16 +553,16 @@ function killProcessOnPort(port) {
     if (isWin) {
       const out = execSync(
         `netstat -ano | findstr :${port} | findstr LISTENING`,
-        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true },
       ).trim();
       const pids = [...new Set(out.split('\n').map(l => l.trim().split(/\s+/).pop()).filter(Boolean))];
       for (const pid of pids) {
-        try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' }); } catch {}
+        try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', windowsHide: true }); } catch {}
       }
     } else {
       const out = execSync(
         `lsof -ti tcp:${port}`,
-        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true },
       ).trim();
       if (out) {
         for (const pid of out.split('\n')) {

tests/test-db-clean.js

@@ -1,12 +1,11 @@
 /**
- * Drop the `mmgis-test` database.
+ * Drop the `mmgis-test` and `mmgis-stac-test` databases.
  *
  * Usage:  npm run test:clean
  *
- * Reads DB_HOST / DB_PORT / DB_USER / DB_PASS from the project `.env`
- * (or falls back to sensible defaults) and drops the hardcoded
- * `mmgis-test` database. Safe to run at any time — only ever touches
- * the test database.
+ * Reads DB_HOST / DB_PORT / DB_USER_TEST / DB_PASS_TEST from the project
+ * `.env` and drops the hardcoded test databases. Safe to run at any time
+ * — only ever touches test databases.
  */
 
 import { config } from 'dotenv';
@@ -15,6 +14,7 @@ import { readFileSync } from 'fs';
 import pgPromise from 'pg-promise';
 
 const TEST_DB_NAME = 'mmgis-test';
+const TEST_STAC_DB_NAME = 'mmgis-stac-test';
 
 function readDotenvValue(key) {
   try {
@@ -31,10 +31,29 @@ function readDotenvValue(key) {
 async function clean() {
   config({ path: resolve(process.cwd(), '.env') });
 
+  // ── Production environment fail-safe ──────────────────────────
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error(
+      '\u26A0\uFE0F DANGER: Refusing to run test operations because NODE_ENV is set to "production". ' +
+      'Tests must never be executed against a production environment.'
+    );
+  }
+
   const dbHost = process.env.DB_HOST || readDotenvValue('DB_HOST') || 'localhost';
   const dbPort = process.env.DB_PORT || readDotenvValue('DB_PORT') || '5432';
-  const dbUser = process.env.DB_USER || readDotenvValue('DB_USER') || 'mmgis';
-  const dbPass = process.env.DB_PASS || readDotenvValue('DB_PASS') || 'mmgis';
+
+  // Use dedicated test DB credentials (DB_USER_TEST / DB_PASS_TEST) to enforce
+  // least-privilege separation between CI/test and production database roles.
+  // No fallback — test-db-clean must use explicit test credentials.
+  const dbUser = process.env.DB_USER_TEST || readDotenvValue('DB_USER_TEST');
+  const dbPass = process.env.DB_PASS_TEST || readDotenvValue('DB_PASS_TEST');
+
+  if (!dbUser || !dbPass) {
+    throw new Error(
+      'DB_USER_TEST and DB_PASS_TEST must be set for test database cleanup. ' +
+      'Set them in your environment or .env file.'
+    );
+  }
 
   const pgp = pgPromise();
   const db = pgp({
@@ -46,31 +65,50 @@ async function clean() {
   });
 
   try {
+    // Drop mmgis-test
     const exists = await db.oneOrNone(
       'SELECT 1 FROM pg_database WHERE datname = $1',
       [TEST_DB_NAME],
     );
 
-    if (!exists) {
-      console.log(`Database "${TEST_DB_NAME}" does not exist. Nothing to clean.`);
-      return;
+    if (exists) {
+      await db.none(
+        `SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+         WHERE datname = $1 AND pid <> pg_backend_pid()`,
+        [TEST_DB_NAME],
+      );
+      await db.none('DROP DATABASE $1:name', [TEST_DB_NAME]);
+      console.log(`Dropped database "${TEST_DB_NAME}".`);
+    } else {
+      console.log(`Database "${TEST_DB_NAME}" does not exist — skipping.`);
     }
 
-    // Terminate active connections before dropping
-    await db.none(
-      `SELECT pg_terminate_backend(pid) FROM pg_stat_activity
-       WHERE datname = $1 AND pid <> pg_backend_pid()`,
-      [TEST_DB_NAME],
+    // Drop mmgis-stac-test (independent of main test DB)
+    const stacExists = await db.oneOrNone(
+      'SELECT 1 FROM pg_database WHERE datname = $1',
+      [TEST_STAC_DB_NAME],
     );
 
-    await db.none('DROP DATABASE $1:name', [TEST_DB_NAME]);
-    console.log(`Dropped database "${TEST_DB_NAME}".`);
+    if (stacExists) {
+      await db.none(
+        `SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+         WHERE datname = $1 AND pid <> pg_backend_pid()`,
+        [TEST_STAC_DB_NAME],
+      );
+      await db.none('DROP DATABASE $1:name', [TEST_STAC_DB_NAME]);
+      console.log(`Dropped database "${TEST_STAC_DB_NAME}".`);
+    } else {
+      console.log(`Database "${TEST_STAC_DB_NAME}" does not exist — skipping.`);
+    }
   } catch (err) {
-    console.error(`Failed to drop "${TEST_DB_NAME}":`, err.message);
+    console.error(`Failed to drop test databases:`, err.message);
     process.exit(1);
   } finally {
     pgp.end();
   }
 }
 
-clean();
+clean().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});