@bevel-software/platform-core-backend 0.33.0 → 0.34.0

package/src/modules/agent-scope/agent-scope.contract.ts

@@ -0,0 +1,83 @@
+import { ConnectionScope } from './connection-scope.js';
+
+/** One agent configuration a person may connect as — a row of the "Connect as" choice. */
+export interface AgentChoice {
+  /** Repo-relative path of the configuration — what the connection records. */
+  path: string;
+  /** Its name, as the choice shows it. */
+  name: string;
+  /** Its description, one line; empty when it has none. */
+  description: string;
+}
+
+/**
+ * The connection-scope mechanism: which agent configurations a person may
+ * connect as, and what a connection made as one may load right now.
+ *
+ * Core owns the MECHANISM and none of the configurations: what an agent
+ * configuration is — the file kind, where it lives, what its definition
+ * says — is the distribution's (`CorePorts.agentScope`), exactly as the
+ * file kinds whose frontmatter carries access verbs are
+ * (`registerAccessFrontmatterExtensions`). Core itself offers no agent to
+ * connect as ({@link noAgentConfigurations}): every connection it makes is
+ * Everything, and a connection recorded as some path by a distribution that
+ * is no longer there loads nothing, never Everything.
+ *
+ * Every agent surface resolves its caller's scope here, with the agent path
+ * its credential carries — a connection key's `api_tokens.agent_path`, an
+ * agent connection's `agent_connections.agent_path` — and asks the scope;
+ * none reads a configuration itself.
+ */
+export interface IAgentScopeResolver {
+  /**
+   * The scope of a connection made as `agentPath` for the person `userEmail`.
+   * No path is Everything. The configuration is read, through the person's
+   * read gate, on EVERY call — the connection follows the configuration, not
+   * a copy of it — and one that is missing, unreadable to the person or not
+   * a valid definition yields a scope that loads nothing, never Everything.
+   */
+  resolve(userEmail: string | undefined, agentPath: string | null | undefined): Promise<ConnectionScope>;
+  /**
+   * The agent configurations `userEmail` may connect as, by name — what the
+   * consent step and the key-mint dialog offer below Everything. Rejects
+   * when they cannot be listed at all (the default branch cannot be opened):
+   * that is a failed listing, which the caller says, never an empty one.
+   */
+  listChoices(userEmail: string): Promise<AgentChoice[]>;
+  /**
+   * `agentPath` normalized when it is one of {@link listChoices}' paths, else
+   * null — one answer for a configuration that does not exist and one the
+   * person may not read, so a refused choice says nothing about either.
+   */
+  choosable(userEmail: string, agentPath: string): Promise<string | null>;
+}
+
+/**
+ * The resolver of a distribution that has no agent configurations — core's
+ * own default. Nothing is offered, nothing is choosable, and a recorded path
+ * resolves to a scope that loads nothing: a narrowing that cannot be read is
+ * never read as Everything.
+ */
+export function noAgentConfigurations(): IAgentScopeResolver {
+  return {
+    resolve: async (_userEmail, agentPath) => (agentPath ? ConnectionScope.gone(agentPath) : ConnectionScope.everything()),
+    listChoices: async () => [],
+    choosable: async () => null,
+  };
+}
+
+/**
+ * The scope of a caller whose credential connects as `agentPath` — THE way
+ * every agent surface turns a credential into a scope. No path is
+ * Everything, without asking anything. A path with no resolver to read it
+ * (a construction that wired none) loads nothing: a narrowing that cannot be
+ * read is never read as Everything.
+ */
+export async function resolveConnectionScope(
+  resolver: Pick<IAgentScopeResolver, 'resolve'> | undefined,
+  userEmail: string | undefined,
+  agentPath: string | null | undefined,
+): Promise<ConnectionScope> {
+  if (!agentPath) return ConnectionScope.everything();
+  return resolver ? resolver.resolve(userEmail, agentPath) : ConnectionScope.gone(agentPath);
+}

package/src/modules/agent-scope/connection-scope.ts

