PD-103 — Agent Developer — Module M2 : capture-crypto¶

let dek: Uint8Array | null = null;
try {
  dek = generateDEK();
  // ... utilisation du DEK ...
} finally {
  if (dek) {
    zeroize(dek);
  }
}

// --- crypto-pipeline.ts ---

// Fonctions pures
export function hashLocal(imageBytes: Uint8Array): Sha3_256Hash;
export function generateDEK(): Uint8Array;
export function generateNonce(): Uint8Array;
export function encryptFileLevel(
  imageBytes: Uint8Array,
  dek: Uint8Array,
  nonce: Uint8Array,
): { ciphertext: Uint8Array; tag: Uint8Array };
export function zeroizeDEK(buffer: Uint8Array): void;

// Classe orchestratrice
export class CryptoCapturePipeline {
  constructor(kekProvider: KekProvider);
  execute(imageBytes: Uint8Array): Promise<CryptoCapturePipelineResult>;
}

// Resultat du pipeline
export interface CryptoCapturePipelineResult {
  readonly hashSha3_256: Sha3_256Hash;
  readonly ciphertext: Uint8Array;
  readonly aesGcmNonceB64: AesGcmNonceB64;
  readonly aesGcmTagB64: AesGcmTagB64;
  readonly dekWrappedB64: DekWrappedB64;
  readonly kekId: KekId;
}

// --- kek-provider.ts ---

export interface KekProvider {
  /** Wrappe le DEK avec la KEK publique backend active (RSA-OAEP-SHA256) */
  wrapDEK(dek: Uint8Array): Promise<{ dekWrappedB64: DekWrappedB64; kekId: KekId }>;
  /** Retourne le kek_id de la cle active */
  getActiveKekId(): KekId;
}

export class StaticKekProvider implements KekProvider { ... }

import { sha3_256 } from "@noble/hashes/sha3";
import { bytesToHex } from "../crypto/utils";
import { asSha3_256Hash, type Sha3_256Hash } from "./types";

export function hashLocal(imageBytes: Uint8Array): Sha3_256Hash {
  if (imageBytes.length === 0) {
    throw new CaptureHashError("Image bytes cannot be empty");
  }
  const hashBytes = sha3_256(imageBytes);
  const hashHex = bytesToHex(hashBytes);
  return asSha3_256Hash(hashHex);
}

import * as Crypto from "expo-crypto";
import { AES_KEY_LENGTH } from "../crypto/constants";

export function generateDEK(): Uint8Array {
  return Crypto.getRandomBytes(AES_KEY_LENGTH);
}

import { AES_NONCE_LENGTH } from "../crypto/constants";

export function generateNonce(): Uint8Array {
  return Crypto.getRandomBytes(AES_NONCE_LENGTH);
}

import { gcm } from "@noble/ciphers/aes.js";
import { AES_KEY_LENGTH, AES_TAG_LENGTH } from "../crypto/constants";

export function encryptFileLevel(
  imageBytes: Uint8Array,
  dek: Uint8Array,
  nonce: Uint8Array,
): { ciphertext: Uint8Array; tag: Uint8Array } {
  if (dek.length !== AES_KEY_LENGTH) {
    throw new CaptureEncryptionError("DEK must be exactly 32 bytes (256 bits)");
  }
  if (nonce.length !== AES_NONCE_LENGTH) {
    throw new CaptureEncryptionError("Nonce must be exactly 12 bytes (96 bits)");
  }

  const cipher = gcm(dek, nonce);
  const ciphertextWithTag = cipher.encrypt(imageBytes);

  const ciphertext = ciphertextWithTag.slice(0, -AES_TAG_LENGTH);
  const tag = ciphertextWithTag.slice(-AES_TAG_LENGTH);

  return { ciphertext, tag };
}

import { zeroize } from "../crypto/zeroize";

export function zeroizeDEK(buffer: Uint8Array): void {
  zeroize(buffer);
}

export class CryptoCapturePipeline {
  constructor(private readonly kekProvider: KekProvider) {}

  async execute(imageBytes: Uint8Array): Promise<CryptoCapturePipelineResult> {
    if (imageBytes.length === 0) {
      throw new CaptureHashError("Image bytes cannot be empty");
    }

    // Etape 1 : hash local (INV-103-03)
    const hashSha3_256 = hashLocal(imageBytes);

    // Etape 2-6 : encrypt + wrap avec zeroization garantie
    let dek: Uint8Array | null = null;
    try {
      dek = generateDEK();
      const nonce = generateNonce();

      // Etape 4 : chiffrement file-level (INV-103-06)
      const { ciphertext, tag } = encryptFileLevel(imageBytes, dek, nonce);

      // Etape 5 : wrapping DEK (INV-103-30)
      const { dekWrappedB64, kekId } = await this.kekProvider.wrapDEK(dek);

      // Conversion base64 pour le DTO
      const aesGcmNonceB64 = asAesGcmNonceB64(bytesToBase64(nonce));
      const aesGcmTagB64 = asAesGcmTagB64(bytesToBase64(tag));

      return {
        hashSha3_256,
        ciphertext,
        aesGcmNonceB64,
        aesGcmTagB64,
        dekWrappedB64,
        kekId,
      };
    } finally {
      // Etape 6 : zeroization (INV-103-32)
      if (dek) {
        zeroizeDEK(dek);
      }
    }
  }
}

