feat: authenticate attachment descriptors as protected metadata

Author: Killerjunior

src/services/crypto/attachment-metadata.ts

@@ -0,0 +1,44 @@
+import { canonicalize } from "./jcs";
+
+export interface AttachmentDescriptor {
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+  content_hash: string;
+}
+
+/**
+ * Canonicalizes attachment descriptors for additional authenticated data (AAD).
+ * Uses RFC 8785 JSON Canonicalization Scheme (JCS) under the hood.
+ * Authenticates filename, MIME type, size, ordering, and content commitment.
+ */
+export function canonicalizeAttachmentDescriptors(attachments: AttachmentDescriptor[]): Uint8Array {
+  const normalized = attachments.map((a) => ({
+    filename: a.filename,
+    content_type: a.content_type,
+    size_bytes: a.size_bytes,
+    content_hash: a.content_hash,
+  }));
+  const canonicalString = canonicalize(normalized);
+  return new TextEncoder().encode(canonicalString);
+}
+
+/**
+ * Safe filename normalization for display purposes.
+ * Strips directory traversal segments and unsafe characters.
+ * This is handled before display, not inside the cryptographic identity.
+ */
+export function sanitizeFilenameForDisplay(filename: string): string {
+  // Replace backslashes with forward slashes
+  let safe = filename.replace(/\\/g, "/");
+
+  // Remove directory traversal sequences (../ or ./)
+  safe = safe.replace(/(?:\.\.\/|\.\/)/g, "");
+
+  // Strip leading slashes
+  safe = safe.replace(/^\/+/, "");
+
+  // Extract the base filename segment
+  const lastSegment = safe.split("/").pop();
+  return lastSegment || "unnamed_attachment";
+}

src/services/crypto/envelope.ts

@@ -15,6 +15,7 @@ import { clearSecret, digestHex, sharedPool, toBase64, toHex } from "./memory";
 import { getCryptoTestVectors } from "./testing";
 import { createCommitment } from "./commitment";
 import { recordCryptoTelemetry, type CryptoResultCode } from "./telemetry";
+import { canonicalizeAttachmentDescriptors } from "./attachment-metadata";
 
 export interface EnvelopeAttachment {
   filename: string;
@@ -130,6 +131,57 @@ export async function sealEnvelope(input: SealEnvelopeInput): Promise<SealedEnve
           "decrypt",
         ]);
 
+    // --- Pre-process attachments to get descriptors for AAD ---
+    const attachmentsToProcess = input.attachments ?? [];
+    const descriptors: Array<{
+      filename: string;
+      content_type: string;
+      size_bytes: number;
+      content_hash: string;
+    }> = [];
+    const preparedAttachments: Array<{
+      filename: string;
+      content_type: string;
+      size_bytes: number;
+      data?: ArrayBuffer;
+      content_hash: string;
+    }> = [];
+
+    for (const attachment of attachmentsToProcess) {
+      let hash: string;
+      if (attachment.data) {
+        // View into caller's ArrayBuffer — no copy for hashing.
+        const dataBytes = new Uint8Array(attachment.data);
+        hash = await digestHex(dataBytes);
+        if (attachment.content_hash && hash !== attachment.content_hash) {
+          throw new Error(
+            `Mismatch between supplied bytes and content_hash for attachment ${attachment.filename}`,
+          );
+        }
+      } else if (attachment.content_hash) {
+        hash = attachment.content_hash;
+      } else {
+        throw new Error(
+          `Attachment ${attachment.filename} must include either data bytes or a validated content_hash`,
+        );
+      }
+      descriptors.push({
+        filename: attachment.filename,
+        content_type: attachment.content_type,
+        size_bytes: attachment.size_bytes,
+        content_hash: hash,
+      });
+      preparedAttachments.push({
+        filename: attachment.filename,
+        content_type: attachment.content_type,
+        size_bytes: attachment.size_bytes,
+        data: attachment.data,
+        content_hash: hash,
+      });
+    }
+
+    const aad = canonicalizeAttachmentDescriptors(descriptors);
+
     // --- Body encryption ---
     throwIfAborted();
     const ivBuf = sharedPool.acquire(12);
