pdf-oxide-fips 0.3.47

package/lib/managers/signature-manager.d.ts

@@ -0,0 +1,738 @@
+/**
+ * SignatureManager - Canonical Signature Manager (merged from 3 implementations)
+ *
+ * Consolidates:
+ * - src/signature-manager.ts SignatureManager (verification + basic field management)
+ * - src/managers/barcode-signature-rendering.ts SignaturesManager (certificate loading + signing + detail info)
+ * - src/managers/signature-creation-manager.ts SignatureCreationManager (complete signing workflow + LTV + timestamps)
+ *
+ * Provides comprehensive digital signature operations with full type safety
+ * and FFI integration.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Signature algorithms
+ */
+export declare enum SignatureAlgorithm {
+    RSA2048 = "RSA2048",
+    RSA3072 = "RSA3072",
+    RSA4096 = "RSA4096",
+    ECDSAP256 = "ECDSA_P256",
+    ECDSAP384 = "ECDSA_P384",
+    ECDSAP521 = "ECDSA_P521",
+    RSA_SHA256 = "RSA_SHA256",
+    RSA_SHA384 = "RSA_SHA384",
+    RSA_SHA512 = "RSA_SHA512",
+    ECDSA_SHA256 = "ECDSA_SHA256",
+    ECDSA_SHA384 = "ECDSA_SHA384",
+    ECDSA_SHA512 = "ECDSA_SHA512",
+    ED25519 = "ED25519"
+}
+/**
+ * Digest algorithms for signature
+ */
+export declare enum DigestAlgorithm {
+    SHA256 = "SHA256",
+    SHA384 = "SHA384",
+    SHA512 = "SHA512",
+    SHA512_256 = "SHA512_256"
+}
+/**
+ * Signature type enumeration
+ */
+export declare enum SignatureType {
+    APPROVAL = "approval",
+    CERTIFICATION = "certification",
+    USAGE_RIGHTS = "usage_rights"
+}
+/**
+ * Certification permission level
+ */
+export declare enum CertificationPermission {
+    NO_CHANGES = 1,
+    FORM_FILLING = 2,
+    FORM_FILLING_ANNOTATIONS = 3
+}
+/**
+ * Certificate format enumeration
+ */
+export declare enum CertificateFormat {
+    PFX = "pfx",
+    PEM = "pem",
+    DER = "der",
+    P12 = "p12",
+    CER = "cer"
+}
+/**
+ * Timestamp response status
+ */
+export declare enum TimestampStatus {
+    SUCCESS = "success",
+    FAILED = "failed",
+    TIMEOUT = "timeout",
+    INVALID_RESPONSE = "invalid_response"
+}
+export interface DigitalSignature {
+    signatureName: string;
+    signingDate?: Date;
+    reason?: string;
+    location?: string;
+    signer?: string;
+    isCertified: boolean;
+    algorithm?: SignatureAlgorithm;
+}
+export interface SignatureField {
+    fieldName: string;
+    pageIndex: number;
+    isSigned: boolean;
+    signature?: DigitalSignature;
+}
+export interface SignatureValidationResult {
+    isValid: boolean;
+    signatures: DigitalSignature[];
+    issues: string[];
+}
+export interface SignatureConfig {
+    algorithm?: SignatureAlgorithm;
+    digestAlgorithm?: DigestAlgorithm;
+    reason?: string;
+    location?: string;
+}
+export interface Certificate {
+    subject: string;
+    issuer: string;
+    serial: string;
+    notBefore: number;
+    notAfter: number;
+    isValid: boolean;
+}
+export interface Signature {
+    signerName: string;
+    signingTime: number;
+    reason?: string;
+    location?: string;
+    certificate: Certificate;
+    isValid: boolean;
+}
+export interface CertificateInfo {
+    readonly subject: string;
+    readonly issuer: string;
+    readonly serialNumber: string;
+    readonly validFrom: Date;
+    readonly validTo: Date;
+    readonly isValid: boolean;
+    readonly isSelfSigned: boolean;
+    readonly keyUsage?: readonly string[];
+    readonly extendedKeyUsage?: readonly string[];
+    readonly subjectAltNames?: readonly string[];
+    readonly thumbprint?: string;
+    readonly publicKeyAlgorithm?: string;
+    readonly signatureAlgorithm?: string;
+}
+export interface CertificateChain {
+    readonly certificates: readonly CertificateInfo[];
+    readonly isComplete: boolean;
+    readonly validationStatus: 'valid' | 'invalid' | 'unknown';
+    readonly validationMessages?: readonly string[];
+}
+export interface LoadedCertificate {
+    readonly certificateId: string;
+    readonly info: CertificateInfo;
+    readonly hasPrivateKey: boolean;
+    readonly chain?: CertificateChain;
+}
+export interface SignatureAppearance {
+    readonly showName?: boolean;
+    readonly showDate?: boolean;
+    readonly showReason?: boolean;
+    readonly showLocation?: boolean;
+    readonly showLabels?: boolean;
+    readonly imageData?: Buffer;
+    readonly imagePath?: string;
+    readonly backgroundColor?: string;
+    readonly textColor?: string;
+    readonly borderColor?: string;
+    readonly borderWidth?: number;
+    readonly font?: string;
+    readonly fontSize?: number;
+    readonly customText?: string;
+}
+export interface SignatureFieldConfig {
+    readonly fieldName: string;
+    readonly pageIndex: number;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly appearance?: SignatureAppearance;
+    readonly tooltip?: string;
+    readonly isRequired?: boolean;
+    readonly isReadOnly?: boolean;
+}
+export interface SigningOptions {
+    readonly reason?: string;
+    readonly location?: string;
+    readonly contactInfo?: string;
+    readonly signatureType?: SignatureType;
+    readonly certificationPermission?: CertificationPermission;
+    readonly algorithm?: SignatureAlgorithm;
+    readonly digestAlgorithm?: DigestAlgorithm;
+    readonly appearance?: SignatureAppearance;
+    readonly embedTimestamp?: boolean;
+    readonly timestampServerUrl?: string;
+    readonly enableLtv?: boolean;
+    readonly ocspResponderUrl?: string;
+    readonly crlDistributionPoints?: readonly string[];
+}
+export interface TimestampConfig {
+    readonly serverUrl: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly hashAlgorithm?: DigestAlgorithm;
+    readonly timeout?: number;
+    readonly policy?: string;
+    readonly nonce?: boolean;
+    readonly certReq?: boolean;
+}
+export interface SigningResult {
+    readonly success: boolean;
+    readonly signatureId?: string;
+    readonly signingTime?: Date;
+    readonly timestampTime?: Date;
+    readonly error?: string;
+    readonly warnings?: readonly string[];
+}
+export interface TimestampResult {
+    readonly status: TimestampStatus;
+    readonly timestamp?: Date;
+    readonly serialNumber?: string;
+    readonly tsaName?: string;
+    readonly error?: string;
+}
+/**
+ * Opaque handle to signing credentials loaded via FFI.
+ * Wraps a native pointer returned by pdf_credentials_from_pkcs12 or pdf_credentials_from_pem.
+ */
+export interface SigningCredentials {
+    /** Internal native handle - do not access directly */
+    readonly _handle: any;
+    /** Source type: 'pkcs12' or 'pem' */
+    readonly sourceType: 'pkcs12' | 'pem';
+}
+/**
+ * Options for FFI-based document signing operations.
+ */
+export interface SignOptions {
+    /** Reason for signing the document */
+    readonly reason?: string;
+    /** Location where the document was signed */
+    readonly location?: string;
+    /** Contact information for the signer */
+    readonly contact?: string;
+    /** Digest algorithm (0=SHA1, 1=SHA256, 2=SHA384, 3=SHA512). Defaults to SHA256 (1). */
+    readonly algorithm?: number;
+    /** Signature subfilter (0=PKCS7_DETACHED, 1=PKCS7_SHA1, 2=CADES_DETACHED). Defaults to PKCS7_DETACHED (0). */
+    readonly subfilter?: number;
+}
+/**
+ * FFI digest algorithm constants for use with SignOptions.algorithm
+ */
+export declare enum FfiDigestAlgorithm {
+    SHA1 = 0,
+    SHA256 = 1,
+    SHA384 = 2,
+    SHA512 = 3
+}
+/**
+ * FFI signature subfilter constants for use with SignOptions.subfilter
+ */
+export declare enum FfiSignatureSubFilter {
+    PKCS7_DETACHED = 0,
+    PKCS7_SHA1 = 1,
+    CADES_DETACHED = 2
+}
+/**
+ * Canonical Signature Manager - all signature operations in one class.
+ *
+ * Provides:
+ * - Verification (from root SignatureManager)
+ * - Certificate loading (from SignatureCreationManager)
+ * - Document signing with timestamps and LTV (from SignatureCreationManager)
+ * - Detailed signature info (from SignaturesManager)
+ */
+export declare class SignatureManager extends EventEmitter {
+    private document;
+    private resultCache;
+    private maxCacheSize;
+    private native;
+    private readonly loadedCertificates;
+    private readonly createdFields;
+    constructor(document: any);
+    getSignatures(): Promise<DigitalSignature[]>;
+    getSignatureFields(): Promise<SignatureField[]>;
+    verifySignatures(): Promise<SignatureValidationResult>;
+    verifySignature(signatureName: string): Promise<SignatureValidationResult>;
+    isCertified(): Promise<boolean>;
+    getSignatureCount(): Promise<number>;
+    isSigned(): Promise<boolean>;
+    loadCertificateFromFile(filePath: string, password?: string, format?: CertificateFormat): Promise<LoadedCertificate | null>;
+    loadCertificateFromBytes(certData: Buffer, password?: string, format?: CertificateFormat): Promise<LoadedCertificate | null>;
+    loadCertificateFromPem(certificatePem: string, privateKeyPem?: string, privateKeyPassword?: string): Promise<LoadedCertificate | null>;
+    getCertificateInfo(certificateId: string): Promise<CertificateInfo | null>;
+    getCertificateChain(certificateId: string): Promise<CertificateChain | null>;
+    validateCertificate(certificateId: string): Promise<{
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    }>;
+    getLoadedCertificates(): readonly LoadedCertificate[];
+    unloadCertificate(certificateId: string): boolean;
+    addSignatureField(config: SignatureFieldConfig): Promise<boolean>;
+    removeSignatureField(fieldName: string): Promise<boolean>;
+    getSignatureFieldNames(): Promise<string[]>;
+    hasSignatureField(fieldName: string): Promise<boolean>;
+    updateSignatureFieldAppearance(fieldName: string, appearance: SignatureAppearance): Promise<boolean>;
+    signDocument(fieldName: string, certificate: LoadedCertificate | string, options?: SigningOptions): Promise<SigningResult>;
+    certifyDocument(fieldName: string, certificate: LoadedCertificate | string, permission: CertificationPermission, options?: Omit<SigningOptions, 'signatureType' | 'certificationPermission'>): Promise<SigningResult>;
+    signInvisibly(certificate: LoadedCertificate | string, options?: Omit<SigningOptions, 'appearance'>): Promise<SigningResult>;
+    counterSign(certificate: LoadedCertificate | string, options?: SigningOptions): Promise<SigningResult>;
+    signMultipleFields(signings: Array<{
+        fieldName: string;
+        certificate: LoadedCertificate | string;
+        options?: SigningOptions;
+    }>): Promise<SigningResult[]>;
+    prepareForExternalSigning(fieldName: string, options?: {
+        estimatedSize?: number;
+        digestAlgorithm?: DigestAlgorithm;
+    }): Promise<{
+        hash: Buffer;
+        byteRange: [number, number, number, number];
+    } | null>;
+    embedTimestamp(fieldName: string, config: TimestampConfig): Promise<TimestampResult>;
+    addDocumentTimestamp(config: TimestampConfig): Promise<TimestampResult>;
+    validateTimestamp(fieldName: string): Promise<{
+        valid: boolean;
+        timestamp?: Date;
+        errors: string[];
+    }>;
+    getTimestampInfo(fieldName: string): Promise<{
+        timestamp?: Date;
+        tsaName?: string;
+        serialNumber?: string;
+        policy?: string;
+    } | null>;
+    enableLtvForSignature(fieldName: string, options?: {
+        ocspResponderUrl?: string;
+        crlDistributionPoints?: readonly string[];
+    }): Promise<boolean>;
+    enableLtvForAllSignatures(options?: {
+        ocspResponderUrl?: string;
+        crlDistributionPoints?: readonly string[];
+    }): Promise<number>;
+    addValidationInfo(fieldName: string, info: {
+        ocspResponse?: Buffer;
+        crl?: Buffer;
+        certificates?: readonly Buffer[];
+    }): Promise<boolean>;
+    hasLtvEnabled(fieldName: string): Promise<boolean>;
+    getSignerName(index: number): Promise<string>;
+    getSigningTime(index: number): Promise<number>;
+    getSigningReason(index: number): Promise<string | null>;
+    getSigningLocation(index: number): Promise<string | null>;
+    getCertificateSubject(index: number): Promise<string>;
+    getCertificateIssuer(index: number): Promise<string>;
+    getCertificateSerial(index: number): Promise<string>;
+    getCertificateValidity(index: number): Promise<[number, number]>;
+    getSignatureDetails(index: number): Promise<Signature | null>;
+    isCertificateValidByIndex(index: number): Promise<boolean>;
+    /**
+     * Load signing credentials from a PKCS#12 (.p12/.pfx) file.
+     *
+     * Calls the native `pdf_credentials_from_pkcs12` FFI function to load
+     * a certificate and private key from a PKCS#12 container.
+     *
+     * @param filePath - Path to the .p12 or .pfx file
+     * @param password - Password to decrypt the PKCS#12 file
+     * @returns SigningCredentials handle for use with signing methods
+     * @throws SignatureException if the file cannot be loaded or the password is incorrect
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPkcs12('/path/to/cert.p12', 'password');
+     * const signed = await sigManager.signWithPkcs12(pdfData, '/path/to/cert.p12', 'password');
+     * ```
+     */
+    loadCredentialsPkcs12(filePath: string, password: string): Promise<SigningCredentials>;
+    /**
+     * Load signing credentials from PEM certificate and key files.
+     *
+     * Calls the native `pdf_credentials_from_pem` FFI function to load
+     * credentials from separate PEM-encoded certificate and private key files.
+     *
+     * @param certFile - Path to the PEM certificate file
+     * @param keyFile - Path to the PEM private key file
+     * @param keyPassword - Optional password for an encrypted private key
+     * @returns SigningCredentials handle for use with signing methods
+     * @throws SignatureException if the files cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPem('/path/to/cert.pem', '/path/to/key.pem');
+     * ```
+     */
+    loadCredentialsPem(certFile: string, keyFile: string, keyPassword?: string): Promise<SigningCredentials>;
+    /**
+     * Free signing credentials when they are no longer needed.
+     *
+     * Calls the native `pdf_credentials_free` FFI function to release
+     * memory associated with the credentials handle.
+     *
+     * @param credentials - The credentials handle to free
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPkcs12(path, password);
+     * // ... use credentials for signing ...
+     * sigManager.freeCredentials(credentials);
+     * ```
+     */
+    freeCredentials(credentials: SigningCredentials): void;
+    /**
+     * Sign a PDF document in memory using PKCS#12 credentials.
+     *
+     * Loads credentials from a PKCS#12 file, signs the PDF data, and returns
+     * the signed PDF bytes. Credentials are automatically freed after signing.
+     *
+     * @param pdfData - Buffer containing the PDF document bytes
+     * @param filePath - Path to the .p12 or .pfx certificate file
+     * @param password - Password for the PKCS#12 file
+     * @param options - Optional signing parameters (reason, location, contact, algorithm, subfilter)
+     * @returns Buffer containing the signed PDF document
+     * @throws SignatureException if credential loading or signing fails
+     *
+     * @example
+     * ```typescript
+     * const pdfData = await fs.readFile('document.pdf');
+     * const signed = await sigManager.signWithPkcs12(pdfData, 'cert.p12', 'password', {
+     *   reason: 'Approval',
+     *   location: 'New York',
+     *   contact: 'signer@example.com',
+     * });
+     * await fs.writeFile('signed.pdf', signed);
+     * ```
+     */
+    signWithPkcs12(pdfData: Buffer, filePath: string, password: string, options?: SignOptions): Promise<Buffer>;
+    /**
+     * Sign a PDF document in memory using PEM credentials.
+     *
+     * Loads credentials from PEM files, signs the PDF data, and returns
+     * the signed PDF bytes. Credentials are automatically freed after signing.
+     *
+     * @param pdfData - Buffer containing the PDF document bytes
+     * @param certFile - Path to the PEM certificate file
+     * @param keyFile - Path to the PEM private key file
+     * @param options - Optional signing parameters (reason, location, contact, algorithm, subfilter)
+     * @returns Buffer containing the signed PDF document
+     * @throws SignatureException if credential loading or signing fails
+     *
+     * @example
+     * ```typescript
+     * const pdfData = await fs.readFile('document.pdf');
+     * const signed = await sigManager.signWithPem(pdfData, 'cert.pem', 'key.pem', {
+     *   reason: 'Review complete',
+     *   location: 'London',
+     * });
+     * await fs.writeFile('signed.pdf', signed);
+     * ```
+     */
+    signWithPem(pdfData: Buffer, certFile: string, keyFile: string, options?: SignOptions): Promise<Buffer>;
+    /**
+     * Sign a PDF document in memory using pre-loaded credentials.
+     *
+     * Calls the native `pdf_document_sign` FFI function to apply a digital
+     * signature to the PDF data using the provided credentials handle.
+     *
+     * @param pdfData - Buffer containing the PDF document bytes
+     * @param credentials - Pre-loaded signing credentials handle
+     * @param options - Optional signing parameters
+     * @returns Buffer containing the signed PDF document
+     * @throws SignatureException if signing fails
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPkcs12(path, password);
+     * const signed = await sigManager.signWithCredentials(pdfData, credentials, {
+     *   reason: 'Approved',
+     *   algorithm: FfiDigestAlgorithm.SHA256,
+     *   subfilter: FfiSignatureSubFilter.PKCS7_DETACHED,
+     * });
+     * sigManager.freeCredentials(credentials);
+     * ```
+     */
+    signWithCredentials(pdfData: Buffer, credentials: SigningCredentials, options?: SignOptions): Promise<Buffer>;
+    /**
+     * Sign a PDF file on disk and write the signed output to another file.
+     *
+     * Calls the native `pdf_document_sign_file` FFI function, which reads
+     * the input file, applies a digital signature, and writes the result
+     * to the output path.
+     *
+     * @param inputPath - Path to the input PDF file
+     * @param outputPath - Path to write the signed PDF file
+     * @param credentials - Pre-loaded signing credentials handle
+     * @param options - Optional signing parameters
+     * @throws SignatureException if file signing fails
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPkcs12('cert.p12', 'pass');
+     * await sigManager.signFile('input.pdf', 'signed.pdf', credentials, {
+     *   reason: 'Final approval',
+     *   location: 'Berlin',
+     * });
+     * sigManager.freeCredentials(credentials);
+     * ```
+     */
+    signFile(inputPath: string, outputPath: string, credentials: SigningCredentials, options?: SignOptions): Promise<void>;
+    /**
+     * Embed Long-Term Validation (LTV) data into a signed PDF.
+     *
+     * Calls the native `pdf_embed_ltv_data` FFI function to add OCSP responses
+     * and/or CRL data to the document's DSS (Document Security Store), enabling
+     * long-term signature validation even after certificates expire.
+     *
+     * @param pdfData - Buffer containing the signed PDF document bytes
+     * @param ocspData - Optional OCSP response data to embed
+     * @param crlData - Optional CRL data to embed
+     * @returns Buffer containing the PDF with embedded LTV data
+     * @throws SignatureException if LTV embedding fails
+     *
+     * @example
+     * ```typescript
+     * const signedPdf = await sigManager.signWithPkcs12(pdfData, 'cert.p12', 'pass');
+     * const ocspResponse = await fetch('http://ocsp.example.com/...').then(r => r.buffer());
+     * const ltvPdf = await sigManager.embedLtv(signedPdf, ocspResponse);
+     * await fs.writeFile('signed-ltv.pdf', ltvPdf);
+     * ```
+     */
+    embedLtv(pdfData: Buffer, ocspData?: Buffer, crlData?: Buffer): Promise<Buffer>;
+    /**
+     * Save signed PDF bytes to a file.
+     *
+     * Calls the native `pdf_document_save_signed` FFI function to write
+     * signed PDF data to disk.
+     *
+     * @param pdfData - Buffer containing the signed PDF bytes
+     * @param outputPath - Path to write the signed PDF file
+     * @throws SignatureException or IoException if saving fails
+     *
+     * @example
+     * ```typescript
+     * const signed = await sigManager.signWithPkcs12(pdfData, 'cert.p12', 'pass');
+     * await sigManager.saveSigned(signed, '/output/signed.pdf');
+     * ```
+     */
+    saveSigned(pdfData: Buffer, outputPath: string): Promise<void>;
+    /**
+     * Load signing credentials from raw DER-encoded certificate and key bytes.
+     *
+     * Calls the native `pdf_credentials_from_der` FFI function to create
+     * credentials from in-memory DER-encoded certificate data and an optional
+     * private key.
+     *
+     * @param certData - Buffer containing DER-encoded certificate bytes
+     * @param keyData - Optional Buffer containing DER-encoded private key bytes
+     * @returns SigningCredentials handle for use with signing methods
+     * @throws SignatureException if credential loading fails
+     *
+     * @example
+     * ```typescript
+     * const certDer = await fs.readFile('cert.der');
+     * const keyDer = await fs.readFile('key.der');
+     * const credentials = await sigManager.loadCredentialsFromDer(certDer, keyDer);
+     * const signed = await sigManager.signWithCredentials(pdfData, credentials);
+     * sigManager.freeCredentials(credentials);
+     * ```
+     */
+    loadCredentialsFromDer(certData: Buffer, keyData?: Buffer): Promise<SigningCredentials>;
+    /**
+     * Add a certificate chain entry to existing signing credentials.
+     *
+     * Calls the native `pdf_credentials_add_chain_cert` FFI function to append
+     * an intermediate or root CA certificate to the credential's certificate chain.
+     * This is used to build a complete certification chain for signature validation.
+     *
+     * @param credentials - The signing credentials handle to modify
+     * @param certData - Buffer containing DER-encoded certificate bytes
+     * @throws SignatureException if the chain certificate cannot be added
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsFromDer(certDer, keyDer);
+     * const intermediateCa = await fs.readFile('intermediate-ca.der');
+     * await sigManager.addChainCert(credentials, intermediateCa);
+     * ```
+     */
+    addChainCert(credentials: SigningCredentials, certData: Buffer): Promise<void>;
+    /**
+     * Get the certificate handle from signing credentials.
+     *
+     * Calls the native `pdf_credentials_get_certificate` FFI function to extract
+     * the certificate handle from a credentials object. The returned handle can be
+     * used with certificate inspection methods like getCertificateCn, getCertificateIssuer,
+     * and getCertificateSize.
+     *
+     * @param credentials - The signing credentials handle
+     * @returns An opaque certificate handle for use with certificate inspection methods
+     * @throws SignatureException if the certificate cannot be retrieved
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPkcs12('cert.p12', 'pass');
+     * const certHandle = await sigManager.getCertificate(credentials);
+     * const cn = await sigManager.getCertificateCn(certHandle);
+     * console.log(`Certificate CN: ${cn}`);
+     * sigManager.freeCredentials(credentials);
+     * ```
+     */
+    getCertificate(credentials: SigningCredentials): Promise<any>;
+    /**
+     * Load a certificate from raw DER bytes for inspection.
+     *
+     * Calls the native `pdf_certificate_load_from_bytes` FFI function to create
+     * a certificate handle from DER-encoded bytes. This is useful for inspecting
+     * certificate properties without creating full signing credentials.
+     *
+     * @param certData - Buffer containing DER-encoded certificate bytes
+     * @returns An opaque certificate handle for use with certificate inspection methods
+     * @throws SignatureException if the certificate cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * const certDer = await fs.readFile('cert.der');
+     * const certHandle = await sigManager.loadCertificateFromDerBytes(certDer);
+     * const cn = await sigManager.getCertificateCn(certHandle);
+     * const issuer = await sigManager.getCertificateIssuerFromHandle(certHandle);
+     * const size = await sigManager.getCertificateSize(certHandle);
+     * ```
+     */
+    loadCertificateFromDerBytes(certData: Buffer): Promise<any>;
+    /**
+     * Get the common name (CN) from a certificate handle.
+     *
+     * Calls the native `pdf_certificate_get_cn` FFI function to extract
+     * the subject common name from a certificate.
+     *
+     * @param certHandle - An opaque certificate handle obtained from getCertificate or loadCertificateFromDerBytes
+     * @returns The certificate common name string
+     * @throws SignatureException if the CN cannot be retrieved
+     *
+     * @example
+     * ```typescript
+     * const credentials = await sigManager.loadCredentialsPkcs12('cert.p12', 'pass');
+     * const certHandle = await sigManager.getCertificate(credentials);
+     * const cn = await sigManager.getCertificateCn(certHandle);
+     * console.log(`Signer: ${cn}`);
+     * ```
+     */
+    getCertificateCn(certHandle: any): Promise<string>;
+    /**
+     * Get the issuer name from a certificate handle.
+     *
+     * Calls the native `pdf_certificate_get_issuer` FFI function to extract
+     * the issuer distinguished name from a certificate.
+     *
+     * @param certHandle - An opaque certificate handle obtained from getCertificate or loadCertificateFromDerBytes
+     * @returns The certificate issuer name string
+     * @throws SignatureException if the issuer cannot be retrieved
+     *
+     * @example
+     * ```typescript
+     * const certHandle = await sigManager.loadCertificateFromDerBytes(certDer);
+     * const issuer = await sigManager.getCertificateIssuerFromHandle(certHandle);
+     * console.log(`Issued by: ${issuer}`);
+     * ```
+     */
+    getCertificateIssuerFromHandle(certHandle: any): Promise<string>;
+    /**
+     * Get the size in bytes of a certificate.
+     *
+     * Calls the native `pdf_certificate_get_size` FFI function to get the
+     * size of the DER-encoded certificate data.
+     *
+     * @param certHandle - An opaque certificate handle obtained from getCertificate or loadCertificateFromDerBytes
+     * @returns The certificate size in bytes
+     * @throws SignatureException if the size cannot be retrieved
+     *
+     * @example
+     * ```typescript
+     * const certHandle = await sigManager.loadCertificateFromDerBytes(certDer);
+     * const size = await sigManager.getCertificateSize(certHandle);
+     * console.log(`Certificate size: ${size} bytes`);
+     * ```
+     */
+    getCertificateSize(certHandle: any): Promise<number>;
+    /**
+     * Free a certificate handle when it is no longer needed.
+     *
+     * Calls the native `pdf_certificate_free` FFI function to release
+     * memory associated with the certificate handle.
+     *
+     * @param certHandle - The certificate handle to free
+     *
+     * @example
+     * ```typescript
+     * const certHandle = await sigManager.loadCertificateFromDerBytes(certDer);
+     * const cn = await sigManager.getCertificateCn(certHandle);
+     * sigManager.freeCertificate(certHandle);
+     * ```
+     */
+    freeCertificate(certHandle: any): void;
+    /**
+     * Add an RFC 3161 timestamp to an existing signature via a Time Stamp Authority.
+     *
+     * Calls the native `pdf_add_timestamp` FFI function.
+     *
+     * @param pdfData - Buffer containing the signed PDF document bytes
+     * @param signatureIndex - Index of the signature to timestamp (0-based)
+     * @param tsaUrl - URL of the Time Stamp Authority server
+     * @returns Buffer containing the timestamped PDF bytes
+     * @throws SignatureException if timestamping fails
+     */
+    addTimestamp(pdfData: Buffer, signatureIndex: number, tsaUrl: string): Promise<Buffer>;
+    /**
+     * Sign PDF data with a visible signature appearance on a specific page.
+     *
+     * @param pdfData - Buffer containing PDF bytes to sign
+     * @param credentials - Pre-loaded signing credentials
+     * @param pageNum - Page number for appearance (0-based)
+     * @param x - X coordinate of appearance box
+     * @param y - Y coordinate of appearance box
+     * @param width - Width of appearance box
+     * @param height - Height of appearance box
+     * @param options - Optional signing parameters
+     * @returns Buffer containing signed PDF bytes
+     * @throws SignatureException if signing fails
+     */
+    signWithAppearance(pdfData: Buffer, credentials: SigningCredentials, pageNum: number, x: number, y: number, width: number, height: number, options?: SignOptions): Promise<Buffer>;
+    clearCache(): void;
+    getCacheStats(): Record<string, any>;
+    destroy(): void;
+    /**
+     * Sign a PDF from raw bytes using PEM credentials.
+     *
+     * Calls the native `signPdfBytes` FFI function (two-pass ByteRange writer).
+     * Credentials are loaded and freed within this call.
+     *
+     * @param pdfData - Buffer containing the PDF document bytes
+     * @param certPem - PEM-encoded certificate string
+     * @param keyPem  - PEM-encoded private key string
+     * @param reason  - Optional signature reason
+     * @param location - Optional signature location
+     * @returns Buffer containing the signed PDF
+     */
+    signPdfData(pdfData: Buffer, certPem: string, keyPem: string, reason?: string, location?: string): Promise<Buffer>;
+    private setCached;
+    private clearCachePattern;
+}
+export default SignatureManager;