@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/work/src/diagrams/embed.ts

@@ -0,0 +1,340 @@
+import { DiagramsProtocolError, DiagramsTimeoutError } from "./errors.js";
+import type { DrawioExportBounds, DrawioExportFormat, DrawioInboundEvent, DrawioOutboundAction } from "./messages.js";
+import { validateDiagramsOrigin } from "./origin.js";
+
+export interface DrawioEmbedFrame {
+  readonly contentWindow: {
+    postMessage(message: unknown, targetOrigin: string): void;
+  } | null;
+}
+
+export interface DrawioMessageEvent {
+  readonly origin: string;
+  readonly source: unknown;
+  readonly data: unknown;
+}
+
+export interface DrawioMessageSource {
+  addEventListener(type: "message", listener: (event: DrawioMessageEvent) => void): void;
+  removeEventListener(type: "message", listener: (event: DrawioMessageEvent) => void): void;
+}
+
+export type DrawioEventMap = {
+  init: () => void;
+  load: () => void;
+  save: (event: { readonly xml: string; readonly exit?: boolean }) => void;
+  autosave: (event: { readonly xml: string }) => void;
+  exit: (event: { readonly modified: boolean }) => void;
+  configure: () => void;
+  export: (event: { readonly format: string; readonly data: string; readonly xml?: string; readonly bounds?: DrawioExportBounds }) => void;
+  error: (event: { readonly message: string }) => void;
+};
+
+export interface DrawioEmbedOptions {
+  readonly iframe: DrawioEmbedFrame;
+  readonly origin: string;
+  readonly messageSource?: DrawioMessageSource;
+  readonly onProtocolError?: (error: DiagramsProtocolError) => void;
+  readonly defaultExportTimeoutMs?: number;
+}
+
+export interface DrawioLoadOptions {
+  readonly xml: string;
+  readonly autosave?: boolean;
+  readonly saveAndExit?: boolean;
+  readonly noSaveBtn?: boolean;
+  readonly noExitBtn?: boolean;
+  readonly title?: string;
+}
+
+export interface DrawioExportOptions {
+  readonly format: DrawioExportFormat;
+  readonly scale?: number;
+  readonly border?: number;
+  readonly xml?: string;
+  readonly embedImages?: boolean;
+  readonly timeoutMs?: number;
+}
+
+export interface DrawioExportResult {
+  readonly format: string;
+  readonly data: string;
+  readonly xml?: string;
+  readonly bounds?: DrawioExportBounds;
+}
+
+export interface DrawioEmbed {
+  readonly origin: string;
+  on<K extends keyof DrawioEventMap>(event: K, listener: DrawioEventMap[K]): () => void;
+  off<K extends keyof DrawioEventMap>(event: K, listener: DrawioEventMap[K]): void;
+  load(options: DrawioLoadOptions): void;
+  configure(config: Readonly<Record<string, unknown>>): void;
+  merge(xml: string): void;
+  export(options: DrawioExportOptions): Promise<DrawioExportResult>;
+  postAction(action: DrawioOutboundAction): void;
+  destroy(): void;
+}
+
+const DEFAULT_EXPORT_TIMEOUT_MS = 30_000;
+
+export function createDrawioEmbed(options: DrawioEmbedOptions): DrawioEmbed {
+  if (!options || typeof options !== "object") {
+    throw new DiagramsProtocolError("createDrawioEmbed requires an options object");
+  }
+
+  if (!options.iframe || typeof options.iframe !== "object") {
+    throw new DiagramsProtocolError("createDrawioEmbed requires an iframe container with contentWindow");
+  }
+
+  const origin = validateDiagramsOrigin(options.origin);
+  const defaultTimeoutMs = options.defaultExportTimeoutMs ?? DEFAULT_EXPORT_TIMEOUT_MS;
+
+  const listeners = new Map<keyof DrawioEventMap, Set<(...args: any[]) => void>>();
+  const pendingExportResolvers = new Set<(result: DrawioExportResult) => void>();
+
+  const messageSource: DrawioMessageSource | undefined =
+    options.messageSource ??
+    (typeof globalThis !== "undefined" && typeof (globalThis as unknown as { addEventListener?: unknown }).addEventListener === "function"
+      ? (globalThis as unknown as DrawioMessageSource)
+      : undefined);
+
+  function handleMessage(event: DrawioMessageEvent): void {
+    // 1. Origin verification: must strictly match the configured origin
+    if (event.origin !== origin) {
+      return;
+    }
+
+    // 2. Source verification: must come from the embed iframe's contentWindow
+    if (!options.iframe.contentWindow || event.source !== options.iframe.contentWindow) {
+      return;
+    }
+
+    // 3. Payload normalization
+    let payload: unknown;
+    if (typeof event.data === "string") {
+      try {
+        payload = JSON.parse(event.data);
+      } catch {
+        options.onProtocolError?.(new DiagramsProtocolError("Failed to parse JSON message payload from draw.io iframe"));
+        return;
+      }
+    } else {
+      payload = event.data;
+    }
+
+    if (!payload || typeof payload !== "object") {
+      options.onProtocolError?.(new DiagramsProtocolError("Received non-object message payload from draw.io iframe"));
+      return;
+    }
+
+    const eventName = (payload as { event?: unknown }).event;
+    if (typeof eventName !== "string") {
+      options.onProtocolError?.(new DiagramsProtocolError("Inbound draw.io message is missing string 'event' discriminator"));
+      return;
+    }
+
+    dispatchInboundEvent(payload as DrawioInboundEvent);
+  }
+
+  function dispatchInboundEvent(inbound: DrawioInboundEvent): void {
+    switch (inbound.event) {
+      case "init": {
+        const set = listeners.get("init");
+        if (set) {
+          for (const fn of Array.from(set)) fn();
+        }
+        break;
+      }
+      case "load": {
+        const set = listeners.get("load");
+        if (set) {
+          for (const fn of Array.from(set)) fn();
+        }
+        break;
+      }
+      case "save": {
+        const set = listeners.get("save");
+        if (set) {
+          for (const fn of Array.from(set)) {
+            fn({ xml: inbound.xml, exit: inbound.exit });
+          }
+        }
+        break;
+      }
+      case "autosave": {
+        const set = listeners.get("autosave");
+        if (set) {
+          for (const fn of Array.from(set)) {
+            fn({ xml: inbound.xml });
+          }
+        }
+        break;
+      }
+      case "exit": {
+        const set = listeners.get("exit");
+        if (set) {
+          for (const fn of Array.from(set)) {
+            fn({ modified: Boolean(inbound.modified) });
+          }
+        }
+        break;
+      }
+      case "configure": {
+        const set = listeners.get("configure");
+        if (set) {
+          for (const fn of Array.from(set)) fn();
+        }
+        break;
+      }
+      case "export": {
+        const result: DrawioExportResult = {
+          format: inbound.format,
+          data: inbound.data,
+          ...(inbound.xml !== undefined ? { xml: inbound.xml } : {}),
+          ...(inbound.bounds !== undefined ? { bounds: inbound.bounds } : {}),
+        };
+        // Resolve any waiting export promise
+        for (const resolver of Array.from(pendingExportResolvers)) {
+          resolver(result);
+        }
+        const set = listeners.get("export");
+        if (set) {
+          for (const fn of Array.from(set)) {
+            fn(result);
+          }
+        }
+        break;
+      }
+      case "error": {
+        const set = listeners.get("error");
+        if (set) {
+          for (const fn of Array.from(set)) {
+            fn({ message: inbound.message });
+          }
+        }
+        break;
+      }
+      default: {
+        options.onProtocolError?.(
+          new DiagramsProtocolError(`Unknown or unsupported draw.io event: "${(inbound as { event: string }).event}"`),
+        );
+        break;
+      }
+    }
+  }
+
+  if (messageSource) {
+    messageSource.addEventListener("message", handleMessage);
+  }
+
+  function postAction(action: DrawioOutboundAction): void {
+    if (!action || typeof action !== "object" || typeof action.action !== "string") {
+      throw new DiagramsProtocolError("Outbound action must be an object with an 'action' discriminator");
+    }
+
+    if (!options.iframe.contentWindow) {
+      throw new DiagramsProtocolError("Cannot post action: iframe contentWindow is null or unavailable");
+    }
+
+    // Prohibit wildcard posting - always post strictly to validated origin
+    if (origin === "*") {
+      throw new DiagramsProtocolError("Posting to wildcard targetOrigin '*' is strictly prohibited");
+    }
+
+    options.iframe.contentWindow.postMessage(JSON.stringify(action), origin);
+  }
+
+  return {
+    origin,
+
+    on<K extends keyof DrawioEventMap>(event: K, listener: DrawioEventMap[K]): () => void {
+      let set = listeners.get(event);
+      if (!set) {
+        set = new Set();
+        listeners.set(event, set);
+      }
+      set.add(listener as (...args: any[]) => void);
+      return () => {
+        set?.delete(listener as (...args: any[]) => void);
+      };
+    },
+
+    off<K extends keyof DrawioEventMap>(event: K, listener: DrawioEventMap[K]): void {
+      listeners.get(event)?.delete(listener as (...args: any[]) => void);
+    },
+
+    load(opts: DrawioLoadOptions): void {
+      postAction({
+        action: "load",
+        xml: opts.xml,
+        ...(opts.autosave !== undefined ? { autosave: opts.autosave ? 1 : 0 } : {}),
+        ...(opts.saveAndExit !== undefined ? { saveAndExit: opts.saveAndExit ? 1 : 0 } : {}),
+        ...(opts.noSaveBtn !== undefined ? { noSaveBtn: opts.noSaveBtn ? 1 : 0 } : {}),
+        ...(opts.noExitBtn !== undefined ? { noExitBtn: opts.noExitBtn ? 1 : 0 } : {}),
+        ...(opts.title !== undefined ? { title: opts.title } : {}),
+      });
+    },
+
+    configure(config: Readonly<Record<string, unknown>>): void {
+      postAction({
+        action: "configure",
+        config,
+      });
+    },
+
+    merge(xml: string): void {
+      postAction({
+        action: "merge",
+        xml,
+      });
+    },
+
+    export(opts: DrawioExportOptions): Promise<DrawioExportResult> {
+      const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs;
+
+      return new Promise<DrawioExportResult>((resolve, reject) => {
+        let timer: ReturnType<typeof setTimeout> | undefined;
+
+        const resolver = (result: DrawioExportResult) => {
+          if (timer) clearTimeout(timer);
+          pendingExportResolvers.delete(resolver);
+          resolve(result);
+        };
+
+        pendingExportResolvers.add(resolver);
+
+        if (timeoutMs > 0 && timeoutMs !== Number.POSITIVE_INFINITY) {
+          timer = setTimeout(() => {
+            pendingExportResolvers.delete(resolver);
+            reject(new DiagramsTimeoutError(`Timed out waiting for draw.io export response after ${timeoutMs}ms`));
+          }, timeoutMs);
+        }
+
+        try {
+          postAction({
+            action: "export",
+            format: opts.format,
+            ...(opts.scale !== undefined ? { scale: opts.scale } : {}),
+            ...(opts.border !== undefined ? { border: opts.border } : {}),
+            ...(opts.xml !== undefined ? { xml: opts.xml } : {}),
+            ...(opts.embedImages !== undefined ? { embedImages: opts.embedImages } : {}),
+          });
+        } catch (error) {
+          if (timer) clearTimeout(timer);
+          pendingExportResolvers.delete(resolver);
+          reject(error);
+        }
+      });
+    },
+
+    postAction,
+
+    destroy(): void {
+      if (messageSource) {
+        messageSource.removeEventListener("message", handleMessage);
+      }
+      listeners.clear();
+      pendingExportResolvers.clear();
+    },
+  };
+}

