edockit 0.1.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Edgars Jēkabsons, ZenomyTech SIA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# edockit
+
+A JavaScript/TypeScript library for viewing and verifying EU standard ASiC-E containers (including Latvian eDoc files, which use the same format with a different extension). Works in both browser and Node.js environments.
+
+> **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) 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.
+
+## Installation
+
+```bash
+# Install the core library
+npm install edockit
+
+# If using in Node.js environment, also install xmldom
+npm install @xmldom/xmldom
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { parseEdoc, verifySignature } from 'edockit';
+
+// Parse an ASiC-E/eDoc file
+const fileBuffer = /* your file buffer */;
+const container = parseEdoc(fileBuffer);
+// container = {
+//   files: Map<string, Uint8Array>,  // All files in the container
+//   documentFileList: string[],      // Document files (.pdf, .docx, etc.)
+//   metadataFileList: string[],      // Metadata files
+//   signedFileList: string[],        // Files covered by signatures
+//   signatures: SignatureInfo[]      // Signature objects
+// }
+
+// List files in container
+console.log(Array.from(container.files.keys()));
+
+// Verify a signature
+const result = await verifySignature(container.signatures[0], container.files);
+// result = {
+//   isValid: boolean,                // Overall validity
+//   certificate: {isValid: boolean}, // Certificate validation result
+//   checksums: {isValid: boolean},   // File checksums validation result
+//   signature: {isValid: boolean},   // XML signature validation result
+//   errors: string[]                 // Any validation errors (if present)
+// }
+console.log(`Signature valid: ${result.isValid}`);
+```
+
+### Node.js Example
+
+```typescript
+import { readFileSync } from 'fs';
+import { parseEdoc, verifySignature } from 'edockit';
+
+// Read file
+const fileBuffer = readFileSync('document.asice');
+const container = parseEdoc(fileBuffer);
+
+// Check signatures
+for (const signature of container.signatures) {
+  const result = await verifySignature(signature, container.files);
+  console.log(`Signature valid: ${result.isValid}`);
+
+  if (!result.isValid && result.errors) {
+    console.log(`Errors: ${result.errors.join(', ')}`);
+  }
+}
+```
+
+### Browser Example
+
+```javascript
+// Fetch and verify a document
+async function verifyDocument(url) {
+  const response = await fetch(url);
+  const fileBuffer = await response.arrayBuffer();
+
+  const container = parseEdoc(new Uint8Array(fileBuffer));
+
+  // List document files
+  console.log("Documents:", container.documentFileList);
+
+  for (const signature of container.signatures) {
+    const result = await verifySignature(signature, container.files);
+    console.log(`Valid: ${result.isValid}`);
+  }
+}
+```
+
+## 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)
+
+## 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
+- Edge cases and non-standard implementations
+
+## Browser Usage with UMD Build
+
+If you're not using a module bundler, you can use the UMD build:
+
+```html
+<script src="path/to/edockit/dist/index.umd.js"></script>
+<script>
+  // Access the library from the global 'edockit' object
+  const { parseEdoc, verifySignature } = edockit;
+
+  // Your code here
+</script>
+```
+
+## Contributing
+
+Contributions are highly encouraged! The library needs more real-world testing to improve compatibility and robustness. In particular:
+
+1. Testing with ASiC-E containers from different European countries
+2. Bug reports with sample files (when possible)
+3. Feature requests for specific EU country implementations
+4. Documentation improvements
+
+If you encounter any issues, please open an issue on GitHub. Including sample files with your issue report (if possible) will help tremendously with debugging and improving compatibility.
+
+## License
+
+MIT - See LICENSE file for details.

package/dist/core/canonicalization/XMLCanonicalizer.d.ts

