@omega.js/backend 0.1.0

package/test/helpers/dev-only-routes.test.js

@@ -0,0 +1,225 @@
+/**
+ * Test: the development-only route folder gate (#238)
+ *
+ * `routes/test/*` exists to exercise the framework — it echoes the settings
+ * engine, increments a usage counter, reflects a redirect, resets a seeded
+ * persona — and none of it belongs at a production URL. ONE guard in
+ * Middleware.run() covers the whole folder, so a NEW test route is gated the
+ * day it lands instead of the day somebody remembers to copy a guard.
+ *
+ * Run: npx omega test framework:helpers/dev-only-routes
+ *
+ * The decision is pure (route name + environment), so it runs here directly
+ * with the REAL Manager resolving the environment — nothing is hand-rolled.
+ * The wiring half is proven by the emulator itself: every `test/routes/test/*`
+ * suite still round-trips green, which is the "still serves under the
+ * emulator" leg.
+ */
+const fs = require('fs');
+const path = require('path');
+const Middleware = require('../../dist/manager/helpers/middleware.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const { isDevOnlyRouteBlocked, isRouteOutsideRoutesDir, DEV_ONLY_ROUTE_FOLDER } = Middleware;
+
+const ROUTES_DIR = path.resolve(__dirname, '../../dist/manager/routes');
+
+// Every route the framework ships in the dev-only folder, read off DISK rather
+// than listed here — a route added tomorrow joins this test automatically.
+function listDevOnlyRoutes() {
+  const dir = path.join(ROUTES_DIR, DEV_ONLY_ROUTE_FOLDER);
+  const names = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      names.push(`${DEV_ONLY_ROUTE_FOLDER}/${entry.name}`);
+    } else if (entry.name === 'index.js') {
+      names.push(DEV_ONLY_ROUTE_FOLDER);
+    }
+  }
+
+  return names;
+}
+
+// The env-detection vars are getEnvironment()'s only inputs — clear them for a
+// clean slate per case, and restore afterward (mirrors helpers/environment).
+function withEnv(overrides, fn) {
+  const KEYS = ['OMEGA_TEST_MODE', 'ENVIRONMENT', 'FUNCTIONS_EMULATOR', 'TERM_PROGRAM'];
+  const saved = {};
+  for (const k of KEYS) saved[k] = process.env[k];
+  try {
+    for (const k of KEYS) delete process.env[k];
+    for (const k of Object.keys(overrides)) process.env[k] = overrides[k];
+    return fn();
+  } finally {
+    for (const k of KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  }
+}
+
+module.exports = defineCases({
+  description: 'Development-only route folder gate',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'the folder is not empty — the disk read this suite depends on works',
+      async run({ assert }) {
+        const routes = listDevOnlyRoutes();
+
+        assert.ok(routes.length > 1, `Expected several ${DEV_ONLY_ROUTE_FOLDER}/ routes, got ${routes.length}`);
+        assert.contains(routes, 'test/usage', 'the usage route is one of them');
+        assert.contains(routes, 'test/redirect', 'and the redirect route');
+      },
+    },
+
+    {
+      name: 'every route in the dev-only folder is refused in production',
+      async run({ Manager, assert }) {
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          const environment = Manager.getEnvironment();
+          assert.equal(environment, 'production', 'the real Manager resolves production');
+
+          for (const route of listDevOnlyRoutes()) {
+            assert.equal(
+              isDevOnlyRouteBlocked(route, environment),
+              true,
+              `${route} should be refused in production`
+            );
+          }
+        });
+      },
+    },
+
+    {
+      name: 'a route added to the folder later is refused without touching the guard',
+      async run({ Manager, assert }) {
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          // Not a file that exists — the point is that the gate keys off the
+          // FOLDER, so a handler nobody has written yet is already covered.
+          assert.equal(
+            isDevOnlyRouteBlocked(`${DEV_ONLY_ROUTE_FOLDER}/some-future-debug-route`, Manager.getEnvironment()),
+            true,
+            'a not-yet-written test route is gated by default'
+          );
+        });
+      },
+    },
+
+    {
+      name: 'the same routes serve under the emulator (development AND testing)',
+      async run({ Manager, assert }) {
+        const scenarios = [
+          { env: { FUNCTIONS_EMULATOR: 'true' }, expect: 'development' },
+          { env: { OMEGA_TEST_MODE: 'true' }, expect: 'testing' },
+        ];
+
+        for (const scenario of scenarios) {
+          withEnv(scenario.env, () => {
+            const environment = Manager.getEnvironment();
+            assert.equal(environment, scenario.expect, `the real Manager resolves ${scenario.expect}`);
+
+            for (const route of listDevOnlyRoutes()) {
+              assert.equal(
+                isDevOnlyRouteBlocked(route, environment),
+                false,
+                `${route} must still serve in ${scenario.expect}`
+              );
+            }
+          });
+        }
+      },
+    },
+
+    {
+      name: 'test/health is no carve-out either — the folder gate has none',
+      async run({ Manager, assert }) {
+        // It WAS the one exception: @omega.js/manager's live API check read it
+        // on a PRODUCTION host, so gating it would have broken `omega manage`
+        // against a real brand. The probe is a REAL route now (`routes/health`,
+        // covered by test/routes/health.test.js) and every reader points there,
+        // so the exception list — and the mechanism behind it — is gone.
+        assert.equal(Middleware.DEV_ONLY_ROUTE_EXCEPTIONS, undefined, 'the exception mechanism is gone, not just emptied');
+
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          assert.equal(isDevOnlyRouteBlocked('test/health', Manager.getEnvironment()), true, 'the old probe path is refused in production like every other test route');
+        });
+      },
+    },
+
+    {
+      name: 'routes outside the folder are never gated',
+      async run({ Manager, assert }) {
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          const environment = Manager.getEnvironment();
+
+          for (const route of ['', 'user/sign-up', 'payments/intent', 'general/uuid', 'testing/thing', 'contest']) {
+            assert.equal(
+              isDevOnlyRouteBlocked(route, environment),
+              false,
+              `${route || '<root>'} is a real route and must answer in production`
+            );
+          }
+        });
+      },
+    },
+
+    {
+      name: 'the URL shapes the function path hands in are normalized before the check',
+      async run({ Manager, assert }) {
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          const environment = Manager.getEnvironment();
+
+          // BackendRouter takes routePath straight off the request URL, so a
+          // trailing slash, a .js suffix or a case variant must not walk past
+          // the gate.
+          for (const route of ['test/usage', 'test/usage/', '/test/usage', 'test/usage.js', 'TEST/usage', 'Test/Usage']) {
+            assert.equal(isDevOnlyRouteBlocked(route, environment), true, `${route} is refused in production`);
+          }
+
+          // Dot segments: the loader's path.resolve() collapses these to
+          // routes/test/usage, so the gate has to read them the same way or a
+          // caller reaches the handler with a `./` in front of it.
+          for (const route of ['./test/usage', './/test/usage', 'x/../test/usage', './/./test/usage']) {
+            assert.equal(isDevOnlyRouteBlocked(route, environment), true, `${route} resolves into the folder and is refused`);
+          }
+        });
+      },
+    },
+
+    {
+      name: 'a route path may not escape the routes directory',
+      async run({ assert }) {
+        // path.resolve() rewrites the path the loader require()s, so these are
+        // refused on their SHAPE — environment plays no part.
+        const escaping = [
+          // Climbs out: `/omega/../schemas/test/usage` require()s a schema
+          // module as a handler.
+          '../schemas/test/usage',
+          '../../etc/passwd',
+          // Climbs out and back IN — resolves to routes/test/usage, so the
+          // folder gate alone never sees a `test` first segment.
+          '../routes/test/usage',
+          // Absolute: path.resolve() would hand it the whole filesystem.
+          '/schemas/test/usage',
+          '//schemas/test/usage',
+        ];
+
+        for (const route of escaping) {
+          assert.equal(isRouteOutsideRoutesDir(route), true, `${route} must be refused before the loader sees it`);
+        }
+      },
+    },
+
+    {
+      name: 'ordinary route paths are not mistaken for an escape',
+      async run({ assert }) {
+        for (const route of ['', 'test/usage', './test/usage', 'x/../test/usage', 'user/sign-up', 'general/uuid', 'items/export']) {
+          assert.equal(isRouteOutsideRoutesDir(route), false, `${route || '<root>'} stays inside the routes directory`);
+        }
+      },
+    },
+  ],
+});