@@ -0,0 +1,199 @@
+import { pathUnderRoot } from '@bevel-software/platform-shared';
+import {
+  NOT_AVAILABLE_TO_CONNECTION,
+  connectionRefusal,
+  describeConnection,
+  type ConnectionScopeWire,
+  type ScopeAgent,
+} from '@bevel-software/platform-mcp-core';
+
+// The wire and its words are the MCP core's (`connection-scope-wire.ts`),
+// so the hosted proxy and the local server read and word a connection the
+// same way; offered here too, as this module's callers learnt them.
+export { NOT_AVAILABLE_TO_CONNECTION, connectionRefusal, describeConnection, type ConnectionScopeWire, type ScopeAgent };
+
+/**
+ * The resolved roots a usable agent configuration narrows a connection to — what
+ * {@link ConnectionScope.narrowed} is built from.
+ */
+export interface ScopeRoots {
+  /** Skill folders and subtrees: the `skills:` entries, each plugin folder, and the skills its manifest links. */
+  skills: readonly string[];
+  /** Connector files and subtrees: the `connectors:` entries and each plugin folder. */
+  connectors: readonly string[];
+  /** Platform tool names; null for all of them. */
+  platformTools: readonly string[] | null;
+}
+
+type State =
+  | { kind: 'everything' }
+  | { kind: 'narrowed'; agent: ScopeAgent; roots: ScopeRoots; fingerprint: string }
+  | { kind: 'unavailable'; agent: ScopeAgent; sentence: string; fingerprint: string };
+
+/**
+ * What one connection may load — the ONE answer every agent surface asks
+ * (`all-tools`, the `/agent/utcp` manual, the tool route, the skill tools,
+ * the setup tools, the catalog revision). Everything is the scope of every
+ * connection made without a choice, and asks nothing of anyone: each of its
+ * predicates is true, so a surface that consults it serves exactly what it
+ * served before connections could be narrowed.
+ *
+ * A scope only ever NARROWS. It is applied to what the person may already
+ * read — each surface asks it about items that passed the person's own read
+ * gate — so no list in an agent configuration can add an item to a connection.
+ */
+export class ConnectionScope {
+  private constructor(private readonly state: State) {}
+
+  static everything(): ConnectionScope {
+    return new ConnectionScope({ kind: 'everything' });
+  }
+
+  static narrowed(agent: ScopeAgent, roots: ScopeRoots, fingerprint: string): ConnectionScope {
+    return new ConnectionScope({ kind: 'narrowed', agent, roots, fingerprint });
+  }
+
+  /** A chosen file that cannot be used: nothing at all is loaded, and `sentence` says why. */
+  static unavailable(agent: ScopeAgent, sentence: string, fingerprint: string): ConnectionScope {
+    return new ConnectionScope({ kind: 'unavailable', agent, sentence, fingerprint });
+  }
+
+  /**
+   * A chosen file that is not there for the person — missing, or one they may
+   * no longer read: ONE answer for both, so the sentence discloses neither.
+   */
+  static gone(agentPath: string): ConnectionScope {
+    return ConnectionScope.unavailable(
+      { path: agentPath, name: agentPath },
+      `This connection was made as the agent \`${agentPath}\`, which no longer exists or which you can no ` +
+        'longer read, so it loads no tools and no skills. Reconnect and choose another agent, or Everything.',
+      `agent\u0000${agentPath}\u0000gone`,
+    );
+  }
+
+  /** True for Everything: the connection was made without choosing an agent. */
+  isEverything(): boolean {
+    return this.state.kind === 'everything';
+  }
+
+  /** Whether the skill in `skillFolder` (repo-relative) is loaded. */
+  allowsSkill(skillFolder: string): boolean {
+    const s = this.state;
+    if (s.kind === 'everything') return true;
+    if (s.kind === 'unavailable') return false;
+    return s.roots.skills.some((root) => pathUnderRoot(skillFolder, root));
+  }
+
+  /** Whether the connector defined at `definitionPath` (a `.tool` file or an MCP server definition) is loaded. */
+  allowsConnector(definitionPath: string): boolean {
+    const s = this.state;
+    if (s.kind === 'everything') return true;
+    if (s.kind === 'unavailable') return false;
+    return s.roots.connectors.some((root) => pathUnderRoot(definitionPath, root));
+  }
+
+  /**
+   * Whether any connector this connection loads is defined in `folder`
+   * (repo-relative) or in a folder that contains it — what a plugin's
+   * archive asks, since the local MCP server materializes a plugin only to
+   * run a connector it defines.
+   */
+  loadsConnectorIn(folder: string): boolean {
+    const s = this.state;
+    if (s.kind === 'everything') return true;
+    if (s.kind === 'unavailable') return false;
+    return s.roots.connectors.some((root) => pathUnderRoot(folder, root) || pathUnderRoot(root, folder));
+  }
+
+  /**
+   * {@link allowsSkill} as the narrowing a skill listing takes, or undefined
+   * for Everything — so an Everything caller's listing runs exactly the code
+   * it ran before connections could be narrowed.
+   */
+  skillFilter(): ((skillFolder: string) => boolean) | undefined {
+    return this.state.kind === 'everything' ? undefined : (p) => this.allowsSkill(p);
+  }
+
+  /** {@link allowsConnector} as the narrowing a catalog read takes, or undefined for Everything. */
+  connectorFilter(): ((definitionPath: string) => boolean) | undefined {
+    return this.state.kind === 'everything' ? undefined : (p) => this.allowsConnector(p);
+  }
+
+  /**
+   * Whether the connection's surface may be discovered: its skills read as
+   * MCP prompts, and its local-only connectors read by the local server so
+   * it can materialize them. Neither is a platform tool, so `platformTools`
+   * has no say — an agent that names skills gets them as prompts, and one
+   * that names connectors gets them served, whatever tools it is offered.
+   * False only for a file that cannot be used, which loads nothing at all.
+   */
+  allowsDiscovery(): boolean {
+    return this.state.kind !== 'unavailable';
+  }
+
+  /** Whether the platform's own tool `name` is loaded. */
+  allowsPlatformTool(name: string): boolean {
+    const s = this.state;
+    if (s.kind === 'everything') return true;
+    if (s.kind === 'unavailable') return false;
+    return s.roots.platformTools === null || s.roots.platformTools.includes(name);
+  }
+
+  /**
+   * The answer to a call of `toolName`, a tool this connection does not load:
+   * names the tool and the agent, so the caller knows the tool was refused by
+   * the connection's choice and not missing from the deployment. For a file
+   * that cannot be used, the sentence that says why.
+   */
+  refusal(toolName: string): string {
+    return connectionRefusal(toolName, this.toWire());
+  }
+
+  /**
+   * THE policy for a call of the platform tool `toolName` by this connection:
+   * null when the call may proceed, else the body the route answers with a
+   * 403 — the refusal naming the tool and the agent, and the code that says
+   * it was the connection's choice. Every route that IS a platform tool asks
+   * this, whether `toolHandler` hosts it or it is mounted on its own (the
+   * plugin-creation routes), so the rule is written once and the answers
+   * cannot drift. `discovery` marks a route that is a discovery read of the
+   * surface (the skill routes, the local-only tool list), which a narrowed
+   * connection is answered even when its `platformTools` omits the tool;
+   * a connection that loads nothing is refused it like everything else.
+   */
+  platformToolRefusal(
+    toolName: string,
+    opts: { discovery?: boolean } = {},
+  ): { error: string; code: typeof NOT_AVAILABLE_TO_CONNECTION } | null {
+    if (this.allowsPlatformTool(toolName)) return null;
+    if (opts.discovery === true && this.allowsDiscovery()) return null;
+    return { error: this.refusal(toolName), code: NOT_AVAILABLE_TO_CONNECTION };
+  }
+
+  /**
+   * One line for the text an agent is told about its connection (the MCP
+   * handshake, the agent guide); null for Everything, which is told nothing
+   * new.
+   */
+  describe(): string | null {
+    return describeConnection(this.toWire());
+  }
+
+  /**
+   * What moves the catalog revision when the agent's FILE changes — its path
+   * and a digest of its bytes, or the reason it cannot be used. Null for
+   * Everything, whose revision is exactly what it was before agents existed.
+   */
+  fingerprint(): string | null {
+    const s = this.state;
+    return s.kind === 'everything' ? null : s.fingerprint;
+  }
+
+  /** See {@link ConnectionScopeWire}; undefined for Everything. */
+  toWire(): ConnectionScopeWire | undefined {
+    const s = this.state;
+    if (s.kind === 'everything') return undefined;
+    if (s.kind === 'unavailable') return { agent: s.agent, unavailable: s.sentence };
+    return { agent: s.agent };
+  }
+}

