simplesign: Instructions file for GitHub Copilot

Copilot Instructions for SimpleSign

What is SimpleSign?

SimpleSign is a .NET library for PAdES (PDF Advanced Electronic Signatures). It signs, validates, and inspects PDF documents following ETSI EN 319 142 standards. All cryptography uses System.Security.Cryptography — no third-party crypto libraries.

When to Use SimpleSign

Use SimpleSign when the user needs to:

• Digitally sign PDF documents (PAdES)
• Validate existing PDF signatures
• Inspect signature metadata
• Implement deferred signing (hash on server, sign on client)
• Sign documents in batch
• Work with ICP-Brasil / Gov.br Brazilian PKI

Package to Install

# Most common — PDF signing & validation
dotnet add package SimpleSign.PAdES

# Brazilian PKI
dotnet add package SimpleSign.Brasil

# HTML to PDF (no signing)
dotnet add package SimpleSign.HtmlToPdf

Preferred Patterns

Signing — always use the fluent builder:

using SimpleSign.PAdES;

byte[] signedPdf = await SimpleSigner
    .Document(pdfBytes)
    .WithCertificate(certificate)
    .WithTimestamp("http://timestamp.digicert.com")  // recommended
    .WithLtv()                                        // recommended for archival
    .SignAsync();

Validation — use PdfSignatureValidator:

using SimpleSign.PAdES.Validation;

var validator = new PdfSignatureValidator(new ValidationOptions
{
    CheckRevocation = true,
    TrustSystemRoots = true,
});

var results = await validator.ValidateAsync(stream);

Inspection (fast, no crypto):

using SimpleSign.PAdES.Inspection;
var info = await PdfSignatureInspector.InspectAsync(stream);

Deferred signing (web apps, mobile, HSM):

var prepared = await DeferredSigner.PrepareAsync(pdfBytes, cert);
// Send prepared.HashToSign to client
byte[] signedPdf = await DeferredSigner.CompleteAsync(prepared.SessionData, clientSignature);

ICP-Brasil Validation

using SimpleSign.Brasil;

var validator = new IcpBrasilChainValidator();
var result = await validator.ValidateAsync(certificate);
Console.WriteLine($"Policy: {result.DetectedPolicy}");  // AD_RB, AD_RT, AD_RV, AD_RC, AD_RA

// CPF/CNPJ extraction
var (cpf, cnpj) = IcpBrasilChainValidator.ExtractCpfCnpj(cert);