WebKMS Client (@interop/webkms-client)

A TypeScript/JavaScript WebKMS client library for Node.js, browser and React Native.

Background

Security

TBD

Install

Browsers and Node.js 24+ are supported.
Web Crypto API required. Older browsers must use a polyfill.

NPM

To install via NPM:

npm install @interop/webkms-client

Development

To install locally (for development):

git clone https://github.com/interop-alliance/webkms-client.git
cd webkms-client
pnpm install

Testing

pnpm test            # lint, build, Node (vitest) and browser (Playwright) tests
pnpm run test:node   # Node tests only
pnpm run test:browser  # browser tests only (run `pnpm exec playwright install chromium` first)

Usage

Modules

webkms: WebKMS client for Javascript.

Functions

webkms:generateKey(options) ⇒ Promise.<object>: Generates a new cryptographic key in the keystore.
webkms:getKeyDescription(options) ⇒ Promise.<object>: Gets the key description for the given key ID.
webkms:listKeys(options) ⇒ Promise.<Array>: Lists the public key descriptions in a keystore (a fork extension beyond upstream webkms-switch).
webkms:revokeCapability(options) ⇒ Promise.<object>: Store a capability revocation.
webkms:wrapKey(options) ⇒ Promise.<Uint8Array>: Wraps a cryptographic key using a key encryption key (KEK).
webkms:unwrapKey(options) ⇒ Promise.<(Uint8Array|null)>: Unwraps a cryptographic key using a key encryption key (KEK).
webkms:sign(options) ⇒ Promise.<Uint8Array>: Signs some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.
webkms:verify(options) ⇒ Promise.<boolean>: Verifies some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.
webkms:deriveSecret(options) ⇒ Promise.<Uint8Array>: Derives a shared secret via the given peer public key, typically for use as one parameter for computing a shared key. It should not be used as a shared key itself, but rather input into a key derivation function (KDF) to produce a shared key.
webkms:createKeystore(options) ⇒ Promise.<object>: Creates a new keystore using the given configuration.
webkms:getKeystore(options) ⇒ Promise.<object>: Gets the configuration for a keystore by its ID.

webkms

WebKMS client for Javascript.

webkms
- .KmsClient
  - new exports.KmsClient(options)

webkms.KmsClient

A WebKMS Client used to interface with a KMS.

Kind: instance class of webkms

new exports.KmsClient(options)

Creates a new KmsClient.

Returns: KmsClient - The new instance.

Param	Type	Description
options	`object`	The options to use.
[options.keystore]	`string`	The ID of the keystore that must be a URL that refers to the keystore's root storage location; if not given, then a separate capability must be given to each method called on the client instance.
[options.httpsAgent]	`object`	An optional node.js `https.Agent` instance to use when making requests.

webkms:generateKey(options) ⇒ `Promise.<object>`

Generates a new cryptographic key in the keystore.

Kind: global function Returns: Promise.<object> - The key description for the key.

Param	Type	Description
options	`object`	The options to use.
options.kmsModule	`string`	The KMS module to use.
options.type	`string`	The key type (e.g. 'AesKeyWrappingKey2019').
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:getKeyDescription(options) ⇒ `Promise.<object>`

Gets the key description for the given key ID.

Kind: global function Returns: Promise.<object> - The key description.

Param	Type	Description
options	`object`	The options to use.
[options.keyId]	`string`	The ID of the key.
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:listKeys(options) ⇒ `Promise.<Array>`

Lists the public key descriptions in a keystore (a fork extension beyond upstream webkms-switch). Follows the server's next cursor to exhaustion and returns every key's description, sorted by the server's local id. Never returns secret material. Each entry additionally carries keyUrl, the key's canonical invocation URL (<keystoreId>/keys/<localId>) -- the handle a publicAlias / publicAliasTemplate override erases from id, and the value to record as a key's kmsId when recovering lost key references (ListedKeyDescription in types.ts).

KeystoreAgent.listKeys() is a convenience wrapper over this method that uses the agent's keystore and signer.

Kind: global function Returns: Promise.<Array> - The keystore's public key descriptions.

Param	Type	Description
options	`object`	The options to use.
[options.capability]	`string`	The authorization capability to authorize the invocation; the keystore's root zcap is used if not provided. A delegated capability's `invocationTarget` must be the `<keystoreId>/keys` collection URL.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.
[options.maxPages]	`number`	Safety cap on pages followed (default `1000`), to bound a server that never terminates the cursor.

webkms:revokeCapability(options) ⇒ `Promise.<object>`

Store a capability revocation.

Kind: global function Returns: Promise.<object> - Resolves once the operation completes.

Param	Type	Description
options	`object`	The options to use.
options.capabilityToRevoke	`object`	The capability to revoke.
[options.capability]	`string`	The zcap authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:wrapKey(options) ⇒ `Promise.<Uint8Array>`

Wraps a cryptographic key using a key encryption key (KEK).

Kind: global function Returns: Promise.<Uint8Array> - The wrapped key bytes.

Param	Type	Description
options	`object`	The options to use.
options.kekId	`string`	The ID of the wrapping key to use.
options.unwrappedKey	`Uint8Array`	The unwrapped key material as a Uint8Array.
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:unwrapKey(options) ⇒ `Promise.<(Uint8Array|null)>`

Unwraps a cryptographic key using a key encryption key (KEK).

Kind: global function Returns: Promise.<(Uint8Array|null)> - Resolves to the unwrapped key material or null if the unwrapping failed because the key did not match.

Param	Type	Description
options	`object`	The options to use.
options.kekId	`string`	The ID of the unwrapping key to use.
options.wrappedKey	`string`	The wrapped key material as a base64url-encoded string.
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:sign(options) ⇒ `Promise.<Uint8Array>`

