Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/digitalbazaar/did-cli
A client for managing Decentralized Identifiers
https://github.com/digitalbazaar/did-cli
Last synced: 2 months ago
JSON representation
A client for managing Decentralized Identifiers
- Host: GitHub
- URL: https://github.com/digitalbazaar/did-cli
- Owner: digitalbazaar
- License: other
- Created: 2017-09-24T16:11:44.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2022-03-30T19:34:30.000Z (almost 3 years ago)
- Last Synced: 2024-09-19T01:12:06.384Z (4 months ago)
- Language: JavaScript
- Size: 259 KB
- Stars: 43
- Watchers: 16
- Forks: 10
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - digitalbazaar/did-cli - A client for managing Decentralized Identifiers (JavaScript)
README
# Decentralized Identifier client CLI _(did-cli)_
> A command-line client for managing Decentralized Identifiers.
* [Quickstart](#quickstart)
* [Installation](#installation)
* [Usage](#usage)
* [General](#general)
* [Generate a DID](#generate-a-did)
* [Register on a Ledger](#register-on-a-ledger)
* [DID Information](#did-information)
* [Notes](#notes)
* [Key Management](#key-management)
* [Examples](#examples)
* [Roadmap](#roadmap)
* [Support](#support)## Quickstart
The current client supports the creation of Testnet DIDs on the Veres One
ledger as well as the retrieval of those DIDs from the Testnet. You can try the
tool out by doing the following commands on a system that has node.js installed:npm install did-cli
cd node_modules/did-cli
./did generate -rTo retrieve the freshly generated DID:
./did info
By default, keys and DID Documents will be stored in `~/.dids///`,
see [Setting Up Storage](STORAGE.md) for more details.## Installation
### Requirements
* Linux or Mac OS X
* Node.js >= 8.6.x
* npm >= 3.x### Install
Install in a development directory:
npm install did-cli
./node_modules/.bin/did ...Install globally:
npm install -g did-cli
did ...Run from npx:
npx did-cli ...
### Developing
To download the source and install the client:
git clone https://github.com/digitalbazaar/did-cli.git
cd did-cli
npm install
./did ...## Usage
### General
The `did` command has many commands and options. Help is available with the
`--help/-h` command line option:did -h
did COMMAND -hCommands can be more verbose with one ore more `--verbose/-v` options, or
quieted more than the default with `--quiet/-q`:did COMMAND -v ...
did COMMAND -vv ...
did COMMAND -q ...Copies of registered DIDs, keys, and metadata are all stored in your
`$HOME/.dids/` directory.Remote commands operate on a ledger. Various ledgers may be available. They
can be selected with the `--ledger/-l` option which defaults to `veres`.did COMMAND -l LEDGER ...
Remote ledger commands also have a "live", "test", or "dev" mode selected with
`--mode/-m` which defaults to `test`:did COMMAND -m MODE ...
The combination of ledger and mode options will select the default hostnames to
connect to. Specific hostnames can be selected with `--hostname/-H`:did COMMAND -l example -m test -H host1.example.com ...
### Generate a DID
A DID is generated locally with the `generate` command:
did generate
Other options:
* `--passphrase/-p PASSPHRASE`: set a key passphrase
* `--type/-t TYPE`: set key type (ex: `ed25519` or `rsa`)
* `--name NAME`: set a private name [note](#notes)
* `--description DESCRIPTION`: set a private description [note](#notes)
* `--register/-r`: register on a ledger### Register on a Ledger
By default `generate` will only store a DID locally. If you want to also
immediately register it to the default Veres One testnet ledger:did generate -r
You can register local DIDs to a ledger with the `register` command:
did register DID
Some ledgers may require DID authorization (this topic is outside of the scope
of this tool). You can specify an authorization DID key with `--auth/-a`:did register DID -a AUTHDID
Some ledgers may require proof-of-work to accept a DID request. Others may
allow "accelerators" to be used. These are specified with `--accelerator/-A`
and require an authorization DID:did register DID -a AUTHDID -A ACCELERATORHOSTNAME
### DID Information
Pending (created but not registered) and registered DIDs can be listed with the
`list` command:did list
Information on a DID can be found with the `info` command:
did info DID
### Notes
It can be useful to store **private** local notes about DIDs which are
otherwise somewhat opaque identifiers. The `notes` command adds this ability
with simple key/value pairs.All notes for all DIDs can be shown with:
did notes
Notes for specific DID can be shown:
did notes DID
Various notes operations are available:
* `--clear`: remove all notes
* `--add KEY VALUE`: append VALUE to an array for KEY
* `--remove`: remove VALUE from array for KEY
* `--get KEY`: get KEY value
* `--set KEY VALUE`: set single VALUE for KEY
* `--delete`: delete all values for KEY
* `--find KEY VALUE`: find DIDs with VALUE set for KEYIf a DID is not specified the commands will operate on *all* DIDs. As this can
be dangerous, any operation with operates on many DIDs must use the `--all`
option.did notes --delete old-property --all
You can choose any KEY values you wish, although simple strings will be easiest
to use. The `generate` and `register` commands have an "auto" feature to write
some notes. The "name" note is useful to assign simple names to DIDs. The
"ledger" note is useful to keep track of where DIDs have been sent.$ did notes did:example:test:1234 --set name shortname
$ did notes did:example:test:1234 --get name
did:example:test:1234 name
$ did notes --find name shortname
did:example:test:1234$ did notes did:example:test:A --add url https://example.com/
$ did notes did:example:test:B --add url https://example.com/
$ did notes did:example:test:C --add url https://example.org/
$ did notes --find url https://example.com/
did:example:test:A
did:example:test:B
$ did notes --get url
did:example:test:A url https://example.com/
did:example:test:B url https://example.com/
did:example:test:C url https://example.org/The notes data is stored in the `config.jsonld` file in your local DID dir. It
can be freely edited as needed. **Warning**: This file is *not* currently safe
to write to concurrently!### Key Management
A DID has a number of application suite parameters that can store keys. Keys
are managed with the with the `authn-*` commands. To inspect the keys use
`info`:# show the DID JSON including keys
did info did:example:1234# show more readable summary
did info did:example:1234 -f human# show summary with public keys
did info did:example:1234 -f human --public-key# show local summary with private keys
did info did:example:1234 -f human -L local --private-keyKey material can be added with `ed25519-key-add`. A unique cryptonym key id
will be generated. Note that the updates will be automatically
registered on the ledger unless `--no-register` is provided:# add a public and private key
did ed25519-key-add did:example:1234 -p authentication --pub PUBLICKEYINFO \
--pvt PRIVATEKEYINFO## Examples
Basic generate and check DID is on ledger:
# generate and register on ledger
did generate -r # generate and register on ledger
# wait a few moments
# ...
did info DIDMore extreme checking if ledger has details of multiple hosts. As of this
writing, Veres One has multiple testnet hosts hardcoded, but you can specify
your own with multiple `-H` options:# generate and register on ledger
did generate -r # generate and register to ledger
did info DIDDepending on the ledger, you may be able to see consensus happening after a
generate:# start a retry loop, see info --help for other options
did info DID -f found -L all --retryUse an accelerator to register a DID faster. This assumes you have registered
`did:ex:my-did` at the accelerator:did generate -r -a did:ex:test:my-did -A accelerator.example.com
Split creation and later register to multiple ledgers (because you are an
expert and have solid reasons for doing this):# generate with a private name, do not register
did generate --name my-did
# ... time passes
# ...
# ... grrr, I forgot the long DID name
did list
... many many DIDs ...
# hmm... lots of random DID names, which one is it?
did notes --get name
... many other DIDs with names ...
did:example:test:1234 name my-did
# ah! there it is!
# register on a ledger
did register did:example:test:1234
# i'd like to use on other ledgers too
did register -H ledger2.example.com did:example:test:1234Show which DIDs have a note about being on a ledger:
did notes --get ledger
Tips and tricks:
# reload DIDs on a dev ledger after a wipe
did notes --find ledger veres:dev | xargs -I {} did register -m dev {}
# alternative
for d in `did notes --find ledger veres:dev`; do did register -m dev $did; done## Roadmap
There are plans to support the following other commands and features:
* Rotating authentication credentials
* Adding and removing authorization capability descriptions
* Adding and removing service descriptions
* Checking the validity of a DID (deep blockchain check)## Support
Bugs, suggestions, requests, and code issues:
* https://github.com/digitalbazaar/did-cli/issues
Commercial support is available upon request from [Digital Bazaar][]:
[Digital Bazaar]: https://digitalbazaar.com/