package/src/modules/agent-scope/index.ts

@@ -0,0 +1,15 @@
+export {
+  noAgentConfigurations,
+  resolveConnectionScope,
+  type AgentChoice,
+  type IAgentScopeResolver,
+} from './agent-scope.contract.js';
+export {
+  ConnectionScope,
+  NOT_AVAILABLE_TO_CONNECTION,
+  connectionRefusal,
+  describeConnection,
+  type ConnectionScopeWire,
+  type ScopeAgent,
+  type ScopeRoots,
+} from './connection-scope.js';

package/src/modules/audit/agent-audit.service.ts

@@ -151,6 +151,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         deletedAt: k.deletedAt,
         eventCount: counts.get(k.id) ?? 0,
         user: k.user,
+        agentPath: k.agentPath ?? null,
       })),
       ...connectionRows.map(({ connection: c, user }) => ({
         kind: 'agent' as const,
@@ -162,6 +163,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         revokedBy: (c.revokedBy as 'owner' | 'admin' | null) ?? null,
         eventCount: counts.get(c.id) ?? 0,
         user,
+        agentPath: c.agentPath ?? null,
       })),
       ...pageRows.flatMap((r) =>
         r.pagePath

package/src/modules/audit/audit.contract.ts

@@ -128,6 +128,12 @@ export interface AuditPrincipal {
   /** Events currently on record for it (within the retention window). */
   eventCount: number;
   user: { id: string; email: string; name: string };
+  /**
+   * For a key or an agent connection: the agent configuration it connects as (a
+   * repo-relative knowledge-base path), or null for Everything. Absent for a
+   * page, which acts as its viewer.
+   */
+  agentPath?: string | null;
 }
 
 /** One event as the page reads it. */

package/src/modules/auth/__tests__/auth.middleware.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import type { Request, Response, NextFunction } from 'express';
-import { createAuthMiddleware, AUTH_COOKIE_NAME } from '../auth.middleware.js';
-import { AccountDeactivatedError, AuthBackendError } from '../account-admission.js';
+import { authCookieSecure, createAuthMiddleware, AUTH_COOKIE_NAME } from '../auth.middleware.js';
+import { AccountDeactivatedError, AuthBackendError, SessionEndedError } from '../account-admission.js';
 import type { AuthService } from '../auth.service.js';
 
 /**
@@ -14,11 +14,13 @@ import type { AuthService } from '../auth.service.js';
 const GOOD_TOKEN = 'good-token';
 const OFF_TOKEN = 'switched-off-token';
 const DOWN_TOKEN = 'database-down-token';
+const ENDED_TOKEN = 'password-changed-since-token';
 const IDENTITY = { userId: 'user-1', email: 'alice@example.com' };
 
 async function run(headers: Record<string, string>) {
   const resolveSession = vi.fn(async (token: string) => {
     if (token === OFF_TOKEN) throw new AccountDeactivatedError();
+    if (token === ENDED_TOKEN) throw new SessionEndedError();
     if (token === DOWN_TOKEN) throw new AuthBackendError(new Error('db down'));
     if (token !== GOOD_TOKEN) throw new Error('bad token');
     return IDENTITY;
@@ -91,6 +93,32 @@ describe('createAuthMiddleware — a switched-off account', () => {
   });
 });
 
+describe('authCookieSecure', () => {
+  it('marks the cookie Secure for an https deployment, whatever the case of the scheme', () => {
+    expect(authCookieSecure('https://kb.example.com')).toBe(true);
+    expect(authCookieSecure('HTTPS://kb.example.com/')).toBe(true);
+    expect(authCookieSecure('Https://kb.example.com:8443/base')).toBe(true);
+  });
+
+  it('leaves it off for a deployment reached over plain http', () => {
+    expect(authCookieSecure('http://localhost:3001')).toBe(false);
+    expect(authCookieSecure('HTTP://10.0.0.5')).toBe(false);
+  });
+
+  it('refuses a public URL that is not one, as the rest of the boot does', () => {
+    expect(() => authCookieSecure('kb.example.com')).toThrow();
+  });
+});
+
+describe('createAuthMiddleware — a session a password change ended', () => {
+  it('refuses it with a 401 that says the password was changed, so the sign-in form can', async () => {
+    const { next, status, json } = await run({ cookie: `${AUTH_COOKIE_NAME}=${ENDED_TOKEN}` });
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+    expect(json.mock.calls[0][0].error).toMatch(/password was changed after this session was opened/);
+  });
+});
+
 describe('createAuthMiddleware — the account cannot be looked up', () => {
   it('500s rather than signing a valid session out during an outage', async () => {
     const { next, status, json } = await run({ authorization: `Bearer ${DOWN_TOKEN}` });

package/src/modules/auth/__tests__/auth.routes.test.ts

@@ -1,15 +1,16 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import express from 'express';
 import type { Server } from 'node:http';
-import { createAuthRoutes } from '../auth.routes.js';
-import type { AuthService } from '../auth.service.js';
+import { createAuthRoutes, type AuthRoutesOptions } from '../auth.routes.js';
+import { PasswordChangedMeanwhileError, PasswordRefusedError, type AuthService } from '../auth.service.js';
+import { AUTH_COOKIE_NAME } from '../auth.middleware.js';
 
 const authService = {
   loginWithPassword: vi.fn(async () => {
     throw new Error('Invalid credentials');
   }),
   changePassword: vi.fn(async () => {
-    throw new Error('Current password is incorrect');
+    throw new PasswordRefusedError('Current password is incorrect');
   }),
   getUserById: vi.fn(async () => null),
 } as unknown as AuthService;
@@ -28,10 +29,10 @@ afterEach(() => {
   server?.close();
 });
 
-async function listen(): Promise<string> {
+async function listen(options?: AuthRoutesOptions): Promise<string> {
   const app = express();
   app.use(express.json());
-  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware));
+  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware, [], true, options));
   await new Promise<void>((resolve) => {
     server = app.listen(0, resolve);
   });
@@ -89,3 +90,68 @@ describe('auth routes — rate limiting', () => {
     expect((await post()).status).toBe(429);
   });
 });
+
+describe('auth routes — change-password', () => {
+  const post = (base: string) =>
+    fetch(`${base}/api/auth/change-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ currentPassword: 'old-password', newPassword: 'new-password-1' }),
+    });
+
+  it('hands the changer a fresh token, in the body and the auth cookie', async () => {
+    vi.mocked(authService.changePassword).mockResolvedValueOnce({ token: 'fresh-jwt' });
+    const res = await post(await listen());
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, token: 'fresh-jwt' });
+    expect(res.headers.getSetCookie().some((c) => c.startsWith(`${AUTH_COOKIE_NAME}=fresh-jwt;`))).toBe(true);
+  });
+
+  it('answers a change another session got in first with a 409 and its words, and no cookie', async () => {
+    vi.mocked(authService.changePassword).mockRejectedValueOnce(new PasswordChangedMeanwhileError());
+    const res = await post(await listen());
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toMatch(/changed from another session/);
+    expect(res.headers.getSetCookie()).toEqual([]);
+  });
+
+  it('answers a refusal the service made on purpose with a 400 and its words', async () => {
+    vi.mocked(authService.changePassword).mockRejectedValueOnce(new PasswordRefusedError('Password must be at least 8 characters'));
+    const res = await post(await listen());
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: 'Password must be at least 8 characters' });
+  });
+
+  it('answers a fault with a generic 500 that carries nothing of the cause', async () => {
+    vi.mocked(authService.changePassword).mockRejectedValueOnce(
+      new Error('connect ECONNREFUSED db.internal:5432 (role bevel, database bevel)'),
+    );
+    const res = await post(await listen());
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body).toEqual({ error: 'Could not change the password' });
+    expect(JSON.stringify(body)).not.toMatch(/ECONNREFUSED|5432|bevel/);
+  });
+
+  it('marks the cookie Secure when the deployment is reached over https, and not otherwise', async () => {
+    vi.mocked(authService.changePassword).mockResolvedValueOnce({ token: 'fresh-jwt' });
+    const secure = await post(await listen({ cookieSecure: true }));
+    expect(secure.headers.getSetCookie()[0]).toMatch(/; Secure/);
+    vi.mocked(authService.changePassword).mockResolvedValueOnce({ token: 'fresh-jwt' });
+    const plain = await post(await listen({ cookieSecure: false }));
+    expect(plain.headers.getSetCookie()[0]).not.toMatch(/; Secure/);
+  });
+});
+
+describe('auth routes — me', () => {
+  it('answers a fault with a generic 500 that carries nothing of the cause', async () => {
+    vi.mocked(authService.getUserById).mockRejectedValueOnce(
+      new Error('connect ECONNREFUSED db.internal:5432 (role bevel, database bevel)'),
+    );
+    const res = await fetch(`${await listen()}/api/auth/me`);
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body).toEqual({ error: 'Could not load your account' });
+    expect(JSON.stringify(body)).not.toMatch(/ECONNREFUSED|5432|bevel/);
+  });
+});

package/src/modules/auth/__tests__/auth.service.test.ts

@@ -3,11 +3,12 @@ import { PgDialect } from 'drizzle-orm/pg-core';
 import type { SQL } from 'drizzle-orm';
 import type { Database } from '../../database/connection.js';
 import type { CoreConfig } from '../../../core-config.js';
-import { AuthService } from '../auth.service.js';
-import { AccountAdmissionRefusedError, type IAccountAdmission } from '../account-admission.js';
+import jwt from 'jsonwebtoken';
+import { AuthService, PasswordChangedMeanwhileError, PasswordRefusedError } from '../auth.service.js';
+import { AccountAdmissionRefusedError, SessionEndedError, type IAccountAdmission } from '../account-admission.js';
 import { hashPassword, verifyPassword } from '../password-hash.js';
-import { RECOVERY_BOT_EMAIL } from '../../workflow/recovery-bot.js';
-import { DIRECTORY_SYNC_BOT_EMAIL } from '../../access/directory-sync-bot.js';
+import { RECOVERY_BOT_EMAIL } from '../../workflow/index.js';
+import { DIRECTORY_SYNC_BOT_EMAIL } from '../../access/index.js';
 
 /**
  * Minimal drizzle chain stub (same idiom as the secrets-vault tests): each
@@ -78,8 +79,12 @@ const ROW = {
   // always has a boolean here, so the fixture carries one rather than letting
   // every asserted payload read `undefined`.
   onboardingDone: false,
+  sessionVersion: 0,
 };
 
+/** What a password change's conditional write hands back: the row, one session generation on. */
+const CHANGED = [{ ...ROW, sessionVersion: 1 }];
+
 describe('AuthService.loginWithPassword — env bootstrap admin', () => {
   const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
 
@@ -283,14 +288,14 @@ describe('AuthService.createAccount / changePassword', () => {
       new AuthService(wrong.db, makeConfig()).changePassword('user-1', 'not-it', 'new-password-1'),
     ).rejects.toThrow('Current password is incorrect');
 
-    const right = makeFakeDb([[{ ...ROW, passwordHash }], undefined]);
+    const right = makeFakeDb([[{ ...ROW, passwordHash }], CHANGED]);
     await expect(
       new AuthService(right.db, makeConfig()).changePassword('user-1', 'old-password', 'new-password-1'),
-    ).resolves.toBeUndefined();
+    ).resolves.toMatchObject({ token: expect.any(String) });
   });
 
   it('changePassword lets an SSO-only account set its first password without one', async () => {
-    const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: null }], undefined]);
+    const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: null }], CHANGED]);
     await new AuthService(db, makeConfig()).changePassword('user-1', undefined, 'first-password');
     const set = captured.set[0] as { passwordHash: string };
     expect(set.passwordHash.startsWith('scrypt:')).toBe(true);
