@omega.js/backend 0.1.0

package/test/routes/payments/winback.test.js

@@ -0,0 +1,597 @@
+/**
+ * Test: POST /payments/winback — the cancel-flow save offer's apply path
+ * ([#268](https://github.com/Omega-JS-Stack/omega/issues/268)).
+ *
+ * The offer is pitched before the cancellation questionnaire and accepting it
+ * discounts the next cycle instead of ending the subscription. What that offer
+ * IS belongs to the brand (`payment.winback`, resolved by @omega.js/config with a
+ * 50%-off default), so this suite reads the brand's own resolution rather than
+ * asserting a number.
+ *
+ * Two layers, the same split cancel.test.js and plan.test.js use:
+ *  - the wire guards and the happy path over `http.as(...)`, which is what
+ *    proves the route is registered, auth-gated and schema-validated at all;
+ *  - the per-subscription guards and the provider capability gate through
+ *    DIRECT handler calls (the _route-harness technique), so one test can choose
+ *    a provider and a subscription shape without minting a persona each.
+ *
+ * The offer is claimed ONCE: the claim lives on
+ * payments-orders/{orderId}.requests.winback, so the second call is refused
+ * against the same document the first one wrote.
+ *
+ * EVERY refusal carries a branchable code on `omega-properties`
+ * ([#311](https://github.com/Omega-JS-Stack/omega/issues/311)): the client
+ * pitches the offer off the account alone, so any refusal it cannot name leaves
+ * the customer in a dialog arming a retry that can never succeed. Each guard
+ * below asserts its own code for that reason.
+ *
+ * Run: npx omega test framework:routes/payments/winback
+ */
+const { buildUser, recordingResponse } = require('./_route-harness.js');
+const winback = require('../../../dist/manager/libraries/payment/winback.js');
+
+const handler = require('../../../dist/manager/routes/payments/winback/post.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+function providerModule(name) {
+  return require(`../../../dist/manager/routes/payments/winback/providers/${name}.js`);
+}
+
+const YEAR = 365 * 24 * 60 * 60;
+
+/**
+ * A paying subscriber the offer can be made to.
+ *
+ * @param {object} Manager - The @omega.js/backend Manager
+ * @param {object} options - uid, product, provider, resourceId, and the state overrides
+ */
+function subscriber(Manager, { uid, product, provider, resourceId, orderId, pending, trial, status }) {
+  const lastYearUNIX = Math.floor(Date.now() / 1000) - YEAR;
+  const nextMonthUNIX = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60);
+
+  return buildUser(Manager, {
+    auth: { uid: uid, email: `${uid}@example.com` },
+    roles: {},
+    subscription: {
+      product: { id: product.id, name: product.name || product.id },
+      status: status === undefined ? 'active' : status,
+      cancellation: { pending: pending === true },
+      expires: trial
+        ? { timestamp: new Date(nextMonthUNIX * 1000).toISOString(), timestampUNIX: nextMonthUNIX }
+        : { timestamp: new Date(nextMonthUNIX * 1000).toISOString(), timestampUNIX: nextMonthUNIX },
+      ...(trial
+        ? { trial: { claimed: true, expires: { timestamp: new Date(nextMonthUNIX * 1000).toISOString(), timestampUNIX: nextMonthUNIX } } }
+        : {}),
+      payment: {
+        provider: provider === undefined ? 'test' : provider,
+        resourceId: resourceId === undefined ? 'sub_test_winback_guard' : resourceId,
+        orderId: orderId === undefined ? null : orderId,
+        frequency: 'monthly',
+        startDate: { timestamp: new Date(lastYearUNIX * 1000).toISOString(), timestampUNIX: lastYearUNIX },
+      },
+    },
+  });
+}
+
+/**
+ * A direct call with the `omega-properties` header captured — the
+ * branchable half of a 4xx rides that header, so a test asserting a CODE reads
+ * it (plan.test.js's technique, for the same gate).
+ *
+ * @returns {Promise<{ sent: object, properties: object|null }>}
+ */
+async function acceptOfferReadingProperties(Manager, user, settings) {
+  const res = recordingResponse();
+  const headers = {};
+
+  res.header = (key, value) => {
+    headers[key] = value;
+    return res;
+  };
+  res.get = (key) => headers[key];
+
+  const req = { method: 'POST', headers: { 'content-type': 'application/json' }, query: {}, body: {} };
+  const ctx = Manager.RouteContext({ req, res }, { functionName: 'payments-winback' });
+
+  // The REAL analytics library, attached the way the middleware attaches it —
+  // every refusal returns before the route's accept event, but the success path
+  // records one, and a ctx built without it would fail on a line the wire never
+  // reaches this way. Not a stand-in: in a test environment the library itself
+  // skips the send.
+  ctx.analytics = Manager.Analytics({ ctx: ctx, uuid: user.auth.uid });
+
+  await handler({ ctx, Manager, user, settings: { confirmed: true, ...(settings || {}) }, libraries: Manager.libraries });
+
+  return {
+    sent: res.sent,
+    properties: headers['omega-properties'] ? JSON.parse(headers['omega-properties']) : null,
+  };
+}
+
+/** Run the thunk with the brand's save offer replaced, restoring it after. */
+async function withOffer(Manager, winbackConfig, fn) {
+  const payment = Manager.config.payment;
+  const original = payment.winback;
+
+  if (winbackConfig === null) delete payment.winback;
+  else payment.winback = winbackConfig;
+
+  try {
+    return await fn();
+  } finally {
+    if (original === undefined) delete payment.winback;
+    else payment.winback = original;
+  }
+}
+
+// The paid subscription product the offer is made against.
+function paidProduct(config, skip) {
+  const paid = (config.payment?.products || []).find((p) => p.id !== 'basic' && p.type === 'subscription' && p.prices?.monthly);
+
+  if (!paid) {
+    skip('No paid subscription product with a monthly price configured in this brand');
+  }
+
+  return paid;
+}
+
+module.exports = defineCases({
+  description: 'Payment winback endpoint: the save offer apply path',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    // ─── the wire guards ───
+
+    {
+      name: 'rejects-unauthenticated',
+      async run({ http, assert }) {
+        const response = await http.as('none').post('backend-manager/payments/winback', {
+          confirmed: true,
+        });
+
+        assert.isError(response, 401, 'Should reject unauthenticated request');
+      },
+    },
+
+    {
+      name: 'rejects-missing-confirmed',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/winback', {});
+
+        assert.isError(response, 400, 'Should reject a request that confirms nothing');
+      },
+    },
+
+    {
+      name: 'rejects-basic-user',
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('backend-manager/payments/winback', {
+          confirmed: true,
+        });
+
+        assert.isError(response, 400, 'Should reject a user with no paid subscription to keep');
+      },
+    },
+
+    // ─── the offer itself ───
+
+    {
+      name: 'resolves-the-brand-offer-with-the-framework-default',
+      async run({ Manager, assert }) {
+        // The 50% default has ONE home (@omega.js/config). A brand that
+        // configures nothing still has an offer, and it is that one.
+        await withOffer(Manager, null, async () => {
+          const offer = winback.resolveOffer(Manager.config);
+
+          assert.equal(offer.enabled, true, 'the offer is on by default');
+          assert.equal(offer.percent, 50, 'and it is 50% off');
+          assert.equal(offer.duration, 'once', 'for one cycle');
+
+          const discount = winback.toDiscount(offer);
+
+          assert.equal(discount.valid, true, 'it hands downstream a validate()-shaped discount');
+          assert.equal(discount.code, 'WINBACK50', 'named for what it is');
+          assert.equal(discount.amount, undefined, 'a percent offer declares no amount at all');
+        });
+      },
+    },
+
+    {
+      name: 'refuses-when-the-brand-disabled-the-offer',
+      async run({ Manager, assert, config, skip }) {
+        const product = paidProduct(config, skip);
+
+        await withOffer(Manager, { enabled: false }, async () => {
+          const user = subscriber(Manager, { uid: '_test-winback-disabled', product });
+          const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(sent.code, 400, 'Should refuse an offer the brand turned off');
+          assert.equal(
+            properties?.additional?.code,
+            'offer-disabled',
+            'the refusal carries a code the billing card can branch on',
+          );
+        });
+      },
+    },
+
+    {
+      name: 'refuses-an-unconfirmed-request',
+      async run({ Manager, assert, config, skip }) {
+        const product = paidProduct(config, skip);
+        const user = subscriber(Manager, { uid: '_test-winback-unconfirmed', product });
+        const { sent, properties } = await acceptOfferReadingProperties(Manager, user, { confirmed: false });
+
+        assert.equal(sent.code, 400, 'Should refuse a request that confirms nothing');
+        assert.equal(
+          properties?.additional?.code,
+          'confirmation-required',
+          'and says which refusal it was — the ONE code a retry can actually fix',
+        );
+      },
+    },
+
+    // ─── the per-subscription guards ───
+
+    {
+      name: 'refuses-a-trial',
+      async run({ Manager, assert, config, skip }) {
+        // A trial cancel ends access immediately (#267) and nothing has been
+        // paid, so there is no next cycle to discount. The billing card gates
+        // the same way, off the same rule.
+        const product = paidProduct(config, skip);
+        const user = subscriber(Manager, { uid: '_test-winback-trial', product, trial: true });
+
+        const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+        assert.equal(sent.code, 400, 'Should refuse a subscription still inside its free trial');
+        assert.equal(
+          properties?.additional?.code,
+          'trial-not-eligible',
+          'the refusal carries a code the billing card can branch on',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-a-scheduled-cancellation',
+      async run({ Manager, assert, config, skip }) {
+        const product = paidProduct(config, skip);
+        const user = subscriber(Manager, { uid: '_test-winback-pending', product, pending: true });
+
+        const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+        assert.equal(sent.code, 400, 'Should refuse when the cancellation is already scheduled');
+        assert.equal(
+          properties?.additional?.code,
+          'cancellation-pending',
+          'the refusal carries the same code the plan switch refuses that state with',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-a-suspended-subscription',
+      async run({ Manager, assert, config, skip }) {
+        const product = paidProduct(config, skip);
+        const user = subscriber(Manager, { uid: '_test-winback-suspended', product, status: 'suspended' });
+
+        const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+        assert.equal(sent.code, 400, 'Should refuse a subscription that is not active');
+        assert.equal(
+          properties?.additional?.code,
+          'no-active-subscription',
+          'the refusal carries a code the billing card can branch on',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-missing-payment-details',
+      async run({ Manager, assert, config, skip }) {
+        // An ADMIN-GRANTED or imported subscription is paid and active with no
+        // provider details on it at all, and the client pitches what it can
+        // read — so this refusal needs a code as much as the capability gate
+        // does ([#311]): without one, accepting shows an error toast and leaves
+        // the dialog armed for a retry that can never succeed. HALF the details
+        // is the same dead end, so each half is proven on its own.
+        const product = paidProduct(config, skip);
+        const halves = [
+          { what: 'provider', provider: null, resourceId: 'sub_test_winback_guard' },
+          { what: 'resourceId', provider: 'test', resourceId: null },
+          { what: 'both', provider: null, resourceId: null },
+        ];
+
+        for (const { what, provider, resourceId } of halves) {
+          const user = subscriber(Manager, { uid: `_test-winback-no-${what}`, product, provider, resourceId });
+          const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(sent.code, 400, `missing ${what}: Should refuse a subscription the route cannot reach a provider with`);
+          assert.equal(
+            properties?.additional?.code,
+            'missing-payment-details',
+            `missing ${what}: the refusal carries a code the billing card can branch on`,
+          );
+        }
+      },
+    },
+
+    {
+      name: 'refuses-an-unknown-provider',
+      async run({ Manager, assert, config, skip }) {
+        const product = paidProduct(config, skip);
+        const user = subscriber(Manager, { uid: '_test-winback-unknown', product, provider: 'not-a-provider' });
+
+        const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+        assert.equal(sent.code, 400, 'Should refuse a provider that does not exist');
+        assert.equal(
+          properties?.additional?.code,
+          'unknown-provider',
+          'the refusal carries a code the billing card can branch on',
+        );
+      },
+    },
+
+    {
+      name: 'refuses-when-the-claim-has-nowhere-to-be-recorded',
+      async run({ Manager, assert, config, skip }) {
+        // "Claimed once" is only true while there is a document to record the
+        // claim on. A subscription carrying no orderId (dashboard-created,
+        // imported, a metadata backfill that never landed) has none, so the
+        // offer is refused BEFORE dispatch rather than becoming takeable on
+        // every cancel dialog — each accept re-couponing the subscription.
+        const product = paidProduct(config, skip);
+        const user = subscriber(Manager, { uid: '_test-winback-no-order', product });
+        const provider = providerModule('test');
+        const applied = [];
+        const realApplyOffer = provider.applyOffer;
+
+        provider.applyOffer = async (options) => applied.push(options);
+
+        try {
+          const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(sent.code, 400, 'Should refuse an offer whose claim cannot be recorded');
+          assert.equal(
+            properties?.additional?.code,
+            'offer-not-claimable',
+            'the refusal carries a code the billing card can branch on',
+          );
+          assert.equal(applied.length, 0, 'and nothing reached the provider');
+        } finally {
+          provider.applyOffer = realApplyOffer;
+        }
+      },
+    },
+
+    {
+      name: 'refuses-a-second-claim-with-a-branchable-code',
+      async run({ Manager, assert, config, firestore, skip }) {
+        // The offer is claimed ONCE, and a past claimant who opens the cancel
+        // dialog again is pitched it anyway — the client reads the account, not
+        // the order doc. So the refusal carries a code the billing card can
+        // branch on ([#310]): without one, accepting shows an error toast and
+        // leaves the dialog armed for a retry that can never succeed.
+        const product = paidProduct(config, skip);
+        const orderId = '_test-winback-claimed-order';
+        const user = subscriber(Manager, { uid: '_test-winback-claimed', product, orderId });
+        const provider = providerModule('test');
+        const applied = [];
+        const realApplyOffer = provider.applyOffer;
+
+        // The first claim, written where the route records it
+        await firestore.set(`payments-orders/${orderId}`, {
+          requests: {
+            winback: {
+              discount: winback.toDiscount(winback.resolveOffer(Manager.config)),
+              date: { timestamp: new Date().toISOString(), timestampUNIX: Math.floor(Date.now() / 1000) },
+            },
+          },
+        }, { merge: true });
+
+        provider.applyOffer = async (options) => applied.push(options);
+
+        try {
+          const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(sent.code, 400, 'Should refuse an offer this subscription already took');
+          assert.equal(
+            properties?.additional?.code,
+            'offer-already-claimed',
+            'the refusal carries a code the billing card can branch on',
+          );
+          assert.equal(applied.length, 0, 'and the provider is never asked to discount twice');
+        } finally {
+          provider.applyOffer = realApplyOffer;
+          await firestore.delete(`payments-orders/${orderId}`);
+        }
+      },
+    },
+
+    // ─── the claim on the account ───
+
+    {
+      name: 'records-the-applied-discount-on-the-account',
+      async run({ Manager, assert, config, firestore, skip }) {
+        // The order doc is the offer's MEMORY — what a second claim is refused
+        // against — but the billing card reads the ACCOUNT, and a saving that
+        // vanishes on reload was never announced at all ([#325]). So the claim
+        // lands on both, and the account's copy has to survive the SAME resolver
+        // the client reads it through (which strips every key the schema does
+        // not name).
+        const product = paidProduct(config, skip);
+        const uid = '_test-winback-account';
+        const orderId = '_test-winback-account-order';
+        const user = subscriber(Manager, { uid, product, orderId });
+        const provider = providerModule('test');
+        const realApplyOffer = provider.applyOffer;
+        const applied = [];
+
+        provider.applyOffer = async (options) => applied.push(options);
+
+        try {
+          const { sent } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(sent.code, 200, 'Should apply the save offer');
+          assert.equal(applied.length, 1, 'and the provider discounted the live subscription once');
+
+          const userDoc = await firestore.get(`users/${uid}`);
+          const discount = userDoc?.subscription?.discount;
+
+          assert.equal(discount?.valid, true, 'The account carries the discount that was applied');
+          assert.equal(discount.code, sent.body.discount.code, 'the same one the route answered with');
+          assert.equal(discount.duration, sent.body.discount.duration, 'for the same duration');
+          assert.equal(
+            discount.percent > 0 || discount.amount > 0,
+            true,
+            'and it is worth something — both shapes are written, so a merge can never leave half of an older discount behind',
+          );
+
+          // The source is the whole reason this is safe to read as a CLAIM: a
+          // checkout code sets the same node, and a winback pitch suppressed by
+          // someone else's promo is an offer silently withheld.
+          assert.equal(discount.source, 'winback', 'and it says which system applied it');
+
+          // And WHICH subscription it was applied to ([#333]). Nothing cleared
+          // this node, so a customer who churned and resubscribed carried the
+          // old claim into the new subscription and was never pitched the save
+          // again. The stamp is what the webhook pipeline compares the incoming
+          // subscription against, so the claim can end with the subscription it
+          // was made on.
+          assert.equal(
+            discount.resourceId,
+            user.subscription.payment.resourceId,
+            'stamped with the subscription it discounted',
+          );
+
+          // Through the resolver, exactly as the client reads it
+          const resolved = Manager.User(userDoc).properties.subscription.discount;
+
+          assert.equal(resolved.valid, true, 'The discount survives account resolution');
+          assert.equal(resolved.source, 'winback', 'source and all');
+          assert.equal(resolved.resourceId, user.subscription.payment.resourceId, 'stamp and all');
+
+          // The claim is still recorded where the refusal reads it
+          const orderDoc = await firestore.get(`payments-orders/${orderId}`);
+          assert.equal(orderDoc.requests.winback.discount.code, discount.code, 'The order doc keeps the offer memory');
+
+          // A second accept changes NOTHING: it is refused before dispatch, and
+          // the account's discount is not doubled, re-stamped or cleared.
+          const { sent: second, properties } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(second.code, 400, 'Should refuse a second claim');
+          assert.equal(properties?.additional?.code, 'offer-already-claimed', 'with the branchable code');
+          assert.equal(applied.length, 1, 'the provider is never asked twice');
+
+          const after = (await firestore.get(`users/${uid}`))?.subscription?.discount;
+
+          assert.deepEqual(after, discount, 'and the account carries exactly the one discount it already had');
+        } finally {
+          provider.applyOffer = realApplyOffer;
+          await firestore.delete(`payments-orders/${orderId}`);
+          await firestore.delete(`users/${uid}`);
+        }
+      },
+    },
+
+    // ─── the provider capability gate ───
+
+    {
+      name: 'declares-which-providers-can-apply-the-offer',
+      async run({ assert }) {
+        // The export IS the declaration. Stripe rides the coupon plumbing the
+        // checkout already uses; the test provider mirrors it. PayPal has no
+        // discount object at all, and Chargebee has coupons but no way to reach
+        // a LIVE subscription with one through plumbing that exists here — both
+        // say so by exporting nothing.
+        assert.equal(typeof providerModule('stripe').applyOffer, 'function', 'Stripe applies the offer');
+        assert.equal(typeof providerModule('test').applyOffer, 'function', 'the test provider applies the offer');
+        assert.equal(typeof providerModule('paypal').applyOffer, 'undefined', 'PayPal declares it cannot');
+        assert.equal(typeof providerModule('chargebee').applyOffer, 'undefined', 'Chargebee declares it cannot');
+      },
+    },
+
+    {
+      name: 'refuses-a-provider-that-cannot-discount-with-a-branchable-code',
+      async run({ Manager, assert, config, skip }) {
+        const product = paidProduct(config, skip);
+
+        for (const provider of ['paypal', 'chargebee']) {
+          const user = subscriber(Manager, { uid: `_test-winback-${provider}`, product, provider, resourceId: `sub_${provider}_winback` });
+          const { sent, properties } = await acceptOfferReadingProperties(Manager, user);
+
+          assert.equal(sent.code, 400, `${provider}: Should refuse before dispatch`);
+          assert.equal(
+            properties?.additional?.code,
+            'not-supported-by-provider',
+            `${provider}: the refusal carries the code the billing card branches on`,
+          );
+        }
+      },
+    },
+
+    // ─── the happy path, over the wire ───
+
+    {
+      name: 'applies-the-offer-and-claims-it-once',
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
+        const uid = accounts['route-winback-success'].uid;
+        const product = paidProduct(config, skip);
+
+        // Step 1: a real paid subscription on the test provider
+        const intentResponse = await http.as('route-winback-success').post('backend-manager/payments/intent', {
+          provider: 'test',
+          productId: product.id,
+          frequency: 'monthly',
+        });
+
+        assert.isSuccess(intentResponse, 'Intent should succeed');
+
+        // Step 2: the auto-webhook activates it
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.payment?.provider === 'test'
+            && userDoc?.subscription?.payment?.resourceId
+            && userDoc?.subscription?.status === 'active';
+        }, 15000, 500);
+
+        // Step 3: the customer starts cancelling and takes the offer instead
+        const response = await http.as('route-winback-success').post('backend-manager/payments/winback', {
+          confirmed: true,
+        });
+
+        assert.isSuccess(response, 'Should apply the save offer');
+        assert.equal(response.data.success, true, 'Should return success: true');
+        assert.equal(response.data.discount.valid, true, 'Should answer with the discount it applied');
+
+        // Step 4: the subscription is UNCHANGED — the cancel never happened and
+        // a coupon does not move the plan, the cadence or the renewal
+        const userDoc = await firestore.get(`users/${uid}`);
+        assert.equal(userDoc.subscription.status, 'active', 'The subscription is still active');
+        assert.equal(userDoc.subscription.cancellation?.pending, false, 'and nothing is scheduled to cancel');
+
+        // Step 5: the claim is on the order doc — the offer's whole memory
+        const orderId = userDoc.subscription.payment.orderId;
+        const orderDoc = await firestore.get(`payments-orders/${orderId}`);
+
+        assert.equal(orderDoc.requests.winback.discount.code, response.data.discount.code, 'The claim records the discount applied');
+        assert.ok(orderDoc.requests.winback.date.timestampUNIX > 0, 'and when it was claimed');
+
+        // …and on the ACCOUNT, which is what the billing card reads ([#325])
+        assert.equal(userDoc.subscription.discount.code, response.data.discount.code, 'The account carries the applied discount');
+        assert.equal(userDoc.subscription.discount.source, 'winback', 'stamped with the system that applied it');
+
+        // Step 6: it is claimed ONCE — an offer takeable on every cancel dialog
+        // is a permanent discount nobody agreed to
+        const second = await http.as('route-winback-success').post('backend-manager/payments/winback', {
+          confirmed: true,
+        });
+
+        assert.isError(second, 400, 'Should refuse a second claim on the same subscription');
+      },
+    },
+  ],
+});