package/work/src/diagrams/errors.ts

@@ -0,0 +1,76 @@
+export type DiagramsErrorCode =
+  | "ERR_PRISM_DIAGRAMS"
+  | "ERR_PRISM_DIAGRAMS_ORIGIN_INVALID"
+  | "ERR_PRISM_DIAGRAMS_PROTOCOL"
+  | "ERR_PRISM_DIAGRAMS_XXE"
+  | "ERR_PRISM_DIAGRAMS_XML_MALFORMED"
+  | "ERR_PRISM_DIAGRAMS_XML_CAP"
+  | "ERR_PRISM_DIAGRAMS_XML_INVALID_MODEL"
+  | "ERR_PRISM_DIAGRAMS_UNSUPPORTED_FORMAT"
+  | "ERR_PRISM_DIAGRAMS_TIMEOUT";
+
+export class DiagramsError extends Error {
+  readonly code: DiagramsErrorCode;
+
+  constructor(code: DiagramsErrorCode, message: string) {
+    super(message);
+    this.name = "DiagramsError";
+    this.code = code;
+  }
+}
+
+export class DiagramsOriginError extends DiagramsError {
+  constructor(message: string) {
+    super("ERR_PRISM_DIAGRAMS_ORIGIN_INVALID", message);
+    this.name = "DiagramsOriginError";
+  }
+}
+
+export class DiagramsProtocolError extends DiagramsError {
+  constructor(message: string, code: DiagramsErrorCode = "ERR_PRISM_DIAGRAMS_PROTOCOL") {
+    super(code, message);
+    this.name = "DiagramsProtocolError";
+  }
+}
+
+export class DiagramsXxeError extends DiagramsError {
+  constructor(message = "XML contains forbidden DOCTYPE or ENTITY declaration") {
+    super("ERR_PRISM_DIAGRAMS_XXE", message);
+    this.name = "DiagramsXxeError";
+  }
+}
+
+export class DiagramsCapError extends DiagramsError {
+  constructor(message: string) {
+    super("ERR_PRISM_DIAGRAMS_XML_CAP", message);
+    this.name = "DiagramsCapError";
+  }
+}
+
+export class DiagramsXmlMalformedError extends DiagramsError {
+  constructor(message: string) {
+    super("ERR_PRISM_DIAGRAMS_XML_MALFORMED", message);
+    this.name = "DiagramsXmlMalformedError";
+  }
+}
+
+export class DiagramsModelInvalidError extends DiagramsError {
+  constructor(message: string) {
+    super("ERR_PRISM_DIAGRAMS_XML_INVALID_MODEL", message);
+    this.name = "DiagramsModelInvalidError";
+  }
+}
+
+export class DiagramsFormatError extends DiagramsError {
+  constructor(message: string) {
+    super("ERR_PRISM_DIAGRAMS_UNSUPPORTED_FORMAT", message);
+    this.name = "DiagramsFormatError";
+  }
+}
+
+export class DiagramsTimeoutError extends DiagramsError {
+  constructor(message: string) {
+    super("ERR_PRISM_DIAGRAMS_TIMEOUT", message);
+    this.name = "DiagramsTimeoutError";
+  }
+}

