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

package/src/modules/workspace/write-denial.ts

@@ -7,14 +7,6 @@ import { toKbRelative } from '../access-model/kb-read-filter.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 
-/**
- * Appended to the description of every workspace tool whose refusal is mapped
- * by `writeDenial`, so an agent knows before it is refused that a refusal is
- * not necessarily the end of the road.
- */
-export const PROPOSAL_ROUTE_NOTE =
-  ' If this is refused for permissions, the `write-denied` error says whether you may propose the change instead (create a branch from this one, repeat this call on it, then `open_change_request` into this branch) and lists those steps.';
-
 /** One step of the proposal route, named by the tool the agent calls. */
 export interface ProposalStep {
   tool: string;

package/src/modules/workspace/zip-entry-rules.ts

@@ -0,0 +1,173 @@
+import { inflateRawSync } from 'node:zlib';
+import { validateFilename } from '@bevel-software/platform-shared';
+import { GitInternalsError } from '../../shared/domain-errors.js';
+import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+
+/**
+ * What an archive's entry NAMES are allowed to be, as one set of rules two
+ * surfaces ask: `unzip` (a .zip already in the workspace) and
+ * `apply_file_upload` (a .zip the agent sent to the upload route). Both land
+ * bytes an agent never typed at paths the archive chose, so both have to judge
+ * the same names the same way — and they did not, for as long as the rules
+ * lived inside `WorkspaceService.unzipFile` as three inline blocks.
+ *
+ * NAMES, and how an entry's BYTES are read ({@link readZipEntry}) — the two
+ * things decidable from the archive alone. Whether a target sits behind a
+ * symbolic link already on disk, whether the caller may write there, and what
+ * is already at the path are facts about a workspace, so each surface asks
+ * those where its own writes land.
+ */
+
+/**
+ * The entries an archive from macOS carries that nobody asked for: the
+ * resource-fork sidecar tree and the Finder's own index. SILENTLY dropped
+ * rather than reported — they are not the caller's content and a list of
+ * refusals about them says nothing.
+ */
+export function isZipNoiseEntry(rawName: string): boolean {
+  return (
+    rawName.startsWith('__MACOSX/') ||
+    rawName === '__MACOSX' ||
+    rawName.endsWith('/.DS_Store') ||
+    rawName === '.DS_Store' ||
+    /(^|\/)\._/.test(rawName)
+  );
+}
+
+/**
+ * An entry's name with separators in the one spelling the rules read. A zip
+ * written on Windows may use `\`, which every check below (and every path
+ * built from the result) would otherwise read as part of a single segment.
+ */
+export function zipEntryName(entryName: string): string {
+  return entryName.replace(/\\/g, '/');
+}
+
+/** The path segments `rawName` names, with a trailing slash and empty parts dropped. */
+export function zipEntrySegments(rawName: string): string[] {
+  return rawName
+    .replace(/\/+$/, '')
+    .split('/')
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Why `rawName` may not be landed at all — the reason a caller reports beside
+ * the entry — or null when the name is one a workspace path can be built from.
+ *
+ * Three rules, in the order that makes each refusal say the most useful thing:
+ * a path that climbs out or is anchored at the root is invalid whatever its
+ * segments are; the git folder is refused in every spelling, because an
+ * archive must not be a way to write what git reads as its own metadata; and
+ * then each segment has to be a name a filesystem on any of the three
+ * operating systems keeps intact (`validateFilename`).
+ */
+export function zipEntryNameRefusal(rawName: string): string | null {
+  if (!rawName || rawName.startsWith('/') || /(^|\/)\.\.($|\/)/.test(rawName)) return 'Invalid path';
+  if (hasGitInternalsSegment(rawName)) return new GitInternalsError().message;
+  for (const segment of zipEntrySegments(rawName)) {
+    const reason = validateFilename(segment);
+    if (reason) return reason;
+  }
+  return null;
+}
+
+/**
+ * Whether a zip entry is a symbolic LINK rather than a file or a folder.
+ *
+ * A zip stores a link as an ordinary member whose bytes are the link's target
+ * text and whose unix mode (the high half of the external attributes) carries
+ * `S_IFLNK`. A reader that ignores the mode writes the target text out as a
+ * regular file — content nobody sent, under a name that was meant to point
+ * somewhere. `apply_file_upload` refuses such an entry outright; the entry is
+ * not a file, so there are no bytes of the caller's to land.
+ */
+export function isSymlinkZipEntry(entry: {
+  header?: { attr?: number };
+  attr?: number;
+}): boolean {
+  const attr = entry.header?.attr ?? entry.attr ?? 0;
+  if (!Number.isFinite(attr) || attr <= 0) return false;
+  // The external attributes' high 16 bits are the unix mode when the archive
+  // was written on a unix host; `S_IFMT & mode === S_IFLNK` is the link bit.
+  return ((attr >>> 16) & 0o170000) === 0o120000;
+}
+
+/** A zip's compression method for DEFLATE, the only one that can expand. */
+const ZIP_METHOD_DEFLATED = 8;
+
+/** What {@link readZipEntry} needs of an entry — the part of adm-zip's it reads. */
+export interface ReadableZipEntry {
+  header: { size: number; compressedSize: number; method: number };
+  getData(): Buffer;
+  getCompressedData(): Buffer;
+}
+
+/** An entry's bytes, or why they were not read. */
+export type ZipEntryRead =
+  | { ok: true; data: Buffer }
+  /** The entry is, or would expand to, more than the caller's budget allows. */
+  | { ok: false; reason: 'too_large' }
+  /** The entry cannot be read as what its header says it is. `detail` says how. */
+  | { ok: false; reason: 'unreadable'; detail: string };
+
+/**
+ * Read one entry's bytes, inflating NO MORE than `budget` of them.
+ *
+ * The one read both surfaces use, because the bound is the whole point and it
+ * has a hole when each surface writes it itself. An entry's header DECLARES its
+ * uncompressed size, and the reader caps the inflation at that — but only when
+ * the size it declares is above zero. An entry that declares zero is inflated
+ * with no cap at all, so "check the declared size against the budget, then
+ * read" passes a 20 KB archive that expands to 20 MB, and a 50 MB one that
+ * expands to tens of gigabytes in a single call, before any check on the bytes
+ * that arrived has run. A thousandfold is what deflate does to a run of one
+ * byte; the header saying "empty" was the only thing standing in front of it.
+ *
+ * So the declared size is never the only bound:
+ *
+ *  - an entry declaring more than `budget` is refused unread;
+ *  - a DEFLATED entry declaring ZERO with a stream of its own is inflated here,
+ *    capped at a single byte. An empty file compressed with deflate is exactly
+ *    this shape (a two-byte stream that inflates to nothing) and is read as the
+ *    empty file it is; anything that inflates to a byte or more contradicts its
+ *    own header and is refused;
+ *  - every other entry is read by the archive reader, which caps the inflation
+ *    at the declared size this function has just held against the budget, and
+ *    the bytes that arrive are measured again.
+ *
+ * A read that throws — a failed checksum, a stream longer than it declared, an
+ * unknown method — is that entry's refusal, not the whole archive's: one bad
+ * member must not cost the caller the others.
+ */
+export function readZipEntry(entry: ReadableZipEntry, budget: number): ZipEntryRead {
+  const { size: declared, compressedSize, method } = entry.header;
+  if (declared > budget) return { ok: false, reason: 'too_large' };
+  if (declared === 0 && method === ZIP_METHOD_DEFLATED && compressedSize > 0) {
+    let inflated: Buffer;
+    try {
+      inflated = inflateRawSync(entry.getCompressedData(), { maxOutputLength: 1 });
+    } catch (err) {
+      // Past the one-byte cap, or not a deflate stream at all: either way it
+      // is not the empty file its header says it is.
+      return { ok: false, reason: 'unreadable', detail: declaresEmptyButIsNot(err) };
+    }
+    if (inflated.byteLength > 0) return { ok: false, reason: 'unreadable', detail: declaresEmptyButIsNot() };
+    return { ok: true, data: inflated };
+  }
+  let data: Buffer;
+  try {
+    data = entry.getData();
+  } catch (err) {
+    return { ok: false, reason: 'unreadable', detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (data.byteLength > budget) return { ok: false, reason: 'too_large' };
+  return { ok: true, data };
+}
+
+function declaresEmptyButIsNot(err?: unknown): string {
+  const outputLimit = (err as { code?: string } | undefined)?.code === 'ERR_BUFFER_TOO_LARGE';
+  return err === undefined || outputLimit
+    ? 'its header declares an empty file, but it holds content'
+    : `its header declares an empty file, and its content could not be read (${err instanceof Error ? err.message : String(err)})`;
+}

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/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

@@ -27,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');
   });