@omega.js/backend 0.1.0

package/test/events/payments/webhook-refund-without-order.test.js

@@ -0,0 +1,170 @@
+/**
+ * Test: a one-time refund with no order behind it is refused, not minted
+ *
+ * When PAYMENT.CAPTURE.REFUNDED arrived and payments-orders/{orderId} did not
+ * exist, the refund event was read as a fresh purchase definition: the order was
+ * created with `unified.status: 'completed'` and the REFUND's id as the resource,
+ * so a reversal was booked as revenue while the transition trail said
+ * one-time/purchase-refunded ([#335]). The pipeline now refuses and stamps the
+ * refusal on the event's own doc instead.
+ *
+ * The same file covers the fetched-resource log line ([#347]): the live sighting
+ * was a v1 sale refund, whose resource spells its state `state`, not `status` —
+ * the same lane, one payload away.
+ *
+ * Plain-node control-flow test (no emulator, no network): the real trigger module
+ * runs against the shared in-memory Firestore stand-in (_webhook-harness.js). The
+ * emulator would need a persona, a purchase and a deliberately missing order write
+ * per permutation to reach the same state; the stand-in seeds it exactly.
+ */
+const assert = require('node:assert');
+const { runTrigger } = require('./_webhook-harness.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+const UID = '_test-refund-refusal-uid';
+const ORDER_ID = '2402-2402-2402';
+const REFUND_ID = '_test-refund-id';
+const CAPTURE_ID = '_test-capture-id';
+const CHECKOUT_ID = '_test-checkout-id';
+const EVENT_ID = '_test-refund-refusal-evt';
+
+/**
+ * The refund resource the provider answers with: a bare charge that moved the
+ * money back, naming no product and no price, linking `up` at the capture it
+ * reversed the way PayPal's does.
+ */
+function refundPayload({ id = REFUND_ID, object = 'charge', status = 'complete' } = {}) {
+  return {
+    id: id,
+    object: object,
+    status: status,
+    amount_refunded: 999,
+    currency: 'usd',
+    metadata: { uid: UID, orderId: ORDER_ID },
+    links: [
+      { rel: 'self', href: `https://api.test.invalid/v2/payments/refunds/${id}` },
+      { rel: 'up', href: `https://api.test.invalid/v2/payments/captures/${CAPTURE_ID}` },
+    ],
+  };
+}
+
+/** The order a completed purchase already wrote, for the path that HAS one */
+function existingOrder() {
+  return {
+    id: ORDER_ID,
+    type: 'one-time',
+    owner: UID,
+    productId: 'premium',
+    provider: 'test',
+    resourceId: CHECKOUT_ID,
+    unified: {
+      product: { id: 'premium', name: 'Premium' },
+      status: 'completed',
+      payment: {
+        provider: 'test',
+        orderId: ORDER_ID,
+        resourceId: CHECKOUT_ID,
+        price: 9.99,
+      },
+    },
+    metadata: {
+      created: { timestamp: '2026-08-01T00:00:00.000Z', timestampUNIX: 1785196800 },
+      updated: { timestamp: '2026-08-01T00:00:00.000Z', timestampUNIX: 1785196800 },
+    },
+  };
+}
+
+/** The refund event this suite is about, with only the starting state left to choose */
+function runRefund({ seed = {}, payload = refundPayload(), eventType = 'charge.refunded', resourceType = 'charge' } = {}) {
+  return runTrigger({
+    uid: UID,
+    orderId: ORDER_ID,
+    resourceId: payload.id,
+    eventId: EVENT_ID,
+    eventType: eventType,
+    resourceType: resourceType,
+    category: 'one-time',
+    payload: payload,
+    seed: seed,
+  });
+}
+
+module.exports = defineCases({
+  description: 'A one-time refund with no order behind it is refused on its own event doc, never minted as a purchase',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'a refund with no order mints NO order and no intent',
+
+      async run() {
+        const { store } = await runRefund();
+
+        assert.ok(!store.get(`payments-orders/${ORDER_ID}`), 'a refund must never define a purchase');
+        assert.ok(!store.get(`payments-intents/${ORDER_ID}`), 'nothing completed, so no intent is closed out');
+      },
+    },
+
+    {
+      name: 'the refusal is stamped on the event doc with the capture it reversed',
+
+      async run() {
+        const { store } = await runRefund();
+        const event = store.get(`payments-webhooks/${EVENT_ID}`);
+
+        assert.ok(event.refusal, 'the event doc carries the refusal durably');
+        assert.equal(event.refusal.reason, 'refund-without-order', 'the stamp names what is wrong');
+        assert.equal(event.refusal.captureId, CAPTURE_ID, 'the capture from links.up — the pointer back to the purchase');
+        assert.equal(event.owner, UID, 'the owner it resolved to');
+        assert.equal(event.orderId, ORDER_ID, 'the order the refund named, which does not exist');
+        assert.equal(event.raw?.data?.object?.id, REFUND_ID, 'the refund payload as delivered is already on the doc');
+      },
+    },
+
+    {
+      name: 'the refusal is loud and the trail agrees with the record',
+
+      async run() {
+        const { store, logs } = await runRefund();
+        const output = logs.join('\n');
+
+        assert.match(output, /REFUND WITHOUT ORDER/, 'the refusal is loud');
+        assert.ok(!output.includes('Transition detected: one-time/purchase-refunded'), 'no purchase was refunded, so the trail must not say one was');
+        assert.equal(store.get(`payments-webhooks/${EVENT_ID}`)?.transition, null, 'the webhook records no transition');
+        assert.equal(store.get(`payments-webhooks/${EVENT_ID}`)?.status, 'completed', 'the event reached a decision — it is not a retryable failure');
+      },
+    },
+
+    {
+      name: 'a refund WITH an order still merges onto the purchase it reversed',
+
+      async run() {
+        const { store } = await runRefund({ seed: { [`payments-orders/${ORDER_ID}`]: existingOrder() } });
+        const order = store.get(`payments-orders/${ORDER_ID}`);
+
+        assert.ok(!store.get(`payments-webhooks/${EVENT_ID}`)?.refusal, 'a refund with a purchase behind it is refused nothing');
+        assert.equal(order.unified.status, 'refunded', 'the purchase is marked refunded');
+        assert.equal(order.unified.product.id, 'premium', 'the purchase keeps its product');
+        assert.equal(order.resourceId, CHECKOUT_ID, 'the purchase keeps the resource it was bought through');
+        assert.equal(order.unified.payment.refund.amount, '9.99', 'the refund is recorded on the purchase');
+      },
+    },
+
+    {
+      name: 'the fetched-resource log reads the v1 `state` spelling, not status=unknown',
+
+      async run() {
+        // A v1 sale resource carries no `status` key at all — its state is `state`
+        const payload = refundPayload({ object: 'sale' });
+        delete payload.status;
+        payload.state = 'refunded';
+
+        const { logs } = await runRefund({ eventType: 'PAYMENT.SALE.REFUNDED', resourceType: 'sale', payload: payload });
+        const output = logs.join('\n');
+
+        assert.match(output, /Fetched resource: type=sale, id=_test-refund-id, status=refunded, source=provider API/, 'a v1 sale fetch logs its real state');
+      },
+    },
+  ],
+});