@@ -146,7 +198,7 @@ export async function sealEnvelope(input: SealEnvelopeInput): Promise<SealedEnve
     // a pool buffer, but we manage the result lifecycle explicitly below.
     const ciphertext = new Uint8Array(
       await crypto.subtle.encrypt(
-        { name: "AES-GCM", iv: iv as BufferSource },
+        { name: "AES-GCM", iv: iv as BufferSource, additionalData: aad as BufferSource },
         key,
         plaintext as BufferSource,
       ),
@@ -161,22 +213,13 @@ export async function sealEnvelope(input: SealEnvelopeInput): Promise<SealedEnve
     // --- Attachments (sequential, buffers freed per iteration) ---
     throwIfAborted();
     const attachments: EnvelopeAttachment[] = [];
-    for (const attachment of input.attachments ?? []) {
+    for (const attachment of preparedAttachments) {
       throwIfAborted();
-      let hash: string;
       let encMetadata: EncryptionMetadata | undefined;
       let ciphertextStr: string | undefined;
 
       if (attachment.data) {
-        // View into caller's ArrayBuffer — no copy for hashing.
         const dataBytes = new Uint8Array(attachment.data);
-        hash = await digestHex(dataBytes);
-        if (attachment.content_hash && hash !== attachment.content_hash) {
-          throw new Error(
-            `Mismatch between supplied bytes and content_hash for attachment ${attachment.filename}`,
-          );
-        }
-
         const attIv = sharedPool.acquire(12);
         const attIvView = new Uint8Array(attIv, 0, 12);
         crypto.getRandomValues(attIvView);
@@ -200,18 +243,12 @@ export async function sealEnvelope(input: SealEnvelopeInput): Promise<SealedEnve
         // Release attachment crypto buffers.
         clearSecret(attCiphertext);
         sharedPool.release(attIv);
-      } else if (attachment.content_hash) {
-        hash = attachment.content_hash;
-      } else {
-        throw new Error(
-          `Attachment ${attachment.filename} must include either data bytes or a validated content_hash`,
-        );
       }
       attachments.push({
         filename: attachment.filename,
         content_type: attachment.content_type,
         size_bytes: attachment.size_bytes,
-        content_hash: hash,
+        content_hash: attachment.content_hash,
         ...(encMetadata ? { encryption_metadata: encMetadata } : {}),
         ...(ciphertextStr ? { ciphertext: ciphertextStr } : {}),
       });

src/services/crypto/open-envelope.ts

@@ -15,6 +15,7 @@
 
 import { verifyCommitment } from "./commitment";
 import { recordCryptoTelemetry, type CryptoResultCode } from "./telemetry";
+import { canonicalizeAttachmentDescriptors } from "./attachment-metadata";
 
 /** Minimal non-secret error carrying a stable code (no key/plaintext leakage). */
 export class OpenEnvelopeError extends Error {
@@ -213,6 +214,25 @@ export async function openEnvelope(
       throw new OpenEnvelopeError("recipient key unavailable", "crypto_decryption_error");
     }
 
+    const parsedAttachments = Array.isArray(payload.attachments)
+      ? payload.attachments.map((a) => ({
+          filename: str((a as { filename?: unknown }).filename, "attachment.filename"),
+          content_type: str(
+            (a as { content_type?: unknown }).content_type,
+            "attachment.content_type",
+          ),
+          size_bytes: Number(
+            str((a as { size_bytes?: unknown }).size_bytes, "attachment.size_bytes"),
+          ),
+          content_hash: str(
+            (a as { content_hash?: unknown }).content_hash,
+            "attachment.content_hash",
+          ),
+        }))
+      : [];
+
+    const aad = canonicalizeAttachmentDescriptors(parsedAttachments);
+
     const iv = fromHex(nonceHex);
     const ivCopy = new Uint8Array(new ArrayBuffer(iv.length));
     ivCopy.set(iv);
@@ -223,7 +243,11 @@ export async function openEnvelope(
     // fails closed on tamper or wrong key).
     let decrypted: ArrayBuffer;
     try {
-      decrypted = await crypto.subtle.decrypt({ name: "AES-GCM", iv: ivCopy }, key, ctCopy);
+      decrypted = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv: ivCopy, additionalData: aad as BufferSource },
+        key,
+        ctCopy,
+      );
     } catch {
       throw new OpenEnvelopeError(
         "decryption failed (wrong key or tampered)",
@@ -233,29 +257,12 @@ export async function openEnvelope(
 
     const body = new TextDecoder().decode(new Uint8Array(decrypted));
 
-    const attachments = Array.isArray(payload.attachments)
-      ? payload.attachments.map((a) => ({
-          filename: str((a as { filename?: unknown }).filename, "attachment.filename"),
-          content_type: str(
-            (a as { content_type?: unknown }).content_type,
-            "attachment.content_type",
-          ),
-          size_bytes: Number(
-            str((a as { size_bytes?: unknown }).size_bytes, "attachment.size_bytes"),
-          ),
-          content_hash: str(
-            (a as { content_hash?: unknown }).content_hash,
-            "attachment.content_hash",
-          ),
-        }))
-      : [];
-
     return {
       sender,
       recipient,
       timestamp,
       body,
-      attachments,
+      attachments: parsedAttachments,
       recipientKeyId,
       senderKeyId,
     };