edockit 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] - 2025-12-30
+
+### Added
+
+- **CORS Proxy Support** - New `proxyUrl` option in `revocationOptions` for browser environments
+  - Routes OCSP, CRL, and CA issuer certificate requests through a CORS proxy
+  - Enables revocation checking in browsers where direct requests are blocked by CORS
+
+## [0.2.0] - 2025-12-29
+
+### Added
+
+- **Certificate Revocation Checking** - OCSP-first verification with CRL fallback
+  - Soft-fail mode: network errors return `status: 'unknown'`, signature remains valid
+  - Issuer certificate retrieval from XAdES chain or AIA extension
+  - Optional via `checkRevocation: false` for offline-only verification
+- **RFC 3161 Timestamp Verification**
+  - Parse and verify RFC 3161 timestamps (SignatureTimeStamp)
+  - Check TSA certificate validity and revocation (OCSP/CRL)
+  - Use trusted TSA time for signer certificate validation
+  - `revocationOptions` pass-through to `verifySignature()`
+
+### Changed
+
+- Refactored encoding utilities (consolidated base64/hex/ArrayBuffer helpers)
+
+### Fixed
+
+- Browser compatibility import fixes (direct paths vs barrel imports)
+- Fixed vulnerable dev dependencies
+
+## [0.1.2] - 2025-12-29
+
+### Added
+
+- Initial public release
+- Parse ASiC-E containers (including Latvian eDoc files)
+- Extract and verify XAdES signatures
+- Certificate validity checking
+- File checksum verification (SHA-256/384/512)
+- Browser and Node.js support
+
+[0.2.1]: https://github.com/edgarsj/edockit/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/edgarsj/edockit/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/edgarsj/edockit/releases/tag/v0.1.2

package/README.md

@@ -4,8 +4,6 @@ A JavaScript/TypeScript library for viewing and verifying EU standard ASiC-E con
 
 > **Note: Work in Progress** - This library is under active development and requires more real-world testing with various ASiC-E implementations from different European countries. If you have sample files or encounter issues, please contribute!
 
-> **Important:** Certificate validation currently lacks OCSP checks (Online Certificate Status Protocol). Adding OCSP support is on the roadmap and will be implemented in a future release.
-
 ## About
 
 This library supports standard European ASiC-E (.asice, .sce) containers as defined by the ETSI standards. Latvian eDoc (.edoc) files are effectively ASiC-E containers with a different file extension, so they are also supported. While the core functionality exists, extensive testing with real-world documents from various EU countries is still needed to ensure complete compatibility across different implementations.
@@ -41,13 +39,36 @@ const container = parseEdoc(fileBuffer);
 // List files in container
 console.log(Array.from(container.files.keys()));
 
-// Verify a signature
-const result = await verifySignature(container.signatures[0], container.files);
+// Verify a signature (with revocation and timestamp checking)
+const result = await verifySignature(container.signatures[0], container.files, {
+  checkRevocation: true,   // OCSP/CRL checking (default: true)
+  revocationOptions: {     // Optional: configure revocation check behavior
+    ocspTimeout: 5000,     // OCSP request timeout in ms (default: 5000)
+    crlTimeout: 10000,     // CRL fetch timeout in ms (default: 10000)
+    proxyUrl: 'https://cors-proxy.example.com/?url=',  // CORS proxy for browser (optional)
+  },
+  verifyTimestamps: true,  // RFC 3161 timestamp verification (default: true)
+  verifyTime: new Date()   // Verify certificate at specific time (default: timestamp time if present, otherwise now)
+});
 // result = {
 //   isValid: boolean,                // Overall validity
-//   certificate: {isValid: boolean}, // Certificate validation result
+//   certificate: {
+//     isValid: boolean,              // Certificate validity (time-based)
+//     revocation: {                  // Revocation check result
+//       status: 'good' | 'revoked' | 'unknown' | 'error',
+//       method: 'ocsp' | 'crl' | 'none',
+//       checkedAt: Date,
+//       isValid: boolean
+//     }
+//   },
 //   checksums: {isValid: boolean},   // File checksums validation result
 //   signature: {isValid: boolean},   // XML signature validation result
