SignatureKit
Signers

A1 Certificates

Read the holder identity of an A1 certificate (e-CPF / e-CNPJ), inspect the full certificate, and verify validity and ICP-Brasil fields.

What you will do: read the holder identity of an A1 certificate (e-CPF or e-CNPJ), inspect the full certificate, and check validity and ICP-Brasil fields. An A1 is a PKCS#12 file (.pfx/.p12) loaded by @signature-kit/a1; the runtime exposes two independent reads of the signing material.

Read the identity

signatures.inspect() returns an Effect<SignerIdentity, SignatureKitError> with the holder's essential fields — the cheap read: subject, issuer, serial number, thumbprint, validity window, and the optional document. Provide a Signatures layer (here a1SignaturesLayer) so the accessor can resolve the loaded material.

read-identity.ts
import { a1SignaturesLayer } from "@signature-kit/a1/signer"
import { signatures } from "@signature-kit/signatures"
import { Effect, Redacted } from "effect"

const layer = a1SignaturesLayer({
  pfx,                                          // Uint8Array — bytes of the .pfx/.p12
  password: Redacted.make(process.env.A1_PASSWORD ?? ""),
})

export const readIdentity = Effect.gen(function* () {
  const identity = yield* signatures.inspect()

  console.log(identity.subject)       // certificate holder
  console.log(identity.issuer)        // issuing CA (ICP-Brasil chain)
  console.log(identity.serialNumber)  // serial number
  console.log(identity.thumbprint)    // thumbprint
  console.log(identity.validFrom, identity.validTo)

  // e-CPF -> CPF; e-CNPJ -> CNPJ; absent if the OID is not recognized
  if (identity.document !== undefined) {
    console.log("document:", identity.document)
  }
}).pipe(Effect.provide(layer))

document is only populated when the certificate carries a recognized ICP-Brasil OID (e-CPF or e-CNPJ). For other profiles the field is absent — always test !== undefined.

The SignerIdentity type

The exact shape of what inspect returns. validFrom and validTo are Date; document is the only optional field.

signer-identity.ts
// return of signatures.inspect()
type SignerIdentity = {
  subject: string
  issuer: string
  serialNumber: string
  thumbprint: string
  validFrom: Date
  validTo: Date
  document?: string   // CPF (e-CPF) or CNPJ (e-CNPJ), when recognized
}

Inspect the certificate

When you need more than the identity, signatures.certificate() returns an Effect<Certificate, SignatureKitError> with the whole certificate: PEM, DER, public key, precomputed validity (isValid), SANs, and the brazilian block with the ICP-Brasil fields.

Caution

the accessor is signatures.certificate() — the full read on the same Signatures service as inspect(). privateKeyPem is Redacted<string>: it never appears in logs, console.log, or JSON.stringify. To get the PEM, call Redacted.value(...) explicitly, only at the boundary where the key is consumed.

inspect.ts
import { signatures } from "@signature-kit/signatures"
import { Effect, Redacted } from "effect"

// provide the same a1SignaturesLayer({ pfx, password }) as above
export const inspectCertificate = Effect.gen(function* () {
  const cert = yield* signatures.certificate()

  console.log(cert.isValid)        // boolean already computed by the chain
  console.log(cert.fingerprint)    // SHA-256 fingerprint (hex)
  console.log(cert.subjectAltName) // subject alternative name (string | null)
  console.log(cert.brazilian)      // { cnpj, cpf } — ICP-Brasil fields

  // the private key is Redacted: it does not appear in logs nor in JSON.stringify
  const pem = Redacted.value(cert.privateKeyPem) // only at the point of use
}).pipe(Effect.provide(layer))

The Certificate type

The full shape of what signatures.certificate() returns. Note the three certificate encodings (certPem, certificateDer, publicKeyDer) and the private key protected by Redacted.

certificate.ts
// return of signatures.certificate()
type Certificate = {
  serialNumber: string
  subject: {
    commonName: string | null
    organization: string | null
    organizationalUnit: string | null
    country: string | null
    state: string | null
    locality: string | null
    raw: string
  }
  issuer: {
    commonName: string | null
    organization: string | null
    country: string | null
    raw: string
  }
  validity: { notBefore: Date; notAfter: Date }
  fingerprint: string
  subjectAltName: string | null
  isValid: boolean
  brazilian: { cnpj: string | null; cpf: string | null }
  certPem: string
  certificateDer: Uint8Array
  intermediateCertificates: readonly Uint8Array[]   // intermediate CA chain, embedded by signPdf into the CMS SignedData
  publicKeyDer: Uint8Array
  privateKeyPem: Redacted<string>   // secret, never printed
}

Validity and ICP-Brasil

Install the low-level package to work directly with PKCS#12/X.509:

npm install @signature-kit/certificates

@signature-kit/certificates exposes pure utilities over the certificate: toSignerIdentity(cert) reduces a Certificate to the same SignerIdentity as inspect; isCertificateValid(cert) returns a boolean and daysUntilExpiry(cert), a number. For raw DER bytes, parseX509(der) returns an X509Info.

validity.ts
import { toSignerIdentity, isCertificateValid, daysUntilExpiry } from "@signature-kit/certificates"
import { signatures } from "@signature-kit/signatures"
import { Effect } from "effect"

// provide the same a1SignaturesLayer({ pfx, password }) as above
export const checkValidity = Effect.gen(function* () {
  // cert: Certificate coming from signatures.certificate()
  const cert = yield* signatures.certificate()

  // identity derived from the certificate (same shape as inspect())
  const identity = toSignerIdentity(cert)
  // identity.document is populated by the ICP-Brasil OIDs:
  //   2.16.76.1.3.1 -> e-CPF   (document = CPF)
  //   2.16.76.1.3.3 -> e-CNPJ  (document = CNPJ)

  // temporal validity and expiry window
  const valid = isCertificateValid(cert)   // boolean
  const days = daysUntilExpiry(cert)       // number

  if (!valid) {
    yield* Effect.logWarning("certificate out of validity")
  } else if (days < 30) {
    yield* Effect.logWarning(`certificate expires in ${days} day(s)`)
  }
}).pipe(Effect.provide(layer))

the ICP-Brasil OIDs populate the document field: 2.16.76.1.3.1 identifies the e-CPF (document = CPF) and 2.16.76.1.3.3 the e-CNPJ (document = CNPJ). extractBrazilianFields reads them internally; the values arrive ready in identity.document and cert.brazilian.

Errors you may see

Every read failure is a typed SignatureKitError in the error channel. The most common when reading certificates:

See also

Inspect validity with the Effect clock

inspectCertificateValidity reports notYetValid, valid, or expired, the evaluation time, remaining milliseconds, and whole days until expiry. Both validity boundaries are inclusive. It rejects invalid dates and reversed intervals as SignatureKitError. Use the remaining duration to choose an expiry-warning threshold in your application. This checks the validity interval; trust-chain and revocation verification remain separate operations. parseCertificate uses the same Effect clock for its isValid snapshot.

import { inspectCertificateValidity } from "@signature-kit/certificates";

declare const notBefore: Date;
declare const notAfter: Date;

const inspection = inspectCertificateValidity({ notBefore, notAfter });

How is this guide?

On this page