@proteinjs/user-server 1.18.0 → 1.19.0

package/src/authorization/UserActivityStamp.ts

@@ -1,39 +1,41 @@
 import moment from 'moment';
 import { getDbAsSystem } from '@proteinjs/db';
 import { Logger } from '@proteinjs/logger';
-import { tables, type User, type UserActivity } from '@proteinjs/user';
+import { guestUser, tables, type User, type UserActivity } from '@proteinjs/user';
 
 /**
  * Writes the LAST-ACTIVITY presence stamp (`user_activity`, one row per user — see
- * UserActivityTable's contract): "this human made an interactive request just now".
+ * UserActivityTable's contract): "this person gave a page input just now".
  *
- * The TRANSPORT keying lives at the call site — userCache.create runs once per session-cookie
- * request (wrapRoute's session-cache build) and only there, so seeded/background contexts
- * (runInUserScope sets session data directly) structurally never reach this class. What this
- * class owns is the ACCOUNT predicate: machine accounts (`isLoadedFromSource`) are refused —
- * their requests do arrive over real sessions (e.g. the error bridge's polling), but a machine
- * logging in is not a person being present.
+ * The INPUT keying lives at the call site — the UserPresence service is the only caller, and
+ * the page reports through it only from a real pointer / key / touch / wheel event. The
+ * per-request session build (userCache.create) does NOT call this: it runs for every request
+ * over a session cookie, and that transport is what an idle tab produces all day (polls, socket
+ * re-joins on reconnect, the reload a deploy pushes) — presence keyed on it read every user as
+ * "active today" (founder finding 2026-09-12). What this class owns is the ACCOUNT predicate:
+ * the guest identity and machine accounts (`machine` — the one owner of "is this a machine",
+ * founder ruling 2026-09-02) are refused, whatever door they arrive through.
  *
  * Write behavior mirrors DbSessionStore's touch: throttled per user (a presence fact consumed at
- * day grain needs no finer cadence, and an unthrottled stamp would put a write on EVERY request),
- * fail-open (a lost stamp is a few minutes of staleness, never a failed request — the returned
- * promise NEVER rejects), and race-tolerant (concurrent first stamps contend on the scope-unique
- * index; the loser's error is swallowed as debug).
+ * day grain needs no finer cadence, and the page already throttles its reports — this is the
+ * belt), fail-open (a lost stamp is a few minutes of staleness, never a failed call — the
+ * returned promise NEVER rejects), and race-tolerant (concurrent first stamps contend on the
+ * scope-unique index; the loser's error is swallowed as debug).
  */
 export class UserActivityStamp {
   /** Stamp at most this often per user — same cadence class as DbSessionStore.TOUCH_INTERVAL. */
   private static readonly STAMP_INTERVAL_MS = 1000 * 60 * 5;
-  /** Process-wide: userCache is a plain object, so throttle state can't live per-instance. */
+  /** Process-wide: the throttle outlives any one service instance. */
   private static lastStampMs = new Map<string, number>();
 
   private logger = new Logger({ name: this.constructor.name });
 
   /**
-   * Record that `user` is present on an interactive request. Fire-and-forget safe: errors are
-   * handled (and logged) here, so callers may `void` the returned promise.
+   * Record that `user` gave a page human input. Fire-and-forget safe: errors are handled (and
+   * logged) here, so callers may `void` the returned promise.
    */
-  recordInteractiveRequest(user: User): Promise<void> {
-    if (!user.id || user.isLoadedFromSource === true) {
+  recordHumanInput(user: Pick<User, 'id' | 'machine'>): Promise<void> {
+    if (!user.id || user.id === guestUser.id || user.machine === true) {
       return Promise.resolve();
     }
     const last = UserActivityStamp.lastStampMs.get(user.id) ?? 0;
@@ -46,9 +48,9 @@ export class UserActivityStamp {
       UserActivityStamp.lastStampMs.clear(); // bounded memory; worst case is one extra stamp per user
     }
     return this.upsert(user.id).catch((error) => {
-      // Contention (a concurrent request stamped first, racing the scope-unique index) and real
-      // failures land here alike; both are harmless to the request. Un-throttle so the next
-      // request retries instead of waiting out a full interval on a stamp that never landed.
+      // Contention (a concurrent report stamped first, racing the scope-unique index) and real
+      // failures land here alike; both are harmless to the caller. Un-throttle so the next
+      // report retries instead of waiting out a full interval on a stamp that never landed.
       UserActivityStamp.lastStampMs.delete(user.id);
       this.logger.error({ message: 'Failed to write user activity stamp', error });
     });

package/src/authorization/userCache.ts

@@ -4,11 +4,18 @@ import { getDbAsSystem } from '@proteinjs/db';
 import { Logger } from '@proteinjs/logger';
 import { User, tables, guestUser, USER_SESSION_CACHE_KEY } from '@proteinjs/user';
 import { DefaultAdminCredentials } from '../authentication/DefaultAdminCredentials';
-import { UserActivityStamp } from './UserActivityStamp';
 
 const logger = new Logger({ name: 'userCache' });
-const userActivityStamp = new UserActivityStamp();
 
+/**
+ * The per-request session-cache build: resolves the session's email to the account row every
+ * request that rides a session cookie (wrapRoute), and every socket event (util-server's
+ * SocketSessionContext). It resolves IDENTITY only — it does not write the presence stamp
+ * (`user_activity`, UserActivityTable's contract): this build runs for an idle tab's polls, a
+ * socket's room re-joins on every reconnect, the reload a deploy pushes onto every open tab —
+ * transport, not a person. Presence is written from the page's human-input report alone
+ * (UserPresence.recordPresence).
+ */
 export const userCache: SessionDataCache<User> = {
   key: USER_SESSION_CACHE_KEY,
   create: async (sessionId: string, userEmail: string): Promise<User> => {
@@ -40,13 +47,6 @@ export const userCache: SessionDataCache<User> = {
         } else if (accountUser) {
           delete (accountUser as any)['password'];
           user = accountUser;
-          // LAST ACTIVITY (human presence — UserActivityTable's contract): stamped HERE because
-          // this cache build runs exactly once per session-cookie request (wrapRoute), i.e. only
-          // for interactive transport. Background/seeded contexts (runInUserScope) set session
-          // data directly and never pass through, so machinery acting as the user structurally
-          // cannot stamp; the stamp itself refuses machine accounts. Fire-and-forget: the
-          // returned promise never rejects, and a request never waits on its own stamp.
-          void userActivityStamp.recordInteractiveRequest(user);
         } else {
           // A session can outlive its account (row deleted, or a dev auto-login for a never-created
           // email). Resolve it to the unauthenticated guest session — the client sees no

package/src/services/UserPresence.ts

@@ -0,0 +1,26 @@
+import { Service } from '@proteinjs/service';
+import { UserPresenceService, UserRepo, type User } from '@proteinjs/user';
+import { UserActivityStamp } from '../authorization/UserActivityStamp';
+
+/**
+ * The server end of the human-input presence door (UserActivityTable's contract): the page
+ * reports "a person interacted just now" and this writes the `user_activity` stamp for the
+ * CALLING user — the one write path onto presence. Any signed-in user may report their own
+ * presence and nobody else's (the user is the session's, never an argument); the guest identity
+ * and machine accounts are refused inside the stamp. `doNotAwait`: the page never waits on its
+ * own stamp, and a lost stamp is minutes of staleness at day grain, never a failed call.
+ */
+export class UserPresence implements UserPresenceService {
+  public serviceMetadata: Service['serviceMetadata'] = {
+    auth: {
+      allUsers: true,
+    },
+    doNotAwait: true,
+  };
+
+  private stamp = new UserActivityStamp();
+
+  async recordPresence(): Promise<void> {
+    await this.stamp.recordHumanInput(new UserRepo().getUser() as Pick<User, 'id' | 'machine'>);
+  }
+}

package/test/UserActivityStamp.integration.test.ts

@@ -1,8 +1,8 @@
 import moment from 'moment';
 import { getDbAsSystem } from '@proteinjs/db';
-import { tables, type User, type UserActivity } from '@proteinjs/user';
-import { userCache } from '../src/authorization/userCache';
+import { guestUser, tables, type User, type UserActivity } from '@proteinjs/user';
 import { UserActivityStamp } from '../src/authorization/UserActivityStamp';
+import { UserPresence } from '../src/services/UserPresence';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 
 const testEnv = new UserServerTestEnvironment();
@@ -16,26 +16,15 @@ const stampInternals = (stamp: UserActivityStamp) => (stamp as unknown as StampI
 const activityRows = async (scope: string): Promise<UserActivity[]> =>
   await getDbAsSystem().query(tables.UserActivity, { scope });
 
-/** The stamp write is fire-and-forget off userCache — poll the OUTCOME (row present) briefly. */
-const waitForActivityRow = async (scope: string): Promise<UserActivity> => {
-  for (let attempt = 0; attempt < 50; attempt++) {
-    const rows = await activityRows(scope);
-    if (rows.length > 0) {
-      return rows[0];
-    }
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-  throw new Error(`No user_activity row appeared for scope ${scope}`);
-};
-
 /**
- * LAST ACTIVITY = HUMAN PRESENCE (UserActivityTable's contract): the stamp fires from
- * userCache.create — the once-per-interactive-request session-cache build — and from nowhere
- * else. These tests pin the seam's outcomes: a human's request lands the presence row; machine
- * accounts (real sessions, e.g. the error bridge's polling login) never do; repeated stamps
- * keep ONE row per user; the throttle holds writes to the interval.
+ * LAST ACTIVITY = HUMAN PRESENCE (UserActivityTable's contract): the stamp is written from the
+ * page's human-input report — the UserPresence service door — and from nowhere else (the
+ * session build's non-stamp is pinned in UserCacheDoesNotStampPresence). These tests pin the
+ * door's outcomes: a person's report lands the presence row for the CALLING user; machine
+ * accounts and the guest identity never do; repeated reports keep ONE row per user; the
+ * throttle holds writes to the interval.
  */
-describe('UserActivityStamp — interactive presence', () => {
+describe('UserActivityStamp — human-input presence', () => {
   beforeAll(async () => {
     await testEnv.beforeAll();
   });
@@ -49,34 +38,36 @@ describe('UserActivityStamp — interactive presence', () => {
     stampInternals(new UserActivityStamp()).lastStampMs.clear();
   });
 
-  it('stamps presence when a signed-in human makes an interactive request (through userCache.create)', async () => {
+  it('the presence door stamps the calling user: a page report under her session lands her row', async () => {
     const user = await testEnv.createUser({ name: 'Present Human', email: 'present-human@test.local' });
+    testEnv.actAs(user);
 
-    const resolved = await userCache.create('interactive-session', user.email);
-    expect(resolved.id).toBe(user.id);
+    await new UserPresence().recordPresence();
 
-    const row = await waitForActivityRow(user.id);
-    expect(moment(row.lastActiveAt).isAfter(moment().subtract(1, 'minute'))).toBe(true);
+    const rows = await activityRows(user.id);
+    expect(rows).toHaveLength(1);
+    expect(moment(rows[0].lastActiveAt).isAfter(moment().subtract(1, 'minute'))).toBe(true);
   });
 
-  it('keeps ONE row per user and advances it on later stamps (scope-unique invariant)', async () => {
+  it('keeps ONE row per user and advances it on later reports (scope-unique invariant)', async () => {
     const user = await testEnv.createUser({ name: 'Returning Human', email: 'returning-human@test.local' });
     const stamp = new UserActivityStamp();
 
-    await stamp.recordInteractiveRequest(user);
-    const first = await waitForActivityRow(user.id);
+    await stamp.recordHumanInput(user);
+    const [first] = await activityRows(user.id);
+    expect(first).toBeDefined();
 
-    // Clear the throttle so the second request stamps immediately.
+    // Clear the throttle so the second report stamps immediately.
     stampInternals(stamp).lastStampMs.clear();
     await new Promise((resolve) => setTimeout(resolve, 5));
-    await stamp.recordInteractiveRequest(user);
+    await stamp.recordHumanInput(user);
 
     const rows = await activityRows(user.id);
     expect(rows).toHaveLength(1);
     expect(moment(rows[0].lastActiveAt).valueOf()).toBeGreaterThanOrEqual(moment(first.lastActiveAt).valueOf());
   });
 
-  it('never stamps a machine account, even though its requests ride a real session', async () => {
+  it('never stamps a machine account (`machine` — the one owner of "is this a machine"), even through the door', async () => {
     const machine = await getDbAsSystem().insert(tables.User, {
       name: 'Ops machine',
       email: 'stamp-machine@test.local',
@@ -84,39 +75,36 @@ describe('UserActivityStamp — interactive presence', () => {
       emailVerified: true,
       roles: [],
       isLoadedFromSource: true,
+      machine: true,
     } as unknown as User);
 
-    // Await the stamp DIRECTLY (deterministic absence — no fire-and-forget race), then confirm
-    // the transport seam agrees by resolving the machine session through userCache too.
-    await new UserActivityStamp().recordInteractiveRequest(machine);
-    const resolved = await userCache.create('machine-session', machine.email);
-    expect(resolved.id).toBe(machine.id);
-    await new Promise((resolve) => setTimeout(resolve, 300));
+    await new UserActivityStamp().recordHumanInput(machine);
+    testEnv.actAs(machine);
+    await new UserPresence().recordPresence();
 
     expect(await activityRows(machine.id)).toHaveLength(0);
   });
 
-  it('throttles: a second request inside the interval writes nothing', async () => {
+  it('never stamps the guest identity (a door reached with no signed-in user)', async () => {
+    const before = (await getDbAsSystem().query(tables.UserActivity, {})).length;
+    await new UserActivityStamp().recordHumanInput(guestUser);
+    expect((await getDbAsSystem().query(tables.UserActivity, {})).length).toBe(before);
+  });
+
+  it('throttles: a second report inside the interval writes nothing', async () => {
     const user = await testEnv.createUser({ name: 'Rapid Human', email: 'rapid-human@test.local' });
     const stamp = new UserActivityStamp();
 
-    await stamp.recordInteractiveRequest(user);
-    const first = await waitForActivityRow(user.id);
+    await stamp.recordHumanInput(user);
+    const [first] = await activityRows(user.id);
+    expect(first).toBeDefined();
 
-    // Throttle history now holds this user; a second stamp inside the interval must not write.
-    await stamp.recordInteractiveRequest(user);
+    // Throttle history now holds this user; a second report inside the interval must not write.
+    await stamp.recordHumanInput(user);
     await new Promise((resolve) => setTimeout(resolve, 300));
 
     const rows = await activityRows(user.id);
     expect(rows).toHaveLength(1);
     expect(moment(rows[0].lastActiveAt).valueOf()).toBe(moment(first.lastActiveAt).valueOf());
   });
-
-  it('a session for a missing account still resolves guest and stamps nothing (no throw)', async () => {
-    const before = (await getDbAsSystem().query(tables.UserActivity, {})).length;
-    const resolved = await userCache.create('stale-session', 'no-such-account@test.local');
-    expect(resolved.id).toBe('guest');
-    await new Promise((resolve) => setTimeout(resolve, 200));
-    expect((await getDbAsSystem().query(tables.UserActivity, {})).length).toBe(before);
-  });
 });

package/test/UserCacheDoesNotStampPresence.integration.test.ts

@@ -0,0 +1,44 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables, type UserActivity } from '@proteinjs/user';
+import { userCache } from '../src/authorization/userCache';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+const activityRows = async (scope: string): Promise<UserActivity[]> =>
+  await getDbAsSystem().query(tables.UserActivity, { scope });
+
+/**
+ * TRANSPORT IS NOT PRESENCE (UserActivityTable's contract; founder finding 2026-09-12 — every
+ * user on the admin usage page "last active today"). The per-request session-cache build
+ * (`userCache.create`) runs for EVERY request that rides a session cookie: an open tab's polls,
+ * a socket's room re-joins on every reconnect, the reload a deploy pushes onto every idle tab.
+ * None of that is a person. The build must therefore never write the presence stamp — the
+ * only door is the page's human-input report (UserPresence.recordPresence).
+ *
+ * Pre-fix, `userCache.create` stamped on every build: this test reads one row where the
+ * contract says none.
+ */
+describe('userCache.create — the session build does not stamp presence', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  it('resolving a human session (any request over a session cookie) writes NO user_activity row', async () => {
+    const user = await testEnv.createUser({ name: 'Idle Tab', email: 'idle-tab@test.local' });
+
+    // Three request-shaped builds: a poll, a reconnect re-join, a deploy reload — all the same seam.
+    for (const sessionId of ['poll', 'socket-rejoin', 'deploy-reload']) {
+      const resolved = await userCache.create(sessionId, user.email);
+      expect(resolved.id).toBe(user.id);
+    }
+    // The pre-fix stamp was fire-and-forget off the build — give it every chance to land.
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    expect(await activityRows(user.id)).toHaveLength(0);
+  });
+});