@rapidmx/web-client 0.35.0 → 0.37.0

package/lib/crypto/keyvaultApi.ts

@@ -15,9 +15,10 @@ import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
 /** A cryptographic public key used to sign or encrypt messages — safe to expose publicly. Mirrors
  * `@rapidmx/restapi`'s `PublicKey` type exactly. */
 export interface PublicKey {
-    /** Base64-encoded DER X.509 certificate. */
+    /** Base64-encoded DER X.509 certificate - or, for `type: "openpgp"`, the binary OpenPGP transferable public key. */
     publicKey: string;
-    /** The key's type/format (e.g. `x509`). */
+    /** The key's type/format: `x509` (S/MIME), or `openpgp` - an OpenPGP certificate, which both encrypts and signs and is listed
+     * once, with `useType: "encrypt"` (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*). */
     type: string;
     useType: "sign" | "encrypt";
     /** SHA-256 fingerprint of the certificate, hex encoded. */
@@ -47,7 +48,35 @@ export interface WrappedPrivateKey {
     /** AEAD algorithm identifier (e.g. `AES-256-GCM`). */
     algorithm: string;
     fingerprint: string;
-    useType: "sign" | "encrypt";
+    useType: KeyUseType;
+    /** `"openpgp"` for an OpenPGP secret key (sealed with `OPENPGP_PRIVATE_KEY_AAD_PURPOSE`); absent for a PKCS#8 key. */
+    type?: string;
+}
+
+/** `PublicKey.type` of an OpenPGP certificate. */
+export const OPENPGP_KEY_TYPE = "openpgp";
+
+/** Whether `key` is an OpenPGP certificate (or an OpenPGP secret key's wrap). */
+export function isOpenPgpKey(key: { type?: string } | undefined): boolean {
+    return key?.type === OPENPGP_KEY_TYPE;
+}
+
+/** A key's format: `"openpgp"`, or `"x509"` for every other key (S/MIME). */
+export type KeyFormat = "x509" | "openpgp";
+
+export function keyFormat(key: { type?: string }): KeyFormat {
+    return isOpenPgpKey(key) ? "openpgp" : "x509";
+}
+
+/** What a mailbox's own key is used for. `sign`/`encrypt` keys are published (`Mailbox.keys`); `zero-access` keys never are.
+ * Mirrors `@rapidmx/restapi`'s `KeyUseType`. */
+export type KeyUseType = "sign" | "encrypt" | "zero-access";
+
+/** A mailbox's zero-access key (restapi `specs/search.md` §3): the certificate the server encrypts mail at rest to on
+ * arrival. Same shape as `PublicKey`, but never published - only the vault's reader gets it (`KeyVault.zeroAccessKeys`).
+ * Mirrors `@rapidmx/restapi`'s `ZeroAccessKey`. */
+export interface ZeroAccessKey extends Omit<PublicKey, "useType" | "issuerCertificate"> {
+    useType: "zero-access";
 }
 
 /** One wrapped copy of the mailbox master key (MK), per unlock method. Mirrors `@rapidmx/restapi`'s
@@ -72,8 +101,14 @@ export interface MasterKeyWrap {
 export interface EncryptionPreference {
     lastSeen?: number;
     preferEncrypt: "mutual" | "nopreference";
+    /** Which end-to-end format the address would rather receive when a sender can use either (restapi
+     * `specs/end-to-end_encryption.md` *Choosing the format*). Absent: no preference. */
+    preferFormat?: EndToEndFormat;
 }
 
+/** The two end-to-end encryption formats. */
+export type EndToEndFormat = "smime" | "openpgp";
+
 /** A newly observed key that differs from a contact's pinned key of the same `useType` - restapi records it instead of
  * silently replacing the pin (the spec's Key Conflict Handling) until the user resolves it with `resolveKeyConflict()`.
  * A contact holds at most one per `useType`. Mirrors `@rapidmx/restapi`'s `KeyConflict`. */
@@ -114,6 +149,9 @@ export interface KeyVault {
      * (`enrollKey()`, `startSignEnrollment()`, `addMasterKeyWrap()`, `rekey()`), so restapi refuses it with `409` if
      * another device rotated the master key meanwhile. Absent from servers that don't track it yet. */
     masterKeyGeneration?: number;
+    /** The mailbox's zero-access certificates, newest last - returned with the vault because they are never published and
+     * an unlock needs them to decrypt zero-access mail. Absent from servers without zero-access encryption. */
+    zeroAccessKeys?: ZeroAccessKey[];
 }
 
 /** The optional optimistic check restapi applies to vault writes carrying key material sealed under the master key. */
