@rapidmx/web-client 0.2.0 → 0.3.1

package/apps/shared/components/forms/StringListField.tsx

@@ -0,0 +1,104 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useState } from "react";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+
+export interface StringListFieldProps {
+    label: string;
+    /** Associates the label with the add-input via `htmlFor`/`id`, same as `FormField` — required so the
+     * field is reachable via `getByLabelText()` in tests and by assistive tech, not just visually. */
+    id: string;
+    values: string[];
+    onChange: (values: string[]) => void;
+    placeholder?: string;
+    emptyMessage?: string;
+    disabled?: boolean;
+}
+
+/**
+ * A plain, controlled add/remove list-of-strings editor — the same visual add-row/per-item-remove shape
+ * `MemberListCard` already established for a `DistributionList`'s `memberAddresses`, but operating on a
+ * local `value`/`onChange` pair rather than persisting itself via its own API call. `MemberListCard`
+ * isn't reusable here as-is: `EscrowScope.holderUserUids` (at least one required) and
+ * `Matter.custodianMailboxUids` (also non-empty) are both required *at creation time*, before there's any
+ * uid yet to `PUT` against — this needs to compose into an ordinary create/edit form's own local state
+ * instead, same as every other field on those forms.
+ */
+export default function StringListField({
+    label,
+    id,
+    values,
+    onChange,
+    placeholder,
+    emptyMessage = "None added yet.",
+    disabled,
+}: StringListFieldProps) {
+    const [draft, setDraft] = useState("");
+
+    /** Accepts either the "Add" button's own form submit or the input's Enter keydown — both just need
+     * `preventDefault()` (submitting would otherwise reload the page; Enter would otherwise do nothing
+     * harmful here, but is prevented for consistency). */
+    function handleAdd(e: { preventDefault(): void }) {
+        e.preventDefault();
+        const trimmed = draft.trim();
+        if (!trimmed || values.includes(trimmed)) {
+            return;
+        }
+        onChange([...values, trimmed]);
+        setDraft("");
+    }
+
+    function handleRemove(value: string) {
+        onChange(values.filter((v) => v !== value));
+    }
+
+    return (
+        <div className="mb-4">
+            <label htmlFor={id} className="block text-sm font-semibold mb-1.5 text-text">
+                {label}
+            </label>
+
+            <ul className="flex flex-col gap-2 mb-2">
+                {values.length === 0 && <li className="text-sm text-text-muted">{emptyMessage}</li>}
+                {values.map((value) => (
+                    <li
+                        key={value}
+                        className="flex items-center justify-between gap-3 py-2 px-3 border border-border rounded-sm"
+                    >
+                        <span className="text-sm font-medium break-all">{value}</span>
+                        <button
+                            type="button"
+                            onClick={() => handleRemove(value)}
+                            disabled={disabled}
+                            className="text-sm text-danger hover:underline disabled:opacity-55 shrink-0"
+                        >
+                            Remove
+                        </button>
+                    </li>
+                ))}
+            </ul>
+
+            <div className="flex gap-2">
+                <input
+                    id={id}
+                    type="text"
+                    value={draft}
+                    onChange={(e) => setDraft(e.target.value)}
+                    onKeyDown={(e) => {
+                        if (e.key === "Enter") {
+                            handleAdd(e);
+                        }
+                    }}
+                    placeholder={placeholder}
+                    disabled={disabled}
+                    className="flex-1 text-sm py-2 px-3 border border-border rounded-sm bg-surface text-text focus:outline-none focus:border-primary"
+                />
+                <Button type="button" variant="secondary" disabled={disabled} className="!w-auto" onClick={handleAdd}>
+                    Add
+                </Button>
+            </div>
+        </div>
+    );
+}

package/apps/shared/components/layout/AppShell.tsx

@@ -9,6 +9,7 @@ import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelop
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
 import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
+import { useIdleKeyTimeout } from "@rapidmx/react-shared/crypto/useIdleKeyTimeout.js";
 import ComposeProvider from "../mail/compose/ComposeContext.js";
 import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