package/test/events/payments/webhook-refusal-reporting.test.js

@@ -0,0 +1,194 @@
+/**
+ * Test: a REFUSED webhook event reports itself to Sentry, at warning level
+ *
+ * A refusal is an attack signal — a forged owner, a resource the provider never
+ * had, a refund id pointing at someone else's record — and the whole family used
+ * to live in Cloud Logging and a Firestore stamp, which are only ever read by
+ * someone already looking. Ian's call (2026-08-24, closing #506's open question):
+ * it surfaces on the dashboard ([#550](https://github.com/Omega-JS-Stack/omega/issues/550)).
+ *
+ * The report rides the SHARED refusal path (`acknowledgeRefusal`), not the
+ * individual catches, so every terminal decision taken before processing reports
+ * exactly once and a new refusal reason inherits it for free. WARNING, not an
+ * exception: nothing failed — the pipeline decided, correctly.
+ *
+ * The monitoring contract is the other half ([docs/shared/monitoring.md]):
+ * `libraries.sentry` is the backend's ONE capture handle and is null whenever no
+ * DSN is configured, so an unconfigured brand reports nothing, and only IDS ride
+ * — the refusal stamp's own fields plus the event's, never the payload.
+ *
+ * Stripe is the provider under test for both refusals: `provider=test` is a
+ * pass-through of Stripe's shape, so neither a mismatch nor a not-found lookup
+ * can arise there. The SDK is the ONE thing stubbed — everything inward (the
+ * library, the trigger, the writes) runs for real.
+ *
+ * Plain-node control-flow test (no emulator, no network): the real trigger module
+ * runs against the shared in-memory Firestore stand-in (_webhook-harness.js),
+ * whose Sentry stand-in records what a real transport would have sent.
+ *
+ * Run: npx omega test backend:events/payments/webhook-refusal-reporting
+ */
+const assert = require('node:assert');
+const { runTrigger, subscriptionPayload } = require('./_webhook-harness.js');
+const Stripe = require('../../../dist/manager/libraries/payment/providers/stripe.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// The subscriber Stripe's own record names, and the uid the forged event claims
+const OWNER_UID = '_test-refusal-report-owner';
+const FORGED_UID = '_test-refusal-report-forged';
+
+const ORDER_ID = '5500-5500-5500';
+const RESOURCE_ID = 'sub_test_refusal_report';
+const EVENT_ID = '_test-refusal-report-evt';
+const EVENT_TYPE = 'customer.subscription.updated';
+
+/** Run fn with the library's SDK replaced by `sdk`, restored afterwards */
+async function withStripeSdk(sdk, fn) {
+  const realInit = Stripe.init;
+
+  Stripe.init = () => sdk;
+
+  try {
+    return await fn();
+  } finally {
+    Stripe.init = realInit;
+  }
+}
+
+/** Stripe's own "that object does not exist" shape, as the SDK throws it */
+function resourceMissing() {
+  const error = new Error(`No such subscription: '${RESOURCE_ID}'`);
+
+  error.type = 'StripeInvalidRequestError';
+  error.code = 'resource_missing';
+  error.statusCode = 404;
+
+  return error;
+}
+
+/**
+ * The event under test, answered by whatever `sdk` says.
+ *
+ * @param {object} options
+ * @param {object} options.sdk - The stand-in Stripe SDK
+ * @param {string} [options.payloadUid] - The owner the event's payload claims
+ * @param {boolean} [options.reporting] - Whether a DSN is configured at all
+ */
+function runSubscriptionUpdated({ sdk, payloadUid = OWNER_UID, reporting = true }) {
+  return withStripeSdk(sdk, () => runTrigger({
+    uid: payloadUid,
+    orderId: ORDER_ID,
+    resourceId: RESOURCE_ID,
+    eventId: EVENT_ID,
+    eventType: EVENT_TYPE,
+    provider: 'stripe',
+    payload: subscriptionPayload({ uid: payloadUid, orderId: ORDER_ID, resourceId: RESOURCE_ID }),
+    // Both uids are real accounts here — what is forged is the CLAIM, so the
+    // #399 auth guard (which reports on its own path) never fires
+    authUids: [OWNER_UID, FORGED_UID],
+    reporting: reporting,
+  }));
+}
+
+/** A stand-in SDK answering with the record Stripe really holds */
+function sdkAnswering() {
+  return { subscriptions: { retrieve: async () => subscriptionPayload({ uid: OWNER_UID, orderId: ORDER_ID, resourceId: RESOURCE_ID }) } };
+}
+
+/** A stand-in SDK whose lookup throws `error` */
+function sdkThrowing(error) {
+  return { subscriptions: { retrieve: async () => { throw error; } } };
+}
+
+module.exports = defineCases({
+  description: 'A refused payment webhook reports one Sentry warning; a processed one reports nothing',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'a forged owner reports exactly one warning, naming the reason, the provider and the event',
+
+      async run() {
+        const { captures, store } = await runSubscriptionUpdated({ sdk: sdkAnswering(), payloadUid: FORGED_UID });
+
+        assert.strictEqual(captures.length, 1, `A refusal reports exactly once, got ${JSON.stringify(captures)}`);
+
+        const capture = captures[0];
+
+        assert.strictEqual(capture.level, 'warning', `A refusal is a decision, not a server fault, got ${capture.level}`);
+        assert.strictEqual(capture.tags.refusal, 'uid-mismatch', `The tag names the reason, got ${JSON.stringify(capture.tags)}`);
+        assert.strictEqual(capture.tags.provider, 'stripe', `The tag names the provider, got ${JSON.stringify(capture.tags)}`);
+        assert.strictEqual(capture.tags.eventId, EVENT_ID, `The event is nameable in the provider dashboard, got ${JSON.stringify(capture.tags)}`);
+        assert.strictEqual(capture.extra.eventId, EVENT_ID, `The event id rides the report body too, got ${JSON.stringify(capture.extra)}`);
+        assert.strictEqual(capture.extra.eventType, EVENT_TYPE, `The report says which event it was, got ${JSON.stringify(capture.extra)}`);
+        assert.match(capture.message, /uid-mismatch/, `The message says what was refused, got ${capture.message}`);
+
+        assert.strictEqual(
+          store.get(`payments-webhooks/${EVENT_ID}`)?.refusal?.reason,
+          capture.tags.refusal,
+          'The reported reason is the one stamped on the event doc',
+        );
+      },
+    },
+
+    {
+      name: 'the report carries the refusal stamp and nothing off the payload',
+
+      async run() {
+        const { captures } = await runSubscriptionUpdated({ sdk: sdkAnswering(), payloadUid: FORGED_UID });
+        const capture = captures[0];
+
+        // Ids only, per the scrub rules: the stamp's own fields are the join
+        // keys a human reconciles from, and the payload never rides along.
+        assert.strictEqual(capture.extra.payloadUid, FORGED_UID, `The claimed owner rides, got ${JSON.stringify(capture.extra)}`);
+        assert.strictEqual(capture.extra.providerUid, OWNER_UID, `The real owner rides, got ${JSON.stringify(capture.extra)}`);
+        assert.ok(!JSON.stringify(capture).includes('@'), `No email is ever assembled into the report, got ${JSON.stringify(capture)}`);
+        assert.ok(!JSON.stringify(capture).includes('current_period_end'), `The provider payload never rides, got ${JSON.stringify(capture)}`);
+      },
+    },
+
+    {
+      name: 'a resource the provider does not have reports the same way',
+
+      async run() {
+        // The whole family rides the one seam ([#506]) — a different refusal
+        // reason needs no capture of its own.
+        const { captures } = await runSubscriptionUpdated({ sdk: sdkThrowing(resourceMissing()) });
+
+        assert.strictEqual(captures.length, 1, `The #506 refusal reports too, got ${JSON.stringify(captures)}`);
+        assert.strictEqual(captures[0].tags.refusal, 'resource-not-found', `The tag names this reason, got ${JSON.stringify(captures[0].tags)}`);
+        assert.strictEqual(captures[0].extra.resourceId, RESOURCE_ID, `The stamp's resource rides, got ${JSON.stringify(captures[0].extra)}`);
+      },
+    },
+
+    {
+      name: 'a processed event reports nothing at all',
+
+      async run() {
+        const { captures, store } = await runSubscriptionUpdated({ sdk: sdkAnswering() });
+
+        assert.deepStrictEqual(captures, [], `An ordinary event is a non-event on the dashboard, got ${JSON.stringify(captures)}`);
+        assert.strictEqual(store.get(`users/${OWNER_UID}`)?.subscription?.status, 'active', 'The subscription is written exactly as before');
+      },
+    },
+
+    {
+      name: 'with no DSN configured the refusal still lands, reporting nothing',
+
+      async run() {
+        // `libraries.sentry` is null whenever no DSN is set — the capture must be
+        // a clean no-op, never a second failure on top of the refusal
+        const { captures, store } = await runSubscriptionUpdated({ sdk: sdkAnswering(), payloadUid: FORGED_UID, reporting: false });
+
+        assert.deepStrictEqual(captures, [], `Nothing is reported when reporting is off, got ${JSON.stringify(captures)}`);
+
+        const event = store.get(`payments-webhooks/${EVENT_ID}`);
+
+        assert.strictEqual(event?.refusal?.reason, 'uid-mismatch', 'The stamp still lands');
+        assert.strictEqual(event?.status, 'completed', 'The refusal is still acknowledged, not failed');
+        assert.ok(!store.get(`payments-orders/${ORDER_ID}`), 'And the refused event still writes nothing');
+      },
+    },
+  ],
+});

