backend-manager 5.9.3 → 5.9.5

package/CHANGELOG.md

@@ -14,6 +14,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.9.5] - 2026-06-21
+
+### Fixed
+- **Suspended subscription cancel dead zone.** Users with `subscription.status: 'suspended'` were trapped — the subscribe endpoint required them to cancel first, but the cancel endpoint only accepted `active` subscriptions. Cancel now accepts both `active` and `suspended`. When the processor rejects a suspended cancel (subscription already dead on their end), falls back to directly resetting the user doc to `cancelled`.
+
+### Security
+- **Supply-chain audited installs.** All `npm install` calls in CLI commands (`install`, setup-tests) now route through `safeInstall()` which prefixes Socket Firewall (`sfw`) when available, blocking confirmed malware before packages reach disk.
+
+# [5.9.4] - 2026-06-21
+
+### Fixed
+- **Download-app-link email had blank body.** Template passed `data: {}` so the card rendered logo + signoff + footer but no content. Now populates title, message, and "Download Now" button linking to `{brand.url}/download`.
+
 # [5.9.3] - 2026-06-21
 
 ### Changed

package/CLAUDE.md

@@ -2,6 +2,8 @@
 
 > **Note for contributors and Claude:** This file is the architectural overview — identity, top-level conventions, and a map to deep references. The **meat** (per-subsystem APIs, behavior tables, recipes) lives in `docs/<topic>.md`. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one. Goal: keep this file under 250 lines.
 
+> **Mirrored structure:** BEM, UJM, BXM, and EM CLAUDE.md files mirror each other — shared sections (Supply-Chain Security, Development Workflow, File Conventions, etc.) appear in the **same order at the same position** across all four. When adding a section that applies to multiple frameworks, insert it in the same spot in all of them.
+
 ## Identity
 
 Backend Manager (BEM) is a comprehensive framework for building modern Firebase Cloud Functions backends. Sister project to Electron Manager (EM), Browser Extension Manager (BXM), and Ultimate Jekyll Manager (UJM). Provides a single `Manager.init(exports, {...})` bootstrap that wires built-in functions (`bm_api`, auth events, cron jobs), helper classes (Assistant, User, Analytics, Usage, Middleware, Settings, Utilities, Metadata), payment processor integrations (Stripe / PayPal), Firestore-trigger pipelines, marketing campaign automation, an MCP server, and a CLI for emulator/deploy/logs/auth/Firestore operations.