@@ -84,6 +85,9 @@ export default function AppShell({
     const { branding, iconSrc } = useBranding();
 
     useRedirectIfUnauthenticated(userUid, authServerUrl);
+    // Mounted here, not scoped to Mail/Settings (the only shells that actually read unlocked keys),
+    // specifically so activity in *any* app resets the idle clock - see that hook's own doc comment.
+    useIdleKeyTimeout();
 
     function handleSignOut() {
         window.location.href = authServerUrl ?? "/";

package/apps/shared/components/layout/KeyEnrollmentGate.tsx

@@ -0,0 +1,265 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
+import { enrollKey, getKeyVault, PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import {
+    ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE,
+    getUnlockedKeys,
+    unlockWithPassword,
+} from "@rapidmx/react-shared/crypto/keySession.js";
+import { buildAad, generateMasterKey, sealWithKey } from "@rapidmx/react-shared/crypto/masterKey.js";
+import { buildPasswordWrap, buildRecoveryWraps } from "@rapidmx/react-shared/crypto/masterKeyWraps.js";
+import { exportPrivateKeyPkcs8, generateKeyPairWithCsr } from "@rapidmx/react-shared/crypto/keys.js";
+
+type Status = "checking" | "setup_password" | "enrolling" | "show_recovery_codes" | "unlock" | "unlocking" | "ready";
+
+const MIN_PASSWORD_LENGTH = 8;
+
+async function provisionEncryptionKey(
+    mailboxUid: string,
+    mailboxAddress: string,
+    password: string,
+): Promise<{ recoveryCodes: string[] }> {
+    const mk = generateMasterKey();
+    const passwordWrap = await buildPasswordWrap(mailboxUid, mk, password);
+    const { wraps: recoveryWraps, codes: recoveryCodes } = await buildRecoveryWraps(mailboxUid, mk);
+
+    // Only the encryption key is provisioned here. The signing key's spec-required public-CA enrolment
+    // (RFC 8823 ACME automation) is a real but genuinely asynchronous flow (a live email round-trip with
+    // a public CA, likely minutes) - it's a deliberate opt-in action in Settings > Encryption
+    // ("Enable digital signatures"), not something to block first-sign-in mailbox setup on.
+    const { keyPair, csrPem } = await generateKeyPairWithCsr(mailboxAddress, "encrypt");
+    const privateKeyRaw = await exportPrivateKeyPkcs8(keyPair.privateKey);
+    const wrappedKeySealed = await sealWithKey(mk, privateKeyRaw, buildAad(mailboxUid, ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE));
+
+    await enrollKey(mailboxUid, {
+        useType: "encrypt",
+        csr: csrPem,
+        wrappedKey: { ciphertext: wrappedKeySealed.ciphertext, nonce: wrappedKeySealed.nonce, algorithm: "AES-256-GCM" },
+        masterKeyWraps: [passwordWrap, ...recoveryWraps],
+    });
+
+    return { recoveryCodes };
+}
+
+export interface KeyEnrollmentGateProps {
+    /** Undefined while the caller's mailbox hasn't resolved yet (or has none) - renders `children`
+     * unchanged in that case, so this component can be mounted unconditionally at a stable tree
+     * position (see this component's own doc comment for why that matters). */
+    mailboxUid?: string;
+    mailboxAddress?: string;
+    /** The mailbox's currently-published public keys (`Mailbox.keys`) - needed to unlock an
+     * already-enrolled vault (see `unlockWithPassword()`'s own signature), not just to provision a new
+     * one. Treated as empty when undefined - a mailbox with no public keys published yet has nothing to
+     * unlock, so this only affects the already-enrolled path. */
+    mailboxKeys?: PublicKey[];
+    children: React.ReactNode;
+}
+
+/**
+ * Gates a mailbox's normal content behind one-time E2E encryption key setup, per
+ * `specs/end-to-end_encryption.md`'s "Generate signing and encryption keypairs on the client's device on
+ * first sign-in." Rendered by `MailShell` wrapping its own returned content unconditionally, not only
+ * once a mailbox is resolved — mounting this component at a *different* tree position depending on
+ * `mailboxUid`'s readiness (e.g. only wrapping once ready, rendering bare content beforehand) would make
+ * `children` (real `AppShell` chrome) itself remount the moment `mailboxUid` resolves, tearing down any
+ * state/effects it had already started. Always wrapping keeps `AppShell` mounted continuously across
+ * that transition; this component simply passes `children` through untouched while `mailboxUid` is
+ * still unresolved, and only starts its own check once a real `mailboxUid` is supplied.
+ *
+ * A `getKeyVault()` failure (network error, server not yet wired up to serve this endpoint) also renders
+ * `children` unchanged rather than blocking mail entirely - encryption is optional and gradual by design
+ * (the spec's own "near zero frictionless experience" goal), not a hard prerequisite for reading mail.
+ */
+export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxKeys, children }: KeyEnrollmentGateProps) {
+    const [status, setStatus] = useState<Status>(mailboxUid ? "checking" : "ready");
+    const [password, setPassword] = useState("");
+    const [confirmPassword, setConfirmPassword] = useState("");
+    const [error, setError] = useState<string | null>(null);
+    const [recoveryCodes, setRecoveryCodes] = useState<string[]>([]);
+    const [codesSaved, setCodesSaved] = useState(false);
+
+    useEffect(() => {
+        if (!mailboxUid) {
+            return;
+        }
+        // A remount within the same browser session (e.g. navigating between pages) shouldn't re-prompt
+        // for a password the in-memory session store (`keySession.ts`) already has unwrapped - only a
+        // fresh session (reload, new tab, post-logout) has nothing there.
+        if (getUnlockedKeys(mailboxUid)) {
+            setStatus("ready");
+            return;
+        }
+        let cancelled = false;
+        getKeyVault(mailboxUid)
+            .then((vault) => {
+                if (!cancelled) {
+                    setStatus(vault.wrappedKeys.length > 0 ? "unlock" : "setup_password");
+                }
+            })
+            .catch(() => {
+                if (!cancelled) {
+                    setStatus("ready");
+                }
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [mailboxUid]);
+
+    async function handleUnlock(e: React.FormEvent) {
+        e.preventDefault();
+        setError(null);
+        setStatus("unlocking");
+        try {
+            // Only reachable via "unlock", which the effect above only ever sets once mailboxUid was
+            // defined.
+            await unlockWithPassword(mailboxUid!, mailboxKeys ?? [], password);
+            setStatus("ready");
+        } catch {
+            // Deliberately generic - see `unlockWithPassword()`'s own doc comment: it throws the same way
+            // for "no password wrap enrolled" and "wrong password" today, and this UI has no way to tell
+            // those apart without leaking which is which to a potential attacker guessing passwords.
+            setError("Incorrect password.");
+            setStatus("unlock");
+        }
+    }
+
+    async function handleSetPassword(e: React.FormEvent) {
+        e.preventDefault();
+        if (password.length < MIN_PASSWORD_LENGTH) {
+            setError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters.`);
+            return;
+        }
+        if (password !== confirmPassword) {
+            setError("Passwords do not match.");
+            return;
+        }
+        setError(null);
+        setStatus("enrolling");
+        try {
+            // Only reachable via "setup_password", which the effect above only ever sets once mailboxUid
+            // was defined (and mailboxAddress necessarily came with it - see KeyEnrollmentGateProps).
+            const { recoveryCodes: codes } = await provisionEncryptionKey(mailboxUid!, mailboxAddress!, password);
+            setRecoveryCodes(codes);
+            setStatus("show_recovery_codes");
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not set up encryption for this mailbox.");
+            setStatus("setup_password");
+        }
+    }
+
+    if (status === "checking") {
+        return null;
+    }
+
+    if (status === "unlock" || status === "unlocking") {
+        const unlocking = status === "unlocking";
+        return (
+            <div className="min-h-screen flex items-center justify-center p-8 bg-surface-alt">
+                <div className="w-full max-w-md bg-surface border border-border rounded-md p-8">
+                    <h1 className="text-lg font-bold mb-2">Unlock your mailbox</h1>
+                    <p className="text-sm text-text-muted mb-5">
+                        Enter your encryption password to unlock signing and reading protected mail this session.
+                    </p>
+                    {error && <Alert>{error}</Alert>}
+                    <form onSubmit={handleUnlock}>
+                        <FormField label="Encryption password" htmlFor="key-unlock-password">
+                            <input
+                                id="key-unlock-password"
+                                type="password"
+                                className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
+                                value={password}
+                                onChange={(e) => setPassword(e.target.value)}
+                                disabled={unlocking}
+                                autoComplete="current-password"
+                            />
+                        </FormField>
+                        <Button type="submit" loading={unlocking} disabled={unlocking}>
+                            Unlock
+                        </Button>
+                    </form>
+                </div>
+            </div>
+        );
+    }
+
+    if (status === "setup_password" || status === "enrolling") {
+        const enrolling = status === "enrolling";
+        return (
+            <div className="min-h-screen flex items-center justify-center p-8 bg-surface-alt">
+                <div className="w-full max-w-md bg-surface border border-border rounded-md p-8">
+                    <h1 className="text-lg font-bold mb-2">Protect your mailbox</h1>
+                    <p className="text-sm text-text-muted mb-5">
+                        Choose a password to protect your encryption keys. This is separate from your sign-in
+                        password and is never sent to the server.
+                    </p>
+                    {error && <Alert>{error}</Alert>}
+                    <form onSubmit={handleSetPassword}>
+                        <FormField label="Encryption password" htmlFor="key-enrollment-password">
+                            <input
+                                id="key-enrollment-password"
+                                type="password"
+                                className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
+                                value={password}
+                                onChange={(e) => setPassword(e.target.value)}
+                                disabled={enrolling}
+                                autoComplete="new-password"
+                            />
+                        </FormField>
+                        <FormField label="Confirm password" htmlFor="key-enrollment-password-confirm">
+                            <input
+                                id="key-enrollment-password-confirm"
+                                type="password"
+                                className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
+                                value={confirmPassword}
+                                onChange={(e) => setConfirmPassword(e.target.value)}
+                                disabled={enrolling}
+                                autoComplete="new-password"
+                            />
+                        </FormField>
+                        <Button type="submit" loading={enrolling} disabled={enrolling}>
+                            Continue
+                        </Button>
+                    </form>
+                </div>
+            </div>
+        );
+    }
+
+    if (status === "show_recovery_codes") {
+        return (
+            <div className="min-h-screen flex items-center justify-center p-8 bg-surface-alt">
+                <div className="w-full max-w-md bg-surface border border-border rounded-md p-8">
+                    <h1 className="text-lg font-bold mb-2">Save your recovery codes</h1>
+                    <p className="text-sm text-text-muted mb-5">
+                        If you lose your password, these codes are the only way to recover your encrypted mail.
+                        Each code can be used once. Store them somewhere safe — they will not be shown again.
+                    </p>
+                    <ul className="grid grid-cols-2 gap-2 mb-5 font-mono text-sm">
+                        {recoveryCodes.map((code) => (
+                            <li key={code} className="bg-surface-alt rounded-sm py-1.5 px-2 text-center">
+                                {code}
+                            </li>
+                        ))}
+                    </ul>
+                    <label className="flex items-center gap-2 text-sm mb-4">
+                        <input type="checkbox" checked={codesSaved} onChange={(e) => setCodesSaved(e.target.checked)} />
+                        I have saved these recovery codes in a safe place.
+                    </label>
+                    <Button type="button" disabled={!codesSaved} onClick={() => setStatus("ready")}>
+                        Continue
+                    </Button>
+                </div>
+            </div>
+        );
+    }
+
+    return <>{children}</>;
+}

package/apps/shared/components/mail/ConversationThreadPane.tsx

@@ -6,6 +6,7 @@ import React, { useEffect, useState } from "react";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { Attachment, Folder, Message, getMessage, listAttachments, setMessageRead } from "@rapidmx/react-shared/mail/mailApi.js";
 import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
 import MessageDetailPane from "./MessageDetailPane.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 
@@ -15,6 +16,9 @@ export interface ConversationThreadPaneProps {
      * Sent Items copy of its reply), so each message's own recall eligibility is looked up individually
      * against its own `folderUid` rather than assuming one folder for the whole thread. */
     folders: Folder[];
+    /** The mailbox's labels, fetched once by the parent (`apps/www/index.tsx`) and passed through to
+     * every expanded message's own `MessageDetailPane` — see that component's own `labels` prop. */
+    labels?: Label[];
 }
 
 /**
@@ -25,7 +29,7 @@ export interface ConversationThreadPaneProps {
  * lightweight summary, since mounting a full `MessageDetailPane` (and its iframe) for every message in
  * a long thread up front would be wasteful.
  */
-export default function ConversationThreadPane({ conversation, folders }: ConversationThreadPaneProps) {
+export default function ConversationThreadPane({ conversation, folders, labels }: ConversationThreadPaneProps) {
     const [messages, setMessages] = useState<Record<string, Message>>({});
     const [attachmentsByUid, setAttachmentsByUid] = useState<Record<string, Attachment[]>>({});
     const [expandedUids, setExpandedUids] = useState<Set<string>>(new Set());
@@ -165,6 +169,9 @@ export default function ConversationThreadPane({ conversation, folders }: Conver
                             isInbox={folders.find((f) => f.uid === message.folderUid)?.type === "inbox"}
                             onClassified={(updated) => setMessages((prev) => ({ ...prev, [uid]: updated }))}
                             onReceiptHandled={(updated) => setMessages((prev) => ({ ...prev, [uid]: updated }))}
+                            onArchived={(updated) => setMessages((prev) => ({ ...prev, [uid]: updated }))}
+                            labels={labels}
+                            onLabelsChanged={(updated) => setMessages((prev) => ({ ...prev, [uid]: updated }))}
                         />
                     </div>
                 );