EnvelopeGenerator/EnvelopeGenerator.Infrastructure.Crypt/resources/INFRASTRUCTURE_PLAN.md

# FES Signature Infrastructure Plan

## 1. Goal

Build a reusable and modular cryptography infrastructure in `EnvelopeGenerator.Infrastructure.Crypt` to support FES (Advanced Electronic Signature) workflows.

This module must:

- use PKCS#11 providers (SoftHSMv2 first, real HSM later),
- stay independent from UI/API concerns,
- expose clean interfaces to `Application` layer use-cases,
- support future extensions (timestamping, certificate chain validation, multiple key algorithms).

---

## 2. Context and Constraints

1. SoftHSMv2 is **not** a REST service. It is a PKCS#11 module loaded as a native library.
2. `EnvelopeGenerator.Server` is presentation only; cryptographic implementation belongs to infrastructure.
3. Clean Architecture boundaries must be respected:
   - `Application` depends on abstractions.
   - `Infrastructure.Crypt` implements abstractions.
4. Initial target framework is `net8.0`.
5. We need production-ready behavior, not only PoC signing.

---

## 3. High-Level Design

## 3.1 Architecture slice

- **Application layer (contracts/use-cases):**
  - request signing hash/document,
  - request certificate/public key material,
  - request verification,
  - consume signature evidence result.

- **Infrastructure.Crypt layer (this project):**
  - PKCS#11 session handling,
  - key/certificate object discovery,
  - hash signing operations,
  - local cryptographic verification,
  - certificate parsing helpers,
  - error normalization.

## 3.2 Provider model

Define provider-agnostic APIs and add one concrete provider first:

- `Pkcs11SignatureProvider` (primary)
- future providers:
  - `RemoteSigningProvider` (if a dedicated signing gateway is introduced)
  - `MockSignatureProvider` (for deterministic test scenarios)

---

## 4. Deliverables (Phase by Phase)

## Phase 0 - Contracts and Domain Language

Create neutral models and interfaces in `Infrastructure.Crypt` (or shared abstractions if needed later):

- `SigningAlgorithm` (enum/value object)
- `Pkcs11ProviderOptions`
- `KeyLocator` (label/id/slot/token selectors)
- `SignHashRequest`
- `SignHashResult`
- `VerifySignatureRequest`
- `VerifySignatureResult`
- `CertificateDescriptor`
- `SignatureEvidence` (technical evidence payload)

Interfaces:

- `ISignatureProvider`
- `ICertificateProvider`
- `ISignatureVerifier`
- `ICryptographicHealthCheck`

Acceptance criteria:

- no dependency on ASP.NET types,
- no UI/API naming leakage,
- all model names are business-neutral.

## Phase 1 - PKCS#11 Core Adapter (SoftHSM-ready)

Implement:

- `Pkcs11LibraryLoader`
- `Pkcs11SessionFactory`
- `Pkcs11ObjectFinder`
- `Pkcs11SignatureProvider`
- `Pkcs11CertificateProvider`

Capabilities:

1. load module path from options (`libsofthsm2.so` or proxy module when required),
2. enumerate slots/tokens,
3. open read-write session,
4. login with user pin,
5. find private key by label/id,
6. sign digest with selected mechanism,
7. read certificate object by label/id.

Acceptance criteria:

- deterministic disposal of sessions,
- no leaked native handles,
- detailed typed errors (not raw exception strings only).

## Phase 2 - Verification and Certificate Utilities

Implement:

- `DefaultSignatureVerifier`
- `X509CertificateParser`
- optional `CertificateChainValidator` (toggleable)

Capabilities:

1. verify signature using returned certificate/public key,
2. expose certificate metadata (`thumbprint`, `subject`, `issuer`, `notBefore`, `notAfter`),
3. map validation failures into stable error codes.

Acceptance criteria:

- same request yields same verification outcome,
- invalid signature returns structured negative result.

## Phase 3 - Evidence Builder

Implement:

- `SignatureEvidenceBuilder`

Evidence payload should contain:

- transaction/correlation id,
- algorithm,
- hash metadata,
- key locator snapshot (safe subset),
- certificate fingerprint and subject,
- sign timestamp (UTC),
- verification outcome,
- provider type (`PKCS11`).

Acceptance criteria:

- no secret values in evidence (pin, private key id internals),
- evidence serializable for storage/audit.

