@omega.js/backend 0.1.0

package/test/helpers/analytics-user-data.test.js

@@ -0,0 +1,194 @@
+/**
+ * Test: the GA4 Measurement Protocol helper's `user_data` match block
+ * ([#388](https://github.com/Omega-JS-Stack/omega/issues/388), the email
+ * normalization pin of [#397](https://github.com/Omega-JS-Stack/omega/issues/397),
+ * and the name normalization pin of
+ * [#403](https://github.com/Omega-JS-Stack/omega/issues/403)).
+ *
+ * `sha256_phone_number` had never been sent by any event flowing through the
+ * helper: it read `personal.telephone.number`, and the account schema's field is
+ * `personal.telephone.national`. A key that is silently always absent looks
+ * exactly like a user with no phone, so nothing ever complained.
+ *
+ * The authenticated user is a REAL resolved account doc (`Manager.User()` is the
+ * production resolver) rather than a hand-written stand-in — which is what makes
+ * the phoneless case honest: it carries the schema's own `0` default, the value
+ * whose hash would hand every phoneless account one shared junk match key.
+ *
+ * `self.userData` IS the payload's `user_data` — `event()` passes it straight
+ * into the Measurement Protocol body — so the assertions read it directly rather
+ * than firing an event at Google.
+ *
+ * Run: npx omega test framework:helpers/analytics-user-data
+ */
+
+const crypto = require('crypto');
+const Analytics = require('../../dist/manager/helpers/analytics.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-ga4-user-data-uid';
+const EMAIL = 'buyer@example.com';
+const NATIONAL = 5550102030;
+
+// The same address as it might sit in an account doc, and the digest of its
+// canonical form (`ada.lovelace@example.com`). The expected value is hard-coded
+// rather than hashed here, so the pin fails if the helper's normalization ever
+// drifts from the one every platform agrees on (#397).
+const MESSY_EMAIL = '  Ada.Lovelace@Example.COM ';
+const MESSY_EMAIL_DIGEST = 'e814ff3dc480a94c7ce9334062ec4733c75a002f4bcec0197f62ffea64059e2f';
+
+// The same deal for the names GA4's user-data spec normalizes the same way, with
+// the digests of `ada` and `lovelace` hard-coded (#403).
+const MESSY_FIRST = '  Ada ';
+const MESSY_FIRST_DIGEST = 'fdee430d40bd57deeac186cd9790033d0f06f909a8806e7ce6e717ab7c7d5029';
+const MESSY_LAST = ' LOVELACE ';
+const MESSY_LAST_DIGEST = 'fb1e7ec987523d2cb9e022cec1d6ae7c99dc46edfae4fe51254025fe4bea571f';
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+// The helper reads its user off `ctx.usage.user` — the resolved account doc the
+// middleware attaches on an authenticated request.
+function userDataFor(Manager, settings) {
+  const ctx = Manager.RouteContext({}, { functionName: 'analytics-user-data' });
+
+  ctx.usage = { user: Manager.User(settings).properties };
+
+  return { userData: new Analytics(Manager, { ctx: ctx }).userData, user: ctx.usage.user };
+}
+
+module.exports = defineCases({
+  description: 'analytics(): the GA4 user_data match block',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'an-account-with-a-phone-sends-the-hashed-number',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData } = userDataFor(Manager, {
+          auth: { uid: UID, email: EMAIL },
+          personal: { telephone: { countryCode: 1, national: NATIONAL } },
+        });
+
+        // GA4's spec hashes the E.164 form, plus included — the same digest
+        // TikTok's Events API takes (#392).
+        assert.equal(userData.sha256_phone_number, sha256(`+1${NATIONAL}`), 'the phone rides as SHA256 of the E.164 number');
+        assert.equal(userData.sha256_email_address, sha256(EMAIL), 'the email key is untouched by the phone fix');
+        assert.equal(JSON.stringify(userData).includes(`${NATIONAL}`), false, 'the raw number must never appear anywhere in the payload');
+      },
+    },
+
+    {
+      name: 'the-schema-default-sends-no-phone-hash',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData, user } = userDataFor(Manager, { auth: { uid: UID, email: EMAIL } });
+
+        // The premise: an account with no phone carries 0, not an absent branch.
+        assert.equal(user.personal.telephone.national, 0, 'the schema default is 0');
+
+        assert.equal(userData.sha256_phone_number, undefined, 'no phone on file means no match key, never a hash of 0');
+        assert.equal(Object.values(userData).includes(sha256('0')), false, 'the default must not be hashed under any key');
+      },
+    },
+
+    {
+      name: 'a-messy-email-hashes-its-canonical-form',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData } = userDataFor(Manager, { auth: { uid: UID, email: MESSY_EMAIL } });
+
+        // Casing and padding are the account doc's business, never the match
+        // key's: GA4 matches the digest of the trimmed, lowercased address, and
+        // a raw hash silently misses every user whose email was stored with a
+        // capital in it (#397).
+        assert.equal(userData.sha256_email_address, MESSY_EMAIL_DIGEST, 'the email rides as SHA256 of the normalized address');
+      },
+    },
+
+    {
+      name: 'messy-names-hash-their-canonical-form',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData } = userDataFor(Manager, {
+          auth: { uid: UID, email: EMAIL },
+          personal: { name: { first: MESSY_FIRST, last: MESSY_LAST } },
+        });
+
+        // GA4's user-data spec normalizes a name exactly like an email — trimmed
+        // and lowercased — so hashing what the account happened to store missed
+        // every user whose name carried a capital or a stray space (#403).
+        assert.equal(userData.address.sha256_first_name, MESSY_FIRST_DIGEST, 'the given name rides as SHA256 of its normalized form');
+        assert.equal(userData.address.sha256_last_name, MESSY_LAST_DIGEST, 'the family name rides as SHA256 of its normalized form');
+      },
+    },
+
+    {
+      name: 'an-account-with-no-name-sends-no-name-hash',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData, user } = userDataFor(Manager, { auth: { uid: UID, email: EMAIL } });
+
+        // The schema's default is null, and a normalizer must never turn an
+        // absent name into the digest of '' — one junk key shared by everybody.
+        assert.equal(user.personal.name.first, null, 'the schema default is null');
+
+        assert.equal(userData.address.sha256_first_name, undefined, 'no name on file means no match key');
+        assert.equal(userData.address.sha256_last_name, undefined, 'no name on file means no match key');
+      },
+    },
+
+    {
+      // GA4's user-data spec takes a whole ADDRESS block, and only the names and
+      // the street are hashed: city, region, postal code and country ride in the
+      // clear, normalized ([#577](https://github.com/Omega-JS-Stack/omega/issues/577)).
+      // The ACCOUNT's own location wins over the request's geolocation — the
+      // person's address is what the platform matches, not the exit node they
+      // happened to browse from.
+      name: 'the-address-block-comes-off-the-account-per-ga4-spec',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData } = userDataFor(Manager, {
+          auth: { uid: UID, email: EMAIL },
+          personal: { location: { country: 'us', region: 'California', city: 'San Diego' } },
+        });
+
+        assert.equal(userData.address.city, 'san diego', 'city: lowercased and trimmed, never hashed');
+        assert.equal(userData.address.region, 'california', 'region: the NAME, GA4\'s own sample shape');
+        assert.equal(userData.address.country, 'US', 'country: uppercase ISO 3166-1 alpha-2');
+        assert.equal(userData.address.postal_code, undefined, 'nothing on file means no key at all');
+        assert.equal(userData.address.sha256_street, undefined);
+      },
+    },
+
+    {
+      // The postal code and the street have a home in the schema now
+      // ([#663](https://github.com/Omega-JS-Stack/omega/issues/663)):
+      // `personal.location.postalCode` and `personal.location.street`, filled by
+      // the account page. Before that they were read off field names no account
+      // carried, so GA4 got neither key from any user.
+      name: 'the-postal-code-and-street-come-off-the-account-schema',
+      auth: 'none',
+
+      run: async ({ assert, Manager }) => {
+        const { userData, user } = userDataFor(Manager, {
+          auth: { uid: UID, email: EMAIL },
+          personal: { location: { postalCode: '94035-1234', street: ' 123 Main Street. ' } },
+        });
+
+        assert.equal(user.personal.location.postalCode, '94035-1234', 'precondition: the resolver keeps the schema field');
+
+        assert.equal(userData.address.postal_code, '94035-1234', 'the postal code rides in the clear, only . and ~ removed');
+        assert.equal(userData.address.sha256_street, sha256('123 main street'), 'the street is hashed, its digits kept');
+      },
+    },
+  ],
+});

