@omega.js/backend 0.1.0

package/test/routes/payments/_route-harness.js

@@ -0,0 +1,145 @@
+/**
+ * Shared harness for the payments-route suites that call a handler DIRECTLY.
+ *
+ * The technique, for the routes that need a `user`: a real ctx from
+ * Manager.RouteContext(), a real user built the
+ * way `ctx.authenticate()` builds one (Manager.User(doc).properties, then the
+ * `authenticated` flag it sets outside the schema), and only `res` as a
+ * stand-in — the external sink respond() writes to, per the no-mock doctrine.
+ *
+ * Direct calls are the honest layer for these cases: they let one test choose a
+ * provider and a subscription shape without minting a persona per permutation,
+ * and they can run two handlers CONCURRENTLY in one process, which is the only
+ * way to prove a same-instant duplicate delivery.
+ *
+ * `_`-prefixed, so the runner never discovers it as a suite.
+ */
+
+// A minimal express-shaped response recorder — the one external sink respond() writes to.
+function recordingResponse() {
+  const sent = { code: null, body: null, headers: {} };
+
+  return {
+    sent,
+    headersSent: false,
+    status(code) {
+      sent.code = code;
+      return this;
+    },
+    set(key, value) {
+      sent.headers[key] = value;
+      return this;
+    },
+    json(payload) {
+      sent.body = payload;
+      return this;
+    },
+    send(payload) {
+      sent.body = payload;
+      return this;
+    },
+  };
+}
+
+/**
+ * Build a resolved user exactly the way authenticate() does.
+ *
+ * @param {object} Manager - The @omega.js/backend Manager
+ * @param {object} doc - The user document shape (auth, roles, subscription, …)
+ * @returns {object} The resolved user a route handler receives
+ */
+function buildUser(Manager, doc) {
+  const user = Manager.User(doc).properties;
+
+  // authenticate() sets this OUTSIDE the account schema — mirror it exactly
+  user.authenticated = doc.authenticated !== false;
+
+  return user;
+}
+
+/**
+ * Run the thunk with `vars` applied to process.env (null deletes), restoring
+ * every key afterwards. The route/provider code reads the environment live on
+ * every call, so swapping it is the real switch.
+ *
+ * @param {object} vars - { NAME: 'value' | null }
+ * @param {Function} fn - The thunk
+ */
+async function withEnvironment(vars, fn) {
+  const original = {};
+
+  Object.entries(vars).forEach(([key, value]) => {
+    original[key] = process.env[key];
+
+    if (value === null) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  });
+
+  try {
+    return await fn();
+  } finally {
+    Object.entries(original).forEach(([key, value]) => {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    });
+  }
+}
+
+/**
+ * The environment overrides that make getEnvironment() resolve to production.
+ * Testing wins over everything else, so it has to come off too.
+ */
+const PRODUCTION_ENVIRONMENT = {
+  OMEGA_TEST_MODE: null,
+  TERM_PROGRAM: null,
+  FUNCTIONS_EMULATOR: null,
+  ENVIRONMENT: 'production',
+};
+
+/**
+ * Call a route handler directly against a real ctx.
+ *
+ * @param {object} options
+ * @param {object} options.Manager - The @omega.js/backend Manager
+ * @param {Function} options.handler - The route handler module
+ * @param {string} options.functionName - The ctx's function-name tag
+ * @param {object} [options.user] - A user built by buildUser()
+ * @param {object} [options.settings] - The resolved request settings
+ * @param {object} [options.req] - Request overrides (query, headers, body, rawBody)
+ * @returns {Promise<object>} What the handler sent: { code, body, headers }
+ */
+async function callHandler({ Manager, handler, functionName, user, settings, req }) {
+  const res = recordingResponse();
+  const request = {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    query: {},
+    body: {},
+    ...(req || {}),
+  };
+  const ctx = Manager.RouteContext({ req: request, res }, { functionName });
+
+  await handler({
+    ctx,
+    Manager,
+    user,
+    settings,
+    libraries: Manager.libraries,
+  });
+
+  return res.sent;
+}
+
+module.exports = {
+  recordingResponse,
+  buildUser,
+  withEnvironment,
+  callHandler,
+  PRODUCTION_ENVIRONMENT,
+};

package/test/routes/payments/cancel-provider-errors.test.js

