@bevel-software/platform-core-frontend 0.11.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/THIRD-PARTY-NOTICES.md +670 -395
  2. package/package.json +6 -2
  3. package/src/lib/__tests__/api.test.ts +95 -0
  4. package/src/lib/api.ts +30 -2
  5. package/src/lib/clipboard.ts +25 -0
  6. package/src/modules/access/__tests__/useFileAccess.test.tsx +47 -0
  7. package/src/modules/access/hooks/useFileAccess.ts +23 -5
  8. package/src/modules/library/utils/clipboard.ts +4 -20
  9. package/src/modules/workspace/components/FileExplorer.tsx +6 -14
  10. package/src/modules/workspace/components/FileViewer.tsx +17 -4
  11. package/src/modules/workspace/components/KbPageHeader.tsx +1 -1
  12. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +3 -1
  13. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +17 -0
  14. package/src/modules/workspace/components/__tests__/KbPageHeader.test.tsx +15 -0
  15. package/src/modules/workspace/components/renderers/DocxRenderer.tsx +11 -2
  16. package/src/modules/workspace/components/renderers/DownloadFileButton.tsx +88 -0
  17. package/src/modules/workspace/components/renderers/EmailRenderer.tsx +309 -0
  18. package/src/modules/workspace/components/renderers/LegacyOfficeRenderer.tsx +60 -0
  19. package/src/modules/workspace/components/renderers/PdfRenderer.tsx +261 -33
  20. package/src/modules/workspace/components/renderers/PptxRenderer.tsx +184 -0
  21. package/src/modules/workspace/components/renderers/XlsxRenderer.tsx +195 -45
  22. package/src/modules/workspace/components/renderers/__tests__/DownloadFileButton.test.tsx +48 -0
  23. package/src/modules/workspace/components/renderers/__tests__/EmailRenderer.test.tsx +176 -0
  24. package/src/modules/workspace/components/renderers/__tests__/PdfRenderer.test.tsx +214 -76
  25. package/src/modules/workspace/components/renderers/__tests__/PptxRenderer.test.tsx +125 -0
  26. package/src/modules/workspace/components/renderers/__tests__/XlsxRenderer.test.tsx +245 -0
  27. package/src/modules/workspace/components/renderers/__tests__/emailBody.test.ts +117 -0
  28. package/src/modules/workspace/components/renderers/__tests__/emailMessage.test.ts +404 -0
  29. package/src/modules/workspace/components/renderers/__tests__/pptxOutline.test.ts +448 -0
  30. package/src/modules/workspace/components/renderers/__tests__/readBodyCapped.test.ts +117 -0
  31. package/src/modules/workspace/components/renderers/__tests__/rendererLayout.test.ts +73 -7
  32. package/src/modules/workspace/components/renderers/__tests__/rendererSelection.test.tsx +107 -0
  33. package/src/modules/workspace/components/renderers/downloadFile.ts +33 -0
  34. package/src/modules/workspace/components/renderers/emailBody.ts +168 -0
  35. package/src/modules/workspace/components/renderers/emailMessage.ts +223 -0
  36. package/src/modules/workspace/components/renderers/emlMessage.ts +91 -0
  37. package/src/modules/workspace/components/renderers/htmlSandbox.ts +9 -2
  38. package/src/modules/workspace/components/renderers/index.ts +82 -6
  39. package/src/modules/workspace/components/renderers/lazyRenderer.tsx +9 -2
  40. package/src/modules/workspace/components/renderers/msgMessage.ts +219 -0
  41. package/src/modules/workspace/components/renderers/pptxOutline.ts +317 -0
  42. package/src/modules/workspace/components/renderers/readBodyCapped.ts +97 -0
  43. package/src/modules/workspace/components/renderers/xmlReading.ts +0 -0
  44. package/src/url-suffix-imports.d.ts +12 -0