## Phase 4 - Dependency Injection Module

Implement:

- `CryptInfrastructureDependencyInjection` extension methods

Methods:

- `AddCryptInfrastructure(...)`
- `AddPkcs11Provider(...)`

Acceptance criteria:

- one-line registration from composition root,
- options validation on startup.

## Phase 5 - Test Suite (`EnvelopeGenerator.Tests`)

Add test categories for `net8.0`:

1. `Unit`:
   - request validation,
   - algorithm mapping,
   - evidence building,
   - error mapping.
2. `Integration` (conditional/manual profile):
   - SoftHSM slot listing,
   - login,
   - sign hash,
   - verify,
   - certificate read.

Acceptance criteria:

- unit tests run in CI without native SoftHSM,
- integration tests run when module path + pins are provided via environment variables.

---

## 5. Proposed Project Structure

```text
EnvelopeGenerator.Infrastructure.Crypt/
  Abstractions/
    ISignatureProvider.cs
    ICertificateProvider.cs
    ISignatureVerifier.cs
    ICryptographicHealthCheck.cs
  Models/
    SigningAlgorithm.cs
    SignHashRequest.cs
    SignHashResult.cs
    VerifySignatureRequest.cs
    VerifySignatureResult.cs
    SignatureEvidence.cs
    CertificateDescriptor.cs
    KeyLocator.cs
  Options/
    Pkcs11ProviderOptions.cs
  Pkcs11/
    Pkcs11LibraryLoader.cs
    Pkcs11SessionFactory.cs
    Pkcs11ObjectFinder.cs
    Pkcs11SignatureProvider.cs
    Pkcs11CertificateProvider.cs
  Verification/
    DefaultSignatureVerifier.cs
    X509CertificateParser.cs
  Evidence/
    SignatureEvidenceBuilder.cs
  DependencyInjection/
    CryptInfrastructureDependencyInjection.cs
  Exceptions/
    CryptographicOperationException.cs
    Pkcs11ProviderException.cs
```

---

## 6. Configuration Strategy

Use options (bound from host config) with environment override support:

- `Crypt:Provider = PKCS11`
- `Crypt:Pkcs11:LibraryPath`
- `Crypt:Pkcs11:SlotId` or token selectors
- `Crypt:Pkcs11:UserPin` (from secret store/env, not plain committed value)
- `Crypt:Pkcs11:PrivateKeyLabel`
- `Crypt:Pkcs11:CertificateLabel`
- `Crypt:Pkcs11:LoginType`

Validation rules:

- library path required,
- at least one key locator required,
- pin required for signing operations.

---

## 7. Error Model

Define stable error codes to prevent provider-specific leakage:

- `CRYPT_PROVIDER_UNAVAILABLE`
- `CRYPT_SLOT_NOT_FOUND`
- `CRYPT_LOGIN_FAILED`
- `CRYPT_KEY_NOT_FOUND`
- `CRYPT_CERT_NOT_FOUND`
- `CRYPT_SIGN_FAILED`
- `CRYPT_VERIFY_FAILED`

Map low-level exceptions to these codes with safe diagnostics.

---

## 8. Non-Functional Requirements

1. **Security:** never log pins or raw private key handles.
2. **Reliability:** deterministic cleanup (`IDisposable`/`IAsyncDisposable`).
3. **Observability:** structured logs with correlation id.
4. **Performance:** avoid repeated login per operation when a safe session strategy is available.
5. **Extensibility:** algorithm/provider mapping must be open for extension.

---

## 9. Implementation Order (Small Tasks)

1. Add models + interfaces.
2. Add options + validators.
3. Add PKCS#11 low-level loader/session wrappers.
4. Implement `Pkcs11SignatureProvider` for hash signing.
5. Implement certificate retrieval.
6. Implement verifier.
7. Implement evidence builder.
8. Add DI registration extension.
9. Add unit tests.
10. Add optional integration tests (SoftHSM profile).

---

## 10. Definition of Done

Done means:

1. `Infrastructure.Crypt` exposes generic cryptographic services usable by Application use-cases.
2. SoftHSM-backed PKCS#11 sign/verify path works in integration tests.
3. All sensitive configuration is externalized.
4. Structured error codes are returned for expected failure scenarios.
5. Documentation exists for host registration and required settings.