Introduction
Effect-native signing for TypeScript — A1 first, one Signatures boundary, XML/PDF formats around it, and browser UI at the app edge.
SignatureKit has one signing boundary: the Signatures Effect service. Start with an A1 / PKCS#12 certificate, then reuse the same boundary from Node, the browser, XML-DSig, and PDF/PAdES. Remote providers stay separate provider APIs; browser UI stays at the application edge.
Choose the path
Install A1
Add the Effect runtime, the core Signatures service, and the PKCS#12 signer.
First signature
Load an A1 certificate, inspect the identity, sign bytes, and verify the result.
PDF/PAdES
Sign PDFs by placing a detached CMS signature into a PDF placeholder.
Browser PDF flow
Read PDF bytes, render placement UI, and provide the A1 layer only at the action boundary.
One boundary
import { a1SignaturesLayer } from "@signature-kit/a1/signer"
import { signatures } from "@signature-kit/core/signatures"
import { Effect, Redacted } from "effect"
export const signWithA1 = (content: Uint8Array, pfx: Uint8Array, password: string) =>
Effect.gen(function* () {
const identity = yield* signatures.inspect()
const artifact = yield* signatures.sign({ content, algorithm: "rsa-sha256" })
return { identity, artifact }
}).pipe(
Effect.provide(
a1SignaturesLayer({
pfx,
password: Redacted.make(password),
}),
),
)The program knows the contract, not the key location. Browser A1, server A1, XML, and PDF/PAdES all provide or consume the same service.
Product rules
- A1 first. The first local signer is PKCS#12 (
.pfx/.p12) with passwords kept inRedacted. - Browser PDF is format-owned.
@signature-kit/pdfowns file bytes, placement state, and browser A1 PDF signing; app UI only subscribes to that state and providesa1SignaturesLayerat the action boundary. - Formats mutate documents. XML-DSig and PDF/PAdES own document mutation around
signatures.sign; signer adapters only own signing power. - Remote APIs stay explicit. Clicksign, Assinafy, ZapSign, DocuSeal, and Documenso keep provider-specific APIs instead of pretending to be one universal signer.
- Failures are values. Recoverable faults are typed
SignatureKitErroror package-specific Effect errors, not thrown exceptions.
Go deeper
PDF/PAdES
Detached CMS signing and placeholder sizing for PDF documents.
XML-DSig
XML mutation through an explicit XmlRuntime dependency.
Provider APIs
Clicksign, Assinafy, ZapSign, DocuSeal, and Documenso as explicit upstream request packages.
Error catalog
Literal error codes and the metadata preserved at each failure point.
npm install @signature-kit/core @signature-kit/a1Local checks are not legal validity
verifyXml, verifyPdf, and signatures.verify confirm the cryptography against the key in the
document — not legal validity. Verify with your own ICP-Brasil trust chain and policy before
treating a signed document as valid.