Merge pull request Stellar-Mail#1811 from Killerjunior/feature/authenticate-attachment-metadata

Feature/authenticate attachment metadata

Author: kryputh

package-lock.json

@@ -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/attachment-metadata.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;
@@ -30,6 +31,8 @@ export interface EncryptionMetadata {
   nonce: string;
   mac: string;
   ephemeral_public_key?: string;
+  recipient_key_id?: string;
+  sender_key_id?: string;
 }
 
 export interface EnvelopePayload {
@@ -60,6 +63,8 @@ export interface SealEnvelopeInput {
   }>;
   /** When aborted, all internal references are released and the promise rejects. */
   signal?: AbortSignal;
+  recipientKeyId?: string;
+  senderKeyId?: string;
 }
 
 const GCM_TAG_BYTES = 16;
@@ -126,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);
@@ -142,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,
       ),
@@ -157,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);
@@ -196,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 } : {}),
       });
@@ -218,11 +259,14 @@ export async function sealEnvelope(input: SealEnvelopeInput): Promise<SealedEnve
 
     // Compute the content commitment BEFORE base64-encoding so the binary
     // ciphertext can be released immediately after.
-    const contentCommitment = await digestHex(ciphertext);
+    const contentCommitment = await createCommitment(ciphertext);
 
     // Encode the ciphertext — the binary buffer is no longer needed afterwards.
     const ciphertextBase64 = toBase64(ciphertext);
 
+    const nonceHex = toHex(iv);
+    const macHex = toHex(tag);
+
     // Release body ciphertext buffer now that both commitment and base64 are done.
     clearSecret(ciphertext);
     sharedPool.release(ivBuf);
@@ -234,8 +278,10 @@ export async function sealEnvelope(input: SealEnvelopeInput): Promise<SealedEnve
       timestamp: now ? now().toISOString() : new Date().toISOString(),
       encryption_metadata: {
         algorithm: "AES-256-GCM",
-        nonce: toHex(iv),
-        mac: toHex(tag),
+        nonce: nonceHex,
+        mac: macHex,
+        ...(input.recipientKeyId ? { recipient_key_id: input.recipientKeyId } : {}),
+        ...(input.senderKeyId ? { sender_key_id: input.senderKeyId } : {}),
       },
       content_commitment: contentCommitment,
       attachments,

src/services/crypto/envelope.ts

