@bevel-software/platform-core-backend 0.26.0 → 0.28.0

package/src/modules/database/__tests__/pii-backfill.pg.test.ts

@@ -11,6 +11,7 @@ import { runCoreMigrations, runEnterpriseMigrations, runPiiBackfill, type PiiBac
 import { prFileApprovals, users } from '../core-schema.js';
 import { coreMigrationsDir } from '../../../assets.js';
 import { PII_CIPHERTEXT_PREFIX, derivePiiKeys, isEncryptedBlob } from '../../../shared/column-crypto.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
 
 /**
  * Personal data in a real Postgres: what a database handle stores under its
@@ -22,12 +23,10 @@ import { PII_CIPHERTEXT_PREFIX, derivePiiKeys, isEncryptedBlob } from '../../../
  * key, which sees what a dump would.
  *
  * Runs where `TEST_DATABASE_URL` names a server this role may create
- * databases on (CI carries one as a service container); skipped elsewhere.
- * Every test works in a scratch database of its own and drops it: the
- * database the URL names is only connected to, never written.
+ * databases on, each test in a scratch database of its own (`pg-scratch.ts`).
  */
-const ADMIN_URL = process.env.TEST_DATABASE_URL;
-const TIMEOUT = 120_000;
+const ADMIN_URL = PG_ADMIN_URL;
+const TIMEOUT = PG_TEST_TIMEOUT;
 const KEY = randomBytes(32).toString('base64');
 const keys = derivePiiKeys(KEY);
 
@@ -45,31 +44,13 @@ const TABLES = [
 type Row = Record<string, unknown>;
 type Query = (text: string) => Promise<Row[]>;
 
-const created: string[] = [];
 const open: Database[] = [];
 const plain: pg.Pool[] = [];
 /** Temporary folders a test made (an overlay's migration history); removed in `afterAll`. */
 const folders: string[] = [];
 
-async function withAdmin<T>(fn: (admin: pg.Client) => Promise<T>): Promise<T> {
-  const admin = new pg.Client({ connectionString: ADMIN_URL });
-  await admin.connect();
-  try {
-    return await fn(admin);
-  } finally {
-    await admin.end();
-  }
-}
-
 /** A scratch database of this test's own; dropped in `afterAll`. */
-async function scratchDatabase(): Promise<string> {
-  const name = `hexis_pii_${randomBytes(6).toString('hex')}`;
-  await withAdmin((admin) => admin.query(`create database ${name}`));
-  created.push(name);
-  const url = new URL(ADMIN_URL!);
-  url.pathname = `/${name}`;
-  return url.toString();
-}
+const scratchDatabase = () => scratchDatabaseUrl('hexis_pii');
 
 /** The application's handle on a schema, holding `key`. */
 function handle(url: string, opts: { schema?: string; key?: string | null } = {}): Database {
@@ -157,9 +138,7 @@ describe.skipIf(!ADMIN_URL)('personal data, on a real Postgres', () => {
   // With the tests' own timeout: every test leaves a scratch database, and
   // dropping them one after the other outlasts the default for a hook.
   afterAll(async () => {
-    await withAdmin(async (admin) => {
-      for (const name of created) await admin.query(`drop database if exists ${name} with (force)`);
-    });
+    await dropScratchDatabases();
     for (const folder of folders) rmSync(folder, { recursive: true, force: true });
   }, TIMEOUT);
 

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

@@ -1,11 +1,11 @@
 /**
  * CORE platform tables — the git-backed workspace/workflow, auth, access,
  * change requests, locks, the pending-commits queue, connection keys, MCP
- * OAuth, and the Secrets Vault. A core-only deployment migrates and runs on
- * exactly these tables.
+ * OAuth, the Secrets Vault, and the embed's Atlassian account links. A
+ * core-only deployment migrates and runs on exactly these tables.
  *
  * Enterprise-only tables (chat, routines, watchlist, connectors, LLM config,
- * SharePoint/Atlassian links, feedback, upload, kb-revalidation) live in
+ * SharePoint links, feedback, upload, kb-revalidation) live in
  * `enterprise-schema.ts`, which imports the FK targets (`users`,
  * `externalApiKeys`) from here. `schema.ts` re-exports both, so existing
  * imports keep working unchanged.
@@ -829,3 +829,33 @@ export const pluginJoinRequests = pgTable('plugin_join_requests', {
     sql`${t.status} IN ('pending', 'opened', 'failed')`,
   ),
 }));
+
+/**
+ * Links an account from an outside system — today an Atlassian (Forge)
+ * account id — to a Hexis user, so an embed minted for that account resolves
+ * to a person whose read and write access the view obeys.
+ *
+ * KEPT UNDER ITS ENTERPRISE NAME, deliberately. The table was created by the
+ * Bevel Platform's own migration history before the embed moved into Hexis;
+ * an upgraded database already holds every link its Jira users made, and
+ * nobody is going to re-link. So the core migration creates it only if it is
+ * absent and adopts what is there otherwise (see
+ * `0017_atlassian_account_links.sql`), and the generic name this table
+ * deserves is not worth a data migration for a column nobody reads by name.
+ *
+ * Not sealed: an Atlassian account id is an opaque identifier from another
+ * system, which is the same reason the rest of those are left in the clear.
+ *
+ * PK is the account id — one Hexis user per Atlassian account — while one
+ * user may hold several account ids across sites, which is what `by_user`
+ * serves. Links die with the user (`onDelete: 'cascade'`): an erasure request
+ * must never be blocked by a leftover embed link.
+ */
+export const atlassianAccountLinks = pgTable('atlassian_account_links', {
+  atlassianAccountId: text('atlassian_account_id').primaryKey(),
+  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+}, (t) => ({
+  byUser: index('atlassian_account_links_by_user').on(t.userId),
+}));

package/src/modules/database/pg-error.ts

@@ -0,0 +1,15 @@
+/**
+ * The Postgres SQLSTATE of a failed query, or undefined when the error is not
+ * one Postgres raised. node-postgres puts `code` on the driver error; Drizzle
+ * (0.44 and later) wraps that error in a `DrizzleQueryError` whose `cause`
+ * carries it. So the code is read off the error and, failing that, off its
+ * cause — one level, which is all either wrapping adds.
+ */
+export function pgErrorCode(err: unknown): string | undefined {
+  const codeOf = (e: unknown): unknown => (typeof e === 'object' && e !== null ? (e as { code?: unknown }).code : undefined);
+  const own = codeOf(err);
+  if (typeof own === 'string') return own;
+  const cause = typeof err === 'object' && err !== null ? (err as { cause?: unknown }).cause : undefined;
+  const wrapped = codeOf(cause);
+  return typeof wrapped === 'string' ? wrapped : undefined;
+}

package/src/modules/embed/__tests__/account-links.migration.test.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { coreMigrationsDir } from '../../../assets.js';
+
+const MIGRATION = '0017_atlassian_account_links.sql';
+
+async function sql(): Promise<string> {
+  return fs.readFile(path.join(coreMigrationsDir(), MIGRATION), 'utf8');
+}
+
+/**
+ * The account-link table already EXISTS on an enterprise database: the Bevel
+ * Platform's own migration history created it, under this exact name and
+ * shape, while the embed lived there. Such a database must be ADOPTED as it
+ * stands, so every Atlassian link it holds keeps working and nobody re-links
+ * after the upgrade.
+ *
+ * That property lives in how this one file is WRITTEN, and the thing most
+ * likely to break it is regenerating it: `drizzle-kit generate` emits a bare
+ * `CREATE TABLE` and a bare `ADD CONSTRAINT`, either of which fails on a
+ * database that already has them — and a failed migration crash-loops the
+ * boot. So the guards are pinned here.
+ */
+describe('the account-link migration adopts a database that already has the table', () => {
+  it('creates the table only if it is absent', async () => {
+    expect(await sql()).toMatch(/CREATE TABLE IF NOT EXISTS "atlassian_account_links"/i);
+  });
+
+  it('adds the foreign key behind an existence guard, under the name the enterprise used', async () => {
+    const text = await sql();
+    // The NAME is what the guard recognises. A different one would add a
+    // second, duplicate constraint to an upgraded database.
+    const name = 'atlassian_account_links_user_id_users_id_fk';
+    // The guard looks for THIS name, as a foreign key with the cascade, and
+    // the constraint it adds when the guard finds nothing carries the same
+    // one — tied together, so a guard naming anything else fails here.
+    const guard = /IF NOT EXISTS\s*\(\s*SELECT 1 FROM pg_constraint\s+WHERE([\s\S]*?)\)\s*THEN/i.exec(text);
+    expect(guard).not.toBeNull();
+    expect(guard![1]).toContain(`conname = '${name}'`);
+    expect(guard![1]).toMatch(/contype = 'f'/);
+    expect(guard![1]).toMatch(/confdeltype = 'c'/);
+    expect(text).toContain(`ADD CONSTRAINT "${name}"`);
+    // Links die with the user: an erasure request must never be blocked by a
+    // leftover embed link.
+    expect(text).toMatch(/ON DELETE cascade/i);
+  });
+
+  it('creates the by-user index only if it is absent', async () => {
+    expect(await sql()).toMatch(/CREATE INDEX IF NOT EXISTS "atlassian_account_links_by_user"/i);
+  });
+
+  /**
+   * Nothing here may remove or rewrite a row or a column somebody is using.
+   *
+   * Matched on STATEMENTS rather than on words: `ON DELETE cascade` and `ON
+   * UPDATE no action` are referential actions on the key being added, not
+   * destructive statements, and a word-level rule would forbid the very
+   * clause that makes an erasure request work.
+   */
+  it('is purely additive — it drops nothing and rewrites nothing', async () => {
+    const statements = (await sql())
+      .split('\n')
+      .filter((line) => !line.trimStart().startsWith('--'))
+      .join('\n')
+      .split(';');
+    // The VERB a statement opens with is what says whether it destroys
+    // anything. `ON DELETE cascade` and `ON UPDATE no action` sit mid-clause
+    // on the key being added and are the referential actions an erasure
+    // request depends on; `ALTER COLUMN` is a rewrite wherever it appears.
+    const destructive = statements.filter((statement) => {
+      const body = statement.trim();
+      // A statement opens a segment — or opens a block's body: inside a
+      // `DO $$ BEGIN … IF … THEN … END IF; END $$` the first statement shares
+      // its segment with the block's opening, so the verbs are looked for
+      // after BEGIN / THEN / ELSE / LOOP as well.
+      return (
+        /(^|\b(BEGIN|THEN|ELSE|LOOP)\s+)(DROP|DELETE|TRUNCATE|UPDATE)\b/i.test(body) ||
+        /ALTER\s+COLUMN/i.test(body)
+      );
+    });
+    expect(destructive).toEqual([]);
+  });
+
+  it('is registered in the journal the runner reads, exactly once', async () => {
+    const journal = JSON.parse(
+      await fs.readFile(path.join(coreMigrationsDir(), 'meta', '_journal.json'), 'utf8'),
+    ) as { entries: Array<{ tag: string; idx: number }> };
+    const mine = journal.entries.filter((e) => e.tag === MIGRATION.replace(/\.sql$/, ''));
+    expect(mine).toHaveLength(1);
+    // The runner applies entries in ARRAY order, so the array order is the
+    // ledger: every entry sits at the position its idx names, and this one
+    // after every migration numbered before it.
+    expect(journal.entries.map((e) => e.idx)).toEqual(journal.entries.map((_, i) => i));
+    expect(journal.entries.findIndex((e) => e.tag === mine[0].tag)).toBe(mine[0].idx);
+    expect(mine[0].tag.startsWith(String(mine[0].idx).padStart(4, '0'))).toBe(true);
+  });
+});

package/src/modules/embed/__tests__/embed-link.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import {
+  EmbedRefParseError,
+  isSafeRepoRelativeEmbedPath,
+  parseEmbedRef,
+} from '../embed-link.js';
+
+const KB = 'knowledge-base';
+
+/**
+ * The mint's reference grammar — the boundary between Hexis and the Atlassian
+ * connector's own repository, which is why its shape may not change. Two
+ * consumers hand it very different strings: `open_page` a path from a model,
+ * the connector a `content:` marker a person pasted into a ticket.
+ */
+describe('parseEmbedRef', () => {
+  it.each([
+    ['a bare path', 'Data/Thing.md', { repoRelative: 'Data/Thing.md' }],
+    ['a path under the kb folder', `${KB}/Data/Thing.md`, { repoRelative: 'Data/Thing.md' }],
+    ['a leading slash', '/Data/Thing.md', { repoRelative: 'Data/Thing.md' }],
+    ['a dot-slash', './Data/Thing.md', { repoRelative: 'Data/Thing.md' }],
+    [
+      'a heading anchor',
+      'Data/Thing.md#problem-statement',
+      { repoRelative: 'Data/Thing.md', slug: 'problem-statement' },
+    ],
+    [
+      'an app URL',
+      `https://hexis.example/workspace/main/${KB}/Data/Thing.md#goal`,
+      { repoRelative: 'Data/Thing.md', slug: 'goal' },
+    ],
+    [
+      'an embed URL (the branch segment is ignored)',
+      `https://hexis.example/embed/some-draft/${KB}/Data/Thing.md`,
+      { repoRelative: 'Data/Thing.md' },
+    ],
+    [
+      'an app URL of a deployment served under a path prefix',
+      `https://hexis.example/hexis/workspace/main/${KB}/Data/Thing.md#goal`,
+      { repoRelative: 'Data/Thing.md', slug: 'goal' },
+    ],
+    [
+      'an app URL whose route name arrives percent-encoded',
+      `https://hexis.example/%77orkspace/main/${KB}/Data/Thing.md`,
+      { repoRelative: 'Data/Thing.md' },
+    ],
+    [
+      'an app URL whose default branch carries a slash, encoded in its segment',
+      `https://hexis.example/workspace/team%2Fmain/${KB}/Data/Thing.md`,
+      { repoRelative: 'Data/Thing.md' },
+    ],
+    ['a content: marker in angle brackets', '<content: Data/Thing.md>', { repoRelative: 'Data/Thing.md' }],
+    ['a percent-encoded space', 'Data/Some%20Thing.md', { repoRelative: 'Data/Some Thing.md' }],
+  ])('reads %s', (_label, raw, expected) => {
+    expect(parseEmbedRef(raw, KB)).toEqual(expected);
+  });
+
+  /**
+   * EVERY file type the app renders, because the embed renders them all with
+   * the app's own renderer. The enterprise panel this grammar came from
+   * accepted `.md`, `.html` and `.htm` only — the three its own renderer could
+   * draw — and that list would now be a second, narrower answer to "what can
+   * be shown".
+   */
+  it.each(['Shots/diagram.png', 'Docs/Report.pdf', 'Docs/Spec.docx', 'Data/rows.csv', 'Notes/plain.txt'])(
+    'reads a path of any type: %s',
+    (path) => {
+      expect(parseEmbedRef(path, KB)).toEqual({ repoRelative: path });
+    },
+  );
+
+  it('reads a bare node id as an id, not a path', () => {
+    expect(parseEmbedRef('hx-some-ticket', KB)).toEqual({ nodeId: 'hx-some-ticket' });
+    expect(parseEmbedRef('hx-some-ticket#notes', KB)).toEqual({
+      nodeId: 'hx-some-ticket',
+      slug: 'notes',
+    });
+  });
+
+  it('reads a single segment WITH an extension as a path, not an id', () => {
+    expect(parseEmbedRef('AGENTS.md', KB)).toEqual({ repoRelative: 'AGENTS.md' });
+  });
+
+  it.each([
+    ['empty', ''],
+    ['traversal', '../../etc/passwd'],
+    ['a traversal inside', 'Data/../../etc/passwd'],
+    ['a percent-encoded separator', 'Data%2f..%2fsecret.md'],
+    ['a percent-encoded dot', 'Data/%2e%2e/secret.md'],
+  ])('refuses %s', (_label, raw) => {
+    expect(() => parseEmbedRef(raw, KB)).toThrow(EmbedRefParseError);
+  });
+
+  /**
+   * A single segment that is not a legal id is a FILE NAME, not a bad id — a
+   * space is perfectly legal in one, and the knowledge base is full of them.
+   * Only the shape of the trailing segment decides which form a reference is
+   * (see `looksLikeNodeId`), and nothing about that is a refusal.
+   */
+  it('reads a single segment that is not a legal id as a file name', () => {
+    expect(parseEmbedRef('Not An Id', KB)).toEqual({ repoRelative: 'Not An Id' });
+  });
+
+  it('refuses a malformed percent-escape rather than throwing a URIError', () => {
+    expect(() => parseEmbedRef('Data/%zz.md', KB)).toThrow(EmbedRefParseError);
+  });
+});
+
+describe('isSafeRepoRelativeEmbedPath', () => {
+  it('refuses an absolute path, traversal and a control character', () => {
+    expect(isSafeRepoRelativeEmbedPath('/etc/passwd')).toBe(false);
+    expect(isSafeRepoRelativeEmbedPath('a/../b.md')).toBe(false);
+    expect(isSafeRepoRelativeEmbedPath('a\nb.md')).toBe(false);
+    expect(isSafeRepoRelativeEmbedPath('')).toBe(false);
+  });
+
+  it('accepts a path with no extension at all', () => {
+    // Not a node id — it has a separator — and the app renders extensionless
+    // text files, so nothing here may refuse it.
+    expect(isSafeRepoRelativeEmbedPath('Data/LICENSE')).toBe(true);
+  });
+});