package/test/events/payments/webhook-refused-intent.test.js

@@ -0,0 +1,142 @@
+/**
+ * Test: a REFUSED event touches no doc the payload named, even when its own stamp fails
+ *
+ * A refusal writes one thing — the stamp on the event's own doc — and nothing
+ * else. But if that write itself throws, the outer failure path took over and ran
+ * `resolveOrderIdAfterFailure()`, which reads the orderId out of the PAYLOAD and
+ * marks `payments-intents/{orderId}` failed. So the one doc a refused forgery
+ * could still reach was a doc named entirely by the caller
+ * ([#535](https://github.com/Omega-JS-Stack/omega/issues/535)).
+ *
+ * The refusal is already the terminal state, so the failure path writes nothing
+ * for it: the event doc is marked failed (the retry sweep re-lands the stamp on
+ * the next pass) and the payload-derived intent write is skipped entirely.
+ *
+ * Plain-node control-flow test (no emulator, no network): the real trigger module
+ * runs against the shared in-memory Firestore stand-in (_webhook-harness.js). The
+ * emulator cannot produce this fault at all — the admin SDK bypasses rules and
+ * every write is legal — so the stand-in fails the ONE write this is about: the
+ * stamp, identified by the refusal it carries, leaving the failure stamp that
+ * follows it on the same doc free to land.
+ *
+ * Run: npx omega test backend:events/payments/webhook-refused-intent
+ */
+const assert = require('node:assert');
+const { runTrigger, subscriptionPayload } = require('./_webhook-harness.js');
+const Stripe = require('../../../dist/manager/libraries/payment/providers/stripe.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// The subscriber the subscription actually belongs to, on Stripe's own record
+const OWNER_UID = '_test-refused-intent-owner';
+const OWNER_ORDER_ID = '5351-5351-5351';
+
+// The uid the forged event claims, and the order it names — both the caller's choice
+const FORGED_UID = '_test-refused-intent-forged';
+const FORGED_ORDER_ID = '5350-5350-5350';
+
+const RESOURCE_ID = 'sub_test_refused_intent';
+const EVENT_ID = '_test-refused-intent-evt';
+
+/** Run fn with the library's SDK replaced by one that answers with `subscription` */
+async function withStripeAnswering(subscription, fn) {
+  const realInit = Stripe.init;
+
+  Stripe.init = () => ({ subscriptions: { retrieve: async () => subscription } });
+
+  try {
+    return await fn();
+  } finally {
+    Stripe.init = realInit;
+  }
+}
+
+/**
+ * The forged event — a real subscription id under someone else's uid, which the
+ * #509 check refuses — run with the refusal STAMP as the write that rejects
+ */
+function runRefusalWhoseStampFails() {
+  const record = subscriptionPayload({ uid: OWNER_UID, orderId: OWNER_ORDER_ID, resourceId: RESOURCE_ID });
+
+  return withStripeAnswering(record, () => runTrigger({
+    uid: FORGED_UID,
+    orderId: FORGED_ORDER_ID,
+    resourceId: RESOURCE_ID,
+    eventId: EVENT_ID,
+    provider: 'stripe',
+    payload: subscriptionPayload({ uid: FORGED_UID, orderId: FORGED_ORDER_ID, resourceId: RESOURCE_ID }),
+    authUids: [OWNER_UID, FORGED_UID],
+    // The stamp is the write that fails — the failure stamp that follows it lands
+    // on the same doc and must still be able to
+    failPath: (path, data) => path === `payments-webhooks/${EVENT_ID}` && !!data.refusal,
+  }));
+}
+
+module.exports = defineCases({
+  description: 'A refused event whose refusal stamp fails to write still touches nothing else',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'no intent doc is written for the order the payload named',
+
+      async run() {
+        const { store } = await runRefusalWhoseStampFails();
+
+        assert.ok(!store.get(`payments-intents/${FORGED_ORDER_ID}`), 'the refused event must not reach a doc named by the caller, not even to fail it');
+        assert.ok(!store.get(`payments-intents/${OWNER_ORDER_ID}`), 'nor the real owner\'s intent — a refusal acts on nobody');
+      },
+    },
+
+    {
+      name: 'nothing else is written either',
+
+      async run() {
+        const { store } = await runRefusalWhoseStampFails();
+
+        assert.ok(!store.get(`users/${FORGED_UID}`), 'no subscription for the forged uid');
+        assert.ok(!store.get(`users/${OWNER_UID}`), 'and none for the owner');
+        assert.ok(!store.get(`payments-orders/${FORGED_ORDER_ID}`), 'no order behind it');
+      },
+    },
+
+    {
+      name: 'the event is left failed, so the sweep re-lands the stamp',
+
+      async run() {
+        const { store } = await runRefusalWhoseStampFails();
+        const event = store.get(`payments-webhooks/${EVENT_ID}`);
+
+        assert.equal(event.status, 'failed', 'the decision was made but never recorded — the retry sweep is what re-lands it');
+        assert.ok(!event.refusal, 'the stamp is exactly the write that did not land');
+        assert.equal(event.retryCount, 1, 'and the attempt is counted like any other failed pass');
+      },
+    },
+
+    {
+      name: 'a refusal whose stamp DOES land is unaffected',
+
+      async run() {
+        // The ordinary #509 refusal, with no write fault in the way — the skip
+        // above must not have taken the stamp with it.
+        const record = subscriptionPayload({ uid: OWNER_UID, orderId: OWNER_ORDER_ID, resourceId: RESOURCE_ID });
+
+        const { store } = await withStripeAnswering(record, () => runTrigger({
+          uid: FORGED_UID,
+          orderId: FORGED_ORDER_ID,
+          resourceId: RESOURCE_ID,
+          eventId: EVENT_ID,
+          provider: 'stripe',
+          payload: subscriptionPayload({ uid: FORGED_UID, orderId: FORGED_ORDER_ID, resourceId: RESOURCE_ID }),
+          authUids: [OWNER_UID, FORGED_UID],
+        }));
+
+        const event = store.get(`payments-webhooks/${EVENT_ID}`);
+
+        assert.equal(event.status, 'completed', 'a refusal that records itself is terminal and acknowledged');
+        assert.equal(event.refusal?.reason, 'uid-mismatch', 'and carries its reason');
+        assert.ok(!store.get(`payments-intents/${FORGED_ORDER_ID}`), 'still nothing under the order the payload named');
+      },
+    },
+  ],
+});