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

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

@@ -9,6 +9,7 @@ import {
   AccountChangeRefusedError,
   AccountDeactivatedError,
   AuthBackendError,
+  SessionEndedError,
   admitEveryone,
   type AccountProvisionReason,
   type IAccountAdmission,
@@ -32,6 +33,8 @@ const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  * request carrying a credential asks, so the answer is kept briefly rather
  * than read each time; switching an account off or on in THIS process
  * forgets it at once, and another replica sees the change within this long.
+ * A session token never waits on it: {@link AuthService.resolveSession}
+ * reads the row each time, so a password change ends it everywhere at once.
  */
 const ACTIVE_CACHE_MS = 30_000;
 
@@ -69,6 +72,33 @@ export const OWNER_SWITCH_OFF_REFUSAL = "The owner can't be switched off.";
 /** What an admin is told when deleting an owner's account would leave them no way to sign in. */
 export const OWNER_DELETE_REFUSAL = "The owner's account can't be deleted: they would have no way to sign in.";
 
+/**
+ * A password change refused because the password it proved is no longer the
+ * account's: another session changed it between this change's read and its
+ * write. Nothing was written; the routes answer it with a 409 and its words.
+ */
+export class PasswordChangedMeanwhileError extends Error {
+  constructor() {
+    super('Your password was changed from another session while this change was being made, so nothing was changed. Sign in with the new password.');
+    this.name = 'PasswordChangedMeanwhileError';
+  }
+}
+
+/**
+ * A password write the service refuses on purpose: the policy, a wrong
+ * current password, an account whose password is not kept here. The message
+ * is written for the caller, and a route answers it with a 400 — unlike any
+ * other error a password write raises, which is a fault and answered generic.
+ */
+export class PasswordRefusedError extends Error {
+  readonly status = 400;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'PasswordRefusedError';
+  }
+}
+
 /**
  * Decoy hash verified when the email is unknown or has no password set, so
  * those paths cost the same scrypt work as a real wrong-password attempt —
@@ -271,7 +301,7 @@ export class AuthService implements IAccountSwitchGuard {
       const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
       await this.assertAdmitted(normalizedEmail, 'bootstrap');
       const admin = await this.clearOwnerSwitchOff(await this.upsertUserByEmail(normalizedEmail, defaultName));
-      return { token: this.signToken(admin.id, admin.email), user: this.toClientUser(admin) };
+      return { token: this.signToken(admin), user: this.toClientUser(admin) };
     }
 
     // Always run one scrypt verification — against the stored hash when there
@@ -287,7 +317,7 @@ export class AuthService implements IAccountSwitchGuard {
     // is switched off would tell them it has an account.
     const signedIn = await this.clearOwnerSwitchOff(user);
     if (signedIn.deactivatedAt) throw new AccountDeactivatedError();
-    return { token: this.signToken(signedIn.id, signedIn.email), user: this.toClientUser(signedIn) };
+    return { token: this.signToken(signedIn), user: this.toClientUser(signedIn) };
   }
 
   /**
@@ -319,7 +349,7 @@ export class AuthService implements IAccountSwitchGuard {
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.clearOwnerSwitchOff(await this.upsertUserByEmail(normalizedEmail, displayName));
     if (user.deactivatedAt) throw new AccountDeactivatedError();
-    return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
+    return { token: this.signToken(user), user: this.toClientUser(user) };
   }
 
   /**
@@ -361,7 +391,7 @@ export class AuthService implements IAccountSwitchGuard {
     // than sending the admin off to pick a longer password first.
     this.assertNotSystemAccount(normalizedEmail);
     if (this.isEnvAdminEmail(normalizedEmail)) {
-      throw new Error(ENV_ADMIN_PASSWORD_REFUSAL);
+      throw new PasswordRefusedError(ENV_ADMIN_PASSWORD_REFUSAL);
     }
     this.assertPasswordPolicy(password);
     await this.assertAdmitted(normalizedEmail, 'admin-create');
@@ -370,16 +400,22 @@ export class AuthService implements IAccountSwitchGuard {
     // EXPLICITLY supplied name is persisted too; a blank name keeps the
     // existing display name rather than clobbering it with the local-part
     // fallback. `returning()` yields the authoritative row either way.
+    // A reset is a password change like any other: the session generation
+    // moves on with it, so every session opened with the old password ends,
+    // and a self-service change that read the row before it is refused
+    // rather than overwriting the reset (see {@link changePassword}).
+    const sessionVersion = sql`${users.sessionVersion} + 1`;
     const [row] = await this.db
       .insert(users)
       .values({ email: normalizedEmail, emailBidx: normalizedEmail, name: displayName, passwordHash })
       .onConflictDoUpdate({
         target: users.emailBidx,
         set: suppliedName
-          ? { passwordHash, name: suppliedName, updatedAt: new Date() }
-          : { passwordHash, updatedAt: new Date() },
+          ? { passwordHash, sessionVersion, name: suppliedName, updatedAt: new Date() }
+          : { passwordHash, sessionVersion, updatedAt: new Date() },
       })
       .returning();
+    this.activeCache.delete(row.id);
     return this.toClientUser(row);
   }
 
@@ -443,21 +479,26 @@ export class AuthService implements IAccountSwitchGuard {
       if (existing) {
         return { user: this.toClientUser(existing), created: false, passwordSet: false, deactivated: existing.deactivatedAt != null };
       }
-      throw new Error(ENV_ADMIN_PASSWORD_REFUSAL);
+      throw new PasswordRefusedError(ENV_ADMIN_PASSWORD_REFUSAL);
     }
     this.assertPasswordPolicy(password);
     await this.assertAdmitted(normalizedEmail, 'admin-create');
     const passwordHash = await hashPassword(password);
     const displayName = normalizedEmail.split('@')[0] || normalizedEmail;
+    // A first password on an existing account is a password write like any
+    // other, so the session generation moves on with it: a self-service
+    // first password that read the row before this one is refused rather
+    // than overwriting it (see {@link changePassword}).
     const [row] = await this.db
       .insert(users)
       .values({ email: normalizedEmail, emailBidx: normalizedEmail, name: displayName, passwordHash })
       .onConflictDoUpdate({
         target: users.emailBidx,
-        set: { passwordHash, updatedAt: new Date() },
+        set: { passwordHash, sessionVersion: sql`${users.sessionVersion} + 1`, updatedAt: new Date() },
         setWhere: and(isNull(users.passwordHash), isNull(users.deactivatedAt)),
       })
       .returning({ ...getTableColumns(users), created: CREATED });
+    if (row) this.activeCache.delete(row.id);
     if (row) return { user: this.toClientUser(row), created: row.created === true, passwordSet: true, deactivated: false };
     // The conflicting account has a password or is switched off: untouched.
     const [existing] = await this.db.select().from(users).where(eq(users.emailBidx, normalizedEmail)).limit(1);
@@ -586,31 +627,49 @@ export class AuthService implements IAccountSwitchGuard {
    * environment password is the platform's rescue path into a deployment and
    * is changed there, which is what the Account page says in place of the
    * form.
+   *
+   * A change ends every session opened before it: the row's
+   * `sessionVersion` moves on in the same write, so every token issued
+   * before it is refused at its next request (see {@link resolveSession}).
+   * The caller's own session is the one exception: the token returned here
+   * carries the new generation and is what the caller keeps using.
+   *
+   * The write only lands on the row as it was read. If another session
+   * changed the password between the read and the write, the current
+   * password this one proved is no longer current, so it is refused with
+   * {@link PasswordChangedMeanwhileError} and nothing is written. Two clicks
+   * of one form are the same race.
    */
   async changePassword(
     userId: string,
     currentPassword: string | undefined,
     newPassword: string,
-  ): Promise<void> {
+  ): Promise<{ token: string }> {
     const [user] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
-    if (!user) throw new Error('User not found');
+    if (!user) throw new PasswordRefusedError('User not found');
     // Before the policy check, so the deployment admin is told the real reason
     // rather than being sent to fix a password that would be refused anyway.
     this.assertNotSystemAccount(user.email);
     if (this.isEnvAdminEmail(user.email)) {
-      throw new Error(ENV_ADMIN_PASSWORD_REFUSAL);
+      throw new PasswordRefusedError(ENV_ADMIN_PASSWORD_REFUSAL);
     }
     this.assertPasswordPolicy(newPassword);
     if (user.passwordHash) {
       if (!currentPassword || !(await verifyPassword(currentPassword, user.passwordHash))) {
-        throw new Error('Current password is incorrect');
+        throw new PasswordRefusedError('Current password is incorrect');
       }
     }
     const passwordHash = await hashPassword(newPassword);
-    await this.db
+    const [changed] = await this.db
       .update(users)
-      .set({ passwordHash, updatedAt: new Date() })
-      .where(eq(users.id, userId));
+      .set({ passwordHash, sessionVersion: sql`${users.sessionVersion} + 1`, updatedAt: new Date() })
+      .where(and(eq(users.id, userId), eq(users.sessionVersion, user.sessionVersion)))
+      .returning();
+    if (!changed) throw new PasswordChangedMeanwhileError();
+    // Sessions read the row fresh (see resolveSession); the cached entry is
+    // dropped so nothing in this process keeps the old generation either.
+    this.activeCache.delete(userId);
+    return { token: this.signToken(changed) };
   }
 
   /**
@@ -664,18 +723,24 @@ export class AuthService implements IAccountSwitchGuard {
   /** Every password write calls this first: the system accounts never get one. */
   private assertNotSystemAccount(normalizedEmail: string): void {
     if (SYSTEM_ACCOUNT_EMAILS.includes(normalizedEmail)) {
-      throw new Error(SYSTEM_ACCOUNT_PASSWORD_REFUSAL);
+      throw new PasswordRefusedError(SYSTEM_ACCOUNT_PASSWORD_REFUSAL);
     }
   }
 
   private assertPasswordPolicy(password: string): void {
     if ((password ?? '').length < MIN_PASSWORD_LENGTH) {
-      throw new Error(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+      throw new PasswordRefusedError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
     }
   }
 
-  private signToken(userId: string, email: string): string {
-    return jwt.sign({ userId, email }, this.config.jwtSecret, { expiresIn: '7d' });
+  /**
+   * A session token for `user`, stamped with the session generation its row
+   * is at (`sv`): {@link resolveSession} refuses it once the row moves on.
+   */
+  private signToken(user: { id: string; email: string; sessionVersion: number }): string {
+    return jwt.sign({ userId: user.id, email: user.email, sv: user.sessionVersion }, this.config.jwtSecret, {
+      expiresIn: '7d',
+    });
   }
 
   /**
@@ -710,39 +775,55 @@ export class AuthService implements IAccountSwitchGuard {
 
   /**
    * The signature and expiry of a session token, and nothing else — whether
-   * its account is still on is {@link resolveSession}'s question. Every
+   * its account is still on, and whether the session is still honoured, are
+   * {@link resolveSession}'s questions. Every
    * place a session is ACCEPTED goes through that one.
    */
   verifyToken(token: string): { userId: string; email: string } {
+    const { userId, email } = this.decodeSession(token);
+    return { userId, email };
+  }
+
+  /** {@link verifyToken} plus the session generation the token was issued at. */
+  private decodeSession(token: string): { userId: string; email: string; sessionVersion: number } {
     const decoded = jwt.verify(token, this.config.jwtSecret) as {
       userId: string;
       email: string;
+      sv?: number;
     };
-    return { userId: decoded.userId, email: decoded.email };
+    // A token issued before sessions had generations carries none: it is of
+    // the first one, which is where every row started.
+    return { userId: decoded.userId, email: decoded.email, sessionVersion: decoded.sv ?? 0 };
   }
 
   /**
-   * A session token that may still be used: signed by us, not expired, and
-   * its account still on. A token outlives a deactivation by up to seven
+   * A session token that may still be used: signed by us, not expired, its
+   * account still on, and issued since the account's password last changed.
+   * A token outlives a deactivation or a password change by up to seven
    * days, so the signature alone no longer says the bearer may enter.
-   * Throws for an invalid token, {@link AccountDeactivatedError} for one
-   * whose account was switched off.
+   * Throws for an invalid token, {@link SessionEndedError} for one a
+   * password change ended, {@link AccountDeactivatedError} for one whose
+   * account was switched off.
    */
   async resolveSession(token: string): Promise<{ userId: string; email: string }> {
-    const claim = this.verifyToken(token);
-    let active: boolean;
+    const { sessionVersion, ...claim } = this.decodeSession(token);
+    let account: { active: boolean; sessionVersion: number };
     try {
-      active = await this.isActive(claim.userId);
+      // Read fresh, never from the cache: a password changed on another
+      // replica must end this token at its very next request, and only the
+      // row can say it was.
+      account = await this.accountState(claim.userId, { fresh: true });
     } catch (err) {
       // The token is fine; the database is not. Said apart from a refusal, so
       // an outage is a 500 and not a sign-out (see `AuthBackendError`).
       throw new AuthBackendError(err);
     }
-    if (!active) throw new AccountDeactivatedError();
+    if (!account.active) throw new AccountDeactivatedError();
+    if (sessionVersion !== account.sessionVersion) throw new SessionEndedError();
     return claim;
   }
 
-  private readonly activeCache = new Map<string, { active: boolean; at: number }>();
+  private readonly activeCache = new Map<string, { active: boolean; sessionVersion: number; at: number }>();
 
   /**
    * Whether the account behind a credential is on: it exists and no admin
@@ -762,18 +843,38 @@ export class AuthService implements IAccountSwitchGuard {
    * ({@link clearOwnerSwitchOff}).
    */
   async isActive(userId: string): Promise<boolean> {
+    return (await this.accountState(userId)).active;
+  }
+
+  /**
+   * {@link isActive}'s answer and the session generation the account is at,
+   * read and cached together; a password change in this process forgets the
+   * entry at once, as switching an account off does. `fresh` reads the row
+   * whatever the cache holds (and refreshes it): {@link resolveSession}'s
+   * question, since a session's generation must hold on every replica.
+   */
+  private async accountState(
+    userId: string,
+    { fresh = false }: { fresh?: boolean } = {},
+  ): Promise<{ active: boolean; sessionVersion: number }> {
     const now = Date.now();
     const hit = this.activeCache.get(userId);
-    if (hit && now - hit.at < ACTIVE_CACHE_MS) return hit.active;
+    if (!fresh && hit && now - hit.at < ACTIVE_CACHE_MS) return hit;
     const [found] = await this.db
-      .select({ id: users.id, email: users.email, deactivatedAt: users.deactivatedAt })
+      .select({
+        id: users.id,
+        email: users.email,
+        deactivatedAt: users.deactivatedAt,
+        sessionVersion: users.sessionVersion,
+      })
       .from(users)
       .where(eq(users.id, userId))
       .limit(1);
     const row = found && (await this.clearOwnerSwitchOff(found));
     const active = row !== undefined && (!row.deactivatedAt || this.isEnvAdminEmail(row.email ?? ''));
-    this.activeCache.set(userId, { active, at: now });
-    return active;
+    const entry = { active, sessionVersion: row?.sessionVersion ?? 0, at: now };
+    this.activeCache.set(userId, entry);
+    return entry;
   }
 
   /**

package/src/modules/auth/index.ts

@@ -15,6 +15,8 @@ export {
   AccountChangeRefusedError,
   AccountDeactivatedError,
   AuthBackendError,
+  SESSION_ENDED_MESSAGE,
+  SessionEndedError,
   admitEveryone,
   type AccountAdmissionVerdict,
   type AccountProvisionReason,

package/src/modules/auth/oidc-auth-provider.ts

@@ -4,8 +4,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('oidc');
 import type express from 'express';
 import type { AuthProviderPlugin } from './auth.routes.js';
-import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
-import { AUTH_COOKIE_NAME } from './auth.middleware.js';
+import { setAuthCookie } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
 import { AccountAdmissionRefusedError, AccountDeactivatedError } from './account-admission.js';
 import { normalizeIssuerUrl } from '../settings/index.js';
@@ -311,13 +310,7 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         } catch (error) {
           log.error('OIDC sign-in record failed:', { err: error });
         }
-        res.cookie(AUTH_COOKIE_NAME, token, {
-          httpOnly: true,
-          sameSite: 'lax',
-          secure: cookieSecure,
-          maxAge: AUTH_COOKIE_MAX_AGE_S * 1000,
-          path: '/',
-        });
+        setAuthCookie(res, token, cookieSecure);
         res.redirect(`${publicFrontendUrl}/auth/oidc/callback#token=${encodeURIComponent(token)}`);
       } catch (error) {
         // A refused provisioning is not a failed sign-in: the identity was

package/src/modules/code-mode/code-mode.tool.ts

@@ -51,7 +51,7 @@ export function createCallToolChainTool(
       `There is NO single calling shape: some tools take their arguments under a \`body\` object, others take them flat. Call each tool as the \`Call:\` line at the top of its own description shows — it is generated from that tool's input schema, and every tool in \`${ns}\` has one. Every argument a tool declares REQUIRED must be present; for the knowledge-base tools that includes \`branch\`. Arguments that do not match the schema are refused before anything is sent or run, and the refusal carries the tool's interface.`,
       'Error handling inside the chain: a failing tool call THROWS, and the thrown error\'s `.message` holds the server\'s actual reason (e.g. a 403 with the explanation, not just a status code). If you catch it, surface `err.message` (and `err.status` / `err.data` when present) — NEVER `return { error: err }` or otherwise return the raw Error object, because an Error serializes to `{}` (its `message` is non-enumerable) and the reason is lost. If you don\'t need to handle it, just let it throw — the runtime already reports `err.message` back to you.',
       `Failures are answered, never dropped: a chain that throws comes back with \`success: false\` and the reason, and one that outlives \`timeout\` (default ${CHAIN_TIMEOUT_DEFAULT_MS} ms, maximum ${CHAIN_TIMEOUT_MAX_MS} ms) comes back saying it timed out — raise \`timeout\` or split the work and run it again. Either way your next tool call works as usual.`,
-      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (its `branch` is ignored) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
+      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (any existing branch as `branch`; it is not used) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
     ].join('\n\n'),
     inputSchema: z.object({
       code: z
@@ -121,7 +121,7 @@ export function createCallToolChainTool(
           truncated: true,
           result_ref: ref,
           result_bytes: bytes,
-          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (\`branch\` is ignored) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
+          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (any existing branch as \`branch\`; it is not used) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
         };
       } catch (err) {
         // The chain itself SUCCEEDED and only its delivery failed, so the logs

package/src/modules/connection-probe/__tests__/connection-probe.service.test.ts

@@ -4,8 +4,8 @@ import type {
   IToolManualService,
   ToolHealthCheck,
   ToolProbeTarget,
-} from '../../tool-manuals/tool-manuals.contract.js';
-import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+} from '../../tool-manuals/index.js';
+import type { ISecretsVaultService } from '../../secrets-vault/index.js';
 
 /**
  * The three-way verdict is the whole point of this module, and the line that
@@ -33,7 +33,7 @@ vi.mock('@utcp/code-mode', () => ({
   CodeModeUtcpClient: { create: () => createClientMock() },
 }));
 
-const { ConnectionProbeService, readCapped } = await import('../connection-probe.service.js');
+const { ConnectionProbeService } = await import('../connection-probe.service.js');
 
 const DECLARED_PROBE: ToolHealthCheck = {
   url: 'https://api.acme.test/me',
@@ -739,25 +739,6 @@ describe('ConnectionProbeService: what the probe concludes', () => {
     expect(r?.detail!.length).toBeLessThan(400);
     expect(cancelled).toBe(true);
   });
-
-  /**
-   * The cap has to bound what is DECODED, not merely how many times we loop.
-   * Counting a chunk against the budget after decoding it lets a provider that
-   * answers in one huge chunk put the whole thing through the decoder — the
-   * bound bypassed by exactly the party it exists to bound. Asserted on
-   * `readCapped` directly because the caller's 200-character snippet is
-   * identical either way, which is how the first version of this passed.
-   */
-  it('holds one oversized chunk to the byte budget, not just the loop', async () => {
-    const oneHugeChunk = new ReadableStream<Uint8Array>({
-      start(controller) {
-        controller.enqueue(new TextEncoder().encode('x'.repeat(5_000_000)));
-        controller.close();
-      },
-    });
-
-    const out = await readCapped(new Response(oneHugeChunk), 8 * 1024);
-
-    expect(out.length).toBe(8 * 1024);
-  });
+  // The byte budget's own property (one oversized chunk held to the cap) is
+  // asserted on the shared reader in `shared/__tests__/read-capped.test.ts`.
 });

