From 09f1e27c512535c6f5d5a34d59e2e160e0a59fa9 Mon Sep 17 00:00:00 2001
From: Muhammad Saffi Ullah <42832684+saffiullah200@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:25:02 +0200
Subject: [PATCH] feat: add lastOpenedAt field for accurate app-open tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces a dedicated User.lastOpenedAt timestamp that updates ONLY on real
app-open events (sign-in, social sign-ins, token refresh). Separates "user
actually opened the app" from the existing lastActivityTime field, which is
set on every authenticated API call and was the cause of the May 2026 bulk-
update incident that mass-marked users as Active in Salesforce.

Schema:
  • models/user.js: add `lastOpenedAt: { type: Date, default: null }`

App-open write sites (5 routes, all set both lastLogin and lastOpenedAt):
  • routes/auth/sign-in.js
  • routes/auth/apple-sign-in.js
  • routes/auth/google-sign-in.js
  • routes/auth/facebook-sign-in.js
  • routes/auth/generate-token.js (token refresh = app reopen)

Each write emits a `[app-open]` console log line for audit.

NOT set in:
  • middleware (helpers/index.js) — would recreate the lastActivityTime trap
  • admin scripts in src/scripts/db/
  • the AWS Lambda sync (sync-users does not write this field)

Docs + verification tooling:
  • models/LASTOPENEDAT.md — operating doc
  • scripts/verify-last-opened-at.js — Mongo-side verification script
    (snapshot mode + --watch mode for manual sign-in testing)

Salesforce mapping (handled in AWS Lambda repo, not here):
  Mongo `lastOpenedAt` → SF `Contact.Last_App_Opened_At__c`
  with the omit-when-absent pattern so a future backfill cannot recreate the
  May 2026 mass-overwrite issue.

Note: the production API was hot-deployed with these changes earlier this week
to unblock the SF User Status migration; this PR brings the code into git.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/models/LASTOPENEDAT.md           | 116 +++++++++++++++++++++++++++
 src/models/user.js                   |   9 +++
 src/routes/auth/apple-sign-in.js     |  14 ++--
 src/routes/auth/facebook-sign-in.js  |  14 ++--
 src/routes/auth/generate-token.js    |  14 ++++
 src/routes/auth/google-sign-in.js    |  16 ++--
 src/routes/auth/sign-in.js           |  12 ++-
 src/scripts/verify-last-opened-at.js | 105 ++++++++++++++++++++++++
 8 files changed, 280 insertions(+), 20 deletions(-)
 create mode 100644 src/models/LASTOPENEDAT.md
 create mode 100644 src/scripts/verify-last-opened-at.js