@@ -0,0 +1,227 @@
+/**
+ * Test: POST /payments/cancel — only "already gone" force-cancels
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * A suspended subscriber whose provider record no longer exists gets their
+ * subscription reset directly, so they can re-subscribe. That write used to fire
+ * on ANY provider error: a network blip, an expired key, a rate limit — each
+ * one silently downgraded a paying user to Basic and reported success. Now the
+ * force-cancel answers to one classification only, and everything else returns
+ * the failure with NOTHING written.
+ *
+ * Two layers, each proving what it can:
+ *  - the classifier against REAL SDK error objects (the Stripe SDK's own error
+ *    classes; the exact strings the PayPal and Chargebee clients in this repo
+ *    throw) — the only place a live 404 can be represented offline;
+ *  - the route against a genuine transient failure: a `stripe` subscription with
+ *    no STRIPE_SECRET_KEY configured, which is exactly the misconfiguration that
+ *    used to fake a cancellation.
+ *
+ * Run: npx omega test backend:routes/payments/cancel-provider-errors
+ */
+const Stripe = require('stripe');
+const { buildUser, callHandler, withEnvironment } = require('./_route-harness.js');
+
+const handler = require('../../../dist/manager/routes/payments/cancel/post.js');
+const isAlreadyGone = require('../../../dist/manager/libraries/payment/provider-errors.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// A subscriber on a real provider, old enough to clear the age guard.
+function subscriber(Manager, { uid, status, provider }) {
+  const lastYearUNIX = Math.floor(Date.now() / 1000) - (365 * 24 * 60 * 60);
+
+  return buildUser(Manager, {
+    auth: { uid: uid, email: `${uid}@example.com` },
+    roles: {},
+    subscription: {
+      product: { id: 'premium', name: 'Premium' },
+      status: status,
+      cancellation: { pending: false },
+      payment: {
+        provider: provider,
+        resourceId: 'sub_test_provider_error',
+        startDate: { timestamp: new Date(lastYearUNIX * 1000).toISOString(), timestampUNIX: lastYearUNIX },
+      },
+    },
+  });
+}
+
+// Cancel with Stripe unconfigured — StripeLib.init() throws, the transient failure
+// closest to a real outage that can be produced offline.
+function cancelWithoutStripeKey(Manager, user) {
+  return withEnvironment({ STRIPE_SECRET_KEY: null }, () => callHandler({
+    Manager,
+    handler,
+    functionName: 'payments-cancel',
+    user,
+    settings: { confirmed: true, skipGuards: false, reason: null, feedback: null },
+  }));
+}
+
+module.exports = defineCases({
+  description: 'Payment cancel endpoint: provider error classification',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    // ─── the route ───
+
+    {
+      name: 'a-transient-failure-on-a-suspended-subscription-writes-nothing',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const uid = '_test-cancel-transient-suspended';
+        const user = subscriber(Manager, { uid, status: 'suspended', provider: 'stripe' });
+
+        assert.equal(await firestore.exists(`users/${uid}`), false, 'the case starts with no user doc to overwrite');
+
+        const sent = await cancelWithoutStripeKey(Manager, user);
+
+        assert.equal(sent.code, 500, `A transient failure must reach the caller, got ${sent.code}: ${JSON.stringify(sent.body)}`);
+        assert.equal(await firestore.exists(`users/${uid}`), false, 'A transient failure must never write a cancelled subscription');
+      },
+    },
+
+    {
+      name: 'a-transient-failure-on-an-active-subscription-writes-nothing',
+      auth: 'none',
+      async run({ assert, Manager, firestore }) {
+        const uid = '_test-cancel-transient-active';
+        const user = subscriber(Manager, { uid, status: 'active', provider: 'stripe' });
+
+        const sent = await cancelWithoutStripeKey(Manager, user);
+
+        assert.equal(sent.code, 500, `A transient failure must reach the caller, got ${sent.code}: ${JSON.stringify(sent.body)}`);
+        assert.equal(await firestore.exists(`users/${uid}`), false, 'A transient failure must never write a cancelled subscription');
+      },
+    },
+
+    {
+      name: 'the-failure-response-carries-no-sdk-detail',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const user = subscriber(Manager, { uid: '_test-cancel-neutral-message', status: 'active', provider: 'stripe' });
+
+        const sent = await cancelWithoutStripeKey(Manager, user);
+
+        assert.equal(sent.code, 500, `Expected the provider failure, got ${sent.code}`);
+        assert.ok(!/STRIPE_SECRET_KEY/.test(`${sent.body}`), `The SDK detail must stay in the logs, got: ${sent.body}`);
+        assert.match(`${sent.body}`, /could not cancel your subscription/i, 'The client should get the neutral message');
+      },
+    },
+
+    // ─── the classifier: already gone ───
+
+    {
+      name: 'classifies-a-stripe-missing-resource-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        // The SDK's own error class, generated from the payload Stripe returns
+        // for a subscription that does not exist.
+        const error = Stripe.errors.StripeInvalidRequestError.generate({
+          type: 'invalid_request_error',
+          code: 'resource_missing',
+          statusCode: 404,
+          message: "No such subscription: 'sub_test_provider_error'",
+        });
+
+        assert.equal(isAlreadyGone(error), true, 'Stripe resource_missing means the subscription is gone');
+      },
+    },
+
+    {
+      name: 'classifies-a-chargebee-404-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        // The shape libraries/payment/providers/chargebee.js throws
+        const error = new Error('Chargebee API 404: Sorry, we couldn\'t find that resource');
+        error.statusCode = 404;
+
+        assert.equal(isAlreadyGone(error), true, 'A Chargebee 404 means the subscription is gone');
+      },
+    },
+
+    {
+      name: 'classifies-a-paypal-404-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        // The shape libraries/payment/providers/paypal.js throws — status in the message only
+        const error = new Error('PayPal API 404: The specified resource does not exist.');
+
+        assert.equal(isAlreadyGone(error), true, 'A PayPal 404 means the subscription is gone');
+      },
+    },
+
+    // ─── the classifier: everything else ───
+
+    {
+      name: 'does-not-classify-a-stripe-outage-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        const error = Stripe.errors.StripeAPIError.generate({
+          type: 'api_error',
+          statusCode: 503,
+          message: 'Stripe is temporarily unavailable',
+        });
+
+        assert.equal(isAlreadyGone(error), false, 'A Stripe outage is transient, not gone');
+      },
+    },
+
+    {
+      name: 'does-not-classify-a-stripe-auth-failure-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        const error = Stripe.errors.StripeAuthenticationError.generate({
+          type: 'invalid_request_error',
+          statusCode: 401,
+          message: 'Invalid API Key provided',
+        });
+
+        assert.equal(isAlreadyGone(error), false, 'A rotated key is transient, not gone');
+      },
+    },
+
+    {
+      name: 'does-not-classify-a-paypal-422-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        // PayPal answers 422 for an already-cancelled subscription too, but the
+        // client surfaces no issue code — so it stays in the transient bucket
+        // rather than becoming a guess that writes.
+        const error = new Error('PayPal API 422: The requested action could not be performed, semantically incorrect, or failed business validation.');
+
+        assert.equal(isAlreadyGone(error), false, 'An unreadable PayPal 422 must not force a cancellation');
+      },
+    },
+
+    {
+      name: 'does-not-classify-a-paypal-outage-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        const error = new Error('PayPal API 503: Service Unavailable');
+
+        assert.equal(isAlreadyGone(error), false, 'A PayPal outage is transient, not gone');
+      },
+    },
+
+    {
+      name: 'does-not-classify-a-configuration-error-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        const error = new Error('STRIPE_SECRET_KEY environment variable is required');
+
+        assert.equal(isAlreadyGone(error), false, 'A misconfiguration is not a missing subscription');
+      },
+    },
+
+    {
+      name: 'does-not-classify-an-unknown-error-as-gone',
+      auth: 'none',
+      async run({ assert }) {
+        assert.equal(isAlreadyGone(new Error('socket hang up')), false, 'An unrecognized error must never be the one that writes');
+        assert.equal(isAlreadyGone(undefined), false, 'A missing error must never be the one that writes');
+      },
+    },
+  ],
+});