@@ -0,0 +1,51 @@
+interface CanonMethod {
+    beforeChildren: (hasElementChildren?: boolean, hasMixedContent?: boolean) => string;
+    afterChildren: (hasElementChildren?: boolean, hasMixedContent?: boolean) => string;
+    betweenChildren: (prevIsElement?: boolean, nextIsElement?: boolean, hasMixedContent?: boolean) => string;
+    afterElement: () => string;
+    isCanonicalizationMethod?: string;
+}
+declare const CANONICALIZATION_METHODS: {
+    default: string;
+    "http://www.w3.org/TR/2001/REC-xml-c14n-20010315": string;
+    "http://www.w3.org/2006/12/xml-c14n11": string;
+    "http://www.w3.org/2001/10/xml-exc-c14n#": string;
+};
+declare const NODE_TYPES: {
+    ELEMENT_NODE: number;
+    TEXT_NODE: number;
+};
+interface ExcC14NOptions {
+    inclusiveNamespacePrefixList?: string[];
+    isStartingNode?: boolean;
+}
+interface WhitespaceInfo {
+    hasMixedContent?: boolean;
+    hasExistingLinebreaks?: boolean;
+    originalContent?: Record<string, any>;
+}
+interface NodeWithWhitespace extends Node {
+    _whitespace?: WhitespaceInfo;
+    _originalText?: string;
+}
+declare class XMLCanonicalizer {
+    private method;
+    constructor(method?: CanonMethod);
+    static fromMethod(methodUri: string): XMLCanonicalizer;
+    static base64Elements: Set<string>;
+    setMethod(method: CanonMethod): void;
+    static escapeXml(text: string): string;
+    static collectNamespaces(node: Node, visibleNamespaces?: Map<string, string>): Map<string, string>;
+    static collectUsedNamespaces(node: Node, allVisibleNamespaces?: Map<string, string>, inclusivePrefixList?: string[]): Map<string, string>;
+    static isBase64Element(node: Node): boolean;
+    static analyzeWhitespace(node: Node): void;
+    canonicalize(node: NodeWithWhitespace, visibleNamespaces?: Map<string, string>, options?: {
+        isStartingNode: boolean;
+    }): string;
+    canonicalizeExclusive(node: NodeWithWhitespace, visibleNamespaces?: Map<string, string>, options?: ExcC14NOptions): string;
+    static c14n(node: Node): string;
+    static c14n11(node: Node): string;
+    static c14n_exc(node: Node, inclusiveNamespacePrefixList?: string[]): string;
+    static canonicalize(node: Node, methodUri: string, options?: any): string;
+}
+export { XMLCanonicalizer, CANONICALIZATION_METHODS, NODE_TYPES };

package/dist/core/certificate.d.ts

@@ -0,0 +1,98 @@
+import { X509Certificate } from "@peculiar/x509";
+/**
+ * Certificate subject information
+ */
+export interface CertificateSubject {
+    country?: string;
+    commonName?: string;
+    surname?: string;
+    givenName?: string;
+    serialNumber?: string;
+    organization?: string;
+}
+/**
+ * Certificate issuer information
+ */
+export interface CertificateIssuer {
+    country?: string;
+    commonName?: string;
+    organization?: string;
+}
+/**
+ * Full certificate information
+ */
+export interface CertificateInfo {
+    subject: CertificateSubject;
+    validFrom: Date;
+    validTo: Date;
+    issuer: CertificateIssuer;
+    serialNumber?: string;
+}
+/**
+ * Certificate validity check result
+ */
+export interface CertificateValidityResult {
+    isValid: boolean;
+    reason?: string;
+}
+/**
+ * Format a certificate string as a proper PEM certificate
+ * @param certBase64 Base64-encoded certificate
+ * @returns Formatted PEM certificate
+ */
+export declare function formatPEM(certBase64?: string): string;
+/**
+ * Extract subject information from an X.509 certificate
+ * @param certificate X509Certificate instance
+ * @returns Signer information object
+ */
+export declare function extractSignerInfo(certificate: X509Certificate): {
+    commonName?: string;
+    organization?: string;
+    country?: string;
+    surname?: string;
+    givenName?: string;
+    serialNumber?: string;
+    validFrom: Date;
+    validTo: Date;
+    issuer: {
+        commonName?: string;
+        organization?: string;
+        country?: string;
+    };
+};
+/**
+ * Parse a certificate from base64 data
+ * @param certData Base64-encoded certificate data
+ * @returns Parsed certificate information
+ */
+export declare function parseCertificate(certData: string): Promise<CertificateInfo>;
+/**
+ * Check if a certificate was valid at a specific time
+ * @param cert Certificate object or info
+ * @param checkTime The time to check validity against (defaults to current time)
+ * @returns Validity check result
+ */
+export declare function checkCertificateValidity(cert: X509Certificate | CertificateInfo, checkTime?: Date): CertificateValidityResult;
+/**
+ * Extract the public key information from a certificate
+ * @param cert The X.509 certificate
+ * @returns Public key information
+ */
+export declare function getPublicKeyInfo(cert: X509Certificate): {
+    algorithm: string;
+    namedCurve?: string;
+    rawData: ArrayBuffer;
+};
+/**
+ * Helper function to get signer display name from certificate
+ * @param certInfo Certificate information
+ * @returns Formatted display name
+ */
+export declare function getSignerDisplayName(certInfo: CertificateInfo): string;
+/**
+ * Helper function to format certificate validity period in a human-readable format
+ * @param certInfo Certificate information
+ * @returns Formatted validity period
+ */
+export declare function formatValidityPeriod(certInfo: CertificateInfo): string;

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

