Core API Reference

function createVerifier(config?: VerifyKitCoreConfig): Promise<VerifyKitVerifier>

import { createVerifier } from '@trexolab/verifykit-core'
 
const verifier = await createVerifier({
  trustStore: { certificates: [pemString], mode: 'merge' },
  plugins: [revocationPlugin()],
})
 
const result = await verifier.verify(buffer, 'contract.pdf')
console.log(result.signatures[0].overallStatus) // "valid"
console.log(result.signatures[0].padesLevel)    // "B-T"
 
// Release resources when done.
verifier.dispose()

function verifyPdf(input: PdfInput, fileName?: string): Promise<VerificationResult>

import { verifyPdf } from '@trexolab/verifykit-core'
 
const buffer = await fetch('/document.pdf').then(r => r.arrayBuffer())
const result = await verifyPdf(buffer, 'document.pdf')
 
for (const sig of result.signatures) {
  console.log(sig.name, sig.overallStatus) // "Alice" "valid"
}

function extractPdfMetadata(input: PdfInput): Promise<{
  metadata: DocumentMetadata
  permissions: DocumentPermissions
}>

import { extractPdfMetadata } from '@trexolab/verifykit-core'
 
const { metadata, permissions } = await extractPdfMetadata(pdfBuffer)
 
console.log(metadata.title)        // "Annual Report 2025"
console.log(metadata.pageCount)    // 42
console.log(permissions.printing)  // "allowed"
console.log(permissions.encrypted) // false

function extractSignaturesFromPdf(buffer: ArrayBuffer): Promise<any[]>

function initWasm(): Promise<any>

import { initWasm } from '@trexolab/verifykit-core'
 
// Pre-warm during app boot (20-50ms)
await initWasm()

function setWasmUrl(source: string | URL | ArrayBuffer | WebAssembly.Module): void

import { setWasmUrl } from '@trexolab/verifykit-core'
 
// Load from a custom URL
setWasmUrl('/custom/path/verifykit_core_wasm_bg.wasm')
 
// Load from an ArrayBuffer
setWasmUrl(myWasmArrayBuffer)
 
// Load from a precompiled WebAssembly.Module
setWasmUrl(myCompiledModule)

function isWasmReady(): boolean

import { isWasmReady, initWasm } from '@trexolab/verifykit-core'
 
if (!isWasmReady()) {
  await initWasm()
}

function setTrustStoreConfig(config: TrustStoreConfig): Promise<void>

import { setTrustStoreConfig } from '@trexolab/verifykit-core'
 
await setTrustStoreConfig({
  certificates: [pemCert1, pemCert2],
  mode: 'merge', // "merge" adds to defaults; "replace" removes defaults
})

function resetTrustStore(): Promise<void>

function ensureTrustStoreReady(): Promise<void>

function getTrustStore(): TrustStore

function sha256hex(data: Uint8Array): Promise<string>

import { sha256hex } from '@trexolab/verifykit-core'
 
const hash = await sha256hex(new Uint8Array([0x50, 0x44, 0x46]))
// "b8e0e1..."

function buf2hex(buf: ArrayBuffer): string

function oidToName(oid: string): string

import { oidToName } from '@trexolab/verifykit-core'
 
oidToName('1.2.840.113549.1.1.11') // "SHA-256 with RSA"
oidToName('1.2.840.10045.4.3.2')   // "SHA-256 with ECDSA"
oidToName('1.3.101.112')           // "Ed25519"

function parseDn(dn: string): string

import { parseDn } from '@trexolab/verifykit-core'
 
parseDn('CN=Alice,O=Acme,C=US') // "CN=Alice, O=Acme, C=US"

function computeUnsignedFields(
  signatures: PdfSignature[],
  detectedFields?: Array<{ fieldName: string; pageNum: number }>,
): UnsignedSigField[]

function decompressFlate(data: Uint8Array): Promise<Uint8Array | null>

const isNode: boolean

function ensureCryptoEngine(): Promise<void>

interface VerifyKitVerifier {
  verify(input: PdfInput, fileName?: string): Promise<VerificationResult>
  extractMetadata(input: PdfInput): Promise<{
    metadata: DocumentMetadata
    permissions: DocumentPermissions
  }>
  dispose(): void
}

type VerificationStatus = "valid" | "invalid" | "warning" | "unknown" | "pending"

type PAdESLevel = "B-B" | "B-T" | "B-LT" | "B-LTA"

interface VerificationResult {
  fileName?: string            // Name of the verified file
  fileSize: number             // File size in bytes
  fileHash: string             // SHA-256 hex digest of the entire file
  signatures: PdfSignature[]   // All signatures found
  error?: string               // Set if the PDF could not be parsed
}

interface PdfSignature {
  index: number                          // 0-based signature index
  name: string                           // Signer display name
  fieldName: string                      // PDF form field name
  subFilter: string                      // e.g. "adbe.pkcs7.detached"
  byteRangeCoverage: boolean             // ByteRange is syntactically correct
  byteRangeCoversWholeFile: boolean      // ByteRange covers all file bytes
 
  // -- Eight independent checks --
  integrityCheck: SignatureCheckResult
  signatureCheck: SignatureCheckResult
  certificateChainCheck: SignatureCheckResult
  expiryCheck: SignatureCheckResult
  timestampCheck: SignatureCheckResult
  revocationCheck: SignatureCheckResult
  algorithmCheck: SignatureCheckResult
  ekuCheck: SignatureCheckResult
 