@@ -452,7 +457,7 @@ describe('AuthService.changePassword — the three account kinds', () => {
       });
 
       it('stores a new hash for the right current password', async () => {
-        const { db, captured } = makeFakeDb([[await row()], undefined]);
+        const { db, captured } = makeFakeDb([[await row()], CHANGED]);
         await new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
           kind.id,
           'old-password',
@@ -585,7 +590,7 @@ describe('AuthService.changePassword — the three account kinds', () => {
       ).getUserById('user-root');
       expect(flagged?.isEnvAdmin).toBe(false);
 
-      const { db, captured } = makeFakeDb([[{ ...rootRow, passwordHash }], undefined]);
+      const { db, captured } = makeFakeDb([[{ ...rootRow, passwordHash }], CHANGED]);
       await new AuthService(db, config).changePassword('user-root', 'old-password', 'new-password-1');
       expect((captured.set[0] as { passwordHash: string }).passwordHash.startsWith('scrypt:')).toBe(
         true,
@@ -594,6 +599,82 @@ describe('AuthService.changePassword — the three account kinds', () => {
   });
 });
 
+/**
+ * A password change ends the sessions opened before it. The real-Postgres
+ * half (`password-change-sessions.pg.test.ts`) proves it end to end; these
+ * pin the service's side without a database.
+ */
+describe('AuthService.changePassword — the sessions opened before it', () => {
+  const ON = { deactivatedAt: null };
+
+  it('refuses a session issued before the change, and accepts the token the change hands back', async () => {
+    const passwordHash = await hashPassword('old-password');
+    const { db } = makeFakeDb([
+      [{ ...ROW, passwordHash }], // sign-in
+      [{ ...ROW, passwordHash }], // the change reads the row...
+      CHANGED, // ...and writes it one generation on
+      [{ ...ON, ...CHANGED[0] }], // the old token's lookup...
+      [{ ...ON, ...CHANGED[0] }], // ...and the new one's: a session is never answered from the cache
+    ]);
+    const svc = new AuthService(db, makeConfig());
+    const before = await svc.loginWithPassword('alice@example.com', 'old-password');
+    const { token } = await svc.changePassword('user-1', 'old-password', 'new-password-1');
+    // Named, and worded for the person: the middleware shows these words
+    // where a bare "invalid token" would leave them guessing.
+    const ended = svc.resolveSession(before.token);
+    await expect(ended).rejects.toBeInstanceOf(SessionEndedError);
+    await expect(ended).rejects.toThrow(/password was changed after this session was opened/);
+    await expect(svc.resolveSession(token)).resolves.toEqual({ userId: ROW.id, email: ROW.email });
+  });
+
+  it('refuses a wrong current password as a refusal the caller is told, not a fault', async () => {
+    const passwordHash = await hashPassword('old-password');
+    const { db } = makeFakeDb([[{ ...ROW, passwordHash }]]);
+    const refused = new AuthService(db, makeConfig()).changePassword('user-1', 'not-it', 'new-password-1');
+    await expect(refused).rejects.toBeInstanceOf(PasswordRefusedError);
+    await expect(refused).rejects.toThrow('Current password is incorrect');
+  });
+
+  it('reads the account row for every session it resolves, whatever the cache holds', async () => {
+    // Another replica's password change is only visible in the row, so a
+    // session answered from the cache would outlive it by up to 30 seconds.
+    const live = [{ ...ON, ...ROW }];
+    const { db } = makeFakeDb([live, live, live]);
+    const svc = new AuthService(db, makeConfig());
+    const token = jwt.sign({ userId: ROW.id, email: ROW.email, sv: 0 }, 'test-jwt-secret', { expiresIn: '7d' });
+    const select = vi.mocked(db.select);
+
+    await svc.resolveSession(token);
+    expect(select).toHaveBeenCalledTimes(1);
+    // The cache now holds the account; isActive may use it...
+    await expect(svc.isActive(ROW.id)).resolves.toBe(true);
+    expect(select).toHaveBeenCalledTimes(1);
+    // ...but a session never does.
+    await svc.resolveSession(token);
+    expect(select).toHaveBeenCalledTimes(2);
+    await svc.resolveSession(token);
+    expect(select).toHaveBeenCalledTimes(3);
+  });
+
+  it('keeps a token issued before sessions had generations while the password never changed', async () => {
+    const { db } = makeFakeDb([[{ ...ON, ...ROW }]]);
+    const legacy = jwt.sign({ userId: ROW.id, email: ROW.email }, 'test-jwt-secret', { expiresIn: '7d' });
+    await expect(new AuthService(db, makeConfig()).resolveSession(legacy)).resolves.toEqual({
+      userId: ROW.id,
+      email: ROW.email,
+    });
+  });
+
+  it('is refused, in words, when another session changed the password between the read and the write', async () => {
+    const passwordHash = await hashPassword('old-password');
+    // The conditional write finds the row no longer at the generation read.
+    const { db } = makeFakeDb([[{ ...ROW, passwordHash }], []]);
+    const refused = new AuthService(db, makeConfig()).changePassword('user-1', 'old-password', 'new-password-1');
+    await expect(refused).rejects.toBeInstanceOf(PasswordChangedMeanwhileError);
+    await expect(refused).rejects.toThrow(/changed from another session.*nothing was changed/);
+  });
+});
+
 describe('AuthService.listAccounts', () => {
   it('reports hasPassword without ever exposing the hash', async () => {
     const passwordHash = await hashPassword('pw-longer-than-8');