PD-103 — Agent Developer — Module M10 : capture-idempotence¶

// ============================================================================
// src/modules/capture/services/capture-idempotence.service.ts — PD-103 / M10
// ----------------------------------------------------------------------------
// Service d'idempotence pour le flux de capture probatoire.
// Construit le payload canonique, calcule le fingerprint SHA-256,
// et verifie l'idempotence sous advisory lock PostgreSQL.
//
// Alignement : PD-103-specification.md v3, §5.12
// Invariants couverts : INV-103-31, INV-103-37
// Pattern : identique a DepositService.checkIdempotenceOrConflict (PD-60)
// ============================================================================

import { ConflictException, Injectable, Logger } from '@nestjs/common';
import { createHash } from 'node:crypto';
import { EntityManager } from 'typeorm';

// =============================================================================
// Types
// =============================================================================

/**
 * Champs requis pour construire le payload canonique d'idempotence.
 * Conforme a §5.12 — definition normative.
 * Les champs optionnels OCR sont exclus par contrat (INV-103-37).
 */
export interface CanonicalPayloadFields {
  readonly captureId: string;
  readonly contentHash: string;
  readonly aesGcmNonceB64: string;
  readonly aesGcmTagB64: string;
  readonly dekWrappedB64: string;
  readonly kekId: string;
  readonly mimeType: string;
  readonly sizeBytes: number;
  readonly uploadObjectKey: string;
}

/** Resultat de la verification d'idempotence */
export type IdempotenceCheckResult =
  | { readonly action: 'CREATE'; readonly payloadCanonicalSha256: string }
  | { readonly action: 'IDEMPOTENT'; readonly existingCaptureEventId: string; readonly existingState: string };

// =============================================================================
// Service
// =============================================================================

@Injectable()
export class CaptureIdempotenceService {
  private readonly logger = new Logger(CaptureIdempotenceService.name);

  // ---------------------------------------------------------------------------
  // Public API
  // ---------------------------------------------------------------------------

  /**
   * Acquiert un advisory lock sur (userId, captureId), puis verifie l'idempotence.
   *
   * DOIT etre appele dans une transaction existante (manager fourni par M9).
   *
   * @returns CREATE si capture_id inconnu (avec fingerprint calcule)
   * @returns IDEMPOTENT si capture_id connu + fingerprint identique (200)
   * @throws ConflictException si capture_id connu + fingerprint divergent (409)
   */
  async acquireLockAndCheckIdempotence(
    manager: EntityManager,
    userId: string,
    fields: CanonicalPayloadFields,
  ): Promise<IdempotenceCheckResult> {
    // 1. Normaliser capture_id en lowercase (INV-103-31)
    const normalizedCaptureId = fields.captureId.toLowerCase();

    // 2. Serialisation lock : pg_advisory_xact_lock(hashtext(userId || '/' || captureId))
    //    Pattern identique a DepositService (PD-60, INV-60-02)
    await manager.query(`SELECT pg_advisory_xact_lock(hashtext($1 || '/' || $2))`, [
      userId,
      normalizedCaptureId,
    ]);

    // 3. Calculer le fingerprint canonique (INV-103-37)
    const payloadCanonicalSha256 = this.computeCanonicalFingerprint({
      ...fields,
      captureId: normalizedCaptureId,
      contentHash: fields.contentHash.toLowerCase(),
    });

    // 4. Lookup sous lock
    const existing = await manager.query(
      `SELECT id, state, payload_canonical_sha256
       FROM vault_secure.capture_events
       WHERE capture_id = $1
       LIMIT 1`,
      [normalizedCaptureId],
    ) as Array<{ id: string; state: string; payload_canonical_sha256: string }>;

    if (existing.length === 0) {
      // Capture inconnue — continuer la creation
      return { action: 'CREATE', payloadCanonicalSha256: payloadCanonicalSha256 };
    }

    const record = existing[0];

    // Comparaison fingerprint
    if (record.payload_canonical_sha256 === payloadCanonicalSha256) {
      // Meme fingerprint — replay idempotent (200)
      this.logger.log(
        `Idempotent replay detected for capture_id=${normalizedCaptureId}`,
      );
      return {
        action: 'IDEMPOTENT',
        existingCaptureEventId: record.id,
        existingState: record.state,
      };
    }

    // Fingerprint divergent — conflit (409)
    this.logger.warn(
      `Conflict detected for capture_id=${normalizedCaptureId}: ` +
        `stored=${record.payload_canonical_sha256.substring(0, 16)}..., ` +
        `received=${payloadCanonicalSha256.substring(0, 16)}...`,
    );
    throw new ConflictException({
      error: 'CONFLICT',
      message: 'capture_id already used with different payload',
    });
  }

  // ---------------------------------------------------------------------------
  // Canonical payload construction (§5.12)
  // ---------------------------------------------------------------------------

