edockit 0.3.0 → 0.4.0-dev.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [Unreleased]
+
+### Added
+
+- **Verification checklist output** - `verifySignature()` can now return a structured `checklist` with per-check status details when `includeChecklist: true`
+- **Pluggable trusted-list provider support** - `verifySignature()` now uses `trustListProvider` for trust-list checks instead of built-in root-level trusted-list behavior
+- **Purpose-aware trusted-list matching** - Trusted-list checks now distinguish signer issuer lookup from timestamp authority lookup and expose both `trustListMatch` and `timestampTrustListMatch`
+- **Trusted-list package split** - Added opt-in subpath exports for `edockit/trusted-list`, `edockit/trusted-list/build`, `edockit/trusted-list/http`, and `edockit/trusted-list/bundled`
+- **Compact trusted-list bundle format** - Added local matching against compact JSON bundles with a dedicated provider contract
+- **Public Node-only trusted-list builder** - Added `edockit/trusted-list/build` for generating app-hosted trusted-list JSON, along with the repository `npm run update-trusted-list` script
+
+### Fixed
+
+- **SignatureTimeStamp canonicalization** - Respect the timestamp's declared canonicalization method when hashing `ds:SignatureValue`, fixing false `coversSignature: false` results for some real samples
+- **Skip LDAP CRL distribution points** - Filter out non-HTTP(S) URLs from CRL distribution points to avoid failed fetch attempts on unsupported protocols like LDAP
+- **Timestamp trust-list evaluation** - Trusted-list verification now checks timestamp authorities at the timestamp signing time instead of only checking the signer issuer side
+
 ## [0.3.0] - 2026-01-04
 
 ### Added

package/README.md

@@ -1,244 +1,127 @@
 # 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.
+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. It 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!
-
-## 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.
+> Note: Work in progress. This library still needs broader real-world testing with ASiC-E implementations from more EU countries.
 
 ## Installation
 
 ```bash
-# Install the core library
 npm install edockit
-
-# If using in Node.js environment, also install xmldom
-npm install @xmldom/xmldom
 ```
 
-## Usage
+If you implement trusted-list checking, [TRUSTED-LIST.md](TRUSTED-LIST.md) is required reading. The README only covers the quick-start path.
 
-### Basic Usage
+## Quick Start
 
 ```typescript
-import { parseEdoc, verifySignature } from 'edockit';
+import { parseEdoc, verifySignature } from "edockit";
+import { createTrustListProvider } from "edockit/trusted-list";
 
-// 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 (with revocation and timestamp checking)
+
+const trustListProvider = createTrustListProvider({
+  url: "/assets/trusted-list.json",
+});
+
 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)
+  includeChecklist: true,
+  trustListProvider,
+  revocationOptions: {
+    proxyUrl: "https://cors-proxy.example.com/?url=",
+  },
+  trustedListFetchOptions: {
+    proxyUrl: "https://cors-proxy.example.com/?url=",
   },
-  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 (for backwards compatibility)
-//   status: 'VALID' | 'INVALID' | 'INDETERMINATE' | 'UNSUPPORTED',  // Granular status
-//   statusMessage?: string,          // Human-readable explanation
-//   limitations?: [{                 // Platform/environment constraints (if any)
-//     code: string,                  // e.g., 'RSA_KEY_SIZE_UNSUPPORTED'
-//     description: string,
-//     platform?: string              // e.g., 'Safari/WebKit'
-//   }],
-//   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}`);
+
+console.log(result.status, result.statusMessage);
+console.log(
+  result.checklist?.find((item) => item.check === "issuer_trusted_at_signing_time"),
+);
 ```
 
-### Node.js Example
+Use `revocationOptions.proxyUrl` in browsers because OCSP and CRL endpoints usually do not support CORS. `trustedListFetchOptions.proxyUrl` is only needed if the verifier must fetch issuer certificates to strengthen trusted-list matching.
 
-```typescript
-import { readFileSync } from "fs";
-import { parseEdoc, verifySignature } from "edockit";
+## Verification Results
 
-// Read file
-const fileBuffer = readFileSync("document.asice");
-const container = parseEdoc(fileBuffer);
+`verifySignature()` returns:
 