@@ -0,0 +1,107 @@
1
+ import { describe, it, expect, vi, beforeEach } from 'vitest';
2
+ import { render, screen } from '@testing-library/react';
3
+ import {
4
+ WorkspaceContext,
5
+ type WorkspaceContextValue,
6
+ } from '../../../state/workspace.context';
7
+
8
+ const apiMock = vi.hoisted(() => ({ authFetch: vi.fn() }));
9
+ vi.mock('../../../../../lib/api', () => ({ authFetch: apiMock.authFetch }));
10
+
11
+ import { getFileRenderer } from '../index';
12
+ import { LegacyOfficeRenderer } from '../LegacyOfficeRenderer';
13
+ import { TextRenderer } from '../TextRenderer';
14
+ import { ImageRenderer } from '../ImageRenderer';
15
+
16
+ /**
17
+ * The extension → renderer routing. The document viewers are code-split, so
18
+ * the map holds anonymous lazy wrappers rather than the components
19
+ * themselves — `lazyRenderer` stamps each wrapper with a
20
+ * `displayName` naming what it loads, and THAT is the identity pinned here.
21
+ * Asserting through the display name keeps this test from importing (and
22
+ * thereby eagerly loading) the heavy chunks the wrappers exist to defer.
23
+ */
24
+ function rendererName(component: unknown): string {
25
+ const c = component as { displayName?: string; name?: string };
26
+ return c.displayName ?? c.name ?? '';
27
+ }
28
+
29
+ describe('getFileRenderer: document routing', () => {
30
+ it.each([
31
+ ['Inbox/brief.pdf', 'LazyRenderer(PDF)'],
32
+ ['Inbox/BRIEF.PDF', 'LazyRenderer(PDF)'],
33
+ ['Data/book.xlsx', 'LazyRenderer(spreadsheet)'],
34
+ ['Inbox/report.docx', 'LazyRenderer(document)'],
35
+ ['Inbox/all-hands.pptx', 'LazyRenderer(presentation)'],
36
+ ['Inbox/offer.eml', 'LazyRenderer(email)'],
37
+ ['Inbox/thread.msg', 'LazyRenderer(email)'],
38
+ ['Inbox/THREAD.MSG', 'LazyRenderer(email)'],
39
+ ])('routes %s to its lazy viewer %s', (path, expected) => {
40
+ expect(rendererName(getFileRenderer(path))).toBe(expected);
41
+ });
42
+
43
+ it.each(['old/memo.doc', 'old/deck.ppt', 'old/sheet.xls', 'old/SHOUTY.DOC'])(
44
+ 'routes the legacy %s to the legacy-format note, never the text fallback',
45
+ (path) => {
46
+ expect(getFileRenderer(path)).toBe(LegacyOfficeRenderer);
47
+ },
48
+ );
49
+
50
+ // The text fallback would print a garbled zip for these — they get the
51
+ // no-preview note (with ODF-honest copy) until a real viewer exists.
52
+ it.each(['docs/spec.odt', 'decks/pitch.odp', 'data/numbers.ods', 'docs/SPEC.ODT'])(
53
+ 'routes the OpenDocument %s to the no-preview note, never the text fallback',
54
+ (path) => {
55
+ expect(getFileRenderer(path)).toBe(LegacyOfficeRenderer);
56
+ },
57
+ );
58
+
59
+ it('keeps the existing routes: unknown extensions fall back to text, images stay images', () => {
60
+ expect(getFileRenderer('notes/scratch.unknown')).toBe(TextRenderer);
61
+ expect(getFileRenderer('pics/logo.png')).toBe(ImageRenderer);
62
+ });
63
+ });
64
+
65
+ describe('LegacyOfficeRenderer', () => {
66
+ beforeEach(() => {
67
+ apiMock.authFetch.mockReset();
68
+ });
69
+
70
+ function renderLegacy(filePath: string) {
71
+ return render(
72
+ <WorkspaceContext.Provider
73
+ value={{ workspaceId: 'ws-1' } as unknown as WorkspaceContextValue}
74
+ >
75
+ <LegacyOfficeRenderer filePath={filePath} content="" onSave={async () => {}} />
76
+ </WorkspaceContext.Provider>,
77
+ );
78
+ }
79
+
80
+ it.each([
81
+ ['old/memo.doc', 'Word', '.docx'],
82
+ ['old/deck.ppt', 'PowerPoint', '.pptx'],
83
+ ['old/sheet.xls', 'Excel', '.xlsx'],
84
+ ])('for %s: names the format, points at %s → %s, and offers Download', (path, label, modern) => {
85
+ renderLegacy(path);
86
+ const note = screen.getByText(/legacy .* format/);
87
+ expect(note.textContent).toContain(label);
88
+ expect(note.textContent).toContain(modern);
89
+ expect(screen.getByRole('button', { name: /Download/ })).toBeInTheDocument();
90
+ // A note, not a parse attempt: nothing was fetched.
91
+ expect(apiMock.authFetch).not.toHaveBeenCalled();
92
+ });
93
+
94
+ it.each([
95
+ ['docs/spec.odt', 'text document'],
96
+ ['decks/pitch.odp', 'presentation'],
97
+ ['data/numbers.ods', 'spreadsheet'],
98
+ ])('for the OpenDocument %s: says no preview YET and offers Download — never a convert hint (agents read these fine)', (path, kind) => {
99
+ renderLegacy(path);
100
+ const note = screen.getByText(/No preview for OpenDocument files yet/);
101
+ expect(note.textContent).toContain(kind);
102
+ expect(note.textContent).toContain('Download the file to view it');
103
+ expect(note.textContent).not.toMatch(/[Cc]onvert/);
104
+ expect(screen.getByRole('button', { name: /Download/ })).toBeInTheDocument();
105
+ expect(apiMock.authFetch).not.toHaveBeenCalled();
106
+ });
107
+ });
@@ -0,0 +1,33 @@
1
+ import { authFetch } from '../../../../lib/api';
2
+
3
+ /** What an authenticated blob download came back with. Network errors THROW — callers already catch. */
4
+ export type DownloadOutcome = { ok: true } | { ok: false; status: number; body: string };
5
+
6
+ /**
7
+ * The one authenticated blob-download path, shared by `DownloadFileButton`
8
+ * and the file tree's context-menu Download (`FileExplorer.handleDownload`):
9
+ * fetch with auth → blob → synthetic `<a download>` click → DEFERRED
10
+ * `revokeObjectURL`. The revoke is deferred via `setTimeout(…, 0)` because
11
+ * revoking synchronously after `click()` can invalidate the blob URL before
12
+ * the browser has actually begun the navigation the click started — the
13
+ * download silently never happens on the affected engines.
14
+ *
15
+ * On a non-OK response the outcome carries the status and (best-effort) body
16
+ * so each caller keeps its own error copy; nothing is downloaded.
17
+ */
18
+ export async function downloadViaBlob(url: string, fileName: string): Promise<DownloadOutcome> {
19
+ const res = await authFetch(url);
20
+ if (!res.ok) {
21
+ return { ok: false, status: res.status, body: await res.text().catch(() => '') };
22
+ }
23
+ const blob = await res.blob();
24
+ const blobUrl = URL.createObjectURL(blob);
25
+ const a = document.createElement('a');
26
+ a.href = blobUrl;
27
+ a.download = fileName;
28
+ document.body.appendChild(a);
29
+ a.click();
30
+ a.remove();
31
+ window.setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
32
+ return { ok: true };
33
+ }
@@ -0,0 +1,168 @@
1
+ import { buildSandboxedHtml, sanitizeAgentHtml } from './htmlSandbox';
2
+ import type { EmailAttachmentView } from './emailMessage';
3
+
4
+ /**
5
+ * Turn a message's HTML body into something safe to SHOW.
6
+ *
7
+ * The threat model for an email body is not the one for agent-authored HTML,
8
+ * and it is worth stating because it decides every rule below. A message comes
9
+ * from outside: the sender chose its markup, and two of the things a sender
10
+ * may want are hostile to the reader.
11
+ *
12
+ * - SCRIPT. Never runs. The frame is mounted `sandbox=""` — not
13
+ * `allow-scripts` like the agent-HTML renderer — so nothing in the message
14
+ * executes, and the CSP's `script-src` is moot rather than load-bearing.
15
+ * - THE TRACKING PIXEL. A remote image is a beacon: fetching it tells the
16
+ * sender the message was opened, when, from which address. `img-src data:`
17
+ * forbids every remote fetch, so the message renders without ever telling
18
+ * its sender it was read. Images the sender EMBEDDED (referenced `cid:`,
19
+ * carried in the file itself) are rewritten to `data:` URIs and do render —
20
+ * that is the fidelity worth having, and it costs no network at all.
21
+ *
22
+ * Links are the third case, and they get a different answer. A click cannot be
23
+ * intercepted inside a script-free frame, so a live anchor would open its
24
+ * destination with no chance to show the reader where it goes. Every anchor is
25
+ * therefore made INERT and numbered, and its URL is handed back in `links` for
26
+ * the parent to render in trusted UI — where the reader sees the whole address
27
+ * before anything opens. Reverse-tabnabbing and referrer leakage stop being
28
+ * possible rather than being mitigated.
29
+ */
30
+
31
+ /** One link found in the body, numbered as the rendering marks it. */
32
+ export interface EmailLink {
33
+ /** 1-based, matching the `[n]` marker shown after the link text. */
34
+ index: number;
35
+ /** The link's own text, trimmed and bounded. */
36
+ text: string;
37
+ /** Its full destination, exactly as written. */
38
+ url: string;
39
+ }
40
+
41
+ export interface EmailBodyDocument {
42
+ /** A complete document for `<iframe srcDoc>`; makes zero network requests. */
43
+ srcDoc: string;
44
+ /** Every link the body carried, in document order. */
45
+ links: EmailLink[];
46
+ /** How many images were dropped for pointing somewhere REMOTE. */
47
+ blockedRemoteImages: number;
48
+ /**
49
+ * How many images the sender EMBEDDED but this viewer could not draw — the
50
+ * part was missing from the file, or past the inline budget. Counted apart
51
+ * from remote ones because the honest sentence differs: nothing was withheld
52
+ * to protect the reader, the picture simply is not available.
53
+ */
54
+ unavailableInlineImages: number;
55
+ }
56
+
57
+ /** Schemes a link may name. Anything else is not shown as a link at all. */
58
+ const PRESENTABLE_SCHEMES = /^(https?|mailto):/i;
59
+
60
+ /** Elements that never belong in a rendered message, whatever the sender meant. */
61
+ const DROP = ['script', 'form', 'input', 'button', 'select', 'textarea', 'object', 'embed', 'iframe', 'link', 'meta', 'base'];
62
+
63
+ /** Longest link text kept for the panel — a whole paragraph inside an anchor is not a label. */
64
+ const MAX_LINK_TEXT = 200;
65
+
66
+ /** `data:` URI for an inline part, or undefined when its bytes were not retained. */
67
+ function dataUri(part: EmailAttachmentView): string | undefined {
68
+ if (!part.bytes || part.bytes.length === 0) return undefined;
69
+ let binary = '';
70
+ // Chunked: `String.fromCharCode(...bytes)` on a multi-megabyte part exceeds
71
+ // the argument limit and throws.
72
+ for (let i = 0; i < part.bytes.length; i += 0x8000) {
73
+ binary += String.fromCharCode(...part.bytes.subarray(i, i + 0x8000));
74
+ }
75
+ return `data:${part.mimeType ?? 'application/octet-stream'};base64,${btoa(binary)}`;
76
+ }
77
+
78
+ /** The `cid:` value an `<img src>` names, lowercased and unbracketed. */
79
+ function contentIdOf(src: string): string | undefined {
80
+ const trimmed = src.trim();
81
+ if (!/^cid:/i.test(trimmed)) return undefined;
82
+ return trimmed.slice(4).replace(/^<|>$/g, '').toLowerCase();
83
+ }
84
+
85
+ export function buildEmailBody(html: string, attachments: readonly EmailAttachmentView[]): EmailBodyDocument {
86
+ const doc = new DOMParser().parseFromString(html, 'text/html');
87
+
88
+ const inlineByCid = new Map<string, EmailAttachmentView>();
89
+ for (const part of attachments) {
90
+ if (part.contentId && part.bytes) inlineByCid.set(part.contentId.toLowerCase(), part);
91
+ }
92
+
93
+ // Images: the sender's own parts become data: URIs, everything remote goes.
94
+ let blockedRemoteImages = 0;
95
+ let unavailableInlineImages = 0;
96
+ for (const img of Array.from(doc.querySelectorAll('img'))) {
97
+ const src = img.getAttribute('src') ?? '';
98
+ const cid = contentIdOf(src);
99
+ if (cid !== undefined) {
100
+ const uri = inlineByCid.get(cid) && dataUri(inlineByCid.get(cid) as EmailAttachmentView);
101
+ if (uri !== undefined) {
102
+ img.setAttribute('src', uri);
103
+ continue;
104
+ }
105
+ // Named a part this message does not carry, or one whose bytes the
106
+ // inline budget declined to hold.
107
+ img.remove();
108
+ unavailableInlineImages += 1;
109
+ continue;
110
+ }
111
+ if (src.trim().toLowerCase().startsWith('data:image/')) {
112
+ continue; // already inline
113
+ }
114
+ img.remove();
115
+ blockedRemoteImages += 1;
116
+ }
117
+
118
+ // Links: inert, numbered, and reported to the caller.
119
+ const links: EmailLink[] = [];
120
+ for (const anchor of Array.from(doc.querySelectorAll('a'))) {
121
+ const href = (anchor.getAttribute('href') ?? '').trim();
122
+ // Removed whatever it says: the sanitizer would strip it anyway, and an
123
+ // anchor with no href cannot be followed even if a future change to the
124
+ // frame's sandbox let it try.
125
+ anchor.removeAttribute('href');
126
+ anchor.removeAttribute('target');
127
+ if (!PRESENTABLE_SCHEMES.test(href)) continue;
128
+ const index = links.length + 1;
129
+ links.push({ index, text: (anchor.textContent ?? '').trim().slice(0, MAX_LINK_TEXT), url: href });
130
+ const marker = doc.createElement('sup');
131
+ marker.textContent = `[${index}]`;
132
+ anchor.after(marker);
133
+ }
134
+
135
+ for (const tag of DROP) {
136
+ for (const el of Array.from(doc.querySelectorAll(tag))) el.remove();
137
+ }
138
+
139
+ // Event handlers go too. The shared sanitizer keeps them ON PURPOSE — it
140
+ // serves agent HTML, which is allowed to run its own scripts — and the frame
141
+ // here forbids scripts outright, so an `onerror` could not fire. Removing
142
+ // them anyway means the document does not merely fail to execute an attack;
143
+ // it does not carry one.
144
+ for (const el of Array.from(doc.querySelectorAll('*'))) {
145
+ for (const attr of Array.from(el.attributes)) {
146
+ if (attr.name.toLowerCase().startsWith('on')) el.removeAttribute(attr.name);
147
+ }
148
+ }
149
+
150
+ return {
151
+ // Through the shared sanitizer as well: it enforces the URL policy this
152
+ // function relies on (`data:image/` and nothing else) and strips event
153
+ // handlers, so a gap here cannot become a rendered attack.
154
+ srcDoc: buildSandboxedHtml({
155
+ title: 'Message',
156
+ libModuleSources: [],
157
+ includeRuntime: false,
158
+ // The WHOLE document, not `body.innerHTML`: mail routinely puts its CSS
159
+ // in `<head><style>`, and the sanitizer hoists that into the body before
160
+ // serializing. Passing the body alone silently dropped the styling of
161
+ // every message written the ordinary way.
162
+ bodyHtml: sanitizeAgentHtml(doc.documentElement.outerHTML),
163
+ }),
164
+ links,
165
+ blockedRemoteImages,
166
+ unavailableInlineImages,
167
+ };
168
+ }
@@ -0,0 +1,223 @@
1
+ import { Parser } from 'htmlparser2';
2
+
3
+ /**
4
+ * The shared view model + text helpers for the email viewer (`EmailRenderer`),
5
+ * the browser twin of the backend's `email-text.ts` — the same honest story
6
+ * agents get through `read_file`: headers as labelled fields, the body as
7
+ * text (`body` — the text part preferred, an HTML body stripped to text) plus
8
+ * the sender's own HTML when there is one (`bodyHtml`), attachments listed by
9
+ * name. `body` is what an agent reads through `read_file`; the viewer renders
10
+ * `bodyHtml` in a sandbox that can neither run a script nor fetch a byte (see
11
+ * `emailBody.ts`), so a human sees the message and an agent reads the same
12
+ * message, without either being handed live markup. Parsers: `emlMessage.ts` (postal-mime) and `msgMessage.ts` (CFB via
13
+ * SheetJS) fill this model; the renderer never sees a format.
14
+ */
15
+
16
+ export interface EmailAttachmentView {
17
+ name: string;
18
+ mimeType?: string;
19
+ sizeBytes?: number;
20
+ /**
21
+ * The attachment's Content-ID with its angle brackets removed, when the
22
+ * message gave it one. An HTML body references such a part as `cid:<id>`,
23
+ * which is how a sender embeds a picture IN the message rather than linking
24
+ * to one on their server.
25
+ */
26
+ contentId?: string;
27
+ /**
28
+ * Raw bytes — retained ONLY for a part small enough to inline and referenced
29
+ * by Content-ID, because that is the only thing the viewer renders from
30
+ * bytes. An ordinary 40 MB attachment is described, never held.
31
+ */
32
+ bytes?: Uint8Array;
33
+ }
34
+
35
+ /** Bounds on what may be held in memory for inline rendering. */
36
+ export const MAX_INLINE_IMAGE_BYTES = 4 * 1024 * 1024;
37
+ export const MAX_INLINE_IMAGE_TOTAL_BYTES = 16 * 1024 * 1024;
38
+
39
+ /**
40
+ * Should this part's bytes be kept for inline rendering? Only a Content-ID'd
41
+ * image within bounds: everything else is listed by name and nothing more.
42
+ */
43
+ export function isInlineImagePart(mimeType: string | undefined, contentId: string | undefined, size: number): boolean {
44
+ return (
45
+ contentId !== undefined &&
46
+ contentId !== '' &&
47
+ (mimeType ?? '').toLowerCase().startsWith('image/') &&
48
+ size > 0 &&
49
+ size <= MAX_INLINE_IMAGE_BYTES
50
+ );
51
+ }
52
+
53
+ /** The Content-IDs an HTML body actually references as `cid:…`, lowercased. */
54
+ export function referencedContentIds(html: string | undefined): Set<string> {
55
+ const out = new Set<string>();
56
+ if (html === undefined) return out;
57
+ // The delimiter before `cid:` is a quote or `(` (url(...)), then optional
58
+ // whitespace. Both escapes matter: written unescaped, `\s` is a literal `s`
59
+ // — the class stops excluding whitespace and starts excluding the LETTER,
60
+ // truncating `photos@x` to `photo` and failing outright on an id that starts
61
+ // with one.
62
+ for (const m of html.matchAll(/["'(]\s*cid:([^"')\s>]+)/gi)) {
63
+ out.add(m[1].replace(/^<|>$/g, '').toLowerCase());
64
+ }
65
+ return out;
66
+ }
67
+
68
+ /**
69
+ * Drop retained bytes past the aggregate inline budget. Shared by both parsers
70
+ * so the rule cannot drift between `.eml` and `.msg`.
71
+ *
72
+ * Parts the body REFERENCES are considered first, whatever their order in the
73
+ * file: a message may carry inline images it never shows, and spending the
74
+ * budget on those in document order left the picture the reader was actually
75
+ * meant to see undrawn while an unreferenced one sat in memory.
76
+ */
77
+ export function inlineBudgeted(
78
+ parts: EmailAttachmentView[],
79
+ referenced: Set<string>,
80
+ ): EmailAttachmentView[] {
81
+ const order = parts
82
+ .map((part, index) => ({ index, shown: referenced.has((part.contentId ?? '').toLowerCase()) }))
83
+ .sort((a, b) => Number(b.shown) - Number(a.shown) || a.index - b.index);
84
+ const keep = new Set<number>();
85
+ let held = 0;
86
+ for (const { index } of order) {
87
+ const bytes = parts[index].bytes;
88
+ if (bytes === undefined) continue;
89
+ if (held + bytes.byteLength > MAX_INLINE_IMAGE_TOTAL_BYTES) continue;
90
+ held += bytes.byteLength;
91
+ keep.add(index);
92
+ }
93
+ return parts.map((part, index) =>
94
+ part.bytes !== undefined && !keep.has(index) ? { ...part, bytes: undefined } : part,
95
+ );
96
+ }
97
+
98
+ /** Where the body text came from — drives the honest notes in the viewer. */
99
+ export type EmailBodySource = 'text' | 'html' | 'rtf-only' | 'none';
100
+
101
+ export interface EmailMessageView {
102
+ from?: string;
103
+ to?: string;
104
+ cc?: string;
105
+ bcc?: string;
106
+ subject?: string;
107
+ /** ISO timestamp when the date parsed, the raw header value otherwise. */
108
+ date?: string;
109
+ /** Plain-text body ('' when there is none, or it exists only as RTF). */
110
+ body: string;
111
+ /**
112
+ * The HTML body as the sender wrote it, when there is one. The viewer
113
+ * renders this in a sandbox; `body` remains the text an agent reads, so the
114
+ * two surfaces never disagree about what the message SAYS.
115
+ */
116
+ bodyHtml?: string;
117
+ bodySource: EmailBodySource;
118
+ attachments: EmailAttachmentView[];
119
+ }
120
+
121
+ /** The 50 MB raw-size bound the backend extractors apply — mirrored client-side. */
122
+ export const MAX_EMAIL_BYTES = 50 * 1024 * 1024;
123
+
124
+ /**
125
+ * Strip an HTML email body to plain text — the same pass as the backend's
126
+ * `email-text.ts`, so the viewer and `read_file` agree about what a message
127
+ * says: `<style>`/`<script>`/`<head>`/`<title>` dropped whole, `<br>` and
128
+ * block-tag boundaries become newlines, entities decoded, runs of blank lines
129
+ * collapsed to one.
130
+ *
131
+ * Parsing is `htmlparser2` in HTML mode, because an email body IS html — with
132
+ * its void elements, its implied closes, its raw-text `<script>` and its named
133
+ * entities — and because the hand-rolled strip this replaced had to be taught
134
+ * those rules one crafted message at a time, in a tab the reader cannot close
135
+ * while its main thread is pinned.
136
+ */
137
+ const CONTAINER_TAGS = new Set(['script', 'style', 'head', 'title']);
138
+ const BLOCK_TAGS = new Set([
139
+ 'p', 'div', 'section', 'article', 'header', 'footer', 'main',
140
+ 'table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th',
141
+ 'li', 'ul', 'ol', 'dl', 'dt', 'dd', 'blockquote', 'pre', 'hr',
142
+ 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
143
+ ]);
144
+
145
+ /**
146
+ * How deep the element stack may go before the strip gives up on the rest of
147
+ * the body. Mail nests a few dozen levels even at its most table-happy; a
148
+ * crafted body can nest as deep as it has bytes, and the parser holds a stack
149
+ * entry per open element. What was read before the bound is kept.
150
+ */
151
+ const MAX_ELEMENT_DEPTH = 1_000;
152
+
153
+ /** Thrown to stop the parse at {@link MAX_ELEMENT_DEPTH}; never leaves this module. */
154
+ const TOO_DEEP = Symbol('too deep');
155
+
156
+ export function htmlToEmailText(html: string): string {
157
+ let s = '';
158
+ let depth = 0;
159
+ let skipping = 0; // inside a container whose content is not body text
160
+ const parser = new Parser(
161
+ {
162
+ onopentag(name) {
163
+ depth++;
164
+ if (CONTAINER_TAGS.has(name)) skipping++;
165
+ else if (name === 'br' || BLOCK_TAGS.has(name)) s += '\n';
166
+ if (depth > MAX_ELEMENT_DEPTH) throw TOO_DEEP;
167
+ },
168
+ ontext(text) {
169
+ if (skipping === 0) s += text;
170
+ },
171
+ onclosetag(name) {
172
+ if (CONTAINER_TAGS.has(name)) {
173
+ if (skipping > 0) skipping--;
174
+ } else if (BLOCK_TAGS.has(name)) s += '\n';
175
+ depth--;
176
+ },
177
+ },
178
+ { decodeEntities: true },
179
+ );
180
+ try {
181
+ parser.write(html);
182
+ parser.end();
183
+ } catch (err) {
184
+ if (err !== TOO_DEEP) throw err;
185
+ parser.reset();
186
+ }
187
+
188
+ // `&nbsp;` decodes to U+00A0, which LOOKS like a space and is not one — a
189
+ // reader searching the message for "one two" would miss a line that reads
190
+ // exactly that.
191
+ const out: string[] = [];
192
+ const NBSP = /\u00a0/g;
193
+ for (const raw of s.replace(NBSP, ' ').split('\n')) {
194
+ const line = raw.trim();
195
+ if (line !== '') out.push(line);
196
+ else if (out.length > 0 && out[out.length - 1] !== '') out.push('');
197
+ }
198
+ while (out.length > 0 && out[out.length - 1] === '') out.pop();
199
+ return out.join('\n');
200
+ }
201
+
202
+ /** `Name <addr>` / `Name` / `addr` — whatever the message carries. */
203
+ export function mailboxText(name: string | undefined, address: string | undefined): string | undefined {
204
+ const n = name?.trim() ?? '';
205
+ const a = address?.trim() ?? '';
206
+ if (n !== '' && a !== '' && n !== a) return `${n} <${a}>`;
207
+ if (a !== '') return a;
208
+ return n !== '' ? n : undefined;
209
+ }
210
+
211
+ /** `name (mimeType, N bytes)` with the parenthesis dropped when nothing is known. */
212
+ export function attachmentLine(a: EmailAttachmentView): string {
213
+ const details = [a.mimeType, a.sizeBytes !== undefined ? `${a.sizeBytes} bytes` : undefined]
214
+ .filter((d): d is string => d !== undefined && d !== '')
215
+ .join(', ');
216
+ return details === '' ? a.name : `${a.name} (${details})`;
217
+ }
218
+
219
+ /** Normalize a date header/property to ISO; keep the raw value when unparseable. */
220
+ export function isoDate(value: string): string {
221
+ const d = new Date(value);
222
+ return Number.isNaN(d.getTime()) ? value : d.toISOString();
223
+ }
@@ -0,0 +1,91 @@
1
+ import PostalMime from 'postal-mime';
2
+ import type { Address, Email } from 'postal-mime';
3
+ import {
4
+ MAX_EMAIL_BYTES,
5
+ htmlToEmailText,
6
+ inlineBudgeted,
7
+ isInlineImagePart,
8
+ isoDate,
9
+ referencedContentIds,
10
+ type EmailAttachmentView,
11
+ type EmailMessageView,
12
+ } from './emailMessage';
13
+
14
+ /**
15
+ * Client-side `.eml` → `EmailMessageView`, on the SAME parser the backend
16
+ * extractor uses (`postal-mime` — pure ESM, dependency-free, runs in the
17
+ * browser unchanged), so viewer and agent read one message the same way.
18
+ *
19
+ * Throws an `Error` whose message reads "could not be parsed as a .eml (…)"
20
+ * — the caller shows it verbatim — for over-bound files and for bytes that
21
+ * yield no email headers at all (postal-mime itself is lenient and would
22
+ * "parse" random bytes to an empty message).
23
+ */
24
+ export async function parseEmlMessage(bytes: ArrayBuffer): Promise<EmailMessageView> {
25
+ if (bytes.byteLength > MAX_EMAIL_BYTES) {
26
+ throw new Error(
27
+ `could not be parsed as a .eml (the file is ${bytes.byteLength} bytes — over the 50 MB limit)`,
28
+ );
29
+ }
30
+ let email: Email;
31
+ try {
32
+ email = await PostalMime.parse(new Uint8Array(bytes));
33
+ } catch (err) {
34
+ throw new Error(`could not be parsed as a .eml (${(err as Error).message})`);
35
+ }
36
+ if (
37
+ email.from === undefined &&
38
+ email.to === undefined &&
39
+ email.cc === undefined &&
40
+ email.bcc === undefined &&
41
+ email.subject === undefined &&
42
+ email.date === undefined &&
43
+ email.messageId === undefined &&
44
+ email.attachments.length === 0
45
+ ) {
46
+ throw new Error('could not be parsed as a .eml (no email headers found)');
47
+ }
48
+ const text = email.text !== undefined && email.text.trim() !== '' ? email.text : undefined;
49
+ const html = email.html !== undefined && email.html.trim() !== '' ? email.html : undefined;
50
+ const body = text ?? (html !== undefined ? htmlToEmailText(html) : '');
51
+ return {
52
+ from: email.from && addressListText([email.from]),
53
+ to: email.to && addressListText(email.to),
54
+ cc: email.cc && addressListText(email.cc),
55
+ bcc: email.bcc && addressListText(email.bcc),
56
+ subject: email.subject,
57
+ date: email.date !== undefined ? isoDate(email.date) : undefined,
58
+ body: body.replace(/\s+$/, ''),
59
+ bodyHtml: html,
60
+ bodySource: text !== undefined ? 'text' : html !== undefined ? 'html' : 'none',
61
+ attachments: inlineBudgeted(
62
+ email.attachments.map((a): EmailAttachmentView => {
63
+ const bytes =
64
+ typeof a.content === 'string' ? new TextEncoder().encode(a.content) : new Uint8Array(a.content);
65
+ // postal-mime keeps the angle brackets: `<abc@host>`.
66
+ const contentId = a.contentId?.replace(/^<|>$/g, '');
67
+ return {
68
+ name: a.filename ?? 'unnamed attachment',
69
+ mimeType: a.mimeType,
70
+ sizeBytes: bytes.byteLength,
71
+ contentId,
72
+ bytes: isInlineImagePart(a.mimeType, contentId, bytes.byteLength) ? bytes : undefined,
73
+ };
74
+ }),
75
+ referencedContentIds(html),
76
+ ),
77
+ };
78
+ }
79
+
80
+ /** `Name <addr>, addr2, Group: member, member` — groups flattened inline. */
81
+ function addressListText(list: Address[]): string | undefined {
82
+ const s = list
83
+ .map(function one(a: Address): string {
84
+ if (a.group !== undefined) return `${a.name}: ${a.group.map(one).join(', ')}`;
85
+ if (a.address === undefined || a.address === '') return a.name;
86
+ return a.name !== '' && a.name !== a.address ? `${a.name} <${a.address}>` : a.address;
87
+ })
88
+ .filter((t) => t !== '')
89
+ .join(', ');
90
+ return s === '' ? undefined : s;
91
+ }
@@ -281,6 +281,13 @@ interface BuildSandboxedHtmlOptions {
281
281
  title: string;
282
282
  /** knowledge-base JS library files, in dependency order. */
283
283
  libModuleSources: string[];
284
+ /**
285
+ * Emit the runtime (library + nav bridge)? The EMAIL viewer passes false:
286
+ * its frame is mounted `sandbox=""`, so a script could never run, and
287
+ * shipping one anyway leaves dead code in a document whose whole claim is
288
+ * that it executes nothing.
289
+ */
290
+ includeRuntime?: boolean;
284
291
  /** Sanitized agent HTML, body content only. */
285
292
  bodyHtml: string;
286
293
  }
@@ -323,9 +330,9 @@ export function buildSandboxedHtml(opts: BuildSandboxedHtmlOptions): string {
323
330
  <title>${safeTitle}</title>
324
331
  </head>
325
332
  <body>
326
- <script type="module">
333
+ ${opts.includeRuntime === false ? '' : `<script type="module">
327
334
  ${inlineLib}
328
- </script>
335
+ </script>`}
329
336
  ${opts.bodyHtml}
330
337
  </body>
331
338
  </html>`;