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

package/dist/modules/embed/embed.errors.d.ts

@@ -0,0 +1,30 @@
+/** The presented embed token is missing, malformed, or expired. */
+export declare class EmbedTokenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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 declare class EmbedNodeNotFoundError extends Error {
+    constructor(message: string);
+}
+/** The viewer lacks the access the operation needs on the default branch. */
+export declare class EmbedAccessError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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 declare class EmbedLockedError extends Error {
+    /** Display name / email of the current lock holder, for the UI. */
+    readonly heldBy: string;
+    constructor(
+    /** Display name / email of the current lock holder, for the UI. */
+    heldBy: string);
+}
+//# sourceMappingURL=embed.errors.d.ts.map

package/dist/modules/embed/embed.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.errors.d.ts","sourceRoot":"","sources":["../../../src/modules/embed/embed.errors.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,SAAmC;CAIvD;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,6EAA6E;AAC7E,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,SAA6C;CAIjE;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,mEAAmE;aACnD,MAAM,EAAE,MAAM;;IAD9B,mEAAmE;IACnD,MAAM,EAAE,MAAM;CAKjC"}

package/dist/modules/embed/embed.errors.js

@@ -0,0 +1,42 @@
+/** 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) {
+        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 {
+    heldBy;
+    constructor(
+    /** Display name / email of the current lock holder, for the UI. */
+    heldBy) {
+        super(`This file is currently being edited by ${heldBy}`);
+        this.heldBy = heldBy;
+        this.name = 'EmbedLockedError';
+    }
+}
+//# sourceMappingURL=embed.errors.js.map

package/dist/modules/embed/embed.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.errors.js","sourceRoot":"","sources":["../../../src/modules/embed/embed.errors.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,GAAG,gCAAgC;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,GAAG,0CAA0C;QAC9D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAGvB;IAFlB;IACE,mEAAmE;IACnD,MAAc;QAE9B,KAAK,CAAC,0CAA0C,MAAM,EAAE,CAAC,CAAC;QAF1C,WAAM,GAAN,MAAM,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/modules/embed/embed.interface.d.ts

@@ -0,0 +1,204 @@
+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>;
+}
+//# sourceMappingURL=embed.interface.d.ts.map

package/dist/modules/embed/embed.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.interface.d.ts","sourceRoot":"","sources":["../../../src/modules/embed/embed.interface.ts"],"names":[],"mappings":"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"}

package/dist/modules/embed/embed.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=embed.interface.js.map

package/dist/modules/embed/embed.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.interface.js","sourceRoot":"","sources":["../../../src/modules/embed/embed.interface.ts"],"names":[],"mappings":""}

package/dist/modules/embed/embed.routes.d.ts

@@ -0,0 +1,59 @@
+import express from 'express';
+import type { IEmbedService } from './embed.interface.js';
+import '../auth/auth.middleware.js';
+/**
+ * What `/api/embed/raw` answers as `Content-Type`, by extension — the types a
+ * renderer draws from a URL. Anything else is bytes the renderer parses
+ * itself (a workbook, a deck), served as the octet stream it is.
+ */
+/**
+ * The embed surface: a token-minted, pseudonymous, short-lived page that
+ * renders ONE knowledge-base file with the app's own renderer, inside
+ * somebody else's frame — an MCP App's sandbox in a chat, an Atlassian issue
+ * panel. Two routers, with deliberately different auth stories:
+ *
+ *  - {@link createEmbedRoutes} (mounted at the app root, ahead of the JWT
+ *    middleware): the connector's shared-secret mint, and the TOKEN-ONLY data
+ *    routes the SPA `/embed` page calls. Also stamps the framing headers on
+ *    the two SPA routes.
+ *  - {@link createEmbedLinkRoutes} (mounted under the JWT middleware): links
+ *    the viewer's outside account to their just-authenticated Hexis user.
+ *
+ * Mounted before the production static catch-all, so the framing headers are
+ * stamped before `index.html` is served for `/embed*`.
+ *
+ * ── Why the data routes take the token and NOTHING else ───────────────────
+ *
+ * The embed page is framed by any site (see the framing headers below), which
+ * is what makes it work in every host's sandbox without an admin entry per
+ * host. The security of the embed therefore rests entirely on the token:
+ * short-lived, scoped to one file and one identity, pseudonymous. A session
+ * FALLBACK would hand that away — a hostile page could frame `/embed`, and
+ * the browser would attach the visitor's own cookie to every data request the
+ * page made, so the attacker's frame would read and write as the victim. So
+ * every route here reads `token` and never `req.userId`: a request carrying a
+ * perfectly valid session and no token is refused.
+ *
+ * ── Cross-origin callers ──────────────────────────────────────────────────
+ *
+ * The MCP App view runs the embed inside a chat host's SANDBOX — another
+ * origin, unknowable in advance (a hash subdomain under Claude's content
+ * domain, a URL-derived one under ChatGPT's) — and calls the token routes
+ * from there. Nothing here has to allow that: the server's app-wide CORS
+ * (`create-core-server.ts`, mounted ahead of this router) already reflects
+ * any origin and answers the preflight, for every route. That is 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. The routes test mounts the same CORS
+ * to pin that a cross-origin caller gets through.
+ */
+export declare function createEmbedRoutes(embedService: IEmbedService): express.Router;
+/**
+ * Links the authenticated Hexis user to the outside account the embed token
+ * carries. JWT-protected — `req.userId` is the user we link TO, which is why
+ * the page it is called from refuses every framing ancestor.
+ */
+export declare function createEmbedLinkRoutes(embedService: IEmbedService): express.Router;
+/** What a tokenless request is told, on every embed data route. */
+export declare const TOKEN_REQUIRED = "This view needs its embed token. A session is not accepted here.";
+//# sourceMappingURL=embed.routes.d.ts.map

package/dist/modules/embed/embed.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/embed/embed.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAS1D,OAAO,4BAA4B,CAAC;AAEpC;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CA0I7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAwDjF;AAqBD,mEAAmE;AACnE,eAAO,MAAM,cAAc,qEACyC,CAAC"}