package/test/routes/payments/cancel-skip-guards.test.js

@@ -0,0 +1,126 @@
+/**
+ * Test: POST /payments/cancel — `skipGuards` is a privileged request
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * `skipGuards` arrives in the request BODY, so any client can send it. It waives
+ * the 24-hour subscription-age guard, which exists to stop a cancellation racing
+ * a checkout that is still settling — a guard a caller must not be able to waive
+ * for itself. The route honors it for an admin, or anywhere outside a real
+ * deployment (the suites and the dev palette cancel seeded subscriptions minutes
+ * old), and ignores it with a warning otherwise.
+ *
+ * The whole matrix therefore has to be driven in a PRODUCTION environment: in a
+ * testing run every caller is permitted by design, so a testing-run assertion
+ * would prove nothing. getEnvironment() reads the env live, so swapping it is
+ * the real switch — the same technique webhook-test-provider.test.js uses.
+ *
+ * Both verdicts land as a 400 with DIFFERENT text: the age rejection means the
+ * guard ran, and "Unknown provider" means the request got past it (the persona
+ * carries a deliberately unknown provider so nothing external is ever reached).
+ *
+ * Run: npx omega test backend:routes/payments/cancel-skip-guards
+ */
+const { buildUser, callHandler, withEnvironment, PRODUCTION_ENVIRONMENT } = require('./_route-harness.js');
+
+const handler = require('../../../dist/manager/routes/payments/cancel/post.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// A paid subscriber whose subscription is minutes old — the shape the age guard exists for.
+function youngSubscriber(Manager, { uid, admin }) {
+  const nowUNIX = Math.floor(Date.now() / 1000);
+
+  return buildUser(Manager, {
+    auth: { uid: uid, email: `${uid}@example.com` },
+    roles: { admin: !!admin },
+    subscription: {
+      product: { id: 'premium', name: 'Premium' },
+      status: 'active',
+      cancellation: { pending: false },
+      payment: {
+        // Deliberately unknown: getting PAST the age guard must not reach a real provider
+        provider: 'unknown-provider',
+        resourceId: 'sub_test_skip_guards',
+        startDate: { timestamp: new Date(nowUNIX * 1000).toISOString(), timestampUNIX: nowUNIX },
+      },
+    },
+  });
+}
+
+function cancel(Manager, user) {
+  return callHandler({
+    Manager,
+    handler,
+    functionName: 'payments-cancel',
+    user,
+    settings: { confirmed: true, skipGuards: true, reason: null, feedback: null },
+  });
+}
+
+module.exports = defineCases({
+  description: 'Payment cancel endpoint: skipGuards is privileged',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'skip-guards-is-ignored-for-an-ordinary-caller',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const user = youngSubscriber(Manager, { uid: '_test-skip-guards-plain', admin: false });
+
+        const sent = await withEnvironment(PRODUCTION_ENVIRONMENT, () => cancel(Manager, user));
+
+        assert.equal(sent.code, 400, `An ordinary caller's skipGuards must not waive the age guard, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /still being set up/i, 'The age guard should be the rejection');
+      },
+    },
+
+    {
+      name: 'skip-guards-is-honored-for-an-admin',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const user = youngSubscriber(Manager, { uid: '_test-skip-guards-admin', admin: true });
+
+        const sent = await withEnvironment(PRODUCTION_ENVIRONMENT, () => cancel(Manager, user));
+
+        assert.equal(sent.code, 400, `An admin should reach the provider lookup, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /Unknown provider/i, 'An admin should get PAST the age guard');
+      },
+    },
+
+    {
+      name: 'skip-guards-is-honored-outside-production',
+      auth: 'none',
+      async run({ assert, Manager, ctx }) {
+        assert.equal(ctx.isProduction(), false, 'the suite must run outside production for this test');
+
+        const user = youngSubscriber(Manager, { uid: '_test-skip-guards-nonprod', admin: false });
+
+        const sent = await cancel(Manager, user);
+
+        assert.equal(sent.code, 400, `A non-production run should reach the provider lookup, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /Unknown provider/i, 'A non-production run should get PAST the age guard');
+      },
+    },
+
+    {
+      name: 'the-age-guard-still-runs-without-skip-guards',
+      auth: 'none',
+      async run({ assert, Manager }) {
+        const user = youngSubscriber(Manager, { uid: '_test-skip-guards-absent', admin: true });
+
+        // An admin who never asked to bypass gets the guard like anybody else
+        const sent = await callHandler({
+          Manager,
+          handler,
+          functionName: 'payments-cancel',
+          user,
+          settings: { confirmed: true, skipGuards: false, reason: null, feedback: null },
+        });
+
+        assert.equal(sent.code, 400, `The age guard should reject, got ${sent.code}: ${sent.body}`);
+        assert.match(`${sent.body}`, /still being set up/i, 'The age guard should be the rejection');
+      },
+    },
+  ],
+});