diff --git a/src/models/LASTOPENEDAT.md b/src/models/LASTOPENEDAT.md
new file mode 100644
index 00000000..44867988
--- /dev/null
+++ b/src/models/LASTOPENEDAT.md
@@ -0,0 +1,116 @@
+# `lastOpenedAt` — operating notes
+
+## What it is
+
+A Date field on the `User` schema that tracks **real app-open events** — when an
+authenticated user genuinely opens or re-opens the AXS Map app.
+
+Distinct from existing fields:
+
+| Field | When set | Semantics |
+|---|---|---|
+| `lastLogin` | Sign-in flows | Last successful password / social sign-in |
+| `lastActivityTime` | ⚠️ **Every authenticated API call** (`helpers/index.js:isAuthenticated`) | Way too noisy — every background poll updates this. Source of the May 2026 user-status bug. |
+| **`lastOpenedAt`** | **Sign-in flows + token refresh** | Real app-open signal. Used by future Salesforce User Status logic. |
+
+## Where it IS set (only these places)
+
+| File | When |
+|---|---|
+| `routes/auth/sign-in.js` | Successful email+password sign-in |
+| `routes/auth/apple-sign-in.js` | Successful Apple sign-in (new or existing user) |
+| `routes/auth/google-sign-in.js` | Successful Google sign-in (new or existing user) |
+| `routes/auth/facebook-sign-in.js` | Successful Facebook sign-in (new or existing user) |
+| `routes/auth/generate-token.js` | Successful refresh-token → new JWT (the AXS Map app was re-opened after the previous JWT expired) |
+
+Every update logs to stdout:
+```
+[app-open] sign-in: userId=<id> lastOpenedAt=2026-05-23T18:00:00.000Z
+[app-open] google-sign-in (existing): userId=<id> lastOpenedAt=...
+[app-open] token-refresh: userId=<id> lastOpenedAt=...
+```
+
+This is the audit trail — easy to grep for in CloudWatch / log aggregators.
+
+## Where it is NOT set (and must NEVER be set)
+
+- ❌ `helpers/index.js:isAuthenticated` middleware — this was the trap with
+  `lastActivityTime`. Setting any "user activity" field on every API request
+  means even silent background polling counts as activity. **Do not extend this.**
+- ❌ Any of the AWS Lambda sync functions (`axs-map-sync-users` etc.) — they
+  don't read or write this field. Confirmed by code grep.
+- ❌ Admin bulk scripts in `src/scripts/db/*` — `import-users.js`,
+  `update-users-avatars.js`, `migrate-scores.js` — none touch this field.
+- ❌ MongoDB Atlas Triggers — they fire change events to AWS EventBridge but
+  don't update the source doc.
+- ❌ Salesforce → MongoDB direction — there is no sync in that direction today.
+
+## How to verify before/after a deploy
+
+```bash
+cd "/Users/saffiullah/AXS Map API"
+
+# Snapshot — read schema definition and population counts
+node src/scripts/verify-last-opened-at.js
+
+# Watch a specific user in real time (do this BEFORE signing in via the app):
+node src/scripts/verify-last-opened-at.js --watch --user me@example.com
+
+# Then sign in via the app or POST /auth/sign-in. You should see a single line:
+#   [<time>] lastOpenedAt changed: <old> → <new>
+# If you see multiple updates from a single sign-in, or updates with no sign-in,
+# something else is writing the field — find and remove the writer.
+```
+
+## Salesforce side
+
+The matching SF field already exists:
+
+| SF Object | Field | Type | Population (as of 2026-05-23) |
+|---|---|---|---|
+| `Contact` | `Last_App_Opened_At__c` | Date/Time | 0 Contacts populated |
+
+It exists but is **not yet synced** — per this ticket's scope ("Do not change
+Salesforce User Status logic in this ticket"), the Lambda is NOT mapping
+`lastOpenedAt` → `Last_App_Opened_At__c` yet. Seeding now would let the User
+Status flow start consuming it, which is the next ticket's work.
+
+When the next ticket lands, it must:
+
+1. **Add FLS to the integration's permission set.** The Lambda's run-as user
+   uses `AXS_Map_AWS_Lambda_Integration` perm set, which currently has **no**
+   FLS for `Last_App_Opened_At__c`. Without this, the sync would fail with
+   `INSUFFICIENT_ACCESS`. The deploy is one block in:
+   `force-app/main/default/permissionsets/AXS_Map_AWS_Lambda_Integration.permissionset-meta.xml`
+
+   ```xml
+   <fieldPermissions>
+       <editable>true</editable>
+       <field>Contact.Last_App_Opened_At__c</field>
+       <readable>true</readable>
+   </fieldPermissions>
+   ```
+
+2. **Add the field to the Lambda payload** in
+   `/Users/saffiullah/AXS Map AWS/lambdas/sync-users/index.js:buildContact()`.
+   IMPORTANT: use the same omit-when-Mongo-absent pattern that was applied to
+   `lastActivityTime__c` in the recent fix — otherwise we'd recreate the May
+   2026 bulk-overwrite bug:
+
+   ```js
+   // Only include if Mongo has a value — never fall back to Date.now() or
+   // any default; omit the field entirely if Mongo has nothing to say.
+   const opened = core.toDateTime(document.lastOpenedAt);
+   if (opened) {
+     contact.Last_App_Opened_At__c = opened;
+     core.logDebug('users: setting Last_App_Opened_At__c from Mongo', { mongoId, value: opened });
+   }
+   ```
+
+3. **Run the audit script** to confirm the perm set now grants the field:
+   `node "/Users/saffiullah/AXS Map AWS/scripts/audit-lambda-perms.js"`
+
+4. **Update the User Status flow** to read `Last_App_Opened_At__c` instead of
+   `lastActivityTime__c`. The flow is at
+   `Setup → Flows → Welcome Email Trigger Flow on Contact` (or whichever
+   actually contains the active/inactive logic).
diff --git a/src/models/user.js b/src/models/user.js
index 6dd097ad..c015d7ad 100644
--- a/src/models/user.js
+++ b/src/models/user.js
@@ -145,6 +145,15 @@ const userSchema = new mongoose.Schema(
       type: Date,
       default: null,
     },