package/work/src/diagrams/index.ts

@@ -0,0 +1,81 @@
+export {
+  canonicalizeDrawioXml,
+  type DrawioCanonicalizeOptions,
+} from "./canonicalize.js";
+export {
+  DEFAULT_MAX_ATTRIBUTES,
+  DEFAULT_MAX_ELEMENTS,
+  DEFAULT_MAX_XML_BYTES,
+  type DrawioXmlCaps,
+  HARD_MAX_ATTRIBUTES,
+  HARD_MAX_ELEMENTS,
+  HARD_MAX_XML_BYTES,
+  type ResolvedDrawioXmlCaps,
+  resolveDiagramsCaps,
+  validateByteCap,
+} from "./caps.js";
+export {
+  createDrawioEmbed,
+  type DrawioEmbed,
+  type DrawioEmbedFrame,
+  type DrawioEmbedOptions,
+  type DrawioEventMap,
+  type DrawioExportOptions,
+  type DrawioExportResult,
+  type DrawioLoadOptions,
+  type DrawioMessageEvent,
+  type DrawioMessageSource,
+} from "./embed.js";
+export {
+  DiagramsCapError,
+  DiagramsError,
+  type DiagramsErrorCode,
+  DiagramsFormatError,
+  DiagramsModelInvalidError,
+  DiagramsOriginError,
+  DiagramsProtocolError,
+  DiagramsTimeoutError,
+  DiagramsXmlMalformedError,
+  DiagramsXxeError,
+} from "./errors.js";
+export type {
+  DrawioAutosaveEvent,
+  DrawioConfigureAction,
+  DrawioConfigureEvent,
+  DrawioDialogAction,
+  DrawioDraftAction,
+  DrawioErrorEvent,
+  DrawioExitEvent,
+  DrawioExportAction,
+  DrawioExportBounds,
+  DrawioExportEvent,
+  DrawioExportFormat,
+  DrawioFitAction,
+  DrawioInboundEvent,
+  DrawioInitEvent,
+  DrawioLoadAction,
+  DrawioLoadEvent,
+  DrawioMergeAction,
+  DrawioOutboundAction,
+  DrawioPromptAction,
+  DrawioResetEditorAction,
+  DrawioSaveEvent,
+  DrawioSpinnerAction,
+  DrawioStatusAction,
+  DrawioTemplateAction,
+} from "./messages.js";
+export { validateDiagramsOrigin } from "./origin.js";
+export {
+  type DiagramsTelemetry,
+  type DiagramsTelemetryAttributeValue,
+  type DiagramsTelemetrySpan,
+  noopDiagramsSpan,
+  noopDiagramsTelemetry,
+} from "./telemetry.js";
+export {
+  assertNotVisio,
+  type DrawioModelSummary,
+  type DrawioXmlOptions,
+  UNSAFE_XML_DECLARATION_PATTERN,
+  validateDrawioXml,
+} from "./xml.js";