@@ -0,0 +1,163 @@
+/**
+ * Cryptographic key identifiers and rotation metadata.
+ *
+ * Implements deterministic derivation of collision-resistant key identifiers (Key IDs)
+ * and defines versioned key metadata for tracking rotation and revocation states.
+ */
+
+import { CryptoError } from "./errors";
+
+/**
+ * Key metadata tracking version, creation/expiry timestamps, and rotation state.
+ */
+export interface KeyMetadata {
+  /** Deterministic, collision-resistant identifier derived from the public key. */
+  keyId: string;
+  /** Cryptographic algorithm name (e.g. "Ed25519", "AES-256-GCM"). */
+  algorithm: string;
+  /** Version of the key, incremented upon rotation. */
+  version: number;
+  /** ISO 8601 timestamp representing the time of key creation/issuance. */
+  createdAt: string;
+  /** Optional ISO 8601 timestamp representing key expiration. */
+  expiresAt?: string;
+  /** Current state of the key in its lifecycle. */
+  rotationState: "active" | "rotated" | "revoked";
+}
+
+/**
+ * Policy defining which keys are eligible for decryption.
+ */
+export interface KeyRotationPolicy {
+  /** If false, only "active" keys can be used for decryption. */
+  allowRotatedKeys: boolean;
+  /** Optional grace period in seconds after expiration during which a key remains decryptable. */
+  gracePeriodSeconds?: number;
+  /** If true, expired keys can still decrypt envelopes (ignoring expiresAt). */
+  allowExpiredKeysForDecryption?: boolean;
+}
+
+/**
+ * Derives a deterministic, collision-resistant key identifier from a public key.
+ *
+ * Scheme:
+ * 1. Compute SHA-256 hash of the public key bytes.
+ * 2. Format the hash as a lowercase hex string.
+ * 3. Prefix with "kid_".
+ *
+ * @param publicKey The public key bytes (non-secret).
+ * @returns A promise resolving to the key identifier.
+ */
+export async function deriveKeyId(publicKey: Uint8Array): Promise<string> {
+  if (!publicKey || publicKey.length === 0) {
+    throw new CryptoError("crypto_key_error", "Public key bytes cannot be empty");
+  }
+
+  const hashBuffer = await crypto.subtle.digest("SHA-256", publicKey as BufferSource);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `kid_${hex}`;
+}
+
+/**
+ * Validates whether a key can be used for decryption according to the rotation policy.
+ *
+ * @param key The key metadata to evaluate.
+ * @param policy The rotation policy to enforce.
+ * @param referenceTime The reference time to check expiration against (defaults to now).
+ * @returns True if the key is decryptable, false otherwise.
+ */
+export function isKeyDecryptable(
+  key: KeyMetadata,
+  policy: KeyRotationPolicy,
+  referenceTime: Date = new Date(),
+): boolean {
+  if (key.rotationState === "revoked") {
+    return false;
+  }
+
+  if (key.rotationState === "rotated" && !policy.allowRotatedKeys) {
+    return false;
+  }
+
+  if (key.expiresAt && !policy.allowExpiredKeysForDecryption) {
+    const expiresTime = Date.parse(key.expiresAt);
+    if (Number.isNaN(expiresTime)) {
+      return false; // Safely fail closed on malformed dates.
+    }
+    const refMs = referenceTime.getTime();
+    if (refMs > expiresTime) {
+      if (policy.gracePeriodSeconds !== undefined) {
+        const graceMs = policy.gracePeriodSeconds * 1000;
+        if (refMs > expiresTime + graceMs) {
+          return false;
+        }
+      } else {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Resolves all eligible keys matching a given Key ID from a set of keys,
+ * enforcing the rotation policy.
+ *
+ * @param keyId The target key identifier.
+ * @param keys A pool of available keys.
+ * @param policy The rotation policy to filter by.
+ * @param referenceTime The reference time to check expiration against.
+ * @returns A filtered list of decryptable keys matching the Key ID.
+ */
+export function resolveKeysFromSet(
+  keyId: string,
+  keys: KeyMetadata[],
+  policy: KeyRotationPolicy,
+  referenceTime: Date = new Date(),
+): KeyMetadata[] {
+  return keys.filter((k) => k.keyId === keyId && isKeyDecryptable(k, policy, referenceTime));
+}
+
+/**
+ * Sorts and selects the best/primary key from a candidate list (e.g. in case of collision).
+ *
+ * Precedence rules:
+ * 1. "active" keys take precedence over "rotated" keys.
+ * 2. Higher version number takes precedence.
+ * 3. Newer creation time takes precedence.
+ *
+ * @param keys Candidates matching the criteria.
+ * @returns The best matching key, or undefined if the list is empty.
+ */
+export function selectBestKey(keys: KeyMetadata[]): KeyMetadata | undefined {
+  if (keys.length === 0) {
+    return undefined;
+  }
+
+  return [...keys].sort((a, b) => {
+    // 1. Rotation state (active first)
+    if (a.rotationState === "active" && b.rotationState !== "active") return -1;
+    if (a.rotationState !== "active" && b.rotationState === "active") return 1;
+
+    // 2. Version (higher first)
+    if (b.version !== a.version) {
+      return b.version - a.version;
+    }
+
+    // 3. Created time (newer first)
+    const timeA = Date.parse(a.createdAt);
+    const timeB = Date.parse(b.createdAt);
+    const validA = !Number.isNaN(timeA);
+    const validB = !Number.isNaN(timeB);
+
+    if (validA && validB) {
+      return timeB - timeA;
+    }
+    if (validA) return -1;
+    if (validB) return 1;
+
+    return 0;
+  })[0];
+}