+    // Tracks REAL app-open events only (sign-in, social sign-in, token refresh).
+    // Intentionally NOT touched by middleware/syncs/admin scripts — see ticket
+    // "Add Mongo lastOpenedAt Field and Prepare Salesforce User Status Migration".
+    // Salesforce User Status logic will eventually migrate from lastActivityTime
+    // to this field. Do NOT set this from background jobs.
+    lastOpenedAt: {
+      type: Date,
+      default: null,
+    },
     lastLocation: {
       type: {
         lat: {
diff --git a/src/routes/auth/apple-sign-in.js b/src/routes/auth/apple-sign-in.js
index 9bbdc1fa..17763afa 100644
--- a/src/routes/auth/apple-sign-in.js
+++ b/src/routes/auth/apple-sign-in.js
@@ -27,28 +27,32 @@ module.exports = async (req, res, next) => {
     let user = await User.findOne({
       email: appleResponse?.email,
     });
+    const now = new Date();
     if (!user) {
       user = new User({
         email: appleResponse?.email,
         firstName:appleResponse?.fullName?.givenName ?? "",
         lastName:appleResponse?.fullName?.familyName ?? "",
         appleId: appleResponse?.sub,
-        lastLogin: new Date(),
+        lastLogin: now,
+        lastOpenedAt: now,
       });
 
       await user.save();
+      console.log(`[app-open] apple-sign-in (new): userId=${user._id} lastOpenedAt=${now.toISOString()}`);
     } else {
       // Check if user is archived
       if (user.isArchived) {
-        return res.status(403).json({ 
+        return res.status(403).json({
           error: "Account archived",
           isArchived: true,
           userId: user._id.toString()
         });
       }
-      
-      // Update lastLogin for existing users
-      await User.findByIdAndUpdate(user._id, { lastLogin: new Date() });
+
+      // Real app-open: update lastLogin AND lastOpenedAt for existing users
+      await User.findByIdAndUpdate(user._id, { lastLogin: now, lastOpenedAt: now });
+      console.log(`[app-open] apple-sign-in (existing): userId=${user._id} lastOpenedAt=${now.toISOString()}`);
     }
 
     const userId = user._id;
diff --git a/src/routes/auth/facebook-sign-in.js b/src/routes/auth/facebook-sign-in.js
index 42c44a86..c5c2592b 100644
--- a/src/routes/auth/facebook-sign-in.js
+++ b/src/routes/auth/facebook-sign-in.js
@@ -48,6 +48,7 @@ module.exports = async (req, res, next) => {
       const email = fbUser.email;
 
       let user = await User.findOne({ email: fbUser.email });
+      const now = new Date();
 
       if (!user) {
         const [firstName, lastName] = fbUser.name.split(" ");
@@ -57,22 +58,25 @@ module.exports = async (req, res, next) => {
           firstName: firstName || "",
           lastName: lastName || "",
           avatar: fbUser.picture.data.url,
-          lastLogin: new Date(),
+          lastLogin: now,
+          lastOpenedAt: now,
         });
 
         await user.save();
+        console.log(`[app-open] facebook-sign-in (new): userId=${user._id} lastOpenedAt=${now.toISOString()}`);
       } else {
         // Check if user is archived
         if (user.isArchived) {
-          return res.status(403).json({ 
+          return res.status(403).json({
             error: "Account archived",
             isArchived: true,
             userId: user._id.toString()
           });
         }
-        
-        // Update lastLogin for existing users
-        await User.findByIdAndUpdate(user._id, { lastLogin: new Date() });
+
+        // Real app-open: update both lastLogin and lastOpenedAt for existing users
+        await User.findByIdAndUpdate(user._id, { lastLogin: now, lastOpenedAt: now });
+        console.log(`[app-open] facebook-sign-in (existing): userId=${user._id} lastOpenedAt=${now.toISOString()}`);
       }
 
       const userId = user._id;
diff --git a/src/routes/auth/generate-token.js b/src/routes/auth/generate-token.js
index b6ff3e7e..bb30317a 100644
--- a/src/routes/auth/generate-token.js
+++ b/src/routes/auth/generate-token.js
@@ -2,6 +2,7 @@ const jwt = require("jsonwebtoken");
 const moment = require("moment");
 
 const { RefreshToken } = require("../../models/refresh-token");
+const { User } = require("../../models/user");
 
 const { validateGenerateToken } = require("./validations");
 
@@ -51,5 +52,18 @@ module.exports = async (req, res, next) => {
       expiresIn: '30d',
     }
   );
+
+  // Token refresh = the AXS Map app is being reopened (the user's previous
+  // JWT expired and the client is exchanging the long-lived refresh token).
+  // That's a real app-open event — set lastOpenedAt.
+  try {
+    const now = new Date();
+    await User.findByIdAndUpdate(refreshToken.userId, { lastOpenedAt: now });
+    console.log(`[app-open] token-refresh: userId=${refreshToken.userId} lastOpenedAt=${now.toISOString()}`);
+  } catch (err) {
+    console.log(`Failed to update lastOpenedAt on token refresh for userId ${refreshToken.userId}: ${err.message}`);
+    // Don't fail the token-refresh if the activity update fails
+  }
+
   return res.status(200).json({ token });
 };
diff --git a/src/routes/auth/google-sign-in.js b/src/routes/auth/google-sign-in.js
index 216a02a5..6bd86777 100644
--- a/src/routes/auth/google-sign-in.js
+++ b/src/routes/auth/google-sign-in.js
@@ -52,28 +52,32 @@ module.exports = async (req, res) => {
     const [firstName, lastName] = name.split(" ");
 
     let user = await User.findOne({ email });
+    const now = new Date();
     if (!user) {
       user = new User({
         email: email,
         firstName: firstName || name,
         lastName: lastName || "",
-        createdAt: new Date(),
+        createdAt: now,
         avatar: picture,
-        lastLogin: new Date(),
+        lastLogin: now,
+        lastOpenedAt: now,
       });
       await user.save();
+      console.log(`[app-open] google-sign-in (new): userId=${user._id} lastOpenedAt=${now.toISOString()}`);
     } else {
       // Check if user is archived
       if (user.isArchived) {
-        return res.status(403).json({ 
+        return res.status(403).json({
           error: "Account archived",
           isArchived: true,
           userId: user._id.toString()
         });
       }
-      
-      // Update lastLogin for existing users
-      await User.findByIdAndUpdate(user._id, { lastLogin: new Date() });
+
+      // Real app-open: update both lastLogin and lastOpenedAt for existing users
+      await User.findByIdAndUpdate(user._id, { lastLogin: now, lastOpenedAt: now });
+      console.log(`[app-open] google-sign-in (existing): userId=${user._id} lastOpenedAt=${now.toISOString()}`);
     }
 
     const token = jwt.sign({ userId: user._id }, process.env.JWT_SECRET, {
diff --git a/src/routes/auth/sign-in.js b/src/routes/auth/sign-in.js
index 3290057f..eceab529 100644
--- a/src/routes/auth/sign-in.js
+++ b/src/routes/auth/sign-in.js
@@ -46,12 +46,16 @@ module.exports = async (req, res, next) => {
 
   const userId = user.id;
 
-  // Update lastLogin timestamp
+  // Real app-open event: set both lastLogin and lastOpenedAt.
+  // lastOpenedAt powers the new user-status pipeline (replacing lastActivityTime).
+  // ONLY set here in real auth flows — never from middleware/syncs/admin scripts.
+  const now = new Date();
   try {
-    await User.findByIdAndUpdate(userId, { lastLogin: new Date() });
+    await User.findByIdAndUpdate(userId, { lastLogin: now, lastOpenedAt: now });
+    console.log(`[app-open] sign-in: userId=${userId} lastOpenedAt=${now.toISOString()}`);
   } catch (updateErr) {
-    console.log(`Failed to update lastLogin for userId ${userId}: ${updateErr.message}`);
-    // Continue with login even if lastLogin update fails
+    console.log(`Failed to update lastLogin/lastOpenedAt for userId ${userId}: ${updateErr.message}`);
+    // Continue with login even if the update fails
   }
 
   const today = moment.utc();
diff --git a/src/scripts/verify-last-opened-at.js b/src/scripts/verify-last-opened-at.js
new file mode 100644
index 00000000..0e5d471e
--- /dev/null
+++ b/src/scripts/verify-last-opened-at.js
@@ -0,0 +1,105 @@
+/**
+ * Verification script for the `lastOpenedAt` field.
+ *
+ * Use this to confirm that:
+ *   1. The User schema has the new lastOpenedAt field
+ *   2. The auth routes update it (run before+after a sign-in to observe)
+ *   3. No background process is silently writing it
+ *
+ * Usage:
+ *   node src/scripts/verify-last-opened-at.js [--watch] [--user <emailOrId>]
+ *
+ *   --watch         Print updates to lastOpenedAt every 5 seconds (use during manual test:
+ *                   start the watcher, then sign in via the app, observe the change)
+ *   --user X        Watch a specific user (email or Mongo _id). Default: most recently
+ *                   opened user.
+ *
+ * Env required:
+ *   MONGO_URI   Mongo connection string (same one the API uses)
+ */
+
+const mongoose = require("mongoose");
+
+require("dotenv").config(); // load .env if present
+const { User } = require("../models/user");
+
+const args = process.argv.slice(2);
+const WATCH = args.includes("--watch");
+const userArg = args[args.indexOf("--user") + 1];
+const userSelector = (args.indexOf("--user") >= 0 && userArg) ? userArg : null;
+
+async function findUser() {
+  if (userSelector) {
+    if (userSelector.match(/^[0-9a-f]{24}$/i)) {
+      return await User.findById(userSelector).lean();
+    }
+    return await User.findOne({ email: userSelector }).lean();
+  }
+  // Most recently opened user, or fall back to most recent login
+  return await User.findOne({ lastOpenedAt: { $ne: null } })
+    .sort({ lastOpenedAt: -1 })
+    .lean()
+    || await User.findOne().sort({ lastLogin: -1 }).lean();
+}
+
+async function snapshot() {
+  return {
+    totalUsers: await User.countDocuments({}),
+    withLastOpenedAt: await User.countDocuments({ lastOpenedAt: { $ne: null } }),
+    withLastActivityTime: await User.countDocuments({ lastActivityTime: { $ne: null } }),
+    withLastLogin: await User.countDocuments({ lastLogin: { $ne: null } }),
+  };
+}
+
+async function main() {
+  if (!process.env.MONGO_URI) {
+    console.error("ERROR: MONGO_URI env required");
+    process.exit(1);
+  }
+
+  await mongoose.connect(process.env.MONGO_URI);
+  console.log("Connected to Mongo");
+
+  // Confirm schema has the field
+  const paths = User.schema.paths;
+  if (!paths.lastOpenedAt) {
+    console.error("ERROR: User schema does not include lastOpenedAt. Update src/models/user.js");
+    process.exit(1);
+  }
+  console.log("Schema check: lastOpenedAt is", paths.lastOpenedAt.instance, paths.lastOpenedAt.options);
+
+  // Population stats
+  console.log("\nCurrent population stats:");
+  console.log(JSON.stringify(await snapshot(), null, 2));
+
+  const user = await findUser();
+  if (!user) {
+    console.log("\nNo user found to watch.");
+    await mongoose.disconnect();
+    return;
+  }
+
+  console.log("\nWatching user:", user._id.toString(),
+    " email:", user.email, " current lastOpenedAt:", user.lastOpenedAt);
+
+  if (!WATCH) {
+    console.log("\n(pass --watch to poll every 5s; useful while exercising sign-in via the app)");
+    await mongoose.disconnect();
+    return;
+  }
+
+  console.log("\nPolling every 5 seconds. Sign in via the app to trigger an update. Ctrl+C to stop.");
+  let last = user.lastOpenedAt ? user.lastOpenedAt.toISOString() : null;
+  setInterval(async () => {
+    const u = await User.findById(user._id).lean();
+    const cur = u.lastOpenedAt ? u.lastOpenedAt.toISOString() : null;
+    if (cur !== last) {
+      console.log(`[${new Date().toISOString()}] lastOpenedAt changed: ${last} → ${cur}`);
+      last = cur;
+    } else {
+      process.stdout.write(".");
+    }
+  }, 5000);
+}
+
+main().catch(e => { console.error("Fatal:", e); process.exit(1); });