package/src/modules/connection-probe/connection-probe.service.ts

@@ -12,6 +12,7 @@ import type { ISecretsVaultService } from '../secrets-vault/index.js';
 import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { readCapped } from '../../shared/read-capped.js';
 import type { IConnectionProbeService, ProbeStatus, ProbeVerdict } from './connection-probe.contract.js';
 
 /** How long a probe may take before we call it inconclusive. */
@@ -753,37 +754,3 @@ async function describeRejection(res: Response, redactor: SecretRedactor): Promi
   }
 }
 
-/**
- * At most `limit` bytes of a response body, decoded as text.
- *
- * Each CHUNK is sliced to the remaining budget before being decoded, not just
- * counted against it: a provider that answers in one 5MB chunk would otherwise
- * put the whole thing through the decoder before the loop noticed it was over,
- * which is the bound bypassed by the very party it is meant to bound.
- *
- * Exported for its test — the property here is how much is held in memory,
- * which the caller's 200-character snippet hides completely.
- */
-export async function readCapped(res: Response, limit: number): Promise<string> {
-  const reader = res.body?.getReader();
-  // No stream (a mocked or already-consumed response): fall back to the whole
-  // body, which for those cases is ours and small.
-  if (!reader) return (await res.text()).slice(0, limit);
-  const decoder = new TextDecoder();
-  let out = '';
-  let read = 0;
-  try {
-    while (read < limit) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const remaining = limit - read;
-      const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
-      read += chunk.byteLength;
-      out += decoder.decode(chunk, { stream: true });
-      if (chunk.byteLength < value.byteLength) break;
-    }
-  } finally {
-    await reader.cancel().catch(() => {});
-  }
-  return out;
-}

