Luca Web Crypto

@lucaapp/crypto is the shared cryptography library of the luca web services. It bundles the primitives, encodings and JWT/X.509 helpers that the services need to talk to each other and to the luca apps:

• EC P-256 key generation, ECDSA (DER and IEEE P1363), ECDH
• SHA-256, HMAC, HKDF/KDF, scrypt, AES-CTR and AES-GCM, DLIES encryption
• hex, base64, base32 (plain and Crockford), z85 and UUID conversions
• PEM helpers and X.509 certificate parsing and chain verification
• generic JWT verification against zod schemas
• the signed key and transfer entities of the luca protocol

Source: https://gitlab.com/luca-internal/web/luca-web-crypto

Requirements

• Node.js as pinned in .nvmrc (nvm use)
• yarn 1 (classic)

Installation

yarn add @lucaapp/crypto

For development:

nvm use
yarn install --frozen-lockfile
yarn lint
yarn test
yarn build

yarn test:coverage writes a coverage report, yarn audit:osv runs the dependency audit and yarn list-licenses prints the license report.

Exports

Everything is re-exported from the package root (src/index.ts):

| Module | Contents | |--------|----------| | crypto | Key generation, signatures, ECDH, hashes, KDFs, AES, DLIES, trace IDs | | encoding | Conversions between hex, bytes, base64, base32, z85, integers and UUIDs | | x509 | EC key to PEM, common name, organizational unit, fingerprint and public key extraction, certificate chain verification | | jwt | verifyJWT: signature, issuer and subject check, then zod schema parse | | entities | createSigned* / verifySigned* pairs for publicDailyKey, publicBadgeKey, encryptedPrivateDailyKey, encryptedPrivateBadgeKey, publicHDSKP, publicHDEKP and locationTransfer | | errors | CommonNameMismatchError, CertificateChainInvalidError |

See src/AGENTS.md for a file by file overview.

Release process

1. Bump version in package.json and add the release to CHANGELOG.md.
2. Merge to master.
3. Push a tag v<version> (for example v4.4.1).

The tag pipeline builds the package and publishes it to npm through trusted publishing (OIDC). No npm token is involved. The publish job fails if the tag does not match the package.json version.

Changelog

An overview of all releases can be found in the changelog.

Issues and support

Please create an issue for suggestions or problems related to this library. For general questions, check the FAQ or contact [email protected].

License

The luca web crypto package is Free Software (Open Source) and is distributed with a number of components with compatible licenses.

SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2021 culture4life GmbH <https://luca-app.de>

For details see the license file.