Signs some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

Kind: global function Returns: Promise.<Uint8Array> - The signature.

Param	Type	Description
options	`object`	The options to use.
options.keyId	`string`	The ID of the signing key to use.
options.data	`Uint8Array`	The data to sign as a Uint8Array.
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:verify(options) ⇒ `Promise.<boolean>`

Verifies some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

Kind: global function Returns: Promise.<boolean> - true if verified, false if not.

Param	Type	Description
options	`object`	The options to use.
options.keyId	`string`	The ID of the signing key to use.
options.data	`Uint8Array`	The data to verify as a Uint8Array.
options.signature	`string`	The base64url-encoded signature to verify.
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:deriveSecret(options) ⇒ `Promise.<Uint8Array>`

Derives a shared secret via the given peer public key, typically for use as one parameter for computing a shared key. It should not be used as a shared key itself, but rather input into a key derivation function (KDF) to produce a shared key.

Kind: global function Returns: Promise.<Uint8Array> - The shared secret bytes.

Param	Type	Description
options	`object`	The options to use.
options.keyId	`string`	The ID of the key agreement key to use.
options.publicKey	`object`	The public key to compute the shared secret against; the public key type must match the key agreement key's type.
[options.capability]	`string`	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	`object`	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:createKeystore(options) ⇒ `Promise.<object>`

Creates a new keystore using the given configuration.

Kind: global function Returns: Promise.<object> - Resolves to the configuration for the newly created keystore.

Param	Type	Description
options	`object`	The options to use.
options.url	`string`	The url to post the configuration to.
options.config	`string`	The keystore's configuration.
[options.httpsAgent]	`object`	An optional node.js `https.Agent` instance to use when making requests.

webkms:getKeystore(options) ⇒ `Promise.<object>`

Gets the configuration for a keystore by its ID.

Kind: global function Returns: Promise.<object> - Resolves to the configuration for the keystore.

Param	Type	Description
options	`object`	The options to use.
options.id	`string`	The keystore's ID.
[options.httpsAgent]	`object`	An optional node.js `https.Agent` instance to use when making requests.

webkms:findKeystore(options) ⇒ `Promise.<object>`

Finds the configuration for a keystore by its controller and reference ID.

Kind: global function Returns: Promise.<object> - Resolves to the configuration for the keystore.

Param	Type	Description
options	`object`	The options to use.
[options.url]	`string`	The url to query.
options.controller	`string`	The keystore's controller.
[options.httpsAgent]	`object`	An optional node.js `https.Agent` instance to use when making requests.

Contribute

Please follow the existing code style.

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
prettier.config.js		prettier.config.js
tsconfig.dev.json		tsconfig.dev.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Navigation Menu

Uh oh!

Repository files navigation

WebKMS Client (@interop/webkms-client)

Table of Contents

Background

Security

Install

NPM

Development

Testing

Usage

Modules

Functions

webkms

webkms.KmsClient

new exports.KmsClient(options)

webkms:generateKey(options) ⇒ `Promise.<object>`

webkms:getKeyDescription(options) ⇒ `Promise.<object>`

webkms:listKeys(options) ⇒ `Promise.<Array>`

webkms:revokeCapability(options) ⇒ `Promise.<object>`

webkms:wrapKey(options) ⇒ `Promise.<Uint8Array>`

webkms:unwrapKey(options) ⇒ `Promise.<(Uint8Array|null)>`

webkms:sign(options) ⇒ `Promise.<Uint8Array>`

webkms:verify(options) ⇒ `Promise.<boolean>`

webkms:deriveSecret(options) ⇒ `Promise.<Uint8Array>`

webkms:createKeystore(options) ⇒ `Promise.<object>`

webkms:getKeystore(options) ⇒ `Promise.<object>`

webkms:findKeystore(options) ⇒ `Promise.<object>`

Contribute

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

WebKMS Client (@interop/webkms-client)

Table of Contents

Background

Security

Install

NPM

Development

Testing

Usage

Modules

Functions

webkms

webkms.KmsClient

new exports.KmsClient(options)

webkms:generateKey(options) ⇒ Promise.<object>

webkms:getKeyDescription(options) ⇒ Promise.<object>

webkms:listKeys(options) ⇒ Promise.<Array>

webkms:revokeCapability(options) ⇒ Promise.<object>

webkms:wrapKey(options) ⇒ Promise.<Uint8Array>

webkms:unwrapKey(options) ⇒ Promise.<(Uint8Array|null)>

webkms:sign(options) ⇒ Promise.<Uint8Array>

webkms:verify(options) ⇒ Promise.<boolean>

webkms:deriveSecret(options) ⇒ Promise.<Uint8Array>

webkms:createKeystore(options) ⇒ Promise.<object>

webkms:getKeystore(options) ⇒ Promise.<object>

webkms:findKeystore(options) ⇒ Promise.<object>

Contribute

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

webkms:generateKey(options) ⇒ `Promise.<object>`

webkms:getKeyDescription(options) ⇒ `Promise.<object>`

webkms:listKeys(options) ⇒ `Promise.<Array>`

webkms:revokeCapability(options) ⇒ `Promise.<object>`

webkms:wrapKey(options) ⇒ `Promise.<Uint8Array>`

webkms:unwrapKey(options) ⇒ `Promise.<(Uint8Array|null)>`

webkms:sign(options) ⇒ `Promise.<Uint8Array>`

webkms:verify(options) ⇒ `Promise.<boolean>`

webkms:deriveSecret(options) ⇒ `Promise.<Uint8Array>`

webkms:createKeystore(options) ⇒ `Promise.<object>`

webkms:getKeystore(options) ⇒ `Promise.<object>`

webkms:findKeystore(options) ⇒ `Promise.<object>`