@@ -0,0 +1,6 @@
+/**
+ * Format a certificate string as a proper PEM certificate
+ * @param certBase64 Base64-encoded certificate
+ * @returns Formatted PEM certificate
+ */
+export declare function formatPEM(certBase64?: string): string;

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

@@ -0,0 +1,33 @@
+import { SignatureInfo } from "./types";
+import { formatPEM } from "./certificateUtils";
+/**
+ * Find signature files in the eDoc container
+ * @param files Map of filenames to file contents
+ * @returns Array of signature filenames
+ */
+export declare function findSignatureFiles(files: Map<string, Uint8Array>): string[];
+/**
+ * Parse a signature file that contains a single signature
+ * @param xmlContent The XML file content
+ * @param filename The filename (for reference)
+ * @returns The parsed signature with raw XML content
+ */
+export declare function parseSignatureFile(xmlContent: Uint8Array, filename: string): SignatureInfo | null;
+/**
+ * Parse a single signature element using a browser-like approach
+ * @param signatureElement The signature element to parse
+ * @param xmlDoc The parent XML document
+ * @returns Parsed signature information
+ */
+export declare function parseSignatureElement(signatureElement: Element, xmlDoc: Document): SignatureInfo;
+/**
+ * Fallback for creating a basic signature from text when DOM parsing fails
+ * @param xmlText The full XML text
+ * @returns A basic signature or null if parsing fails
+ */
+export declare function parseBasicSignatureFromText(xmlText: string): SignatureInfo | null;
+export declare const __test__: {
+    parseSignatureElement: typeof parseSignatureElement;
+    parseBasicSignatureFromText: typeof parseBasicSignatureFromText;
+    formatPEM: typeof formatPEM;
+};

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

@@ -0,0 +1,38 @@
+export interface EdocContainer {
+    files: Map<string, Uint8Array>;
+    documentFileList: string[];
+    metadataFileList: string[];
+    signedFileList: string[];
+    signatures: SignatureInfo[];
+}
+export interface SignatureInfo {
+    id: string;
+    signingTime: Date;
+    certificate: string;
+    certificatePEM: string;
+    publicKey?: {
+        algorithm: string;
+        namedCurve?: string;
+        rawData: ArrayBuffer;
+    };
+    signedChecksums: Record<string, string>;
+    signerInfo?: {
+        commonName?: string;
+        organization?: string;
+        country?: string;
+        serialNumber?: string;
+        validFrom: Date;
+        validTo: Date;
+        issuer: {
+            commonName?: string;
+            organization?: string;
+            country?: string;
+        };
+    };
+    references: string[];
+    algorithm?: string;
+    signatureValue?: string;
+    signedInfoXml?: string;
+    rawXml?: string;
+    canonicalizationMethod?: string;
+}

