backend-manager 5.2.15 → 5.2.16

package/CHANGELOG.md

@@ -14,6 +14,20 @@ 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.2.16] - 2026-05-28
+
+### Removed
+
+- **Dropped the legacy top-level `affiliateCode` field from `/user/signup`.** UJM and all current consumers send the referral code as `attribution.affiliate.code`; the top-level `affiliateCode` (and the normalize-to-`attribution` shim + the `processAffiliate` fallback that read it) was a dead legacy path. Removed from `src/manager/schemas/user/signup/post.js`, the `buildUserRecord` normalize block, and the `processAffiliate` lookup in `src/manager/routes/user/signup/post.js`. The route now reads referral codes exclusively from `attribution.affiliate.code`. (The legacy `bm_api` sign-up action `functions/core/actions/api/user/sign-up.js` is unchanged.)
+
+### Fixed
+
+- **Consent: never downgrade an existing granted consent on `/user/signup`** (`src/manager/routes/user/signup/post.js`). A legacy account — signed up before the `flags.signupProcessed` completion flow existed, so the flag was never set — re-fires `/user/signup` on every page load until the flag flips. Its consent payload arrives empty (the original is long gone from `localStorage`), which previously computed `'revoked'` and, on the `{ merge: true }` write, wiped the consent the user actually granted months ago. `buildConsentRecord` now reads the existing doc's consent and preserves any already-`granted` status when the incoming payload doesn't explicitly re-grant it. A genuine new grant still applies; an at-signup decline with no prior grant still records the decline. Added `consent-empty-payload-preserves-existing-grant` and `consent-explicit-decline-does-not-downgrade-existing-grant` tests (+ a dedicated `consent-preserve` test account). See `docs/consent.md`.
+
+### Changed
+
+- **`user/signup` schema: shaped the `consent` field.** `src/manager/schemas/user/signup/post.js` now declares the nested `consent.{legal,marketing}.{granted,text}` shape instead of a bare passthrough object, documenting the input contract at the schema layer (the SSOT for request shape). Each sub-object is optional — omitting it leaves existing consent untouched (see the downgrade guard above).
+
 # [5.2.15] - 2026-05-28
 
 ### Changed

package/docs/consent.md