@@ -138,10 +176,10 @@ export function getKeyVault(mailboxUid: string, client?: ApiClient): Promise<Key
  * `revocationReason` - a superseded key may still verify old mail (`isTrustedForVerification()`) but is never used for
  * new mail. Shared by `crypto/keySession.ts` (the
  * mailbox's own keys) and `crypto/composeSecurity.ts` (a recipient's discovered keys). */
-export function findActivePublicKey(keys: PublicKey[], useType: "sign" | "encrypt"): PublicKey | undefined {
+export function findActivePublicKey(keys: PublicKey[], useType: "sign" | "encrypt", format: KeyFormat = "x509"): PublicKey | undefined {
     const now = Date.now();
     return keys
-        .filter((k) => k.useType === useType && !k.revokedAt && k.notAfter > now)
+        .filter((k) => k.useType === useType && keyFormat(k) === format && !k.revokedAt && k.notAfter > now)
         .sort((a, b) => b.notBefore - a.notBefore)[0];
 }
 
@@ -179,13 +217,17 @@ export function signingKeyFingerprints(keys: PublicKey[] | undefined, previousKe
 }
 
 export interface EnrollKeyInput extends ExpectedMasterKeyGeneration {
-    useType: "sign" | "encrypt";
-    /** PEM-encoded PKCS#10 CSR — required (and only meaningful) for `useType: "encrypt"`; the server
+    useType: KeyUseType;
+    /** PEM-encoded PKCS#10 CSR — required (and only meaningful) for `useType: "encrypt"` and `"zero-access"`; the server
      * calls its own internal CA against this CSR. */
     csr?: string;
     /** An already-issued PEM certificate — required (and only meaningful) for `useType: "sign"`. */
     certificate?: string;
-    wrappedKey: Omit<WrappedPrivateKey, "fingerprint" | "useType">;
+    /** `"openpgp"` to enroll the mailbox's OpenPGP key (with `useType: "encrypt"`): self-certified, no CA. */
+    type?: string;
+    /** The OpenPGP public key (armored or base64 binary) - required, and only meaningful, with `type: "openpgp"`. */
+    publicKey?: string;
+    wrappedKey: Omit<WrappedPrivateKey, "fingerprint" | "useType" | "type">;
     /** Only meaningful the very first time a mailbox enrolls a key at all (bootstraps its master key). */
     masterKeyWraps?: MasterKeyWrap[];
 }
@@ -508,6 +550,110 @@ export function removeMasterKeyWrap(mailboxUid: string, method: string, methodId
     });
 }
 