package/test/routes/test/authenticate.test.js

@@ -0,0 +1,79 @@
+/**
+ * Test: test/authenticate
+ * Tests different authentication methods using new RESTful API
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Authentication methods (RESTful)',
+  type: 'group',
+  tests: [
+    // Test 1: Unauthenticated request
+    {
+      name: 'no-auth',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/test/authenticate');
+
+        assert.isSuccess(response, 'Should succeed without auth');
+        assert.equal(response.data.user.authenticated, false, 'User should not be authenticated');
+      },
+    },
+
+    // Test 2: Private key authentication
+    {
+      name: 'private-key',
+      auth: 'basic',
+      async run({ http, assert, accounts }) {
+        const response = await http.as('basic').get('backend-manager/test/authenticate');
+
+        assert.isSuccess(response, 'Should succeed with privateKey');
+        assert.equal(response.data.user.authenticated, true, 'User should be authenticated');
+        assert.equal(response.data.user.auth.uid, accounts.basic.uid, 'UID should match');
+      },
+    },
+
+    // Test 3: Invalid private key
+    {
+      name: 'invalid-private-key',
+      auth: 'none',
+      async run({ http, assert }) {
+        const response = await http.withPrivateKey('invalid-key-12345').get('backend-manager/test/authenticate');
+
+        assert.isSuccess(response, 'Should succeed but not authenticate');
+        assert.equal(response.data.user.authenticated, false, 'Invalid key should not authenticate');
+      },
+    },
+
+    // Test 4: Admin (admin key) authentication
+    {
+      name: 'admin-key-header',
+      auth: 'admin',
+      async run({ http, assert }) {
+        const response = await http.as('admin').get('backend-manager/test/authenticate');
+
+        assert.isSuccess(response, 'Should succeed with admin key');
+        assert.equal(response.data.user.authenticated, true, 'User should be authenticated');
+        assert.equal(response.data.user.roles?.admin, true, 'Should have admin role');
+      },
+    },
+
+    // Test 5: The RETIRED wire — the real admin key as a request parameter
+    // must NOT grant admin (only the omega-admin-key header does). Query and
+    // body merge into the SAME request.data object authenticate() used to
+    // read, so the query variant kills both lanes (the route is GET-only).
+    {
+      name: 'legacy-key-field-dead',
+      auth: 'none',
+      async run({ http, assert, config }) {
+        const viaQuery = await http.as('none').get('backend-manager/test/authenticate', {
+          backendManagerKey: config.adminKey,
+        });
+
+        assert.isSuccess(viaQuery, 'Request itself should succeed');
+        assert.equal(viaQuery.data.user.authenticated, false, 'Legacy backendManagerKey param must NOT authenticate');
+        assert.equal(viaQuery.data.user.roles?.admin ?? false, false, 'Legacy backendManagerKey param must NOT grant admin');
+      },
+    },
+  ],
+});