DUIS Signing Wrapper

Lightweight TypeScript wrapper around SmartDCCInnovation/dccboxed-signing-tool - which is a tool for signing and validating DUIS messages. This package wraps dccboxed-signing-tool as a JavaScript package with some additional marshalling and error handling. That is, it provides an API to create and validate an appropriately formatted xmldsig.

Table of Contents

• Usage
  • Sign DUIS
  • Validate
  • HTTP Backend
  • Advanced
• API Options
• Contributing

Usage

Important: This package wraps around a JAR file, thus it is essential that a Java Runtime Environment is installed and available in the PATH before using it. Please use JRE 11 (or newer).

From Debian/Ubuntu an appropriate JRE can be installed with:

sudo apt install openjdk-11-jre

Developed and tested against node 24. Install from npm:

npm i @smartdcc/duis-sign-wrap

Sign DUIS

Below is a minimal example of how to use the library:

import { signDuis } from '@smartdcc/duis-sign-wrap'
import { readFile } from 'node:fs/promises'

const duisSigned: string = await signDuis({ xml: await readFile('/path/to/duis/file-without-signature.xml') })

Providing no exception was raised, the resulting duisSigned should be compatible with DCC Boxed.

Validate

Then to validate a signed DUIS against its XSD and remove the digital signature:

import { validateDuis } from '@smartdcc/duis-sign-wrap'

const xml: string = await validateDuis({ xml: duisSigned })

HTTP Backend

The library supports using an HTTP backend server for signing and validation, which provides increased performance for multiple operations by reusing the same Java process.

import { signDuis, validateDuis } from '@smartdcc/duis-sign-wrap'

// Automatically start and manage a local backend server
const signed = await signDuis({ xml: '<duis/>', backend: true })
const validated = await validateDuis({ xml: signed, backend: true })

Alternatively, a custom backend server can be provided that conforms to the correct API. This is useful when needing to integrate with a bespoke key store. The HTTP API is documented within the SmartDCCInnovation/dccboxed-signing-tool tool.

// Or use a custom backend URL
const customSigned = await signDuis({
  xml: '<duis/>',
  backend: new URL('http://signing-service.example.com/'),
  headers: { 'Authorization': 'Bearer token' }
})

Advanced

The intention is that this tool is compatible with the duis-parser to obtain a JSON representation of the DUIS. A minimal example without error handling would be:

import { validateDuis } from '@smartdcc/duis-sign-wrap'
import { parseDuis } from '@smartdcc/duis-parser'

const data = parseDuis(await validateDuis({ xml: duisSigned }))

API Options

Both signDuis and validateDuis accept an options object with the following properties:

• xml (string | Buffer, required): The DUIS XML content to sign or validate
• backend (boolean | URL, optional): Use HTTP backend for improved performance
  • true: Automatically start and manage a local backend server
  • URL: Use a custom backend server at the specified URL
• headers (Record<string, string>, optional): Custom HTTP headers when using backend mode
• preserveCounter (boolean, optional, sign only): Preserve counter value in RequestID when signing

Error Handling

import { signDuis } from '@smartdcc/duis-sign-wrap'

try {
  const signed = await signDuis({ xml: '<invalid/>', backend: true })
} catch (error) {
  console.error('Signing failed:', error.message)
  // Handle validation errors, missing credentials, etc.
}

Contributing

Contributions are welcome!

Remember, when developing it is required to install a JDK (to build the dccboxed-signing-tool) and update submodules. To build the JAR file, run the following command: npm run build:jar.

When submitting a pull request, please ensure:

1. Each PR is concise and provides only one feature/bug fix.
2. Unit test are provided to cover feature. The project uses jest. To test, run npm run test:cov to view code coverage metrics.
3. Bugfixes are reference the GitHub issue.
4. If appropriate, update documentation.
5. Before committing, run npm run lint and npm run prettier-check.

If you are planning a new non-trivial feature, please first raise a GitHub issue to discuss it to before investing your time to avoid disappointment.

Any contributions will be expected to be licensable under GPLv3.

Other Info

Copyright 2026, Smart DCC Limited, All rights reserved. Project is licensed under GPLv3.