+//   timestamp: {                     // Timestamp verification (if present)
+//     isValid: boolean,
+//     info: { genTime: Date, policy: string, ... },
+//     coversSignature: boolean,
+//     tsaRevocation: { status, method, ... }
+//   },
 //   errors: string[]                 // Any validation errors (if present)
 // }
 console.log(`Signature valid: ${result.isValid}`);
@@ -56,18 +77,29 @@ console.log(`Signature valid: ${result.isValid}`);
 ### Node.js Example
 
 ```typescript
-import { readFileSync } from 'fs';
-import { parseEdoc, verifySignature } from 'edockit';
+import { readFileSync } from "fs";
+import { parseEdoc, verifySignature } from "edockit";
 
 // Read file
-const fileBuffer = readFileSync('document.asice');
+const fileBuffer = readFileSync("document.asice");
 const container = parseEdoc(fileBuffer);
 
-// Check signatures
+// Check signatures with revocation and timestamp checking
 for (const signature of container.signatures) {
-  const result = await verifySignature(signature, container.files);
+  const result = await verifySignature(signature, container.files, {
+    checkRevocation: true,
+    verifyTimestamps: true
+  });
   console.log(`Signature valid: ${result.isValid}`);
 
+  if (result.timestamp?.info) {
+    console.log(`Signed at (TSA): ${result.timestamp.info.genTime}`);
+  }
+
+  if (result.certificate.revocation) {
+    console.log(`Revocation status: ${result.certificate.revocation.status}`);
+  }
+
   if (!result.isValid && result.errors) {
     console.log(`Errors: ${result.errors.join(', ')}`);
   }
@@ -88,23 +120,72 @@ async function verifyDocument(url) {
   console.log("Documents:", container.documentFileList);
 
   for (const signature of container.signatures) {
-    const result = await verifySignature(signature, container.files);
+    const result = await verifySignature(signature, container.files, {
+      checkRevocation: true,
+      revocationOptions: {
+        // Use a CORS proxy for OCSP/CRL requests in browser environments
+        proxyUrl: 'https://your-cors-proxy.example.com/?url=',
+      },
+    });
+
     console.log(`Valid: ${result.isValid}`);
+
+    if (result.timestamp?.info) {
+      console.log(`Timestamp: ${result.timestamp.info.genTime}`);
+    }
+    if (result.certificate.revocation) {
+      console.log(`Revocation: ${result.certificate.revocation.status}`);
+    }
   }
 }
 ```
 
+> **Note:** OCSP and CRL endpoints typically don't support CORS, so browser environments need a proxy to perform revocation checks. The `proxyUrl` option routes all revocation requests through the specified proxy, which should accept the original URL as a query parameter.
+
+### Timestamp Utilities
+
+For advanced timestamp handling, you can use the timestamp utilities directly:
+
+```typescript
+import { parseTimestamp, verifyTimestamp, getTimestampTime } from 'edockit';
+
+// Get timestamp time from a signature (quick utility)
+const timestampTime = getTimestampTime(signature.signatureTimestamp);
+console.log(`Signed at: ${timestampTime}`);
+
+// Parse timestamp for detailed info
+const info = parseTimestamp(signature.signatureTimestamp);
+// info = {
+//   genTime: Date,           // When TSA signed
+//   policy: string,          // TSA policy OID
+//   hashAlgorithm: string,   // e.g., 'SHA-256'
+//   messageImprint: string,  // Hash of timestamped data
+//   tsaName?: string,        // TSA name
+//   tsaCertificate?: string, // TSA cert in PEM format
+// }
+
+// Verify timestamp with options
+const result = await verifyTimestamp(signature.signatureTimestamp, {
+  signatureValue: signature.signatureValue,  // Verify timestamp covers this signature
+  verifyTsaCertificate: true,                // Check TSA cert validity
+  checkTsaRevocation: true,                  // Check TSA cert revocation
+});
+```
+
 ## Features
 
 - Support for EU standard ASiC-E containers and Latvian eDoc files/containers (same format, different extension)
 - List files contained in ASiC-E/eDoc container
 - Extract and display signature information
 - Verify XML signatures against file checksums