-// Check signatures with revocation and timestamp checking
-for (const signature of container.signatures) {
-  const result = await verifySignature(signature, container.files, {
-    checkRevocation: true,
-    verifyTimestamps: true
-  });
-
-  // Use granular status for detailed handling
-  console.log(`Status: ${result.status}`);  // VALID, INVALID, INDETERMINATE, or UNSUPPORTED
-
-  if (result.status === 'VALID') {
-    console.log('Signature is valid');
-  } else if (result.status === 'UNSUPPORTED') {
-    // Platform limitation (e.g., RSA >4096 bits in Safari)
-    console.log(`Cannot verify: ${result.statusMessage}`);
-  } else if (result.status === 'INDETERMINATE') {
-    // Can't conclude (e.g., revocation status unknown)
-    console.log(`Inconclusive: ${result.statusMessage}`);
-  } else {
-    // INVALID - definitely wrong
-    console.log(`Invalid: ${result.statusMessage}`);
-  }
-
-  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}`);
-  }
-}
-```
+- `status`: `"VALID" | "INVALID" | "INDETERMINATE" | "UNSUPPORTED"`
+- `statusMessage`: a human-readable explanation
+- `checklist`: optional structured verification steps when `includeChecklist: true`
+- `trustListMatch`: signer-issuer trust-list result when `trustListProvider` is configured
+- `timestampTrustListMatch`: timestamp-authority trust-list result when `trustListProvider` is configured
 
-### 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, {
-      checkRevocation: true,
-      revocationOptions: {
-        // Use a CORS proxy for OCSP/CRL requests in browser environments
-        proxyUrl: 'https://your-cors-proxy.example.com/?url=',
-      },
-    });
-
-    // Handle different validation states
-    if (result.status === 'VALID') {
-      console.log('Signature verified successfully');
-    } else if (result.status === 'UNSUPPORTED') {
-      // Some signatures can't be verified in certain browsers (e.g., RSA >4096 in Safari)
-      console.log(`Browser limitation: ${result.statusMessage}`);
-    } else {
-      console.log(`${result.status}: ${result.statusMessage}`);
-    }
-
-    if (result.timestamp?.info) {
-      console.log(`Timestamp: ${result.timestamp.info.genTime}`);
-    }
-  }
-}
-```
+`allowWeakDnOnlyTrustMatch` is off by default, so DN-only trusted-list matches remain `indeterminate`.
+
+## Trusted List Setup
 
-> **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.
+Recommended production path:
 
-### Timestamp Utilities
+1. Generate your own compact trusted-list bundle in CI or a build step.
+2. Host that JSON from your own app or CDN.
+3. Load it with `createTrustListProvider({ url })`.
 
-For advanced timestamp handling, you can use the timestamp utilities directly:
+Build-time generation uses the Node-only helper:
 
 ```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
+import { generateTrustedListBundle } from "edockit/trusted-list/build";
+
+await generateTrustedListBundle({
+  outputPath: "public/assets/trusted-list.json",
 });
 ```
 
-## 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 (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)
+Runtime local matching uses:
 
-## Testing Status
+```typescript
+import { createTrustListProvider } from "edockit/trusted-list";
+```
 
-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:
+Other opt-in trusted-list subpaths:
 
-- 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
+- `edockit/trusted-list/build`: Node-only bundle generation helpers
+- `edockit/trusted-list/http`: tiny remote API wrapper
+- `edockit/trusted-list/bundled`: explicit bundled fallback snapshot
 
-## Browser Usage with UMD Build
+For proper trusted-list integration, remote API usage, hybrid local+remote setups, the provider contract, and bundle/manifest details, read [TRUSTED-LIST.md](TRUSTED-LIST.md).
 
-If you're not using a module bundler, you can use the UMD build:
+## Timestamp Utilities
 
-```html
-<script src="path/to/edockit/dist/index.umd.js"></script>
-<script>
-  // Access the library from the global 'edockit' object
-  const { parseEdoc, verifySignature } = edockit;
+The root package also exposes timestamp helpers:
 
-  // Your code here
-</script>
+```typescript
+import { getTimestampTime, parseTimestamp, verifyTimestamp } from "edockit";
 ```
 
-## Contributing
+Use these if you need direct RFC 3161 parsing or verification outside `verifySignature()`.
+
+## Features
 
-Contributions are highly encouraged! The library needs more real-world testing to improve compatibility and robustness. In particular:
+- Parse ASiC-E containers, including Latvian `.edoc`
+- Verify XML signatures and signed file checksums
+- Validate signer certificates at the relevant signing time
+- Verify RFC 3161 timestamps
+- Check revocation for signer and TSA certificates
+- Return granular validation statuses instead of only boolean success/failure
+- Return a structured verification checklist for consumer applications
+- Match both signer issuers and timestamp authorities against a trusted list through an explicit provider contract
 
-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
+## Testing Status
 
