Digital Certificate Compliance Module

Digital certificates in Brazil are legally required for almost every operational task that touches government systems — issuing invoices, submitting payroll data, signing tax filings, accessing federal portals. For an accounting firm managing dozens of client companies, this means hundreds of certificates across two types: software certificates (A1, stored as encrypted files) and hardware tokens (A3, stored on physical USB devices).

Each certificate has an expiration date. When it expires, it becomes legally invalid — the company cannot sign anything. In practice this means: a certificate expires on a Friday, the client calls Monday morning because they cannot issue invoices, and now the accounting team is scrambling to renew it retroactively.

Before this module, the firm tracked certificate expiry in a spreadsheet. Manually. One person kept it updated when they remembered. When that person was on vacation, the spreadsheet went stale. When someone left the firm, institutional knowledge of where certificates were stored left with them.

The engineering problem was not “store a list of certificates.” That is a CRUD table. The real problem was: how do you automatically discover, parse, and track certificates that live in a directory tree managed by a legacy ERP — across hundreds of client folders, with inconsistent organization, mixed naming conventions, and credentials stored in various formats the system does not control?

One of the first architectural decisions was recognizing that A1 and A3 certificates have fundamentally different management workflows — and designing the module to handle both cleanly.

This distinction matters throughout the system: A3 certificates are never auto-updated by scans. A1 certificates are never manually created. Deactivating an A1 certificate happens automatically when the scan no longer finds its file on disk. Deactivating an A3 certificate requires an explicit operator action.

The scan is the most operationally complex piece of this module. It is a data pipeline that runs on demand, walks a directory tree, handles every edge case gracefully, and updates the certificate database without human intervention.

The pipeline handles real-world messiness gracefully. A folder with a wrong password creates a wrong_password verification — visible in the Verificações view — without blocking the rest of the scan. A folder with the same certificate copied to multiple locations is deduplicated by serial number so the database stays clean.

The deactivation step runs only after all upserts are complete — by design. During the scan, a certificate not yet processed is indistinguishable from one that no longer exists. Only after the full scan can the system confidently mark a record as stale.

Certificate passwords are operationally sensitive — they unlock credentials used to sign legal documents. The module treats credential management as a security concern at the architecture level, not a UI toggle.

The module follows the same four-layer structure as every other module in the platform, with one addition: a scanning sub-module with its own independent domain.

The scanning sub-module is a deliberate design decision. The scanning pipeline has its own domain vocabulary (batches, verifications, candidate resolution) that would contaminate the certificate management domain if mixed together. Keeping them separate means: the certificate module works correctly even if the scanning infrastructure is unavailable. The scan produces certificates; it does not define what a certificate is.

Brazilian certificates issued under ICP-Brasil standards embed identity information in specific ASN.1 extensions not found in generic X.509 certificates. The OID 2.16.76.1.3.2 carries the name of the natural person legally responsible for the company — the responsável.

Extracting this field requires parsing OtherName structures inside the Subject Alternative Name extension — ASN.1 traversal that goes beyond what the node-forge library exposes through its standard API. The adapter handles this with explicit tree walking, silently ignoring malformed extensions rather than failing the parse.

Why does this matter? For compliance monitoring, showing the responsible person's name alongside the company name and document gives the accounting team the context they need to identify who to contact when a certificate is about to expire.

The firm's legacy ERP holds the canonical list of active client companies. The “Companies without certificates” KPI cross-references that list against the certificate database — flagging companies that have no certificate registered in the platform.

This integration uses a raw pg.Pool connection to the legacy PostgreSQL database, separate from the platform's Prisma client. The repository class is typed as read-only by contract: its interface has no write methods, and the SQL is a single parameterized SELECT. If the legacy database is unavailable (the connection pool is null), the repository returns legacyAvailable: false and the KPI card renders in a graceful disabled state rather than failing the page.

This is not a module you design by reading framework documentation. The operational edge cases — what to do with three certificates in one folder, how to detect when a certificate file has been removed from disk, how to handle the same cert copied to a backup location, what it means when CNPJ validation fails — come from understanding how accounting firms actually organize their client data.

The encryption choices (AES-256-GCM over simpler alternatives), the audit design (logging failures, not just successes), the deactivation timing (after upserts, not during), the dual sub-module boundary (scanning vs. management) — none of these are obvious from the requirements document. They are the result of thinking through the operational consequences of each decision before writing the code.

Understanding compliance systems, certificate authority chains, and ICP-Brasil standards well enough to know which X.509 fields to extract — and which ASN.1 OIDs carry the data that the accounting team actually needs — that context does not come from building web applications. It comes from spending years inside the operational workflows this system was built to replace.