package/work/src/diagrams/messages.ts

@@ -0,0 +1,150 @@
+export type DrawioExportFormat = "xml" | "xmlsvg" | "xmlpng" | "json" | "png" | "svg";
+
+export interface DrawioExportBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+// Inbound Editor-to-Host Events
+export interface DrawioInitEvent {
+  readonly event: "init";
+}
+
+export interface DrawioLoadEvent {
+  readonly event: "load";
+}
+
+export interface DrawioSaveEvent {
+  readonly event: "save";
+  readonly xml: string;
+  readonly exit?: boolean;
+}
+
+export interface DrawioAutosaveEvent {
+  readonly event: "autosave";
+  readonly xml: string;
+}
+
+export interface DrawioExitEvent {
+  readonly event: "exit";
+  readonly modified: boolean;
+}
+
+export interface DrawioConfigureEvent {
+  readonly event: "configure";
+}
+
+export interface DrawioExportEvent {
+  readonly event: "export";
+  readonly format: string;
+  readonly data: string;
+  readonly xml?: string;
+  readonly bounds?: DrawioExportBounds;
+}
+
+export interface DrawioErrorEvent {
+  readonly event: "error";
+  readonly message: string;
+}
+
+export type DrawioInboundEvent =
+  | DrawioInitEvent
+  | DrawioLoadEvent
+  | DrawioSaveEvent
+  | DrawioAutosaveEvent
+  | DrawioExitEvent
+  | DrawioConfigureEvent
+  | DrawioExportEvent
+  | DrawioErrorEvent;
+
+// Outbound Host-to-Editor Actions
+export interface DrawioLoadAction {
+  readonly action: "load";
+  readonly xml: string;
+  readonly autosave?: boolean | 0 | 1;
+  readonly saveAndExit?: boolean | 0 | 1;
+  readonly noSaveBtn?: boolean | 0 | 1;
+  readonly noExitBtn?: boolean | 0 | 1;
+  readonly title?: string;
+}
+
+export interface DrawioConfigureAction {
+  readonly action: "configure";
+  readonly config: Readonly<Record<string, unknown>>;
+}
+
+export interface DrawioExportAction {
+  readonly action: "export";
+  readonly format: DrawioExportFormat;
+  readonly scale?: number;
+  readonly border?: number;
+  readonly xml?: string;
+  readonly embedImages?: boolean;
+}
+
+export interface DrawioMergeAction {
+  readonly action: "merge";
+  readonly xml: string;
+}
+
+export interface DrawioDialogAction {
+  readonly action: "dialog";
+  readonly title: string;
+  readonly message: string;
+  readonly button: string;
+}
+
+export interface DrawioPromptAction {
+  readonly action: "prompt";
+  readonly title: string;
+  readonly defaultValue?: string;
+  readonly ok: string;
+}
+
+export interface DrawioTemplateAction {
+  readonly action: "template";
+  readonly xml?: string;
+  readonly name?: string;
+}
+
+export interface DrawioDraftAction {
+  readonly action: "draft";
+  readonly xml: string;
+  readonly editKey?: string;
+}
+
+export interface DrawioStatusAction {
+  readonly action: "status";
+  readonly message: string;
+  readonly modified?: boolean;
+}
+
+export interface DrawioSpinnerAction {
+  readonly action: "spinner";
+  readonly show: boolean;
+  readonly message?: string;
+}
+
+export interface DrawioFitAction {
+  readonly action: "fit";
+}
+
+export interface DrawioResetEditorAction {
+  readonly action: "resetEditor";
+}
+
+export type DrawioOutboundAction =
+  | DrawioLoadAction
+  | DrawioConfigureAction
+  | DrawioExportAction
+  | DrawioMergeAction
+  | DrawioDialogAction
+  | DrawioPromptAction
+  | DrawioTemplateAction
+  | DrawioDraftAction
+  | DrawioStatusAction
+  | DrawioSpinnerAction
+  | DrawioFitAction
+  | DrawioResetEditorAction;