-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.
+The library has been tested with a limited set of real Latvian eDoc files. More testing is still needed with:
+
+- ASiC-E containers from more EU countries
+- files produced by different vendor implementations
+- more signature algorithm and certificate variations
+- more edge cases and malformed samples
+
+## Contributing
 
-## License
+Contributions are welcome, especially:
 
-MIT - See LICENSE file for details.
+- real-world ASiC-E samples from different countries
+- bug reports with reproducible files when possible
+- interoperability fixes
+- documentation improvements

package/TRUSTED-LIST.md

@@ -0,0 +1,308 @@
+# Trusted List Usage
+
+This document describes the intended trusted-list integration model for `edockit`.
+
+If you are implementing trusted-list verification in a real app, this document is required reading. The root `README.md` only shows the shortest happy-path examples.
+
+## Package Surfaces
+
+`edockit` exposes the verification API and the trusted-list contract types:
+
+- `verifySignature`
+- `TrustListProvider`
+- `TrustListQuery`
+- `TrustListMatch`
+
+Trusted-list runtime is opt-in and split into subpaths:
+
+- `edockit/trusted-list`
+  - local compact-JSON provider
+  - use this for app-hosted JSON data
+- `edockit/trusted-list/build`
+  - Node.js-only trusted-list bundle generation helpers
+  - use this in CI or app build scripts to generate your own JSON
+- `edockit/trusted-list/http`
+  - tiny remote API wrapper
+  - use this if trust matching happens on your server
+- `edockit/trusted-list/bundled`
+  - convenience bundled fallback snapshot
+  - use only if you explicitly want the library-shipped snapshot
+
+## Recommended Production Setup
+
+For a first production version, use:
+
+- `edockit`
+- `edockit/trusted-list`
+- your own hosted compact trusted-list JSON
+
+Do not use the bundled fallback as the main production path.
+
+This avoids:
+
+- duplicating trusted-list data in your app and in the package
+- tying freshness to npm package releases
+- shipping extra trusted-list bytes you do not control
+
+Important:
+
+- `createTrustListProvider({ url })` expects the compact bundle JSON itself
+- it does not read `manifest.json`
+- if you generate a manifest, use it for your own rollout logic, then pass the actual bundle URL to the provider
+
+## Browser: Local JSON
+
+```typescript
+import { parseEdoc, verifySignature } from "edockit";
+import { createTrustListProvider } from "edockit/trusted-list";
+
+const trustListProvider = createTrustListProvider({
+  url: "/assets/trusted-list.json",
+});
+
+const container = parseEdoc(fileBuffer);
+
+const result = await verifySignature(container.signatures[0], container.files, {
+  includeChecklist: true,
+  trustListProvider,
+});
+```
+
+This is the preferred default for normal web apps.
+
+## Node.js: Local JSON
+
+```typescript
+import { readFileSync } from "node:fs";
+import { parseEdoc, verifySignature } from "edockit";
+import { createTrustListProvider } from "edockit/trusted-list";
+
+const trustedListBundle = JSON.parse(readFileSync("./trusted-list.json", "utf8"));
+const trustListProvider = createTrustListProvider({
+  data: trustedListBundle,
+});
+
+const container = parseEdoc(fileBuffer);
+
+const result = await verifySignature(container.signatures[0], container.files, {
+  trustListProvider,
+});
+```
+
+## Provider Contract
+
+The provider answers one narrow question:
+
+> Was this service trusted at time `T` for this purpose?
+
+The verifier combines that with timestamp, certificate, and revocation checks into the final signature result.
+
+```typescript
+type TrustListQueryPurpose = "signature_issuer" | "timestamp_tsa";
+
+interface TrustListQuery {
+  purpose: TrustListQueryPurpose;
+  time: Date;
+  spkiSha256Hex?: string | null;
+  skiHex?: string | null;
+  subjectDn?: string | null;
+}
+
+interface TrustListMatch {
+  found: boolean;
+  trustedAtTime?: boolean;
+  confidence?: "exact" | "ski_dn" | "dn_only";
+  country?: string;
+  detail?: string;
+}
+
+interface TrustListProvider {
+  match(query: TrustListQuery): Promise<TrustListMatch>;
+}
+```
+
+Notes:
+
+- `purpose` distinguishes signer-issuer matching from timestamp-authority matching.
+- `time` is required because trust-list answers are historical.
+- `subjectDn` should be the normalized X.500 DN used by the matcher.
+- `dn_only` matches are weak evidence. `verifySignature()` keeps them `indeterminate` unless `allowWeakDnOnlyTrustMatch` is enabled.
+
+## Remote API Example
+
+If you want a server-side trust-match API, you can either use the tiny helper or write the provider inline.
+
+```typescript
+import { verifySignature, type TrustListProvider } from "edockit";
+
+const trustListProvider: TrustListProvider = {
+  async match(query) {
+    const response = await fetch("/api/trust-list/match", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(query),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Trust-list lookup failed: HTTP ${response.status}`);
+    }
+
+    return response.json();
+  },
+};
+
+const result = await verifySignature(signature, files, {
+  trustListProvider,
+});
+```
+
+The packaged helper is equivalent in spirit:
+
+```typescript
+import { createRemoteTrustListProvider } from "edockit/trusted-list/http";
+```
+
+## Hybrid Model
+
+You can combine local hot data with remote fallback:
+
+```typescript
+import { createTrustListProvider } from "edockit/trusted-list";
+import { createRemoteTrustListProvider } from "edockit/trusted-list/http";
+
+const local = createTrustListProvider({
+  url: "/assets/trusted-list-baltics.json",
+});
+
+const remote = createRemoteTrustListProvider({
+  url: "/api/trust-list/match",
+});
+
+const trustListProvider = {
+  async match(query) {
+    const localMatch = await local.match(query);
+    if (localMatch.found) {
+      return localMatch;
+    }
+
+    return remote.match(query);
+  },
+};
+```
+
+That is a later optimization, not the recommended first step.
+
+## Bundled Fallback
+
+If you explicitly want the library-shipped fallback snapshot:
+
+```typescript
+import { createBundledTrustListProvider } from "edockit/trusted-list/bundled";
+
+const trustListProvider = createBundledTrustListProvider();
+```
+
+Behavior:
+
+- this is opt-in only
+- the bundled snapshot carries `generatedAt`
+- if it is older than 14 days, the provider emits a one-time warning
+
+Use this for demos, tests, or temporary convenience. Prefer app-hosted JSON in production.
+
+## Generating and Hosting JSON
+
+Apps can generate compact trusted-list JSON themselves with the public Node-only build helper:
+
+```typescript
+import { generateTrustedListBundle } from "edockit/trusted-list/build";
+
+await generateTrustedListBundle({
+  outputPath: "public/assets/trusted-list.json",
+});
+```
+
+That is the recommended production setup for a web app that wants local matching from app-hosted JSON.
+
+If you also want a manifest for later sharding or rollout logic:
+
+```typescript
+await generateTrustedListBundle({
+  outputPath: "public/assets/trusted-list.json",
+  manifestOutputPath: "public/assets/trusted-list-manifest.json",
+  baseUrl: "/assets",
+});
+```
+
+The runtime provider still loads the bundle JSON:
+
+```typescript
+const trustListProvider = createTrustListProvider({
+  url: "/assets/trusted-list.json",
+});
+```
+
+Do not point `createTrustListProvider({ url })` at `trusted-list-manifest.json`.
+
+If you want to do the same thing in this repository itself, the repo script still exists:
+
+```bash
+npm run update-trusted-list
+```
+
+That repo script writes:
+
+- `trusted-list/manifest.json`
+- `trusted-list/bundles/<bundleId>.json`
+
+In production, the usual pattern is:
+
+1. generate the JSON in CI
+2. deploy it as a static asset from your own origin
+3. load it with `createTrustListProvider({ url })`
+
+If your app later moves issuer/TSA matching to a server API, keep generating the same JSON and load it on the server:
+
+```typescript
+import { readFileSync } from "node:fs";
+import { buildTrustedListData, matchTrustListQuery } from "edockit/trusted-list";
+
+const bundle = JSON.parse(readFileSync("./public/assets/trusted-list.json", "utf8"));
+const trustedListData = buildTrustedListData(bundle);
+
+export async function postTrustMatch(request: Request): Promise<Response> {
+  const body = await request.json();
+  const match = matchTrustListQuery(
+    {
+      ...body,
+      time: new Date(body.time),
+    },
+    trustedListData,
+  );
+
+  return Response.json(match);
+}
+```
+
+Browser code can then use:
+
+```typescript
+import { createRemoteTrustListProvider } from "edockit/trusted-list/http";
+
+const trustListProvider = createRemoteTrustListProvider({
+  url: "/api/trust-list/match",
+});
+```
+
+## Practical Rollout
+
+Recommended order:
+
+1. Start with one compact JSON file.
+2. Verify locally with `edockit/trusted-list`.
+3. If needed later, split hot shards such as `lv`, `lt`, `ee`, or `baltics`.
+4. Only after that, add remote fallback for the long tail.
+
+That keeps the first production version simple and avoids unnecessary moving parts.