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

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

@@ -0,0 +1,180 @@
+/**
+ * A knowledge-base reference resolved from whatever a consumer hands the
+ * mint: a pasted app URL, a repo-relative path, or a bare node id.
+ *
+ * Two consumers share this grammar and must keep sharing it — the MCP
+ * `open_page` tool (a path, from a model) and the Atlassian connector (a
+ * `content:` marker, from a person pasting into a ticket). The mint contract
+ * is the boundary between Hexis and that connector's own repository, so this
+ * parse is the one part of the embed that may not change shape.
+ */
+
+/** A reference to a FILE, and optionally one heading inside it. */
+export interface EmbedRef {
+  /** Repo-relative path, e.g. `Product/Knowledge/Thing.md`. */
+  repoRelative: string;
+  /** Heading anchor slug (e.g. `problem-statement`), or undefined for the whole file. */
+  slug?: string;
+}
+
+/**
+ * A node-id reference — the canonical copy-link form `/workspace/<branch>/<id>`.
+ * Core has no node graph to resolve an id with, so it is handed back for a
+ * deployment that does (see `EmbedNodeIdResolver`); without one the mint
+ * refuses it the way it refuses any unresolvable reference.
+ */
+export interface EmbedIdRef {
+  nodeId: string;
+  slug?: string;
+}
+
+/** A node frontmatter id: lowercase alphanumeric + hyphens, no separators/dots. */
+const NODE_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** Thrown when a reference can't be parsed into a safe path or an id. */
+export class EmbedRefParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EmbedRefParseError';
+  }
+}
+
+/** `decodeURIComponent` that turns a malformed escape into a parse error. */
+function safeDecode(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    throw new EmbedRefParseError('Malformed percent-encoding in reference');
+  }
+}
+
+/**
+ * A safe repo-relative embeddable path: rejects absolute paths, traversal,
+ * control characters and percent-encoded separators.
+ *
+ * Deliberately NO extension allowlist. The enterprise panel this grammar came
+ * from accepted `.md`, `.html` and `.htm` only, because those were the two
+ * things its own renderer could draw. The embed now renders with the APP's
+ * renderer for the file's type — every type the app renders, documents and
+ * images included — so an extension list here would be a second, narrower
+ * answer to "what can be shown", and the one that is wrong.
+ */
+export function isSafeRepoRelativeEmbedPath(repoRelative: string): boolean {
+  if (!repoRelative) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f\x7f]/.test(repoRelative)) return false;
+  if (/%2e|%2f|%5c/i.test(repoRelative)) return false;
+  // A backslash is refused, not read as a separator: the workspace path
+  // validator refuses it too, so normalising it here would only move a
+  // malformed reference from this 400 to a later one.
+  if (repoRelative.includes('\\')) return false;
+  const norm = repoRelative;
+  if (norm.startsWith('/')) return false;
+  return norm.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+
+/**
+ * Whether a reference that parses as a safe path should instead be read as a
+ * node id.
+ *
+ * With the extension allowlist gone, `my-process` is BOTH a legal path and a
+ * legal id, so the two forms need a rule rather than a fallback. The rule is
+ * the shape the copy-link produces: an id is one segment with no dot in it
+ * (`/workspace/<branch>/<id>`). Anything with a separator or an extension is
+ * a path, which is every real file in the repository.
+ */
+function looksLikeNodeId(repoRelative: string): boolean {
+  return !repoRelative.includes('/') && !repoRelative.includes('.') && NODE_ID_RE.test(repoRelative);
+}
+
+/**
+ * A separator spelled `%2F` or `%5C` is refused BEFORE decoding: decoded, it
+ * becomes a real `/` that the safe-path check can no longer tell from one
+ * the caller wrote, and `Data%2FThing.md` would name `Data/Thing.md`.
+ */
+function refuseEncodedSeparators(rawPath: string): void {
+  if (/%2f|%5c/i.test(rawPath)) {
+    throw new EmbedRefParseError(`Not a safe knowledge-base path: ${rawPath}`);
+  }
+}
+
+/**
+ * Parse a reference into a file path or a node id. Accepts:
+ *   - A full app URL: `https://<host>/workspace/<branch>/<kbDir>/<path>#<slug>`
+ *     (also `/embed/<branch>/…`), optionally angle-bracketed and/or
+ *     `content:`-prefixed.
+ *   - A bare path, with or without a fragment: `<kbDir>/<path>#<slug>`,
+ *     `<path>#<slug>`, or just `<path>` (whole file).
+ *   - A bare node id (the copy-link form).
+ *
+ * The branch segment in a URL is intentionally ignored: the editable embed
+ * always targets the deployment's default branch. A missing `#slug` means
+ * "the whole file".
+ */
+export function parseEmbedRef(raw: string, kbDirName: string): EmbedRef | EmbedIdRef {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new EmbedRefParseError('Empty reference');
+  }
+
+  // A person pastes the marker, so the two decorations arrive in either order
+  // — `content: <url>` and `<content: url>` are both things a ticket holds.
+  // Peeled in a loop rather than in one fixed order, so neither spelling
+  // leaves a `content:` prefix inside the path (where it reads as a scheme and
+  // the whole reference is refused).
+  let ref = raw.trim();
+  for (let i = 0; i < 4; i += 1) {
+    const peeled = ref
+      .replace(/^content:\s*/i, '')
+      .replace(/^<+/, '')
+      .replace(/>+$/, '')
+      .trim();
+    if (peeled === ref) break;
+    ref = peeled;
+  }
+
+  let pathPart: string;
+  let fragment: string;
+
+  if (/^https?:\/\//i.test(ref)) {
+    let url: URL;
+    try {
+      url = new URL(ref);
+    } catch {
+      throw new EmbedRefParseError(`Not a valid URL: ${ref}`);
+    }
+    fragment = safeDecode(url.hash.replace(/^#/, ''));
+    // The app's route (`workspace` or `embed`) is found wherever it sits: a
+    // deployment served under a path prefix carries it after the prefix,
+    // which is then not part of the file's path. The branch segment that
+    // follows it is ignored — and may carry an encoded separator, since a
+    // default branch named `team/main` is written `team%2Fmain` there; only
+    // the FILE path after it is held to the plain-separator rule.
+    const rawSegments = url.pathname.split('/').filter(Boolean);
+    // Matched DECODED (a route name may arrive percent-encoded), while the
+    // separator rule below reads the raw spelling.
+    const route = rawSegments.findIndex((s) => {
+      const decoded = safeDecode(s);
+      return decoded === 'workspace' || decoded === 'embed';
+    });
+    const rest = route >= 0 && rawSegments.length >= route + 3 ? rawSegments.slice(route + 2) : rawSegments;
+    refuseEncodedSeparators(rest.join('/'));
+    pathPart = rest.map((s) => safeDecode(s)).join('/');
+  } else {
+    const hashIndex = ref.indexOf('#');
+    fragment = hashIndex >= 0 ? safeDecode(ref.slice(hashIndex + 1)) : '';
+    const rawPath = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
+    refuseEncodedSeparators(rawPath);
+    pathPart = rawPath.split('/').map((s) => safeDecode(s)).join('/');
+  }
+
+  let repoRelative = pathPart.replace(/^\.\//, '').replace(/^\/+/, '');
+  if (repoRelative.startsWith(`${kbDirName}/`)) {
+    repoRelative = repoRelative.slice(kbDirName.length + 1);
+  }
+
+  const slug = fragment.trim() || undefined;
+
+  if (looksLikeNodeId(repoRelative)) return { nodeId: repoRelative, slug };
+  if (isSafeRepoRelativeEmbedPath(repoRelative)) return { repoRelative, slug };
+  throw new EmbedRefParseError(`Not a safe knowledge-base path: ${pathPart}`);
+}

package/src/modules/embed/embed.errors.ts

@@ -0,0 +1,43 @@
+/** The presented embed token is missing, malformed, or expired. */
+export class EmbedTokenError extends Error {
+  constructor(message = 'Invalid or expired embed token') {
+    super(message);
+    this.name = 'EmbedTokenError';
+  }
+}
+
+/**
+ * The referenced file doesn't exist on the embed's target branch (→ 404).
+ * Raised at mint time for a dead reference and at load time when the file was
+ * renamed or removed after the token was minted. The message is user-facing —
+ * it is what the embedded view shows for the reference.
+ */
+export class EmbedNodeNotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EmbedNodeNotFoundError';
+  }
+}
+
+/** The viewer lacks the access the operation needs on the default branch. */
+export class EmbedAccessError extends Error {
+  constructor(message = 'You do not have edit access to this file') {
+    super(message);
+    this.name = 'EmbedAccessError';
+  }
+}
+
+/**
+ * Another editor holds the file lock, so a save can't proceed (→ 409). Raised
+ * when the viewer's own lock lapsed — a frame left hidden past the TTL — and
+ * somebody else took the file in the meantime.
+ */
+export class EmbedLockedError extends Error {
+  constructor(
+    /** Display name / email of the current lock holder, for the UI. */
+    public readonly heldBy: string,
+  ) {
+    super(`This file is currently being edited by ${heldBy}`);
+    this.name = 'EmbedLockedError';
+  }
+}