package/test/helpers/api-manager.test.js

@@ -0,0 +1,311 @@
+/**
+ * Test: helpers/api-manager.js — plan limits, per-user stats, quota math
+ *
+ * Run: npx omega test backend:helpers/api-manager
+ *
+ * The rate-limit half of ApiManager is pure arithmetic over an in-memory user
+ * record, and it decides whether a paying customer's request is served or
+ * refused — so it is unit-testable and worth pinning exactly:
+ *   - init() derives the plan table from the NUMBERS in each config.payment.products
+ *     entry's `features` value map (#647); a perk value is not a limit.
+ *   - getUserStat()/incrementUserStat() read and write `_APIManager.stats`
+ *     against `subscription.limits`.
+ *   - isUserOverStat()'s `daily` frame is the MONTHLY limit divided by 31
+ *     (floored), and the comparison is inclusive.
+ *   - A whitelisted API key reports zero usage and an infinite limit.
+ *
+ * getUser()'s cache/refetch path and validateOfficialRequest()'s captcha
+ * verification need a real ctx/hcaptcha boundary and are proven at the route
+ * level, not here.
+ */
+const ApiManager = require('../../dist/manager/helpers/api-manager.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// The only Manager surface init() reads.
+const makeManager = (products) => ({ config: { payment: { products: products || [] } } });
+
+async function makeApi(options, products) {
+  return new ApiManager(makeManager(products)).init(options);
+}
+
+// The message fn() threw, or null when it did not throw.
+function throwsWith(fn) {
+  try {
+    fn();
+  } catch (e) {
+    return e.message;
+  }
+  return null;
+}
+
+module.exports = defineCases({
+  description: 'ApiManager plan limits + stat accounting',
+  type: 'group',
+
+  tests: [
+    // ─── init() ───
+
+    {
+      name: 'init-derives-the-plan-table-from-config-products',
+      async run({ assert }) {
+        const api = await makeApi({}, [
+          { id: 'basic', features: { requests: 3100, support: false } },
+          { id: 'premium', features: { requests: 62000, storage: 10, support: 'priority', templates: true } },
+          { id: 'free' },
+        ]);
+
+        // Only the NUMBERS in a product's `features` map are limits (#647) —
+        // a perk value (a string, a boolean) is not a quota.
+        assert.deepEqual(api.options.plans, {
+          basic: { limits: { requests: 3100 } },
+          premium: { limits: { requests: 62000, storage: 10 } },
+          free: { limits: {} },
+        });
+        assert.equal(api.initialized, true);
+      },
+    },
+
+    {
+      name: 'init-applies-its-defaults-and-a-caller-may-override-them',
+      async run({ assert }) {
+        const defaults = await makeApi({});
+        assert.equal(defaults.options.maxUsersStored, 10000);
+        assert.equal(defaults.options.refetchInterval, 60);
+        assert.equal(defaults.options.resetInterval, 1440);
+        assert.deepEqual(defaults.options.officialAPIKeys, []);
+        assert.deepEqual(defaults.options.whitelistedAPIKeys, []);
+
+        const custom = await makeApi({ refetchInterval: 5, resetInterval: 60, maxUsersStored: 10 });
+        assert.equal(custom.options.refetchInterval, 5);
+        assert.equal(custom.options.resetInterval, 60);
+        assert.equal(custom.options.maxUsersStored, 10);
+      },
+    },
+
+    {
+      name: 'a-config-with-no-products-yields-an-empty-plan-table',
+      async run({ assert }) {
+        const api = await new ApiManager({ config: {} }).init({});
+
+        assert.deepEqual(api.options.plans, {});
+      },
+    },
+
+    // ─── getUserStat ───
+
+    {
+      name: 'getUserStat-reads-current-usage-and-the-plan-limit',
+      async run({ assert }) {
+        const api = await makeApi({});
+        const user = {
+          api: { privateKey: 'key_abc' },
+          subscription: { limits: { requests: 3100 } },
+          _APIManager: { stats: { requests: 42 } },
+        };
+
+        assert.deepEqual(api.getUserStat(user, 'requests'), { current: 42, limit: 3100 });
+      },
+    },
+
+    {
+      name: 'an-unknown-stat-falls-back-to-the-supplied-default-then-zero',
+      async run({ assert }) {
+        const api = await makeApi({});
+        const user = { api: {}, subscription: { limits: {} }, _APIManager: { stats: {} } };
+
+        assert.deepEqual(api.getUserStat(user, 'requests'), { current: 0, limit: 0 });
+        assert.deepEqual(api.getUserStat(user, 'requests', 7), { current: 7, limit: 7 });
+      },
+    },
+
+    {
+      name: 'a-whitelisted-key-reports-zero-used-and-an-infinite-limit',
+      async run({ assert }) {
+        const api = await makeApi({ whitelistedAPIKeys: ['key_internal'] });
+        const byPrivateKey = {
+          api: { privateKey: 'key_internal' },
+          subscription: { limits: { requests: 10 } },
+          _APIManager: { stats: { requests: 9999 } },
+        };
+        const byProvidedKey = {
+          api: {},
+          subscription: { limits: { requests: 10 } },
+          _APIManager: { stats: { requests: 9999 }, providedAPIKey: 'key_internal' },
+        };
+
+        assert.deepEqual(api.getUserStat(byPrivateKey, 'requests'), { current: 0, limit: Infinity });
+        assert.deepEqual(api.getUserStat(byProvidedKey, 'requests'), { current: 0, limit: Infinity });
+      },
+    },
+
+    {
+      name: 'getUserStat-requires-a-user-and-a-stat',
+      async run({ assert }) {
+        const api = await makeApi({});
+
+        assert.equal(throwsWith(() => api.getUserStat(null, 'requests')), '<user> and <stat> required');
+        assert.equal(throwsWith(() => api.getUserStat({}, '')), '<user> and <stat> required');
+      },
+    },
+
+    // ─── incrementUserStat ───
+
+    {
+      name: 'incrementUserStat-adds-and-returns-the-fresh-reading',
+      async run({ assert }) {
+        const api = await makeApi({});
+        const user = { api: {}, subscription: { limits: { requests: 100 } }, _APIManager: { stats: {} } };
+
+        assert.deepEqual(api.incrementUserStat(user, 'requests', 1), { current: 1, limit: 100 });
+        assert.deepEqual(api.incrementUserStat(user, 'requests', 4), { current: 5, limit: 100 });
+        assert.equal(user._APIManager.stats.requests, 5, 'the user record is updated in place');
+      },
+    },
+
+    {
+      name: 'incrementUserStat-accepts-a-negative-amount-the-official-refund-path',
+      async run({ assert }) {
+        const api = await makeApi({});
+        const user = { api: {}, subscription: { limits: { requests: 100 } }, _APIManager: { stats: { requests: 5 } } };
+
+        assert.deepEqual(api.incrementUserStat(user, 'requests', -1), { current: 4, limit: 100 });
+      },
+    },
+
+    // ─── isUserOverStat: the quota decision ───
+
+    {
+      name: 'the-daily-frame-is-the-monthly-limit-divided-by-31-floored',
+      async run({ assert }) {
+        const api = await makeApi({});
+        // 3100 / 31 = 100 requests/day.
+        const at = (used) => api.isUserOverStat(
+          { api: {}, subscription: { limits: { requests: 3100 } }, _APIManager: { stats: { requests: used } } },
+          'requests',
+        );
+
+        assert.equal(at(0), false, 'fresh user is not over quota');
+        assert.equal(at(99), false);
+        assert.equal(at(100), false, 'the bound itself is not over');
+        assert.equal(at(101), true, 'one past the bound is over quota');
+      },
+    },
+
+    {
+      name: 'a-non-daily-frame-uses-the-whole-limit',
+      async run({ assert }) {
+        const api = await makeApi({});
+        const user = { api: {}, subscription: { limits: { requests: 3100 } }, _APIManager: { stats: { requests: 3100 } } };
+
+        assert.equal(api.isUserOverStat(user, 'requests', undefined, 'monthly'), false);
+        user._APIManager.stats.requests = 3101;
+        assert.equal(api.isUserOverStat(user, 'requests', undefined, 'monthly'), true);
+      },
+    },
+
+    {
+      name: 'a-whitelisted-key-is-never-over-quota',
+      async run({ assert }) {
+        const api = await makeApi({ whitelistedAPIKeys: ['key_internal'] });
+        const user = {
+          api: { privateKey: 'key_internal' },
+          subscription: { limits: { requests: 1 } },
+          _APIManager: { stats: { requests: 9999 } },
+        };
+
+        // Infinity is a number, so the daily divide keeps it Infinity.
+        assert.equal(api.isUserOverStat(user, 'requests'), false);
+      },
+    },
+
+    {
+      name: 'a-non-numeric-limit-is-refused-rather-than-guessed',
+      async run({ assert }) {
+        const api = await makeApi({});
+        const user = {
+          api: {},
+          subscription: { limits: { requests: 'unlimited' } },
+          _APIManager: { stats: { requests: 0 } },
+        };
+
+        assert.equal(api.isUserOverStat(user, 'requests'), true, 'a malformed limit fails closed');
+      },
+    },
+
+    {
+      name: 'isUserOverStat-requires-a-user-and-a-stat',
+      async run({ assert }) {
+        const api = await makeApi({});
+
+        assert.equal(throwsWith(() => api.isUserOverStat(null, 'requests')), '<user> and <stat> required');
+        assert.equal(throwsWith(() => api.isUserOverStat({}, null)), '<user> and <stat> required');
+      },
+    },
+
+    // ─── _createNewUser: plan limits land on the record ───
+
+    {
+      name: 'a-new-user-inherits-the-plan-limits-and-starts-at-zero',
+      async run({ assert }) {
+        const api = await makeApi({}, [{ id: 'premium', features: { requests: 62000, storage: 10 } }]);
+
+        const user = api._createNewUser(
+          { auth: { uid: 'uid_1' }, authenticated: true, ip: '1.2.3.4', country: 'US' },
+          'premium',
+          {},
+          false,
+          'key_abc',
+        );
+
+        assert.deepEqual(user.subscription.limits, { requests: 62000, storage: 10 });
+        assert.equal(user.subscription.product.id, 'premium');
+        assert.equal(user._APIManager.stats.requests, 0);
+        assert.equal(user._APIManager.providedAPIKey, 'key_abc');
+        assert.equal(user.authenticated, true);
+        assert.equal(user.ip, '1.2.3.4');
+        assert.equal(user.country, 'US');
+      },
+    },
+
+    {
+      name: 'a-per-user-limit-override-beats-the-plan-limit',
+      async run({ assert }) {
+        const api = await makeApi({}, [{ id: 'basic', features: { requests: 3100 } }]);
+
+        const user = api._createNewUser(
+          { auth: { uid: 'uid_1' }, authenticated: true, subscription: { limits: { requests: 999999 } } },
+          'basic',
+          {},
+          false,
+          null,
+        );
+
+        assert.equal(user.subscription.limits.requests, 999999);
+      },
+    },
+
+    {
+      name: 'stats-carry-over-inside-the-reset-window-and-drop-outside-it',
+      async run({ assert }) {
+        const api = await makeApi({ resetInterval: 60 }, [{ id: 'basic', features: { requests: 3100 } }]);
+        const authed = { auth: { uid: 'uid_1' }, authenticated: true };
+
+        const recent = api._createNewUser(authed, 'basic', {
+          _APIManager: {
+            stats: { requests: 25 },
+            meta: { lastStatsReset: new Date(Date.now() - 10 * 60 * 1000), lastUserFetch: new Date() },
+          },
+        }, false, null);
+        assert.equal(recent._APIManager.stats.requests, 25, 'inside the window usage is kept');
+
+        const stale = api._createNewUser(authed, 'basic', {
+          _APIManager: {
+            stats: { requests: 25 },
+            meta: { lastStatsReset: new Date(Date.now() - 120 * 60 * 1000), lastUserFetch: new Date() },
+          },
+        }, false, null);
+        assert.equal(stale._APIManager.stats.requests, 0, 'past the window usage resets');
+      },
+    },
+  ],
+});

package/test/helpers/backend-router.test.js

@@ -0,0 +1,136 @@
+/**
+ * Test: helpers/backend-router.js — request URL → middleware route path
+ *
+ * Run: npx omega test backend:helpers/backend-router
+ *
+ * Every incoming HTTP request enters the middleware system through this one
+ * resolution, and the prefix table is a COMPATIBILITY contract:
+ *   /omega/…            the canonical prefix
+ *   /omega_api/…        the direct Cloud Function URL
+ *   /backend-manager/…  the legacy BEM alias, kept so migrating brands'
+ *                       in-the-wild clients keep working
+ * Everything else keeps its path, minus the leading slash — including a first
+ * segment that merely STARTS with a prefix word (/omegatron/…), since a prefix
+ * only counts as a whole segment.
+ */
+const BackendRouter = require('../../dist/manager/helpers/backend-router.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const Manager = { libraries: {} };
+
+// The router only ever reads req.path.
+const resolve = (path) => new BackendRouter(Manager, { path }, {}).resolve().routePath;
+
+module.exports = defineCases({
+  description: 'BackendRouter.resolve() route path extraction',
+  type: 'group',
+
+  tests: [
+    // ─── The canonical prefix ───
+
+    {
+      name: 'strips-the-omega-prefix',
+      async run({ assert }) {
+        assert.equal(resolve('/omega/user/sign-up'), 'user/sign-up');
+        assert.equal(resolve('/omega/admin/post'), 'admin/post');
+      },
+    },
+
+    {
+      // The direct Cloud Function URL. The prefix alternation is ordered
+      // longest-first AND followed by a boundary assertion, so `omega` can
+      // never win a `/omega_api/…` path the way first-match alternation
+      // used to (which left `_api/…`, a route that cannot exist).
+      name: 'strips-the-direct-function-url-prefix',
+      async run({ assert }) {
+        assert.equal(resolve('/omega_api/user/sign-up'), 'user/sign-up');
+      },
+    },
+
+    {
+      name: 'strips-the-legacy-backend-manager-alias',
+      async run({ assert }) {
+        assert.equal(resolve('/backend-manager/user/sign-up'), 'user/sign-up');
+      },
+    },
+
+    // ─── Bare prefixes and depth ───
+
+    {
+      name: 'a-bare-prefix-resolves-to-the-empty-route',
+      async run({ assert }) {
+        assert.equal(resolve('/omega/'), '');
+        assert.equal(resolve('/omega'), '');
+        assert.equal(resolve('/backend-manager/'), '');
+        assert.equal(resolve('/omega_api'), '');
+      },
+    },
+
+    {
+      name: 'deep-paths-keep-every-remaining-segment',
+      async run({ assert }) {
+        assert.equal(resolve('/omega/payment/subscription/cancel'), 'payment/subscription/cancel');
+        assert.equal(resolve('/omega/a/b/c/d/e'), 'a/b/c/d/e');
+      },
+    },
+
+    {
+      name: 'trailing-slashes-are-preserved',
+      async run({ assert }) {
+        assert.equal(resolve('/omega/user/sign-up/'), 'user/sign-up/');
+      },
+    },
+
+    // ─── Unprefixed and absent paths ───
+
+    {
+      name: 'an-unprefixed-path-just-loses-its-leading-slash',
+      async run({ assert }) {
+        assert.equal(resolve('/user/sign-up'), 'user/sign-up');
+        assert.equal(resolve('user/sign-up'), 'user/sign-up');
+      },
+    },
+
+    {
+      name: 'an-absent-path-resolves-to-the-empty-route',
+      async run({ assert }) {
+        assert.equal(resolve(''), '');
+        assert.equal(resolve(undefined), '');
+        assert.equal(resolve('/'), '');
+      },
+    },
+
+    // ─── The prefix must LEAD ───
+
+    {
+      name: 'a-prefix-word-mid-path-is-not-stripped',
+      async run({ assert }) {
+        assert.equal(resolve('/api/omega/user'), 'api/omega/user');
+        assert.equal(resolve('/omega/omega/user'), 'omega/user', 'only the leading prefix goes');
+      },
+    },
+
+    {
+      // The prefix must be a WHOLE first segment: a path whose first segment
+      // merely starts with a prefix word is not a prefixed path at all, and
+      // keeps every character (minus its leading slash).
+      name: 'a-route-merely-starting-with-a-prefix-word-is-untouched',
+      async run({ assert }) {
+        assert.equal(resolve('/omegatron/user'), 'omegatron/user');
+        assert.equal(resolve('/backend-manager-legacy/user'), 'backend-manager-legacy/user');
+      },
+    },
+
+    // ─── Query strings never reach here (req.path excludes them) ───
+
+    {
+      name: 'the-resolution-returns-a-routePath-object',
+      async run({ assert }) {
+        const resolved = new BackendRouter(Manager, { path: '/omega/user/sign-up' }, {}).resolve();
+
+        assert.equal(typeof resolved, 'object');
+        assert.equal(resolved.routePath, 'user/sign-up');
+      },
+    },
+  ],
+});