@@ -94,6 +96,10 @@ See [docs/cli-firestore-auth.md](docs/cli-firestore-auth.md) and [docs/cli-logs.
 - **If the user reports an error**, check the emulator/test output for the root cause before guessing.
 - **Live-test UI changes via CDP.** When working on admin dashboards or browser-facing endpoints, use the `chrome-devtools` MCP tools (screenshots, click, evaluate JS, console logs) to verify the change works in the running browser. See `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
 
+## Supply-Chain Security
+
+All `npm install` calls in CLI commands (`npx mgr i`, `npx mgr setup`, setup-tests) route through the `safeInstall()` helper (`src/cli/utils/safe-install.js`). It prefixes `sfw` (Socket Firewall) when installed — blocking confirmed malware at the network level before packages reach disk. Falls back to plain npm if sfw isn't available. CI workflows install sfw globally and run `sfw npm install`/`sfw npm ci`. Installs will **fail if sfw detects confirmed malware** in any package in the dependency tree; non-critical CVEs and quality warnings pass through.
+
 ## File Conventions
 
 - **CommonJS** throughout. `prepare-package` copies `src/` → `dist/` 1:1 (no transforms).

package/PROGRESS.md

@@ -2,11 +2,11 @@
 > Agents and maintainers should update this file regularly to reflect the current state of the project.
 
 ## 🎯 Current Focus
-* **Goal:** Ghostii feed sources cleanup + Somiibo consumer config
-* **Current Phase:** Fixes applied + tested, pending commit + publish
+* **Goal:** Fix suspended subscription dead zone — users with `suspended` status couldn't cancel or re-subscribe
+* **Current Phase:** Fix applied + tested (24/24 passing), pending commit + publish
 * **Priority:** High
-* **Last Updated:** 2026-06-19 3:05 AM PDT
-* **Notes:** Renamed Firestore collection `ghostii-feed-items` → `ghostii-sources`. Fixed `FieldValue.serverTimestamp()` → BEM metadata pattern. Added 5 marketing/social feeds to extended tests. All tests passing (20/20 standard, 9/9 extended). Somiibo consumer has feeds configured + `ghostii-sources.md` evaluation doc. Needs BEM publish + consumer deploy.
+* **Last Updated:** 2026-06-21 5:50 PM PDT
+* **Notes:** Cancel endpoint now accepts `suspended` subscriptions. Added fallback: if processor rejects (subscription already dead on their end), directly resets user doc to `cancelled`. Traced from live Somiibo user `t9AeAe7QUhNXAUYRV1vUbOU0QVV2` stuck in limbo. Needs BEM publish + Somiibo deploy.
 
 ## 📌 Active Task List
 * [ ] Phase 6: Setup scaffolds essential configs for fresh projects
@@ -43,6 +43,13 @@
   * [ ] Task 5.17: Publish BEM with feed support
   * [ ] Task 5.12: Publish BEM with feed support
   * [ ] Task 5.13: Configure consumer project(s) with `$feed:` sources
+* [x] Phase 7: Fix suspended subscription cancel dead zone
+  * [x] Task 7.1: Trace user `t9AeAe7QUhNXAUYRV1vUbOU0QVV2` — identified asymmetric status gates
+  * [x] Task 7.2: Update cancel gate to accept `suspended` alongside `active`
+  * [x] Task 7.3: Add fallback — direct Firestore reset when processor rejects suspended cancel
+  * [x] Task 7.4: Add `cancel-suspended` test account + `allows-suspended-subscription` test
+  * [x] Task 7.5: All 24 payment tests passing
+  * [ ] Task 7.6: Publish BEM + deploy Somiibo
 * [ ] Phase 3: Post-audit bug fixes
   * [x] Newsletter ReferenceError: `beehiivConfig` → `newsletterRoleConfig` (committed v5.7.1)
   * [x] HTTPS proxy: `serve.js` returns boolean, caller uses `httpsReady` not `httpsEnabled`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.9.3",
+  "version": "5.9.5",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/plans/suspended-subscription-dead-zone.md

@@ -0,0 +1,97 @@
+# Suspended Subscription Dead Zone
+
+## Issue
+
+A user with a `suspended` subscription was trapped in a loop:
+- **Trying to subscribe** → "You already have a subscription. Please cancel your existing subscription before purchasing a new one." (400)
+- **Trying to cancel** → "No active paid subscription found" (400)
+
+No way out.
+
+## Affected User
+
+- **UID:** `t9AeAe7QUhNXAUYRV1vUbOU0QVV2`
+- **Brand:** Somiibo
+
+The user had two stale subscriptions from different processors:
+
+| Field | Processor | Status | Resource ID | Last Webhook |
+|---|---|---|---|---|
+| `subscription` | PayPal | `suspended` | `I-Y41DMAGNWGP1` | `BILLING.SUBSCRIPTION.SUSPENDED` (2026-04-19) |
+| `plan` (legacy) | Chargebee | `suspended` | `169xhEU1pYXAt3dsj` | `subscription-profile-fixer` (2024-02-28) |
+
+PayPal suspended the subscription (likely failed payment) but never sent a `BILLING.SUBSCRIPTION.CANCELLED` webhook. PayPal doesn't auto-cancel suspended subscriptions — it leaves them in limbo until the user resolves payment or manually cancels in PayPal. The local status stayed `suspended` forever.
+
+## Root Cause
+
+Asymmetric status gates between the intent and cancel endpoints:
+
+### Intent gate (`POST /payments/intent`)
+```js
+// Blocked if product is NOT basic AND status is NOT cancelled
+if (subProductId !== 'basic' && subStatus !== 'cancelled') { ... }
+```
+- `active` → blocked (correct)
+- `suspended` → blocked (correct — user should cancel first)
+- `cancelled` → allowed (correct)
+
+### Cancel gate (`POST /payments/cancel`)
+```js
+// Blocked if status is NOT active
+if (subscription.status !== 'active') { ... }
+```
+- `active` → allowed (correct)
+- `suspended` → **blocked** (the bug)
+- `cancelled` → blocked (correct — nothing to cancel)
+
+The intent gate treats `suspended` as "has a subscription" (must cancel first), but the cancel gate treats `suspended` as "no subscription to cancel." Dead zone.
+
+## The Fix
+
+### 1. Cancel gate now accepts `suspended`
+
+```js
+// Before
+if (!subscription || subscription.status !== 'active' || ...)
+
+// After
+if (!subscription || (subscription.status !== 'active' && subscription.status !== 'suspended') || ...)
+```
+
+### 2. Fallback for dead processor subscriptions
+
+When cancelling a `suspended` subscription, the processor API call might fail — the subscription could be expired/deleted on the processor's side while our local state is stale. The cancel endpoint now catches processor errors for suspended subscriptions and directly resets the user doc:
+
+```js
+if (subscription.status === 'suspended') {
+  // Processor rejected — subscription is already dead on their end
+  // Directly reset the user doc to cancelled
+  await admin.firestore().doc(`users/${uid}`).set({
+    subscription: {
+      status: 'cancelled',
+      product: { id: 'basic', name: 'Basic' },
+      cancellation: { pending: false, date: { timestamp, timestampUNIX } },
+    },
+  }, { merge: true });
+}
+```
+
+### 3. New test coverage
+
+- Test account `cancel-suspended` with `status: 'suspended'` and test processor payment details
+- Test `allows-suspended-subscription` verifying the cancel endpoint accepts and processes suspended subscriptions
+
+## Status Matrix (after fix)
+
+| Status | Can subscribe? | Can cancel? | Can delete account? |
+|---|---|---|---|
+| `active` (basic) | Yes | No (nothing to cancel) | Yes |
+| `active` (paid) | No (cancel first) | Yes | No |
+| `suspended` | No (cancel first) | **Yes** (fixed) | No |
+| `cancelled` | Yes | No (already cancelled) | Yes |
+
+## Files Changed
+
+- `src/manager/routes/payments/cancel/post.js` — gate + fallback
+- `src/test/test-accounts.js` — `cancel-suspended` account
+- `test/routes/payments/cancel.js` — `allows-suspended-subscription` test

package/src/cli/commands/install.js

@@ -5,6 +5,7 @@ const powertools = require('node-powertools');
 const Npm = require('npm-api');
 const jetpack = require('fs-jetpack');
 const wonderfulVersion = require('wonderful-version');
+const { safeInstall } = require('../utils/safe-install');
 
 class InstallCommand extends BaseCommand {
   async execute(type) {
@@ -110,12 +111,12 @@ class InstallCommand extends BaseCommand {
       const command = name;
       this.log('Running ', command);
       
-      return await powertools.execute(command, { log: true })
+      return await safeInstall(command, { log: true })
         .catch((e) => {
           throw e;
         });
     }
-    
+
     if (name.indexOf('file:') > -1) {
       v = '';
     } else if (!version) {
@@ -133,7 +134,7 @@ class InstallCommand extends BaseCommand {
     const command = `npm i ${name}${v}${t}`;
     this.log('Running ', command);
 
-    return await powertools.execute(command, { log: true })
+    return await safeInstall(command, { log: true })
       .catch((e) => {
         throw e;
       });

package/src/cli/commands/setup-tests/backend-manager.js

@@ -4,6 +4,7 @@ const wonderfulVersion = require('wonderful-version');
 const powertools = require('node-powertools');
 const Npm = require('npm-api');
 const helpers = require('./helpers');
+const { safeInstall } = require('../../utils/safe-install');
 
 class BackendManagerTest extends BaseTest {
   getName() {
@@ -72,7 +73,7 @@ class BackendManagerTest extends BaseTest {
     console.log('Running ', command);
 
     // Execute
-    await powertools.execute(command, { log: true });
+    await safeInstall(command);
   }
 }
 

package/src/cli/commands/setup-tests/firebase-admin.js

@@ -3,6 +3,7 @@ const chalk = require('chalk').default;
 const wonderfulVersion = require('wonderful-version');
 const powertools = require('node-powertools');
 const helpers = require('./helpers');
+const { safeInstall } = require('../../utils/safe-install');
 
 class FirebaseAdminTest extends BaseTest {
   getName() {
@@ -64,7 +65,7 @@ class FirebaseAdminTest extends BaseTest {
     console.log('Running ', command);
 
     // Execute
-    await powertools.execute(command, { log: true });
+    await safeInstall(command);
   }
 }
 

package/src/cli/commands/setup-tests/firebase-functions.js

@@ -3,6 +3,7 @@ const chalk = require('chalk').default;
 const wonderfulVersion = require('wonderful-version');
 const powertools = require('node-powertools');
 const helpers = require('./helpers');
+const { safeInstall } = require('../../utils/safe-install');
 
 class FirebaseFunctionsTest extends BaseTest {
   getName() {
@@ -64,7 +65,7 @@ class FirebaseFunctionsTest extends BaseTest {
     console.log('Running ', command);
 
     // Execute
-    await powertools.execute(command, { log: true });
+    await safeInstall(command);
   }
 }
 

package/src/cli/utils/safe-install.js

@@ -0,0 +1,13 @@
+const { execute } = require('node-powertools');
+
+let _hasSfw;
+async function safeInstall(command, options) {
+  if (_hasSfw === undefined) {
+    _hasSfw = await execute('sfw --version', { log: false }).then(() => true).catch(() => false);
+  }
+  const isInstall = /^npm\s+(install|i)\b/.test(command);
+  const prefix = (_hasSfw && isInstall) ? 'sfw ' : '';
+  return execute(`${prefix}${command}`, options || { log: true });
+}
+
+module.exports = { safeInstall };

package/src/manager/functions/core/actions/api/general/emails/general:download-app-link.js

@@ -1,4 +1,9 @@
 module.exports = function (payload, config) {
+  const brandName = config.brand.name || '';
+  const brandUrl = config.brand.url || '';
+  const downloadUrl = `${brandUrl}/download`;
+  const name = payload.name || '';
+
   return {
     // spamFilter: {
     //   ip: 3,
@@ -8,14 +13,26 @@ module.exports = function (payload, config) {
     payload: {
       to: {
         email: payload.email,
-        name: payload.name,
+        name: name,
       },
       sender: 'marketing',
       categories: ['download'],
-      subject: `Free ${config.brand.name} download link for ${payload.name || 'you'}!`,
+      subject: `${name || 'Hey'}, your ${brandName} download link is ready!`,
       template: 'card',
       copy: false,
-      data: {},
+      data: {
+        email: {
+          preview: `Your ${brandName} download link is inside`,
+        },
+        content: {
+          title: 'Your download link is ready!',
+          message: `Thanks for your interest in **${brandName}**! Click the button below to head to the download page and get started.`,
+          button: {
+            url: downloadUrl,
+            text: 'Download Now',
+          },
+        },
+      },
     }
   }
 }

package/src/manager/routes/general/email/templates/general/download-app-link.js

@@ -3,6 +3,11 @@
  * Sends a download link for the app
  */
 module.exports = function (payload, config) {
+  const brandName = config.brand.name || '';
+  const brandUrl = config.brand.url || '';
+  const downloadUrl = `${brandUrl}/download`;
+  const name = payload.name || '';
+
   return {
     // spamFilter: {
     //   ip: 3,
@@ -12,14 +17,26 @@ module.exports = function (payload, config) {
     payload: {
       to: {
         email: payload.email,
-        name: payload.name,
+        name: name,
       },
       sender: 'marketing',
       categories: ['download'],
-      subject: `${payload.name || 'Hey'}, your ${config.brand.name} download link is ready!`,
+      subject: `${name || 'Hey'}, your ${brandName} download link is ready!`,
       template: 'card',
       copy: false,
-      data: {},
+      data: {
+        email: {
+          preview: `Your ${brandName} download link is inside`,
+        },
+        content: {
+          title: 'Your download link is ready!',
+          message: `Thanks for your interest in **${brandName}**! Click the button below to head to the download page and get started.`,
+          button: {
+            url: downloadUrl,
+            text: 'Download Now',
+          },
+        },
+      },
     }
   }
 }

package/src/manager/routes/payments/cancel/post.js

@@ -26,8 +26,8 @@ module.exports = async ({ assistant, user, settings }) => {
 
   const subscription = user.subscription;
 
-  // Require an active, paid subscription
-  if (!subscription || subscription.status !== 'active' || subscription.product?.id === 'basic') {
+  // Require an active or suspended paid subscription
+  if (!subscription || (subscription.status !== 'active' && subscription.status !== 'suspended') || subscription.product?.id === 'basic') {
     assistant.log(`Cancel rejected: uid=${uid}, status=${subscription?.status}, product=${subscription?.product?.id}`);
     return assistant.respond('No active paid subscription found', { code: 400 });
   }
@@ -69,6 +69,26 @@ module.exports = async ({ assistant, user, settings }) => {
   try {
     await processorModule.cancelAtPeriodEnd({ resourceId, uid, subscription, assistant });
   } catch (e) {
+    // If the subscription is suspended and the processor rejects (subscription already dead/gone),
+    // directly reset the user's subscription to cancelled so they can re-subscribe
+    if (subscription.status === 'suspended') {
+      assistant.log(`Processor cancel failed for suspended subscription (${e.message}), resetting directly`);
+      const admin = assistant.Manager.libraries.admin;
+      const now = powertools.timestamp(new Date(), { output: 'string' });
+      const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+      await admin.firestore().doc(`users/${uid}`).set({
+        subscription: {
+          status: 'cancelled',
+          product: { id: 'basic', name: 'Basic' },
+          cancellation: { pending: false, date: { timestamp: now, timestampUNIX: nowUNIX } },
+        },
+      }, { merge: true });
+
+      assistant.log(`Directly cancelled suspended subscription for uid=${uid}`);
+      return assistant.respond({ success: true });
+    }
+
     assistant.log(`Failed to cancel subscription via ${processor}: ${e.message}`);
     return assistant.respond(`Failed to cancel subscription: ${e.message}`, { code: 500, sentry: true });
   }

package/src/test/test-accounts.js

@@ -416,6 +416,15 @@ const JOURNEY_ACCOUNTS = {
       subscription: { product: { id: 'premium', name: 'Premium' }, status: 'active', expires: getFutureExpires(), cancellation: { pending: false }, payment: { processor: 'test', resourceId: 'sub_test_fake', startDate: { timestamp: new Date().toISOString(), timestampUNIX: Math.floor(Date.now() / 1000) } } },
     },
   },
+  'cancel-suspended': {
+    id: 'cancel-suspended',
+    uid: '_test-cancel-suspended',
+    email: '_test.cancel-suspended@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'premium', name: 'Premium' }, status: 'suspended', expires: getPastExpires(), cancellation: { pending: false }, payment: { processor: 'test', resourceId: 'sub_test_suspended', startDate: getPastExpires() } },
+    },
+  },
   // Dedicated accounts for portal validation tests
   'portal-no-processor': {
     id: 'portal-no-processor',

package/test/routes/payments/cancel.js

@@ -90,6 +90,29 @@ module.exports = {
       },
     },
 
+    {
+      name: 'allows-suspended-subscription',
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
+        const uid = accounts['cancel-suspended'].uid;
+
+        const response = await http.as('cancel-suspended').post('backend-manager/payments/cancel', {
+          confirmed: true,
+          reason: 'Subscription was suspended',
+          skipGuards: true,
+        });
+
+        assert.isSuccess(response, 'Should allow cancelling a suspended subscription');
+        assert.equal(response.data.success, true, 'Should return success: true');
+
+        // Verify the subscription was reset to cancelled (via fallback or webhook)
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.status === 'cancelled'
+            || userDoc?.subscription?.cancellation?.pending === true;
+        }, 15000, 500);
+      },
+    },
+
     {
       name: 'succeeds-with-test-processor',
       async run({ http, assert, config, accounts, firestore, waitFor, skip }) {