) => Object.assign(state, p);
+ return { useTemplateStore: hook };
+});
+
+// ─── Misc dependency mocks ────────────────────────────────────────────────────
+
+vi.mock('@/stores/toast-store', () => ({
+ toast: { info: () => {}, error: () => {}, success: () => {} },
+}));
+
+vi.mock('@/lib/plugin-hooks', () => ({
+ identityHooks: {
+ onSignatureRender: { size: 0, transform: async (value: unknown) => value },
+ onIdentitySelect: { size: 0, emit: async () => {} },
+ },
+ templateHooks: {
+ onTemplateRender: { size: 0, transform: async (value: unknown) => value },
+ onTemplateApply: { size: 0, emit: async () => {} },
+ },
+ emailHooks: {
+ onComposerOpen: { call: async () => [] },
+ onRecipientChange: { call: async () => [] },
+ getRecipientSuggestions: { call: async () => [] },
+ onRecipientChipsChange: { transform: async (chips: unknown) => chips },
+ onDraftChange: { emit: () => {} },
+ onBeforeDraftAutoSave: { transform: async (draft: unknown) => draft },
+ onBeforeEmailSend: { intercept: async () => true, interceptOutcome: async () => 'allowed' },
+ onComposeSend: { takeOver: async () => 'default' },
+ onTransformOutgoingEmail: { transform: async (email: unknown) => email },
+ },
+ contactHooks: {
+ search: { call: async () => [] },
+ onProvideRecipientSuggestions: { transform: async (initial: unknown) => initial },
+ },
+}));
+
+vi.mock('@/lib/email-sanitization', () => ({
+ sanitizeSignatureHtml: (v: string) => v,
+ sanitizeSignatureHtmlForDisplay: (v: string) => v,
+ sanitizeEmailHtml: (v: string) => v,
+ sanitizePluginBodyHtml: (v: string) => v,
+ escapeHtml: (v: string) => v,
+ parseHtmlSafely: (html: string) => new DOMParser().parseFromString(html, 'text/html'),
+}));
+
+vi.mock('@/lib/email-threading', () => ({
+ computeReplyThreadingHeaders: () => ({ inReplyTo: [], references: [] }),
+}));
+vi.mock('@/lib/sub-addressing', () => ({ generateSubAddress: () => '' }));
+vi.mock('@/lib/debug', () => ({ debug: { log: () => {}, warn: () => {}, error: () => {} } }));
+vi.mock('@/components/email/quoted-html', () => ({
+ buildQuotedHtmlBlock: () => '',
+ serializeEditorContent: () => '',
+}));
+vi.mock('@/lib/template-utils', () => ({ substitutePlaceholders: (s: string) => s }));
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+// Features add to every send through lib/outgoing/send-pipeline.ts: a check
+// can stop it, a finaliser changes what goes out. Both run in the composer's
+// send, after its own checks.
+
+const DRAFT = {
+ to: 'bob@example.com',
+ cc: 'carol@example.com',
+ bcc: '',
+ subject: 'Hello',
+ body: 'Hi
',
+ showCc: true,
+ showBcc: false,
+ selectedIdentityId: 'id-me',
+ subAddressTag: '',
+ mode: 'compose' as const,
+ draftId: null,
+};
+
+function clickSend() {
+ fireEvent.click(screen.getAllByTestId('composer-send')[0]);
+}
+
+describe('composer send pipeline', () => {
+ beforeEach(() => resetSendPipeline());
+ afterEach(() => {
+ resetSendPipeline();
+ vi.clearAllMocks();
+ });
+
+ it('sends what the finalisers return, with the recipients in the context', async () => {
+ const seen: unknown[] = [];
+ registerOutgoingFinalizer('footer', 10, (bodies, context) => {
+ seen.push(context);
+ return { html: `${bodies.html}Footer
`, text: `${bodies.text}\n\nFooter` };
+ });
+ const onSend = vi.fn();
+ render(Footer<\/p>$/);
+ expect(sent.body).toMatch(/\n\nFooter$/);
+ expect(seen).toEqual([expect.objectContaining({
+ surface: 'composer', to: ['bob@example.com'], cc: ['carol@example.com'], fromEmail: 'me@example.com', mode: 'compose', plainText: false,
+ })]);
+ });
+
+ it('sends nothing when a check says no, and sends after it says yes', async () => {
+ let allow = false;
+ const check = vi.fn(() => allow);
+ registerPreSendCheck('ask', 10, check);
+ const onSend = vi.fn();
+ render(
${rewritten!.html}
${buildSignatureHtml()}`;
+ // What the send-pipeline finalisers add (disclaimer, organisation
+ // signature) goes in here, on the send only: drafts never get it.
+ const { html: finalHtmlBody, text: finalBody } = finalizeOutgoing({
+ html: plainTextMode ? undefined : `${rewritten!.html}
${buildSignatureHtml()}`,
+ text: builtTextBody,
+ }, outgoingContext);
const inlineAttachments = rewritten?.attachments ?? [];
try {
diff --git a/components/mail/mail-app.tsx b/components/mail/mail-app.tsx
index bbd5971b7..e5bfaf3c9 100644
--- a/components/mail/mail-app.tsx
+++ b/components/mail/mail-app.tsx
@@ -112,7 +112,7 @@ import { FilePreviewModal } from "@/components/files/file-preview-modal";
import { WopiEditor } from "@/components/files/wopi-editor";
import { useWopiStatus, canWopiOpen } from "@/hooks/use-wopi-status";
import { isFilePreviewable } from "@/lib/file-preview";
-import { appendHtmlSignature, appendPlainTextSignature } from "@/lib/signature-utils";
+import { prepareQuickReply } from "@/lib/outgoing/quick-reply";
import { computeReplyThreadingHeaders } from "@/lib/email-threading";
import { EML_IMPORT_ACCEPT, expandImportableEmails } from "@/lib/eml-import";
import { findDraftIdentityId, findReplyIdentityId, resolveComposeAccountEmail } from "@/lib/reply-identity";
@@ -3900,21 +3900,18 @@ export function MailApp({ linkSegments: routeSegments }: MailAppProps = {}) {
const signatureIdentity = (sendingIdentity?.htmlSignature || sendingIdentity?.textSignature)
? sendingIdentity
: primaryIdentity;
- const separator = useSettingsStore.getState().signatureSeparatorEnabled;
- const finalBody = appendPlainTextSignature(body, signatureIdentity, { separator });
-
- // When the identity has an HTML signature, send a matching HTML body so the
- // signature keeps its formatting; appendPlainTextSignature would otherwise
- // flatten it to plain text. Text-only identities keep the plain-text-only
- // behavior (htmlBody stays undefined).
- const escapedBody = body
- .replace(/&/g, '&')
- .replace(//g, '>')
- .replace(/\n/g, '${escapedBody}
`, signatureIdentity, { separator })
- : undefined;
+ // The same checks and finalisers as the composer's send
+ // (lib/outgoing/send-pipeline.ts): a quick reply is no way around them.
+ const prepared = await prepareQuickReply({
+ body,
+ signatureIdentity,
+ separator: useSettingsStore.getState().signatureSeparatorEnabled,
+ to: recipients,
+ fromEmail: headerFromEmail,
+ identityId: sendingIdentity?.id,
+ });
+ if (!prepared) return;
+ const { html: finalHtmlBody, text: finalBody } = prepared;
const originalEmailId = selectedEmail.id;
const originalSource = emailWriteSource(selectedEmail, client);
diff --git a/lib/outgoing/__tests__/quick-reply.test.ts b/lib/outgoing/__tests__/quick-reply.test.ts
new file mode 100644
index 000000000..834082a6b
--- /dev/null
+++ b/lib/outgoing/__tests__/quick-reply.test.ts
@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { prepareQuickReply } from '@/lib/outgoing/quick-reply';
+import { registerOutgoingFinalizer, registerPreSendCheck, resetSendPipeline } from '@/lib/outgoing/send-pipeline';
+import type { Identity } from '@/lib/jmap/types';
+
+vi.mock('@/lib/debug', () => ({ debug: { log: () => {}, warn: () => {}, error: () => {} } }));
+
+// Quick reply goes through the same checks and finalisers as the composer,
+// so the disclaimer and the external-recipient confirm reach it too.
+
+const html = { id: 'i', name: 'Me', email: 'me@example.com', htmlSignature: 'Me ', textSignature: '' } as Identity;
+const text = { id: 'i', name: 'Me', email: 'me@example.com', htmlSignature: '', textSignature: 'Me' } as Identity;
+const input = (signatureIdentity: Identity) => ({
+ body: 'Thanks <3', signatureIdentity, separator: true, to: ['bob@example.com'], fromEmail: 'me@example.com', identityId: 'i',
+});
+
+afterEach(() => resetSendPipeline());
+
+describe('prepareQuickReply', () => {
+ it('builds the text and, for an HTML signature, an escaped HTML body', async () => {
+ const withHtml = await prepareQuickReply(input(html));
+ expect(withHtml?.html).toContain('Thanks <3
');
+ expect(withHtml?.html).toContain('Me ');
+ expect(withHtml?.text).toContain('Thanks <3');
+ const plain = await prepareQuickReply(input(text));
+ expect(plain?.html).toBeUndefined();
+ expect(plain?.text).toMatch(/Thanks <3[\s\S]*-- \nMe$/);
+ });
+
+ it('runs the finalisers with a reply context', async () => {
+ const contexts: unknown[] = [];
+ registerOutgoingFinalizer('f', 10, (bodies, context) => {
+ contexts.push(context);
+ return { html: bodies.html, text: `${bodies.text}\nFooter` };
+ });
+ const out = await prepareQuickReply(input(text));
+ expect(out?.text).toMatch(/\nFooter$/);
+ expect(contexts).toEqual([expect.objectContaining({ surface: 'quick-reply', mode: 'reply', to: ['bob@example.com'], plainText: true })]);
+ });
+
+ it('sends nothing when a check says no', async () => {
+ registerPreSendCheck('no', 10, () => false);
+ expect(await prepareQuickReply(input(text))).toBeNull();
+ });
+});
diff --git a/lib/outgoing/__tests__/send-pipeline.test.ts b/lib/outgoing/__tests__/send-pipeline.test.ts
new file mode 100644
index 000000000..9492a1f39
--- /dev/null
+++ b/lib/outgoing/__tests__/send-pipeline.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ finalizeOutgoing,
+ registerOutgoingFinalizer,
+ registerPreSendCheck,
+ resetSendPipeline,
+ runPreSendChecks,
+ type OutgoingContext,
+} from '@/lib/outgoing/send-pipeline';
+
+vi.mock('@/lib/debug', () => ({ debug: { log: () => {}, warn: () => {}, error: () => {} } }));
+
+const CONTEXT: OutgoingContext = {
+ surface: 'composer', to: ['a@example.com'], cc: [], bcc: [], mode: 'compose', plainText: false,
+};
+
+afterEach(() => resetSendPipeline());
+
+describe('finalizeOutgoing', () => {
+ it('runs finalisers in order and leaves the bodies alone without any', () => {
+ expect(finalizeOutgoing({ html: 'x
', text: 'x' }, CONTEXT)).toEqual({ html: 'x
', text: 'x' });
+ registerOutgoingFinalizer('second', 20, (b) => ({ ...b, text: `${b.text}2` }));
+ registerOutgoingFinalizer('first', 10, (b) => ({ ...b, text: `${b.text}1` }));
+ expect(finalizeOutgoing({ text: 'x' }, CONTEXT).text).toBe('x12');
+ });
+
+ it('replaces a finaliser registered again under the same id, and unregisters', () => {
+ registerOutgoingFinalizer('f', 10, (b) => ({ ...b, text: 'old' }));
+ const off = registerOutgoingFinalizer('f', 10, (b) => ({ ...b, text: 'new' }));
+ expect(finalizeOutgoing({ text: 'x' }, CONTEXT).text).toBe('new');
+ off();
+ expect(finalizeOutgoing({ text: 'x' }, CONTEXT).text).toBe('x');
+ });
+
+ it('skips a finaliser that throws', () => {
+ registerOutgoingFinalizer('broken', 10, () => { throw new Error('boom'); });
+ registerOutgoingFinalizer('ok', 20, (b) => ({ ...b, text: `${b.text}!` }));
+ expect(finalizeOutgoing({ text: 'x' }, CONTEXT).text).toBe('x!');
+ });
+});
+
+describe('runPreSendChecks', () => {
+ it('stops at the first check that says no', async () => {
+ const later = vi.fn(() => true);
+ registerPreSendCheck('no', 10, async () => false);
+ registerPreSendCheck('later', 20, later);
+ expect(await runPreSendChecks(CONTEXT)).toBe(false);
+ expect(later).not.toHaveBeenCalled();
+ });
+
+ it('sends when every check agrees or there are none, and skips one that throws', async () => {
+ expect(await runPreSendChecks(CONTEXT)).toBe(true);
+ registerPreSendCheck('broken', 10, () => { throw new Error('boom'); });
+ registerPreSendCheck('yes', 20, () => true);
+ expect(await runPreSendChecks(CONTEXT)).toBe(true);
+ });
+});
diff --git a/lib/outgoing/quick-reply.ts b/lib/outgoing/quick-reply.ts
new file mode 100644
index 000000000..ce696325a
--- /dev/null
+++ b/lib/outgoing/quick-reply.ts
@@ -0,0 +1,46 @@
+import type { Identity } from '@/lib/jmap/types';
+import { appendHtmlSignature, appendPlainTextSignature } from '@/lib/signature-utils';
+import { finalizeOutgoing, runPreSendChecks, type OutgoingBodies } from './send-pipeline';
+
+/**
+ * The bodies a quick reply sends: the typed text with the signature, as
+ * HTML too when the signature is HTML, after the same pre-send checks and
+ * finalisers as the composer's send. Null when a check stopped the send.
+ */
+export async function prepareQuickReply(input: {
+ body: string;
+ signatureIdentity: Identity | null | undefined;
+ separator: boolean;
+ to: string[];
+ fromEmail?: string;
+ identityId?: string;
+}): Promise {
+ const { body, signatureIdentity, separator } = input;
+ const text = appendPlainTextSignature(body, signatureIdentity, { separator });
+
+ // When the identity has an HTML signature, send a matching HTML body so the
+ // signature keeps its formatting; appendPlainTextSignature would otherwise
+ // flatten it to plain text. Text-only identities keep the plain-text-only
+ // behavior (no HTML part).
+ const escapedBody = body
+ .replace(/&/g, '&')
+ .replace(//g, '>')
+ .replace(/\n/g, '${escapedBody}
`, signatureIdentity, { separator })
+ : undefined;
+
+ const context = {
+ surface: 'quick-reply' as const,
+ to: input.to,
+ cc: [],
+ bcc: [],
+ fromEmail: input.fromEmail,
+ identityId: input.identityId,
+ mode: 'reply' as const,
+ plainText: !html,
+ };
+ if (!(await runPreSendChecks(context))) return null;
+ return finalizeOutgoing({ html, text }, context);
+}
diff --git a/lib/outgoing/send-pipeline.ts b/lib/outgoing/send-pipeline.ts
new file mode 100644
index 000000000..bfe97765c
--- /dev/null
+++ b/lib/outgoing/send-pipeline.ts
@@ -0,0 +1,115 @@
+/**
+ * One path for everything Bulwark does to a message on its way out, for
+ * every surface that sends: the composer and quick reply. Features register
+ * here instead of patching each send function:
+ *
+ * - pre-send checks run before anything is sent and may ask the user
+ * (the external-recipient confirm);
+ * - finalisers change the bodies that go out (the organisation signature
+ * check, the legal disclaimer). They run on sends only, never on drafts,
+ * so a re-opened draft never carries what they add.
+ *
+ * With nothing registered both are no-ops.
+ */
+
+import { debug } from '@/lib/debug';
+
+export type SendSurface = 'composer' | 'quick-reply';
+
+export interface OutgoingContext {
+ surface: SendSurface;
+ /** Recipient addresses, without names. */
+ to: string[];
+ cc: string[];
+ bcc: string[];
+ fromEmail?: string;
+ identityId?: string;
+ /** compose, reply, replyAll or forward; quick reply is a reply. */
+ mode: 'compose' | 'reply' | 'replyAll' | 'forward';
+ /** Plain-text-only message (no HTML part). */
+ plainText: boolean;
+}
+
+export interface OutgoingBodies {
+ /** The HTML part; undefined for a plain-text-only message. */
+ html?: string;
+ text: string;
+}
+
+/** Changes the bodies; must return them unchanged when it has nothing to do. */
+export type OutgoingFinalizer = (bodies: OutgoingBodies, context: OutgoingContext) => OutgoingBodies;
+
+/** Resolves false to stop the send (after telling the user why, or asking them). */
+export type PreSendCheck = (context: OutgoingContext) => boolean | Promise;
+
+interface Entry {
+ id: string;
+ order: number;
+ run: T;
+}
+
+const finalizers: Entry[] = [];
+const checks: Entry[] = [];
+
+function register(list: Entry[], id: string, order: number, run: T): () => void {
+ const existing = list.findIndex((entry) => entry.id === id);
+ if (existing >= 0) list.splice(existing, 1);
+ list.push({ id, order, run });
+ list.sort((a, b) => a.order - b.order);
+ return () => {
+ const index = list.findIndex((entry) => entry.id === id && entry.run === run);
+ if (index >= 0) list.splice(index, 1);
+ };
+}
+
+/**
+ * Adds a finaliser; lower `order` runs first. Registering the same id again
+ * replaces it. Returns the unregister function.
+ */
+export function registerOutgoingFinalizer(id: string, order: number, run: OutgoingFinalizer): () => void {
+ return register(finalizers, id, order, run);
+}
+
+/** Adds a pre-send check; lower `order` asks first. Returns the unregister function. */
+export function registerPreSendCheck(id: string, order: number, run: PreSendCheck): () => void {
+ return register(checks, id, order, run);
+}
+
+/** The bodies as they go out, after every finaliser. */
+export function finalizeOutgoing(bodies: OutgoingBodies, context: OutgoingContext): OutgoingBodies {
+ let current = bodies;
+ for (const entry of finalizers) {
+ try {
+ current = entry.run(current, context);
+ } catch (error) {
+ // A broken finaliser must not stop the mail; it goes out without its change.
+ debug.error(`Outgoing finaliser ${entry.id} failed:`, error);
+ }
+ }
+ return current;
+}
+
+/**
+ * Runs the checks in order and stops at the first that says no. A check
+ * that throws is skipped: the checks warn, they don't guard, and a bug in
+ * one must not make sending impossible.
+ */
+export async function runPreSendChecks(context: OutgoingContext): Promise {
+ for (const entry of [...checks]) {
+ try {
+ if (!(await entry.run(context))) {
+ debug.log('email', `Send stopped by the pre-send check ${entry.id}`);
+ return false;
+ }
+ } catch (error) {
+ debug.error(`Pre-send check ${entry.id} failed:`, error);
+ }
+ }
+ return true;
+}
+
+/** For tests: forget every registration. */
+export function resetSendPipeline(): void {
+ finalizers.length = 0;
+ checks.length = 0;
+}
From 7ea0a7d58d169970f9191f175243d99f780db74c Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 01:14:30 +0100
Subject: [PATCH 008/137] feat: read and write account metadata for shared
Bulwark data
---
lib/__tests__/jmap-bulwark-metadata.test.ts | 138 ++++++++++++++++++++
lib/jmap/bulwark-metadata.ts | 76 +++++++++++
lib/jmap/client-interface.ts | 4 +
lib/jmap/client.ts | 79 +++++++++++
4 files changed, 297 insertions(+)
create mode 100644 lib/__tests__/jmap-bulwark-metadata.test.ts
create mode 100644 lib/jmap/bulwark-metadata.ts
diff --git a/lib/__tests__/jmap-bulwark-metadata.test.ts b/lib/__tests__/jmap-bulwark-metadata.test.ts
new file mode 100644
index 000000000..2e1db844a
--- /dev/null
+++ b/lib/__tests__/jmap-bulwark-metadata.test.ts
@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { JMAPClient } from '../jmap/client';
+import { MetadataTooLargeError, MetadataUnsupportedError, bulwarkEntries, isValidMetadataKey } from '../jmap/bulwark-metadata';
+
+// Bulwark keeps shared tags and templates in the Inbox metadata of an
+// account, one namespace per item (each namespace holds at most 8 KB on
+// Stalwart v1.0.0). Servers without metadata, and the pre-release 1.0 build
+// that drops the connection on these calls, count as "not supported".
+
+const METADATA_CAP = {
+ 'urn:ietf:params:jmap:metadata': {
+ dataTypes: { Mailbox: { namespaces: [], supportsVendorNamespaces: true, supportsPrivate: true, maxDepth: 8 } },
+ },
+};
+
+function session() {
+ return {
+ capabilities: { 'urn:ietf:params:jmap:core': {}, 'urn:ietf:params:jmap:mail': {}, 'urn:ietf:params:jmap:metadata': {} },
+ accounts: {
+ me: { name: 'me@example.org', isPersonal: true, accountCapabilities: { 'urn:ietf:params:jmap:mail': {}, ...METADATA_CAP } },
+ team: { name: 'team@example.org', isPersonal: false, accountCapabilities: { 'urn:ietf:params:jmap:mail': {}, ...METADATA_CAP } },
+ old: { name: 'old@example.org', isPersonal: false, accountCapabilities: { 'urn:ietf:params:jmap:mail': {} } },
+ },
+ primaryAccounts: { 'urn:ietf:params:jmap:mail': 'me' },
+ apiUrl: 'https://mail.example.com/jmap/api',
+ downloadUrl: 'https://mail.example.com/jmap/download/{accountId}/{blobId}/{name}',
+ uploadUrl: 'https://mail.example.com/jmap/upload/{accountId}/',
+ eventSourceUrl: '',
+ };
+}
+
+const json = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { 'Content-Type': 'application/json' } });
+
+let fetchSpy: ReturnType;
+let client: JMAPClient;
+let requests: Array<{ using: string[]; methodCalls: Array<[string, Record, string]> }>;
+let answer: (body: (typeof requests)[number]) => Response | Promise;
+
+beforeEach(async () => {
+ vi.useRealTimers();
+ fetchSpy = vi.spyOn(globalThis, 'fetch');
+ fetchSpy.mockResolvedValueOnce(json(session()));
+ client = new JMAPClient('https://mail.example.com', 'me@example.org', 'pw');
+ await client.connect();
+ fetchSpy.mockReset();
+ requests = [];
+ fetchSpy.mockImplementation(async (_url: RequestInfo | URL, init?: RequestInit) => {
+ const body = JSON.parse(String(init?.body ?? '{}'));
+ requests.push(body);
+ return answer(body);
+ });
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+const inboxAnswer = (metadata: unknown, property = 'metadata') => json({
+ methodResponses: [
+ ['Mailbox/query', { ids: ['inbox-1'] }, 'q'],
+ ['Mailbox/get', { list: [{ id: 'inbox-1', [property]: metadata }] }, 'g'],
+ ],
+});
+
+describe('getBulwarkMetadata', () => {
+ it('reads Bulwark\'s namespaces of the Inbox in a request of its own', async () => {
+ answer = () => inboxAnswer({ 'org.bulwarkmail.tags': [{ id: 'urgent' }], 'org.bulwarkmail.template.a': { name: 'A' }, 'other.example': 1 });
+ expect(await client.getBulwarkMetadata('team')).toEqual({ tags: [{ id: 'urgent' }], 'template.a': { name: 'A' } });
+ expect(requests).toHaveLength(1);
+ expect(requests[0].using).toContain('urn:ietf:params:jmap:metadata');
+ expect(requests[0].methodCalls.map((c) => c[0])).toEqual(['Mailbox/query', 'Mailbox/get']);
+ expect(requests[0].methodCalls[1][1].properties).toEqual(['id', 'metadata']);
+ });
+
+ it('reads private metadata when asked', async () => {
+ answer = () => inboxAnswer({ 'org.bulwarkmail.templates': { x: 1 } }, 'privateMetadata');
+ expect(await client.getBulwarkMetadata('me', { private: true })).toEqual({ templates: { x: 1 } });
+ expect(requests[0].methodCalls[1][1].properties).toEqual(['id', 'privateMetadata']);
+ });
+
+ it('asks nothing of an account without the capability', async () => {
+ answer = () => { throw new Error('should not be asked'); };
+ expect(client.supportsBulwarkMetadata('old')).toBe(false);
+ expect(await client.getBulwarkMetadata('old')).toBeNull();
+ expect(requests).toHaveLength(0);
+ });
+
+ it('treats a dropped connection as unsupported and leaves the account alone afterwards', async () => {
+ answer = () => { throw new TypeError('Failed to fetch'); };
+ expect(await client.getBulwarkMetadata('team')).toBeNull();
+ const asked = requests.length;
+ expect(client.supportsBulwarkMetadata('team')).toBe(false);
+ expect(await client.getBulwarkMetadata('team')).toBeNull();
+ expect(requests).toHaveLength(asked);
+ // Other accounts are not affected.
+ expect(client.supportsBulwarkMetadata('me')).toBe(true);
+ });
+});
+
+describe('setBulwarkMetadata', () => {
+ it('patches one namespace of the Inbox and nothing else', async () => {
+ answer = (body) => body.methodCalls[0][0] === 'Mailbox/set'
+ ? json({ methodResponses: [['Mailbox/set', { updated: { 'inbox-1': null } }, '0']] })
+ : inboxAnswer({});
+ await client.setBulwarkMetadata('team', 'tags', [{ id: 'urgent', color: '#f00' }]);
+ const set = requests.find((r) => r.methodCalls[0][0] === 'Mailbox/set')!;
+ expect(set.methodCalls[0][1]).toEqual({
+ accountId: 'team',
+ update: { 'inbox-1': { 'metadata/org.bulwarkmail.tags': [{ id: 'urgent', color: '#f00' }] } },
+ });
+ });
+
+ it('refuses an entry over 8 KB before asking, and passes on the server\'s size refusal', async () => {
+ answer = (body) => body.methodCalls[0][0] === 'Mailbox/set'
+ ? json({ methodResponses: [['Mailbox/set', { notUpdated: { 'inbox-1': { type: 'invalidProperties', description: 'Metadata size 70413 exceeds the maximum of 65536 bytes.' } } }, '0']] })
+ : inboxAnswer({});
+ await expect(client.setBulwarkMetadata('team', 'template.big', { body: 'x'.repeat(9000) })).rejects.toBeInstanceOf(MetadataTooLargeError);
+ expect(requests.some((r) => r.methodCalls[0][0] === 'Mailbox/set')).toBe(false);
+ await expect(client.setBulwarkMetadata('team', 'template.ok', { body: 'small' })).rejects.toBeInstanceOf(MetadataTooLargeError);
+ });
+
+ it('says unsupported for an account without metadata', async () => {
+ await expect(client.setBulwarkMetadata('old', 'tags', [])).rejects.toBeInstanceOf(MetadataUnsupportedError);
+ });
+});
+
+describe('helpers', () => {
+ it('accepts lowercase dotted keys only', () => {
+ expect(isValidMetadataKey('template.abc-1')).toBe(true);
+ expect(isValidMetadataKey('Tags')).toBe(false);
+ expect(isValidMetadataKey('a/b')).toBe(false);
+ expect(isValidMetadataKey('.x')).toBe(false);
+ });
+
+ it('ignores other vendors and non-objects', () => {
+ expect(bulwarkEntries(null)).toEqual({});
+ expect(bulwarkEntries({ 'org.bulwarkmail': 1, 'org.bulwarkmailx.a': 2, 'org.bulwarkmail.a': 3 })).toEqual({ a: 3 });
+ });
+});
diff --git a/lib/jmap/bulwark-metadata.ts b/lib/jmap/bulwark-metadata.ts
new file mode 100644
index 000000000..57f39f7ee
--- /dev/null
+++ b/lib/jmap/bulwark-metadata.ts
@@ -0,0 +1,76 @@
+/**
+ * Bulwark's own data in JMAP metadata (urn:ietf:params:jmap:metadata) of an
+ * account's Inbox: shared tag definitions and team templates in a group
+ * account, personal templates in the user's own account.
+ *
+ * What Stalwart v1.0.0 does (local-data/org-features-facts.md):
+ * - vendor namespaces need a dot ("org.bulwarkmail" works, "bulwark" is
+ * refused); each namespace holds at most 8 KB, one mailbox at most 64 KB
+ * of shared and 16 KB of private metadata;
+ * - `metadata/` patches one namespace and leaves the others;
+ * - every member of a group account sees its shared metadata; private
+ * metadata is per user.
+ *
+ * So every item gets a namespace of its own, `org.bulwarkmail.`. 0.16
+ * has no metadata, and a pre-release 1.0 build advertises it but drops the
+ * connection on Mailbox/get with `metadata`; the calls go in a request of
+ * their own and any failure means "not supported" for that account.
+ */
+
+export const METADATA_CAPABILITY = 'urn:ietf:params:jmap:metadata';
+export const BULWARK_NAMESPACE = 'org.bulwarkmail';
+/** Largest value Stalwart's default config takes in one namespace. */
+export const MAX_METADATA_ENTRY_BYTES = 8192;
+
+const KEY_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$/;
+
+export class MetadataTooLargeError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = 'MetadataTooLargeError';
+ }
+}
+
+export class MetadataUnsupportedError extends Error {
+ constructor(message = 'This server keeps no metadata for Bulwark') {
+ super(message);
+ this.name = 'MetadataUnsupportedError';
+ }
+}
+
+/** `tags`, `template.`: lowercase, digits, dashes, dot-separated. */
+export function isValidMetadataKey(key: string): boolean {
+ return key.length <= 120 && KEY_RE.test(key);
+}
+
+export function namespaceFor(key: string): string {
+ if (!isValidMetadataKey(key)) throw new Error(`Invalid metadata key: ${key}`);
+ return `${BULWARK_NAMESPACE}.${key}`;
+}
+
+/**
+ * Whether the account's capabilities offer vendor-namespaced metadata on
+ * mailboxes. Says nothing about whether the server really implements it.
+ */
+export function advertisesMailboxMetadata(accountCapabilities: Record | undefined): boolean {
+ const cap = accountCapabilities?.[METADATA_CAPABILITY] as
+ | { dataTypes?: Record }
+ | undefined;
+ return cap?.dataTypes?.Mailbox?.supportsVendorNamespaces === true;
+}
+
+/** Bulwark's entries of a `metadata` or `privateMetadata` object, by key. */
+export function bulwarkEntries(metadata: unknown): Record {
+ if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return {};
+ const prefix = `${BULWARK_NAMESPACE}.`;
+ const out: Record = {};
+ for (const [namespace, value] of Object.entries(metadata as Record)) {
+ if (namespace.startsWith(prefix)) out[namespace.slice(prefix.length)] = value;
+ }
+ return out;
+}
+
+/** The size Stalwart counts for a value: its JSON in UTF-8. */
+export function metadataValueBytes(value: unknown): number {
+ return new TextEncoder().encode(JSON.stringify(value)).length;
+}
diff --git a/lib/jmap/client-interface.ts b/lib/jmap/client-interface.ts
index b5fbc4e52..32c3fff43 100644
--- a/lib/jmap/client-interface.ts
+++ b/lib/jmap/client-interface.ts
@@ -610,6 +610,10 @@ export interface IJMAPClient {
listPrincipals?(targetAccountId?: string, options?: { throwOnError?: boolean }): Promise;
/** Principal type by id ("individual", "group"); null when unknown. Optional (demo client). */
getPrincipalTypes?(ids: string[]): Promise | null>;
+ // Bulwark data in Inbox metadata (lib/jmap/bulwark-metadata.ts). Optional (demo client).
+ supportsBulwarkMetadata?(accountId?: string): boolean;
+ getBulwarkMetadata?(accountId?: string, options?: { private?: boolean }): Promise | null>;
+ setBulwarkMetadata?(accountId: string | undefined, key: string, value: unknown, options?: { private?: boolean }): Promise;
setCalendarShare(calendarId: string, principalId: string, rights: CalendarRights | null, targetAccountId?: string): Promise;
setAddressBookShare(addressBookId: string, principalId: string, rights: AddressBookRights | null, targetAccountId?: string): Promise;
setFileNodeShare(fileNodeId: string, principalId: string, rights: FileNodeRights | null, targetAccountId?: string): Promise;
diff --git a/lib/jmap/client.ts b/lib/jmap/client.ts
index 0fd9efa67..3032b4477 100644
--- a/lib/jmap/client.ts
+++ b/lib/jmap/client.ts
@@ -1,3 +1,4 @@
+import { advertisesMailboxMetadata, bulwarkEntries, MAX_METADATA_ENTRY_BYTES, METADATA_CAPABILITY, MetadataTooLargeError, MetadataUnsupportedError, metadataValueBytes, namespaceFor } from "./bulwark-metadata";
import { IncompleteDeleteError } from "./delete-error";
import { ArchiveEmailsError } from "./archive-error";
import { generateUUID } from '@/lib/utils';
@@ -7076,6 +7077,84 @@ export class JMAPClient implements IJMAPClient {
}
}
+ /**
+ * Accounts whose metadata request failed, with when: not asked again for
+ * ten minutes. A dropped connection (the pre-release 1.0 build) looks the
+ * same as a network blip, so the pause is not for the whole session.
+ */
+ private metadataUnsupported = new Map();
+
+ /** Whether Bulwark may keep data in this account's Inbox metadata (lib/jmap/bulwark-metadata.ts). */
+ supportsBulwarkMetadata(accountId?: string): boolean {
+ const id = accountId || this.accountId;
+ const failedAt = this.metadataUnsupported.get(id);
+ if (failedAt !== undefined && Date.now() - failedAt < 10 * 60_000) return false;
+ return advertisesMailboxMetadata(this.accounts[id]?.accountCapabilities as Record | undefined);
+ }
+
+ /**
+ * Bulwark's metadata entries of the account's Inbox, by key, shared or the
+ * user's private ones. Null when the server has no usable metadata.
+ */
+ async getBulwarkMetadata(accountId?: string, options?: { private?: boolean }): Promise | null> {
+ const id = accountId || this.accountId;
+ if (!this.supportsBulwarkMetadata(id)) return null;
+ const property = options?.private ? "privateMetadata" : "metadata";
+ try {
+ // A request of its own: a server that can't answer it must not take
+ // other calls down with it.
+ const response = await this.request([
+ ["Mailbox/query", { accountId: id, filter: { role: "inbox" } }, "q"],
+ ["Mailbox/get", { accountId: id, "#ids": { resultOf: "q", name: "Mailbox/query", path: "/ids" }, properties: ["id", property] }, "g"],
+ ], ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail", METADATA_CAPABILITY]);
+ const get = response.methodResponses?.find((r) => r[0] === "Mailbox/get");
+ const inbox = (get?.[1] as { list?: Array> } | undefined)?.list?.[0];
+ if (!inbox) throw new MetadataUnsupportedError("No Inbox metadata in the answer");
+ this.metadataInboxIds.set(id, inbox.id as string);
+ this.metadataUnsupported.delete(id);
+ return bulwarkEntries(inbox[property]);
+ } catch (error) {
+ debug.warn('jmap', `Metadata unavailable for account ${id}:`, error);
+ this.metadataUnsupported.set(id, Date.now());
+ return null;
+ }
+ }
+
+ private metadataInboxIds = new Map();
+
+ /**
+ * Writes one Bulwark metadata entry of the account's Inbox (null removes
+ * it), leaving every other entry as it is. Throws MetadataTooLargeError
+ * when the server refuses the size, MetadataUnsupportedError when the
+ * account has no metadata.
+ */
+ async setBulwarkMetadata(accountId: string | undefined, key: string, value: unknown, options?: { private?: boolean }): Promise {
+ const id = accountId || this.accountId;
+ if (!this.supportsBulwarkMetadata(id)) throw new MetadataUnsupportedError();
+ const property = options?.private ? "privateMetadata" : "metadata";
+ if (value !== null && metadataValueBytes(value) > MAX_METADATA_ENTRY_BYTES) {
+ throw new MetadataTooLargeError(`The entry is larger than ${MAX_METADATA_ENTRY_BYTES} bytes`);
+ }
+ let inboxId = this.metadataInboxIds.get(id);
+ if (!inboxId) {
+ await this.getBulwarkMetadata(id, options);
+ inboxId = this.metadataInboxIds.get(id);
+ if (!inboxId) throw new MetadataUnsupportedError();
+ }
+ const response = await this.request([
+ ["Mailbox/set", { accountId: id, update: { [inboxId]: { [`${property}/${namespaceFor(key)}`]: value } } }, "0"],
+ ], ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail", METADATA_CAPABILITY]);
+ const [method, result] = response.methodResponses?.[0] ?? [];
+ if (method !== "Mailbox/set") {
+ throw jmapError((result as JmapErrorInfo | undefined)?.description || "Failed to save metadata", result as JmapErrorInfo | undefined);
+ }
+ const notUpdated = (result as { notUpdated?: Record }).notUpdated?.[inboxId];
+ if (notUpdated) {
+ if (/exceeds the maximum/i.test(notUpdated.description ?? "")) throw new MetadataTooLargeError(notUpdated.description!);
+ throw new Error(notUpdated.description || `Failed to save metadata (${notUpdated.type ?? "unknown"})`);
+ }
+ }
+
/**
* The busy periods of a principal between `utcStart` and `utcEnd`
* (Principal/getAvailability). Event details are never requested: this
From 90e6e1046478b71cc61d20c11e210ab905e9af6e Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 01:33:12 +0100
Subject: [PATCH 009/137] test: cover domain and group policies against the
test servers
---
.../tests/19-org-policy-scopes.spec.ts | 169 ++++++++++++++++++
integration/tests/helpers/org.ts | 104 +++++++++++
2 files changed, 273 insertions(+)
create mode 100644 integration/tests/19-org-policy-scopes.spec.ts
create mode 100644 integration/tests/helpers/org.ts
diff --git a/integration/tests/19-org-policy-scopes.spec.ts b/integration/tests/19-org-policy-scopes.spec.ts
new file mode 100644
index 000000000..dedc01ff3
--- /dev/null
+++ b/integration/tests/19-org-policy-scopes.spec.ts
@@ -0,0 +1,169 @@
+import { test, expect } from '@playwright/test';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+ ORG,
+ adminContext,
+ getPolicy,
+ putPolicy,
+ requireOrgEnv,
+ shot,
+ userPage,
+} from './helpers/org';
+
+/**
+ * Domain and group scopes (organisation feature 8), through the real UI on a
+ * VM 106 test server: the admin creates a domain scope and a group scope on
+ * Organisation > Domains and groups, and each applies only where it should.
+ * The admin's policy is put back afterwards.
+ */
+
+test.describe.configure({ mode: 'serial' });
+
+let original: Record;
+
+test.beforeAll(async ({ browser }) => {
+ requireOrgEnv();
+ const admin = await adminContext(browser);
+ original = await getPolicy(admin);
+ await putPolicy(admin, { ...original, scopes: [], restrictions: {}, features: {} });
+ await admin.close();
+});
+
+test.afterAll(async ({ browser }) => {
+ const admin = await adminContext(browser);
+ await putPolicy(admin, original);
+ await admin.close();
+});
+
+test('the admin adds a domain and a group on the Domains and groups page', async ({ browser }) => {
+ const admin = await adminContext(browser);
+ const page = await admin.newPage();
+ await page.goto('/admin/organisation');
+ await expect(page.getByRole('heading', { name: 'Domains and groups' }).first()).toBeVisible();
+
+ await page.getByRole('button', { name: 'Add domains' }).click();
+ await page.getByLabel('Name', { exact: true }).last().fill('Org two');
+ await page.getByLabel('Domains', { exact: true }).last().fill('org-two.test');
+ await page.getByLabel('Domains', { exact: true }).last().blur();
+
+ await page.getByRole('button', { name: 'Add groups' }).click();
+ await page.getByLabel('Name', { exact: true }).last().fill('Org team');
+ await page.getByLabel('Groups', { exact: true }).last().fill(ORG.team);
+ await page.getByLabel('Groups', { exact: true }).last().blur();
+
+ await page.getByRole('button', { name: 'Save', exact: true }).click();
+ await expect(page.getByText('Saved.')).toBeVisible();
+ await shot(page, 'admin-domains-and-groups');
+
+ const policy = await getPolicy(admin);
+ const scopes = policy.scopes as Array<{ id: string; label: string; match: Record }>;
+ expect(scopes.map((s) => [s.label, s.match])).toEqual([
+ ['Org two', { domains: ['org-two.test'] }],
+ ['Org team', { groups: [ORG.team] }],
+ ]);
+
+ // The settings of each scope come with the Organisation pages of the
+ // features; here they are set through the same policy the pages write.
+ const [two, team] = scopes;
+ await putPolicy(admin, {
+ ...policy,
+ scopes: [
+ { ...two, policy: { features: { calendarEnabled: false } } },
+ { ...team, policy: { restrictions: { density: { locked: true, value: 'compact' } } } },
+ ],
+ });
+
+ // The effective policy for org-alice names the group scope.
+ await page.reload();
+ await page.getByLabel('User address').fill(ORG.alice);
+ await page.getByLabel('Groups the user is a member of').fill(ORG.team);
+ const effective = page.getByTestId('org-effective-policy');
+ await expect(effective).toContainText('Applies, in this order: Everyone, Org team.');
+ await expect(effective).toContainText('restrictions.density');
+ await shot(page, 'admin-effective-policy');
+ await admin.close();
+});
+
+test('a domain scope applies to that domain only', async ({ browser }) => {
+ const dave = await userPage(browser, ORG.dave);
+ await expect(dave.locator('[data-tour="nav-mail"]')).toBeVisible();
+ await expect(dave.locator('[data-tour="nav-calendar"]')).toHaveCount(0);
+ await dave.context().close();
+
+ const carol = await userPage(browser, ORG.carol);
+ await expect(carol.locator('[data-tour="nav-calendar"]')).toBeVisible();
+ await carol.goto('/settings/appearance');
+ await expect(carol.getByText('Set by your organisation')).toHaveCount(0);
+ await carol.context().close();
+});
+
+test('a group scope locks a setting for members only, with the reason in place', async ({ browser }) => {
+ const alice = await userPage(browser, ORG.alice);
+ await expect(alice.locator('[data-tour="nav-calendar"]')).toBeVisible();
+ await alice.goto('/settings/appearance');
+ const note = alice.getByText('Set by your organisation');
+ await expect(note).toHaveCount(1);
+ await note.scrollIntoViewIfNeeded();
+ await shot(alice, 'user-locked-setting');
+ // The locked control can't be reached.
+ const row = alice.locator('[data-search-label]').filter({ has: note });
+ await expect(row.locator('[inert]')).toHaveCount(1);
+ await alice.context().close();
+});
+
+test('the lock shows at phone width too', async ({ browser }) => {
+ const alice = await userPage(browser, ORG.alice, true);
+ // A phone opens the settings on their list.
+ await alice.goto('/settings/appearance');
+ await alice.getByRole('button', { name: 'Appearance' }).or(alice.getByRole('link', { name: 'Appearance' })).first().click();
+ const note = alice.getByText('Set by your organisation');
+ await expect(note).toBeVisible();
+ await note.scrollIntoViewIfNeeded();
+ await shot(alice, 'user-locked-setting-phone');
+ await alice.context().close();
+});
+
+test('the whole policy exports to one file and imports back', async ({ browser }, testInfo) => {
+ const admin = await adminContext(browser);
+ const page = await admin.newPage();
+ await page.goto('/admin/organisation');
+ const [download] = await Promise.all([
+ page.waitForEvent('download'),
+ page.getByRole('button', { name: 'Export policy.json' }).click(),
+ ]);
+ const exported = testInfo.outputPath('exported-policy.json');
+ await download.saveAs(exported);
+ const file = JSON.parse(await readFile(exported, 'utf-8'));
+ expect(file.scopes.map((s: { label: string }) => s.label)).toEqual(['Org two', 'Org team']);
+
+ // Change it outside Bulwark, as someone keeping it in git would.
+ file.scopes = file.scopes.filter((s: { label: string }) => s.label !== 'Org two');
+ const edited = path.join(path.dirname(exported), 'edited-policy.json');
+ await writeFile(edited, JSON.stringify(file));
+ await page.getByLabel('Policy file to import').setInputFiles(edited);
+ const preview = page.getByTestId('policy-import-preview');
+ await expect(preview).toContainText('Domains and groups: 1 removed');
+ await shot(page, 'admin-policy-import-preview');
+ await page.getByRole('button', { name: 'Replace the current policy' }).click();
+ await expect(preview).toHaveCount(0);
+ const after = await getPolicy(admin);
+ expect((after.scopes as Array<{ label: string }>).map((s) => s.label)).toEqual(['Org team']);
+ await admin.close();
+
+ // org-dave has the calendar again.
+ const dave = await userPage(browser, ORG.dave);
+ await expect(dave.locator('[data-tour="nav-calendar"]')).toBeVisible();
+ await dave.context().close();
+});
+
+test('the Organisation pages work at phone width', async ({ browser }) => {
+ const admin = await adminContext(browser, true);
+ const page = await admin.newPage();
+ await page.goto('/admin/organisation');
+ await expect(page.getByRole('button', { name: 'Add domains' })).toBeVisible();
+ const overflow = await page.evaluate(() => document.documentElement.scrollWidth - window.innerWidth);
+ expect(overflow).toBeLessThanOrEqual(0);
+ await shot(page, 'admin-domains-and-groups-phone');
+ await admin.close();
+});
diff --git a/integration/tests/helpers/org.ts b/integration/tests/helpers/org.ts
new file mode 100644
index 000000000..3c14996fe
--- /dev/null
+++ b/integration/tests/helpers/org.ts
@@ -0,0 +1,104 @@
+/**
+ * Helpers for the organisation feature specs (19-org-*.spec.ts). They run
+ * against a local dev server on a VM 106 test Stalwart with the throwaway
+ * org-* accounts, never the suite's alice/bob/carol, and never reset an
+ * account.
+ *
+ * Env:
+ * IT_WEBMAIL_URL the dev server (scratch ADMIN_CONFIG_DIR)
+ * IT_ORG_PASSWORD password of the org-* accounts (vault "Stalwart test – org-* throwaway accounts")
+ * IT_ADMIN_PASSWORD the dev server's admin password (vault "Bulwark dev rig – org features admin")
+ * IT_ORG_SERVER label for screenshots and logs: 0.16, 1.0, 1.0.0
+ */
+import { type Browser, type BrowserContext, type Page, expect } from '@playwright/test';
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { WEBMAIL_URL } from './config';
+import { accountSwitcher, neutralizeDevOverlay } from './app';
+
+export const ORG_PASSWORD = process.env.IT_ORG_PASSWORD ?? '';
+export const ADMIN_PASSWORD = process.env.IT_ADMIN_PASSWORD ?? '';
+export const ORG_SERVER = process.env.IT_ORG_SERVER ?? 'unknown';
+
+export const ORG = {
+ alice: 'org-alice@example.org',
+ bob: 'org-bob@example.org',
+ carol: 'org-carol@example.org',
+ dave: 'org-dave@org-two.test',
+ team: 'org-team@example.org',
+} as const;
+
+export function requireOrgEnv(): void {
+ if (!ORG_PASSWORD || !ADMIN_PASSWORD) {
+ throw new Error('Set IT_ORG_PASSWORD and IT_ADMIN_PASSWORD (vw exec --env ...) to run the org specs');
+ }
+}
+
+/** English UI (Playwright's default locale gives German) at desktop or phone width. */
+export function contextOptions(phone = false) {
+ return {
+ baseURL: WEBMAIL_URL,
+ locale: 'en-US',
+ viewport: phone ? { width: 390, height: 844 } : { width: 1440, height: 900 },
+ ...(phone ? { isMobile: true, hasTouch: true } : {}),
+ };
+}
+
+const stateDir = path.join(process.cwd(), 'integration', 'test-results');
+const adminStatePath = () => path.join(stateDir, `org-admin-${new URL(WEBMAIL_URL).port || '80'}.json`);
+
+/**
+ * A browser context signed in to /admin. Admin login is rate limited (5 per
+ * 15 minutes), so the session is stored once and reused across specs.
+ */
+export async function adminContext(browser: Browser, phone = false): Promise {
+ if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
+ if (existsSync(adminStatePath())) {
+ const context = await browser.newContext({ ...contextOptions(phone), storageState: adminStatePath() });
+ const res = await context.request.get('/api/admin/auth');
+ if (res.ok() && (await res.json().catch(() => ({})))?.authenticated !== false) return context;
+ await context.close();
+ }
+ const context = await browser.newContext(contextOptions(phone));
+ const page = await context.newPage();
+ await page.goto('/admin/login');
+ await page.fill('#password', ADMIN_PASSWORD);
+ await page.click('button[type="submit"]');
+ await page.waitForURL((url) => !url.pathname.endsWith('/admin/login'), { timeout: 30000 });
+ await context.storageState({ path: adminStatePath() });
+ await page.close();
+ return context;
+}
+
+/** The policy as the admin sees it. */
+export async function getPolicy(admin: BrowserContext): Promise> {
+ const res = await admin.request.get('/api/admin/policy');
+ expect(res.ok()).toBe(true);
+ return res.json();
+}
+
+export async function putPolicy(admin: BrowserContext, policy: Record): Promise {
+ const res = await admin.request.put('/api/admin/policy', { data: policy });
+ expect(res.ok(), await res.text()).toBe(true);
+}
+
+/** Sign in a fresh context as one of the org-* accounts. */
+export async function userPage(browser: Browser, email: string, phone = false): Promise {
+ const context = await browser.newContext(contextOptions(phone));
+ const page = await context.newPage();
+ await neutralizeDevOverlay(page);
+ await page.goto('/');
+ await page.fill('#username', email);
+ await page.fill('#password', ORG_PASSWORD);
+ await page.click('button[type="submit"]');
+ await accountSwitcher(page).waitFor({ state: 'visible', timeout: 60000 });
+ return page;
+}
+
+/** Screenshots for local-data/org-features-screenshots/, named by feature and server. */
+export async function shot(page: Page, name: string): Promise {
+ const dir = process.env.IT_ORG_SCREENSHOTS;
+ if (!dir) return;
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+ await page.screenshot({ path: path.join(dir, `${name}-${ORG_SERVER}.png`), fullPage: false });
+}
From b504e39b63f05ff061423f5b8ffdaf7fcfbaba09 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 01:53:39 +0100
Subject: [PATCH 010/137] feat: label mail from outside the organisation
---
.../__tests__/external-sender-chip.test.tsx | 97 +++++++++++++
components/email/email-viewer.tsx | 5 +
components/email/external-sender-chip.tsx | 50 +++++++
components/email/thread-conversation-view.tsx | 2 +
lib/__tests__/external-mail.test.ts | 129 ++++++++++++++++++
lib/admin/organisation-policy.ts | 6 +-
lib/external-mail.ts | 119 ++++++++++++++++
locales/de/common.json | 4 +
locales/en/common.json | 4 +
9 files changed, 415 insertions(+), 1 deletion(-)
create mode 100644 components/email/__tests__/external-sender-chip.test.tsx
create mode 100644 components/email/external-sender-chip.tsx
create mode 100644 lib/__tests__/external-mail.test.ts
create mode 100644 lib/external-mail.ts
diff --git a/components/email/__tests__/external-sender-chip.test.tsx b/components/email/__tests__/external-sender-chip.test.tsx
new file mode 100644
index 000000000..a14269288
--- /dev/null
+++ b/components/email/__tests__/external-sender-chip.test.tsx
@@ -0,0 +1,97 @@
+import { render, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Email, Identity, Mailbox } from '@/lib/jmap/types';
+import { clearAllHooks } from '@/lib/plugin-hooks';
+import { DEFAULT_ORGANISATION_POLICY } from '@/lib/admin/organisation-policy';
+import { DEFAULT_POLICY } from '@/lib/admin/types';
+import { usePolicyStore } from '@/stores/policy-store';
+import { useAuthStore } from '@/stores/auth-store';
+
+vi.mock('@/hooks/use-media-query', () => ({
+ useDeviceDetection: () => ({ isMobile: false, isTablet: false, isDesktop: true }),
+ useMediaQuery: () => false,
+}));
+vi.mock('@/components/tour/tour-provider', () => ({
+ useTour: () => ({ activeTour: null, startTour: vi.fn(), endTour: vi.fn(), registerStep: vi.fn() }),
+}));
+vi.mock('@/components/plugins/plugin-slot', () => ({ PluginSlot: () => null }));
+vi.mock('@/hooks/use-plugin-slot-offers', () => ({ usePluginSlotOffers: () => [] }));
+
+class NoopResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+vi.stubGlobal('ResizeObserver', NoopResizeObserver);
+
+const { EmailViewer } = await import('../email-viewer');
+const { ExternalSenderChip } = await import('../external-sender-chip');
+
+const mailboxes = [
+ { id: 'inbox', name: 'Inbox', role: 'inbox', parentId: null, myRights: { mayAddItems: true } },
+] as unknown as Mailbox[];
+
+const message = (from: string) => ({
+ id: 'm1', blobId: 'b1', threadId: 't1', mailboxIds: { inbox: true }, keywords: { $seen: true },
+ from: [{ name: 'Sender', email: from }], to: [{ name: 'Org Alice', email: 'org-alice@example.org' }],
+ subject: 'Hello', receivedAt: '2026-01-01T00:00:00Z', preview: 'Hello', hasAttachment: false, size: 100,
+ textBody: [{ partId: '1', type: 'text/html' }], htmlBody: [{ partId: '1', type: 'text/html' }], attachments: [],
+ bodyValues: { '1': { value: 'Body
' } },
+}) as unknown as Email;
+
+function setExternalMail(patch: Partial) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+async function openMessage(from: string) {
+ const view = render(<{sender.email}>
)}
+
{compact ? formatDate(emailDisplayDate(email)) : mvSenderDate(emailDisplayDate(email), timeFormat)}
@@ -5045,6 +5047,7 @@ export function EmailViewer({
{mvViewer && sender?.email && sender?.name && (
<{sender.email}>
)}
+ {t('unknown_sender')}
)}
+ s.policy.organisation?.externalMail);
+ const identities = useAuthStore((s) => s.identities);
+ return useMemo(() => {
+ if (!externalMail?.senderLabel) return null;
+ const internal = internalDomains(externalMail.domains, (identities ?? []).map((identity) => identity.email));
+ return externalSenderDomain(fromEmail, internal);
+ }, [externalMail, identities, fromEmail]);
+}
+
+/**
+ * "External" next to the sender's name. A chip and not a banner, so it sits
+ * beside the unverified-sender warning without adding a second banner, and
+ * it keeps to one short word so the narrow phone header doesn't wrap more.
+ */
+export function ExternalSenderChip({ fromEmail, className }: { fromEmail: string | null | undefined; className?: string }) {
+ const t = useTranslations('external_mail');
+ const domain = useExternalSenderDomain(fromEmail);
+ if (!domain) return null;
+ const tooltip = t('sender_tooltip', { domain });
+ return (
+
+ {` (${tooltip})`}
+
+ );
+}
diff --git a/components/email/thread-conversation-view.tsx b/components/email/thread-conversation-view.tsx
index 4cde880b6..26c19ad7f 100644
--- a/components/email/thread-conversation-view.tsx
+++ b/components/email/thread-conversation-view.tsx
@@ -11,6 +11,7 @@ import { emailDisplayDate } from "@/lib/email-date";
import { getRenderableHtmlBody } from "@/lib/email-body-selection";
import { findVerificationCode, verificationCodeBodyText } from "@/lib/verification-code";
import { VerificationCodeChip } from "./verification-code-chip";
+import { ExternalSenderChip } from "./external-sender-chip";
import { collectReferencedCids, isEmbeddedInBody, normalizeCid, rewriteCidReferences } from "@/lib/attachment-visibility";
import { collapsePlainTextQuotes, setupQuoteCollapse } from "@/lib/quote-collapse";
import { fitEmailBodyWidth } from "@/lib/email-fit-width";
@@ -396,6 +397,7 @@ function EmailCard({
)}>
{sender?.name || (sender?.email && formatAddress(sender.email)) || "Unknown"}
+ ) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+describe('addressDomain', () => {
+ it('takes the domain of bare and named addresses, lowercased', () => {
+ expect(addressDomain('Bob@Example.COM')).toBe('example.com');
+ expect(addressDomain('Bob ')).toBe('eu.example.com');
+ expect(addressDomain('no-at-sign')).toBe('');
+ expect(addressDomain(undefined)).toBe('');
+ });
+});
+
+describe('domainMatches', () => {
+ it('matches the domain itself and its subdomains, nothing else', () => {
+ expect(domainMatches('example.com', ['example.com'])).toBe(true);
+ expect(domainMatches('eu.example.com', ['example.com'])).toBe(true);
+ expect(domainMatches('a.b.example.com', ['example.com'])).toBe(true);
+ // A suffix that isn't a subdomain doesn't count.
+ expect(domainMatches('badexample.com', ['example.com'])).toBe(false);
+ expect(domainMatches('example.com.evil.net', ['example.com'])).toBe(false);
+ // A subdomain in the list doesn't cover its parent.
+ expect(domainMatches('example.com', ['eu.example.com'])).toBe(false);
+ });
+});
+
+describe('internalDomains', () => {
+ it('always counts the identity domains and adds the admin list', () => {
+ expect(internalDomains([], ['me@example.org'])).toEqual(['example.org']);
+ expect(internalDomains(['partner.com'], ['me@example.org', 'alias@Example.org'])).toEqual(['partner.com', 'example.org']);
+ });
+});
+
+describe('isExternalAddress', () => {
+ const internal = internalDomains(['partner.com'], ['me@example.org']);
+ it('is external only outside the identity domains and the list, subdomains included', () => {
+ expect(isExternalAddress('bob@example.org', internal)).toBe(false);
+ expect(isExternalAddress('x@eu.partner.com', internal)).toBe(false);
+ expect(isExternalAddress('dave@org-two.test', internal)).toBe(true);
+ });
+ it('calls nobody external when no internal domain is known', () => {
+ expect(isExternalAddress('dave@org-two.test', [])).toBe(false);
+ });
+});
+
+describe('externalRecipients', () => {
+ const internal = ['example.org'];
+ it('lists only the external recipients, each once, with the field it is in', () => {
+ const result = externalRecipients(
+ { to: ['bob@example.org', 'dave@org-two.test'], cc: ['DAVE@org-two.test', 'eve@other.net'], bcc: ['x@sub.example.org'] },
+ internal,
+ );
+ expect(result).toEqual([
+ { address: 'dave@org-two.test', domain: 'org-two.test', field: 'to' },
+ { address: 'eve@other.net', domain: 'other.net', field: 'cc' },
+ ]);
+ });
+ it('leaves out trusted addresses (contacts)', () => {
+ const trusted = new Set(['dave@org-two.test']);
+ const result = externalRecipients({ to: ['Dave@org-two.test', 'eve@other.net'], cc: [], bcc: [] }, internal, (a) => trusted.has(a));
+ expect(result.map((r) => r.address)).toEqual(['eve@other.net']);
+ });
+});
+
+describe('externalSenderDomain', () => {
+ it('names the domain of an external sender and nothing for internal ones', () => {
+ expect(externalSenderDomain('dave@org-two.test', ['example.org'])).toBe('org-two.test');
+ expect(externalSenderDomain('bob@example.org', ['example.org'])).toBeNull();
+ expect(externalSenderDomain(undefined, ['example.org'])).toBeNull();
+ });
+});
+
+describe('the active account', () => {
+ beforeEach(() => {
+ setExternalMail({});
+ useAuthStore.setState({ identities: [] });
+ useContactStore.setState({ contacts: [] });
+ });
+
+ it('reads the switches from the effective policy', () => {
+ expect(coreExternalWarningsOn()).toBe(false);
+ setExternalMail({ senderLabel: true });
+ expect(coreExternalWarningsOn()).toBe(true);
+ setExternalMail({ recipientWarning: true });
+ expect(coreExternalWarningsOn()).toBe(true);
+ });
+
+ it('combines the policy domains with the identity domains', () => {
+ setExternalMail({ domains: ['partner.com'] });
+ useAuthStore.setState({ identities: [identity('org-alice@example.org')] });
+ expect(currentInternalDomains()).toEqual(['partner.com', 'example.org']);
+ });
+
+ it('collects the addresses of every contact', () => {
+ useContactStore.setState({
+ contacts: [
+ { id: 'c1', emails: { e1: { address: 'Dave@org-two.test' }, e2: { address: 'second@x.test' } } },
+ { id: 'c2' },
+ ] as unknown as ContactCard[],
+ });
+ expect([...contactAddresses()].sort()).toEqual(['dave@org-two.test', 'second@x.test']);
+ });
+});
diff --git a/lib/admin/organisation-policy.ts b/lib/admin/organisation-policy.ts
index 55769a4e3..77562da19 100644
--- a/lib/admin/organisation-policy.ts
+++ b/lib/admin/organisation-policy.ts
@@ -25,7 +25,11 @@ export interface OrganisationPolicy {
senderLabel: boolean;
/** Confirm before sending to recipients outside the organisation domains. */
recipientWarning: boolean;
- /** Organisation domains; empty means the domains of the user's identities. Subdomains match. */
+ /**
+ * More organisation domains. The domains of the user's own identities
+ * always count as internal; these are added to them. A domain covers its
+ * subdomains (example.com covers eu.example.com). See lib/external-mail.ts.
+ */
domains: string[];
/** Recipients in the user's contacts don't trigger the warning. */
trustContacts: boolean;
diff --git a/lib/external-mail.ts b/lib/external-mail.ts
new file mode 100644
index 000000000..d81add2b0
--- /dev/null
+++ b/lib/external-mail.ts
@@ -0,0 +1,119 @@
+/**
+ * Who is outside the organisation, for the "External" sender chip and the
+ * confirm before sending outside it (policy.json organisation.externalMail).
+ *
+ * Internal are the domains of the user's own identities plus the domains
+ * the admin lists; a listed domain covers its subdomains (example.com
+ * covers eu.example.com). With no internal domain known at all nobody can
+ * be told apart, so nothing counts as external.
+ *
+ * The pure functions take everything as arguments; the `current*` helpers
+ * read the active account's effective policy and identities.
+ */
+
+import { DEFAULT_ORGANISATION_POLICY, normalizeDomainList, type OrganisationPolicy } from '@/lib/admin/organisation-policy';
+import { usePolicyStore } from '@/stores/policy-store';
+import { useAuthStore } from '@/stores/auth-store';
+import { useContactStore } from '@/stores/contact-store';
+
+export type ExternalMailPolicy = OrganisationPolicy['externalMail'];
+
+/** The lowercased domain of an address ("Name " or "a@b"); '' without one. */
+export function addressDomain(address: string | null | undefined): string {
+ const raw = String(address ?? '').trim();
+ const bracket = raw.match(/<([^<>]*)>\s*$/);
+ const bare = (bracket ? bracket[1] : raw).trim();
+ const at = bare.lastIndexOf('@');
+ if (at < 0) return '';
+ return bare.slice(at + 1).trim().toLowerCase().replace(/\.+$/, '');
+}
+
+/** True when `domain` is one of `internal` or a subdomain of one. */
+export function domainMatches(domain: string, internal: readonly string[]): boolean {
+ if (!domain) return false;
+ const d = domain.toLowerCase();
+ return internal.some((entry) => d === entry || d.endsWith(`.${entry}`));
+}
+
+/** The admin's domains plus the domains of the user's identities, normalised and deduplicated. */
+export function internalDomains(policyDomains: readonly string[], identityEmails: readonly string[]): string[] {
+ const own = identityEmails.map(addressDomain).filter(Boolean);
+ return normalizeDomainList([...policyDomains, ...own]) ?? [];
+}
+
+/** Whether mail from or to this address leaves the organisation. */
+export function isExternalAddress(address: string, internal: readonly string[]): boolean {
+ if (internal.length === 0) return false;
+ const domain = addressDomain(address);
+ return !!domain && !domainMatches(domain, internal);
+}
+
+export type RecipientField = 'to' | 'cc' | 'bcc';
+
+export interface ExternalRecipient {
+ address: string;
+ domain: string;
+ field: RecipientField;
+}
+
+/**
+ * The recipients outside the organisation, each address once (in the first
+ * field it appears in). `trusted` is asked for the rest: with "trust
+ * contacts" on, an address in the user's contacts doesn't count.
+ */
+export function externalRecipients(
+ recipients: { to: readonly string[]; cc: readonly string[]; bcc: readonly string[] },
+ internal: readonly string[],
+ trusted?: (address: string) => boolean,
+): ExternalRecipient[] {
+ const out: ExternalRecipient[] = [];
+ const seen = new Set();
+ for (const field of ['to', 'cc', 'bcc'] as const) {
+ for (const raw of recipients[field]) {
+ const address = String(raw ?? '').trim();
+ const key = address.toLowerCase();
+ if (!address || seen.has(key)) continue;
+ seen.add(key);
+ if (!isExternalAddress(address, internal)) continue;
+ if (trusted?.(key)) continue;
+ out.push({ address, domain: addressDomain(address), field });
+ }
+ }
+ return out;
+}
+
+/** The sender's domain when it is outside the organisation, else null. */
+export function externalSenderDomain(fromEmail: string | null | undefined, internal: readonly string[]): string | null {
+ if (!fromEmail || !isExternalAddress(fromEmail, internal)) return null;
+ return addressDomain(fromEmail);
+}
+
+// ─── The active account ──────────────────────────────────────
+
+/** The externalMail settings of the active account's effective policy. */
+export function currentExternalMailPolicy(): ExternalMailPolicy {
+ return usePolicyStore.getState().getOrganisation().externalMail ?? DEFAULT_ORGANISATION_POLICY.externalMail;
+}
+
+/** Either core switch is on: the label or the recipient warning. */
+export function coreExternalWarningsOn(policy: ExternalMailPolicy = currentExternalMailPolicy()): boolean {
+ return policy.senderLabel || policy.recipientWarning;
+}
+
+/** The internal domains for the active account. */
+export function currentInternalDomains(policy: ExternalMailPolicy = currentExternalMailPolicy()): string[] {
+ const identities = useAuthStore.getState().identities ?? [];
+ return internalDomains(policy.domains, identities.map((identity) => identity.email));
+}
+
+/** Lowercased addresses of every loaded contact (all address books). */
+export function contactAddresses(): Set {
+ const out = new Set();
+ for (const contact of useContactStore.getState().contacts) {
+ for (const entry of Object.values(contact.emails ?? {})) {
+ const address = entry?.address?.trim().toLowerCase();
+ if (address) out.add(address);
+ }
+ }
+ return out;
+}
diff --git a/locales/de/common.json b/locales/de/common.json
index ffdd16235..73f54a823 100644
--- a/locales/de/common.json
+++ b/locales/de/common.json
@@ -659,6 +659,10 @@
"plugin_panel_hide": "Plugin-Bereich ausblenden",
"copy": "Kopieren"
},
+ "external_mail": {
+ "sender_label": "Extern",
+ "sender_tooltip": "Von außerhalb Ihrer Organisation: {domain}"
+ },
"email_composer": {
"select_from_directory": "Aus Verzeichnis auswählen",
"minimize": "Minimieren",
diff --git a/locales/en/common.json b/locales/en/common.json
index 95ec87fa3..60734aa9d 100644
--- a/locales/en/common.json
+++ b/locales/en/common.json
@@ -659,6 +659,10 @@
"plugin_panel_show": "Show plugin panel",
"plugin_panel_hide": "Hide plugin panel"
},
+ "external_mail": {
+ "sender_label": "External",
+ "sender_tooltip": "From outside your organisation: {domain}"
+ },
"email_composer": {
"select_from_directory": "Select from directory",
"minimize": "Minimize",
From 79c697a93553c9da66868a1d5d302a1ccf3d8e13 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 01:55:15 +0100
Subject: [PATCH 011/137] feat: let an automatic sign-out save open and
minimised drafts first
---
.../composer-sign-out-flush.test.tsx | 265 ++++++++++++++++++
components/email/email-composer.tsx | 23 +-
components/mail/mail-app.tsx | 17 ++
lib/__tests__/compose-flush-registry.test.ts | 69 +++++
lib/compose-flush-registry.ts | 82 ++++++
5 files changed, 455 insertions(+), 1 deletion(-)
create mode 100644 components/email/__tests__/composer-sign-out-flush.test.tsx
create mode 100644 lib/__tests__/compose-flush-registry.test.ts
create mode 100644 lib/compose-flush-registry.ts
diff --git a/components/email/__tests__/composer-sign-out-flush.test.tsx b/components/email/__tests__/composer-sign-out-flush.test.tsx
new file mode 100644
index 000000000..50c4a1e17
--- /dev/null
+++ b/components/email/__tests__/composer-sign-out-flush.test.tsx
@@ -0,0 +1,265 @@
+import { render, screen, fireEvent, act } from '@testing-library/react';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { EmailComposer, type ComposerDraftData } from '../email-composer';
+import { useAuthStore } from '@/stores/auth-store';
+import { flushComposers, resetComposeFlushRegistry } from '@/lib/compose-flush-registry';
+
+// ─── Heavy component mocks (mirrors reply-addressing.test.tsx) ────────────────
+
+vi.mock('@/components/email/rich-text-editor', () => ({
+ RichTextEditor: () => React.createElement('div', { 'data-testid': 'rich-text-editor' }),
+}));
+
+vi.mock('@/components/plugins/plugin-slot', () => ({ PluginSlot: () => null }));
+vi.mock('@/components/identity/sub-address-helper', () => ({ SubAddressHelper: () => null }));
+vi.mock('@/components/templates/template-picker', () => ({ TemplatePicker: () => null }));
+vi.mock('@/components/templates/template-form', () => ({ TemplateForm: () => null }));
+vi.mock('@/components/files/file-preview-modal', () => ({ FilePreviewModal: () => null }));
+vi.mock('@/hooks/use-focus-trap', () => ({
+ useFocusTrap: () => ({ current: null }),
+}));
+vi.mock('@/hooks/use-pro-multi-account-identities', () => ({
+ useProMultiAccountIdentities: () => ({ enabled: false, groups: [], allIdentities: [] }),
+ stripCrossAccountIdentityPrefix: (id: string) => ({ localAccountId: null, rawId: id }),
+}));
+
+// ─── Store mocks ──────────────────────────────────────────────────────────────
+
+vi.mock('@/stores/auth-store', () => {
+ const state = {
+ client: null,
+ identities: [],
+ primaryIdentity: null,
+ isAuthenticated: false,
+ isDemoMode: false,
+ activeAccountId: null,
+ connectionLost: false,
+ getClientForAccount: () => undefined,
+ getAllConnectedClients: () => new Map(),
+ syncIdentities: () => {},
+ refreshIdentities: async () => {},
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useAuthStore: hook };
+});
+
+vi.mock('@/stores/identity-store', () => {
+ const state = {
+ identities: [{ id: 'id-me', email: 'me@example.com', name: 'Me' }],
+ defaultIdentityId: 'id-me',
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useIdentityStore: hook };
+});
+
+vi.mock('@/stores/account-store', () => {
+ const state = { accounts: [], getAccountById: () => undefined };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useAccountStore: hook };
+});
+
+vi.mock('@/stores/email-store', () => {
+ const state = {
+ draftSaveEnabled: false,
+ sendRawEmail: async () => ({ sent: true }),
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useEmailStore: hook };
+});
+
+const updateSetting = vi.fn();
+
+vi.mock('@/stores/settings-store', () => {
+ const state = {
+ timeFormat: '24h',
+ plainTextMode: false,
+ subAddressDelimiter: '+',
+ autoSelectReplyIdentity: true,
+ attachmentReminderEnabled: false,
+ attachmentReminderKeywords: [],
+ emptySubjectWarningEnabled: true,
+ sendDelaySeconds: 0,
+ signaturePosition: 'above_quote',
+ signatureSeparatorEnabled: false,
+ requestReadReceiptDefault: false,
+ addTrustedSender: () => {},
+ trustedSendersAddressBook: null,
+ updateSetting: (...args: unknown[]) => updateSetting(...args),
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useSettingsStore: hook };
+});
+
+vi.mock('@/stores/contact-store', () => {
+ const state = {
+ contacts: [],
+ getAutocomplete: async () => [],
+ addToTrustedSendersBook: async () => {},
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useContactStore: hook };
+});
+
+vi.mock('@/stores/template-store', () => {
+ const state = { templates: [], addTemplate: async () => {} };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useTemplateStore: hook };
+});
+
+// ─── Misc dependency mocks ────────────────────────────────────────────────────
+
+vi.mock('@/stores/toast-store', () => ({
+ toast: { info: () => {}, error: () => {}, success: () => {} },
+}));
+
+vi.mock('@/lib/plugin-hooks', () => ({
+ identityHooks: {
+ onSignatureRender: { size: 0, transform: async (value: unknown) => value },
+ onIdentitySelect: { size: 0, emit: async () => {} },
+ },
+ templateHooks: {
+ onTemplateRender: { size: 0, transform: async (value: unknown) => value },
+ onTemplateApply: { size: 0, emit: async () => {} },
+ },
+ emailHooks: {
+ onComposerOpen: { call: async () => [] },
+ onRecipientChange: { call: async () => [] },
+ getRecipientSuggestions: { call: async () => [] },
+ onRecipientChipsChange: { transform: async (chips: unknown) => chips },
+ onDraftChange: { emit: () => {} },
+ onBeforeDraftAutoSave: { transform: async (draft: unknown) => draft },
+ onBeforeEmailSend: { intercept: async () => true, interceptOutcome: async () => 'allowed' },
+ onComposeSend: { takeOver: async () => 'default' },
+ onTransformOutgoingEmail: { transform: async (email: unknown) => email },
+ },
+ contactHooks: {
+ search: { call: async () => [] },
+ onProvideRecipientSuggestions: { transform: async (initial: unknown) => initial },
+ },
+}));
+
+vi.mock('@/lib/email-sanitization', () => ({
+ sanitizeSignatureHtml: (v: string) => v,
+ sanitizeEmailHtml: (v: string) => v,
+ parseHtmlSafely: (html: string) => new DOMParser().parseFromString(html, 'text/html'),
+}));
+
+vi.mock('@/lib/email-threading', () => ({
+ computeReplyThreadingHeaders: () => ({ inReplyTo: [], references: [] }),
+}));
+vi.mock('@/lib/signature-utils', () => ({
+ appendPlainTextSignature: (body: string) => body,
+ getPlainTextSignature: () => '',
+}));
+vi.mock('@/lib/sub-addressing', () => ({ generateSubAddress: () => '' }));
+vi.mock('@/lib/debug', () => ({ debug: { log: () => {}, warn: () => {}, error: () => {} } }));
+vi.mock('@/components/email/quoted-html', () => ({
+ buildQuotedHtmlBlock: () => '',
+ serializeEditorContent: () => '',
+}));
+vi.mock('@/lib/template-utils', () => ({ substitutePlaceholders: (s: string) => s }));
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+/**
+ * Before an automatic sign-out (organisation idle timeout or maximum session
+ * length) every composer saves what the server doesn't have yet, through the
+ * compose flush registry.
+ */
+
+const DRAFT: ComposerDraftData = {
+ to: 'bob@example.com',
+ cc: '',
+ bcc: '',
+ subject: 'Half-written',
+ body: 'Still typing
',
+ showCc: false,
+ showBcc: false,
+ selectedIdentityId: 'id-me',
+ subAddressTag: '',
+ mode: 'compose',
+ draftId: null,
+};
+
+let createDraft: ReturnType;
+
+beforeEach(() => {
+ resetComposeFlushRegistry();
+ createDraft = vi.fn().mockResolvedValue('draft-1');
+ useAuthStore.setState({
+ client: { createDraft, getEmail: vi.fn(), hasDelayedSend: () => false, getMaxDelayedSend: () => 0 } as never,
+ });
+});
+
+afterEach(() => {
+ useAuthStore.setState({ client: null });
+});
+
+describe('composer flush before an automatic sign-out', () => {
+ it('saves edits the autosave has not stored yet', async () => {
+ render(> | undefined;
+ await act(async () => { result = await flushComposers(5000); });
+
+ expect(result).toEqual({ total: 1, settled: 1, timedOut: false });
+ expect(createDraft).toHaveBeenCalledTimes(1);
+ expect(createDraft.mock.calls[0][1]).toBe('Half-written more');
+ });
+
+ it('leaves a composer without changes alone', async () => {
+ render( = {};
@@ -2266,6 +2270,19 @@ export function MailApp({ linkSegments: routeSegments }: MailAppProps = {}) {
setPendingDraft(null);
}, []);
+ // A minimised composer's edits live only in pendingDraft. Before an
+ // automatic sign-out it is opened again and saves them itself.
+ const minimisedUnsaved = !showComposer && pendingDraft?.unsaved === true;
+ useEffect(() => {
+ if (!minimisedUnsaved) return;
+ return registerComposeFlush(async () => {
+ const reopened = waitForComposeFlush(MINIMISED_COMPOSER_REOPEN_MS);
+ setShowComposer(true);
+ const flush = await reopened;
+ await flush?.();
+ });
+ }, [minimisedUnsaved]);
+
const handleReply = async (draftText?: string) => {
if (selectedEmail) {
const formerSelected = { ...selectedEmail };
diff --git a/lib/__tests__/compose-flush-registry.test.ts b/lib/__tests__/compose-flush-registry.test.ts
new file mode 100644
index 000000000..3858bb358
--- /dev/null
+++ b/lib/__tests__/compose-flush-registry.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+ flushComposers,
+ registerComposeFlush,
+ resetComposeFlushRegistry,
+ waitForComposeFlush,
+} from '../compose-flush-registry';
+
+describe('compose flush registry', () => {
+ beforeEach(() => {
+ resetComposeFlushRegistry();
+ vi.useFakeTimers();
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('runs every registered flush and waits for them', async () => {
+ const order: string[] = [];
+ registerComposeFlush(async () => {
+ await new Promise((r) => setTimeout(r, 100));
+ order.push('a');
+ });
+ registerComposeFlush(async () => { order.push('b'); });
+
+ const done = flushComposers(5000);
+ await vi.advanceTimersByTimeAsync(100);
+ await expect(done).resolves.toEqual({ total: 2, settled: 2, timedOut: false });
+ expect(order.sort()).toEqual(['a', 'b']);
+ });
+
+ it('stops waiting for a hanging flush at the timeout', async () => {
+ const quick = vi.fn(async () => {});
+ registerComposeFlush(() => new Promise(() => {}));
+ registerComposeFlush(quick);
+
+ let result: Awaited> | null = null;
+ void flushComposers(3000).then((r) => { result = r; });
+ await vi.advanceTimersByTimeAsync(2999);
+ expect(result).toBeNull();
+ await vi.advanceTimersByTimeAsync(1);
+ expect(result).toEqual({ total: 2, settled: 1, timedOut: true });
+ expect(quick).toHaveBeenCalledTimes(1);
+ });
+
+ it('goes on when a flush fails', async () => {
+ registerComposeFlush(async () => { throw new Error('save refused'); });
+ await expect(flushComposers(1000)).resolves.toEqual({ total: 1, settled: 1, timedOut: false });
+ });
+
+ it('forgets a composer that unregistered', async () => {
+ const flush = vi.fn(async () => {});
+ const unregister = registerComposeFlush(flush);
+ unregister();
+ await expect(flushComposers(1000)).resolves.toEqual({ total: 0, settled: 0, timedOut: false });
+ expect(flush).not.toHaveBeenCalled();
+ });
+
+ it('hands the next registration to a waiting host, or null after the timeout', async () => {
+ const waiting = waitForComposeFlush(500);
+ const flush = vi.fn(async () => {});
+ registerComposeFlush(flush);
+ await expect(waiting).resolves.toBe(flush);
+
+ const nobody = waitForComposeFlush(500);
+ await vi.advanceTimersByTimeAsync(500);
+ await expect(nobody).resolves.toBeNull();
+ });
+});
diff --git a/lib/compose-flush-registry.ts b/lib/compose-flush-registry.ts
new file mode 100644
index 000000000..8af821e9e
--- /dev/null
+++ b/lib/compose-flush-registry.ts
@@ -0,0 +1,82 @@
+/**
+ * Composers that hold text the server may not have yet. An automatic
+ * sign-out (the organisation's idle timeout or maximum session length) saves
+ * them as drafts before the credentials go: each open composer registers a
+ * `flush` that runs its own draft save, and the host of a minimised composer
+ * (its state lives only in the host's memory) registers one that reopens it
+ * so the composer can save itself.
+ *
+ * A flush that hangs must not keep the user signed in, so flushComposers
+ * waits at most `timeoutMs` for all of them together.
+ */
+
+export type ComposeFlush = () => Promise;
+
+let nextId = 1;
+const flushes = new Map();
+const waiters = new Set<(flush: ComposeFlush) => void>();
+
+/** Register a composer's flush; returns the unregister function. */
+export function registerComposeFlush(flush: ComposeFlush): () => void {
+ const id = nextId++;
+ flushes.set(id, flush);
+ for (const waiter of [...waiters]) waiter(flush);
+ return () => {
+ flushes.delete(id);
+ };
+}
+
+/**
+ * The flush of the next composer to register, or null after `timeoutMs`.
+ * A minimised composer's host reopens it and waits for it here.
+ */
+export function waitForComposeFlush(timeoutMs: number): Promise {
+ return new Promise((resolve) => {
+ const waiter = (flush: ComposeFlush) => {
+ clearTimeout(timer);
+ waiters.delete(waiter);
+ resolve(flush);
+ };
+ const timer = setTimeout(() => {
+ waiters.delete(waiter);
+ resolve(null);
+ }, timeoutMs);
+ waiters.add(waiter);
+ });
+}
+
+export interface FlushResult {
+ /** Flushes that were registered when the sign-out started. */
+ total: number;
+ /** Flushes that finished (or failed) in time. */
+ settled: number;
+ timedOut: boolean;
+}
+
+/** Run every registered flush and wait for them, but no longer than `timeoutMs`. */
+export async function flushComposers(timeoutMs: number): Promise {
+ const pending = [...flushes.values()];
+ if (pending.length === 0) return { total: 0, settled: 0, timedOut: false };
+ let settled = 0;
+ const all = Promise.all(pending.map(async (flush) => {
+ try {
+ await flush();
+ } catch {
+ // A failed save is the composer's to report; the sign-out goes on.
+ }
+ settled += 1;
+ }));
+ let timer: ReturnType | undefined;
+ const timedOut = await Promise.race([
+ all.then(() => false),
+ new Promise((resolve) => { timer = setTimeout(() => resolve(true), timeoutMs); }),
+ ]);
+ clearTimeout(timer);
+ return { total: pending.length, settled, timedOut };
+}
+
+/** Test helper: forget every registration. */
+export function resetComposeFlushRegistry(): void {
+ flushes.clear();
+ waiters.clear();
+}
From 2855ca00104847d96efec089083d2d7dda201d35 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 01:59:13 +0100
Subject: [PATCH 012/137] feat: confirm before sending to recipients outside
the organisation
---
app/(main)/[locale]/layout.tsx | 2 +
.../composer-external-recipients.test.tsx | 278 ++++++++++++++++++
.../email/external-recipient-confirm.tsx | 83 ++++++
.../__tests__/external-recipients.test.ts | 112 +++++++
lib/outgoing/external-recipients.ts | 74 +++++
locales/de/common.json | 9 +-
locales/en/common.json | 9 +-
stores/external-recipient-confirm-store.ts | 31 ++
8 files changed, 596 insertions(+), 2 deletions(-)
create mode 100644 components/email/__tests__/composer-external-recipients.test.tsx
create mode 100644 components/email/external-recipient-confirm.tsx
create mode 100644 lib/outgoing/__tests__/external-recipients.test.ts
create mode 100644 lib/outgoing/external-recipients.ts
create mode 100644 stores/external-recipient-confirm-store.ts
diff --git a/app/(main)/[locale]/layout.tsx b/app/(main)/[locale]/layout.tsx
index 76f9396ad..eab9e2482 100644
--- a/app/(main)/[locale]/layout.tsx
+++ b/app/(main)/[locale]/layout.tsx
@@ -10,6 +10,7 @@ import { ProtocolLaunchHandlerProvider } from "@/components/protocol/protocol-la
import { ProInterfaceRedirect } from "@/components/pro/pro-interface-redirect";
import { ImpersonationReconciler } from "@/components/impersonation/impersonation-reconciler";
import { PluginDialogHost } from "@/components/plugins/plugin-dialog-host";
+import { ExternalRecipientConfirmHost } from "@/components/email/external-recipient-confirm";
import { CommandPaletteHost } from "@/components/command-palette/command-palette";
import { PluginConnectDialog } from "@/components/plugins/plugin-connect-dialog";
import { QuickRuleHost } from "@/components/filters/quick-rule-host";
@@ -63,6 +64,7 @@ export default async function LocaleLayout({
) => Object.assign(state, p);
+ return { useAuthStore: hook };
+});
+
+vi.mock('@/stores/identity-store', () => {
+ const state = {
+ identities: [
+ { id: 'id-me', email: 'me@example.com', name: 'Me' },
+ { id: 'id-sales', email: 'sales@example.com', name: 'Sales' },
+ ] as Array>,
+ defaultIdentityId: 'id-me',
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useIdentityStore: hook };
+});
+
+vi.mock('@/stores/account-store', () => {
+ const state = { accounts: [], getAccountById: () => undefined };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useAccountStore: hook };
+});
+
+vi.mock('@/stores/email-store', () => {
+ const state = {
+ draftSaveEnabled: false,
+ sendRawEmail: async () => ({ sent: true }),
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useEmailStore: hook };
+});
+
+vi.mock('@/stores/settings-store', () => {
+ const state = {
+ timeFormat: '24h',
+ plainTextMode: false,
+ subAddressDelimiter: '+',
+ autoSelectReplyIdentity: true,
+ attachmentReminderEnabled: false,
+ attachmentReminderKeywords: [],
+ emptySubjectWarningEnabled: true,
+ sendDelaySeconds: 0,
+ // The default position: replies/forwards get the signature appended at
+ // send time rather than embedded above the quote.
+ signaturePosition: 'below_quote',
+ signatureSeparatorEnabled: true,
+ requestReadReceiptDefault: false,
+ addTrustedSender: () => {},
+ trustedSendersAddressBook: null,
+ updateSetting: () => {},
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useSettingsStore: hook };
+});
+
+vi.mock('@/stores/contact-store', () => {
+ const state = {
+ contacts: [],
+ getAutocomplete: async () => [],
+ addToTrustedSendersBook: async () => {},
+ };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useContactStore: hook };
+});
+
+vi.mock('@/stores/template-store', () => {
+ const state = { templates: [], addTemplate: async () => {} };
+ const hook = (sel?: (s: typeof state) => unknown) =>
+ typeof sel === 'function' ? sel(state) : state;
+ hook.getState = () => state;
+ hook.setState = (p: Partial) => Object.assign(state, p);
+ return { useTemplateStore: hook };
+});
+
+// ─── Misc dependency mocks ────────────────────────────────────────────────────
+
+vi.mock('@/stores/toast-store', () => ({
+ toast: { info: () => {}, error: () => {}, success: () => {} },
+}));
+
+vi.mock('@/lib/plugin-hooks', () => ({
+ identityHooks: {
+ onSignatureRender: { size: 0, transform: async (value: unknown) => value },
+ onIdentitySelect: { size: 0, emit: async () => {} },
+ },
+ templateHooks: {
+ onTemplateRender: { size: 0, transform: async (value: unknown) => value },
+ onTemplateApply: { size: 0, emit: async () => {} },
+ },
+ emailHooks: {
+ onComposerOpen: { call: async () => [] },
+ onRecipientChange: { call: async () => [] },
+ getRecipientSuggestions: { call: async () => [] },
+ onRecipientChipsChange: { transform: async (chips: unknown) => chips },
+ onDraftChange: { emit: () => {} },
+ onBeforeDraftAutoSave: { transform: async (draft: unknown) => draft },
+ onBeforeEmailSend: { intercept: async () => true, interceptOutcome: async () => 'allowed' },
+ onComposeSend: { takeOver: async () => 'default' },
+ onTransformOutgoingEmail: { transform: async (email: unknown) => email },
+ },
+ contactHooks: {
+ search: { call: async () => [] },
+ onProvideRecipientSuggestions: { transform: async (initial: unknown) => initial },
+ },
+}));
+
+vi.mock('@/lib/email-sanitization', () => ({
+ sanitizeSignatureHtml: (v: string) => v,
+ sanitizeSignatureHtmlForDisplay: (v: string) => v,
+ sanitizeEmailHtml: (v: string) => v,
+ sanitizePluginBodyHtml: (v: string) => v,
+ escapeHtml: (v: string) => v,
+ parseHtmlSafely: (html: string) => new DOMParser().parseFromString(html, 'text/html'),
+}));
+
+vi.mock('@/lib/email-threading', () => ({
+ computeReplyThreadingHeaders: () => ({ inReplyTo: [], references: [] }),
+}));
+vi.mock('@/lib/sub-addressing', () => ({ generateSubAddress: () => '' }));
+vi.mock('@/lib/debug', () => ({ debug: { log: () => {}, warn: () => {}, error: () => {} } }));
+vi.mock('@/components/email/quoted-html', () => ({
+ buildQuotedHtmlBlock: () => '',
+ serializeEditorContent: () => '',
+}));
+vi.mock('@/lib/template-utils', () => ({ substitutePlaceholders: (s: string) => s }));
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+// The external-recipient confirm in the real composer: the check is
+// registered by the dialog host, asks only about the recipients outside the
+// organisation, and the composer sends or not by the user's answer.
+
+const DRAFT = {
+ to: 'bob@example.com, dave@org-two.test',
+ cc: 'carol@example.com',
+ bcc: '',
+ subject: 'Hello',
+ body: 'Hi
',
+ showCc: true,
+ showBcc: false,
+ selectedIdentityId: 'id-me',
+ subAddressTag: '',
+ mode: 'compose' as const,
+ draftId: null,
+};
+
+function setExternalMail(patch: Partial) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+function clickSend() {
+ fireEvent.click(screen.getAllByTestId('composer-send')[0]);
+}
+
+function renderComposer(onSend: () => void) {
+ return render(
+ <>
+ {
+ if (e.target === e.currentTarget) answer(false);
+ }}
+ >
+
+
+
+
+
+
+
{t('confirm_title')}
+
+ {t('confirm_message', { count: recipients.length })}
+
+
+
+
+ {recipients.map((recipient) => (
+
+ {field[recipient.field]}
+ {recipient.address}
+
+ ))}
+
+
+
+ {/* Back comes first, so the focus trap puts the focus on it: sending outside takes a deliberate click. */}
+ answer(false)} data-external-recipient-back="">
+ {t('back')}
+
+ answer(true)} data-external-recipient-send="">
+ {t('send_anyway')}
+
+
+
+
) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+const context = (to: string[], cc: string[] = [], bcc: string[] = []): OutgoingContext => ({
+ surface: 'composer', to, cc, bcc, fromEmail: 'org-alice@example.org', identityId: 'i1', mode: 'compose', plainText: false,
+});
+
+beforeEach(() => {
+ setExternalMail({ recipientWarning: true });
+ useAuthStore.setState({ client: null, identities: [{ id: 'i1', name: 'Org Alice', email: 'org-alice@example.org' } as unknown as Identity] });
+ useContactStore.setState({ contacts: [], contactsLoaded: true });
+ useExternalRecipientConfirmStore.setState({ pending: null });
+});
+afterEach(() => resetSendPipeline());
+
+describe('externalRecipientCheck', () => {
+ it('does not ask while the warning is off', async () => {
+ setExternalMail({ recipientWarning: false, senderLabel: true });
+ const ask = vi.fn(async () => false);
+ expect(await externalRecipientCheck(context(['org-dave@org-two.test']), ask)).toBe(true);
+ expect(ask).not.toHaveBeenCalled();
+ });
+
+ it('does not ask when every recipient is internal, subdomains included', async () => {
+ const ask = vi.fn(async () => false);
+ expect(await externalRecipientCheck(context(['org-bob@example.org'], ['x@eu.example.org']), ask)).toBe(true);
+ expect(ask).not.toHaveBeenCalled();
+ });
+
+ it('asks about the external recipients only and returns the answer', async () => {
+ const ask = vi.fn(async () => false);
+ const recipients = context(['org-bob@example.org', 'org-dave@org-two.test'], [], ['eve@other.net']);
+ expect(await externalRecipientCheck(recipients, ask)).toBe(false);
+ expect(ask).toHaveBeenCalledWith([
+ { address: 'org-dave@org-two.test', domain: 'org-two.test', field: 'to' },
+ { address: 'eve@other.net', domain: 'other.net', field: 'bcc' },
+ ]);
+ ask.mockResolvedValueOnce(true);
+ expect(await externalRecipientCheck(recipients, ask)).toBe(true);
+ });
+
+ it('counts the admin domains as internal', async () => {
+ setExternalMail({ recipientWarning: true, domains: ['org-two.test'] });
+ const ask = vi.fn(async () => false);
+ expect(await externalRecipientCheck(context(['org-dave@org-two.test']), ask)).toBe(true);
+ expect(ask).not.toHaveBeenCalled();
+ });
+
+ it('trusts contacts only while trustContacts is on', async () => {
+ useContactStore.setState({
+ contacts: [{ id: 'c1', emails: { e: { address: 'Org-Dave@org-two.test' } } }] as unknown as ContactCard[],
+ });
+ const ask = vi.fn(async () => false);
+ expect(await externalRecipientCheck(context(['org-dave@org-two.test']), ask)).toBe(true);
+ expect(ask).not.toHaveBeenCalled();
+
+ setExternalMail({ recipientWarning: true, trustContacts: false });
+ expect(await externalRecipientCheck(context(['org-dave@org-two.test']), ask)).toBe(false);
+ expect(ask).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('quick reply goes through the same confirm', () => {
+ const input = { body: 'Thanks', signatureIdentity: null, separator: true, to: ['org-dave@org-two.test'], fromEmail: 'org-alice@example.org', identityId: 'i1' };
+
+ async function answerWhenAsked(send: boolean) {
+ await vi.waitFor(() => expect(useExternalRecipientConfirmStore.getState().pending).not.toBeNull());
+ expect(useExternalRecipientConfirmStore.getState().pending?.recipients.map((r) => r.address)).toEqual(['org-dave@org-two.test']);
+ useExternalRecipientConfirmStore.getState().answer(send);
+ }
+
+ it('sends nothing on Back', async () => {
+ registerExternalRecipientCheck();
+ const result = prepareQuickReply(input);
+ await answerWhenAsked(false);
+ expect(await result).toBeNull();
+ });
+
+ it('returns the bodies on Send anyway', async () => {
+ registerExternalRecipientCheck();
+ const result = prepareQuickReply(input);
+ await answerWhenAsked(true);
+ expect((await result)?.text).toContain('Thanks');
+ });
+
+ it('does not ask for a reply to an internal sender', async () => {
+ registerExternalRecipientCheck();
+ const result = await prepareQuickReply({ ...input, to: ['org-bob@example.org'] });
+ expect(result?.text).toContain('Thanks');
+ expect(useExternalRecipientConfirmStore.getState().pending).toBeNull();
+ });
+});
diff --git a/lib/outgoing/external-recipients.ts b/lib/outgoing/external-recipients.ts
new file mode 100644
index 000000000..e7f2b4cb4
--- /dev/null
+++ b/lib/outgoing/external-recipients.ts
@@ -0,0 +1,74 @@
+/**
+ * The pre-send check behind "Send outside your organisation?": when the
+ * admin turned the recipient warning on, recipients outside the
+ * organisation (and, with trustContacts, not in the user's contacts) are
+ * listed in one confirm. Runs for every surface that sends through the
+ * pipeline: the composer and quick reply.
+ */
+
+import {
+ addressDomain,
+ contactAddresses,
+ currentExternalMailPolicy,
+ currentInternalDomains,
+ externalRecipients,
+ type ExternalRecipient,
+} from '@/lib/external-mail';
+import { useAuthStore } from '@/stores/auth-store';
+import { useContactStore } from '@/stores/contact-store';
+import { useExternalRecipientConfirmStore } from '@/stores/external-recipient-confirm-store';
+import { registerPreSendCheck, type OutgoingContext } from './send-pipeline';
+import { debug } from '@/lib/debug';
+
+export const EXTERNAL_RECIPIENT_CHECK_ID = 'external-recipients';
+/** After the composer's own checks (attachment, subject, placeholders), before anything later. */
+const ORDER = 40;
+/** Longest the send waits for the contacts to load the first time. */
+const CONTACTS_WAIT_MS = 3000;
+
+async function ensureContactsLoaded(): Promise {
+ const contacts = useContactStore.getState();
+ if (contacts.contactsLoaded) return;
+ const client = useAuthStore.getState().client;
+ if (!client) return;
+ try {
+ await Promise.race([
+ contacts.fetchContacts(client),
+ new Promise((resolve) => setTimeout(resolve, CONTACTS_WAIT_MS)),
+ ]);
+ } catch (error) {
+ debug.error('Could not load contacts for the external-recipient check:', error);
+ }
+}
+
+/** The recipients the user is asked about; empty when the check doesn't apply. */
+export async function recipientsToConfirm(context: OutgoingContext): Promise {
+ const policy = currentExternalMailPolicy();
+ if (!policy.recipientWarning) return [];
+ // The From address is one of the user's own, even an override typed in the composer.
+ const fromDomain = addressDomain(context.fromEmail);
+ const internal = currentInternalDomains(policy);
+ if (fromDomain && !internal.includes(fromDomain)) internal.push(fromDomain);
+ let trusted: ((address: string) => boolean) | undefined;
+ if (policy.trustContacts) {
+ await ensureContactsLoaded();
+ const known = contactAddresses();
+ trusted = (address) => known.has(address);
+ }
+ return externalRecipients(context, internal, trusted);
+}
+
+/** True to send: nobody external, or the user chose "Send anyway". */
+export async function externalRecipientCheck(
+ context: OutgoingContext,
+ ask: (recipients: ExternalRecipient[]) => Promise = (recipients) => useExternalRecipientConfirmStore.getState().ask(recipients),
+): Promise {
+ const recipients = await recipientsToConfirm(context);
+ if (recipients.length === 0) return true;
+ return ask(recipients);
+}
+
+/** Called by the dialog host once it is mounted; returns the unregister function. */
+export function registerExternalRecipientCheck(): () => void {
+ return registerPreSendCheck(EXTERNAL_RECIPIENT_CHECK_ID, ORDER, (context) => externalRecipientCheck(context));
+}
diff --git a/locales/de/common.json b/locales/de/common.json
index 73f54a823..729bb80ca 100644
--- a/locales/de/common.json
+++ b/locales/de/common.json
@@ -661,7 +661,14 @@
},
"external_mail": {
"sender_label": "Extern",
- "sender_tooltip": "Von außerhalb Ihrer Organisation: {domain}"
+ "sender_tooltip": "Von außerhalb Ihrer Organisation: {domain}",
+ "confirm_title": "Außerhalb Ihrer Organisation senden?",
+ "confirm_message": "{count, plural, one {Dieser Empfänger ist} other {Diese # Empfänger sind}} außerhalb Ihrer Organisation. Senden Sie nur, wenn das so gewollt ist.",
+ "field_to": "An",
+ "field_cc": "Cc",
+ "field_bcc": "Bcc",
+ "send_anyway": "Trotzdem senden",
+ "back": "Zurück"
},
"email_composer": {
"select_from_directory": "Aus Verzeichnis auswählen",
diff --git a/locales/en/common.json b/locales/en/common.json
index 60734aa9d..b8c4ecb2c 100644
--- a/locales/en/common.json
+++ b/locales/en/common.json
@@ -661,7 +661,14 @@
},
"external_mail": {
"sender_label": "External",
- "sender_tooltip": "From outside your organisation: {domain}"
+ "sender_tooltip": "From outside your organisation: {domain}",
+ "confirm_title": "Send outside your organisation?",
+ "confirm_message": "{count, plural, one {This recipient is} other {These # recipients are}} outside your organisation. Send only if you mean to.",
+ "field_to": "To",
+ "field_cc": "Cc",
+ "field_bcc": "Bcc",
+ "send_anyway": "Send anyway",
+ "back": "Back"
},
"email_composer": {
"select_from_directory": "Select from directory",
diff --git a/stores/external-recipient-confirm-store.ts b/stores/external-recipient-confirm-store.ts
new file mode 100644
index 000000000..45e3304e5
--- /dev/null
+++ b/stores/external-recipient-confirm-store.ts
@@ -0,0 +1,31 @@
+import { create } from 'zustand';
+import type { ExternalRecipient } from '@/lib/external-mail';
+
+/**
+ * The one open "Send outside your organisation?" question. The pre-send
+ * check asks, the dialog (components/email/external-recipient-confirm.tsx)
+ * shows it and answers. Asking again while a question is open answers the
+ * old one with "Back", so no send waits forever.
+ */
+interface ExternalRecipientConfirmState {
+ pending: { recipients: ExternalRecipient[]; resolve: (send: boolean) => void } | null;
+ /** Resolves true for "Send anyway", false for "Back". */
+ ask: (recipients: ExternalRecipient[]) => Promise;
+ answer: (send: boolean) => void;
+}
+
+export const useExternalRecipientConfirmStore = create()((set, get) => ({
+ pending: null,
+ ask: (recipients) => {
+ get().pending?.resolve(false);
+ return new Promise((resolve) => {
+ set({ pending: { recipients, resolve } });
+ });
+ },
+ answer: (send) => {
+ const pending = get().pending;
+ if (!pending) return;
+ set({ pending: null });
+ pending.resolve(send);
+ },
+}));
From ab878ebf4fbc84de1ddf46e8c63a5ecee2bf3015 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 02:10:10 +0100
Subject: [PATCH 013/137] feat: tell plugins when Bulwark's own external mail
warnings are on and skip the retired plugin's
---
.../__tests__/plugin-slot-handover.test.tsx | 47 ++++++
components/plugins/plugin-slot.tsx | 12 +-
.../plugin-external-mail-handover.test.ts | 105 +++++++++++++
lib/__tests__/plugin-host-features.test.ts | 143 ++++++++++++++++++
lib/plugin-sandbox/host-bridge.ts | 23 ++-
lib/plugin-sandbox/host-features.ts | 65 ++++++++
lib/plugin-sandbox/loader.ts | 8 +-
lib/plugin-sandbox/protocol.ts | 10 +-
lib/plugin-sandbox/runtime.tsx | 34 ++++-
lib/plugin-types.ts | 14 ++
10 files changed, 455 insertions(+), 6 deletions(-)
create mode 100644 components/plugins/__tests__/plugin-slot-handover.test.tsx
create mode 100644 lib/__tests__/plugin-external-mail-handover.test.ts
create mode 100644 lib/__tests__/plugin-host-features.test.ts
create mode 100644 lib/plugin-sandbox/host-features.ts
diff --git a/components/plugins/__tests__/plugin-slot-handover.test.tsx b/components/plugins/__tests__/plugin-slot-handover.test.tsx
new file mode 100644
index 000000000..24cb78e67
--- /dev/null
+++ b/components/plugins/__tests__/plugin-slot-handover.test.tsx
@@ -0,0 +1,47 @@
+import { render, act, cleanup } from '@testing-library/react';
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { DEFAULT_ORGANISATION_POLICY } from '@/lib/admin/organisation-policy';
+import { DEFAULT_POLICY } from '@/lib/admin/types';
+import { usePolicyStore } from '@/stores/policy-store';
+import { clearSlotOffers, offerSlots } from './fake-slot-offer';
+
+vi.mock('@/components/plugins/plugin-iframe-slot', () => import('@/components/plugins/__tests__/fake-slot-offer'));
+
+const { PluginSlot } = await import('../plugin-slot');
+
+// The retired external-mail-warning plugin's banner stays away while the
+// organisation's own External label or recipient warning is on, so the
+// reader doesn't show both; other plugins' banners stay.
+
+function setExternalMail(patch: Partial) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+const frames = (container: HTMLElement) =>
+ [...container.querySelectorAll('[data-testid="plugin-frame-email-banner"]')].map((el) => el.getAttribute('data-plugin-id'));
+
+beforeEach(() => {
+ setExternalMail({});
+ offerSlots('external-mail-warning', ['email-banner']);
+ offerSlots('spam-score', ['email-banner']);
+});
+afterEach(() => {
+ cleanup();
+ clearSlotOffers();
+});
+
+describe('email-banner slot while core external warnings are on', () => {
+ it('shows the plugin banner while they are off and hides it as soon as one is on', () => {
+ const { container } = render(,
+}));
+
+const CODE = 'export default { activate() {} }';
+const HASH = createHash('sha256').update(CODE, 'utf-8').digest('hex');
+
+vi.mock('../plugin-storage', () => ({
+ pluginStorage: { getCode: async () => CODE, saveCode: async () => {}, deleteCode: vi.fn() },
+}));
+vi.mock('../plugin-sandbox/bundle-fetch', () => ({ downloadManagedBundle: vi.fn() }));
+vi.mock('../plugin-sandbox/host-bridge', () => ({
+ createBackgroundInstance: () => {
+ // The old plugin's check: "Send to external recipients?" answered with Cancel.
+ const invokeHook = vi.fn(async () => false);
+ mocks.invokeHook = invokeHook;
+ return {
+ initPromise: Promise.resolve({ hooks: mocks.hooks, slots: [], shortcuts: [] }),
+ invokeHook,
+ destroy: vi.fn(),
+ };
+ },
+ snapshotRegionalSettings: vi.fn((locale: string) => ({ locale, dateLocale: locale, hour12: false, timeZone: 'UTC', firstDayOfWeek: 1 })),
+ forEachInstance: vi.fn(),
+ SandboxInstance: class {},
+}));
+vi.mock('../plugin-sandbox/host-api', () => ({ cancelPluginDialogs: vi.fn() }));
+vi.mock('../plugin-sandbox/shortcuts', () => ({ registerShortcuts: () => () => {} }));
+
+import { loadSandboxedPlugin, unloadSandboxedPlugin, setSandboxStoreAccessor } from '../plugin-sandbox/loader';
+import { emailHooks } from '../plugin-hooks';
+import { DEFAULT_ORGANISATION_POLICY } from '@/lib/admin/organisation-policy';
+import { DEFAULT_POLICY } from '@/lib/admin/types';
+import { usePolicyStore } from '@/stores/policy-store';
+
+function plugin(id: string): InstalledPlugin {
+ return {
+ id, name: id, version: '1.5.1', author: 'someone', description: '', type: 'hook',
+ permissions: ['email:send', 'email:read'], entrypoint: 'index.js', enabled: true, status: 'enabled',
+ settings: {}, managed: true, adminApproved: true, bundleHash: HASH,
+ };
+}
+
+function setExternalMail(patch: Partial) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+const OUTGOING = { to: ['dave@org-two.test'], cc: [], bcc: [], subject: 'Hi' };
+let loaded: string | null = null;
+
+beforeEach(() => {
+ setSandboxStoreAccessor({ setPluginStatus: () => {} });
+ mocks.hooks = ['onBeforeEmailSend', 'onNewEmailReceived'];
+ setExternalMail({});
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ vi.spyOn(console, 'info').mockImplementation(() => {});
+});
+afterEach(() => {
+ if (loaded) unloadSandboxedPlugin(loaded);
+ loaded = null;
+ vi.restoreAllMocks();
+});
+
+describe('the retired external-mail-warning plugin', () => {
+ it('asks as before while the core warnings are off', async () => {
+ loaded = 'external-mail-warning';
+ await loadSandboxedPlugin(plugin(loaded));
+ expect(await emailHooks.onBeforeEmailSend.interceptOutcome(OUTGOING as never)).toBe('vetoed');
+ expect(mocks.invokeHook).toHaveBeenCalledWith('onBeforeEmailSend', [OUTGOING]);
+ });
+
+ it('is skipped while the core warnings are on, and asked again once they are off', async () => {
+ loaded = 'external-mail-warning';
+ await loadSandboxedPlugin(plugin(loaded));
+ setExternalMail({ senderLabel: true });
+ expect(await emailHooks.onBeforeEmailSend.interceptOutcome(OUTGOING as never)).toBe('allowed');
+ await emailHooks.onNewEmailReceived.emit({ from: [{ email: 'dave@org-two.test' }] } as never);
+ expect(mocks.invokeHook).not.toHaveBeenCalled();
+
+ setExternalMail({});
+ expect(await emailHooks.onBeforeEmailSend.interceptOutcome(OUTGOING as never)).toBe('vetoed');
+ });
+
+ it('leaves the send checks of other plugins alone', async () => {
+ loaded = 'reply-all-guardrail';
+ await loadSandboxedPlugin(plugin(loaded));
+ setExternalMail({ recipientWarning: true });
+ expect(await emailHooks.onBeforeEmailSend.interceptOutcome(OUTGOING as never)).toBe('vetoed');
+ });
+});
diff --git a/lib/__tests__/plugin-host-features.test.ts b/lib/__tests__/plugin-host-features.test.ts
new file mode 100644
index 000000000..ea665ba73
--- /dev/null
+++ b/lib/__tests__/plugin-host-features.test.ts
@@ -0,0 +1,143 @@
+/**
+ * api.host.features tells plugins which of Bulwark's own features replace
+ * them (externalMailWarnings: the organisation's External label or
+ * recipient warning). The host sends it with init and again on every
+ * change; the runtime keeps one object up to date.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import React from 'react';
+import { render, cleanup, waitFor } from '@testing-library/react';
+import { DEFAULT_ORGANISATION_POLICY } from '@/lib/admin/organisation-policy';
+import { DEFAULT_POLICY } from '@/lib/admin/types';
+import { usePolicyStore } from '@/stores/policy-store';
+import {
+ EXTERNAL_MAIL_WARNING_PLUGIN_ID,
+ isHookHandedOver,
+ isSlotHandedOver,
+ snapshotHostFeatures,
+} from '@/lib/plugin-sandbox/host-features';
+
+function setExternalMail(patch: Partial) {
+ usePolicyStore.setState({
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, externalMail: { ...DEFAULT_ORGANISATION_POLICY.externalMail, ...patch } },
+ },
+ });
+}
+
+beforeEach(() => setExternalMail({}));
+
+describe('snapshotHostFeatures', () => {
+ it('says externalMailWarnings while either switch is on', () => {
+ expect(snapshotHostFeatures()).toEqual({ externalMailWarnings: false });
+ setExternalMail({ senderLabel: true });
+ expect(snapshotHostFeatures()).toEqual({ externalMailWarnings: true });
+ setExternalMail({ recipientWarning: true });
+ expect(snapshotHostFeatures()).toEqual({ externalMailWarnings: true });
+ });
+});
+
+describe('hand-over of the external-mail-warning plugin', () => {
+ it('skips its send check, toast and banner only while core warnings are on', () => {
+ const id = EXTERNAL_MAIL_WARNING_PLUGIN_ID;
+ expect(isHookHandedOver(id, 'onBeforeEmailSend')).toBe(false);
+ expect(isSlotHandedOver(id, 'email-banner')).toBe(false);
+ setExternalMail({ recipientWarning: true });
+ expect(isHookHandedOver(id, 'onBeforeEmailSend')).toBe(true);
+ expect(isHookHandedOver(id, 'onNewEmailReceived')).toBe(true);
+ expect(isSlotHandedOver(id, 'email-banner')).toBe(true);
+ // Its other hooks, and every other plugin, keep running.
+ expect(isHookHandedOver(id, 'onIdentitiesLoaded')).toBe(false);
+ expect(isHookHandedOver('reply-all-guardrail', 'onBeforeEmailSend')).toBe(false);
+ expect(isSlotHandedOver('spam-score', 'email-banner')).toBe(false);
+ });
+});
+
+// ─── Host bridge: init payload and pushes ────────────────────
+
+describe('host bridge', () => {
+ afterEach(() => { document.body.innerHTML = ''; });
+
+ it('puts the features into the init payload and pushes changes to running frames', async () => {
+ const { createBackgroundInstance } = await import('@/lib/plugin-sandbox/host-bridge');
+ setExternalMail({ senderLabel: true });
+ const plugin = { id: 'p', name: 'P', version: '1.0.0', permissions: [], settings: {}, settingsSchema: {} } as never;
+ const instance = createBackgroundInstance({ plugin, tier: 'privileged', code: '', locale: 'en' });
+ const pending = (instance as unknown as { pendingInit: { hostFeatures?: unknown } | null }).pendingInit;
+ expect(pending?.hostFeatures).toEqual({ externalMailWarnings: true });
+
+ // Before init has gone out a change lands in the payload ...
+ setExternalMail({});
+ expect(pending?.hostFeatures).toEqual({ externalMailWarnings: false });
+
+ // ... after it, as a host-change message.
+ const sent: unknown[] = [];
+ (instance as unknown as { pendingInit: unknown }).pendingInit = null;
+ (instance as unknown as { send: (m: unknown) => void }).send = (m) => sent.push(m);
+ setExternalMail({ recipientWarning: true });
+ expect(sent).toEqual([{ type: 'host-change', features: { externalMailWarnings: true } }]);
+ instance.destroy();
+ }, 30_000);
+});
+
+// ─── Sandbox runtime: api.host.features ──────────────────────
+
+const HOST_ORIGIN = window.location.origin;
+
+function post(source: unknown, origin: string, data: unknown): void {
+ const ev = new MessageEvent('message', { data, origin });
+ Object.defineProperty(ev, 'source', { value: source });
+ window.dispatchEvent(ev);
+}
+
+describe('api.host in the sandbox runtime', () => {
+ let hostWindow: { postMessage: ReturnType };
+ const realParent = Object.getOwnPropertyDescriptor(window, 'parent');
+ const g = globalThis as {
+ __pluginApi?: { host: { features: { externalMailWarnings: boolean }; onFeaturesChange(fn: (f: unknown) => void): () => void } };
+ __seenAtActivate?: boolean;
+ };
+
+ beforeEach(() => {
+ vi.resetModules();
+ hostWindow = { postMessage: vi.fn() };
+ Object.defineProperty(window, 'parent', { configurable: true, get: () => hostWindow as unknown as Window });
+ vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} });
+ });
+ afterEach(() => {
+ cleanup();
+ vi.unstubAllGlobals();
+ delete g.__pluginApi;
+ delete g.__seenAtActivate;
+ if (realParent) Object.defineProperty(window, 'parent', realParent);
+ });
+
+ it('has the value from init in activate and follows host-change', async () => {
+ const bundle = `module.exports = { activate: function (api) {
+ globalThis.__seenAtActivate = api.host.features.externalMailWarnings;
+ globalThis.__pluginApi = api;
+ } };`;
+ const { SandboxRuntime } = await import('@/lib/plugin-sandbox/runtime');
+ render(React.createElement(SandboxRuntime));
+ post(hostWindow, HOST_ORIGIN, {
+ type: 'init',
+ payload: {
+ mode: 'background', pluginId: 'x', tier: 'privileged', locale: 'en',
+ manifest: { id: 'x', version: '1.0.0', permissions: [], settings: {} },
+ code: bundle,
+ hostFeatures: { externalMailWarnings: true },
+ },
+ });
+ await waitFor(() => expect(g.__pluginApi).toBeDefined());
+ expect(g.__seenAtActivate).toBe(true);
+
+ const api = g.__pluginApi!;
+ const kept = api.host.features;
+ const changes: unknown[] = [];
+ api.host.onFeaturesChange((f) => changes.push({ ...(f as object) }));
+ post(hostWindow, HOST_ORIGIN, { type: 'host-change', features: { externalMailWarnings: false } });
+ expect(kept.externalMailWarnings).toBe(false);
+ expect(changes).toEqual([{ externalMailWarnings: false }]);
+ }, 30_000);
+});
diff --git a/lib/plugin-sandbox/host-bridge.ts b/lib/plugin-sandbox/host-bridge.ts
index db5a39018..1d0e7d67c 100644
--- a/lib/plugin-sandbox/host-bridge.ts
+++ b/lib/plugin-sandbox/host-bridge.ts
@@ -7,12 +7,13 @@
// `event.source === iframe.contentWindow`. The iframe's runtime pins the
// parent on the first inbound message.
-import type { InstalledPlugin, SlotName, PluginTier } from '../plugin-types';
+import type { HostFeaturesView, InstalledPlugin, SlotName, PluginTier } from '../plugin-types';
import { dispatchApiCall } from './host-api';
import { SANDBOX_PATH, SANDBOX_PRIVILEGED_PATH, type RegionalSnapshot } from './protocol';
export type { RegionalSnapshot };
import { withBasePath } from '../browser-navigation';
import { snapshotHostTheme, type ThemeSnapshot } from './host-theme';
+import { snapshotHostFeatures, watchHostFeatures } from './host-features';
import { effectiveSettings } from '../plugin-settings';
import { clampSlotHeight, clampSlotWidth, isInlineSlot, MAX_INLINE_SLOT_WIDTH } from './slot-layout';
import { resolveDateLocale } from '../utils';
@@ -252,6 +253,13 @@ function pushThemeToFrames(): void {
}
}
+/** Every frame hears about a Bulwark feature that replaces plugins turning on or off. */
+function pushHostFeaturesToFrames(features: HostFeaturesView): void {
+ for (const instance of liveInstances) {
+ try { instance.setHostFeatures(features); } catch { /* one broken iframe must not stop the rest */ }
+ }
+}
+
function ensureThemeWatcher(): void {
if (themeWatcher || typeof MutationObserver === 'undefined' || typeof document === 'undefined') return;
let scheduled = false;
@@ -414,6 +422,7 @@ export class SandboxInstance {
hostContainer.appendChild(this.iframe);
liveInstances.add(this);
if (this.mode === 'slot') ensureThemeWatcher();
+ watchHostFeatures(pushHostFeaturesToFrames);
// Send init after the iframe runtime signals it's ready.
this.readyPromise.then(() => {
@@ -637,6 +646,16 @@ export class SandboxInstance {
this.send({ type: 'theme-change', theme });
}
+ /** Push what api.host.features says now; before init it goes into the init payload. */
+ setHostFeatures(features: HostFeaturesView): void {
+ if (this.destroyed) return;
+ if (this.pendingInit) {
+ this.pendingInit.hostFeatures = features;
+ return;
+ }
+ this.send({ type: 'host-change', features });
+ }
+
/** Push the plugin's current settings (see effectiveSettings). */
setSettings(settings: Record): void {
if (this.destroyed) return;
@@ -735,6 +754,7 @@ export function createBackgroundInstance(opts: BackgroundOptions): SandboxInstan
code: opts.code,
locale: opts.locale,
regional: opts.regional ?? snapshotRegionalSettings(opts.locale),
+ hostFeatures: snapshotHostFeatures(),
};
return new SandboxInstance(
opts.plugin,
@@ -764,6 +784,7 @@ export function createSlotInstance(opts: SlotOptions): SandboxInstance {
locale: opts.locale,
regional: opts.regional ?? snapshotRegionalSettings(opts.locale),
theme: snapshotHostTheme(),
+ hostFeatures: snapshotHostFeatures(),
};
return new SandboxInstance(opts.plugin, payload, opts.hostContainer, opts.onResize, opts.onFloatingDropdown);
}
diff --git a/lib/plugin-sandbox/host-features.ts b/lib/plugin-sandbox/host-features.ts
new file mode 100644
index 000000000..f9721ba19
--- /dev/null
+++ b/lib/plugin-sandbox/host-features.ts
@@ -0,0 +1,65 @@
+// What the host tells plugins about its own features (`api.host.features`),
+// so a plugin can step back where Bulwark now does the job itself. Sent with
+// every frame's init and again whenever it changes (the admin's policy, an
+// account switch to another scope).
+//
+// And the other half of that hand-over: copies of a plugin core replaced
+// that are older than the release which knows the flag keep running their
+// hooks. While core does the job, the host skips those hooks by plugin id.
+
+import { usePolicyStore } from '@/stores/policy-store';
+import type { HostFeaturesView } from '../plugin-types';
+import type { OrganisationPolicy } from '@/lib/admin/organisation-policy';
+
+/**
+ * Either external-mail switch is on. The same rule as coreExternalWarningsOn
+ * (lib/external-mail.ts), kept apart so the sandbox doesn't pull in the
+ * account and contact stores.
+ */
+export function externalWarningsOn(externalMail: OrganisationPolicy['externalMail'] | undefined): boolean {
+ return !!externalMail && (externalMail.senderLabel || externalMail.recipientWarning);
+}
+
+export function snapshotHostFeatures(): HostFeaturesView {
+ return { externalMailWarnings: externalWarningsOn(usePolicyStore.getState().getOrganisation().externalMail) };
+}
+
+/** The external-mail-warning plugin, retired in favour of organisation.externalMail. */
+export const EXTERNAL_MAIL_WARNING_PLUGIN_ID = 'external-mail-warning';
+
+/** Its send check and its new-mail toast; its banner is the email-banner slot. */
+const EXTERNAL_MAIL_WARNING_HOOKS = new Set(['onBeforeEmailSend', 'onNewEmailReceived']);
+const EXTERNAL_MAIL_WARNING_SLOTS = new Set(['email-banner']);
+
+/** True when core does this plugin hook's job right now, so the host skips it. */
+export function isHookHandedOver(pluginId: string, hookName: string): boolean {
+ return pluginId === EXTERNAL_MAIL_WARNING_PLUGIN_ID
+ && EXTERNAL_MAIL_WARNING_HOOKS.has(hookName)
+ && snapshotHostFeatures().externalMailWarnings;
+}
+
+/** True when core does this plugin slot's job right now, so the host doesn't show it. */
+export function isSlotHandedOver(pluginId: string, slot: string, features: HostFeaturesView = snapshotHostFeatures()): boolean {
+ return pluginId === EXTERNAL_MAIL_WARNING_PLUGIN_ID
+ && EXTERNAL_MAIL_WARNING_SLOTS.has(slot)
+ && features.externalMailWarnings;
+}
+
+// ─── Change watch ────────────────────────────────────────────
+
+let watching = false;
+let lastKey = '';
+
+/** Calls `onChange` with the new features whenever they change; set up once. */
+export function watchHostFeatures(onChange: (features: HostFeaturesView) => void): void {
+ if (watching) return;
+ watching = true;
+ lastKey = JSON.stringify(snapshotHostFeatures());
+ usePolicyStore.subscribe(() => {
+ const features = snapshotHostFeatures();
+ const key = JSON.stringify(features);
+ if (key === lastKey) return;
+ lastKey = key;
+ onChange(features);
+ });
+}
diff --git a/lib/plugin-sandbox/loader.ts b/lib/plugin-sandbox/loader.ts
index a95b2bc47..bbf79ef99 100644
--- a/lib/plugin-sandbox/loader.ts
+++ b/lib/plugin-sandbox/loader.ts
@@ -31,6 +31,7 @@ import { clearPluginPages } from './pages';
import { clearSectionTitle } from './section-titles';
import { cancelPluginProxyRequests } from './proxy-client';
import { cancelConnectFor } from './connect-dialog';
+import { isHookHandedOver } from './host-features';
import type { SlotName } from '../plugin-types';
// ─── Hook-bus lookup (one flat map for name → bus) ────────────
@@ -280,7 +281,12 @@ async function startSandboxedPlugin(plugin: InstalledPlugin): Promise {
}
// The bus records a failure once; recording it here too made the
// three-strikes breaker trip on the second error.
- const proxy = (...args: unknown[]) => bg.invokeHook(hookName, args);
+ // While Bulwark does a retired plugin's job itself, that plugin's
+ // hook is skipped: copies older than the release that steps back on
+ // its own would ask twice (host-features.ts). Asked per call, so
+ // turning the core switch off gives the plugin its hook back.
+ const pluginId = plugin.id;
+ const proxy = (...args: unknown[]) => (isHookHandedOver(pluginId, hookName) ? undefined : bg.invokeHook(hookName, args));
hookDisposables.push(bus.register(plugin.id, proxy as (...a: unknown[]) => unknown));
if (hookName === 'onEmailOpen') openHandler = proxy;
}
diff --git a/lib/plugin-sandbox/protocol.ts b/lib/plugin-sandbox/protocol.ts
index 0dda74f34..c947991a9 100644
--- a/lib/plugin-sandbox/protocol.ts
+++ b/lib/plugin-sandbox/protocol.ts
@@ -8,7 +8,7 @@
// the boundary must be structured-cloneable: no functions, no DOM nodes, no
// class instances.
-import type { SlotName, PluginTier } from '../plugin-types';
+import type { SlotName, PluginTier, HostFeaturesView } from '../plugin-types';
import type { ThemeSnapshot } from './host-theme';
/** Resolved presentation/regional settings mirrored into plugin runtimes. */
@@ -50,6 +50,8 @@ export interface BackgroundInit {
locale: string;
/** Resolved presentation/regional preferences (time format, date locale, time zone). */
regional?: RegionalSnapshot;
+ /** Bulwark features that replace plugins (api.host.features); host pushes updates via 'host-change'. */
+ hostFeatures?: HostFeaturesView;
}
/** Initialisation payload for a slot-instance iframe (one per slot mount). */
@@ -97,6 +99,8 @@ export interface SlotInit {
* injected CSS + a `.dark` class. Host pushes updates via 'theme-change'.
*/
theme: ThemeSnapshot;
+ /** Mirrors `BackgroundInit.hostFeatures`. */
+ hostFeatures?: HostFeaturesView;
}
export type InitPayload = BackgroundInit | SlotInit;
@@ -265,6 +269,9 @@ export interface ThemeChangeMsg { type: 'theme-change'; theme: ThemeSnapshot; }
/** Host → sandbox: the user changed this plugin's settings. */
export interface SettingsChangeMsg { type: 'settings-change'; settings: Record; }
+/** Host → sandbox: a Bulwark feature that replaces plugins was turned on or off. */
+export interface HostChangeMsg { type: 'host-change'; features: HostFeaturesView; }
+
export interface PropsUpdateMsg { type: 'props-update'; props: Record; }
export interface SlotShouldShowMsg {
@@ -309,6 +316,7 @@ export type HostToSandbox =
| LocaleChangeMsg
| ThemeChangeMsg
| SettingsChangeMsg
+ | HostChangeMsg
| PropsUpdateMsg
| SlotShouldShowMsg
| FloatingDropdownSelectMsg
diff --git a/lib/plugin-sandbox/runtime.tsx b/lib/plugin-sandbox/runtime.tsx
index 3f8f46405..748de7916 100644
--- a/lib/plugin-sandbox/runtime.tsx
+++ b/lib/plugin-sandbox/runtime.tsx
@@ -33,7 +33,7 @@ import { initFloatingDropdownBridge, dispatchFloatingDropdownEvent } from './ui-
import { interpolate, lookup, textDirection, type LocaleTables } from './plugin-i18n';
import { isFillableSlot, isInlineSlot, MAX_INLINE_SLOT_WIDTH } from './slot-layout';
import type {
- AppInfoView, AppSettingsView, SettingsSearchResult, CalendarEventInput, CalendarEventView, CalendarView, ComposeInput, DraftInput, EmailReadView,
+ AppInfoView, AppSettingsView, HostFeaturesView, SettingsSearchResult, CalendarEventInput, CalendarEventView, CalendarView, ComposeInput, DraftInput, EmailReadView,
EmailSummary, IdentityPatch, IdentityView, MailboxView, NotificationInput, SlotName, TaskInput,
TaskView, TemplateInput, TemplateView, VacationInput, VacationView,
} from '../plugin-types';
@@ -148,6 +148,18 @@ function applySettings(next: Record): void {
try { listener(settingsState); } catch (err) { console.error('[plugin] settings listener failed', err); }
}
}
+// What api.host.features says: one object for the iframe's lifetime,
+// updated in place on 'host-change' like the settings.
+const hostFeaturesState: HostFeaturesView = { externalMailWarnings: false };
+const hostFeatureListeners = new Set<(features: HostFeaturesView) => void>();
+
+function applyHostFeatures(next: HostFeaturesView | undefined): void {
+ if (!next) return;
+ hostFeaturesState.externalMailWarnings = next.externalMailWarnings === true;
+ for (const listener of hostFeatureListeners) {
+ try { listener(hostFeaturesState); } catch (err) { console.error('[plugin] host feature listener failed', err); }
+ }
+}
const pendingCallbacks = new Map void; reject: (err: Error) => void }>();
const hookHandlers: Record unknown> = {};
@@ -375,6 +387,18 @@ function buildPluginApi(manifest: PluginManifest) {
return () => { settingsListeners.delete(listener); };
},
},
+ /**
+ * Bulwark features that replace what plugins did, so a plugin can step
+ * back while Bulwark does its job. Updated in place; no permission needed.
+ */
+ host: {
+ features: hostFeaturesState,
+ /** Called with the new features whenever one turns on or off. Returns an unsubscribe function. */
+ onFeaturesChange: (listener: (features: HostFeaturesView) => void) => {
+ hostFeatureListeners.add(listener);
+ return () => { hostFeatureListeners.delete(listener); };
+ },
+ },
/** The app the plugin runs in: product, the administrator's name for it, version, edition. No permission needed. */
app: {
getInfo: () => callApi('app.getInfo', []) as Promise,
@@ -1143,9 +1167,11 @@ async function bootSlot(payload: SlotInit): Promise {
const bump = () => setSettingsVersion((v) => v + 1);
settingsListeners.add(bump);
localeListeners.add(bump);
+ hostFeatureListeners.add(bump);
return () => {
settingsListeners.delete(bump);
localeListeners.delete(bump);
+ hostFeatureListeners.delete(bump);
};
}, []);
React.useEffect(() => {
@@ -1193,6 +1219,8 @@ async function handleInit(payload: InitPayload): Promise {
// Make the active locale available to plugin code (api.i18n) right away -
// not only after the first 'locale-change' push.
applyLocale(payload.locale, payload.regional);
+ // Before the bundle runs, so activate() and shouldShow already see it.
+ applyHostFeatures(payload.hostFeatures);
try {
if (payload.mode === 'background') {
await bootBackground(payload);
@@ -1289,6 +1317,10 @@ function handleHostMessage(ev: MessageEvent): void {
applySettings(msg.settings ?? {});
break;
+ case 'host-change':
+ applyHostFeatures(msg.features);
+ break;
+
case 'props-update':
if (slotPropsUpdater) slotPropsUpdater(msg.props ?? {});
else if (mode === 'slot') propsBeforeBoot = msg.props ?? {};
diff --git a/lib/plugin-types.ts b/lib/plugin-types.ts
index 9fc9b4959..3660d9d5c 100644
--- a/lib/plugin-types.ts
+++ b/lib/plugin-types.ts
@@ -837,6 +837,20 @@ export interface AppInfoView {
demoMode: boolean;
}
+/**
+ * Features of Bulwark itself that replace what a plugin did, as
+ * `api.host.features` tells the plugin (no permission needed). A plugin
+ * that does the same job steps back while one is true. Missing on hosts
+ * older than 1.19.0, so read it as `api.host?.features?.x === true`.
+ */
+export interface HostFeaturesView {
+ /**
+ * The admin turned on the "External" sender label or the external
+ * recipient warning (policy organisation.externalMail) for this user.
+ */
+ externalMailWarnings: boolean;
+}
+
/** One setting `api.app.searchSettings` found, in the user's language. */
export interface SettingsSearchResult {
/** The settings page's id: account, appearance, composing, vacation, ... */
From 45cc6988e051c46d37481008bc23e084191e75a6 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Wed, 28 Oct 2026 02:18:07 +0100
Subject: [PATCH 014/137] feat: sign out after an admin-set idle time or
session length, with a warning first
---
app/(main)/[locale]/layout.tsx | 2 +
app/(main)/[locale]/login/page.tsx | 17 +-
.../admin/org/sections/sessions-section.tsx | 87 ++++++-
.../__tests__/session-timeout-guard.test.tsx | 232 ++++++++++++++++++
components/session/session-timeout-dialog.tsx | 85 +++++++
components/session/session-timeout-guard.tsx | 221 +++++++++++++++++
.../host-api-app-session-timeout.test.ts | 43 ++++
lib/plugin-sandbox/host-api-app.ts | 8 +
.../__tests__/activity-channel.test.ts | 69 ++++++
lib/session-policy/__tests__/limits.test.ts | 34 +++
.../__tests__/session-timer.test.ts | 143 +++++++++++
lib/session-policy/activity-channel.ts | 72 ++++++
lib/session-policy/limits.ts | 60 +++++
lib/session-policy/session-timer.ts | 139 +++++++++++
lib/session-policy/sign-out-reason.ts | 33 +++
locales/de/common.json | 12 +
locales/en/common.json | 12 +
.../auth-store-provider-logout.test.ts | 16 ++
stores/account-store.ts | 6 +
stores/auth-store.ts | 15 +-
20 files changed, 1294 insertions(+), 12 deletions(-)
create mode 100644 components/session/__tests__/session-timeout-guard.test.tsx
create mode 100644 components/session/session-timeout-dialog.tsx
create mode 100644 components/session/session-timeout-guard.tsx
create mode 100644 lib/plugin-sandbox/__tests__/host-api-app-session-timeout.test.ts
create mode 100644 lib/session-policy/__tests__/activity-channel.test.ts
create mode 100644 lib/session-policy/__tests__/limits.test.ts
create mode 100644 lib/session-policy/__tests__/session-timer.test.ts
create mode 100644 lib/session-policy/activity-channel.ts
create mode 100644 lib/session-policy/limits.ts
create mode 100644 lib/session-policy/session-timer.ts
create mode 100644 lib/session-policy/sign-out-reason.ts
diff --git a/app/(main)/[locale]/layout.tsx b/app/(main)/[locale]/layout.tsx
index 76f9396ad..31c983c1d 100644
--- a/app/(main)/[locale]/layout.tsx
+++ b/app/(main)/[locale]/layout.tsx
@@ -19,6 +19,7 @@ import { PluginOAuthCallbackListener } from "@/components/providers/plugin-oauth
import { PWAInstallPrompt } from "@/components/pwa-install-prompt";
import { PushNotificationPrompt } from "@/components/push-notification-prompt";
import { AccountArchiveRestorePrompt } from "@/components/account-archive-prompt";
+import { SessionTimeoutGuard } from "@/components/session/session-timeout-guard";
import { IS_LITE } from "@/lib/lite";
import { setRequestLocale } from "next-intl/server";
import { locales } from "@/i18n/routing";
@@ -61,6 +62,7 @@ export default async function LocaleLayout({
(null);
const [sessionExpired, setSessionExpired] = useState(false);
+ // Signed out by the organisation's idle timeout or maximum session length.
+ const [sessionEnd, setSessionEnd] = useState(null);
const [showPassword, setShowPassword] = useState(false);
const [shakeError, setShakeError] = useState(false);
const [showThemeMenu, setShowThemeMenu] = useState(false);
@@ -332,6 +336,11 @@ function LoginPageContent() {
sessionStorage.removeItem('session_expired');
}
} catch { /* sessionStorage unavailable */ }
+ const ended = consumeSessionEnd();
+ if (ended) {
+ setSessionEnd(ended);
+ setSessionExpired(true);
+ }
}, []);
useEffect(() => {
@@ -1229,8 +1238,12 @@ function LoginPageContent() {
-
- {t("session_expired")}
+
+ {sessionEnd?.kind === "idle"
+ ? tSessionLimits("reason_idle", { minutes: sessionEnd.minutes })
+ : sessionEnd?.kind === "max"
+ ? tSessionLimits("reason_max", { hours: sessionEnd.hours })
+ : t("session_expired")}
0 ? `${value} ${field.unit}` : field.zero;
+}
+
+/** Organisation > Security > Sessions: the idle timeout and the maximum session length. */
export function SessionsSection({ draft }: { draft: OrgPolicyDraft }) {
- void draft;
return (
-
- Nothing to set here yet.
+
+ {FIELDS.map((field) => {
+ const { value, own, everyone } = draft.orgValue('session', field.key);
+ const inputId = `org-session-${field.key}`;
+ return (
+
+
+
+ {field.unit}
+
+
draft.clearOrgValue('session', field.key)}
+ />
+
+ );
+ })}
);
}
diff --git a/components/session/__tests__/session-timeout-guard.test.tsx b/components/session/__tests__/session-timeout-guard.test.tsx
new file mode 100644
index 000000000..f693eb685
--- /dev/null
+++ b/components/session/__tests__/session-timeout-guard.test.tsx
@@ -0,0 +1,232 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SessionTimeoutGuard, DRAFT_FLUSH_TIMEOUT_MS } from '../session-timeout-guard';
+import { useAuthStore } from '@/stores/auth-store';
+import { useAccountStore, type AccountEntry } from '@/stores/account-store';
+import { usePolicyStore } from '@/stores/policy-store';
+import { DEFAULT_POLICY, type SettingsPolicy } from '@/lib/admin/types';
+import { DEFAULT_ORGANISATION_POLICY } from '@/lib/admin/organisation-policy';
+import { registerComposeFlush, resetComposeFlushRegistry } from '@/lib/compose-flush-registry';
+import { consumeSessionEnd } from '@/lib/session-policy/sign-out-reason';
+import { LAST_ACTIVITY_KEY } from '@/lib/session-policy/activity-channel';
+
+/** BroadcastChannel between "tabs" of one test. */
+class FakeBroadcastChannel {
+ static instances: FakeBroadcastChannel[] = [];
+ onmessage: ((event: MessageEvent) => void) | null = null;
+ closed = false;
+ constructor(public name: string) {
+ FakeBroadcastChannel.instances.push(this);
+ }
+ postMessage(data: unknown) {
+ for (const other of FakeBroadcastChannel.instances) {
+ if (other !== this && !other.closed && other.name === this.name) other.onmessage?.({ data } as MessageEvent);
+ }
+ }
+ close() {
+ this.closed = true;
+ }
+}
+
+const START = new Date('2026-10-28T09:00:00Z').getTime();
+const SECOND = 1000;
+
+function fakeClient(email: string) {
+ return {
+ getUsername: () => email,
+ getSharedAccounts: () => [],
+ getAccountInfo: () => undefined,
+ getPrincipalTypes: async () => ({}),
+ };
+}
+
+function account(id: string, email: string, signedInAt = START): AccountEntry {
+ return {
+ id, label: email, serverUrl: 'https://mail.example.org', username: email, authMode: 'basic', cookieSlot: 0,
+ rememberMe: true, displayName: email, email, avatarColor: '#336699', lastLoginAt: START, signedInAt,
+ isConnected: true, hasError: false, isDefault: true,
+ };
+}
+
+function policyWith(session: { idleMinutes: number; maxHours: number; warnSeconds: number }, scopes: SettingsPolicy['scopes'] = []): SettingsPolicy {
+ return { ...DEFAULT_POLICY, organisation: { ...DEFAULT_ORGANISATION_POLICY, session }, scopes };
+}
+
+let logoutAll: ReturnType;
+const realGetAllConnectedClients = useAuthStore.getState().getAllConnectedClients;
+
+async function signIn(policy: SettingsPolicy, email = 'org-alice@example.org') {
+ usePolicyStore.setState({ rawPolicy: policy });
+ useAccountStore.setState({ accounts: [account('alice', email)], activeAccountId: 'alice' });
+ useAuthStore.setState({
+ isAuthenticated: true,
+ isDemoMode: false,
+ activeAccountId: 'alice',
+ client: fakeClient(email) as never,
+ logoutAll: logoutAll as never,
+ });
+ render((() => {}));
+
+ await advance(60 * SECOND);
+ await advance(DRAFT_FLUSH_TIMEOUT_MS - 1);
+ expect(logoutAll).not.toHaveBeenCalled();
+ await advance(1);
+ expect(logoutAll).toHaveBeenCalledWith({ endProviderSession: false });
+ });
+
+ it('uses the strictest of the signed-in accounts', async () => {
+ const policy = policyWith({ idleMinutes: 0, maxHours: 0, warnSeconds: 30 }, [
+ { id: 'example', label: 'example.org', match: { domains: ['example.org'] }, policy: { organisation: { session: { idleMinutes: 10 } } } },
+ { id: 'two', label: 'org-two.test', match: { domains: ['org-two.test'] }, policy: { organisation: { session: { idleMinutes: 2 } } } },
+ ]);
+ usePolicyStore.setState({ rawPolicy: policy });
+ useAccountStore.setState({ accounts: [account('alice', 'org-alice@example.org'), account('dave', 'org-dave@org-two.test')], activeAccountId: 'alice' });
+ const alice = fakeClient('org-alice@example.org');
+ const dave = fakeClient('org-dave@org-two.test');
+ useAuthStore.setState({
+ isAuthenticated: true,
+ isDemoMode: false,
+ activeAccountId: 'alice',
+ client: alice as never,
+ logoutAll: logoutAll as never,
+ getAllConnectedClients: (() => new Map([['alice', alice], ['dave', dave]])) as never,
+ });
+ render(
+
+
+
+ {mode === "ending" ?
+
+
{title}
+ {mode !== "ending" && (
+
+ {mode === "max"
+ ? t("max_message", { hours: maxHours ?? 0, seconds })
+ : t("idle_message", { seconds })}
+
+ )}
+
+
+ {mode !== "ending" && (
+
+ {t("sign_out_now")}
+ {mode === "idle"
+ ? {t("stay")}
+ : {t("dismiss")} }
+
+ )}
+
+
>();
+function subjectFor(client: IJMAPClient): Promise {
+ let subject = subjects.get(client);
+ if (!subject) {
+ subject = policySubjectForClient(client).catch(() => null);
+ subjects.set(client, subject);
+ }
+ return subject;
+}
+
+/** The limits of every account signed in here, each with its own domain and group scopes. */
+async function collectLimits(): Promise {
+ const auth = useAuthStore.getState();
+ const clients = new Map(auth.getAllConnectedClients());
+ if (auth.client && auth.activeAccountId && !clients.has(auth.activeAccountId)) clients.set(auth.activeAccountId, auth.client);
+ const accounts: AccountSession[] = await Promise.all([...clients.entries()].map(async ([accountId, client]) => {
+ const subject = await subjectFor(client);
+ const session = usePolicyStore.getState().resolveFor(subject).organisation?.session;
+ return { session, signedInAt: signedInAtFor(accountId) };
+ }));
+ return sessionLimits(accounts);
+}
+
+/**
+ * When the account signed in. An account signed in before this was recorded
+ * counts as signed in now, the first time it is seen.
+ */
+function signedInAtFor(accountId: string): number | undefined {
+ const store = useAccountStore.getState();
+ const account = store.getAccountById(accountId);
+ if (!account) return undefined;
+ if (typeof account.signedInAt === "number") return account.signedInAt;
+ const now = Date.now();
+ store.updateAccount(accountId, { signedInAt: now });
+ return now;
+}
+
+const IDLE_STATE: SessionTimerState = { phase: "active", kind: null, deadline: null };
+
+/**
+ * The organisation's idle timeout and maximum session length
+ * (policy.json `organisation.session`). Activity in any Bulwark tab keeps
+ * every tab signed in; a warning counts down first; at zero the open and
+ * minimised composers save their drafts and every account signs out, with
+ * the reason on the login page.
+ */
+export function SessionTimeoutGuard() {
+ const isAuthenticated = useAuthStore((s) => s.isAuthenticated);
+ const isDemoMode = useAuthStore((s) => s.isDemoMode);
+ const client = useAuthStore((s) => s.client);
+ const revision = useAuthStore((s) => s.connectedAccountsRevision);
+ const rawPolicy = usePolicyStore((s) => s.rawPolicy);
+ const accountsKey = useAccountStore((s) => s.accounts.map((a) => `${a.id}|${a.signedInAt ?? ""}|${a.isConnected}`).join(","));
+
+ const [limits, setLimits] = useState(NO_SESSION_LIMITS);
+ const [state, setState] = useState(IDLE_STATE);
+ const [ending, setEnding] = useState(false);
+ const [dismissedMax, setDismissedMax] = useState(null);
+ const timerRef = useRef(null);
+ const channelRef = useRef(null);
+ const limitsRef = useRef(limits);
+ limitsRef.current = limits;
+ const endingRef = useRef(false);
+ const active = isAuthenticated && !isDemoMode;
+
+ useEffect(() => {
+ if (!active) {
+ setLimits(NO_SESSION_LIMITS);
+ return;
+ }
+ let cancelled = false;
+ void collectLimits().then((next) => {
+ if (!cancelled) setLimits((prev) => (sameLimits(prev, next) ? prev : next));
+ });
+ return () => { cancelled = true; };
+ }, [active, client, revision, rawPolicy, accountsKey]);
+
+ useEffect(() => {
+ setCurrentSessionLimits(active ? limits : null);
+ }, [active, limits]);
+
+ const endSession = useCallback(async (kind: SessionEndKind) => {
+ if (endingRef.current) return;
+ endingRef.current = true;
+ setEnding(true);
+ const current = limitsRef.current;
+ rememberSessionEnd(kind === "max"
+ ? { kind: "max", hours: current.max?.hours ?? 0 }
+ : { kind: "idle", minutes: current.idle?.minutes ?? 0 });
+ await flushComposers(DRAFT_FLUSH_TIMEOUT_MS);
+ await useAuthStore.getState().logoutAll({ endProviderSession: false });
+ }, []);
+
+ // The clock, while there is a limit to count.
+ const hasLimits = active && (!!limits.idle || !!limits.max);
+ useEffect(() => {
+ if (!hasLimits) {
+ timerRef.current?.dispose();
+ timerRef.current = null;
+ setState(IDLE_STATE);
+ return;
+ }
+ if (timerRef.current) {
+ timerRef.current.setLimits(limits);
+ return;
+ }
+ // A tab opened or reloaded after a long pause starts from the pause, a
+ // fresh sign-in from the sign-in.
+ const newestSignIn = Math.max(0, ...useAccountStore.getState().accounts.map((a) => a.signedInAt ?? 0));
+ const lastActivity = Math.max(readLastActivity() ?? Date.now(), newestSignIn);
+ timerRef.current = createSessionTimer({
+ limits,
+ lastActivity,
+ onChange: setState,
+ onExpire: (kind) => { void endSession(kind); },
+ });
+ setState(timerRef.current.state());
+ }, [hasLimits, limits, endSession]);
+
+ useEffect(() => () => {
+ timerRef.current?.dispose();
+ timerRef.current = null;
+ }, []);
+
+ useEffect(() => {
+ if (!active) {
+ endingRef.current = false;
+ setEnding(false);
+ }
+ }, [active]);
+
+ // Activity in this tab and the others.
+ useEffect(() => {
+ const channel = openActivityChannel((at) => timerRef.current?.remoteActivity(at));
+ channelRef.current = channel;
+ let lastSeen = 0;
+ const onActivity = () => {
+ if (endingRef.current) return;
+ const at = Date.now();
+ if (at - lastSeen < ACTIVITY_THROTTLE_MS) return;
+ const timer = timerRef.current;
+ if (timer) {
+ timer.activity(at);
+ // During the idle warning only "Stay signed in" counts.
+ const s = timer.state();
+ if (s.phase === "expired" || (s.phase === "warning" && s.kind === "idle")) return;
+ }
+ lastSeen = at;
+ channel.post(at);
+ };
+ const onVisibility = () => {
+ if (document.visibilityState === "visible") timerRef.current?.check();
+ };
+ for (const event of ACTIVITY_EVENTS) window.addEventListener(event, onActivity, { capture: true, passive: true });
+ document.addEventListener("visibilitychange", onVisibility);
+ return () => {
+ for (const event of ACTIVITY_EVENTS) window.removeEventListener(event, onActivity, { capture: true });
+ document.removeEventListener("visibilitychange", onVisibility);
+ channel.close();
+ channelRef.current = null;
+ };
+ }, []);
+
+ const stay = useCallback(() => {
+ const timer = timerRef.current;
+ if (!timer) return;
+ timer.stay();
+ channelRef.current?.post(timer.lastActivity());
+ }, []);
+
+ const signOutNow = useCallback(() => {
+ const kind = timerRef.current?.state().kind ?? "idle";
+ void endSession(kind);
+ }, [endSession]);
+
+ if (!active) return null;
+ if (ending) {
+ return setDismissedMax(state.deadline)}
+ onSignOut={signOutNow}
+ />
+ );
+}
diff --git a/lib/plugin-sandbox/__tests__/host-api-app-session-timeout.test.ts b/lib/plugin-sandbox/__tests__/host-api-app-session-timeout.test.ts
new file mode 100644
index 000000000..a371e4192
--- /dev/null
+++ b/lib/plugin-sandbox/__tests__/host-api-app-session-timeout.test.ts
@@ -0,0 +1,43 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { doAppGetSettings } from '../host-api-app';
+import { usePolicyStore } from '@/stores/policy-store';
+import { useSettingsStore } from '@/stores/settings-store';
+import { DEFAULT_POLICY } from '@/lib/admin/types';
+import { DEFAULT_ORGANISATION_POLICY } from '@/lib/admin/organisation-policy';
+import { setCurrentSessionLimits } from '@/lib/session-policy/limits';
+
+/**
+ * Plugins read `sessionTimeout` from the settings view. The user setting of
+ * that name never did anything; the view reports the idle timeout the
+ * organisation set instead.
+ */
+describe('plugin settings view: sessionTimeout', () => {
+ beforeEach(() => {
+ useSettingsStore.setState({ sessionTimeout: 45 } as never);
+ usePolicyStore.setState({
+ rawPolicy: DEFAULT_POLICY,
+ policy: {
+ ...DEFAULT_POLICY,
+ organisation: { ...DEFAULT_ORGANISATION_POLICY, session: { idleMinutes: 20, maxHours: 0, warnSeconds: 60 } },
+ },
+ });
+ setCurrentSessionLimits(null);
+ });
+ afterEach(() => {
+ setCurrentSessionLimits(null);
+ });
+
+ it("reports the active account's idle timeout before the guard has looked at every account", () => {
+ expect(doAppGetSettings().sessionTimeout).toBe(20);
+ });
+
+ it('reports the strictest idle timeout of the signed-in accounts', () => {
+ setCurrentSessionLimits({ idle: { minutes: 5, warnSeconds: 60 }, max: null });
+ expect(doAppGetSettings().sessionTimeout).toBe(5);
+ });
+
+ it('reports 0 when no account has an idle timeout, whatever the old user setting says', () => {
+ setCurrentSessionLimits({ idle: null, max: null });
+ expect(doAppGetSettings().sessionTimeout).toBe(0);
+ });
+});
diff --git a/lib/plugin-sandbox/host-api-app.ts b/lib/plugin-sandbox/host-api-app.ts
index 86f7f58ad..b3ddc8968 100644
--- a/lib/plugin-sandbox/host-api-app.ts
+++ b/lib/plugin-sandbox/host-api-app.ts
@@ -17,6 +17,7 @@ import { productName } from '@/lib/product-name';
import {
collectSubResults, getByPath, tabKeywords, tabSearchPaths, withAppName, type SettingsSearchTab, type SubResult,
} from '@/lib/settings-search';
+import { currentSessionLimits } from '@/lib/session-policy/limits';
import type { AppSettingsView, SettingsSearchResult } from '../plugin-types';
type Messages = Record;
@@ -144,6 +145,13 @@ export function doAppGetSettings(): AppSettingsView {
if (typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) out[key] = value;
else if (Array.isArray(value) && value.every((v) => typeof v === 'number' || typeof v === 'string')) out[key] = value.slice(0, 20) as number[] | string[];
}
+ // Minutes without activity before Bulwark signs out (0 = never). The user
+ // setting of that name was never read; the organisation's idle timeout is
+ // what applies, the strictest of the accounts signed in here.
+ const limits = currentSessionLimits();
+ out.sessionTimeout = limits
+ ? limits.idle?.minutes ?? 0
+ : usePolicyStore.getState().getOrganisation().session.idleMinutes;
const theme = (useThemeStore.getState() as unknown as { theme?: unknown }).theme;
if (typeof theme === 'string') out.theme = theme;
const locale = useLocaleStore.getState().locale;
diff --git a/lib/session-policy/__tests__/activity-channel.test.ts b/lib/session-policy/__tests__/activity-channel.test.ts
new file mode 100644
index 000000000..beabf28e6
--- /dev/null
+++ b/lib/session-policy/__tests__/activity-channel.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { LAST_ACTIVITY_KEY, openActivityChannel, readLastActivity } from '../activity-channel';
+
+/** BroadcastChannel between "tabs" of one test: every instance of a name hears the others. */
+class FakeBroadcastChannel {
+ static instances: FakeBroadcastChannel[] = [];
+ onmessage: ((event: MessageEvent) => void) | null = null;
+ closed = false;
+ constructor(public name: string) {
+ FakeBroadcastChannel.instances.push(this);
+ }
+ postMessage(data: unknown) {
+ for (const other of FakeBroadcastChannel.instances) {
+ if (other !== this && !other.closed && other.name === this.name) other.onmessage?.({ data } as MessageEvent);
+ }
+ }
+ close() {
+ this.closed = true;
+ }
+}
+
+describe('activity shared between tabs', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ FakeBroadcastChannel.instances = [];
+ });
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it('tells the other tabs through a BroadcastChannel and keeps the time', () => {
+ vi.stubGlobal('BroadcastChannel', FakeBroadcastChannel);
+ const heardA = vi.fn();
+ const heardB = vi.fn();
+ const a = openActivityChannel(heardA);
+ const b = openActivityChannel(heardB);
+
+ a.post(1234);
+
+ expect(heardB).toHaveBeenCalledWith(1234);
+ expect(heardA).not.toHaveBeenCalled();
+ expect(readLastActivity()).toBe(1234);
+
+ b.close();
+ a.post(5678);
+ expect(heardB).toHaveBeenCalledTimes(1);
+ a.close();
+ });
+
+ it('falls back to storage events without BroadcastChannel', () => {
+ vi.stubGlobal('BroadcastChannel', undefined);
+ const heard = vi.fn();
+ const channel = openActivityChannel(heard);
+
+ // Another tab's write arrives as a storage event.
+ window.dispatchEvent(new StorageEvent('storage', { key: LAST_ACTIVITY_KEY, newValue: '4321' }));
+ window.dispatchEvent(new StorageEvent('storage', { key: 'something-else', newValue: '1' }));
+ window.dispatchEvent(new StorageEvent('storage', { key: LAST_ACTIVITY_KEY, newValue: 'garbage' }));
+ expect(heard).toHaveBeenCalledTimes(1);
+ expect(heard).toHaveBeenCalledWith(4321);
+
+ channel.post(9999);
+ expect(readLastActivity()).toBe(9999);
+
+ channel.close();
+ window.dispatchEvent(new StorageEvent('storage', { key: LAST_ACTIVITY_KEY, newValue: '5555' }));
+ expect(heard).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/lib/session-policy/__tests__/limits.test.ts b/lib/session-policy/__tests__/limits.test.ts
new file mode 100644
index 000000000..676a30e08
--- /dev/null
+++ b/lib/session-policy/__tests__/limits.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { sessionLimits } from '../limits';
+
+const HOUR = 60 * 60 * 1000;
+const session = (idleMinutes: number, maxHours: number, warnSeconds = 60) => ({ idleMinutes, maxHours, warnSeconds });
+
+describe('session limits of the signed-in accounts', () => {
+ it('takes the shortest idle time that is set', () => {
+ const limits = sessionLimits([
+ { session: session(30, 0, 120) },
+ { session: session(0, 0) },
+ { session: session(10, 0, 45) },
+ ]);
+ expect(limits.idle).toEqual({ minutes: 10, warnSeconds: 45 });
+ });
+
+ it('ignores accounts that set nothing', () => {
+ expect(sessionLimits([{ session: session(0, 0) }, { session: undefined }])).toEqual({ idle: null, max: null });
+ expect(sessionLimits([])).toEqual({ idle: null, max: null });
+ });
+
+ it('ends at the first maximum that runs out, counted from each sign-in', () => {
+ const limits = sessionLimits([
+ { session: session(0, 8), signedInAt: 10 * HOUR },
+ { session: session(0, 12), signedInAt: 0 },
+ { session: session(0, 4, 30), signedInAt: 9 * HOUR },
+ ]);
+ expect(limits.max).toEqual({ at: 12 * HOUR, hours: 12, warnSeconds: 60 });
+ });
+
+ it('needs a sign-in time to count a maximum', () => {
+ expect(sessionLimits([{ session: session(0, 8) }]).max).toBeNull();
+ });
+});
diff --git a/lib/session-policy/__tests__/session-timer.test.ts b/lib/session-policy/__tests__/session-timer.test.ts
new file mode 100644
index 000000000..f5fef76d2
--- /dev/null
+++ b/lib/session-policy/__tests__/session-timer.test.ts
@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createSessionTimer, type SessionTimerState } from '../session-timer';
+import type { SessionLimits } from '../limits';
+
+const START = new Date('2026-10-28T09:00:00Z').getTime();
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+
+const idleOnly = (minutes: number, warnSeconds: number): SessionLimits => ({ idle: { minutes, warnSeconds }, max: null });
+
+function setup(limits: SessionLimits) {
+ const states: SessionTimerState[] = [];
+ const onExpire = vi.fn();
+ const timer = createSessionTimer({ limits, lastActivity: Date.now(), onChange: (s) => states.push(s), onExpire });
+ return { timer, states, onExpire };
+}
+
+describe('session timer', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(START);
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('warns warnSeconds before the idle time runs out, then signs out at zero', () => {
+ const { timer, onExpire } = setup(idleOnly(1, 30));
+ expect(timer.state()).toMatchObject({ phase: 'active', kind: 'idle', deadline: START + MINUTE });
+
+ vi.advanceTimersByTime(30 * SECOND - 1);
+ expect(timer.state().phase).toBe('active');
+ vi.advanceTimersByTime(1);
+ expect(timer.state()).toMatchObject({ phase: 'warning', kind: 'idle', deadline: START + MINUTE });
+ expect(onExpire).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(30 * SECOND - 1);
+ expect(onExpire).not.toHaveBeenCalled();
+ vi.advanceTimersByTime(1);
+ expect(onExpire).toHaveBeenCalledWith('idle');
+ expect(timer.state().phase).toBe('expired');
+ timer.dispose();
+ });
+
+ it('starts the idle time again on activity before the warning', () => {
+ const { timer, onExpire } = setup(idleOnly(1, 30));
+ vi.advanceTimersByTime(20 * SECOND);
+ timer.activity();
+ // Without the reset the warning would have started at 30 s.
+ vi.advanceTimersByTime(29 * SECOND);
+ expect(timer.state().phase).toBe('active');
+ vi.advanceTimersByTime(1 * SECOND);
+ expect(timer.state().phase).toBe('warning');
+ expect(timer.state().deadline).toBe(START + 20 * SECOND + MINUTE);
+ vi.advanceTimersByTime(30 * SECOND);
+ expect(onExpire).toHaveBeenCalledTimes(1);
+ timer.dispose();
+ });
+
+ it('keeps the warning up on local activity until the user chooses to stay', () => {
+ const { timer, onExpire } = setup(idleOnly(1, 30));
+ vi.advanceTimersByTime(40 * SECOND);
+ expect(timer.state().phase).toBe('warning');
+
+ timer.activity();
+ expect(timer.state().phase).toBe('warning');
+
+ timer.stay();
+ expect(timer.state()).toMatchObject({ phase: 'active', deadline: START + 40 * SECOND + MINUTE });
+ vi.advanceTimersByTime(MINUTE - 1);
+ expect(onExpire).not.toHaveBeenCalled();
+ vi.advanceTimersByTime(1);
+ expect(onExpire).toHaveBeenCalledWith('idle');
+ timer.dispose();
+ });
+
+ it('ends the warning when another tab reports activity', () => {
+ const { timer, onExpire } = setup(idleOnly(1, 30));
+ vi.advanceTimersByTime(45 * SECOND);
+ expect(timer.state().phase).toBe('warning');
+
+ timer.remoteActivity(Date.now());
+ expect(timer.state().phase).toBe('active');
+ vi.advanceTimersByTime(MINUTE - 1);
+ expect(onExpire).not.toHaveBeenCalled();
+ timer.dispose();
+ });
+
+ it('signs out after a sleep even when the wake-up arrives as activity first', () => {
+ const { timer, onExpire } = setup(idleOnly(15, 60));
+ // The machine slept: the clock jumped, no timer ran.
+ vi.setSystemTime(START + 2 * 60 * MINUTE);
+ timer.activity();
+ expect(onExpire).toHaveBeenCalledWith('idle');
+ expect(timer.state().phase).toBe('expired');
+ timer.remoteActivity(Date.now());
+ timer.stay();
+ expect(onExpire).toHaveBeenCalledTimes(1);
+ timer.dispose();
+ });
+
+ it('runs no clock without limits', () => {
+ const { timer, onExpire } = setup({ idle: null, max: null });
+ expect(timer.state()).toEqual({ phase: 'active', kind: null, deadline: null });
+ vi.advanceTimersByTime(365 * 24 * 60 * MINUTE);
+ expect(onExpire).not.toHaveBeenCalled();
+ timer.dispose();
+ });
+
+ it('follows new limits', () => {
+ const { timer, onExpire } = setup({ idle: null, max: null });
+ vi.advanceTimersByTime(10 * MINUTE);
+ timer.setLimits(idleOnly(5, 60));
+ // The last activity was ten minutes ago: already past five minutes.
+ expect(onExpire).toHaveBeenCalledWith('idle');
+ timer.dispose();
+ });
+
+ it('warns before the maximum session length and does not move it on activity', () => {
+ const at = START + 2 * 60 * MINUTE;
+ const { timer, onExpire } = setup({ idle: { minutes: 30, warnSeconds: 60 }, max: { at, hours: 2, warnSeconds: 60 } });
+
+ for (let i = 0; i < 119; i++) {
+ vi.advanceTimersByTime(MINUTE);
+ timer.activity();
+ }
+ expect(timer.state()).toMatchObject({ phase: 'warning', kind: 'max', deadline: at });
+ timer.stay();
+ expect(timer.state()).toMatchObject({ phase: 'warning', kind: 'max' });
+ vi.advanceTimersByTime(MINUTE);
+ expect(onExpire).toHaveBeenCalledWith('max');
+ timer.dispose();
+ });
+
+ it('counts a maximum far away without running its timer early', () => {
+ const at = START + 365 * 24 * 60 * MINUTE;
+ const { timer, onExpire } = setup({ idle: null, max: { at, hours: 365 * 24, warnSeconds: 60 } });
+ vi.advanceTimersByTime(30 * 24 * 60 * MINUTE);
+ expect(onExpire).not.toHaveBeenCalled();
+ expect(timer.state().phase).toBe('active');
+ timer.dispose();
+ });
+});
diff --git a/lib/session-policy/activity-channel.ts b/lib/session-policy/activity-channel.ts
new file mode 100644
index 000000000..283560c89
--- /dev/null
+++ b/lib/session-policy/activity-channel.ts
@@ -0,0 +1,72 @@
+/**
+ * Activity shared between Bulwark tabs, so working in one tab keeps the
+ * others signed in. Tabs tell each other through a BroadcastChannel; where
+ * there is none, through `storage` events on a localStorage key. The last
+ * activity is also kept in localStorage, so a tab opened (or reloaded) after
+ * a long pause starts from it rather than from the page load.
+ */
+
+const CHANNEL = 'bulwark-session-activity';
+export const LAST_ACTIVITY_KEY = 'bulwark-last-activity';
+
+export interface ActivityChannel {
+ /** Tell the other tabs about activity at `at` (ms). */
+ post(at: number): void;
+ close(): void;
+}
+
+function parse(value: unknown): number | null {
+ const at = typeof value === 'string' ? Number(value) : value;
+ return typeof at === 'number' && Number.isFinite(at) && at > 0 ? at : null;
+}
+
+/** The last activity any tab recorded, or null. */
+export function readLastActivity(): number | null {
+ try {
+ return parse(window.localStorage.getItem(LAST_ACTIVITY_KEY));
+ } catch {
+ return null;
+ }
+}
+
+export function openActivityChannel(onActivity: (at: number) => void): ActivityChannel {
+ let channel: BroadcastChannel | null = null;
+ if (typeof BroadcastChannel !== 'undefined') {
+ try {
+ channel = new BroadcastChannel(CHANNEL);
+ channel.onmessage = (event: MessageEvent) => {
+ const at = parse((event.data as { at?: unknown } | null)?.at);
+ if (at) onActivity(at);
+ };
+ } catch {
+ channel = null;
+ }
+ }
+
+ // Without a channel, the localStorage write below reaches the other tabs as a storage event.
+ const onStorage = (event: StorageEvent) => {
+ if (event.key !== LAST_ACTIVITY_KEY) return;
+ const at = parse(event.newValue);
+ if (at) onActivity(at);
+ };
+ if (!channel) window.addEventListener('storage', onStorage);
+
+ return {
+ post(at) {
+ try {
+ window.localStorage.setItem(LAST_ACTIVITY_KEY, String(at));
+ } catch {
+ /* storage unavailable */
+ }
+ try {
+ channel?.postMessage({ at });
+ } catch {
+ /* channel closed */
+ }
+ },
+ close() {
+ channel?.close();
+ if (!channel) window.removeEventListener('storage', onStorage);
+ },
+ };
+}
diff --git a/lib/session-policy/limits.ts b/lib/session-policy/limits.ts
new file mode 100644
index 000000000..6a939f507
--- /dev/null
+++ b/lib/session-policy/limits.ts
@@ -0,0 +1,60 @@
+/**
+ * The organisation's session limits (policy.json `organisation.session`) as
+ * they apply to this browser. Every account signed in here has its own
+ * effective policy (its domain and group scopes); the browser follows the
+ * strictest: the shortest idle time any of them sets, and the first
+ * maximum session length to run out. 0 is off, so it never wins.
+ */
+
+import { DEFAULT_ORGANISATION_POLICY, type OrganisationPolicy } from '@/lib/admin/organisation-policy';
+
+export type SessionPolicy = OrganisationPolicy['session'];
+
+export interface AccountSession {
+ session: SessionPolicy | undefined;
+ /** When the account signed in (ms); its maximum session length counts from here. */
+ signedInAt?: number;
+}
+
+export interface SessionLimits {
+ idle: { minutes: number; warnSeconds: number } | null;
+ /** `at`: when the first account's maximum session length runs out. */
+ max: { at: number; hours: number; warnSeconds: number } | null;
+}
+
+export const NO_SESSION_LIMITS: SessionLimits = { idle: null, max: null };
+
+const HOUR_MS = 60 * 60 * 1000;
+
+export function sessionLimits(accounts: readonly AccountSession[]): SessionLimits {
+ let idle: SessionLimits['idle'] = null;
+ let max: SessionLimits['max'] = null;
+ for (const account of accounts) {
+ const session = account.session ?? DEFAULT_ORGANISATION_POLICY.session;
+ const warnSeconds = session.warnSeconds;
+ if (session.idleMinutes > 0 && (!idle || session.idleMinutes < idle.minutes)) {
+ idle = { minutes: session.idleMinutes, warnSeconds };
+ }
+ if (session.maxHours > 0 && typeof account.signedInAt === 'number') {
+ const at = account.signedInAt + session.maxHours * HOUR_MS;
+ if (!max || at < max.at) max = { at, hours: session.maxHours, warnSeconds };
+ }
+ }
+ return { idle, max };
+}
+
+export function sameLimits(a: SessionLimits, b: SessionLimits): boolean {
+ return JSON.stringify(a) === JSON.stringify(b);
+}
+
+let current: SessionLimits | null = null;
+
+/** The limits the guard counts with, for readers outside React (the plugin settings view). */
+export function setCurrentSessionLimits(limits: SessionLimits | null): void {
+ current = limits;
+}
+
+/** Null before the guard has looked at the signed-in accounts. */
+export function currentSessionLimits(): SessionLimits | null {
+ return current;
+}
diff --git a/lib/session-policy/session-timer.ts b/lib/session-policy/session-timer.ts
new file mode 100644
index 000000000..b9d54b8e0
--- /dev/null
+++ b/lib/session-policy/session-timer.ts
@@ -0,0 +1,139 @@
+/**
+ * The clock behind the organisation's idle timeout and maximum session
+ * length. It knows the last activity and the limits, and says when the
+ * warning starts and when the session ends; the guard component
+ * (components/session/session-timeout-guard.tsx) feeds it activity and
+ * does the signing out.
+ *
+ * Deadlines are times, not countdowns: a laptop that slept through one
+ * expires on the first check after waking, and activity that arrives after
+ * the deadline (the focus event of the wake-up itself) can't bring the
+ * session back.
+ */
+
+import type { SessionLimits } from './limits';
+
+export type SessionEndKind = 'idle' | 'max';
+
+export interface SessionTimerState {
+ phase: 'active' | 'warning' | 'expired';
+ /** Which limit the next deadline belongs to; null when no limit is set. */
+ kind: SessionEndKind | null;
+ /** When the session ends (ms); null when no limit is set. */
+ deadline: number | null;
+}
+
+export interface SessionTimerOptions {
+ limits: SessionLimits;
+ lastActivity: number;
+ onChange?: (state: SessionTimerState) => void;
+ onExpire: (kind: SessionEndKind) => void;
+ now?: () => number;
+}
+
+export interface SessionTimer {
+ /** Activity in this tab. Ignored while the idle warning shows: the user answers it with "Stay signed in". */
+ activity(at?: number): void;
+ /** Activity in another tab, where the user may have answered the warning already. */
+ remoteActivity(at: number): void;
+ /** "Stay signed in": restarts the idle time, never the maximum. */
+ stay(): void;
+ setLimits(limits: SessionLimits): void;
+ /** Look at the clock now (after a wake-up or a tab becoming visible). */
+ check(): void;
+ lastActivity(): number;
+ state(): SessionTimerState;
+ dispose(): void;
+}
+
+const MINUTE_MS = 60 * 1000;
+const MAX_WAIT_MS = 60 * MINUTE_MS;
+
+export function createSessionTimer(options: SessionTimerOptions): SessionTimer {
+ const now = options.now ?? Date.now;
+ let limits = options.limits;
+ let lastActivity = options.lastActivity;
+ let state: SessionTimerState = { phase: 'active', kind: null, deadline: null };
+ let timer: ReturnType | null = null;
+ let disposed = false;
+
+ const clear = () => {
+ if (timer) clearTimeout(timer);
+ timer = null;
+ };
+
+ const publish = (next: SessionTimerState) => {
+ if (next.phase === state.phase && next.kind === state.kind && next.deadline === state.deadline) return;
+ state = next;
+ options.onChange?.(state);
+ };
+
+ /** The deadline that comes first, with how long its warning lasts. */
+ const target = (): { kind: SessionEndKind; deadline: number; warnMs: number } | null => {
+ const idleMs = limits.idle ? limits.idle.minutes * MINUTE_MS : 0;
+ const idle = limits.idle
+ ? { kind: 'idle' as const, deadline: lastActivity + idleMs, warnMs: Math.min(limits.idle.warnSeconds * 1000, idleMs) }
+ : null;
+ const max = limits.max
+ ? { kind: 'max' as const, deadline: limits.max.at, warnMs: limits.max.warnSeconds * 1000 }
+ : null;
+ if (idle && max) return max.deadline <= idle.deadline ? max : idle;
+ return idle ?? max;
+ };
+
+ const evaluate = () => {
+ if (disposed || state.phase === 'expired') return;
+ clear();
+ const next = target();
+ if (!next) {
+ publish({ phase: 'active', kind: null, deadline: null });
+ return;
+ }
+ const at = now();
+ if (at >= next.deadline) {
+ publish({ phase: 'expired', kind: next.kind, deadline: next.deadline });
+ options.onExpire(next.kind);
+ return;
+ }
+ const warnFrom = next.deadline - next.warnMs;
+ const warning = at >= warnFrom;
+ publish({ phase: warning ? 'warning' : 'active', kind: next.kind, deadline: next.deadline });
+ // Capped: setTimeout overflows past 24.8 days, and a long wait is checked again anyway.
+ timer = setTimeout(evaluate, Math.min((warning ? next.deadline : warnFrom) - at, MAX_WAIT_MS));
+ };
+
+ const record = (at: number) => {
+ // A deadline that already passed ends the session before the activity counts.
+ evaluate();
+ if (state.phase === 'expired') return;
+ if (at > lastActivity) lastActivity = at;
+ evaluate();
+ };
+
+ evaluate();
+
+ return {
+ activity(at = now()) {
+ evaluate();
+ if (state.phase === 'warning' && state.kind === 'idle') return;
+ record(at);
+ },
+ remoteActivity(at) {
+ record(at);
+ },
+ stay() {
+ record(now());
+ },
+ setLimits(next) {
+ limits = next;
+ evaluate();
+ },
+ check: evaluate,
+ lastActivity: () => lastActivity,
+ state: () => state,
+ dispose() {
+ disposed = true;
+ clear();
+ },
+ };
+}
diff --git a/lib/session-policy/sign-out-reason.ts b/lib/session-policy/sign-out-reason.ts
new file mode 100644
index 000000000..b52166520
--- /dev/null
+++ b/lib/session-policy/sign-out-reason.ts
@@ -0,0 +1,33 @@
+/**
+ * Why Bulwark signed the user out on its own, for the login page to say.
+ * Kept in sessionStorage: the tab that signed out shows it once.
+ */
+
+export type SessionEndReason =
+ | { kind: 'idle'; minutes: number }
+ | { kind: 'max'; hours: number };
+
+const KEY = 'session_end_reason';
+
+export function rememberSessionEnd(reason: SessionEndReason): void {
+ try {
+ window.sessionStorage.setItem(KEY, JSON.stringify(reason));
+ } catch {
+ /* storage unavailable */
+ }
+}
+
+/** The reason, once; null when the user wasn't signed out by a session limit. */
+export function consumeSessionEnd(): SessionEndReason | null {
+ try {
+ const raw = window.sessionStorage.getItem(KEY);
+ window.sessionStorage.removeItem(KEY);
+ if (!raw) return null;
+ const parsed = JSON.parse(raw) as Record