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

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

@@ -0,0 +1,304 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
+import type { ReadForTool } from '../../workspace/workspace.tools.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
+import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
+import {
+  HTTP_DEPLOYMENT_NOTE,
+  OPEN_PAGE_TOOL,
+  registerEmbedTools,
+  toRepoRelative,
+} from '../embed.tools.js';
+
+const KB = 'knowledge-base';
+const BRANCH = TEST_BRANCH_MODEL.defaultBranch;
+const PAGE = '# Thing\n\nWhat it is.\n';
+
+let server: Server | null = null;
+afterEach(async () => {
+  if (server) await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = null;
+});
+
+interface Opts {
+  /** What `read_file`'s own read answers — or throws. */
+  read?: ReadForTool;
+  canBeReached?: boolean;
+  /** The deployment's notes for the gated tools; a fresh, empty set when absent. */
+  notes?: ToolDescriptionNotes;
+  /** The caller the tool auth resolves to: a signed-in session, or a connection key's owner. */
+  caller?: { id: string; email: string; name: string; tokenId?: string };
+}
+
+async function serve(opts: Opts = {}) {
+  const caller = opts.caller ?? { id: 'u-1', email: 'alice@bevel.software', name: 'Alice' };
+  const registry = new ToolRegistry();
+  const router = express.Router();
+  const auth: express.RequestHandler = (req, _res, next) => {
+    req.toolAuth = {
+      source: 'external',
+      userId: caller.id,
+      scope: 'write',
+      ...(caller.tokenId ? { tokenId: caller.tokenId } : {}),
+    } as never;
+    next();
+  };
+  const resolve = async (): Promise<ToolContext> =>
+    ({
+      user: { id: caller.id, email: caller.email, name: caller.name },
+      scope: 'write',
+      source: 'external',
+      ...(caller.tokenId ? { tokenId: caller.tokenId } : {}),
+      abortSignal: new AbortController().signal,
+      workspaceService: {} as never,
+      workflowService: {} as never,
+      events: {} as never,
+      getFilesystem: async () => {
+        throw new Error('open_page reads through readForTool, not the filesystem');
+      },
+    }) as unknown as ToolContext;
+
+  const mints: Array<{ userId: string; reference: string }> = [];
+  const embedService = {
+    mintForUser: vi.fn(async (input: { userId: string; reference: string }) => {
+      mints.push(input);
+      return { token: 'tok', embedUrl: `https://hexis.example/embed?token=tok` };
+    }),
+  };
+  const readForTool: ReadForTool =
+    opts.read ?? (async () => ({ kind: 'text', text: PAGE }));
+
+  const notes = opts.notes ?? new ToolDescriptionNotes();
+  registerEmbedTools(registry, router, auth, createToolHandlerFactory(resolve), {
+    embedService: embedService as never,
+    kb: testKbContext({ kbDirName: KB }),
+    readForTool,
+    canBeReached: () => opts.canBeReached ?? true,
+    appUrlFor: (repoRelative, slug) =>
+      `https://hexis.example/workspace/${encodeURIComponent(BRANCH)}/${KB}/${repoRelative}` +
+      (slug ? `#${slug}` : ''),
+    notes,
+  });
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', router);
+  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}`;
+
+  const call = async (body: unknown) => {
+    const res = await fetch(`${base}/api/agent/tools/${OPEN_PAGE_TOOL}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+  };
+  return { call, registry, embedService, mints, notes };
+}
+
+/** `open_page`'s definition as the external listing carries it, with its `sessionId` input. */
+async function openPageDef(registry: ToolRegistry) {
+  const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
+  const body = (def.inputs as { properties: { body: { properties: Record<string, { description?: string }> } } })
+    .properties.body;
+  return { description: def.description, sessionId: body.properties.sessionId };
+}
+
+describe('open_page: the listing', () => {
+  it('is advertised to an external agent, and is not an in-app tool', async () => {
+    const { registry } = await serve();
+    const external = (await registry.listExternal()).map((t) => t.name);
+    const internal = (await registry.listInternal()).map((t) => t.name);
+    expect(external).toContain(OPEN_PAGE_TOOL);
+    // The in-app reader is already looking at the app, where every page is a
+    // click away; an iframe of the page they are standing on cannot help.
+    expect(internal).not.toContain(OPEN_PAGE_TOOL);
+  });
+
+  it('takes a path and an optional heading, and no branch at all', async () => {
+    const { registry } = await serve();
+    const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
+    const body = (def.inputs as { properties: { body: { properties: Record<string, unknown>; required: string[] } } })
+      .properties.body;
+    // `sessionId` as `read_file` takes it: the read is `read_file`'s own, and
+    // a deployment whose read hook wants the session must be able to get it.
+    expect(Object.keys(body.properties).sort()).toEqual(['heading', 'path', 'sessionId']);
+    expect(body.required).toEqual(['path']);
+    // The embedded view is editable, and an editable embed targets the
+    // default branch only — so there is nothing for a caller to choose.
+    expect(body.properties).not.toHaveProperty('branch');
+  });
+
+  /**
+   * The read is `read_file`'s own, so the access contract an agent reads
+   * about it is `read_file`'s too: the note a deployment registers for the
+   * gated tools, and the `sessionId` note — whether registered before this
+   * tool was mounted or after (an overlay registers from the tool-surface
+   * hook, which runs once the tools are up).
+   */
+  it('carries the deployment notes for the gated tools and the sessionId input, registered before or after mounting', async () => {
+    const early = new ToolDescriptionNotes();
+    early.registerGatedToolNote(' Early gated note.');
+    early.registerSessionIdNote(' Early session note.');
+    const before = await serve({ notes: early });
+    const seenEarly = await openPageDef(before.registry);
+    expect(seenEarly.description.endsWith(' Early gated note.')).toBe(true);
+    expect(seenEarly.sessionId.description).toBe(early.sessionIdDescription());
+    expect(seenEarly.sessionId.description?.endsWith(' Early session note.')).toBe(true);
+    if (server) await new Promise<void>((resolve) => server!.close(() => resolve()));
+    server = null;
+
+    const { registry, notes } = await serve();
+    const plain = await openPageDef(registry);
+    expect(plain.description.endsWith(' Early gated note.')).toBe(false);
+    expect(plain.sessionId.description).toBe(notes.sessionIdDescription());
+    notes.registerGatedToolNote(' Late gated note.');
+    notes.registerSessionIdNote(' Late session note.');
+    const late = await openPageDef(registry);
+    expect(late.description).toBe(plain.description + ' Late gated note.');
+    expect(late.sessionId.description).toBe(notes.sessionIdDescription());
+    expect(late.sessionId.description?.endsWith(' Late session note.')).toBe(true);
+  });
+});
+
+describe('open_page: the answer', () => {
+  it('answers the page, the embed address, the app address, the path and the branch', async () => {
+    const { call } = await serve();
+    const { status, body } = await call({ path: `${KB}/Data/Thing.md` });
+    expect(status).toBe(200);
+    expect(body).toEqual({
+      path: `${KB}/Data/Thing.md`,
+      content: PAGE,
+      embedUrl: 'https://hexis.example/embed?token=tok',
+      appUrl: `https://hexis.example/workspace/${encodeURIComponent(BRANCH)}/${KB}/Data/Thing.md`,
+      branch: BRANCH,
+    });
+  });
+
+  it('mints for the caller identity — which under a connection key is the key owner', async () => {
+    const { call, mints } = await serve({
+      caller: { id: 'owner-9', email: 'owner@bevel.software', name: 'Owner', tokenId: 'tok-1' },
+    });
+    await call({ path: 'Data/Thing.md' });
+    expect(mints).toEqual([{ userId: 'owner-9', reference: 'Data/Thing.md' }]);
+  });
+
+  it('passes the heading through to the mint and into the app address', async () => {
+    const { call, mints } = await serve();
+    const { body } = await call({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    expect(mints[0].reference).toBe('Data/Thing.md#what-it-is');
+    expect(body.appUrl).toContain('#what-it-is');
+  });
+
+  it('accepts a path with or without the knowledge-base prefix, as read_file documents', async () => {
+    const { call, mints } = await serve();
+    await call({ path: 'Data/Thing.md' });
+    await call({ path: `/${KB}/Data/Thing.md` });
+    expect(mints.map((m) => m.reference)).toEqual(['Data/Thing.md', 'Data/Thing.md']);
+  });
+
+  it('answers an image with the reader own note, and still shows the picture in the view', async () => {
+    const { call } = await serve({
+      read: async () => ({ kind: 'image', data: 'AAA', mimeType: 'image/png', note: '[image Shots/x.png]' }),
+    });
+    const { body } = await call({ path: 'Shots/x.png' });
+    expect(body.content).toBe('[image Shots/x.png]');
+    expect(body.embedUrl).toBe('https://hexis.example/embed?token=tok');
+  });
+
+  it('answers a refusal the reader gives as the file text, as read_file does', async () => {
+    const { call } = await serve({
+      read: async () => ({ kind: 'refusal', message: 'This .zip cannot be read as text.' }),
+    });
+    const { body } = await call({ path: 'Archive/x.zip' });
+    expect(body.content).toBe('This .zip cannot be read as text.');
+  });
+});
+
+describe('open_page: refusals', () => {
+  /**
+   * The read comes FIRST and it is `read_file`'s own, so the refusal is the
+   * one `read_file` gives — and no token is minted, because the mint is below
+   * that line.
+   */
+  it('refuses a path the caller may not read, in read_file own words, and mints nothing', async () => {
+    const { call, embedService } = await serve({
+      read: async () => {
+        throw new ToolError(`You don't have permission to read "${KB}/Secret.md".`, 403);
+      },
+    });
+    const { status, body } = await call({ path: `${KB}/Secret.md` });
+    expect(status).toBe(403);
+    expect(body.error).toBe(`You don't have permission to read "${KB}/Secret.md".`);
+    expect(embedService.mintForUser).not.toHaveBeenCalled();
+  });
+
+  it('refuses a path that does not exist, in read_file own words, and mints nothing', async () => {
+    const { call, embedService } = await serve({
+      read: async () => {
+        throw new ToolError(`"${KB}/Gone.md" does not exist.`, 404);
+      },
+    });
+    const { status, body } = await call({ path: `${KB}/Gone.md` });
+    expect(status).toBe(404);
+    expect(body.error).toBe(`"${KB}/Gone.md" does not exist.`);
+    expect(embedService.mintForUser).not.toHaveBeenCalled();
+  });
+
+  it('refuses a path outside the knowledge base, and a missing one', async () => {
+    const { call, embedService } = await serve();
+    expect((await call({ path: '' })).status).toBe(400);
+    expect((await call({ path: '../../etc/passwd' })).status).toBe(400);
+    expect((await call({})).status).toBe(400);
+    expect(embedService.mintForUser).not.toHaveBeenCalled();
+  });
+});
+
+describe('open_page: a deployment that cannot be framed', () => {
+  /**
+   * A host runs an app view in a sandboxed https iframe, and no browser lets
+   * an https document frame a plain-http one. So the tool still answers the
+   * text and the app address, says why there is no view, and mints nothing —
+   * a token nobody can open is only a token in a transcript.
+   */
+  it('answers the text and the app address, and says the view needs https', async () => {
+    const { call, embedService } = await serve({ canBeReached: false });
+    const { status, body } = await call({ path: 'Data/Thing.md' });
+    expect(status).toBe(200);
+    expect(body.content).toBe(PAGE);
+    expect(body.appUrl).toContain('/workspace/');
+    expect(body.branch).toBe(BRANCH);
+    expect(body).not.toHaveProperty('embedUrl');
+    expect(body.note).toBe(HTTP_DEPLOYMENT_NOTE);
+    expect(String(body.note)).toContain('https');
+    expect(embedService.mintForUser).not.toHaveBeenCalled();
+  });
+});
+
+describe('toRepoRelative', () => {
+  it.each([
+    ['a bare path', 'Data/Thing.md', 'Data/Thing.md'],
+    ['the kb prefix', `${KB}/Data/Thing.md`, 'Data/Thing.md'],
+    ['a leading slash', `/${KB}/Data/Thing.md`, 'Data/Thing.md'],
+    ['a dot-slash', './Data/Thing.md', 'Data/Thing.md'],
+    ['a trailing slash', 'Data/Thing.md/', 'Data/Thing.md'],
+  ])('reads %s', (_label, input, expected) => {
+    expect(toRepoRelative(input, KB)).toBe(expected);
+  });
+
+  // A backslash is refused, as `read_file` refuses it: read as a separator it
+  // would name a file other than the one the caller wrote, in a signed token.
+  it.each([['empty', ''], ['the folder itself', KB], ['traversal', 'Data/../../x'], ['a newline', 'a\nb'], ['DEL', 'a\x7fb'], ['a backslash', 'Data\\Thing.md']])(
+    'refuses %s',
+    (_label, input) => {
+      expect(toRepoRelative(input, KB)).toBeNull();
+    },
+  );
+});

package/src/modules/embed/__tests__/mcp-app.test.ts

@@ -0,0 +1,207 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { MCP_APP_MIME_TYPE, MCP_APP_URI_SCHEME } from '@bevel-software/platform-mcp-core';
+import { OPEN_PAGE_TOOL } from '../embed.tools.js';
+import {
+  isSandboxReachableOrigin,
+  McpAppService,
+  OPEN_PAGE_VIEW_URI_PREFIX,
+  openPageViewUri,
+  originOf,
+} from '../mcp-app.js';
+import { createMcpAppRoutes } from '../mcp-app.routes.js';
+
+let server: Server | null = null;
+afterEach(async () => {
+  if (server) await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = null;
+});
+
+const PUBLIC = 'https://hexis.example';
+
+describe('the open_page view', () => {
+  it('is named by the tool and served under the MCP App media type', async () => {
+    const manifest = await new McpAppService({ publicFrontendUrl: PUBLIC }).manifest();
+    expect(manifest.resources).toHaveLength(1);
+    const { uri } = manifest.resources[0];
+    expect(manifest.tools[OPEN_PAGE_TOOL]).toEqual({ resourceUri: uri });
+    expect(uri.startsWith(MCP_APP_URI_SCHEME)).toBe(true);
+    expect(uri.startsWith(OPEN_PAGE_VIEW_URI_PREFIX)).toBe(true);
+    expect(manifest.resources[0]).toMatchObject({ uri, mimeType: MCP_APP_MIME_TYPE });
+  });
+
+  /**
+   * A host caches a view by its URI, so a changed view under an unchanged
+   * URI is served stale until the host happens to refetch — Claude kept
+   * rendering the cached, pre-#391 view, the one that goes blank. Naming the
+   * view by its content makes every change a new URI.
+   */
+  it('is named by its content, so a changed view is a new resource and the same view the same one', async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), 'mcp-app-view-'));
+    try {
+      const at = async (html: string) => {
+        writeFileSync(path.join(dir, 'page.html'), html);
+        return (await new McpAppService({ publicFrontendUrl: PUBLIC, viewDir: dir }).manifest()).resources[0].uri;
+      };
+      const first = await at('<!doctype html><p>one</p>');
+      const same = await at('<!doctype html><p>one</p>');
+      const changed = await at('<!doctype html><p>two</p>');
+      expect(first).toMatch(/^ui:\/\/hexis\/page-[0-9a-f]{12}\.html$/);
+      expect(same).toBe(first);
+      expect(changed).not.toBe(first);
+      expect(first).toBe(openPageViewUri('<!doctype html><p>one</p>'));
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  /**
+   * The view reaches ONE origin — the deployment that served it — for two
+   * things: fetching its build manifest and the token-only embed API
+   * (connect), and loading the embed bundle (resources). It frames nothing:
+   * Claude's host drops `frameDomains` and pins `frame-src` to `'self'`,
+   * which is why the view runs the bundle in its own document.
+   */
+  it('declares exactly the deployment own public origin for connecting and loading, and no frames', async () => {
+    const manifest = await new McpAppService({ publicFrontendUrl: `${PUBLIC}/sub/path` }).manifest();
+    expect(manifest.resources[0].ui.csp).toEqual({ connectDomains: [PUBLIC], resourceDomains: [PUBLIC] });
+  });
+
+  /**
+   * The sandbox `domain` field's format is each host's own to define and
+   * validate, and a value a host rejects is a view that never renders. The
+   * view keeps no storage and has no OAuth callback, so it asks for no
+   * dedicated origin and takes the host's default sandbox.
+   */
+  it('asks the host for no sandbox domain of its own', async () => {
+    const manifest = await new McpAppService({ publicFrontendUrl: PUBLIC }).manifest();
+    expect(manifest.resources[0].ui).not.toHaveProperty('domain');
+    expect(manifest.resources[0].ui.prefersBorder).toBe(false);
+  });
+
+  it('is the HTML that runs the deployment embed bundle and relays a link, and nothing that renders content', async () => {
+    const manifest = await new McpAppService({ publicFrontendUrl: PUBLIC }).manifest();
+    const html = manifest.resources[0].text;
+    expect(html).toContain('ui/initialize');
+    expect(html).toContain('ui/notifications/tool-result');
+    expect(html).toContain('ui/open-link');
+    expect(html).toContain('structuredContent');
+    // The deployment's embed bundle, found through its build manifest and
+    // handed the page — not a frame of `/embed`, which a chat host's sandbox
+    // blocks.
+    expect(html).toContain('embed-manifest.json');
+    expect(html).toContain('__HEXIS_EMBED__');
+    expect(html).not.toContain('<iframe');
+    // No second rendering path: the view runs the app's renderers, it does not draw the page itself.
+    expect(html).not.toContain('marked');
+    expect(html).not.toContain('<markdown');
+  });
+
+  it('serves the view by URI, and nothing else', async () => {
+    const apps = new McpAppService({ publicFrontendUrl: PUBLIC });
+    const { uri } = (await apps.manifest()).resources[0];
+    expect(await apps.resource(uri)).not.toBeNull();
+    expect(await apps.resource('ui://hexis/not-a-view.html')).toBeNull();
+    // The unversioned name the view had before #391 is not served either: a
+    // host still asking for it gets "no such resource", not a stale view.
+    expect(await apps.resource('ui://hexis/page.html')).toBeNull();
+  });
+
+  it('reads the view once and caches it — resources/read is on a handshake path', async () => {
+    const apps = new McpAppService({ publicFrontendUrl: PUBLIC });
+    const [a, b] = await Promise.all([apps.manifest(), apps.manifest()]);
+    expect(a).toBe(b);
+  });
+});
+
+describe('originOf / isSandboxReachableOrigin', () => {
+  it('reduces an address to its origin, and refuses one that does not parse', () => {
+    expect(originOf(`${PUBLIC}/sub?x=1#y`)).toBe(PUBLIC);
+    expect(originOf('not a url')).toBeNull();
+  });
+
+  /**
+   * A host runs an app view in a sandboxed https iframe, and no browser lets
+   * an https document load scripts from, or fetch from, a plain-http origin —
+   * so a deployment reached over http has no embedded view, and `open_page`
+   * says so.
+   */
+  it.each([
+    ['https', 'https://hexis.example', true],
+    ['plain http', 'http://hexis.example', false],
+    ['localhost over http', 'http://localhost:3001', false],
+    ['nonsense', 'not a url', false],
+  ])('%s is reachable from a sandbox: %s', (_label, url, expected) => {
+    expect(isSandboxReachableOrigin(url)).toBe(expected);
+  });
+});
+
+describe('the manifest route the local MCP server reads', () => {
+  async function serve() {
+    const app = express();
+    const pass: express.RequestHandler = (_req, _res, next) => next();
+    app.use('/api', createMcpAppRoutes(new McpAppService({ publicFrontendUrl: PUBLIC }), pass));
+    server = app.listen(0);
+    await new Promise<void>((r) => server!.once('listening', () => r()));
+    return `http://127.0.0.1:${(server!.address() as AddressInfo).port}`;
+  }
+
+  it('answers the tool metadata and the view, so the local server can serve both', async () => {
+    const base = await serve();
+    const res = await fetch(`${base}/api/agent/mcp-app`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      tools: Record<string, { resourceUri: string }>;
+      resources: Array<{ uri: string; mimeType: string; text: string; ui: Record<string, unknown> }>;
+    };
+    expect(body.tools[OPEN_PAGE_TOOL].resourceUri).toBe(body.resources[0].uri);
+    expect(body.resources[0].uri.startsWith(OPEN_PAGE_VIEW_URI_PREFIX)).toBe(true);
+    expect(body.resources[0].mimeType).toBe(MCP_APP_MIME_TYPE);
+    expect(body.resources[0].text).toContain('ui/initialize');
+    expect(body.resources[0].ui).toMatchObject({
+      csp: { connectDomains: [PUBLIC], resourceDomains: [PUBLIC] },
+      prefersBorder: false,
+    });
+    expect(body.resources[0].ui).not.toHaveProperty('domain');
+  });
+
+  it('is behind the agent credential, like the rest of that surface', async () => {
+    const app = express();
+    const refuse: express.RequestHandler = (_req, res) => {
+      res.status(401).json({ error: 'Unauthenticated' });
+    };
+    app.use('/api', createMcpAppRoutes(new McpAppService({ publicFrontendUrl: PUBLIC }), refuse));
+    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}`;
+    expect((await fetch(`${base}/api/agent/mcp-app`)).status).toBe(401);
+  });
+});
+
+/**
+ * A deployment whose packaged view cannot be read must serve NO app rather
+ * than half of one: a `resourceUri` with no resource behind it would have a
+ * host preload a failure and show an empty frame where the tool's text was.
+ */
+describe('a view that cannot be read', () => {
+  it('leaves the deployment with no apps at all', async () => {
+    // The REAL build, pointed at a folder with no view in it — the read
+    // fails exactly as it does in an image that shipped without `mcp-app/`,
+    // and nothing packaged is touched under a parallel test run.
+    const empty = mkdtempSync(path.join(tmpdir(), 'no-mcp-app-'));
+    try {
+      const service = new McpAppService({ publicFrontendUrl: PUBLIC, viewDir: empty });
+      const manifest = await service.manifest();
+      expect(manifest.tools).toEqual({});
+      expect(manifest.resources).toEqual([]);
+      expect(await service.resource(openPageViewUri(''))).toBeNull();
+    } finally {
+      rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});

package/src/modules/embed/account-link.service.ts

@@ -0,0 +1,76 @@
+import { and, eq } from 'drizzle-orm';
+import type { Database } from '../database/connection.js';
+import { atlassianAccountLinks } from '../database/schema.js';
+
+/**
+ * Maps an outside system's account id — today an Atlassian (Forge) account —
+ * to a Hexis user. Keyed on the account id because the embed always knows it
+ * (`context.accountId`), unlike email which a user can hide. Written by the
+ * `/embed/link` flow; read on every embed load, lock and save minted for such
+ * an account, to resolve who the viewer is.
+ *
+ * An embed minted for a Hexis user (the MCP `open_page` path) consults none of
+ * this: its token names the user id directly, so there is nothing to link.
+ */
+/** The account links as the embed service consumes them — the port a deployment may substitute. */
+export interface IAccountLinkService {
+  /** Resolve an account id to its linked Hexis user id, or null. */
+  getUserId(accountId: string): Promise<string | null>;
+  link(accountId: string, userId: string): Promise<void>;
+  listForUser(userId: string): Promise<Array<{ atlassianAccountId: string; createdAt: Date }>>;
+  unlink(userId: string, accountId: string): Promise<boolean>;
+}
+
+export class AccountLinkService implements IAccountLinkService {
+  constructor(private readonly db: Database) {}
+
+  /** Resolve an account id to its linked Hexis user id, or null. */
+  async getUserId(accountId: string): Promise<string | null> {
+    const [row] = await this.db
+      .select()
+      .from(atlassianAccountLinks)
+      .where(eq(atlassianAccountLinks.atlassianAccountId, accountId))
+      .limit(1);
+    return row?.userId ?? null;
+  }
+
+  /** Link (or re-link) an account id to a Hexis user. Idempotent. */
+  async link(accountId: string, userId: string): Promise<void> {
+    await this.db
+      .insert(atlassianAccountLinks)
+      .values({ atlassianAccountId: accountId, userId })
+      .onConflictDoUpdate({
+        target: atlassianAccountLinks.atlassianAccountId,
+        set: { userId, updatedAt: new Date() },
+      });
+  }
+
+  /** Every account linked to `userId` (one per outside site). */
+  async listForUser(userId: string): Promise<Array<{ atlassianAccountId: string; createdAt: Date }>> {
+    return this.db
+      .select({
+        atlassianAccountId: atlassianAccountLinks.atlassianAccountId,
+        createdAt: atlassianAccountLinks.createdAt,
+      })
+      .from(atlassianAccountLinks)
+      .where(eq(atlassianAccountLinks.userId, userId));
+  }
+
+  /**
+   * Remove one of `userId`'s links. Scoped to the owner — the userId
+   * condition makes deleting someone else's link structurally impossible,
+   * not a caller responsibility. Returns whether a row was actually removed.
+   */
+  async unlink(userId: string, accountId: string): Promise<boolean> {
+    const deleted = await this.db
+      .delete(atlassianAccountLinks)
+      .where(
+        and(
+          eq(atlassianAccountLinks.atlassianAccountId, accountId),
+          eq(atlassianAccountLinks.userId, userId),
+        ),
+      )
+      .returning({ atlassianAccountId: atlassianAccountLinks.atlassianAccountId });
+    return deleted.length > 0;
+  }
+}