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

package/src/modules/code-mode/code-mode.tool.ts

@@ -11,6 +11,7 @@ import {
   chainExample,
   type ChainExampleTool,
   runToolChain,
+  withCallExample,
 } from '@bevel-software/platform-mcp-core';
 import type { SpillStore } from '../workspace/spill-store.js';
 import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
@@ -46,7 +47,8 @@ export function createCallToolChainTool(
     id: 'call_tool_chain',
     description: [
       CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE,
-      `Execute JavaScript code with direct access to all registered UTCP tools as hierarchical functions — call them as \`${ns}.<tool>({ body: { ...args } })\`, synchronous, no await.${worked} Every argument a tool declares REQUIRED must be present — for the knowledge-base tools that includes \`branch\`. The runtime is plain JavaScript — no type annotations or other TypeScript-only syntax — plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser; there is no \`Buffer\`, no \`fetch\` and no \`require\`. Return the final value with \`return\`. Use \`list_tools\` and \`tools_info\` first to discover available tools and their interfaces.`,
+      `Execute JavaScript code with direct access to all registered UTCP tools as hierarchical functions, synchronous, no await.${worked} The runtime is plain JavaScript — no type annotations or other TypeScript-only syntax — plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser; there is no \`Buffer\`, no \`fetch\` and no \`require\`. Return the final value with \`return\`. Use \`list_tools\` and \`tools_info\` first to discover available tools and their interfaces.`,
+      `There is NO single calling shape: some tools take their arguments under a \`body\` object, others take them flat. Call each tool as the \`Call:\` line at the top of its own description shows — it is generated from that tool's input schema, and every tool in \`${ns}\` has one. Every argument a tool declares REQUIRED must be present; for the knowledge-base tools that includes \`branch\`. Arguments that do not match the schema are refused before anything is sent or run, and the refusal carries the tool's interface.`,
       'Error handling inside the chain: a failing tool call THROWS, and the thrown error\'s `.message` holds the server\'s actual reason (e.g. a 403 with the explanation, not just a status code). If you catch it, surface `err.message` (and `err.status` / `err.data` when present) — NEVER `return { error: err }` or otherwise return the raw Error object, because an Error serializes to `{}` (its `message` is non-enumerable) and the reason is lost. If you don\'t need to handle it, just let it throw — the runtime already reports `err.message` back to you.',
       `Failures are answered, never dropped: a chain that throws comes back with \`success: false\` and the reason, and one that outlives \`timeout\` (default ${CHAIN_TIMEOUT_DEFAULT_MS} ms, maximum ${CHAIN_TIMEOUT_MAX_MS} ms) comes back saying it timed out — raise \`timeout\` or split the work and run it again. Either way your next tool call works as usual.`,
       'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (its `branch` is ignored) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
@@ -176,7 +178,16 @@ export function createToolsInfoTool(client: CodeModeUtcpClient) {
         try {
           const found = await findToolByName(client, name);
           if (found) {
-            interfaces.push(client.toolToTypeScriptInterface(found.tool));
+            // With its `Call:` line, as on the MCP surface (`meta-tools.ts`):
+            // the chain's description tells the agent to call each tool as
+            // that line shows, and this is where it reads the tool. The
+            // repository's tool is not ours to edit, so a copy carries it.
+            interfaces.push(
+              client.toolToTypeScriptInterface({
+                ...found.tool,
+                description: withCallExample(found.tool.description, found.utcpName, found.tool.inputs),
+              }),
+            );
           } else {
             notFound.push(name);
           }

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/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);
+  });
+});

package/src/modules/embed/__tests__/embed.routes.test.ts