+/** One member's copy of a shared mailbox's zero-access private key: base64 CMS of its PKCS#8, to the member's own zero-access certificate. */
+export interface MemberKeyWrap {
+    memberUserUid: string;
+    recipientFingerprint: string;
+    zeroAccessKeyFingerprint: string;
+    cms: string;
+    createdAt?: number;
+}
+
+/** One member in `SharedKeyStatus`. */
+export interface SharedKeyMember {
+    userUid: string;
+    full: boolean;
+    /** Their own zero-access certificate - absent until they first sign in and get one. */
+    certificate?: ZeroAccessKey;
+    /** The mailbox's zero-access keys they hold a wrap of. */
+    wrapped: string[];
+}
+
+/** Where a shared mailbox's zero-access key stands with its members - restapi `GET /mail/mailboxes/:id/keyvault/members`. */
+export interface SharedKeyStatus {
+    ownerless: boolean;
+    /** The caller: the mailbox's owner, one of its members, or neither (an administrator acting through a role). */
+    role?: "owner" | "member" | "other";
+    activeKeyFingerprint?: string;
+    zeroAccessKeys: ZeroAccessKey[];
+    members: SharedKeyMember[];
+    /** Members with a certificate but no wrap of the active key. */
+    pending: string[];
+    /** Users holding wraps who are no longer members. */
+    departed: string[];
+    /** A departed user holds the active key: a new key must be provisioned. */
+    rotationPending: boolean;
+    /** The caller may change the wraps. */
+    manager: boolean;
+    /** A mailbox without an owner assigned to an escrow scope: that scope. */
+    escrowScopeId?: string;
+    /** Its zero-access keys (fingerprints) with no escrow copy for `escrowScopeId` yet. Absent from servers that predate it. */
+    escrowPending?: string[];
+}
+
+/** An escrow copy of a mailbox-without-an-owner's zero-access private key, as `putZeroAccessEscrowWraps()` sends it: CMS of its PKCS#8 to
+ * the escrow scope's certificate (`getEscrowInfo()`). */
+export interface ZeroAccessEscrowWrapInput {
+    escrowScopeId: string;
+    zeroAccessKeyFingerprint: string;
+    /** Base64 DER CMS `EnvelopedData`. */
+    cms: string;
+}
+
+const vaultPath = (mailboxUid: string): string => `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault`;
+
+export function getSharedKeyStatus(mailboxUid: string, client?: ApiClient): Promise<SharedKeyStatus> {
+    return withClient(client, `${vaultPath(mailboxUid)}/members`);
+}
+
+/** The caller's own member key wraps of `mailboxUid` (`[]` for its owner and for a member still waiting). */
+export function getMyMemberKeyWraps(mailboxUid: string, client?: ApiClient): Promise<MemberKeyWrap[]> {
+    return withClient(client, `${vaultPath(mailboxUid)}/member-wraps`);
+}
+
+export function putMemberKeyWraps(mailboxUid: string, wraps: MemberKeyWrap[], client?: ApiClient): Promise<SharedKeyStatus> {
+    return withClient(client, `${vaultPath(mailboxUid)}/member-wraps`, { method: "PUT", body: JSON.stringify({ wraps }) });
+}
+
+/** Removes every wrap of a user who is no longer a member - the last step of a rotation. */
+export function removeMemberKeyWraps(mailboxUid: string, memberUserUid: string, client?: ApiClient): Promise<SharedKeyStatus> {
+    return withClient(client, `${vaultPath(mailboxUid)}/member-wraps/${encodeURIComponent(memberUserUid)}`, { method: "DELETE" });
+}
+
+/** Provisions (or rotates) a mailbox-without-an-owner's zero-access key with its member wraps, in one write - and, for a mailbox assigned to
+ * an escrow scope, its escrow copy (required then). */
+export function enrollSharedZeroAccessKey(
+    mailboxUid: string,
+    input: {
+        csr: string;
+        wraps: Omit<MemberKeyWrap, "zeroAccessKeyFingerprint">[];
+        escrowWrap?: Omit<ZeroAccessEscrowWrapInput, "zeroAccessKeyFingerprint">;
+    },
+    client?: ApiClient,
+): Promise<SharedKeyStatus> {
+    return withClient(client, `${vaultPath(mailboxUid)}/shared-zero-access-key`, { method: "POST", body: JSON.stringify(input) });
+}
+
+/** Adds the escrow copies of a mailbox-without-an-owner's zero-access keys its escrow scope is missing (`SharedKeyStatus.escrowPending`). */
+export function putZeroAccessEscrowWraps(mailboxUid: string, wraps: ZeroAccessEscrowWrapInput[], client?: ApiClient): Promise<SharedKeyStatus> {
+    return withClient(client, `${vaultPath(mailboxUid)}/escrow-wraps`, { method: "PUT", body: JSON.stringify({ wraps }) });
+}
+
+/** One key a "Export keys for Outlook/phone" file held, as `recordKeyExport()` reports it. */
+export interface ExportedKeyRecord {
+    kind: "zero-access" | "encrypt" | "sign";
+    fingerprint: string;
+}
+
+/** Records with restapi that the owner exported these private keys (`key_vault.export` in the audit log). `keyExport.ts`
+ * calls it before handing over the file, so an export the server refuses to record isn't handed over. Owner-only. */
+export async function recordKeyExport(mailboxUid: string, keys: ExportedKeyRecord[], client?: ApiClient): Promise<void> {
+    await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/exports`, {
+        method: "POST",
+        body: JSON.stringify({ keys }),
+    });
+}
+
 export interface RekeyInput extends ExpectedMasterKeyGeneration {
     wrappedKeys: WrappedPrivateKey[];
     /** Every wrap of the new master key. For a mailbox assigned an escrow scope, this must include a fresh escrow wrap
@@ -537,6 +683,11 @@ export interface KeyLookupResult {
     keyConflicts?: KeyConflict[];
     /** Keys that were pinned before, newest first - see `PreviousKey`. */
     previousKeys?: PreviousKey[];
+    /** The format to use for a recipient reachable in both (restapi *Choosing the format*): the user's choice for the contact, else what
+     * the address advertises, else what it was last seen using. Absent when nothing says - S/MIME then. */
+    preferredFormat?: EndToEndFormat;
+    /** Where `preferredFormat` came from. */
+    preferredFormatSource?: "contact" | "advertised" | "observed";
 }
 
 /** Server-side Discovery: the server itself performs the `_rapidmx` DNS lookup and remote key-endpoint
@@ -551,8 +702,11 @@ export function lookupKeys(mailboxUid: string, addr: string, client?: ApiClient)
 /** What `trustSigner()` pins: the sender's address and the certificate that signed their message. */
 export interface TrustSignerInput {
     address: string;
-    /** Base64 DER of the signer certificate - `MessageSecurityResult.signerCertificate`. */
+    /** Base64 DER of the signer certificate - `MessageSecurityResult.signerCertificate` - or, with `type: "openpgp"`, an OpenPGP
+     * public key (armored or base64 binary): a signer's, a key attached to a message, or one the user pasted. */
     certificate: string;
+    /** `"openpgp"` to pin an OpenPGP key (it encrypts and signs); omitted for an X.509 signing certificate. */
+    type?: string;
 }
 
 /**
@@ -578,7 +732,7 @@ export async function trustSigner(mailboxUid: string, input: TrustSignerInput, c
     try {
         return await withClient<KeyLookupResult>(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/trust`, {
             method: "POST",
-            body: JSON.stringify({ address: input.address, certificate: input.certificate }),
+            body: JSON.stringify({ address: input.address, certificate: input.certificate, ...(input.type ? { type: input.type } : {}) }),
         });
     } catch (err) {
         if (err instanceof ApiRequestError && err.status === 409) {
@@ -603,6 +757,8 @@ export interface ResolveKeyConflictInput {
     /** For `"accept"`: base64 DER of the certificate to pin (e.g. `MessageSecurityResult.signerCertificate` of a
      * `signer_key_changed` result). Omitted, restapi pins the recorded conflict's `observedKey`. */
     certificate?: string;
+    /** `"openpgp"` for the contact's OpenPGP key (always `useType: "encrypt"`); omitted for its S/MIME certificate. */
+    type?: string;
 }
 
 /** The contact's resulting key state after `resolveKeyConflict()`. */
@@ -637,6 +793,7 @@ export async function resolveKeyConflict(
         action: input.action,
         expectedPinnedFingerprint: input.expectedPinnedFingerprint,
         ...(input.certificate !== undefined ? { certificate: input.certificate } : {}),
+        ...(input.type ? { type: input.type } : {}),
     };
     try {
         return await withClient<ResolveKeyConflictResult>(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/resolve`, {
@@ -657,6 +814,13 @@ export interface EncryptionPolicy {
     encryptSameOrg: PolicyState;
     encryptFederated: PolicyState;
     encryptExternal: PolicyState;
+    /** "Allow zero-access encryption": whether mailboxes may store mail encrypted at rest. Always present from a server that
+     * supports zero-access encryption (its stored value or the server default); absent from one that doesn't, which a
+     * caller treats as not allowed. */
+    allowZeroAccess?: boolean;
+    /** "Allow OpenPGP": whether mailboxes may enroll and publish OpenPGP keys, for mail with OpenPGP users. Absent from a server
+     * that predates it, which a caller treats as not allowed. */
+    allowOpenPgp?: boolean;
 }
 
 /** The system-wide encryption policy (readable by any authenticated user, used to decide what encryption

package/lib/crypto/meetingKeys.ts

@@ -0,0 +1,118 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The temporary per-meeting key of a meeting with external guests (meet-plugin `specs/meeting_privacy.md` §3-4): a P-256 keypair made
+ * in the browser of whoever creates the meeting, with a self-signed certificate so the CMS code in `smime.ts` seals to it and opens with
+ * it unchanged. Every participant receives the private key in their link's `#k=` part; the organizer also keeps it sealed to their own
+ * zero-access certificate. A live AES-256-GCM key derived from it encrypts the meeting's signaling and relayed media. Shared by the
+ * organizer's calendar editor, meet-plugin and booking-plugin.
+ *
+ * Nothing here talks to the server: the private key never leaves the browser except inside a link or a CMS wrap.
+ */
+import { fromBase64Url, toBase64Url } from "./encoding.js";
+import type { DecryptionKey } from "./smime.js";
+
+/** The `#` parameter of a link that carries a meeting key. */
+export const MEETING_KEY_FRAGMENT_PARAM = "k";
+
+/** HKDF `info` of the live key (`specs/meeting_privacy.md` §3). */
+const LIVE_KEY_INFO = "rapidmx-meeting-live-v1";
+
+const EC_PARAMS: EcKeyImportParams = { name: "ECDH", namedCurve: "P-256" };
+
+/** A meeting key as its creator holds it. */
+export interface GeneratedMeetingKey {
+    /** PKCS#8 DER of the private key - what a link carries and a wrap seals. */
+    pkcs8: Uint8Array;
+    /** The self-signed certificate's DER - what the server stores and data is sealed to. */
+    certificateDer: Uint8Array;
+    /** SHA-256 of `certificateDer`, lowercase hex. */
+    fingerprint: string;
+}
+
+async function loadX509(): Promise<typeof import("@peculiar/x509")> {
+    await import("reflect-metadata");
+    const x509 = await import("@peculiar/x509");
+    x509.cryptoProvider.set(crypto);
+    return x509;
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes as BufferSource));
+    return Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** A new meeting key valid until `expiresAt` (its certificate's `notAfter`). */
+export async function generateMeetingKey(expiresAt: Date): Promise<GeneratedMeetingKey> {
+    const x509 = await loadX509();
+    // ECDSA to self-sign the certificate; the same P-256 key is re-imported as ECDH to open what is sealed to it (`importMeetingKey()`).
+    const keys = (await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]));
+    const cert = await x509.X509CertificateGenerator.createSelfSigned({
+        serialNumber: toHex(crypto.getRandomValues(new Uint8Array(16))),
+        name: "CN=meeting",
+        notBefore: new Date(Date.now() - 60_000),
+        notAfter: expiresAt,
+        signingAlgorithm: { name: "ECDSA", hash: "SHA-256" },
+        keys,
+    });
+    const certificateDer = new Uint8Array(cert.rawData);
+    const pkcs8 = new Uint8Array(await crypto.subtle.exportKey("pkcs8", keys.privateKey));
+    return { pkcs8, certificateDer, fingerprint: await sha256Hex(certificateDer) };
+}
+
+function toHex(bytes: Uint8Array): string {
+    // A positive serial: the top bit clear.
+    const copy = Uint8Array.from(bytes);
+    copy[0] &= 0x7f;
+    return Array.from(copy, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** The `#` part a guest's link carries for `pkcs8`: `k=<base64url>`. */
+export function meetingKeyFragment(pkcs8: Uint8Array): string {
+    return `${MEETING_KEY_FRAGMENT_PARAM}=${toBase64Url(pkcs8)}`;
+}
+
+/** The meeting key in `hash` (a `location.hash`, with or without its `#`), or `undefined` when it carries none or it is malformed. */
+export function readMeetingKeyFragment(hash: string): Uint8Array | undefined {
+    const params = new URLSearchParams(hash.replace(/^#/, ""));
+    const value = params.get(MEETING_KEY_FRAGMENT_PARAM);
+    if (!value || !/^[A-Za-z0-9_-]{16,1024}$/.test(value)) {
+        return undefined;
+    }
+    try {
+        return fromBase64Url(value);
+    } catch {
+        return undefined;
+    }
+}
+
+/** The meeting key `pkcs8` as the CMS code opens with it, and its live key for meeting `meetingUid`. Rejects a key that isn't P-256. */
+export async function importMeetingKey(
+    pkcs8: Uint8Array,
+    certificateDer: Uint8Array,
+    meetingUid: string,
+): Promise<{ decryptionKey: DecryptionKey; liveKey: CryptoKey }> {
+    // Extractable once, only to read its scalar for the live key; the key kept for CMS isn't.
+    const readable = await crypto.subtle.importKey("pkcs8", pkcs8 as BufferSource, EC_PARAMS, true, ["deriveBits"]);
+    const jwk = await crypto.subtle.exportKey("jwk", readable);
+    /* v8 ignore next 3 -- an imported PKCS#8 private key always exports its scalar */
+    if (!jwk.d) {
+        throw new Error("This is not a meeting key.");
+    }
+    const privateKey = await crypto.subtle.importKey("pkcs8", pkcs8 as BufferSource, EC_PARAMS, false, ["deriveBits"]);
+    return { decryptionKey: { certDer: certificateDer, privateKey }, liveKey: await deriveLiveKey(fromBase64Url(jwk.d), meetingUid) };
+}
+
+/** The AES-256-GCM live key of meeting `meetingUid` from `ikm`, the meeting key's private scalar. Non-extractable. */
+export async function deriveLiveKey(ikm: Uint8Array, meetingUid: string): Promise<CryptoKey> {
+    const base = await crypto.subtle.importKey("raw", ikm as BufferSource, "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey(
+        { name: "HKDF", hash: "SHA-256", salt: new TextEncoder().encode(meetingUid), info: new TextEncoder().encode(LIVE_KEY_INFO) },
+        base,
+        { name: "AES-GCM", length: 256 },
+        false,
+        ["encrypt", "decrypt"],
+    );
+}