package/src/modules/embed/embed.interface.ts

@@ -0,0 +1,203 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+
+/**
+ * WHO an embed token was minted for.
+ *
+ * Two kinds, and the difference is only how the identity is spelled:
+ *
+ *  - `user` — a Hexis user id. What the MCP `open_page` tool mints: the MCP
+ *    session already authenticated somebody (a signed-in user, or the owner
+ *    of the connection key the agent carries), so the token names them
+ *    outright and there is nothing to link.
+ *  - `atlassian` — an outside account id, resolved to a Hexis user through
+ *    the account-link table. What the Atlassian connector's mint produces,
+ *    and the reason that table exists.
+ *
+ * Both resolve to one user, whose read and write access the view then obeys.
+ * Claims stay PSEUDONYMOUS whichever kind it is — a token travels as an
+ * iframe URL parameter, so it carries an id and never an address or a name.
+ */
+export type EmbedSubject =
+  | { kind: 'user'; userId: string }
+  | { kind: 'atlassian'; accountId: string };
+
+/** Result of minting an embed token for one file. */
+export interface EmbedTokenResult {
+  /** Signed, short-lived token scoping the bearer to one file + heading + identity. */
+  token: string;
+  /** Ready-to-iframe URL: `<frontend>/embed?token=…` (the SPA embed route). */
+  embedUrl: string;
+}
+
+/** How the embed should render a file: with the app's renderer for its type. */
+export interface EmbedFileView {
+  /** Display name — file basename without its extension. */
+  nodeName: string;
+  /** Repo-relative path of the embedded file. */
+  repoRelative: string;
+  /** Workspace-relative path (`<kbDir>/<repoRelative>`) — what the app's renderers take. */
+  workspacePath: string;
+  /** The knowledge-base directory name, so the view can build app URLs. */
+  kbDirName: string;
+  /** The branch rendered. Always the deployment's default branch. */
+  branch: string;
+  /** The file's address in the app, absolute. */
+  appUrl: string;
+  /** Heading slug this embed is scoped to; absent for a whole file. */
+  heading?: string;
+  /**
+   * The file's TEXT, for a renderer that takes text (markdown, HTML source,
+   * plain text, CSV, a `.tool`). Empty for a file whose renderer fetches its
+   * own bytes — an image, a PDF, a Word document — which read them from
+   * `GET /api/embed/raw` under this same token.
+   */
+  content: string;
+  /**
+   * Whether `content` carries the file's text at all. False says "this
+   * renderer reads bytes": the difference between an empty file and a
+   * picture, which the view must not confuse.
+   */
+  contentIsText: boolean;
+  /** Whether the token's identity resolved to a Hexis user at all. */
+  linked: boolean;
+  /** Whether that user may READ this file. Always false when unlinked. */
+  canRead: boolean;
+  /** Whether that user may WRITE this file on the default branch. */
+  canWrite: boolean;
+  /** Where to send an unlinked viewer to link their account. */
+  linkUrl: string;
+}
+
+/** Outcome of an Edit-time lock acquisition. */
+export interface EmbedLockResult {
+  acquired: boolean;
+  /** Current holder's display name when `acquired` is false. */
+  holderName?: string;
+}
+
+/** Where a proposal landed, so the view can point at it. */
+export interface EmbedProposalResult {
+  /** The suggestions branch the proposal was committed to. */
+  branch: string;
+  /** The change request number, when one could be read back. */
+  number?: number;
+  /** The change request's address in the app, when its number is known. */
+  url?: string;
+}
+
+/** One outside account linked to a Hexis user (the Connected apps screen). */
+export interface EmbedLinkedAccount {
+  atlassianAccountId: string;
+  /** Epoch ms of when the link was created. */
+  createdAt: number;
+}
+
+/**
+ * Resolve a bare node id (the copy-link form `/workspace/<branch>/<id>`) to
+ * its repo-relative path, or null when no node has that id.
+ *
+ * Core has no node graph, so core refuses an id reference. A deployment that
+ * does keeps the Atlassian connector's id references working by registering
+ * one of these — the mint's only extension point, and the reason the connector
+ * needs no change when the embed moves into Hexis.
+ */
+export type EmbedNodeIdResolver = (nodeId: string) => Promise<string | null>;
+
+/**
+ * What the embed service needs of the workspace: the clone of a branch, and
+ * four verbs on one file of it. A port rather than the workspace service
+ * itself, so a deployment (or a test) hands in whatever answers these.
+ */
+export interface EmbedWorkspacePort {
+  getOrCreateForBranch(branch: string): Promise<{ id: string }>;
+  isFile(workspaceId: string, wsPath: string): Promise<boolean>;
+  readFileBinary(workspaceId: string, wsPath: string): Promise<Buffer>;
+  writeFile(workspaceId: string, wsPath: string, content: string): Promise<void>;
+  /** One mutation at a time per resolved path, in this process: `op` runs after every turn already taken for `wsPath`. */
+  withPathTurn<T>(workspaceId: string, wsPath: string, op: () => Promise<T>): Promise<T>;
+}
+
+/** What the embed service needs of authentication: a user by id, and the email-domain rule. */
+export interface EmbedAuthPort {
+  getUserById(userId: string): Promise<AuthUser | null>;
+  isEmailDomainAllowed(email: string): boolean;
+  /** Whether the account is on: it exists and no admin switched it off — the gate every credential passes. */
+  isActive(userId: string): Promise<boolean>;
+}
+
+/**
+ * Mints and consumes embed tokens that let a host — an MCP App's sandbox, an
+ * Atlassian panel — display and edit one knowledge-base file inside itself.
+ *
+ * The file is the source of truth: editing acquires the platform's file lock,
+ * saving writes to the default branch and releases it (which commits), and a
+ * viewer who may not write proposes instead, exactly as the app's file page
+ * does. The framed data methods — load, raw bytes, lock, heartbeat, cancel,
+ * save, propose — authenticate by the TOKEN and nothing else: no session is
+ * consulted, and a request that carries one without a token is refused. The
+ * account-management methods (`linkAccount`, `listLinkedAccounts`,
+ * `unlinkAccount`) are the exception, called from session-authenticated
+ * routes on a page no host may frame.
+ */
+export interface IEmbedService {
+  /**
+   * Whether the SHARED-SECRET mint (`POST /api/embed/token`) is configured.
+   *
+   * Only that one route: the embed surface itself is part of every deployment
+   * now, because the MCP App is, and its mint authenticates by the MCP
+   * session rather than by a secret. A deployment with no
+   * `EMBED_SHARED_SECRET` simply has no Atlassian connector pointed at it.
+   */
+  sharedSecretConfigured(): boolean;
+  /** Constant-time check of the connector→backend shared secret. */
+  verifySharedSecret(secret: string | undefined): boolean;
+
+  /** Mint for a Hexis user — the MCP path. `reference` is a path or an app URL. */
+  mintForUser(input: { userId: string; reference: string }): Promise<EmbedTokenResult>;
+
+  /**
+   * Mint for an outside account — the Atlassian connector's path, unchanged.
+   * `email` is consulted only by the allowed-email-domains gate and never
+   * enters the token.
+   */
+  mintToken(input: { accountId: string; email?: string; reference: string }): Promise<EmbedTokenResult>;
+
+  /** Load the file the token is scoped to, with the viewer's read/write status. */
+  loadFile(token: string): Promise<EmbedFileView>;
+
+  /**
+   * The raw bytes of the embedded file, or of one asset `path` beside it (an
+   * image a markdown page shows — a file no reader edits as text, or an SVG,
+   * the one text format a page draws as a picture), for the app renderers
+   * that read bytes rather than the text buffer. Gated on the token
+   * identity's read access, per file. Any other text page than the embedded
+   * one is refused: the token scopes the view to ONE page, and another page
+   * opens in the app, never through this view's token.
+   */
+  readBytes(token: string, path?: string): Promise<{ bytes: Buffer; path: string }>;
+
+  /** Acquire the edit lock (Edit clicked). Requires write access. */
+  acquireLock(token: string): Promise<EmbedLockResult>;
+  /** Keep a held lock alive while editing. */
+  heartbeat(token: string): Promise<void>;
+  /** Drop the lock without committing (Cancel / view closed). */
+  cancel(token: string): Promise<void>;
+  /** Write `content` to the default branch, then release the lock (commits). */
+  save(token: string, content: string): Promise<void>;
+  /**
+   * File `content` as a change request authored by the token's identity, on
+   * that person's own suggestions branch. What a viewer without write access
+   * does instead of saving; nothing lands on the default branch.
+   */
+  propose(token: string, content: string): Promise<EmbedProposalResult>;
+
+  /** Link the token's outside account to `userId` (called after sign-in). */
+  linkAccount(token: string, userId: string): Promise<void>;
+  /** The outside accounts linked to `userId`, for the Connected apps screen. */
+  listLinkedAccounts(userId: string): Promise<EmbedLinkedAccount[]>;
+  /**
+   * Remove one of `userId`'s links (self-service disconnect / erasure).
+   * False when the account isn't linked to this user.
+   */
+  unlinkAccount(userId: string, accountId: string): Promise<boolean>;
+}