@bevel-software/platform-core-backend 0.33.0 → 0.34.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/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,
+  );
+});

package/src/modules/database/core-schema.ts

@@ -41,6 +41,16 @@ export const users = pgTable('users', {
    * until an admin (or the user, from their Account page) sets one.
    */
   passwordHash: text('password_hash'),
+  /**
+   * Which generation of this account's sessions is honoured. Every session
+   * token carries the value it was issued at (`sv`; a token from before the
+   * column existed carries none and counts as 0), and one whose value is not
+   * the row's is refused. Changing the password moves it on, so every session
+   * opened with the old password ends at its next request — the one that
+   * made the change is handed a fresh token. Connection keys are not
+   * sessions and do not look at it.
+   */
+  sessionVersion: integer('session_version').default(0).notNull(),
   /**
    * The one onboarding fact the server keeps: has this person concluded the
    * connect-your-agent setup (the welcome page's Done, or the reminder
@@ -277,6 +287,15 @@ export const externalApiKeys = pgTable('api_tokens', {
    * deleted in one step.
    */
   deletedAt: timestamp('deleted_at'),
+  /**
+   * The agent configuration the key connects as — a repo-relative knowledge-base
+   * path, chosen when the key is minted. Null is Everything: the key sees
+   * every tool, skill and plugin its owner may read, exactly as before the
+   * column existed. The path is the whole record: the file is re-read on
+   * every surface build, so editing it changes what the key sees without a
+   * new key (see `modules/agent-scope`).
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   byUser: index('api_tokens_by_user').on(t.userId),
 }));
@@ -486,6 +505,12 @@ export const oauthAuthCodes = pgTable('oauth_auth_codes', {
   expiresAt: timestamp('expires_at').notNull(),
   consumedAt: timestamp('consumed_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
+  /**
+   * The "Connect as" choice made on the consent step, carried from Finish to
+   * the token exchange that makes (or finds) the agent connection — the code
+   * is the only thing that travels between the two. Null is Everything.
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   // Sweep expired/spent rows without a full scan.
   byExpiry: index('oauth_auth_codes_by_expiry').on(t.expiresAt),
@@ -525,6 +550,14 @@ export const agentConnections = pgTable('agent_connections', {
   revokedAt: timestamp('revoked_at'),
   /** `owner` | `admin` — who ended it; null while live. Same vocabulary as `api_tokens.revoked_by`. */
   revokedBy: text('revoked_by'),
+  /**
+   * The agent configuration the person chose to connect as on the consent step — a
+   * repo-relative knowledge-base path — or null for Everything. Set by every
+   * consent that lands on the row, so re-authorising with another choice
+   * changes what the agent sees from its next request. Same meaning as
+   * `api_tokens.agent_path`.
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   byUser: index('agent_connections_by_user').on(t.userId),
   liveUnq: uniqueIndex('agent_connections_live_unq')

package/src/modules/declared-variables/__tests__/declared-variables.route.test.ts

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createDeclaredVariableRoutes } from '../declared-variables.routes.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+import { ConnectionScope, type IAgentScopeResolver } from '../../agent-scope/index.js';
 
 /**
  * The one core route that releases secret VALUES. What is worth pinning here is
@@ -46,6 +47,9 @@ async function mount(opts: {
   source?: 'session' | 'external' | 'internal';
   manuals?: ToolManualSummary[];
   secrets?: Record<string, string>;
+  /** The `.agent` file the caller's connection was made as; absent is Everything. */
+  agentPath?: string;
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
 }): Promise<Harness> {
   const userId = opts.userId ?? 'user-1';
   const source = opts.source ?? 'external';
@@ -64,10 +68,18 @@ async function mount(opts: {
       toolManualService,
       secretsVault,
       (req, _res, next) => {
-        if (userId) req.toolAuth = { userId, source, scope: 'write' } as typeof req.toolAuth;
+        if (userId) {
+          req.toolAuth = {
+            userId,
+            source,
+            scope: 'write',
+            ...(opts.agentPath ? { agentPath: opts.agentPath } : {}),
+          } as typeof req.toolAuth;
+        }
         next();
       },
       async () => 'runner@x.eu',
+      opts.agentScope,
     ),
   );
   httpServer = await new Promise<HttpServer>((r) => {
@@ -133,6 +145,37 @@ describe('POST /agent/local-tools/:slug/variables', () => {
     expect(resolve).not.toHaveBeenCalled();
   });
 
+  it("releases only the variables of a connector the connection's .agent file loads", async () => {
+    const agent = { path: 'Agents/ops.agent', name: 'Ops' };
+    const loading = (connectors: string[]) => ({
+      resolve: async () => ConnectionScope.narrowed(agent, { skills: [], connectors, platformTools: null }, 'fp'),
+    });
+    // A folder entry over the tool's plugin loads it.
+    const inScope = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+      agentPath: agent.path,
+      agentScope: loading(['Plugins/Engineering']),
+    });
+    expect((await fetch(`${inScope.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(200);
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    // A readable tool the file does not load is as absent as an unreadable one.
+    const outOfScope = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+      agentPath: agent.path,
+      agentScope: loading(['Plugins/billing.tool']),
+    });
+    expect((await fetch(`${outOfScope.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+    expect(outOfScope.resolve).not.toHaveBeenCalled();
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    // A narrowed connection with no resolver wired loads nothing.
+    const unwired = await mount({ manuals: [GIT_TOOL], agentPath: agent.path });
+    expect((await fetch(`${unwired.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+  });
+
   it('403s an unauthenticated caller', async () => {
     const { base } = await mount({ userId: '', manuals: [GIT_TOOL] });
     expect((await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(403);