  /**
   * Calcule le fingerprint SHA-256 du payload canonique.
   *
   * Regles (§5.12) :
   * - Cles JSON triees alphabetiquement
   * - Serialisation UTF-8 deterministe sans espace superflu
   * - capture_id lowercase, content_hash lowercase
   * - Champs OCR exclus
   */
  computeCanonicalFingerprint(fields: CanonicalPayloadFields): string {
    const canonicalJson = this.buildCanonicalJson(fields);
    return createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
  }

  /**
   * Construit le JSON canonique pour le fingerprint d'idempotence.
   * Expose pour les tests uniquement.
   */
  buildCanonicalJson(fields: CanonicalPayloadFields): string {
    // Objet avec cles deja en ordre alphabetique (conforme §5.12)
    const canonical = {
      aes_gcm_nonce_b64: fields.aesGcmNonceB64,
      aes_gcm_tag_b64: fields.aesGcmTagB64,
      capture_id: fields.captureId.toLowerCase(),
      content_hash: fields.contentHash.toLowerCase(),
      dek_wrapped_b64: fields.dekWrappedB64,
      kek_id: fields.kekId,
      mime_type: fields.mimeType,
      size_bytes: fields.sizeBytes,
      upload_object_key: fields.uploadObjectKey,
    };

    // JSON.stringify avec replacer triant les cles garantit l'ordre
    // meme si un moteur JS ne respecte pas l'ordre d'insertion
    return JSON.stringify(canonical, Object.keys(canonical).sort());
  }
}

// src/modules/capture/__tests__/capture-idempotence.service.spec.ts

import { ConflictException } from '@nestjs/common';
import { CaptureIdempotenceService, CanonicalPayloadFields } from '../services/capture-idempotence.service';