  // -- Certificate data --
  signerCertificate: CertificateInfo | null
  certificateChain: CertificateInfo[]
 
  // -- Timestamp --
  timestamp: TimestampInfo | null
 
  // -- Signature metadata --
  reason: string
  location: string
  contactInfo: string
  signingTime: Date | null
 
  // -- Overall verdict --
  overallStatus: VerificationStatus
  overallMessage: string
 
  // -- PDF-level properties --
  mdpPermission: number | null           // DocMDP permission (1, 2, or 3)
  isVisible: boolean                     // Visible signature appearance
  padesLevel?: PAdESLevel | null          // Detected PAdES conformance level (null for non-ETSI signatures)
 
  // -- Incremental save tracking --
  notYetVerified?: boolean
  isDeleted?: boolean
  deletedAtRevision?: number
}

interface SignatureCheckResult {
  label: string              // Human-readable check name
  status: VerificationStatus // Outcome
  detail: string             // Explanation text
  /** Whether the check was actively attempted (e.g., online revocation request made).
   *  Distinguishes "not checked" from "checked but inconclusive." */
  attempted?: boolean
}

interface CertificateInfo {
  subject: string                    // Distinguished name of the subject
  issuer: string                     // Distinguished name of the issuer
  serialNumber: string               // Certificate serial number (hex)
  notBefore: Date                    // Validity start
  notAfter: Date                     // Validity end
  isExpired: boolean                 // True if notAfter is in the past
  isCA: boolean                      // True if Basic Constraints CA=true
  subjectAltNames: string[]          // Subject Alternative Names
  fingerprint: string                // SHA-256 fingerprint
  sha1Fingerprint?: string           // SHA-1 fingerprint (legacy)
  keyAlgorithm: string               // e.g. "RSA", "EC"
  signatureAlgorithm: string         // e.g. "SHA-256 with RSA"
  keySize?: number                   // Key size in bits
  keyUsage?: string[]                // Key Usage extension values
  extKeyUsage?: string[]             // Extended Key Usage OIDs
  subjectKeyId?: string              // Subject Key Identifier
  authorityKeyId?: string            // Authority Key Identifier
  subjectNameHash?: string           // SHA-1 hash of DER-encoded subject name (hex), used for OCSP
  crlDistributionPoints?: string[]   // CRL distribution point URLs
  ocspUrls?: string[]                // OCSP responder URLs
  caIssuersUrls?: string[]           // CA Issuers URLs
  policies?: string[]                // Certificate policy OIDs
  rawDer?: ArrayBuffer               // Raw DER-encoded certificate bytes
}

interface TimestampInfo {
  time: Date                          // Timestamp time
  tsaName: string                     // Time Stamping Authority name
  hashAlgorithm: string              // Hash algorithm used
  verified: boolean                   // True if timestamp signature is valid
  tsaCertificates?: CertificateInfo[] // TSA certificate chain
}

interface DocumentMetadata {
  title: string
  author: string
  subject: string
  keywords: string
  creator: string          // Application that created the PDF
  producer: string         // PDF library that produced the file
  creationDate: Date | null
  modDate: Date | null
  pdfVersion: string       // e.g. "1.7"
  pageCount: number
}

interface DocumentPermissions {
  encrypted: boolean
  encryptionMethod: string           // e.g. "AES-256"
  permissionFlags: number | null     // Raw permission integer
  printing: "allowed" | "low-res" | "not-allowed"
  modification: boolean
  copying: boolean
  annotations: boolean
  formFilling: boolean
  accessibility: boolean
  assembly: boolean
}

interface VerifyKitCoreConfig {
  trustStore?: TrustStoreConfig
  plugins?: VerifyKitPlugin[]
  wasmUrl?: string | URL
  enableAIA?: boolean
}

interface TrustStoreConfig {
  certificates?: string[]     // PEM-encoded root CA certificates
  mode?: "merge" | "replace"  // "merge" adds to defaults; "replace" removes them
  url?: string                // URL to fetch certificate bundle from
  refreshInterval?: number    // Refresh interval in milliseconds
}

interface TrustStore {
  roots: ArrayBuffer[]         // Root CA certificates (DER)
  intermediates: ArrayBuffer[] // Intermediate certificates (DER)
  all: ArrayBuffer[]           // All certificates (DER)
}

type PdfInput = ArrayBuffer | Uint8Array | File | string

interface VerifyKitPlugin {
  name: string
  setup?: (ctx: PluginContext) => void | Promise<void>
  trustStore?: TrustStoreConfig
  revocation?: {
    checkCRL?: (cert: CertificateInfo, urls: string[]) => Promise<RevocationCheckResult>
    checkOCSP?: (cert: CertificateInfo, issuer: CertificateInfo, urls: string[]) => Promise<RevocationCheckResult>
  }
  inputResolver?: (input: PdfInput) => Promise<ArrayBuffer | null>
}

interface PluginContext {
  config: VerifyKitCoreConfig
}

interface UnsignedSigField {
  fieldName: string
  pageNum: number
}

const verifier = await createVerifier({ enableAIA: false })

interface RevocationCheckResult {
  status: "revoked" | "revokedAfterSigning" | "revokedNoTimestamp" | "good" | "unknown"
  revocationDate?: Date
  reason?: string
  source?: string   // e.g. "OCSP", "CRL"
}