Keys, Algorithms, COSE and CWT


A TypeScript library for the [CBOR Object Signing and Encryption (COSE)][cose-spec] and [CBOR Web Token (CWT)][cwt-spec].

+ Golang version: https://github.com/ldclabs/cose
+ Rust version: https://github.com/google/coset

Introduction

COSE is a standard for signing and encrypting data in the [CBOR][cbor] data format. It is designed to be simple and efficient, and to be usable in constrained environments. It is intended to be used in a variety of applications, including the Internet of Things, and is designed to be extensible to support new algorithms and applications.

Features

- Key: Full support.
- Algorithms:
- Signing: ECDSA, Ed25519;
- Encryption: AES-GCM, ChaCha20/Poly1305;
- MAC: HMAC;
- KDF: HKDF-SHA;
- ECDH: P256, P384, P521, X25519;
- COSE: COSE_Encrypt0, COSE_Mac0, COSE_Sign1, COSE_KDF_Context.
- CWT: Full support.

Packages

| Package | Import | Description |
| ---------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| cwt | @ldclabs/cose-ts/cwt | exports: class Claims, function withCWTTag, interface ValidatorOpts, class Validator |
| encrypt0 | @ldclabs/cose-ts/encrypt0 | exports: class Encrypt0Message |
| sign1 | @ldclabs/cose-ts/sign1 | exports: class Sign1Message |
| mac0 | @ldclabs/cose-ts/mac0 | exports: class Mac0Message |
| iana | @ldclabs/cose-ts/iana | [IANA: COSE][iana-cose] + [IANA: CWT][iana-cwt] + [IANA: CBOR Tags][iana-cbor-tags] |
| ed25519 | @ldclabs/cose-ts/ed25519 | exports: class Ed25519Key |
| ecdh | @ldclabs/cose-ts/ecdh | exports: class ECDHKey, function getCurve, function getKeySize |
| ecdsa | @ldclabs/cose-ts/ecdsa | exports: class ECDSAKey, function getCrv, function getCurve |
| hkdf | @ldclabs/cose-ts/hkdf | exports: function hkdf256, function hkdf512 |
| hmac | @ldclabs/cose-ts/hmac | exports: class HMACKey |
| aesgcm | @ldclabs/cose-ts/aesgcm | exports: class AesGcmKey | |
| chacha20poly1305 | @ldclabs/cose-ts/chacha20poly1305 | exports: class ChaCha20Poly1305Key |
| kdfcontext | @ldclabs/cose-ts/kdfcontext | exports: class KDFContext, class PartyInfo, class SuppPubInfo |
| key | @ldclabs/cose-ts/key | exports: class Key, interface Encryptor, interface MACer, interface Signer, interface Verifier |
| hash | @ldclabs/cose-ts/hash | exports: hmac, sha256, sha384, sha512, sha3_256, sha3_384, sha3_512, function getHash |
| header | @ldclabs/cose-ts/header | exports: class Header |
| map | @ldclabs/cose-ts/map | exports: class KVMap, type RawMap, type AssertFn, assertText, assertInt, assertIntOrText, assertBytes, assertBool, assertMap |
| tag | @ldclabs/cose-ts/tag | exports: function withTag, function skipTag, and many consts |
| utils | @ldclabs/cose-ts/utils | exports: bytesToHex, hexToBytes, utf8ToBytes, randomBytes, toBytes, concatBytes, bytesToBase64Url, base64ToBytes, compareBytes, decodeCBOR, encodeCBOR |

Examples

$3

``typescript
import { utf8ToBytes, randomBytes, compareBytes } from '@ldclabs/cose-ts/utils'
import { Validator, Claims, withCWTTag } from '@ldclabs/cose-ts/cwt'
import { Ed25519Key } from '@ldclabs/cose-ts/ed25519'
import { Sign1Message } from '@ldclabs/cose-ts/sign1'

// get key
const privKey = Ed25519Key.generate()
// const privKey = Ed25519Key.fromSecret(32_bytes_secret)
const pubKey = privKey.public()
// const pubKey = Ed25519Key.fromPublic(32_bytes_public)

const externalData = utf8ToBytes('@ldclabs/cose-ts') // optional

// signing
const claims = new Claims()
claims.iss = 'ldclabs'
claims.aud = 'cose-ts'
claims.sub = 'tester'
claims.exp = Math.floor(Date.now() / 1000) + 3600
claims.cti = randomBytes(16)

const cwtMsg = new Sign1Message(claims.toBytes())
const cwtData = cwtMsg.toBytes(privKey, externalData)
// const cwtDataWithTag = withCWTTag(cwtData)

// verifying
const cwtMsg2 = Sign1Message.fromBytes(
pubKey,
cwtData, // or cwtDataWithTag
externalData
)
const claims2 = Claims.fromBytes(cwtMsg2.payload)
const validator = new Validator({ expectedIssuer: 'ldclabs' })
validator.validate(claims2)
assert.equal(claims2.iss, claims.iss)
assert.equal(claims2.aud, claims.aud)
assert.equal(claims2.sub, claims.sub)
assert.equal(claims2.exp, claims.exp)
assert.equal(compareBytes(claims2.cti, claims.cti), 0)
``

Security Reviews

Todo.

Reference

1. [RFC9052: CBOR Object Signing and Encryption (COSE)][cose-spec]
2. [RFC8392: CBOR Web Token (CWT)][cwt-spec]
3. [RFC9053: CBOR Object Signing and Encryption (COSE): Initial Algorithms][algorithms-spec]
4. [IANA: CBOR Object Signing and Encryption (COSE)][iana-cose]
5. [IANA: CBOR Web Token (CWT) Claims][iana-cwt]
6. [IANA: Concise Binary Object Representation (CBOR) Tags][iana-cbor-tags]

[cbor]: https://datatracker.ietf.org/doc/html/rfc8949
[cose-spec]: https://datatracker.ietf.org/doc/html/rfc9052
[cwt-spec]: https://datatracker.ietf.org/doc/html/rfc8392
[algorithms-spec]: https://datatracker.ietf.org/doc/html/rfc9053
[iana-cose]: https://www.iana.org/assignments/cose/cose.xhtml
[iana-cwt]: https://www.iana.org/assignments/cwt/cwt.xhtml
[iana-cbor-tags]: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml

License

Copyright © 2022-2025 LDC Labs.

ldclabs/cose-ts is licensed under the MIT License. See LICENSE for the full license text.