-- Validate certificate validity (Note: OCSP validation planned for future releases)
+- Validate certificate validity (time-based)
+- RFC 3161 timestamp verification (when present, certificate is validated at the trusted TSA timestamp time)
+- OCSP/CRL revocation checking for both signer and TSA certificates (soft-fail behavior - network errors don't invalidate signatures)
 
 ## Testing Status
 
 The library has been tested with a limited set of real Latvian eDoc files (which are ASiC-E containers with a .edoc extension). More testing is needed with:
+
 - ASiC-E containers from different EU countries
 - Files created with different software implementations
 - Various signature algorithms and certificate types

package/dist/core/parser/types.d.ts

@@ -10,6 +10,7 @@ export interface SignatureInfo {
     signingTime: Date;
     certificate: string;
     certificatePEM: string;
+    certificateChain?: string[];
     publicKey?: {
         algorithm: string;
         namedCurve?: string;
@@ -36,4 +37,6 @@ export interface SignatureInfo {
     signedInfoXml?: string;
     rawXml?: string;
     canonicalizationMethod?: string;
+    /** RFC 3161 timestamp token (base64 encoded) from xades:EncapsulatedTimeStamp */
+    signatureTimestamp?: string;
 }

package/dist/core/revocation/check.d.ts

@@ -0,0 +1,22 @@
+import { X509Certificate } from "@peculiar/x509";
+import { RevocationResult, RevocationCheckOptions } from "./types";
+/**
+ * Check certificate revocation status using OCSP (primary) and CRL (fallback)
+ *
+ * Strategy:
+ * 1. Try OCSP first (faster, real-time)
+ * 2. If OCSP fails or returns unknown, try CRL as fallback
+ * 3. If both fail, return 'unknown' status (soft fail)
+ *
+ * @param cert Certificate to check (X509Certificate or PEM string)
+ * @param options Revocation check options
+ * @returns RevocationResult with status and details
+ */
+export declare function checkCertificateRevocation(cert: X509Certificate | string, options?: RevocationCheckOptions): Promise<RevocationResult>;
+/**
+ * Check multiple certificates' revocation status
+ * @param certs Array of certificates (X509Certificate or PEM strings)
+ * @param options Revocation check options
+ * @returns Array of RevocationResults in same order as input
+ */
+export declare function checkCertificatesRevocation(certs: (X509Certificate | string)[], options?: RevocationCheckOptions): Promise<RevocationResult[]>;

package/dist/core/revocation/crl.d.ts

@@ -0,0 +1,35 @@
+import { X509Certificate, X509Crl } from "@peculiar/x509";
+import { RevocationResult } from "./types";
+/**
+ * Extract CRL distribution point URLs from certificate
+ * @param cert X509Certificate to extract CRL URLs from
+ * @returns Array of CRL distribution URLs
+ */
+export declare function extractCRLUrls(cert: X509Certificate): string[];
+/**
+ * Check if a certificate serial number is in the CRL
+ * @param crl X509Crl to check
+ * @param serialNumber Certificate serial number (hex string)
+ * @returns Object with isRevoked status and optional revocation date
+ */
+export declare function isSerialInCRL(crl: X509Crl, serialNumber: string): {
+    isRevoked: boolean;
+    revokedAt?: Date;
+    reason?: number;
+};
+/**
+ * Parse CRL from DER or PEM data
+ * @param data CRL data (DER or PEM)
+ * @returns X509Crl or null if parsing fails
+ */
+export declare function parseCRL(data: ArrayBuffer): X509Crl | null;
+/**
+ * Check certificate revocation via CRL
+ * @param cert Certificate to check
+ * @param options CRL check options
+ * @returns Revocation result
+ */
+export declare function checkCRL(cert: X509Certificate, options?: {
+    timeout?: number;
+    proxyUrl?: string;
+}): Promise<RevocationResult>;

package/dist/core/revocation/fetch.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Cross-platform HTTP fetch for OCSP and CRL requests
+ * Works in both browser and Node.js environments
+ */
+export interface FetchOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** HTTP method (default: GET) */
+    method?: "GET" | "POST";
+    /** Request body for POST requests */
+    body?: ArrayBuffer | Uint8Array;
+    /** Content-Type header */
+    contentType?: string;
+    /** Accept header */
+    accept?: string;
+    /**
+     * CORS proxy URL for browser environments.
+     * When set, the original URL will be URL-encoded and appended to this proxy URL.
+     * Example: "https://cors-proxy.example.com/?url="
+     */
+    proxyUrl?: string;
+}
+export interface FetchResult {
+    ok: boolean;
+    status: number;
+    data?: ArrayBuffer;
+    error?: string;
+}
+/**
+ * Fetch binary data from a URL with timeout support
+ * @param url URL to fetch
+ * @param options Fetch options
+ * @returns FetchResult with binary data or error
+ */
+export declare function fetchBinary(url: string, options?: FetchOptions): Promise<FetchResult>;
+/**
+ * Fetch OCSP response
+ * @param url OCSP responder URL
+ * @param request DER-encoded OCSP request
+ * @param timeout Timeout in milliseconds
+ * @param proxyUrl Optional CORS proxy URL
+ * @returns FetchResult with OCSP response data
+ */
+export declare function fetchOCSP(url: string, request: ArrayBuffer, timeout?: number, proxyUrl?: string): Promise<FetchResult>;
+/**
+ * Fetch CRL from distribution point
+ * @param url CRL distribution point URL
+ * @param timeout Timeout in milliseconds
+ * @param proxyUrl Optional CORS proxy URL
+ * @returns FetchResult with CRL data
+ */
+export declare function fetchCRL(url: string, timeout?: number, proxyUrl?: string): Promise<FetchResult>;
+/**
+ * Fetch issuer certificate from AIA extension
+ * @param url CA Issuers URL
+ * @param timeout Timeout in milliseconds
+ * @param proxyUrl Optional CORS proxy URL
+ * @returns FetchResult with certificate data
+ */
+export declare function fetchIssuerCertificate(url: string, timeout?: number, proxyUrl?: string): Promise<FetchResult>;

package/dist/core/revocation/index.d.ts

@@ -0,0 +1,4 @@
+export { checkCertificateRevocation, checkCertificatesRevocation } from "./check";
+export { RevocationResult, RevocationCheckOptions, DEFAULT_REVOCATION_OPTIONS, OID } from "./types";
+export { extractOCSPUrls, extractCAIssuersUrls, findIssuerInChain, checkOCSP } from "./ocsp";
+export { extractCRLUrls, checkCRL } from "./crl";

package/dist/core/revocation/ocsp.d.ts

@@ -0,0 +1,54 @@
+import { X509Certificate } from "@peculiar/x509";
+import { RevocationResult } from "./types";
+/**
+ * Extract OCSP responder URLs from certificate
+ * @param cert X509Certificate to extract OCSP URLs from
+ * @returns Array of OCSP responder URLs
+ */
+export declare function extractOCSPUrls(cert: X509Certificate): string[];
+/**
+ * Extract CA Issuers URLs from certificate (for fetching issuer cert)
+ * @param cert X509Certificate to extract URLs from
+ * @returns Array of CA Issuers URLs
+ */
+export declare function extractCAIssuersUrls(cert: X509Certificate): string[];
+/**
+ * Find issuer certificate from certificate chain
+ * @param cert Certificate to find issuer for
+ * @param chain Array of PEM-formatted certificates
+ * @returns Issuer certificate or null if not found
+ */
+export declare function findIssuerInChain(cert: X509Certificate, chain: string[]): X509Certificate | null;
+/**
+ * Fetch issuer certificate from AIA extension
+ * @param cert Certificate to fetch issuer for
+ * @param timeout Timeout in ms
+ * @param proxyUrl Optional CORS proxy URL
+ * @returns Issuer certificate or null
+ */
+export declare function fetchIssuerFromAIA(cert: X509Certificate, timeout?: number, proxyUrl?: string): Promise<X509Certificate | null>;
+/**
+ * Build OCSP request for a certificate
+ * @param cert Certificate to check
+ * @param issuerCert Issuer certificate
+ * @returns DER-encoded OCSP request
+ */
+export declare function buildOCSPRequest(cert: X509Certificate, issuerCert: X509Certificate): Promise<ArrayBuffer>;
+/**
+ * Parse OCSP response and extract revocation status
+ * @param responseData DER-encoded OCSP response
+ * @returns Revocation result
+ */
+export declare function parseOCSPResponse(responseData: ArrayBuffer): RevocationResult;
+/**
+ * Check certificate revocation via OCSP
+ * @param cert Certificate to check
+ * @param issuerCert Issuer certificate (optional, will try to find/fetch)
+ * @param options OCSP check options
+ * @returns Revocation result
+ */
+export declare function checkOCSP(cert: X509Certificate, issuerCert: X509Certificate | null, options?: {
+    timeout?: number;
+    certificateChain?: string[];
+    proxyUrl?: string;
+}): Promise<RevocationResult>;

package/dist/core/revocation/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Result of a certificate revocation check
+ */
+export interface RevocationResult {
+    /** Whether the certificate passed revocation check (not revoked) */
+    isValid: boolean;
+    /** Revocation status */
+    status: "good" | "revoked" | "unknown" | "error";
+    /** Method used to check revocation */
+    method?: "ocsp" | "crl" | "none";
+    /** Human-readable reason for the status */
+    reason?: string;
+    /** Date when certificate was revoked (if revoked) */
+    revokedAt?: Date;
+    /** When this revocation check was performed */
+    checkedAt: Date;
+}
+/**
+ * Options for revocation checking
+ */
+export interface RevocationCheckOptions {
+    /** Enable OCSP checking (default: true) */
+    ocspEnabled?: boolean;
+    /** Enable CRL checking as fallback (default: true) */
+    crlEnabled?: boolean;
+    /** Timeout for OCSP requests in ms (default: 5000) */
+    ocspTimeout?: number;
+    /** Timeout for CRL requests in ms (default: 10000) */
+    crlTimeout?: number;
+    /** Certificate chain for finding issuer (PEM strings) */
+    certificateChain?: string[];
+    /**
+     * CORS proxy URL for browser environments.
+     * When set, all OCSP/CRL fetch requests will be routed through this proxy.
+     * The original URL will be URL-encoded and appended as a query parameter.
+     * Example: "https://cors-proxy.example.com/?url="
+     */
+    proxyUrl?: string;
+}
+/**
+ * Default options for revocation checking
+ */
+export declare const DEFAULT_REVOCATION_OPTIONS: Required<Omit<RevocationCheckOptions, "certificateChain" | "proxyUrl">>;
+/**
+ * OID constants for certificate extensions
+ */
+export declare const OID: {
+    /** Authority Information Access */
+    readonly authorityInfoAccess: "1.3.6.1.5.5.7.1.1";
+    /** CRL Distribution Points */
+    readonly crlDistributionPoints: "2.5.29.31";
+    /** OCSP access method */
+    readonly ocsp: "1.3.6.1.5.5.7.48.1";
+    /** CA Issuers access method */
+    readonly caIssuers: "1.3.6.1.5.5.7.48.2";
+};

package/dist/core/timestamp/index.d.ts

@@ -0,0 +1,2 @@
+export { TimestampInfo, TimestampVerificationResult, TimestampVerificationOptions } from "./types";
+export { parseTimestamp, verifyTimestamp, verifyTimestampCoversSignature, getTimestampTime, } from "./verify";

package/dist/core/timestamp/types.d.ts

@@ -0,0 +1,48 @@
+import { RevocationResult } from "../revocation/types";
+/**
+ * Parsed timestamp information from RFC 3161 TimeStampToken
+ */
+export interface TimestampInfo {
+    /** The timestamp generation time (when TSA signed) */
+    genTime: Date;
+    /** TSA policy OID */
+    policy: string;
+    /** Serial number of the timestamp */
+    serialNumber: string;
+    /** Hash algorithm used for the message imprint */
+    hashAlgorithm: string;
+    /** The message imprint (hash of timestamped data) */
+    messageImprint: string;
+    /** TSA name (if provided) */
+    tsaName?: string;
+    /** TSA certificate (PEM format) */
+    tsaCertificate?: string;
+    /** Accuracy of the timestamp (in seconds) */
+    accuracy?: number;
+}
+/**
+ * Result of timestamp verification
+ */
+export interface TimestampVerificationResult {
+    /** Whether the timestamp is valid */
+    isValid: boolean;
+    /** Parsed timestamp info (if parsing succeeded) */
+    info?: TimestampInfo;
+    /** Error or status message */
+    reason?: string;
+    /** Whether the timestamp covers the signature value correctly */
+    coversSignature?: boolean;
+    /** TSA certificate revocation check result (if checkTsaRevocation was enabled) */
+    tsaRevocation?: RevocationResult;
+}
+/**
+ * Options for timestamp verification
+ */
+export interface TimestampVerificationOptions {
+    /** The signature value that the timestamp should cover (base64) */
+    signatureValue?: string;
+    /** Verify the TSA certificate chain */
+    verifyTsaCertificate?: boolean;
+    /** Check TSA certificate revocation */
+    checkTsaRevocation?: boolean;
+}

package/dist/core/timestamp/verify.d.ts

@@ -0,0 +1,32 @@
+import { TimestampInfo, TimestampVerificationResult, TimestampVerificationOptions } from "./types";
+/**
+ * Parse RFC 3161 TimeStampToken from base64
+ * @param timestampBase64 Base64-encoded timestamp token
+ * @returns Parsed timestamp info or null if parsing fails
+ */
+export declare function parseTimestamp(timestampBase64: string): TimestampInfo | null;
+/**
+ * Verify that timestamp covers the signature value
+ * XAdES timestamps can cover either:
+ * 1. The decoded signature value bytes (standard per ETSI EN 319 132-1)
+ * 2. The base64-encoded string (some implementations)
+ *
+ * @param timestampInfo Parsed timestamp info
+ * @param signatureValueBase64 Base64-encoded signature value
+ * @returns True if the timestamp covers the signature
+ */
+export declare function verifyTimestampCoversSignature(timestampInfo: TimestampInfo, signatureValueBase64: string): Promise<boolean>;
+/**
+ * Verify an RFC 3161 timestamp token
+ * @param timestampBase64 Base64-encoded timestamp token
+ * @param options Verification options
+ * @returns Timestamp verification result
+ */
+export declare function verifyTimestamp(timestampBase64: string, options?: TimestampVerificationOptions): Promise<TimestampVerificationResult>;
+/**
+ * Get the trusted timestamp time from a signature
+ * This should be used instead of the self-declared signingTime for certificate validation
+ * @param timestampBase64 Base64-encoded timestamp token
+ * @returns The timestamp generation time, or null if parsing fails
+ */
+export declare function getTimestampTime(timestampBase64: string): Date | null;

package/dist/core/verification.d.ts

@@ -1,5 +1,7 @@
 import { CertificateInfo } from "./certificate";
 import { SignatureInfo } from "./parser";
+import { RevocationResult, RevocationCheckOptions } from "./revocation/types";
+import { TimestampVerificationResult } from "./timestamp/types";
 /**
  * Options for verification process
  */
@@ -8,6 +10,12 @@ export interface VerificationOptions {
     verifySignatures?: boolean;
     verifyChecksums?: boolean;
     verifyTime?: Date;
+    /** Check certificate revocation via OCSP/CRL (default: true) */
+    checkRevocation?: boolean;
+    /** Options for revocation checking (timeouts, etc.) */
+    revocationOptions?: RevocationCheckOptions;
+    /** Verify RFC 3161 timestamp if present (default: true) */
+    verifyTimestamps?: boolean;
 }
 /**
  * Result of a checksum verification
@@ -42,6 +50,8 @@ export interface CertificateVerificationResult {
     isValid: boolean;
     reason?: string;
     info?: CertificateInfo;
+    /** Revocation check result (if checkRevocation was enabled) */
+    revocation?: RevocationResult;
 }
 /**
  * Complete verification result
@@ -51,6 +61,8 @@ export interface VerificationResult {
     certificate: CertificateVerificationResult;
     checksums: ChecksumVerificationResult;
     signature?: SignatureVerificationResult;
+    /** Timestamp verification result (if timestamp present and verifyTimestamps enabled) */
+    timestamp?: TimestampVerificationResult;
     errors?: string[];
 }
 /**