@bevel-software/platform-core-backend 0.23.0 → 0.25.0

package/migrations/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1790892582327,
       "tag": "0015_account_deactivation",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1790933605784,
+      "tag": "0016_pii_encryption",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,8 +52,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-shared": "0.23.0",
-    "@bevel-software/platform-mcp-core": "0.23.0"
+    "@bevel-software/platform-mcp-core": "0.25.0",
+    "@bevel-software/platform-shared": "0.25.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/__tests__/lifecycle.test.ts

@@ -262,6 +262,14 @@ describe('createShutdown', () => {
             order.push('backgroundJobs.drain');
           },
         },
+        agentUploadStore: {
+          stopSweeping() {
+            order.push('agentUploadStore.stopSweeping');
+          },
+          async drainSweep() {
+            order.push('agentUploadStore.drainSweep');
+          },
+        },
         db: {
           $client: {
             async end() {
@@ -289,7 +297,12 @@ describe('createShutdown', () => {
       'server.close',
       'server.closeAllConnections',
       'backgroundJobs.stopSweeping',
+      // The upload sweep is stopped in the same breath as the other timers,
+      // and drained before the pool goes: a graph that is stopping must not
+      // leave a sweep walking the staging root its replacement will stage into.
+      'agentUploadStore.stopSweeping',
       'backgroundJobs.drain',
+      'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -310,7 +323,13 @@ describe('createShutdown', () => {
     d.finishClose();
     await settle();
     // The jobs are still running: nothing after them has run.
-    expect(d.order).toEqual(['server.close', 'server.closeAllConnections', 'backgroundJobs.stopSweeping', 'backgroundJobs.drain']);
+    expect(d.order).toEqual([
+      'server.close',
+      'server.closeAllConnections',
+      'backgroundJobs.stopSweeping',
+      'agentUploadStore.stopSweeping',
+      'backgroundJobs.drain',
+    ]);
     release();
     await done;
     expect(d.order.slice(-2)).toEqual(['commitWorker.stop', 'db.end']);
@@ -339,6 +358,7 @@ describe('createShutdown', () => {
     const d = deps();
     // A stop that lands mid-boot: the services exist, the jobs do not.
     delete (d.deps as { backgroundJobs?: unknown }).backgroundJobs;
+    delete (d.deps as { agentUploadStore?: unknown }).agentUploadStore;
     const shutdown = createShutdown(d.deps as never);
     const done = shutdown('SIGTERM');
     await settle();
@@ -363,7 +383,12 @@ describe('createShutdown', () => {
     await settle();
     d.finishClose();
     await done;
-    expect(d.order.slice(-3)).toEqual(['backgroundJobs.drain', 'commitWorker.stop', 'db.end']);
+    expect(d.order.slice(-4)).toEqual([
+      'backgroundJobs.drain',
+      'agentUploadStore.drainSweep',
+      'commitWorker.stop',
+      'db.end',
+    ]);
   });
 
   it('does not hang on a step that never finishes, and still runs the rest', async () => {
@@ -376,7 +401,9 @@ describe('createShutdown', () => {
       'server.close',
       'server.closeAllConnections',
       'backgroundJobs.stopSweeping',
+      'agentUploadStore.stopSweeping',
       'backgroundJobs.drain',
+      'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -413,6 +440,14 @@ describe('stopCore', () => {
             order.push('backgroundJobs.drain');
           },
         },
+        agentUploadStore: {
+          stopSweeping() {
+            order.push('agentUploadStore.stopSweeping');
+          },
+          async drainSweep() {
+            order.push('agentUploadStore.drainSweep');
+          },
+        },
         startupRetry: {
           stop() {
             order.push('startupRetry.stop');
@@ -436,13 +471,31 @@ describe('stopCore', () => {
     await stopCore(g.core as never);
     expect(g.order).toEqual([
       'backgroundJobs.stopSweeping',
+      'agentUploadStore.stopSweeping',
       'startupRetry.stop',
       'backgroundJobs.drain',
+      'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
     ]);
   });
 
+  it('stops the upload sweep, so an evicted tenant cannot sweep its own replacement', async () => {
+    const g = graph();
+    await stopCore(g.core as never);
+    // This is the eviction path: the next activation of the same tenant builds
+    // a new store over the SAME staging directory with an empty record map, so
+    // a sweep left running from this graph would read the replacement's files
+    // as orphans and delete them under an apply about to read them. Both
+    // halves, in order — the timer cleared, then the sweep in flight awaited
+    // before anything else lets go.
+    const stopped = g.order.indexOf('agentUploadStore.stopSweeping');
+    const drained = g.order.indexOf('agentUploadStore.drainSweep');
+    expect(stopped).toBeGreaterThanOrEqual(0);
+    expect(stopped).toBeLessThan(drained);
+    expect(drained).toBeLessThan(g.order.indexOf('db.end'));
+  });
+
   it('forgets the graph\'s secrets scope, so a descriptor that outlives it resolves nothing', async () => {
     const g = graph();
     registerBevelSecretsVariableLoader(
@@ -459,14 +512,28 @@ describe('stopCore', () => {
     const g = graph();
     const core = { ...g.core, startupRetry: null, secretsScope: undefined };
     await stopCore(core as never);
-    expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'backgroundJobs.drain', 'commitWorker.stop', 'db.end']);
+    expect(g.order).toEqual([
+      'backgroundJobs.stopSweeping',
+      'agentUploadStore.stopSweeping',
+      'backgroundJobs.drain',
+      'agentUploadStore.drainSweep',
+      'commitWorker.stop',
+      'db.end',
+    ]);
   });
 
   it('does not wait past the budget for a worker that never stops, and still ends the pool', async () => {
     const g = graph();
     const core = { ...g.core, commitWorker: { stop: () => new Promise<void>(() => undefined) } };
     await stopCore(core as never, { deadlineMs: 50 });
-    expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'startupRetry.stop', 'backgroundJobs.drain', 'db.end']);
+    expect(g.order).toEqual([
+      'backgroundJobs.stopSweeping',
+      'agentUploadStore.stopSweeping',
+      'startupRetry.stop',
+      'backgroundJobs.drain',
+      'agentUploadStore.drainSweep',
+      'db.end',
+    ]);
   });
 });
 

package/src/core/create-core-server.ts

@@ -4,6 +4,10 @@ import path from 'node:path';
 import type { Router, RequestHandler } from 'express';
 import { createAuthRoutes } from '../modules/auth/auth.routes.js';
 import { createWorkspaceRoutes } from '../modules/workspace/workspace.routes.js';
+import {
+  createAgentUploadRoutes,
+  isAgentUploadRawBodyPath,
+} from '../modules/workspace/agent-upload.routes.js';
 import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals.middleware.js';
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
@@ -210,7 +214,14 @@ export async function createCoreServer(
   // refused with its own 403, never parsed first (and answered 400 or 413).
   app.use(createWriteGateMiddleware(core.writeAccess));
   app.use((req, res, next) => {
-    if (jsonExemptPaths.has(req.path) || isSyncRawBodyPath(req.path)) return next();
+    // The agent upload route is exempt for the same reason `/api/sync` is:
+    // whoever needs the EXACT bytes has to see them before any parser can
+    // drain the stream. `curl --data-binary @file.zip` with a JSON
+    // content-type is a request an agent can make, and the parser would
+    // otherwise leave the handler nothing to store.
+    if (jsonExemptPaths.has(req.path) || isSyncRawBodyPath(req.path) || isAgentUploadRawBodyPath(req.path)) {
+      return next();
+    }
     return globalJson(req, res, next);
   });
 
@@ -445,7 +456,14 @@ export async function createCoreServer(
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
   registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate);
+  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore);
+  // The agent upload route, on the same router as the tool endpoints so it
+  // mounts ahead of the JWT `/api` mounts below — but WITHOUT `toolAuth`: its
+  // whole credential is the single-use token in its path, which is the point
+  // (an agent's `curl` carries no session and no connection key). It resolves
+  // no workspace and writes into none; every access, platform-file and branch
+  // rule is applied later by `apply_file_upload`.
+  toolsRouter.use(createAgentUploadRoutes({ uploads: core.agentUploadStore }));
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker);
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
@@ -489,7 +507,7 @@ export async function createCoreServer(
   // What every connected agent is told at session start, as the hosted proxy
   // composes it: read by the local `hexis-mcp` bridge at startup and by the
   // External agent access card. Same `manualAuth`, same router, as `all-tools`.
-  toolsRouter.use(createAgentInstructionsRoutes(core.manualAuthMiddleware, core.readAgentPreamble));
+  toolsRouter.use(createAgentInstructionsRoutes(core.manualAuthMiddleware, core.readAgentPreamble, () => core.kb.layout));
   // The fingerprint of the caller's released catalog. The local `hexis-mcp`
   // server polls it to learn that a manual or a skill changed under a
   // connection it cannot be pushed to; nothing else consults it. Same

package/src/core/create-core-services.ts

@@ -54,6 +54,7 @@ function parseDomainList(raw: string): string[] {
     .filter((d) => d.length > 0);
 }
 import { SpillStore } from '../modules/workspace/spill-store.js';
+import { AgentUploadStore, assertUploadsRootOutsideWorkspaces } from '../modules/workspace/agent-upload.store.js';
 import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
@@ -220,6 +221,8 @@ export interface CoreServices {
   /** The scope this graph's vault is registered under with the UTCP variable loader. */
   secretsScope: string;
   spillStore: SpillStore;
+  /** The bytes an agent uploaded, held until `apply_file_upload` lands them or their token expires. */
+  agentUploadStore: AgentUploadStore;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -357,7 +360,11 @@ export async function createCoreServices(
   // the default schema, so a single-tenant deployment keeps the lock ids and
   // the ledger it always had.
   const tenantKey = config.dbSchema === DEFAULT_DB_SCHEMA ? '' : config.dbSchema;
-  const db = getDb(config.databaseUrl, { schema: config.dbSchema });
+  // The handle holds this knowledge base's key for its personal-data columns:
+  // the same `SECRETS_ENC_KEY` that seals its stored credentials — its own
+  // derived one, for a tenant — so everything in the schema opens with one
+  // key and nothing in it opens with another tenant's.
+  const db = getDb(config.databaseUrl, { schema: config.dbSchema, piiKey: config.secretsEncKey });
   // A schema of its own is created on first use, so a tenant's first
   // activation needs nothing done by hand; `public` always exists. Then the
   // server is asked whether the connections really search that schema: a
@@ -377,6 +384,10 @@ export async function createCoreServices(
   // package runs its own squashed idempotent CORE history from the packaged
   // `migrations/` folder, tracked in `__drizzle_migrations_core`. An
   // enterprise overlay runs its own history AFTER this (see migrate.ts).
+  // `runCoreMigrations` also seals any pre-encryption plaintext PII rows and
+  // swaps the unique constraints onto the blind-index columns (see
+  // migrate.ts), under the same lock, before any service reads or writes a
+  // PII column.
   await runCoreMigrations(db, coreMigrationsDir());
 
   // Deployment settings come next, before ANY service is built: the KB remote
@@ -652,6 +663,17 @@ export async function createCoreServices(
   // Shared, workspace-independent store for oversized `call_tool_chain` results,
   // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
   const spillStore = new SpillStore(config.spillRoot);
+  // The upload route an agent lands files by, so their content never passes
+  // through the model. Bytes live BESIDE the workspaces root (never inside
+  // one) until the apply commits them or the token expires — checked here
+  // rather than assumed, because a root configured inside a workspace would
+  // put bytes no gate has judged where the file tools read.
+  await assertUploadsRootOutsideWorkspaces(config.agentUploadsRoot, config.workspacesRoot);
+  const agentUploadStore = new AgentUploadStore({
+    root: config.agentUploadsRoot,
+    publicBaseUrl: config.publicBackendUrl,
+    tokenPrefix: config.uploadTokenPrefix,
+  });
   // Office-document/PDF text extraction for `read_file`/`grep`, cached by
   // content hash beside the workspaces root (see `DocExtractionCache`).
   const docExtractService = new DocExtractService(config.docExtractCacheRoot);
@@ -1167,6 +1189,9 @@ export async function createCoreServices(
       // For the needs-authorization setup link surfaced to external agents.
       publicFrontendUrl: config.publicFrontendUrl,
       readAgentPreamble: readPreamble,
+      // The guide's name the shared file rules spell, read per request so a name
+      // the setup save applies lands without a restart.
+      kbLayout: () => kb.layout,
       secretsScope,
     },
     // Pre-dispatch per-user credential check: the vault answers "has this caller
@@ -1404,6 +1429,7 @@ export async function createCoreServices(
     kb,
     kbDirName,
     spillStore,
+    agentUploadStore,
     docExtractService,
     accessControl,
     creatorAccess,

package/src/core/lifecycle.ts

@@ -428,6 +428,15 @@ export interface CoreStopDeps {
    * to it. Optional: a caller that has not built them yet passes nothing.
    */
   backgroundJobs?: { stopSweeping(): void; drain(): Promise<void> };
+  /**
+   * The agent upload store, whose own sweep deletes staged bytes nobody
+   * applied. Stopped with this graph because the next graph for the same
+   * tenant stages into the SAME directory with an empty record map: a sweep
+   * left running from a store that is gone would read the replacement's files
+   * as orphans and delete them under an apply that is about to read them.
+   * Optional: a caller that has not built one passes nothing.
+   */
+  agentUploadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
   /** The startup phase's retry, if the boot left one asking — see {@link BootableCore.startupRetry}. */
   startupRetry?: { stop(): void } | null;
   /** The database — its pool is ended last, once nothing above can still need it. */
@@ -511,6 +520,10 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // earliest point the interval is dead weight. Synchronous and unfailing
   // — it just clears an interval — so it needs no budget of its own.
   deps.backgroundJobs?.stopSweeping();
+  // And the upload store's sweep, for the same reason and in the same breath:
+  // synchronous, and it only clears an interval and tells a sweep already
+  // running to stop deleting.
+  deps.agentUploadStore?.stopSweeping();
   // A startup phase still asking for an unreachable remote stops asking:
   // synchronous, and nothing after it must be able to clone into a
   // workspaces folder that is about to belong to nobody.
@@ -524,6 +537,12 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.backgroundJobs) {
     await bounded(deps.backgroundJobs.drain(), remaining(), 'finishing the background jobs', log);
   }
+  // The sweep in flight when the interval was cleared: awaited so the next
+  // graph for this tenant cannot start staging bytes while a store it has
+  // never heard of is still walking the same directory.
+  if (deps.agentUploadStore) {
+    await bounded(deps.agentUploadStore.drainSweep(), remaining(), 'finishing the upload sweep', log);
+  }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
   await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);

package/src/core-config.ts

@@ -88,6 +88,7 @@ export interface TenantConfig {
   readonly workspacesRoot: string;
   readonly backupsRoot: string;
   readonly spillRoot: string;
+  readonly agentUploadsRoot: string;
   readonly docExtractCacheRoot: string;
   readonly jwtSecret: string;
   readonly adminEmail: string;
@@ -184,6 +185,21 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * never committed, best-effort GC'd on write.
    */
   readonly spillRoot: string;
+  /**
+   * Sibling-to-`workspacesRoot` location for the bytes an agent uploads with
+   * `request_file_upload`, held until `apply_file_upload` lands them (or their
+   * token expires, whichever comes first). BESIDE the workspaces, never inside
+   * one, and that placement is the point: an upload is content the server has
+   * accepted but not yet judged, so no file tool may name it — every workspace
+   * path resolves against a branch's checkout, and there is no spelling of one
+   * that reaches in here. Ephemeral and never committed.
+   *
+   * `AGENT_UPLOADS_ROOT` overrides it, and the placement is CHECKED at boot
+   * (`assertUploadsRootOutsideWorkspaces`): a value inside `workspacesRoot` —
+   * or one that resolves there through a link — refuses to start rather than
+   * quietly staging unjudged bytes where the file tools read.
+   */
+  readonly agentUploadsRoot: string;
   /**
    * Sibling-to-`workspacesRoot` location for the document-extraction cache —
    * text extracted from office documents/PDFs (`read_file`/`grep`), keyed by
@@ -380,6 +396,8 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     this.workspacesRoot = process.env.WORKSPACES_ROOT || path.resolve(process.cwd(), 'workspaces');
     this.backupsRoot = process.env.BACKUPS_ROOT || path.resolve(this.workspacesRoot, '..', 'backups');
     this.spillRoot = process.env.SPILL_ROOT || path.resolve(this.workspacesRoot, '..', 'tool-chain-spills');
+    this.agentUploadsRoot =
+      process.env.AGENT_UPLOADS_ROOT || path.resolve(this.workspacesRoot, '..', 'agent-uploads');
     this.docExtractCacheRoot =
       process.env.DOC_EXTRACT_CACHE_ROOT || path.resolve(this.workspacesRoot, '..', 'doc-extract-cache');
     // Required, and checked BEFORE the auth routes it signs for are ever

package/src/index.ts

@@ -52,18 +52,43 @@ export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
 export {
   runCoreMigrations,
   runEnterpriseMigrations,
+  runPiiEncryptionBackfill,
+  // The same backfill for an overlay's own sealed columns: its spec goes to
+  // `runEnterpriseMigrations`, or to `runPiiBackfill` under a lock of its own.
+  runPiiBackfill,
+  type PiiBackfillExecutor,
+  type PiiBackfillSpec,
+  type PiiBackfillTable,
+  type PiiBlindIndex,
 } from './modules/database/migrate.js';
 export {
   getDb,
   createDb,
   closeDb,
   dbSchemaOf,
+  piiKeysOf,
   assertSchemaName,
   DEFAULT_DB_SCHEMA,
   type Database,
   type DbOptions,
 } from './modules/database/connection.js';
 
+// PII column encryption (see shared/column-crypto.ts). The key belongs to the
+// database handle (`createDb(url, { piiKey })`), so an overlay seals its own
+// schema's columns by declaring them `encryptedText` / `blindIndexText` and
+// running on the handle the composition root built. `derivePiiKeys` and
+// `piiKeysOf` are for code that handles the stored form itself: SQL written
+// by hand, or a process that reads a knowledge base's tables without a handle
+// of this package's.
+export {
+  encryptedText,
+  blindIndexText,
+  derivePiiKeys,
+  isEncryptedBlob,
+  PII_CIPHERTEXT_PREFIX,
+  type PiiKeys,
+} from './shared/column-crypto.js';
+
 // Build identity surfaced by GET /api/health.
 export { GIT_SHA, resolveGitSha } from './version.js';
 

package/src/modules/access/__tests__/users-db-double.ts

@@ -1,10 +1,11 @@
 import { Param } from 'drizzle-orm';
 
 import type { Database } from '../../database/connection.js';
+import { users } from '../../database/schema.js';
 
 /**
- * Every literal bound into a drizzle condition, in order — for
- * `inArray(users.email, emails)` that is exactly `emails`.
+ * Every address a drizzle condition binds to the users' blind index, in
+ * order — for `inArray(users.emailBidx, emails)` that is exactly `emails`.
  *
  * A drizzle `SQL` is a tree of chunks; the bound values sit in it as `Param`
  * nodes (an `inArray` puts them in a nested array chunk). Reading them back is
@@ -14,7 +15,12 @@ import type { Database } from '../../database/connection.js';
  */
 function boundValues(node: unknown, depth = 0): string[] {
   if (depth > 8 || node === null || node === undefined) return [];
-  if (node instanceof Param) return typeof node.value === 'string' ? [node.value] : [];
+  // Only what is bound THROUGH THE INDEX COLUMN counts: an address compared
+  // with the encrypted `email` column matches nothing in Postgres (the
+  // ciphertext is randomized), so it matches nothing here.
+  if (node instanceof Param) {
+    return node.encoder === users.emailBidx && typeof node.value === 'string' ? [node.value] : [];
+  }
   if (Array.isArray(node)) return node.flatMap((c) => boundValues(c, depth + 1));
   const chunks = (node as { queryChunks?: unknown }).queryChunks;
   return Array.isArray(chunks) ? chunks.flatMap((c) => boundValues(c, depth + 1)) : [];
@@ -30,14 +36,17 @@ function boundValues(node: unknown, depth = 0): string[] {
  * routes ask about comes back without one, which is what makes the share
  * dialog label it "hasn't signed in yet".
  *
- * The `where` clause IS evaluated: the emails bound into it are matched
- * against the roster the same way Postgres would — against the stored rows as
- * written, with no re-canonicalisation on the double's side. Real rows are
- * canonical (the auth service lowercases every address it writes), so a
- * caller that stopped lowering the emails it asks about would match nothing
- * here, exactly as it would match nothing in Postgres. A double that answered
- * with the whole roster could not tell those two apart.
+ * The `where` clause IS evaluated: the values bound into it are matched
+ * against the roster the same way Postgres would. The email column is
+ * randomized ciphertext, so the routes compare its blind index
+ * (`email_bidx`), which they bind the ADDRESSES to — the database handle
+ * turns each into its index, over the canonical (trimmed, lowercased)
+ * address. The double does what the index does: a caller that stopped
+ * lowering the emails it asks about still matches here, as it does in
+ * Postgres.
  */
+const canonical = (email: string) => email.trim().toLowerCase();
+
 export function usersDbDouble(
   accounts: readonly (string | { email: string; name?: string })[] = [],
 ): Database {
@@ -54,8 +63,8 @@ export function usersDbDouble(
       where: (condition: unknown) => Promise<typeof rows>;
     };
     query.where = async (condition: unknown) => {
-      const asked = new Set(boundValues(condition));
-      return rows.filter((r) => asked.has(r.email));
+      const asked = new Set(boundValues(condition).map(canonical));
+      return rows.filter((r) => asked.has(canonical(r.email)));
     };
     return query;
   };

package/src/modules/access/access.routes.ts

@@ -724,10 +724,13 @@ export function createAccessRoutes(
   async function accountsAmong(emails: string[]): Promise<Set<string>> {
     // `inArray` refuses an empty list, and there is nothing to ask anyway.
     if (emails.length === 0) return new Set();
+    // Through the blind index: `email` is randomized ciphertext, and the
+    // index is what the unique constraint and every lookup key on. It is
+    // compared with the addresses themselves.
     const rows = await db
       .select({ email: users.email })
       .from(users)
-      .where(inArray(users.email, emails));
+      .where(inArray(users.emailBidx, emails));
     return new Set(rows.map((r) => r.email.trim().toLowerCase()));
   }
 

package/src/modules/access/directory-sync-bot.ts

@@ -26,8 +26,12 @@ export const DIRECTORY_SYNC_BOT_NAME = 'Directory Sync Bot';
 export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
   const inserted = await db
     .insert(users)
-    .values({ email: DIRECTORY_SYNC_BOT_EMAIL, name: DIRECTORY_SYNC_BOT_NAME })
-    .onConflictDoNothing({ target: users.email })
+    .values({
+      email: DIRECTORY_SYNC_BOT_EMAIL,
+      emailBidx: DIRECTORY_SYNC_BOT_EMAIL,
+      name: DIRECTORY_SYNC_BOT_NAME,
+    })
+    .onConflictDoNothing({ target: users.emailBidx })
     .returning();
   if (inserted.length > 0) {
     const row = inserted[0];
@@ -37,7 +41,7 @@ export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
   const [row] = await db
     .select()
     .from(users)
-    .where(eq(users.email, DIRECTORY_SYNC_BOT_EMAIL))
+    .where(eq(users.emailBidx, DIRECTORY_SYNC_BOT_EMAIL))
     .limit(1);
   if (!row) {
     throw new Error(

package/src/modules/agent-instructions/__tests__/agent-instructions.route.test.ts

@@ -6,7 +6,11 @@ import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.in
 import type { InternalTokenService } from '../../tool-auth/internal-token.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { createAgentInstructionsRoutes } from '../agent-instructions.routes.js';
-import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../compose.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { TOOL_PREFIX_LINE, platformInstructions } from '../compose.js';
+
+/** The platform-owned text the route leads with: header + the shared file rules. */
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
 
 /**
  * `GET /agent/instructions` behind the REAL manual-auth gate, with the three
@@ -61,7 +65,7 @@ describe('GET /agent/instructions', () => {
       expect(res.status, bearer).toBe(200);
       expect(res.headers.get('cache-control')).toBe('no-store');
       const body = (await res.json()) as Record<string, unknown>;
-      expect(body.instructions).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.`);
+      expect(body.instructions).toBe(`${PLATFORM}\n\nAcme builds solar farms.`);
       expect(body.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Acme builds solar farms.`);
       expect(body).toMatchObject({
         truncated: false,
@@ -79,12 +83,12 @@ describe('GET /agent/instructions', () => {
     expect((await fetch(url, { headers: { Authorization: 'Bearer not-a-session' } })).status).toBe(401);
   });
 
-  it('a missing file yields the header alone', async () => {
+  it('a missing file yields the platform text alone', async () => {
     const url = await serve(async () => null);
     const res = await fetch(url, { headers: { Authorization: `Bearer ${CONNECTION_KEY}` } });
     expect(res.status).toBe(200);
     const body = (await res.json()) as { instructions: string; toolPrefix: string; preambleChars: number };
-    expect(body.instructions).toBe(PLATFORM_HEADER);
+    expect(body.instructions).toBe(PLATFORM);
     expect(body.toolPrefix).toBe(TOOL_PREFIX_LINE);
     expect(body.preambleChars).toBe(0);
   });