package/work/src/diagrams/origin.ts

@@ -0,0 +1,52 @@
+import { DiagramsOriginError } from "./errors.js";
+
+/**
+ * Validates and normalizes an origin string for the draw.io embed client.
+ *
+ * Security rules:
+ * - Must be an explicit, non-empty origin string.
+ * - Wildcards ("*") are strictly rejected.
+ * - Must be a valid URL with "https:" or "http:" protocol.
+ * - Must have no path components (no trailing slash), no search query, no hash fragment, and no embedded credentials.
+ * - Returns the exact normalized origin matching url.origin.
+ */
+export function validateDiagramsOrigin(value: unknown): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new DiagramsOriginError("An explicit, non-empty origin string is required to embed draw.io");
+  }
+
+  const trimmed = value.trim();
+  if (trimmed === "*") {
+    throw new DiagramsOriginError('Wildcard origin "*" is prohibited for draw.io embed security');
+  }
+
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new DiagramsOriginError(`Invalid origin URL: "${trimmed}"`);
+  }
+
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new DiagramsOriginError(`Origin must use "https:" or "http:" protocol, received: "${url.protocol}"`);
+  }
+
+  if (url.username || url.password) {
+    throw new DiagramsOriginError("Origin must not contain embedded user credentials");
+  }
+
+  if (url.search || url.hash) {
+    throw new DiagramsOriginError("Origin must not contain query parameters or hash fragments");
+  }
+
+  if (url.pathname !== "" && url.pathname !== "/") {
+    throw new DiagramsOriginError(`Origin must not contain path components, received pathname: "${url.pathname}"`);
+  }
+
+  // Ensure byte-exact match with url.origin (no trailing slash)
+  if (trimmed !== url.origin) {
+    throw new DiagramsOriginError(`Origin must match exact origin format "${url.origin}" (no trailing slashes or paths)`);
+  }
+
+  return url.origin;
+}