package/src/modules/database/__tests__/session-version-migration.pg.test.ts

@@ -0,0 +1,133 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { sql } from 'drizzle-orm';
+import { closeDb, createDb, type Database } from '../connection.js';
+import { runCoreMigrations, runPiiEncryptionBackfill } from '../migrate.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { IndexOnWrite, SealOnWrite } from '../../../shared/column-crypto.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * Migration 0022 on a real Postgres, from both states a deployment can be in
+ * when it starts on this release: without `users.session_version` (every
+ * account starts at 0, so nobody is signed out by the upgrade), and with the
+ * column already there (the guarded `ADD COLUMN` changes nothing, so the
+ * generations it holds, and the sessions they honour, survive the start).
+ *
+ * Runs where `TEST_DATABASE_URL` names a server this role may create
+ * databases on, each test in a scratch database of its own.
+ */
+const KEY = randomBytes(32).toString('base64');
+const open: Database[] = [];
+const folders: string[] = [];
+
+/** The core history as it stood BEFORE 0022: the packaged folder minus 0022, in a folder of this test's own. */
+function historyBefore0022(): string {
+  const folder = mkdtempSync(path.join(tmpdir(), 'hexis-core-before-0022-'));
+  folders.push(folder);
+  cpSync(coreMigrationsDir(), folder, { recursive: true });
+  rmSync(path.join(folder, '0022_session_version.sql'));
+  rmSync(path.join(folder, 'meta', '0022_snapshot.json'));
+  const journalPath = path.join(folder, 'meta', '_journal.json');
+  const journal = JSON.parse(readFileSync(journalPath, 'utf8')) as { entries: { idx: number }[] };
+  journal.entries = journal.entries.filter((e) => e.idx < 22);
+  writeFileSync(journalPath, JSON.stringify(journal, null, 2));
+  return folder;
+}
+
+/**
+ * A database an older version left: started on the history to 0021, holding
+ * the accounts that version wrote, through SQL that names only the columns
+ * it knew. `withColumn` adds `session_version` by hand first, as a database
+ * that already has it would, and gives each account a generation of its own.
+ */
+async function olderDeployment(withColumn: boolean): Promise<Database> {
+  const db = createDb(await scratchDatabaseUrl('hexis_session_version'), { piiKey: KEY });
+  open.push(db);
+  await migrate(db, { migrationsFolder: historyBefore0022(), migrationsTable: '__drizzle_migrations_core' });
+  await runPiiEncryptionBackfill(db);
+  if (withColumn) await db.execute(sql`alter table users add column session_version integer default 0 not null`);
+  const seal = (plain: string) => new SealOnWrite(plain) as unknown as string;
+  const index = (plain: string) => new IndexOnWrite(plain) as unknown as string;
+  const account = (email: string, name: string) => sql`(${seal(email)}, ${index(email)}, ${seal(name)})`;
+  await db.execute(sql`
+    insert into users (email, email_bidx, name) values
+      ${account('ada@example.com', 'Ada')},
+      ${account('bo@example.com', 'Bo')}
+  `);
+  if (withColumn) {
+    await db.execute(sql`update users set session_version = 3 where email_bidx = ${index('ada@example.com')}`);
+    await db.execute(sql`update users set session_version = 7 where email_bidx = ${index('bo@example.com')}`);
+  }
+  return db;
+}
+
+/** How many migrations the packaged history holds — what a fresh start records as applied. */
+function packagedHistoryLength(): number {
+  const journal = JSON.parse(readFileSync(path.join(coreMigrationsDir(), 'meta', '_journal.json'), 'utf8')) as {
+    entries: unknown[];
+  };
+  return journal.entries.length;
+}
+
+/** Each account's generation, in a fixed order. */
+const generations = async (db: Database) =>
+  (await db.execute(sql`select session_version from users order by session_version`)).rows.map(
+    (r) => (r as { session_version: number }).session_version,
+  );
+
+/** What the column is: its type, default and nullability, as Postgres reports them. */
+const columnShape = async (db: Database) =>
+  (
+    await db.execute(sql`
+      select data_type, column_default, is_nullable from information_schema.columns
+      where table_schema = 'public' and table_name = 'users' and column_name = 'session_version'
+    `)
+  ).rows;
+
+const EXPECTED_SHAPE = [{ data_type: 'integer', column_default: '0', is_nullable: 'NO' }];
+
+describe.skipIf(!PG_ADMIN_URL)('migration 0022 (users.session_version), on a real Postgres', () => {
+  afterAll(async () => {
+    for (const db of open.splice(0)) await closeDb(db);
+    for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true });
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  it(
+    'adds the column at 0 for every existing account, so no session is ended by the upgrade',
+    async () => {
+      const db = await olderDeployment(false);
+      expect(await columnShape(db)).toEqual([]);
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      expect(await columnShape(db)).toEqual(EXPECTED_SHAPE);
+      expect(await generations(db)).toEqual([0, 0]);
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'finds the column already there and changes nothing, keeping every generation it holds',
+    async () => {
+      const db = await olderDeployment(true);
+      expect(await columnShape(db)).toEqual(EXPECTED_SHAPE);
+
+      await runCoreMigrations(db, coreMigrationsDir());
+
+      expect(await columnShape(db)).toEqual(EXPECTED_SHAPE);
+      expect(await generations(db)).toEqual([3, 7]);
+      // And 0022 is recorded as applied, so the next start does not try it
+      // again — judged against the packaged history's own length, so a later
+      // migration does not make this count stale.
+      const applied = await db.execute(sql`select count(*)::int as n from drizzle.__drizzle_migrations_core`);
+      expect((applied.rows[0] as { n: number }).n).toBe(packagedHistoryLength());
+    },
+    PG_TEST_TIMEOUT,
+  );
+});