export class CaptureHashError extends Error {
  readonly code = CAPTURE_ERROR_CODES.HASH_MISMATCH;
  constructor(message: string) {
    super(message);
    this.name = "CaptureHashError";
  }
}

export class CaptureEncryptionError extends Error {
  readonly code = CAPTURE_ERROR_CODES.ENCRYPTION_FAILED;
  constructor(message: string) {
    super(message);
    this.name = "CaptureEncryptionError";
  }
}

import type { DekWrappedB64, KekId } from "./types";

export interface KekProvider {
  wrapDEK(dek: Uint8Array): Promise<{ dekWrappedB64: DekWrappedB64; kekId: KekId }>;
  getActiveKekId(): KekId;
}

import { bytesToBase64 } from "../crypto/utils";
import { asDekWrappedB64, asKekId } from "./types";
import type { DekWrappedB64, KekId } from "./types";

export class StaticKekProvider implements KekProvider {
  constructor(
    private readonly publicKey: CryptoKey | Uint8Array,
    private readonly kekId: KekId,
  ) {}

  async wrapDEK(dek: Uint8Array): Promise<{ dekWrappedB64: DekWrappedB64; kekId: KekId }> {
    // RSA-OAEP-SHA256 wrapping via react-native-quick-crypto ou SubtleCrypto
    const wrappedBytes = await this.rsaOaepWrap(dek);
    const dekWrappedB64 = asDekWrappedB64(bytesToBase64(wrappedBytes));
    return { dekWrappedB64, kekId: this.kekId };
  }

  getActiveKekId(): KekId {
    return this.kekId;
  }

  private async rsaOaepWrap(dek: Uint8Array): Promise<Uint8Array> {
    // Implementation depend du runtime :
    // - react-native-quick-crypto : crypto.publicEncrypt()
    // - SubtleCrypto (si disponible) : crypto.subtle.encrypt()
    // Decouplage via cette interface permet de swapper sans refactoring
    throw new Error("RSA-OAEP wrapping not implemented — requires native crypto module");
  }
}

// src/__tests__/capture/crypto-pipeline.test.ts

describe("capture/crypto-pipeline", () => {
  // --- TC-INV-02 : hashLocal ---
  describe("hashLocal (INV-103-03)", () => {
    it("TC-INV-02: retourne un hash SHA3-256 hex lowercase 64 chars", ...);
    it("TC-INV-02: hash est deterministe", ...);
    it("TC-INV-02: hash differe pour des images differentes", ...);
    it("TC-ERR-05: leve CaptureHashError si image vide", ...);
  });

  // --- Fonctions utilitaires ---
  describe("generateDEK", () => {
    it("retourne 32 bytes", ...);
  });

  describe("generateNonce (INV-103-39)", () => {
    it("retourne 12 bytes", ...);
    it("deux appels produisent des valeurs differentes", ...);
  });

  // --- TC-ERR-07 : encryptFileLevel ---
  describe("encryptFileLevel (INV-103-06)", () => {
    it("chiffre avec AES-256-GCM et retourne ciphertext + tag", ...);
    it("ciphertext est dechiffrable avec le meme DEK et nonce", ...);
    it("tag fait exactement 16 bytes", ...);
    it("ciphertext est different du plaintext", ...);
    it("TC-ERR-07: leve CaptureEncryptionError si DEK taille incorrecte", ...);
    it("TC-ERR-07: leve CaptureEncryptionError si nonce taille incorrecte", ...);
  });

  // --- TC-INV-12 : zeroizeDEK ---
  describe("zeroizeDEK (INV-103-32)", () => {
    it("TC-INV-12: ecrase chaque octet du buffer a 0x00", ...);
    it("TC-INV-12: modifie le buffer in-place", ...);
  });

  // --- TC-INV-03 : CryptoCapturePipeline ---
  describe("CryptoCapturePipeline (INV-103-03, 06, 09, 30, 39)", () => {
    it("TC-INV-03: execute le pipeline complet et retourne tous les artefacts", ...);
    it("TC-INV-03: nonce_b64 respecte le pattern contractuel", ...);
    it("TC-INV-03: tag_b64 respecte le pattern contractuel", ...);
    it("TC-INV-03: le DEK n'apparait pas dans le resultat", ...);
    it("zeroize le DEK meme si wrapDEK echoue", ...);
    it("leve CaptureHashError si image vide", ...);
  });
});