package/test/helpers/env-reader.test.js

@@ -0,0 +1,362 @@
+/**
+ * The one env reader and the boot guard it powers
+ * ([#581](https://github.com/Omega-JS-Stack/omega/issues/581)).
+ *
+ * A brand's backend used to serve every route fine with a required key
+ * missing and crash at the first customer action that needed it (#569: an
+ * order email, at a real customer's first receipt). Now `Manager.init()`
+ * validates every required key of the env schema and refuses — in EVERY
+ * environment, development included — with ONE error that names them all.
+ * The single exempt lane is a process with no consumer omega.json5: the
+ * framework booting itself, where there is no brand for a manage run to have
+ * minted keys into. (The self-test fixture IS brand-shaped and gets its keys
+ * seeded — see ensureFixtureEnv in cli/commands/test.js.)
+ *
+ * Real everything: the real reader, the real Manager module booted against
+ * real temp project dirs. Plain-node unit test (no emulator, no network).
+ *
+ * Run: npx omega test framework:helpers/env-reader
+ */
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { requiredEnvKeys, envEnvironment } = require('../../dist/vendor/config/index.js');
+
+const env = require('../../dist/manager/libraries/env.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const MANAGER_PATH = require.resolve('../../dist/manager/index.js');
+const REQUIRED = requiredEnvKeys('backend');
+
+/** A FRESH Manager module, so the boot latches start unset. */
+function freshManagerModule() {
+  delete require.cache[MANAGER_PATH];
+
+  return require(MANAGER_PATH);
+}
+
+/** A temp project dir, with a brand's config/omega.json5 when asked for one. */
+function projectDir({ consumerConfig }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-env-guard-'));
+
+  // The boot reads the project manifest for its name/version
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'fixture-backend', version: '0.0.0' }));
+
+  if (consumerConfig) {
+    fs.mkdirSync(path.join(dir, 'config'));
+    fs.writeFileSync(path.join(dir, 'config', 'omega.json5'), JSON.stringify({
+      brand: { id: 'fixture', name: 'Fixture Brand', url: 'https://fixture.test' },
+      targets: { backend: {} },
+    }));
+  }
+
+  return dir;
+}
+
+/**
+ * Run `thunk` with `vars` applied to process.env (null deletes), restoring
+ * every touched name afterwards — a leaked value would steer the environment
+ * resolution of every later test in the run.
+ */
+function withEnv(vars, thunk) {
+  const saved = {};
+  for (const [name, value] of Object.entries(vars)) {
+    saved[name] = process.env[name];
+    if (value === null) delete process.env[name];
+    else process.env[name] = value;
+  }
+
+  try {
+    return thunk();
+  } finally {
+    for (const [name, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  }
+}
+
+// The two environment signals getEnvironment() reads, spelled as env vars:
+// testing wins over everything, so a production case has to silence the
+// runner's own OMEGA_TEST_MODE
+const PRODUCTION = { OMEGA_TEST_MODE: null, ENVIRONMENT: 'production' };
+const DEVELOPMENT = { OMEGA_TEST_MODE: null, ENVIRONMENT: 'development' };
+
+/**
+ * Boot a real Manager in `development` with every required key absent,
+ * restoring the process env afterwards — a leaked delete would break every
+ * later test in the run.
+ */
+function bootWithoutRequiredKeys({ consumerConfig }) {
+  const saved = { OMEGA_TEST_MODE: process.env.OMEGA_TEST_MODE, ENVIRONMENT: process.env.ENVIRONMENT };
+  for (const name of REQUIRED) {
+    saved[name] = process.env[name];
+    delete process.env[name];
+  }
+
+  // getEnvironment() reads these live on every call: testing wins over
+  // everything, so the runner's own OMEGA_TEST_MODE has to step aside for
+  // this boot to BE a development boot
+  delete process.env.OMEGA_TEST_MODE;
+  process.env.ENVIRONMENT = 'development';
+
+  const dir = projectDir({ consumerConfig: consumerConfig });
+  const warnings = [];
+  const originalWarn = console.warn;
+  console.warn = (...args) => warnings.push(args.join(' '));
+
+  try {
+    const FreshManager = freshManagerModule();
+    const manager = new FreshManager();
+    manager.init(null, { cwd: dir, log: false });
+
+    // Resolved INSIDE the boot's env: getEnvironment() reads live, and the
+    // finally below puts the runner's own test-mode signal back
+    return { manager, warnings, environment: manager.getEnvironment() };
+  } finally {
+    console.warn = originalWarn;
+    fs.rmSync(dir, { recursive: true, force: true });
+    for (const [name, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  }
+}
+
+/**
+ * Boot a real Manager with every REQUIRED key seeded (so the #581 guard is
+ * satisfied and the CONDITIONAL one is what fires), the given consumer config
+ * on disk, and the given environment. Restores the process env afterwards.
+ */
+function bootWithConfig({ config, environment }) {
+  const saved = { OMEGA_TEST_MODE: process.env.OMEGA_TEST_MODE, ENVIRONMENT: process.env.ENVIRONMENT };
+  for (const name of REQUIRED) {
+    saved[name] = process.env[name];
+    process.env[name] = 'fixture-value';
+  }
+  saved.RECAPTCHA_SECRET_KEY = process.env.RECAPTCHA_SECRET_KEY;
+  delete process.env.RECAPTCHA_SECRET_KEY;
+
+  delete process.env.OMEGA_TEST_MODE;
+  process.env.ENVIRONMENT = environment;
+
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-env-rules-'));
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'fixture-backend', version: '0.0.0' }));
+  fs.mkdirSync(path.join(dir, 'config'));
+  fs.writeFileSync(path.join(dir, 'config', 'omega.json5'), JSON.stringify(config));
+
+  const warnings = [];
+  const originalWarn = console.warn;
+  console.warn = (...args) => warnings.push(args.join(' '));
+
+  try {
+    const FreshManager = freshManagerModule();
+    new FreshManager().init(null, { cwd: dir, log: false });
+    return { warnings };
+  } finally {
+    console.warn = originalWarn;
+    fs.rmSync(dir, { recursive: true, force: true });
+    for (const [name, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  }
+}
+
+// A brand whose config makes RECAPTCHA_SECRET_KEY mandatory: the client mints
+// tokens the moment a site key exists, and the backend can never verify one
+// without the secret half — the #507 403-on-every-protected-POST state.
+const HALF_KEYED_CAPTCHA = {
+  brand: { id: 'fixture', name: 'Fixture Brand', url: 'https://fixture.test' },
+  captcha: { providers: { recaptcha: { siteKey: '6Lfixture' } } },
+  targets: { backend: {} },
+};
+
+module.exports = defineCases({
+  description: 'The one env reader (#581): declared keys only, and a boot that refuses without the required ones',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'reading an undeclared key fails at the read, not at the symptom',
+
+      run() {
+        assert.throws(() => env.get('NOT_IN_THE_ENV_SCHEMA'), (error) => {
+          assert.strictEqual(error.name, 'UnknownEnvKeyError');
+          assert.match(error.message, /NOT_IN_THE_ENV_SCHEMA/);
+          return true;
+        });
+
+        // A declared key resolves through the cascade, empty reading as absent
+        const saved = process.env.GH_TOKEN;
+        try {
+          process.env.GH_TOKEN = 'fixture-token';
+          assert.strictEqual(env.get('GH_TOKEN'), 'fixture-token');
+          assert.strictEqual(env.has('GH_TOKEN'), true);
+
+          process.env.GH_TOKEN = '';
+          assert.strictEqual(env.has('GH_TOKEN'), false);
+        } finally {
+          if (saved === undefined) delete process.env.GH_TOKEN;
+          else process.env.GH_TOKEN = saved;
+        }
+      },
+    },
+
+    {
+      name: 'assertRequired() names EVERY missing key in one error, never a value',
+
+      run() {
+        const saved = {};
+        for (const name of REQUIRED) {
+          saved[name] = process.env[name];
+          delete process.env[name];
+        }
+        // One key present proves the error lists only what is actually missing
+        process.env[REQUIRED[0]] = 'fixture-value-present';
+
+        try {
+          assert.throws(() => env.assertRequired('backend'), (error) => {
+            assert.strictEqual(error.name, 'MissingEnvKeysError');
+            assert.deepStrictEqual(error.keys, REQUIRED.slice(1));
+            for (const name of REQUIRED.slice(1)) {
+              assert.ok(error.message.includes(name), `the error names ${name}`);
+            }
+            assert.ok(!error.message.includes(REQUIRED[0]), 'the key that IS set is not reported missing');
+            assert.ok(!error.message.includes('fixture-value-present'), 'no value ever appears in the message');
+            return true;
+          });
+        } finally {
+          for (const [name, value] of Object.entries(saved)) {
+            if (value === undefined) delete process.env[name];
+            else process.env[name] = value;
+          }
+        }
+      },
+    },
+
+    {
+      name: "a brand's backend refuses to boot in development, naming the missing keys",
+
+      run() {
+        assert.throws(() => bootWithoutRequiredKeys({ consumerConfig: true }), (error) => {
+          assert.strictEqual(error.name, 'MissingEnvKeysError');
+          for (const name of REQUIRED) {
+            assert.ok(error.message.includes(name), `the boot failure names ${name}`);
+          }
+          // The fix, not just the fault
+          assert.match(error.message, /omega manage/);
+          return true;
+        });
+      },
+    },
+
+    {
+      name: 'one key, every environment — the _DEV twin mechanism is gone (#586)',
+
+      run() {
+        // Ruled 2026-08-26: the `<KEY>_DEV` twins are replaced, before they
+        // shipped, by `.env.<environment>` files overlaying the base `.env`.
+        // The reader no longer decides WHICH name to read — the cascade has
+        // already resolved the one name by the time anything reaches here, so
+        // a read returns the same value in every environment.
+        for (const vars of [DEVELOPMENT, PRODUCTION, { ...DEVELOPMENT, OMEGA_TEST_MODE: 'true' }]) {
+          withEnv({ ...vars, STRIPE_SECRET_KEY: 'sk_from_the_cascade' }, () => {
+            assert.strictEqual(env.get('STRIPE_SECRET_KEY'), 'sk_from_the_cascade');
+          });
+        }
+
+        // The twin names are not declared anywhere, so reading one is the
+        // undeclared-key programmer error, not a silent undefined
+        for (const name of ['STRIPE_SECRET_KEY_DEV', 'PAYPAL_CLIENT_SECRET_DEV', 'CHARGEBEE_API_KEY_DEV']) {
+          assert.throws(() => env.get(name), (error) => {
+            assert.strictEqual(error.name, 'UnknownEnvKeyError');
+            return true;
+          }, `${name} must not be a declared key`);
+        }
+
+        // …and a live-shaped value is TRUSTED now: the overlay is where a
+        // local run puts its test credential, and no key gets a shape guard
+        withEnv({ ...DEVELOPMENT, STRIPE_SECRET_KEY: 'sk_live_trusted' }, () => {
+          assert.strictEqual(env.get('STRIPE_SECRET_KEY'), 'sk_live_trusted');
+        });
+      },
+    },
+
+    {
+      name: 'env.environment() IS the one vocabulary the overlay files are named with (#586)',
+
+      run() {
+        assert.strictEqual(env.environment, envEnvironment, "the reader re-exports @omega.js/config's resolver, never a second copy");
+
+        withEnv(DEVELOPMENT, () => assert.strictEqual(env.environment(), 'development'));
+        withEnv(PRODUCTION, () => assert.strictEqual(env.environment(), 'production'));
+        withEnv({ ...DEVELOPMENT, OMEGA_TEST_MODE: 'true' }, () => assert.strictEqual(env.environment(), 'testing'));
+      },
+    },
+
+    {
+      name: 'the framework booting itself (no consumer config) warns and boots',
+
+      run() {
+        const { warnings, environment } = bootWithoutRequiredKeys({ consumerConfig: false });
+
+        assert.strictEqual(environment, 'development', 'the development branch was not reached');
+
+        const guardWarnings = warnings.filter((line) => line.includes('required env'));
+        assert.strictEqual(guardWarnings.length, 1, `the fault is still said out loud, got ${guardWarnings.length}`);
+        assert.match(guardWarnings[0], /\[@omega\.js\/backend:index\]/);
+      },
+    },
+
+    {
+      name: "assertRules() names the key its own config made mandatory, and the path that did (#626)",
+
+      run() {
+        withEnv({ RECAPTCHA_SECRET_KEY: null }, () => {
+          assert.throws(() => env.assertRules(HALF_KEYED_CAPTCHA), (error) => {
+            assert.strictEqual(error.name, 'MissingConditionalEnvKeysError');
+            assert.deepStrictEqual(error.keys, ['RECAPTCHA_SECRET_KEY']);
+            // The BRAND-level key name, which is what a human sets, and the
+            // config path that made it mandatory
+            assert.ok(error.message.includes('RECAPTCHA_SECRET_KEY'), 'the error names the key');
+            assert.ok(error.message.includes('captcha.providers.recaptcha.siteKey'), 'and the path that requires it');
+            return true;
+          });
+        });
+
+        // The same config with the key present owes nothing…
+        withEnv({ RECAPTCHA_SECRET_KEY: 'fixture-secret' }, () => {
+          assert.strictEqual(env.assertRules(HALF_KEYED_CAPTCHA), undefined);
+        });
+
+        // …and a brand that never set the site key owes nothing either: the
+        // rule is one-directional, and an unkeyed brand is sanctioned (#17)
+        withEnv({ RECAPTCHA_SECRET_KEY: null }, () => {
+          assert.strictEqual(env.assertRules({ brand: { id: 'fixture' } }), undefined);
+        });
+      },
+    },
+
+    {
+      name: 'a production boot REFUSES on a conditional key, development warns and continues (#626)',
+
+      run() {
+        assert.throws(() => bootWithConfig({ config: HALF_KEYED_CAPTCHA, environment: 'production' }), (error) => {
+          assert.strictEqual(error.name, 'MissingConditionalEnvKeysError');
+          assert.ok(error.message.includes('RECAPTCHA_SECRET_KEY'), 'the boot failure names the key');
+          return true;
+        });
+
+        const { warnings } = bootWithConfig({ config: HALF_KEYED_CAPTCHA, environment: 'development' });
+        const ruleWarnings = warnings.filter((line) => line.includes('RECAPTCHA_SECRET_KEY'));
+        assert.strictEqual(ruleWarnings.length, 1, `one warning line, got ${ruleWarnings.length}`);
+        assert.match(ruleWarnings[0], /\[@omega\.js\/backend:index\]/);
+        assert.ok(ruleWarnings[0].includes('captcha.providers.recaptcha.siteKey'), 'the warning names the path too');
+      },
+    },
+  ],
+});