@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/src/shared/__tests__/column-crypto.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { PgDialect, pgTable, uuid } from 'drizzle-orm/pg-core';
+import { eq, inArray } from 'drizzle-orm';
+import {
+  IndexOnWrite,
+  PII_CIPHERTEXT_PREFIX,
+  PII_SEALED_SHAPE_SQL_REGEX,
+  SealOnWrite,
+  blindIndexText,
+  derivePiiKeys,
+  encryptedText,
+  isEncryptedBlob,
+} from '../column-crypto.js';
+import { TokenCrypto } from '../token-crypto.js';
+
+const KEY = randomBytes(32).toString('base64');
+const keys = derivePiiKeys(KEY);
+const otherKeys = derivePiiKeys(randomBytes(32).toString('base64'));
+
+describe('derivePiiKeys: seal / open / read', () => {
+  it('round-trips a value through ciphertext', () => {
+    const sealed = keys.seal('razvan@bevel.software');
+    expect(sealed).not.toContain('razvan');
+    expect(sealed.startsWith(PII_CIPHERTEXT_PREFIX)).toBe(true);
+    expect(isEncryptedBlob(sealed)).toBe(true);
+    expect(keys.read(sealed)).toBe('razvan@bevel.software');
+  });
+
+  it('stores the empty string as itself (no unparseable empty-ciphertext blob)', () => {
+    expect(keys.seal('')).toBe('');
+    expect(keys.read('')).toBe('');
+    expect(isEncryptedBlob('')).toBe(false);
+  });
+
+  it('is randomized — the same plaintext never encrypts to the same blob', () => {
+    expect(keys.seal('alice')).not.toBe(keys.seal('alice'));
+  });
+
+  it('passes legacy plaintext through unchanged (pre-backfill rows)', () => {
+    expect(keys.read('plain old email@example.com')).toBe('plain old email@example.com');
+  });
+
+  it('passes through plaintext that merely resembles ciphertext', () => {
+    // Blob-shaped but unprefixed (the legacy TokenCrypto shape) → plaintext.
+    const shapeOnly = new TokenCrypto(KEY).encrypt('not-a-pii-blob');
+    expect(isEncryptedBlob(shapeOnly)).toBe(false);
+    expect(keys.read(shapeOnly)).toBe(shapeOnly);
+    // Prefixed but malformed → still not a blob.
+    const impostor = `${PII_CIPHERTEXT_PREFIX}abc:def:ghi`;
+    expect(isEncryptedBlob(impostor)).toBe(false);
+    expect(keys.read(impostor)).toBe(impostor);
+  });
+
+  it('the SQL shape regex agrees with isEncryptedBlob on what a sealed value is', () => {
+    // The backfill trusts rows matching this regex as sealed and skips them;
+    // the app-side check is the authority. Pinned together here so a change
+    // to the prefix, IV or tag width in one place fails this test.
+    const regex = new RegExp(PII_SEALED_SHAPE_SQL_REGEX);
+    for (const plain of ['a@b.co', 'razvan@bevel.software', 'x'.repeat(500)]) {
+      const sealed = keys.seal(plain);
+      expect(isEncryptedBlob(sealed)).toBe(true);
+      expect(regex.test(sealed)).toBe(true);
+    }
+    // The same blob with its padding spelled otherwise decodes to the same
+    // bytes, and the two predicates used to disagree about it: the database
+    // called it unsealed and selected it, this process called it sealed and
+    // skipped it, on every start. One answer, from one pattern.
+    const [iv, tag, ct] = keys.seal('a@b.co').slice(PII_CIPHERTEXT_PREFIX.length).split(':') as [string, string, string];
+    const respelled = [
+      `${PII_CIPHERTEXT_PREFIX}${iv}:${tag.replace(/=+$/, '')}:${ct}`,
+      `${PII_CIPHERTEXT_PREFIX}${iv}==:${tag}:${ct}`,
+      `${PII_CIPHERTEXT_PREFIX}${iv}:${tag}:${ct}\n`,
+    ];
+    for (const unsealed of [
+      'a@b.co',
+      '',
+      `${PII_CIPHERTEXT_PREFIX}abc:def:ghi`,
+      new TokenCrypto(KEY).encrypt('x'),
+      ...respelled,
+    ]) {
+      expect(isEncryptedBlob(unsealed), JSON.stringify(unsealed)).toBe(false);
+      expect(regex.test(unsealed), JSON.stringify(unsealed)).toBe(false);
+    }
+  });
+
+  it("another key cannot open it: the lenient read hands the blob back, open says so", () => {
+    const sealed = keys.seal('secret-person@example.com');
+    expect(otherKeys.read(sealed)).toBe(sealed);
+    expect(otherKeys.open(sealed)).toEqual({ ok: false });
+    expect(keys.open(sealed)).toEqual({ ok: true, plain: 'secret-person@example.com' });
+  });
+
+  it('open tells a blob the key does not open from a plaintext shaped like one', () => {
+    // A value whose PLAINTEXT is itself a well-formed blob: opened correctly,
+    // the result still looks sealed. Only the explicit outcome tells the two
+    // apart — the shape of what the lenient read returns cannot.
+    const inner = keys.seal('inner@example.com');
+    const outer = keys.seal(inner);
+    expect(keys.open(outer)).toEqual({ ok: true, plain: inner });
+    expect(keys.open('plain@example.com')).toEqual({ ok: true, plain: 'plain@example.com' });
+    expect(otherKeys.open(outer)).toEqual({ ok: false });
+  });
+
+  it('domain-separates from the raw secrets key via HKDF', () => {
+    // The column key is DERIVED from KEY — a TokenCrypto built from the raw
+    // KEY itself must not be able to open a PII blob's body.
+    const body = keys.seal('secret-person@example.com').slice(PII_CIPHERTEXT_PREFIX.length);
+    expect(() => new TokenCrypto(KEY).decrypt(body)).toThrow();
+  });
+
+  it('refuses a key that is not 32 bytes', () => {
+    expect(() => derivePiiKeys('too-short')).toThrow();
+  });
+
+  /**
+   * Node's base64 decoder is forgiving in ways a key must not be. Every value
+   * below DECODES TO 32 BYTES, so the length check passes each of them, and
+   * none of them is a way those 32 bytes are written: a mistyped key that
+   * became another key, sealing data the value an operator wrote down will
+   * never open. The property is one, whatever the mistake was — what is
+   * written must be a spelling of what it decodes to.
+   */
+  it('refuses whatever decodes to 32 bytes without being a spelling of them', () => {
+    const unpadded = KEY.replace(/=+$/, '');
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    // The last character of 32 bytes carries four bits of the key and two
+    // that must be zero. Its neighbour in the alphabet sets one of those two.
+    const trailingBits = unpadded.slice(0, -1) + alphabet[alphabet.indexOf(unpadded.slice(-1)) + 1];
+    const mistakes = {
+      'a character the alphabet does not have': `${KEY.slice(0, 10)}$${KEY.slice(10)}`,
+      'a space in the middle': `${KEY.slice(0, 20)} ${KEY.slice(20)}`,
+      'more padding than its length takes': `${unpadded}==`,
+      'bits its last character should not carry': trailingBits,
+    };
+    for (const [mistake, written] of Object.entries(mistakes)) {
+      // The premise: only the round trip can tell this from a key.
+      expect(Buffer.from(written, 'base64'), mistake).toHaveLength(32);
+      expect(() => derivePiiKeys(written), mistake).toThrow(/SECRETS_ENC_KEY is not a clean hex or base64 spelling/);
+    }
+    // Padding in the MIDDLE ends the decoding there, so that one is short and
+    // the length check has always refused it.
+    expect(() => derivePiiKeys(`${unpadded.slice(0, 20)}=${unpadded.slice(20)}`)).toThrow(/must decode to 32 bytes/);
+  });
+
+  it('takes one key in any of its spellings: hex, base64, url-safe, unpadded, with whitespace around it', () => {
+    const raw = Buffer.from(KEY, 'base64');
+    const index = keys.index('a@b.co');
+    for (const spelled of [
+      raw.toString('hex'),
+      raw.toString('hex').toUpperCase(),
+      raw.toString('base64url'),
+      `${raw.toString('base64url')}=`,
+      KEY.replace(/=+$/, ''),
+      `  ${KEY}\n`,
+    ]) {
+      expect(derivePiiKeys(spelled).index('a@b.co'), spelled).toBe(index);
+    }
+  });
+});
+
+describe('derivePiiKeys: index', () => {
+  it('is deterministic and case/whitespace-insensitive', () => {
+    expect(keys.index('Alice@Example.com ')).toBe(keys.index('alice@example.com'));
+    expect(keys.index('alice@example.com')).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('differs across values', () => {
+    expect(keys.index('a@example.com')).not.toBe(keys.index('b@example.com'));
+  });
+
+  it('differs across keys, so one tenant’s index says nothing about another’s', () => {
+    expect(otherKeys.index('a@example.com')).not.toBe(keys.index('a@example.com'));
+  });
+});
+
+/**
+ * The column types hold no key: what they hand the driver is a mark for the
+ * database handle's connection to replace. Pinned through drizzle itself —
+ * the statement a service writes, rendered — because that is where the mark
+ * has to survive to.
+ */
+describe('the column types mark values for the handle', () => {
+  const people = pgTable('people', {
+    id: uuid('id').primaryKey(),
+    email: encryptedText('email').notNull(),
+    emailBidx: blindIndexText('email_bidx').notNull(),
+  });
+  const paramsOf = (clause: unknown) => new PgDialect().sqlToQuery(clause as never).params;
+
+  it('a comparison on an index column binds the address, marked to be indexed', () => {
+    const [bound] = paramsOf(eq(people.emailBidx, 'Ada@Example.com'));
+    expect(bound).toBeInstanceOf(IndexOnWrite);
+    expect((bound as IndexOnWrite).stored(keys)).toBe(keys.index('ada@example.com'));
+    expect(paramsOf(inArray(people.emailBidx, ['a@x.co', 'b@x.co'])).every((p) => p instanceof IndexOnWrite)).toBe(true);
+  });
+
+  it('a value for an encrypted column is marked to be sealed; the empty string is stored as it is', () => {
+    const [bound] = paramsOf(eq(people.email, 'Ada@Example.com'));
+    expect(bound).toBeInstanceOf(SealOnWrite);
+    expect(keys.read((bound as SealOnWrite).stored(keys))).toBe('Ada@Example.com');
+    expect(paramsOf(eq(people.email, ''))).toEqual(['']);
+  });
+
+  it('a mark that reaches a connection holding no key refuses to be written', () => {
+    // `pg` serialises an object parameter through its `toPostgres`. Anything
+    // else here — JSON of the object, say — would store the plaintext.
+    const [bound] = paramsOf(eq(people.email, 'Ada@Example.com'));
+    expect(() => (bound as SealOnWrite).toPostgres()).toThrow(/holds no key/);
+  });
+
+  it('refuses a stored index written back into an index column', () => {
+    // Reading the column gives the stored index; writing that back would
+    // index the index and the row would answer to no address.
+    expect(() => paramsOf(eq(people.emailBidx, keys.index('ada@example.com')))).toThrow(/stored index/);
+  });
+});

package/src/shared/column-crypto.ts

@@ -0,0 +1,218 @@
+import { createHmac, hkdfSync } from 'node:crypto';
+import { customType } from 'drizzle-orm/pg-core';
+import { TokenCrypto, assertKeyDecodesTo32Bytes } from './token-crypto.js';
+
+/**
+ * Application-layer encryption for PII columns. Personal data (emails, names,
+ * change-request text) is AES-256-GCM ciphertext in Postgres, so a leaked
+ * dump, an injected query, or a compromised DB credential yields no personal
+ * data — the key lives only in the app's environment. Disk-level encryption
+ * still carries the blanket at-rest claim (git refs, WAL, logs); this layer is
+ * the DB-specific control on top.
+ *
+ * THE KEY BELONGS TO THE DATABASE HANDLE, not to the process. A process that
+ * serves several knowledge bases holds one handle per tenant, each built with
+ * that tenant's own `SECRETS_ENC_KEY` (`createDb(url, { piiKey })`), so a
+ * tenant's rows are sealed under the same key as its stored credentials and
+ * its dump opens, whole, with that one key.
+ *
+ * A drizzle column type is a module-level object and is told nothing about
+ * the handle a statement runs on, so it cannot hold a key. It only MARKS a
+ * value ({@link SealOnWrite}, {@link IndexOnWrite}); the handle's own
+ * connection replaces the mark with ciphertext or a blind index on the way
+ * in, and opens every sealed value on the way out (see `connection.ts`). A
+ * mark that reaches a connection with no key refuses to be written.
+ *
+ * Both keys are HKDF-derived from the handle's key with distinct info
+ * strings, so PII ciphertext and blind indexes are domain-separated from the
+ * secrets-vault key without asking operators to provision a second variable.
+ */
+
+/** What a database handle seals, opens and indexes personal data with. */
+export interface PiiKeys {
+  /**
+   * Encrypt a value for storage (fresh random IV — NOT equality-comparable).
+   *
+   * The empty string is stored as itself: it carries no personal data, GCM of
+   * an empty plaintext would produce an empty ciphertext segment the blob
+   * parser cannot represent, and columns with a DB-level `DEFAULT ''` then
+   * hold exactly the same representation as an app-written empty value.
+   */
+  seal(plain: string): string;
+  /**
+   * Open a stored value, and SAY whether it opened: a value that is not a
+   * blob is its own plaintext; a blob this key does not open is `ok: false`.
+   * For the callers that must tell "the key does not open this" from a value
+   * — the shape of what {@link read} returns proves nothing, since a
+   * plaintext may itself be shaped like a blob.
+   */
+  open(value: string): { ok: true; plain: string } | { ok: false };
+  /**
+   * The lenient read every query result goes through: a blob this key does
+   * not open is handed back as it is, as is anything that is not a blob —
+   * rows written before the encryption release stay readable until the
+   * backfill at start rewrites them.
+   */
+  read(value: string): string;
+  /**
+   * Blind index for equality on an encrypted column: HMAC-SHA256 of the
+   * trimmed, lower-cased value, hex-encoded. Deterministic, so a `*_bidx`
+   * column can carry the unique constraints and lookups that randomized
+   * ciphertext cannot. Reveals only equality, never content.
+   */
+  index(value: string): string;
+}
+
+/** Derive the personal-data keys from a deployment's (or a tenant's) `SECRETS_ENC_KEY`. */
+export function derivePiiKeys(secretsEncKey: string): PiiKeys {
+  const ikm = assertKeyDecodesTo32Bytes(secretsEncKey, 'SECRETS_ENC_KEY');
+  const columnKey = Buffer.from(hkdfSync('sha256', ikm, Buffer.alloc(0), 'bevel-pii-column-v1', 32));
+  const bidxKey = Buffer.from(hkdfSync('sha256', ikm, Buffer.alloc(0), 'bevel-pii-bidx-v1', 32));
+  const crypto = new TokenCrypto(columnKey.toString('base64'));
+  const open: PiiKeys['open'] = (value) => {
+    if (!isEncryptedBlob(value)) return { ok: true, plain: value };
+    try {
+      return { ok: true, plain: crypto.decrypt(value.slice(PII_CIPHERTEXT_PREFIX.length)) };
+    } catch {
+      return { ok: false };
+    }
+  };
+  return {
+    seal: (plain) => (plain === '' ? '' : PII_CIPHERTEXT_PREFIX + crypto.encrypt(plain)),
+    open,
+    read: (value) => {
+      const opened = open(value);
+      return opened.ok ? opened.plain : value;
+    },
+    index: (value) => createHmac('sha256', bidxKey).update(value.trim().toLowerCase()).digest('hex'),
+  };
+}
+
+/**
+ * Every PII ciphertext starts with this marker. An explicit prefix — rather
+ * than recognising ciphertext by its `iv:tag:ct` shape — means legacy
+ * plaintext can never be mistaken for ciphertext (and silently skipped by the
+ * backfill), and lets the backfill find unsealed rows with a plain SQL
+ * predicate instead of scanning every row in the app. Bump the version
+ * segment if the format ever changes.
+ */
+export const PII_CIPHERTEXT_PREFIX = 'pii:v1:';
+
+/**
+ * The shape of a PII ciphertext blob, as ONE pattern both Postgres and this
+ * process read: the version prefix followed by base64 segments of the exact
+ * widths GCM produces (12-byte IV → 16 chars, 16-byte tag → 22 chars + `==`).
+ * Lets the backfill find unsealed rows with a `!~` predicate instead of
+ * scanning every row in the app.
+ *
+ * {@link isEncryptedBlob} is built FROM it rather than written beside it. The
+ * two used to be separate spellings of one idea, and they disagreed: the
+ * JavaScript one decoded each part and so took an unpadded tag for a 16-byte
+ * one, which this pattern does not. A value the two disagreed about was
+ * selected by the backfill's SQL as unsealed and then skipped by its
+ * JavaScript as sealed, on every start, and stayed in clear for good. The
+ * pattern uses nothing POSIX and JavaScript read differently.
+ */
+export const PII_SEALED_SHAPE_SQL_REGEX = `^${PII_CIPHERTEXT_PREFIX}[A-Za-z0-9+/]{16}:[A-Za-z0-9+/]{22}==:[A-Za-z0-9+/]+={0,2}$`;
+
+const PII_SEALED_SHAPE = new RegExp(PII_SEALED_SHAPE_SQL_REGEX);
+
+/**
+ * Whether `value` has the shape of a PII ciphertext blob — exactly the values
+ * {@link PII_SEALED_SHAPE_SQL_REGEX} matches in the database, no more and no
+ * fewer. Shape only: whether the configured key OPENS it is `PiiKeys.open`'s
+ * answer, and a plaintext somebody typed in this shape passes here.
+ */
+export function isEncryptedBlob(value: string): boolean {
+  return PII_SEALED_SHAPE.test(value);
+}
+
+/**
+ * A value on its way to the database that the handle's connection still has
+ * to turn into what is stored. It is never a storable value itself: `pg`
+ * asks an object how to serialise itself through `toPostgres`, and this one
+ * refuses, so a statement that reaches a connection which did not replace it
+ * — a pool built without `createDb`, or a handle built without a key — fails
+ * instead of writing the plaintext.
+ */
+export abstract class PiiParam {
+  constructor(readonly plain: string) {}
+
+  /** What the handle's keys make of it. */
+  abstract stored(keys: PiiKeys): string;
+
+  toPostgres(): never {
+    throw new Error(
+      'A personal-data value reached a database connection that holds no key for it. ' +
+        'Build the handle with createDb/getDb and its piiKey (createCoreServices does).',
+    );
+  }
+}
+
+/** Plaintext of an {@link encryptedText} column: stored as ciphertext. */
+export class SealOnWrite extends PiiParam {
+  stored(keys: PiiKeys): string {
+    return keys.seal(this.plain);
+  }
+}
+
+/** The address a {@link blindIndexText} column is written or compared with: stored as its blind index. */
+export class IndexOnWrite extends PiiParam {
+  stored(keys: PiiKeys): string {
+    return keys.index(this.plain);
+  }
+}
+
+/**
+ * Drizzle column type for encrypted PII text: services read and write
+ * plaintext, the database only ever sees ciphertext. NEVER use an
+ * `encryptedText` column in a WHERE clause or conflict target — the fresh IV
+ * per write means `eq(column, plaintext)` silently matches nothing. Equality
+ * goes through the column's `*_bidx` companion ({@link blindIndexText}).
+ */
+export const encryptedText = customType<{ data: string; driverData: string }>({
+  dataType() {
+    return 'text';
+  },
+  toDriver(value: string): string {
+    // The mark, typed as the text it becomes on the handle's connection.
+    return (value === '' ? '' : new SealOnWrite(value)) as string;
+  },
+  fromDriver(value: string): string {
+    // Already opened: the handle's connection opens every sealed value of a
+    // result before drizzle maps it.
+    return value;
+  },
+});
+
+const STORED_INDEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Drizzle column type for the blind index beside an encrypted column. WRITE
+ * AND COMPARE IT WITH THE VALUE ITSELF — `emailBidx: email`,
+ * `eq(users.emailBidx, email)`, `inArray(users.emailBidx, emails)` — and the
+ * handle's connection stores or binds its index. Reading the column gives the
+ * stored index, which is good for nothing but SQL: writing it back would
+ * index the index, so that is refused. A row copied from another carries the
+ * value its index was made from, not the index.
+ *
+ * Only through drizzle's operators, which bind through the column: a value
+ * interpolated into a raw `sql` template is compared as it is and matches
+ * nothing.
+ */
+export const blindIndexText = customType<{ data: string; driverData: string }>({
+  dataType() {
+    return 'text';
+  },
+  toDriver(value: string): string {
+    if (STORED_INDEX.test(value)) {
+      throw new Error(
+        'A blind-index column was written with a stored index. Write it with the value the index is of (the address).',
+      );
+    }
+    return new IndexOnWrite(value) as unknown as string;
+  },
+  fromDriver(value: string): string {
+    return value;
+  },
+});

package/src/shared/domain-errors.ts

@@ -377,6 +377,37 @@ export class PathNotFoundError extends WorkflowDomainError {
   }
 }
 
+/**
+ * The one sentence every read of a past save answers when that save is not in
+ * the history of the branch being viewed.
+ *
+ * Written once, here, because four surfaces have to give the same answer: the
+ * bytes route (`?ref=`), the patch route (`show-file`), the before/after
+ * contents route (`file-at-change`), and anything later that serves a file at
+ * a commit. A save the history panel listed came off `git log` on this
+ * workspace's own branch, so it can never be refused this way — what this
+ * refuses is a sha from someone else's branch, or one that was invented.
+ */
+export const VERSION_NOT_ON_BRANCH_MESSAGE =
+  "This version is not in this file's history on this branch.";
+
+/**
+ * The caller named a save that is not an ancestor of the branch this
+ * workspace has checked out.
+ *
+ * 404, and DELIBERATELY the same 404 for a sha that exists on another branch
+ * as for one that exists nowhere: telling the two apart would turn the route
+ * into an oracle for "does this commit exist in the repository", which is
+ * exactly the reading a branch-scoped rule exists to prevent.
+ */
+export class VersionNotOnBranchError extends WorkflowDomainError {
+  readonly kind = 'version-not-on-branch' as const;
+  constructor() {
+    super(VERSION_NOT_ON_BRANCH_MESSAGE, 404, { kind: 'version-not-on-branch' });
+    this.name = 'VersionNotOnBranchError';
+  }
+}
+
 /**
  * An archive the caller uploaded that the zip reader cannot open. 422, not
  * 400: the request is well-formed and the path is fine — the BYTES are not a

package/src/shared/git.contract.ts

@@ -209,6 +209,33 @@ export class GitRunError extends Error {
   }
 }
 
+/**
+ * Refuse a `cat-file --batch` spec that is not ONE line.
+ *
+ * `--batch` reads one object name per LINE, so a spec carrying a `\n` is two
+ * requests. For a single-spec read that means git answers about the part
+ * before the break — bytes the caller then presents as the whole path's,
+ * having had its access gates answered about a string that names nothing. For
+ * a batch it is worse: the extra answer shifts every result after it, and a
+ * walk that steps one header at a time hands each caller the object that
+ * belonged to the next one.
+ *
+ * A path is refused a control character long before this — by
+ * `assertValidRelativePath` and by `normalizeWorkspacePath`, which is where
+ * the rule belongs because it protects every route and tool at once. This is
+ * the fence AT the protocol, for a spec assembled from somewhere neither of
+ * those covers (a ref, a branch name, a path from a future caller). Nothing
+ * should ever trip it, so it throws rather than filtering: a request that
+ * cannot be expressed in this protocol has no correct truncation.
+ */
+export function assertOneSpecPerLine(specs: readonly string[]): void {
+  for (const spec of specs) {
+    if (/[\r\n]/.test(spec)) {
+      throw new Error('git cat-file --batch spec contains a line break');
+    }
+  }
+}
+
 /** Whether a failure came from the deadline rather than from git's own answer. */
 export function isGitTimeout(err: unknown): boolean {
   return err instanceof GitRunError && err.timedOut;

package/src/shared/token-crypto.ts

@@ -61,12 +61,39 @@ function decodeKey(raw: string): Buffer {
  * is then safe, because a bad key never gets that far.
  */
 export function assertKeyDecodesTo32Bytes(rawKey: string, envVarName: string): Buffer {
-  const key = decodeKey(rawKey);
+  // Whitespace around it is the environment's, not the key's.
+  const written = rawKey.trim();
+  const key = decodeKey(written);
   if (key.length !== 32) {
     throw new Error(
       `${envVarName} must decode to 32 bytes (got ${key.length}). ` +
         'Generate one with: `node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'base64\'))"`.',
     );
   }
+  // WHAT IS WRITTEN MUST BE A SPELLING OF WHAT IT DECODES TO. Node's decoder is
+  // forgiving in ways a key must not be: it skips a character it does not know,
+  // it stops at padding wherever padding stands, and it ignores bits a final
+  // character should not carry. Each of those turns a mistyped key into 32
+  // bytes — a DIFFERENT key, sealing data that the value an operator wrote
+  // down will never open. Asking which characters and which padding are
+  // acceptable is a list that is always one case short, so the question is put
+  // the other way round: encode the bytes again, and accept the value only
+  // when it is one of the ways those bytes are written.
+  if (!spellingsOf(key).includes(/^[0-9a-fA-F]{64}$/.test(written) ? written.toLowerCase() : written)) {
+    throw new Error(
+      `${envVarName} is not a clean hex or base64 spelling of a 32-byte key: it holds a character, a padding ` +
+        'or trailing bits the encoding does not have, which the decoder skipped. The key in use so far is what ' +
+        'it decoded to; print that key spelled properly with ' +
+        `\`node -e "console.log(Buffer.from(process.env.${envVarName}, 'base64').toString('base64'))"\` and set that.`,
+    );
+  }
   return key;
 }
+
+/** Every way 32 bytes are written as a key: hex, and base64 in either alphabet, padded or not. */
+function spellingsOf(key: Buffer): string[] {
+  const standard = key.toString('base64');
+  const urlSafe = key.toString('base64url');
+  const padding = standard.slice(standard.replace(/=+$/, '').length);
+  return [key.toString('hex'), standard, standard.replace(/=+$/, ''), urlSafe, urlSafe + padding];
+}

package/src/tenancy/__tests__/static-tenant-source.test.ts

@@ -12,7 +12,6 @@ const settings: TenantHostSettings = {
   workspacesRoot: path.resolve('/srv/hexis/workspaces'),
   kbTemplateDir: '/srv/hexis/template',
   gitTimeoutMs: 120_000,
-  ontologySessionBlock: true,
   updateCheckEnabled: false,
   masterKey: 'a-master-key-that-is-long-enough-to-count-as-random',
 };
@@ -28,6 +27,10 @@ describe('tenantConfigFrom', () => {
     expect(config.workspacesRoot).toBe(path.resolve('/srv/hexis/workspaces/acme-2'));
     expect(config.backupsRoot).toBe(path.resolve('/srv/hexis/backups/acme-2'));
     expect(config.spillRoot).toBe(path.resolve('/srv/hexis/tool-chain-spills/acme-2'));
+    // Per tenant like the rest: a shared staging root would let one tenant's
+    // upload sweep delete another's bytes, and both would be writing ids into
+    // one directory.
+    expect(config.agentUploadsRoot).toBe(path.resolve('/srv/hexis/agent-uploads/acme-2'));
     expect(config.docExtractCacheRoot).toBe(path.resolve('/srv/hexis/doc-extract-cache/acme-2'));
     expect(config.loopbackBaseUrl).toBe('http://127.0.0.1:3001/_tenant/acme-2');
   });

package/src/tenancy/static-tenant-source.ts

@@ -23,7 +23,6 @@ export interface TenantHostSettings {
   readonly workspacesRoot: string;
   readonly kbTemplateDir: string;
   readonly gitTimeoutMs: number;
-  readonly ontologySessionBlock: boolean;
   readonly updateCheckEnabled: boolean;
   /** See `tenant-secrets.ts`. */
   readonly masterKey: string;
@@ -165,6 +164,7 @@ export function tenantConfigFrom(record: TenantRecord, settings: TenantHostSetti
     workspacesRoot: path.resolve(settings.workspacesRoot, slug),
     backupsRoot: besideWorkspaces('backups'),
     spillRoot: besideWorkspaces('tool-chain-spills'),
+    agentUploadsRoot: besideWorkspaces('agent-uploads'),
     docExtractCacheRoot: besideWorkspaces('doc-extract-cache'),
     jwtSecret: secrets.jwtSecret,
     secretsEncKey: secrets.secretsEncKey,
@@ -182,7 +182,6 @@ export function tenantConfigFrom(record: TenantRecord, settings: TenantHostSetti
     gitUsername,
     gitToken: (record.gitToken ?? '').trim(),
     kbTemplateDir: settings.kbTemplateDir,
-    ontologySessionBlock: settings.ontologySessionBlock,
     updateCheckEnabled: settings.updateCheckEnabled,
     allowedEmailDomains,
     trustProxy: settings.trustProxy,
@@ -289,7 +288,6 @@ export function tenantHostEnv(env: NodeJS.ProcessEnv = process.env): TenantHostE
     kbTemplateDir: env.KB_TEMPLATE_DIR || defaultKbTemplateDir(),
     gitTimeoutMs:
       Number.isFinite(gitTimeout) && gitTimeout > 0 && gitTimeout <= MAX_TIMER_MS ? gitTimeout : DEFAULT_GIT_TIMEOUT_MS,
-    ontologySessionBlock: (env.ONTOLOGY_SESSION_BLOCK ?? 'true').trim().toLowerCase() !== 'false',
     updateCheckEnabled: (env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false',
     idleMinutes: Number.isFinite(idle) && idle > 0 ? idle : 30,
   };

package/src/tenancy/tenant-secrets.ts

@@ -4,7 +4,7 @@ import { hkdfSync } from 'node:crypto';
 export interface TenantSecrets {
   /** Signs the tenant's login sessions and OAuth state. */
   jwtSecret: string;
-  /** 32 bytes, base64: encrypts the tenant's vault values, MCP OAuth tokens and stored git credential. */
+  /** 32 bytes, base64: encrypts the tenant's vault values, MCP OAuth tokens, stored git credential and personal-data columns. */
   secretsEncKey: string;
   /** HMAC key for the tenant's internal (loopback) tool tokens. */
   internalTokenSecret: string;
@@ -25,6 +25,10 @@ const MIN_MASTER_KEY_LENGTH = 32;
  * export, and nothing per tenant has to be kept safe in the meantime. The
  * cloud app's registry calls this with the same inputs and gets the same
  * answer.
+ *
+ * The personal-data columns are sealed under `secretsEncKey` too (each
+ * tenant's database handle is built with it), so the same one key opens the
+ * whole of a tenant's dump.
  */
 export function deriveTenantSecrets(masterKey: string, slug: string): TenantSecrets {
   if (masterKey.length < MIN_MASTER_KEY_LENGTH) {