fix(billing): address review feedback on JSDoc, error messages, and test coverage

- Update isAllowedUrl JSDoc to document env-specific behavior
- Make error messages env-aware (clarify production-only restrictions)
- Fix getStripe JSDoc to use standard summary format
- Add production regression test for hostname mismatch rejection

Author: PierreBrisorgueil

modules/billing/lib/stripe.js

@@ -11,7 +11,7 @@ import config from '../../../config/index.js';
 let stripeClient = null;
 
 /**
- * @desc Get or create the Stripe client instance
+ * Get or create the lazily-initialised Stripe client instance.
  * @returns {Object|null} Stripe client or null if not configured
  */
 const getStripe = () => {

modules/billing/services/billing.service.js

@@ -7,7 +7,11 @@ import BillingPlansService from './billing.plans.service.js';
 import SubscriptionRepository from '../repositories/billing.subscription.repository.js';
 
 /**
- * @desc Validate that a URL uses https (or http in dev/test) and belongs to the app domain
+ * Validate that a redirect URL is safe for the current environment.
+ * In production the URL must use HTTPS and, when config.domain is set,
+ * its hostname must match the application domain.
+ * In development / test only basic URL parsing is enforced (HTTP allowed,
+ * any hostname accepted) so that localhost workflows are not blocked.
  * @param {String} url - URL to validate
  * @returns {Boolean} true if valid
  */
@@ -40,13 +44,13 @@ const createCheckout = async (organization, priceId, successUrl, cancelUrl) => {
   if (!stripe) throw new Error('Stripe is not configured');
 
   if (!isAllowedUrl(successUrl) || !isAllowedUrl(cancelUrl)) {
-    throw new Error('Invalid redirect URL: must use HTTPS and match the application domain');
+    throw new Error('Invalid redirect URL: must be a valid URL (production requires HTTPS and a matching application domain)');
   }
 
-  // Validate priceId against known active Stripe prices
+  // Validate priceId against known active Stripe prices and resolve the canonical plan id
   const plans = await BillingPlansService.getPlans();
-  const allowedPriceIds = plans.flatMap((p) => [p.stripePriceMonthly, p.stripePriceAnnual].filter(Boolean));
-  if (!allowedPriceIds.includes(priceId)) {
+  const matchedPlan = plans.find((p) => p.stripePriceMonthly === priceId || p.stripePriceAnnual === priceId);
+  if (!matchedPlan) {
     throw new Error('Invalid priceId: must be an active published price');
   }
 
@@ -86,9 +90,6 @@ const createCheckout = async (organization, priceId, successUrl, cancelUrl) => {
     if (latest?.stripeCustomerId) subscription = latest;
   }
 
-  // Derive plan name from priceId for checkout metadata
-  const matchedPlan = plans.find((p) => p.stripePriceMonthly === priceId || p.stripePriceAnnual === priceId);
-
   const session = await stripe.checkout.sessions.create({
     customer: subscription.stripeCustomerId,
     mode: 'subscription',
@@ -97,7 +98,7 @@ const createCheckout = async (organization, priceId, successUrl, cancelUrl) => {
     cancel_url: cancelUrl,
     metadata: {
       organizationId: String(organization._id),
-      plan: matchedPlan?.planId || 'free',
+      plan: matchedPlan.planId,
     },
   });
 
@@ -119,7 +120,7 @@ const createPortalSession = async (organization, returnUrl) => {
 
   const params = { customer: subscription.stripeCustomerId };
   if (returnUrl) {
-    if (!isAllowedUrl(returnUrl)) throw new Error('Invalid return URL: must use HTTPS and match the application domain');
+    if (!isAllowedUrl(returnUrl)) throw new Error('Invalid return URL: must be a valid URL (production requires HTTPS and a matching application domain)');
     params.return_url = returnUrl;
   }
 

modules/billing/tests/billing.checkout.unit.tests.js

@@ -122,6 +122,28 @@ describe('Billing service unit tests:', () => {
       expect(url).toBe('https://checkout.stripe.com/session_123');
     });
 
+    test('should reject mismatched hostname in production when config.domain is set', async () => {
+      const originalEnv = process.env.NODE_ENV;
+      process.env.NODE_ENV = 'production';
+
+      jest.unstable_mockModule('../../../config/index.js', () => ({
+        default: { stripe: { secretKey: 'sk_test_prodcheck' }, domain: 'https://myapp.com' },
+      }));
+
+      mockSubscriptionRepository.findByOrganization.mockResolvedValue({
+        stripeCustomerId: 'cus_existing',
+      });
+
+      const mod = await import('../services/billing.service.js');
+      BillingService = mod.default;
+
+      await expect(
+        BillingService.createCheckout(mockOrganization, 'price_starter_m', 'https://evil.com/success', 'https://myapp.com/cancel'),
+      ).rejects.toThrow('Invalid redirect URL');
+
+      process.env.NODE_ENV = originalEnv;
+    });
+
     test('should throw when priceId is not in allowed plans', async () => {
       jest.unstable_mockModule('../../../config/index.js', () => ({
         default: { stripe: { secretKey: 'sk_test_price' } },