describe('CaptureIdempotenceService', () => {
  let service: CaptureIdempotenceService;

  const baseFields: CanonicalPayloadFields = {
    captureId: 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
    contentHash: 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789',
    aesGcmNonceB64: 'dGVzdG5vbmNlMTIz',
    aesGcmTagB64: 'dGVzdHRhZzEyMzQ1Njc4OQ==',
    dekWrappedB64: 'ZGVrd3JhcHBlZGI2NA==',
    kekId: 'kek-2026-04-01',
    mimeType: 'image/png',
    sizeBytes: 524288,
    uploadObjectKey: 'captures/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d.enc',
  };

  beforeEach(() => {
    service = new CaptureIdempotenceService();
  });

  describe('buildCanonicalJson', () => {
    it('should produce deterministic JSON with sorted keys', () => {
      const json = service.buildCanonicalJson(baseFields);
      const parsed = JSON.parse(json);
      const keys = Object.keys(parsed);
      expect(keys).toEqual([...keys].sort());
    });

    it('should normalize capture_id to lowercase', () => {
      const json = service.buildCanonicalJson({
        ...baseFields,
        captureId: 'A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D',
      });
      const parsed = JSON.parse(json);
      expect(parsed.capture_id).toBe('a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d');
    });

    it('should normalize content_hash to lowercase', () => {
      const json = service.buildCanonicalJson({
        ...baseFields,
        contentHash: 'ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789',
      });
      const parsed = JSON.parse(json);
      expect(parsed.content_hash).toBe(
        'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789',
      );
    });

    it('should exclude OCR fields', () => {
      const json = service.buildCanonicalJson(baseFields);
      expect(json).not.toContain('ocr_text');
      expect(json).not.toContain('ocr_confidence');
      expect(json).not.toContain('ocr_language');
    });

    it('should include all 9 canonical fields', () => {
      const json = service.buildCanonicalJson(baseFields);
      const parsed = JSON.parse(json);
      expect(Object.keys(parsed)).toHaveLength(9);
      expect(parsed).toHaveProperty('aes_gcm_nonce_b64');
      expect(parsed).toHaveProperty('aes_gcm_tag_b64');
      expect(parsed).toHaveProperty('capture_id');
      expect(parsed).toHaveProperty('content_hash');
      expect(parsed).toHaveProperty('dek_wrapped_b64');
      expect(parsed).toHaveProperty('kek_id');
      expect(parsed).toHaveProperty('mime_type');
      expect(parsed).toHaveProperty('size_bytes');
      expect(parsed).toHaveProperty('upload_object_key');
    });

    it('should serialize size_bytes as number, not string', () => {
      const json = service.buildCanonicalJson(baseFields);
      expect(json).toContain('"size_bytes":524288');
      expect(json).not.toContain('"size_bytes":"524288"');
    });
  });

  describe('computeCanonicalFingerprint', () => {
    it('should return 64-char lowercase hex', () => {
      const fp = service.computeCanonicalFingerprint(baseFields);
      expect(fp).toMatch(/^[a-f0-9]{64}$/);
    });

    it('should be stable across calls (TC-NR-10)', () => {
      const fp1 = service.computeCanonicalFingerprint(baseFields);
      const fp2 = service.computeCanonicalFingerprint(baseFields);
      expect(fp1).toBe(fp2);
    });

    it('should produce same fingerprint regardless of capture_id casing (TC-INV-06 D)', () => {
      const fpLower = service.computeCanonicalFingerprint(baseFields);
      const fpUpper = service.computeCanonicalFingerprint({
        ...baseFields,
        captureId: baseFields.captureId.toUpperCase(),
      });
      expect(fpLower).toBe(fpUpper);
    });

    it('should differ when a canonical field changes (TC-INV-06 B)', () => {
      const fp1 = service.computeCanonicalFingerprint(baseFields);
      const fp2 = service.computeCanonicalFingerprint({
        ...baseFields,
        sizeBytes: 999999,
      });
      expect(fp1).not.toBe(fp2);
    });
  });

  describe('acquireLockAndCheckIdempotence', () => {
    let mockManager: { query: jest.Mock };

    beforeEach(() => {
      mockManager = {
        query: jest.fn(),
      };
    });

    it('should return CREATE when capture_id not found', async () => {
      // Lock query succeeds
      mockManager.query.mockResolvedValueOnce(undefined);
      // Lookup returns empty
      mockManager.query.mockResolvedValueOnce([]);

      const result = await service.acquireLockAndCheckIdempotence(
        mockManager as any,
        'user-123',
        baseFields,
      );

      expect(result.action).toBe('CREATE');
      expect((result as any).payloadCanonicalSha256).toMatch(/^[a-f0-9]{64}$/);
    });

    it('should return IDEMPOTENT when same fingerprint (TC-INV-06 A)', async () => {
      const expectedFp = service.computeCanonicalFingerprint(baseFields);

      mockManager.query.mockResolvedValueOnce(undefined);
      mockManager.query.mockResolvedValueOnce([
        { id: 'event-uuid', state: 'UPLOADED', payload_canonical_sha256: expectedFp },
      ]);

      const result = await service.acquireLockAndCheckIdempotence(
        mockManager as any,
        'user-123',
        baseFields,
      );

      expect(result.action).toBe('IDEMPOTENT');
    });

    it('should throw ConflictException when fingerprint differs (TC-ERR-13)', async () => {
      mockManager.query.mockResolvedValueOnce(undefined);
      mockManager.query.mockResolvedValueOnce([
        { id: 'event-uuid', state: 'UPLOADED', payload_canonical_sha256: 'a'.repeat(64) },
      ]);

      await expect(
        service.acquireLockAndCheckIdempotence(mockManager as any, 'user-123', baseFields),
      ).rejects.toThrow(ConflictException);
    });

    it('should acquire advisory lock with userId and normalized captureId', async () => {
      mockManager.query.mockResolvedValueOnce(undefined);
      mockManager.query.mockResolvedValueOnce([]);

      await service.acquireLockAndCheckIdempotence(
        mockManager as any,
        'user-123',
        { ...baseFields, captureId: 'A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D' },
      );

      // First call = advisory lock
      expect(mockManager.query).toHaveBeenCalledWith(
        `SELECT pg_advisory_xact_lock(hashtext($1 || '/' || $2))`,
        ['user-123', 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'],
      );
    });

    it('should query with normalized lowercase capture_id (INV-103-31)', async () => {
      mockManager.query.mockResolvedValueOnce(undefined);
      mockManager.query.mockResolvedValueOnce([]);

      await service.acquireLockAndCheckIdempotence(
        mockManager as any,
        'user-123',
        { ...baseFields, captureId: 'A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D' },
      );

      // Second call = lookup query
      const lookupCall = mockManager.query.mock.calls[1];
      expect(lookupCall[1]).toEqual(['a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d']);
    });
  });
});

// Dans CaptureIngestService.createCapture() — extrait simplifie
return this.dataSource.transaction(async (manager) => {
  // 1. Verification idempotence (M10)
  const idempotenceResult = await this.captureIdempotenceService
    .acquireLockAndCheckIdempotence(manager, userId, {
      captureId: dto.captureId,
      contentHash: dto.hashSha3256,
      aesGcmNonceB64: dto.aesGcmNonceB64,
      aesGcmTagB64: dto.aesGcmTagB64,
      dekWrappedB64: dto.dekWrappedB64,
      kekId: dto.kekId,
      mimeType: dto.mimeType,
      sizeBytes: dto.sizeBytes,
      uploadObjectKey: dto.uploadObjectKey,
    });

  if (idempotenceResult.action === 'IDEMPOTENT') {
    // Retourner 200 avec l'etat existant
    return { status: 200, captureEventId: idempotenceResult.existingCaptureEventId };
  }

  // 2. Unwrap DEK (M11)
  // 3. Persister capture_events (avec payloadCanonicalSha256)
  // 4. Retourner 202
});