package/dist/core/parser.d.ts

@@ -0,0 +1,8 @@
+import type { EdocContainer, SignatureInfo } from "./parser/types";
+export { EdocContainer, SignatureInfo };
+/**
+ * Parse an eDoc container from a buffer
+ * @param edocBuffer The raw eDoc file content
+ * @returns Parsed container with files, document file list, metadata file list, signed file list, and signatures
+ */
+export declare function parseEdoc(edocBuffer: Uint8Array): EdocContainer;

package/dist/core/verification.d.ts

@@ -0,0 +1,94 @@
+import { CertificateInfo } from "./certificate";
+import { SignatureInfo } from "./parser";
+/**
+ * Options for verification process
+ */
+export interface VerificationOptions {
+    checkCertificateValidity?: boolean;
+    verifySignatures?: boolean;
+    verifyChecksums?: boolean;
+    verifyTime?: Date;
+}
+/**
+ * Result of a checksum verification
+ */
+export interface ChecksumVerificationResult {
+    isValid: boolean;
+    details: Record<string, {
+        expected: string;
+        actual: string;
+        matches: boolean;
+        fileFound: boolean;
+    }>;
+}
+/**
+ * Result of a signature verification
+ */
+export interface SignatureVerificationResult {
+    isValid: boolean;
+    reason?: string;
+}
+/**
+ * Result of a certificate verification
+ */
+export interface CertificateVerificationResult {
+    isValid: boolean;
+    reason?: string;
+    info?: CertificateInfo;
+}
+/**
+ * Complete verification result
+ */
+export interface VerificationResult {
+    isValid: boolean;
+    certificate: CertificateVerificationResult;
+    checksums: ChecksumVerificationResult;
+    signature?: SignatureVerificationResult;
+    errors?: string[];
+}
+/**
+ * Compute a digest (hash) of file content with browser/node compatibility
+ * @param fileContent The file content as Uint8Array
+ * @param algorithm The digest algorithm to use (e.g., 'SHA-256')
+ * @returns Promise with Base64-encoded digest
+ */
+export declare function computeDigest(fileContent: Uint8Array, algorithm: string): Promise<string>;
+/**
+ * Verify checksums of files against signature
+ * @param signature The signature information
+ * @param files Map of filenames to file contents
+ * @returns Promise with verification results for each file
+ */
+export declare function verifyChecksums(signature: {
+    signedChecksums: Record<string, string>;
+    algorithm?: string;
+}, files: Map<string, Uint8Array>): Promise<ChecksumVerificationResult>;
+/**
+ * Verify certificate validity
+ * @param certificatePEM PEM-formatted certificate
+ * @param verifyTime Time to check validity against
+ * @returns Certificate verification result
+ */
+export declare function verifyCertificate(certificatePEM: string, verifyTime?: Date): Promise<CertificateVerificationResult>;
+/**
+ * Verify the XML signature specifically using SignedInfo and SignatureValue
+ * @param signatureXml The XML string of the SignedInfo element
+ * @param signatureValue The base64-encoded signature value
+ * @param publicKeyData The public key raw data
+ * @param algorithm Key algorithm details
+ * @param canonicalizationMethod The canonicalization method used
+ * @returns Signature verification result
+ */
+export declare function verifySignedInfo(signatureXml: string, signatureValue: string, publicKeyData: ArrayBuffer, algorithm: {
+    name: string;
+    hash: string;
+    namedCurve?: string;
+}, canonicalizationMethod?: string): Promise<SignatureVerificationResult>;
+/**
+ * Verify a complete signature (certificate, checksums, and signature)
+ * @param signatureInfo Signature information
+ * @param files File contents
+ * @param options Verification options
+ * @returns Complete verification result
+ */
+export declare function verifySignature(signatureInfo: SignatureInfo, files: Map<string, Uint8Array>, options?: VerificationOptions): Promise<VerificationResult>;