ANTOOZA-BACKEND/Application/Abstractions/Crypto/IFieldEncryptor.cs

namespace Application.Abstractions.Crypto;

/// <summary>
/// 회원 PII(주소·연락처·수령인명 등) 필드 단위 암호화.
/// 운영 정책: AES-GCM 256bit. 키는 appsettings 의 Encryption.Keys 딕셔너리에서 KeyVersion 으로 매핑.
/// 키 회전 지원: 신규 암호화는 항상 CurrentKeyVersion 사용, 복호화는 row 의 KeyVersion 으로 과거 키 매핑.
/// </summary>
public interface IFieldEncryptor
{
    /// <summary>현재 사용 중인 키 버전. 신규 암호화 시 row 에 함께 저장.</summary>
    int CurrentKeyVersion { get; }

    /// <summary>
    /// 평문을 현재 키 버전으로 암호화. 반환값 형식: Base64(nonce 12B + ciphertext + tag 16B).
    /// </summary>
    string Encrypt(string plaintext);

    /// <summary>
    /// 지정된 키 버전으로 복호화. row 의 KeyVersion 컬럼 값을 그대로 전달.
    /// </summary>
    string Decrypt(string ciphertextBase64, int keyVersion);

    /// <summary>
    /// 검색용 SHA-256 hex 해시. 동일 평문 -> 동일 해시 (deterministic).
    /// 회원 주소 검색(수령인명 일치 등) 시 사용. 키와 무관 — 키 회전 영향 없음.
    /// </summary>
    string Hash(string plaintext);
}