@@ -0,0 +1,362 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import cors from 'cors';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createEmbedLinkRoutes, createEmbedRoutes, TOKEN_REQUIRED } from '../embed.routes.js';
+import {
+  EmbedAccessError,
+  EmbedLockedError,
+  EmbedNodeNotFoundError,
+  EmbedTokenError,
+} from '../embed.errors.js';
+
+const TOKEN = 'a-valid-token';
+
+let server: Server | null = null;
+afterEach(async () => {
+  if (server) await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = null;
+});
+
+function stubService(overrides: Record<string, unknown> = {}) {
+  return {
+    sharedSecretConfigured: vi.fn(() => true),
+    verifySharedSecret: vi.fn((s?: string) => s === 'shh'),
+    mintForUser: vi.fn(async () => ({ token: TOKEN, embedUrl: 'https://hexis.example/embed?token=' + TOKEN })),
+    mintToken: vi.fn(async () => ({ token: TOKEN, embedUrl: 'https://hexis.example/embed?token=' + TOKEN })),
+    loadFile: vi.fn(async (token: string) => {
+      if (token !== TOKEN) throw new EmbedTokenError();
+      return { nodeName: 'Thing', content: '# Thing', canWrite: true };
+    }),
+    readBytes: vi.fn(async () => ({ bytes: Buffer.from([1, 2, 3]), path: 'Data/x.png' })),
+    acquireLock: vi.fn(async () => ({ acquired: true })),
+    heartbeat: vi.fn(async () => undefined),
+    cancel: vi.fn(async () => undefined),
+    save: vi.fn(async () => undefined),
+    propose: vi.fn(async () => ({ branch: 'suggestions/a-1/knowledge', number: 7, url: '/change-requests/7' })),
+    linkAccount: vi.fn(async () => undefined),
+    listLinkedAccounts: vi.fn(async () => [{ atlassianAccountId: 'acc-1', createdAt: 0 }]),
+    unlinkAccount: vi.fn(async () => true),
+    ...overrides,
+  };
+}
+
+/**
+ * The app as the server mounts it: the embed routes ahead of the JWT
+ * middleware, the link routes behind it, and a static catch-all last — the
+ * same order `create-core-server` uses, because the order is what makes the
+ * framing headers land before `index.html` is served.
+ */
+async function serve(
+  service: ReturnType<typeof stubService>,
+  opts: { session?: boolean; restrictFraming?: boolean; appWideCors?: boolean } = {},
+) {
+  const app = express();
+  // The server's own CORS, as `create-core-server` mounts it ahead of every
+  // route: any origin reflected, credentials allowed, preflights answered.
+  if (opts.appWideCors) app.use(cors({ origin: true, credentials: true }));
+  app.use(express.json());
+  // A deployment (or a later change to this app) that stamps a framing
+  // restriction on EVERY response, ahead of the embed routes — the case the
+  // embed page's own header removal exists for.
+  if (opts.restrictFraming) {
+    app.use((_req, res, next) => {
+      res.setHeader('X-Frame-Options', 'SAMEORIGIN');
+      res.setHeader('Content-Security-Policy', "frame-ancestors 'self'");
+      next();
+    });
+  }
+  app.use(createEmbedRoutes(service as never));
+  const authMiddleware: express.RequestHandler = (req, res, next) => {
+    if (!opts.session) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    req.userId = 'u-1';
+    next();
+  };
+  app.use('/api', authMiddleware, createEmbedLinkRoutes(service as never));
+  app.get('{*path}', (_req, res) => res.type('html').send('<!doctype html><title>SPA</title>'));
+
+  server = app.listen(0);
+  await new Promise<void>((r) => server!.once('listening', () => r()));
+  const base = `http://127.0.0.1:${(server!.address() as AddressInfo).port}`;
+  return {
+    base,
+    get: (path: string, headers: Record<string, string> = {}) => fetch(`${base}${path}`, { headers }),
+    post: (path: string, body: unknown, headers: Record<string, string> = {}) =>
+      fetch(`${base}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+      }),
+    del: (path: string) => fetch(`${base}${path}`, { method: 'DELETE' }),
+  };
+}
+
+/**
+ * Every route that serves FILE CONTENT or changes a file. The framing rule
+ * makes the embed page reachable from any site, so the token is the whole of
+ * the security — a session fallback would let a hostile frame read and write
+ * as whoever happened to be signed in.
+ */
+const DATA_ROUTES = [
+  ['GET', '/api/embed/load'],
+  ['GET', '/api/embed/raw'],
+  ['POST', '/api/embed/lock'],
+  ['POST', '/api/embed/heartbeat'],
+  ['POST', '/api/embed/cancel'],
+  ['POST', '/api/embed/save'],
+  ['POST', '/api/embed/propose'],
+] as const;
+
+describe('the embed data routes take the token and nothing else', () => {
+  it.each(DATA_ROUTES)('%s %s refuses a request with a valid session and no token', async (method, path) => {
+    const client = await serve(stubService(), { session: true });
+    const res =
+      method === 'GET'
+        ? await client.get(path, { cookie: 'bevel_token=a-real-session' })
+        : await client.post(path, { content: 'x' }, { cookie: 'bevel_token=a-real-session' });
+    expect(res.status).toBe(401);
+    expect((await res.json()).error).toBe(TOKEN_REQUIRED);
+  });
+
+  it.each(DATA_ROUTES)('%s %s answers a request with a token and no session', async (method, path) => {
+    const client = await serve(stubService());
+    const res =
+      method === 'GET'
+        ? await client.get(`${path}?token=${TOKEN}`)
+        : await client.post(path, { token: TOKEN, content: 'x' });
+    expect(res.status).toBeLessThan(400);
+  });
+
+  it('refuses an expired or rejected token with 401, so the view can say it expired', async () => {
+    const client = await serve(stubService());
+    const res = await client.get('/api/embed/load?token=stale');
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('framing', () => {
+  /**
+   * Any host may frame the embed page — that is what makes it work in every
+   * host's sandbox without an admin entry per host, and the token is what
+   * secures it. `X-Frame-Options` is REMOVED rather than merely unset, so a
+   * header added globally later cannot silently break every host's embed.
+   */
+  it('sends no framing restriction on the embed page, even under a global one', async () => {
+    const client = await serve(stubService(), { restrictFraming: true });
+    // The restriction is really there on every other page…
+    const other = await client.get('/workspace/main');
+    expect(other.headers.get('x-frame-options')).toBe('SAMEORIGIN');
+    // …and the embed page clears it.
+    const res = await client.get('/embed?token=' + TOKEN);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('x-frame-options')).toBeNull();
+    expect(res.headers.get('content-security-policy')).toBeNull();
+    // And it still falls through to the SPA.
+    expect(await res.text()).toContain('<!doctype html>');
+  });
+
+  /**
+   * The account-link page acts under the SIGNED-IN SESSION, so a page that
+   * could frame it could link a foreign account to a victim.
+   */
+  it('refuses every framing ancestor on the account-link page', async () => {
+    const client = await serve(stubService(), { restrictFraming: true });
+    const res = await client.get('/embed/link?token=' + TOKEN);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-security-policy')).toBe("frame-ancestors 'none'");
+    expect(res.headers.get('x-frame-options')).toBe('DENY');
+  });
+});
+
+describe('the connector mint', () => {
+  it('mints from the shared secret, an account id and a reference', async () => {
+    const service = stubService();
+    const client = await serve(service);
+    const res = await client.post(
+      '/api/embed/token',
+      { accountId: 'acc-1', email: 'a@x.io', reference: 'Data/Thing.md' },
+      { 'x-embed-secret': 'shh' },
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ token: TOKEN });
+    expect(service.mintToken).toHaveBeenCalledWith({
+      accountId: 'acc-1',
+      email: 'a@x.io',
+      reference: 'Data/Thing.md',
+    });
+  });
+
+  it('refuses a wrong secret and a missing one', async () => {
+    const client = await serve(stubService());
+    expect((await client.post('/api/embed/token', { accountId: 'a', reference: 'b' }, { 'x-embed-secret': 'no' })).status).toBe(401);
+    expect((await client.post('/api/embed/token', { accountId: 'a', reference: 'b' })).status).toBe(401);
+  });
+
+  it('refuses an incomplete body', async () => {
+    const client = await serve(stubService());
+    const res = await client.post('/api/embed/token', { accountId: 'acc-1' }, { 'x-embed-secret': 'shh' });
+    expect(res.status).toBe(400);
+  });
+
+  /** A deployment with no connector pointed at it has no such route at all. */
+  it('is absent when no shared secret is configured', async () => {
+    const service = stubService({ sharedSecretConfigured: vi.fn(() => false) });
+    const client = await serve(service);
+    const res = await client.post('/api/embed/token', { accountId: 'a', reference: 'b' }, { 'x-embed-secret': 'shh' });
+    expect(res.status).toBe(404);
+    expect(service.verifySharedSecret).not.toHaveBeenCalled();
+  });
+});
+
+describe('the data routes', () => {
+  it('serves the page to render', async () => {
+    const client = await serve(stubService());
+    const res = await client.get(`/api/embed/load?token=${TOKEN}`);
+    expect(await res.json()).toMatchObject({ nodeName: 'Thing' });
+  });
+
+  it('serves bytes inline, never as a download, and never from a shared cache', async () => {
+    const client = await serve(stubService());
+    const res = await client.get(`/api/embed/raw?token=${TOKEN}&path=assets/x.png`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-disposition')).toBe('inline');
+    expect(res.headers.get('cache-control')).toContain('no-store');
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    expect([...new Uint8Array(await res.arrayBuffer())]).toEqual([1, 2, 3]);
+  });
+
+  it('saves, and proposes, through the service', async () => {
+    const service = stubService();
+    const client = await serve(service);
+    expect((await client.post('/api/embed/save', { token: TOKEN, content: 'new' })).status).toBe(204);
+    expect(service.save).toHaveBeenCalledWith(TOKEN, 'new');
+    const proposed = await client.post('/api/embed/propose', { token: TOKEN, content: 'draft' });
+    expect(await proposed.json()).toMatchObject({ number: 7 });
+  });
+
+  it('says who holds the lock when a save is refused for it', async () => {
+    const service = stubService({
+      save: vi.fn(async () => {
+        throw new EmbedLockedError('Bob');
+      }),
+    });
+    const client = await serve(service);
+    const res = await client.post('/api/embed/save', { token: TOKEN, content: 'x' });
+    expect(res.status).toBe(409);
+    expect((await res.json()).error).toContain('Bob');
+  });
+
+  /** Protected text and a token-bearing link: nothing may keep the answer. */
+  it('forbids caching the loaded page, as it does the raw bytes', async () => {
+    const client = await serve(stubService());
+    const load = await client.get(`/api/embed/load?token=${TOKEN}`);
+    expect(load.headers.get('cache-control')).toBe('no-store, private');
+    const refused = await client.get('/api/embed/load?token=wrong');
+    expect(refused.headers.get('cache-control')).toBe('no-store, private');
+  });
+
+  it('refuses a save with no content', async () => {
+    const client = await serve(stubService());
+    expect((await client.post('/api/embed/save', { token: TOKEN })).status).toBe(400);
+  });
+
+  it.each([
+    [new EmbedTokenError(), 401],
+    [new EmbedAccessError(), 403],
+    [new EmbedNodeNotFoundError('gone'), 404],
+    [new EmbedLockedError('Bob'), 409],
+  ])('maps %s to its status', async (error, status) => {
+    const service = stubService({
+      loadFile: vi.fn(async () => {
+        throw error;
+      }),
+    });
+    const client = await serve(service);
+    expect((await client.get(`/api/embed/load?token=${TOKEN}`)).status).toBe(status);
+  });
+
+  it('does not leak an unexpected failure message', async () => {
+    const service = stubService({
+      loadFile: vi.fn(async () => {
+        throw new Error('postgres://user:pw@host down');
+      }),
+    });
+    const client = await serve(service);
+    const res = await client.get(`/api/embed/load?token=${TOKEN}`);
+    expect(res.status).toBe(500);
+    expect((await res.json()).error).toBe('Something went wrong.');
+  });
+});
+
+describe('the account-link routes', () => {
+  it('link, list and unlink need a session', async () => {
+    const client = await serve(stubService(), { session: false });
+    expect((await client.post('/api/embed/link', { token: TOKEN })).status).toBe(401);
+    expect((await client.get('/api/embed/links')).status).toBe(401);
+    expect((await client.del('/api/embed/links/acc-1')).status).toBe(401);
+  });
+
+  it('links the token account to the signed-in user', async () => {
+    const service = stubService();
+    const client = await serve(service, { session: true });
+    expect((await client.post('/api/embed/link', { token: TOKEN })).status).toBe(204);
+    expect(service.linkAccount).toHaveBeenCalledWith(TOKEN, 'u-1');
+  });
+
+  it('answers 404 for a link that is not this user own, so it cannot probe others', async () => {
+    const service = stubService({ unlinkAccount: vi.fn(async () => false) });
+    const client = await serve(service, { session: true });
+    expect((await client.del('/api/embed/links/someone-elses')).status).toBe(404);
+  });
+});
+
+/**
+ * The MCP App view runs the embed inside a chat host's SANDBOX — another
+ * origin, and one no deployment can know in advance — and calls the token
+ * routes from there. The server's app-wide CORS is what lets it: mounted
+ * here as `create-core-server` mounts it, so what is pinned is the behaviour
+ * a sandbox actually meets, not a header these routes set themselves. Safe
+ * on the token routes for the reason the token-only rule exists: CORS guards
+ * a browser's ambient credentials, these routes take none, and the token in
+ * the request is the whole credential.
+ */
+describe('a cross-origin caller reaches the token routes through the app-wide CORS', () => {
+  const SANDBOX = 'https://sandbox.example';
+  const FOREIGN = { origin: SANDBOX };
+
+  it.each(DATA_ROUTES)('%s %s answers the sandbox origin', async (method, path) => {
+    const client = await serve(stubService(), { appWideCors: true });
+    const res =
+      method === 'GET'
+        ? await client.get(`${path}?token=${TOKEN}`, FOREIGN)
+        : await client.post(path, { token: TOKEN, content: 'x' }, FOREIGN);
+    expect(res.status).toBeLessThan(400);
+    expect(res.headers.get('access-control-allow-origin')).toBe(SANDBOX);
+  });
+
+  it('answers the preflight a JSON POST from the sandbox triggers', async () => {
+    const client = await serve(stubService(), { appWideCors: true });
+    const res = await fetch(`${client.base}/api/embed/save`, {
+      method: 'OPTIONS',
+      headers: { ...FOREIGN, 'access-control-request-method': 'POST', 'access-control-request-headers': 'content-type' },
+    });
+    expect(res.status).toBe(204);
+    expect(res.headers.get('access-control-allow-origin')).toBe(SANDBOX);
+    expect(res.headers.get('access-control-allow-methods')).toContain('POST');
+    expect(res.headers.get('access-control-allow-headers')?.toLowerCase()).toContain('content-type');
+  });
+
+  it('still refuses a sandbox caller that brings no token', async () => {
+    // Being reachable from another origin changes nothing about who may
+    // read: the token is the credential, and a request without it is 401
+    // from the sandbox exactly as from a tab.
+    const client = await serve(stubService(), { appWideCors: true });
+    const res = await client.get('/api/embed/load', FOREIGN);
+    expect(res.status).toBe(401);
+    expect((await res.json()).error).toBe(TOKEN_REQUIRED);
+  });
+});