WASM based javascript wrapper for DIDComm
npm install didcomm-node

Basic DIDComm v2 support for modern browsers and NodeJS.
This package is written in Rust using didcomm>) crate. It compiles
to wasm32 and exposes Javascript/Typescript API with wasm-bindgen help.
Also wasmp-pack helps in packaging and publishing.
To use didcomm install it with npm
``sh
npm install didcomm --save # If you plan use webpack or other bundler
npm install didcomm-node --save # If you plan use it without bundlers in NodeJS
`
`sh`
WASM_TARGET=nodejs make # builds NodeJS package in pkg directory
cd ./demo
npm install
npm run start
- This library requires wasm32 compatible environment (modern browsers and recent NodeJS are supported).SecretsResolver
- In order to use the library, and DIDResolver interfaces must be implemented on the application level.ExampleDIDResolver
Demo application provides 2 simple implementations ExampleSecretsResolver
and that allows resolve locally known DID docs and secrets for tests/demo purposes.SecretsResolver
- Verification materials are expected in JWK, Base58 and Multibase (internally Base58 only) formats.
- In Base58 and Multibase formats, keys using only X25519 and Ed25519 curves are supported.
- For private keys in Base58 and Multibase formats, the verification material value contains both private and public parts (concatenated bytes).
- In Multibase format, bytes of the verification material value is prefixed with the corresponding Multicodec code.
- Key IDs (kids) used in must match the corresponding key IDs from DID Doc verification methods.did#key-id
- Key IDs (kids) in DID Doc verification methods and secrets must be a full DID Fragment, that is .fromPrior
- Verification methods referencing another DID Document are not supported (see Referring to Verification Methods).
- The following curves and algorithms are supported:
- Encryption:
- Curves: X25519, P-256
- Content encryption algorithms:
- XC20P (to be used with ECDH-ES only, default for anoncrypt),
- A256GCM (to be used with ECDH-ES only),
- A256CBC-HS512 (default for authcrypt)
- Key wrapping algorithms: ECDH-ES+A256KW, ECDH-1PU+A256KW
- Signing:
- Curves: Ed25519, Secp256k1, P-256
- Algorithms: EdDSA (with crv=Ed25519), ES256, ES256K
- Forward protocol is implemented and used by default.
- DID rotation ( field) is supported.
- DIDComm has been implemented under the following Assumptions
A general usage of the API is the following:
- Sender Side:
- Build a Message (plaintext, payload).Message.pack_encrypted
- Convert a message to a DIDComm Message for further transporting by calling one of the following:
- to build an Encrypted DIDComm messageMessage.pack_signed
- to build a Signed DIDComm messageMessage.pack_plaintext
- to build a Plaintext DIDComm messageMessage.unpack
- Receiver side:
- Call on receiver side that will decrypt the message, verify signature if neededMessage
and return a for further processing on the application level.
This is the most common DIDComm message to be used in most of the applications.
A DIDComm encrypted message is an encrypted JWM (JSON Web Messages) that
- hides its content from all but authorized recipients
- (optionally) discloses and proves the sender to only those recipients
- provides message integrity guarantees
It is important in privacy-preserving routing. It is what normally moves over network transports in DIDComm
applications, and is the safest format for storing DIDComm data at rest.
See Message::pack_encrypted documentation for more details.
Authentication encryption example (most common case):
`typescript
// --- Build message from ALICE to BOB ---
const msg = new Message({
id: "1234567890",
typ: "application/didcomm-plain+json",
type: "http://example.com/protocols/lets_do_lunch/1.0/proposal",
from: "did:example:alice",
to: ["did:example:bob"],
created_time: 1516269022,
expires_time: 1516385931,
body: { messagespecificattribute: "and its value" },
});
// --- Packing encrypted and authenticated message ---
let didResolver = new ExampleDIDResolver([ALICE_DID_DOC, BOB_DID_DOC]);
let secretsResolver = new ExampleSecretsResolver(ALICE_SECRETS);
const [encryptedMsg, encryptMetadata] = await msg.pack_encrypted(
BOB_DID,
ALICE_DID,
null,
didResolver,
secretsResolver,
{
forward: false, // Forward wrapping is unsupported in current version
}
);
console.log("Encryption metadata is\n", encryptMetadata);
// --- Send message ---
console.log("Sending message\n", encryptedMsg);
// --- Unpacking message ---
didResolver = new ExampleDIDResolver([ALICE_DID_DOC, BOB_DID_DOC]);
secretsResolver = new ExampleSecretsResolver(BOB_SECRETS);
const [unpackedMsg, unpackMetadata] = await Message.unpack(
encrypted_msg,
didResolver,
secretsResolver,
{}
);
console.log("Receved message is\n", unpackedMsg.as_value());
console.log("Receved message unpack metadata is\n", unpackMetadata);
`
Anonymous encryption example:
`typescript`
let [encryptedMsg, encryptMetadata] = await msg.pack_encrypted(
BOB_DID,
null, // Keep sender as None here
null,
didResolver,
secretsResolver,
{
forward: false, // Forward wrapping is unsupported in current version
}
);
Encryption with non-repudiation example:
`typescript`
let [encrypted_msg, encrypt_metadata] = await msg.pack_encrypted(
BOB_DID,
ALICE_DID,
ALICE_DID, // Provide information about signer here
did_resolver,
secrets_resolver,
{
forward: false, // Forward wrapping is unsupported in current version
}
);
Signed messages are only necessary when
- the origin of plaintext must be provable to third parties
- or the sender can’t be proven to the recipient by authenticated encryption because the recipient is not known in advance (e.g., in a
broadcast scenario).
Adding a signature when one is not needed can degrade rather than enhance security because it
relinquishes the sender’s ability to speak off the record.
See Message.pack_signed documentation for more details.
`typescript`
let [signed, metadata] = await msg.pack_signed(
ALICE_DID,
didResolver,
secretsResolver
);
A DIDComm message in its plaintext form that
- is not packaged into any protective envelope
- lacks confidentiality and integrity guarantees
- repudiable
They are therefore not normally transported across security boundaries.
`typescript`
let plaintext = msg.pack_plaintext(didResolver).expect("Unable pack_plaintext");
Install wasm-pack from https://rustwasm.github.io/wasm-pack/installer/ and then
`bash`
make # Will output modules best-suited to be bundled with webpack
WASM_TARGET=nodejs make # Will output modules that can be directly consumed by NodeJS
WASM_TARGET=web make # Will output modules that can be directly consumed in browser without bundler usage
`bash`
wasm-pack build # Will output modules best-suited to be bundled with webpack
wasm-pack build --target=nodejs # Will output modules that can be directly consumed by NodeJS
wasm-pack build --target=web # Will output modules that can be directly consumed in browser without bundler usage
`bash`
WASM_TARGET=nodejs make
cd ./tests-js
npm install
npm test
`bash`
WASM_TARGET=nodejs make
cd ./tests-js
npm install
npm run test-puppeteer
_Note tests will be executed with jest+puppeteer in Chromium installed inside node_modules._
``
wasm-pack publish
- wasm-bindgen for communicating
between WebAssembly and JavaScript.
- console_error_panic_hook
for logging panic messages to the developer console.
- wee_alloc, an allocator optimized
for small code size.
PRs are welcome!
The following CI checks are run against every PR:
- No warnings from cargo check --all-targetsnpm run check
- No warnings from in tests-js directorynpm run check
- No warnings from in demo directorynpm test
- All tests must pass with in tests-js directorycargo fmt --all
- Rust code must be formatted by npx prettier --write .`
- Javascript/Typescript code must be formatted by prettier