@@ -67,16 +67,19 @@ There are four places where consent gets recorded or updated. All four converge
 }
 ```
 
-`buildConsentRecord(assistant, settings.consent)` translates this into the canonical user-doc shape:
+`buildConsentRecord(assistant, settings.consent, creationTime, existingConsent)` translates this into the canonical user-doc shape:
 
-- `legal.granted: true` → `legal.status = 'granted'`, `grantedAt` populated with `source: 'signup'` + **server timestamp** + server-detected IP + exact label text.
+- `legal.granted: true` → `legal.status = 'granted'`, `grantedAt` populated with `source: 'signup'` + **timestamp from Auth `creationTime`** + server-detected IP + exact label text.
 - `marketing.granted: false` → `marketing.status = 'revoked'`, `grantedAt` all-null, `revokedAt` populated with `source: 'signup'`. (Records the explicit decline.)
-- Missing `consent` block (legacy client) → both default to `'revoked'`.
 
-**Server time is authoritative.** Client-supplied timestamps are ignored — defends against clock manipulation by malicious clients.
+**Timestamps come from Firebase Auth `creationTime`,** not request time, so `consent.grantedAt` matches `metadata.created` (the OMEGA user migration treats `metadata.created` as the SSOT and reconciles `grantedAt` against it — stamping from request time made every new signup drift by a few seconds and get re-fixed on the next migration run).
+
+**Server-derived time is authoritative.** Client-supplied timestamps are ignored — defends against clock manipulation by malicious clients.
 
 **Strict boolean check.** Only `granted === true` counts as granted. `'true'`, `1`, or other truthy values are rejected.
 
+**Never downgrades an existing grant (data-loss guard).** A legacy account — one signed up before the `flags.signupProcessed` completion flow existed, so its flag was never set — re-fires `/user/signup` on every page load until the flag flips. Its consent was captured months ago and is long gone from `localStorage`, so the payload arrives empty. Without protection, `buildConsentRecord` would compute `'revoked'` and the `{ merge: true }` write would wipe the consent the user actually granted. The guard reads the existing doc's consent (`existingConsent`) and **preserves any already-`granted` status when the incoming payload does not explicitly re-grant it.** A genuine new grant still applies; an at-signup decline with no prior grant still records the decline. (The primary mitigation is OMEGA migration Fix 4f, which backfills `flags.signupProcessed: true` for established accounts so they never re-fire; this guard is the backstop for the deploy-before-migration gap.)
+
 **Marketing sync gating.** After writing the user doc, the route checks `userRecord.consent.marketing.status === 'granted'` before calling `mailer.sync(uid)`. Declining the marketing checkbox means the user is created normally, gets transactional emails, but is NEVER added to SendGrid / Beehiiv marketing lists.
 
 ### 2. Account-page toggle (Phase D)

package/package.json

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

package/src/manager/routes/user/signup/post.js

@@ -61,7 +61,7 @@ module.exports = async ({ assistant, user, settings, libraries }) => {
   // 4. Gather all data, then write once
   const email = user.auth.email;
   const inferred = await inferUserContact(assistant, email);
-  const userRecord = buildUserRecord(assistant, settings, inferred, authUser.metadata.creationTime);
+  const userRecord = buildUserRecord(assistant, settings, inferred, authUser.metadata.creationTime, userDoc);
 
   assistant.log(`signup(): Writing user record for ${uid}`, userRecord);
 
@@ -113,15 +113,10 @@ async function pollForUserDoc(assistant, uid) {
 /**
  * Build the full user record: client details, attribution, and inferred contact
  */
-function buildUserRecord(assistant, settings, inferred, creationTime) {
+function buildUserRecord(assistant, settings, inferred, creationTime, existingDoc) {
   const Manager = assistant.Manager;
   const attribution = settings.attribution;
 
-  // Legacy support: if affiliateCode exists, normalize to new format
-  if (settings.affiliateCode && !attribution.affiliate?.code) {
-    attribution.affiliate = { code: settings.affiliateCode };
-  }
-
   const record = {
     flags: {
       signupProcessed: true,
@@ -138,7 +133,7 @@ function buildUserRecord(assistant, settings, inferred, creationTime) {
       },
     },
     attribution: attribution || {},
-    consent: buildConsentRecord(assistant, settings.consent, creationTime),
+    consent: buildConsentRecord(assistant, settings.consent, creationTime, existingDoc?.consent),
     metadata: Manager.Metadata().set({ tag: 'user/signup' }),
   };
 
@@ -184,7 +179,7 @@ function buildUserRecord(assistant, settings, inferred, creationTime) {
  * record what the client sent, but the route will not have reached this point in practice
  * (the signup-form HTML5-requires the legal checkbox).
  */
-function buildConsentRecord(assistant, clientConsent, creationTime) {
+function buildConsentRecord(assistant, clientConsent, creationTime, existingConsent) {
   const consent = clientConsent || {};
   const ip = assistant.request.geolocation?.ip || null;
 
@@ -202,7 +197,7 @@ function buildConsentRecord(assistant, clientConsent, creationTime) {
   const legalGranted = consent.legal?.granted === true;
   const legalText = typeof consent.legal?.text === 'string' ? consent.legal.text : null;
 
-  const legal = legalGranted
+  let legal = legalGranted
     ? {
       status: 'granted',
       grantedAt: { timestamp, timestampUNIX, source: 'signup', ip, text: legalText },
@@ -216,7 +211,7 @@ function buildConsentRecord(assistant, clientConsent, creationTime) {
   const marketingGranted = consent.marketing?.granted === true;
   const marketingText = typeof consent.marketing?.text === 'string' ? consent.marketing.text : null;
 
-  const marketing = marketingGranted
+  let marketing = marketingGranted
     ? {
       status: 'granted',
       grantedAt: { timestamp, timestampUNIX, source: 'signup', ip, text: marketingText },
@@ -229,6 +224,19 @@ function buildConsentRecord(assistant, clientConsent, creationTime) {
       revokedAt: { timestamp, timestampUNIX, source: 'signup', ip, text: null },
     };
 
+  // Never DOWNGRADE an existing granted consent. A legacy account (signed up before this
+  // flow, flags.signupProcessed never set) re-fires /user/signup on page load with empty
+  // consent — which would compute status 'revoked' above and, on a {merge:true} write, wipe
+  // out the consent they actually granted months ago. If the existing doc already has a
+  // consent granted and the incoming payload doesn't explicitly re-grant it, preserve the
+  // existing record. A genuine new grant or an at-signup decline (no prior grant) still applies.
+  if (existingConsent?.legal?.status === 'granted' && legal.status !== 'granted') {
+    legal = existingConsent.legal;
+  }
+  if (existingConsent?.marketing?.status === 'granted' && marketing.status !== 'granted') {
+    marketing = existingConsent.marketing;
+  }
+
   assistant.log(`buildConsentRecord: legal=${legal.status}, marketing=${marketing.status} (raw input legal.granted=${consent.legal?.granted}, marketing.granted=${consent.marketing?.granted})`);
 
   return { legal, marketing };
@@ -262,9 +270,7 @@ async function inferUserContact(assistant, email) {
  */
 async function processAffiliate(assistant, uid, email, settings) {
   const { admin } = assistant.Manager.libraries;
-  const affiliateCode = settings.attribution?.affiliate?.code
-    || settings.affiliateCode
-    || null;
+  const affiliateCode = settings.attribution?.affiliate?.code || null;
 
   if (!affiliateCode) {
     return;

package/src/manager/schemas/user/signup/post.js

@@ -4,11 +4,6 @@ module.exports = ({ user }) => ({
     default: user?.auth?.uid,
     required: false,
   },
-  affiliateCode: {
-    types: ['string'],
-    default: undefined,
-    required: false,
-  },
   attribution: {
     types: ['object'],
     default: {},
@@ -19,9 +14,18 @@ module.exports = ({ user }) => ({
     default: {},
     required: false,
   },
+  // Consent decision captured at signup. Each sub-object is OPTIONAL — if the client omits
+  // `legal`/`marketing` (e.g. a legacy account re-firing /user/signup on page load with no
+  // fresh consent), the route leaves that consent untouched rather than downgrading it.
+  // When present, `granted` is the decision and `text` is the exact copy shown to the user.
   consent: {
-    types: ['object'],
-    default: {},
-    required: false,
+    legal: {
+      granted: { types: ['boolean'], required: false },
+      text: { types: ['string'], required: false },
+    },
+    marketing: {
+      granted: { types: ['boolean'], required: false },
+      text: { types: ['string'], required: false },
+    },
   },
 });

package/src/test/test-accounts.js

@@ -193,6 +193,18 @@ const STATIC_ACCOUNTS = {
       subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
+  // Used to verify the never-downgrade guard: the test seeds this account's doc with already-
+  // granted consent, then re-fires /user/signup with an empty consent payload and asserts the
+  // grant is preserved (not flipped to revoked). Dedicated account so the seeded state is isolated.
+  'consent-preserve': {
+    id: 'consent-preserve',
+    uid: '_test-consent-preserve',
+    email: '_test.consent-preserve@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
 };
 
 /**

package/test/routes/user/signup.js

@@ -347,6 +347,95 @@ module.exports = {
       },
     },
 
+    // --- Consent downgrade-protection tests ---
+    // Guards against data loss when a LEGACY account (signed up before the flags.signupProcessed
+    // flow existed, so flag never set) re-fires /user/signup on page load. Its localStorage
+    // consent is long gone, so the payload is empty — without the guard, buildConsentRecord
+    // would compute 'revoked' and the {merge:true} write would wipe the consent the user
+    // actually granted months ago. The guard preserves any existing 'granted' status.
+    {
+      name: 'consent-empty-payload-preserves-existing-grant',
+      async run({ http, firestore, assert, accounts }) {
+        const uid = accounts['consent-preserve'].uid;
+
+        // Seed the doc as an established account whose consent is already granted (as a real
+        // legacy signup would be after the OMEGA migration backfilled consent). flags is left
+        // at the schema default (signupProcessed: false) to mimic the legacy state exactly.
+        // merge:true — preserve the runner-provisioned auth.uid (pollForUserDoc needs it).
+        await firestore.set(`users/${uid}`, {
+          consent: {
+            legal: {
+              status: 'granted',
+              grantedAt: { timestamp: '2025-01-01T00:00:00.000Z', timestampUNIX: 1735689600, source: 'signup', ip: null, text: 'Legacy legal grant' },
+            },
+            marketing: {
+              status: 'granted',
+              grantedAt: { timestamp: '2025-01-01T00:00:00.000Z', timestampUNIX: 1735689600, source: 'signup', ip: null, text: 'Legacy marketing grant' },
+              revokedAt: { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null },
+            },
+          },
+          flags: { signupProcessed: false },
+        }, { merge: true });
+
+        // Re-fire signup with NO consent payload (the legacy page-load case).
+        const signupResponse = await http.as('consent-preserve').post('user/signup', {});
+        assert.isSuccess(signupResponse, `Signup should succeed: ${JSON.stringify(signupResponse, null, 2)}`);
+
+        const userDoc = await firestore.get(`users/${uid}`);
+
+        // CRITICAL: the prior grants must survive — NOT be downgraded to revoked.
+        assert.equal(userDoc?.consent?.legal?.status, 'granted', 'legal.status must stay granted (not downgraded by empty payload)');
+        assert.equal(userDoc?.consent?.legal?.grantedAt?.text, 'Legacy legal grant', 'legal grantedAt must be the preserved original, not wiped');
+        assert.equal(userDoc?.consent?.legal?.grantedAt?.timestampUNIX, 1735689600, 'legal grantedAt timestamp must be preserved');
+
+        assert.equal(userDoc?.consent?.marketing?.status, 'granted', 'marketing.status must stay granted (not downgraded by empty payload)');
+        assert.equal(userDoc?.consent?.marketing?.grantedAt?.text, 'Legacy marketing grant', 'marketing grantedAt must be the preserved original');
+        // No spurious revokedAt should have been stamped over the preserved grant.
+        assert.equal(userDoc?.consent?.marketing?.revokedAt?.timestamp, null, 'marketing revokedAt must stay null (no decline was recorded)');
+
+        // signupProcessed should now be flipped true by this run.
+        assert.equal(userDoc?.flags?.signupProcessed, true, 'signupProcessed should be set true after the run');
+      },
+    },
+    {
+      name: 'consent-explicit-decline-does-not-downgrade-existing-grant',
+      async run({ http, firestore, assert, accounts }) {
+        const uid = accounts['consent-preserve'].uid;
+
+        // Re-seed: granted marketing + UNSET signupProcessed so the route processes this call.
+        // Then send a payload that explicitly DECLINES marketing. The guard must still preserve
+        // the existing grant — only an explicit RE-GRANT may overwrite; a decline-over-grant on
+        // the signup path is treated as a non-grant and must not wipe a prior consent.
+        // merge:true — preserve the runner-provisioned auth.uid (pollForUserDoc needs it).
+        await firestore.set(`users/${uid}`, {
+          consent: {
+            marketing: {
+              status: 'granted',
+              grantedAt: { timestamp: '2025-01-01T00:00:00.000Z', timestampUNIX: 1735689600, source: 'signup', ip: null, text: 'Prior marketing grant' },
+              revokedAt: { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null },
+            },
+          },
+          flags: { signupProcessed: false },
+        }, { merge: true });
+
+        const signupResponse = await http.as('consent-preserve').post('user/signup', {
+          consent: {
+            legal: { granted: true, text: 'Legal grant on re-fire' },
+            marketing: { granted: false, text: 'Declining marketing' },
+          },
+        });
+        assert.isSuccess(signupResponse, `Signup should succeed: ${JSON.stringify(signupResponse, null, 2)}`);
+
+        const userDoc = await firestore.get(`users/${uid}`);
+
+        // Legal newly granted this call.
+        assert.equal(userDoc?.consent?.legal?.status, 'granted', 'legal.status should be granted from this call');
+        // Marketing was already granted; an explicit decline must NOT downgrade it.
+        assert.equal(userDoc?.consent?.marketing?.status, 'granted', 'marketing.status must stay granted (decline cannot downgrade an existing grant on signup path)');
+        assert.equal(userDoc?.consent?.marketing?.grantedAt?.text, 'Prior marketing grant', 'marketing grant must be the preserved original');
+      },
+    },
+
     // --- Auth rejection test (at end per convention) ---
     {
       name: 'unauthenticated-rejected',