@tumbaland/backend-core 1.41.0 → 1.43.0

package/src/groups/membership.ts

@@ -0,0 +1,133 @@
+import logger from '../logging/logger';
+import { internalGroupUrl } from './client';
+
+/**
+ * Which groups a person belongs to, asked of group-service.
+ *
+ * This used to travel in the session token's `groups` claim, which made it only
+ * as fresh as the token: a new member could not see the group until their next
+ * renewal, and a removed one kept access until theirs, which is why membership
+ * changes used to sign people out. Asked here instead, with a short cache, a
+ * change reaches every service within CACHE_TTL_MS.
+ *
+ * Every request pays for this only once per person per service per cache
+ * window; concurrent callers share one request.
+ */
+const CACHE_TTL_MS = 30_000;
+
+/** Bounded so a service under enumeration can't grow the cache without limit. */
+const MAX_CACHE_ENTRIES = 5_000;
+
+const REQUEST_TIMEOUT_MS = 3_000;
+
+interface CacheEntry {
+  groups: string[];
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+const inFlight = new Map<string, Promise<string[] | null>>();
+
+function putInCache(email: string, groups: string[]): void {
+  if (!cache.has(email) && cache.size >= MAX_CACHE_ENTRIES) {
+    // Map iterates in insertion order, so the first key is the oldest write.
+    const oldest = cache.keys().next();
+    if (!oldest.done) cache.delete(oldest.value);
+  }
+  cache.set(email, { groups, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+async function fetchUserGroupIds(email: string): Promise<string[] | null> {
+  const baseUrl = internalGroupUrl();
+  const token = process.env.INTERNAL_SERVICE_TOKEN;
+
+  if (!baseUrl || !token) {
+    logger.error('Group membership lookup not configured', {
+      hasGroupApiUrl: Boolean(baseUrl),
+      hasInternalToken: Boolean(token)
+    });
+    return null;
+  }
+
+  try {
+    const response = await fetch(`${baseUrl}/api/groups/mine/ids?userEmail=${encodeURIComponent(email)}`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-internal-token': token,
+        'x-service-id': process.env.SERVICE_NAME || 'unknown-service'
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+
+    if (!response.ok) {
+      logger.error('Group membership lookup failed', { email, status: response.status });
+      return null;
+    }
+
+    const body = (await response.json()) as { success?: boolean; data?: unknown };
+    if (!body.success || !Array.isArray(body.data)) {
+      logger.error('Group membership lookup returned no list', { email });
+      return null;
+    }
+    return body.data.filter((id): id is string => typeof id === 'string');
+  } catch (error) {
+    logger.error('Group membership lookup unreachable', { email, error: (error as Error)?.message });
+    return null;
+  }
+}
+
+/**
+ * The ids of the groups `email` belongs to right now.
+ *
+ * When group-service cannot be asked, the last answer is used even if it has
+ * expired, and failing that no groups at all: a person keeps their own data
+ * through an outage and loses group data until it ends, rather than being
+ * granted a group on a guess.
+ */
+export async function getUserGroupIds(email: string): Promise<string[]> {
+  const key = email.toLowerCase();
+  const entry = cache.get(key);
+  if (entry && entry.expiresAt > Date.now()) return entry.groups;
+
+  let pending = inFlight.get(key);
+  if (!pending) {
+    pending = fetchUserGroupIds(key).finally(() => inFlight.delete(key));
+    inFlight.set(key, pending);
+  }
+
+  const groups = await pending;
+  if (groups) {
+    putInCache(key, groups);
+    return groups;
+  }
+  if (entry) {
+    logger.warn('Using the last known group membership while group-service is unreachable', { email: key });
+    return entry.groups;
+  }
+  return [];
+}
+
+/** For tests. */
+export function clearMembershipCache(): void {
+  cache.clear();
+  inFlight.clear();
+}
+
+type MembershipLookup = (user: { email: string; groups?: string[] }) => Promise<string[]>;
+
+const lookUpMembership: MembershipLookup = (user) => getUserGroupIds(user.email);
+let membershipLookup: MembershipLookup = lookUpMembership;
+
+/** The groups the auth middlewares put on `req.userGroups`. */
+export const currentGroupsOf = (user: { email: string; groups?: string[] }): Promise<string[]> =>
+  membershipLookup(user);
+
+/**
+ * Replaces the lookup, for tests only; pass nothing to restore the real one.
+ * Service suites reach it through `@tumbaland/backend-core/testing`, which makes
+ * a test token's own `groups` claim the membership, so they need no group-service.
+ */
+export function overrideMembershipLookupForTests(lookup?: MembershipLookup): void {
+  membershipLookup = lookup ?? lookUpMembership;
+}

package/src/index.ts

@@ -39,6 +39,7 @@ export * from './audit';
 
 // Middleware
 export { authenticateToken, optionalAuth } from './middleware/authMiddleware';
+export { USER_SESSIONS_COLLECTION, isCurrentSession, isLegacySessionlessToken } from './auth/session';
 export {
   requireInternalServiceToken,
   internalServiceTokenBypass,

package/src/middleware/authMiddleware.test.ts

@@ -4,6 +4,12 @@ import { authenticateToken, optionalAuth } from './authMiddleware';
 import { PERSONAL_TENANT } from '../apiKeys/types';
 import { mintAccessToken } from '../oauth/tokens';
 import { UserPayload } from '../types/auth';
+import { overrideSessionCheckForTests } from '../auth/session';
+import { overrideMembershipLookupForTests } from '../groups/membership';
+
+// These tokens carry no session; the session check has its own tests below and in session.test.ts.
+beforeEach(() => overrideSessionCheckForTests(async () => true));
+afterAll(() => overrideSessionCheckForTests());
 
 function mockReq(overrides: Partial<Request> = {}): Request {
   return { cookies: {}, headers: {}, ...overrides } as unknown as Request;
@@ -31,75 +37,80 @@ describe('authenticateToken', () => {
 
   const payload: UserPayload = { id: '1', email: 'user@example.com', name: 'Test User' };
 
-  it('attaches the decoded user and calls next for a valid cookie token', () => {
+  it('attaches the decoded user and calls next for a valid cookie token', async () => {
     const token = jwt.sign(payload, 'test-secret');
     const req = mockReq({ cookies: { access_token: token } });
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(req.user).toMatchObject({ id: '1', email: 'user@example.com' });
   });
 
-  it('attaches an empty userGroups array when the token has no groups claim', () => {
+  it('attaches an empty userGroups array when the token has no groups claim', async () => {
     const token = jwt.sign(payload, 'test-secret');
     const req = mockReq({ cookies: { access_token: token } });
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(req.userGroups).toEqual([]);
   });
 
-  it('attaches userGroups from the token when present', () => {
-    const token = jwt.sign({ ...payload, groups: ['group-1', 'group-2'] }, 'test-secret');
+  it("takes the person's groups from group-service, not from the token", async () => {
+    const lookup = jest.fn(async () => ['live-group']);
+    overrideMembershipLookupForTests(lookup);
+    const token = jwt.sign({ ...payload, groups: ['stale-group'] }, 'test-secret');
     const req = mockReq({ cookies: { access_token: token } });
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
-    expect(req.userGroups).toEqual(['group-1', 'group-2']);
+    expect(lookup).toHaveBeenCalledWith(expect.objectContaining({ email: 'user@example.com' }));
+    expect(req.userGroups).toEqual(['live-group']);
+    expect(req.user?.groups).toEqual(['live-group']);
+    overrideMembershipLookupForTests();
   });
 
-  it('accepts a Bearer token from the Authorization header', () => {
+  it('accepts a Bearer token from the Authorization header', async () => {
     const token = jwt.sign(payload, 'test-secret');
     const req = mockReq({ headers: { authorization: `Bearer ${token}` } });
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(next).toHaveBeenCalledTimes(1);
   });
 
-  it('returns 401 when no token is present', () => {
+  it('returns 401 when no token is present', async () => {
     const req = mockReq();
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(next).not.toHaveBeenCalled();
     expect(res.status).toHaveBeenCalledWith(401);
     expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Access token required' });
   });
 
-  it('returns 401 for an invalid token', () => {
+  it('returns 401 for an invalid token', async () => {
     const req = mockReq({ cookies: { access_token: 'not-a-real-token' } });
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(next).not.toHaveBeenCalled();
     expect(res.status).toHaveBeenCalledWith(401);
     expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Invalid or expired token' });
   });
 
-  it('returns 401 for a token signed with a different secret', () => {
+  it('returns 401 for a token signed with a different secret', async () => {
     const token = jwt.sign(payload, 'wrong-secret');
     const req = mockReq({ cookies: { access_token: token } });
     const res = mockRes();
 
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(res.status).toHaveBeenCalledWith(401);
   });
@@ -120,54 +131,54 @@ describe('optionalAuth', () => {
 
   const payload: UserPayload = { id: '1', email: 'user@example.com', name: 'Test User' };
 
-  it('attaches the user when the token is valid', () => {
+  it('attaches the user when the token is valid', async () => {
     const req = mockReq({ cookies: { access_token: jwt.sign(payload, 'test-secret') } });
 
-    optionalAuth(req, mockRes(), next);
+    await optionalAuth(req, mockRes(), next);
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(req.user).toMatchObject({ email: 'user@example.com' });
   });
 
-  it('reads a bearer token too', () => {
+  it('reads a bearer token too', async () => {
     const req = mockReq({ headers: { authorization: `Bearer ${jwt.sign(payload, 'test-secret')}` } });
 
-    optionalAuth(req, mockRes(), next);
+    await optionalAuth(req, mockRes(), next);
 
     expect(req.user).toMatchObject({ email: 'user@example.com' });
   });
 
-  it('continues anonymously when there is no token', () => {
+  it('continues anonymously when there is no token', async () => {
     const req = mockReq();
     const res = mockRes();
 
-    optionalAuth(req, res, next);
+    await optionalAuth(req, res, next);
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(req.user).toBeUndefined();
     expect(res.status).not.toHaveBeenCalled();
   });
 
-  it('treats an expired or forged token as no token rather than as a 401', () => {
+  it('treats an expired or forged token as no token rather than as a 401', async () => {
     // The caller asked for public data. Refusing it because a stale cookie is
     // lying around would break the landing page for exactly the people most
     // likely to have one.
     const req = mockReq({ cookies: { access_token: jwt.sign(payload, 'wrong-secret') } });
     const res = mockRes();
 
-    optionalAuth(req, res, next);
+    await optionalAuth(req, res, next);
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(req.user).toBeUndefined();
     expect(res.status).not.toHaveBeenCalled();
   });
 
-  it('continues anonymously when JWT_SECRET is not configured', () => {
+  it('continues anonymously when JWT_SECRET is not configured', async () => {
     delete process.env.JWT_SECRET;
     const req = mockReq({ cookies: { access_token: 'anything' } });
     const res = mockRes();
 
-    optionalAuth(req, res, next);
+    await optionalAuth(req, res, next);
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(res.status).not.toHaveBeenCalled();
@@ -200,28 +211,65 @@ describe('OAuth access tokens are not sessions', () => {
       clientName: 'Claude'
     }).accessToken;
 
-  it('refuses one on a session-only route', () => {
+  it('refuses one on a session-only route', async () => {
     const res = mockRes();
     const next = jest.fn();
     const req = mockReq({ headers: { authorization: `Bearer ${accessToken()}` } });
 
     // It verifies — same secret — so nothing but the type check stands between
     // an assistant and every route that has no scopes to be held to.
-    authenticateToken(req, res, next);
+    await authenticateToken(req, res, next);
 
     expect(res.status).toHaveBeenCalledWith(403);
     expect(next).not.toHaveBeenCalled();
     expect(req.user).toBeUndefined();
   });
 
-  it('treats one as no session at all on an optional-auth route', () => {
+  it('treats one as no session at all on an optional-auth route', async () => {
     const next = jest.fn();
     const req = mockReq({ headers: { authorization: `Bearer ${accessToken()}` } });
 
-    optionalAuth(req, mockRes(), next);
+    await optionalAuth(req, mockRes(), next);
 
     // The route still answers, in its public form — the same as a stale cookie.
     expect(next).toHaveBeenCalled();
     expect(req.user).toBeUndefined();
   });
 });
+
+describe('ended sessions', () => {
+  const ORIGINAL_ENV = process.env;
+  const payload: UserPayload = { id: '1', email: 'user@example.com', name: 'Test User', sid: 'a'.repeat(24) };
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV, JWT_SECRET: 'test-secret' };
+    overrideSessionCheckForTests(async () => false);
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('authenticateToken refuses a validly signed token whose session has ended', async () => {
+    const req = mockReq({ cookies: { access_token: jwt.sign(payload, 'test-secret') } });
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateToken(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Session has ended' });
+    expect(next).not.toHaveBeenCalled();
+    expect(req.user).toBeUndefined();
+  });
+
+  it('optionalAuth treats an ended session as no session', async () => {
+    const req = mockReq({ cookies: { access_token: jwt.sign(payload, 'test-secret') } });
+    const next = jest.fn();
+
+    await optionalAuth(req, mockRes(), next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.user).toBeUndefined();
+  });
+});

package/src/middleware/authMiddleware.ts

@@ -3,6 +3,8 @@ import jwt from 'jsonwebtoken';
 import { requireEnv } from '../config/env';
 import { isAccessTokenClaims } from '../oauth/tokens';
 import { UserPayload } from '../types/auth';
+import { isCurrentSession } from '../auth/session';
+import { currentGroupsOf } from '../groups/membership';
 
 /**
  * JWT authentication middleware
@@ -17,7 +19,7 @@ import { UserPayload } from '../types/auth';
  * enforces both — so anything still guarded by this one is a person's to do,
  * and letting a token through would be handing an assistant the account.
  */
-export function authenticateToken(req: Request, res: Response, next: NextFunction): void {
+export async function authenticateToken(req: Request, res: Response, next: NextFunction): Promise<void> {
   try {
     const JWT_SECRET = requireEnv('JWT_SECRET');
     const token = req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
@@ -36,13 +38,22 @@ export function authenticateToken(req: Request, res: Response, next: NextFunctio
       return;
     }
 
-    const user = claims as UserPayload;
-    req.user = user;
-    req.userGroups = user.groups ?? [];
-    next();
+    // A signed-out or revoked device keeps a validly signed token; only its
+    // session record says it has ended.
+    if (!(await isCurrentSession(claims))) {
+      res.status(401).json({ success: false, message: 'Session has ended' });
+      return;
+    }
+    // Membership is asked of group-service, not read from the token, so a
+    // change applies within seconds rather than at the next renewal.
+    const groups = await currentGroupsOf(claims as UserPayload);
+    req.user = { ...(claims as UserPayload), groups };
+    req.userGroups = groups;
   } catch (error) {
     res.status(401).json({ success: false, message: 'Invalid or expired token' });
+    return;
   }
+  next();
 }
 /**
  * Attaches the user when a valid token is present, and never rejects.
@@ -57,7 +68,7 @@ export function authenticateToken(req: Request, res: Response, next: NextFunctio
  * around would break the landing page for exactly the people most likely to
  * have one.
  */
-export function optionalAuth(req: Request, _res: Response, next: NextFunction): void {
+export async function optionalAuth(req: Request, _res: Response, next: NextFunction): Promise<void> {
   try {
     const JWT_SECRET = requireEnv('JWT_SECRET');
     const token = req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
@@ -66,10 +77,11 @@ export function optionalAuth(req: Request, _res: Response, next: NextFunction):
       const claims = jwt.verify(token, JWT_SECRET);
       // An access token is not a session; treated as none, exactly like an
       // expired cookie, so the route still answers with its public form.
-      if (!isAccessTokenClaims(claims)) {
-        const user = claims as UserPayload;
-        req.user = user;
-        req.userGroups = user.groups ?? [];
+      // An ended session is treated as none, like an expired cookie.
+      if (!isAccessTokenClaims(claims) && (await isCurrentSession(claims))) {
+        const groups = await currentGroupsOf(claims as UserPayload);
+        req.user = { ...(claims as UserPayload), groups };
+        req.userGroups = groups;
       }
     }
   } catch {

package/src/testing/serviceTestSetup.ts

@@ -0,0 +1,17 @@
+import { overrideSessionCheckForTests } from '../auth/session';
+import { overrideMembershipLookupForTests } from '../groups/membership';
+
+/**
+ * Jest setup for service test suites: they sign session tokens without a
+ * session and run with no database or group-service, so every token's session
+ * counts as live and its `groups` claim stands in for group membership.
+ * The session check itself is tested in backend-core (auth/session.test.ts).
+ *
+ * Loaded through the package's test-only entry point:
+ *   setupFiles: ['@tumbaland/backend-core/testing']
+ */
+overrideSessionCheckForTests(async () => true);
+
+// No group-service either: a test token's own `groups` claim is taken as the
+// person's membership. The live lookup is tested in groups/membership.test.ts.
+overrideMembershipLookupForTests(async (user) => user.groups ?? []);

package/src/types/auth.ts

@@ -7,6 +7,9 @@ export interface UserPayload {
   picture?: string;
   groups?: string[];
   roles?: string[];
+  tokenVersion?: number;
+  /** The auth-service session (user_sessions) this token belongs to; absent on pre-sessions tokens. */
+  sid?: string;
 }
 
 /**

package/testing.js

@@ -0,0 +1,10 @@
+/**
+ * Test-only entry point: `@tumbaland/backend-core/testing`.
+ *
+ * Loading it makes every session token's session count as live, and a test
+ * token's `groups` claim its group membership, for service test suites that
+ * run with no database and no group-service.
+ * Kept out of the package's main exports so production code never reaches it.
+ * The session check itself is tested in backend-core (src/auth/session.test.ts).
+ */
+require('./dist/testing/serviceTestSetup');