add CLI to readme

decentralized-identity · Oct 4, 2024 · 72f0cc6 · 72f0cc6
1 parent fda0adf
commit 72f0cc6
Show file tree

Hide file tree

Showing 4 changed files with 147 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -14,11 +14,10 @@ the following features from the specification with the goal to be feature comple
 | DONE       | Ability to resolve the full history of the DID | Uses a verifiable chain of updates from genesis to deactivation. |
 | DONE       | A self-certifying identifier (SCID) for the DID | Ensures global uniqueness, derived from the initial DIDDoc for portability. |
 | DONE       | DIDDoc updates include a proof signed by the DID Controller(s) | Proof required for updates, authorized by the DID Controller(s). |
-| TODO       | Optional mechanism for publishing “pre-rotation” keys | Helps prevent loss of control if an active private key is compromised. |
+| DONE       | Optional mechanism for publishing "pre-rotation" keys | Helps prevent loss of control if an active private key is compromised. |
 | TODO       | DID URL path handling | Defaults to resolve <did>/path/to/file by DID-to-HTTPS translation, can be overridden. |
 | TODO       | A DID URL path <did>/whois | Automatically returns a Verifiable Presentation, if published by the DID controller. |
 
-
 ## Prerequisites
 
 Install [bun.sh](https://bun.sh/)
@@ -33,20 +32,148 @@ curl -fsSL https://bun.sh/install | bash
 bun install
 ```
 
-## Run all tests
+## Available Commands
+
+The following commands are defined in the `package.json` file:
+
+1. `dev`: Run the resolver in development mode with debugging enabled.
+   ```bash
+   bun run dev
+   ```
+   This command runs: `bun --watch --inspect-wait ./src/resolver.ts`
+
+2. `server`: Run the resolver in watch mode for development.
+   ```bash
+   bun run server
+   ```
+   This command runs: `bun --watch ./src/resolver.ts`
+
+3. `test`: Run all tests.
+   ```bash
+   bun run test
+   ```
+   This command runs: `bun test`
+
+4. `test:watch`: Run tests in watch mode, focusing on witness tests.
+   ```bash
+   bun run test:watch
+   ```
+   This command runs: `bun test --watch witness`
+
+5. `test:bail`: Run tests in watch mode, stopping on the first failure with verbose output.
+   ```bash
+   bun run test:bail
+   ```
+   This command runs: `bun test --watch --bail --verbose`
+
+6. `test:log`: Run tests and save the output to a log file.
+   ```bash
+   bun run test:log
+   ```
+   This command runs: `mkdir -p ./test/logs && LOG_RESOLVES=true bun test &> ./test/logs/test-run.txt`
+
+7. `cli`: Run the CLI tool.
+   ```bash
+   bun run cli [command] [options]
+   ```
+   This command runs: `bun run src/cli.ts --`
+
+## CLI Documentation
 
-```bash
-bun test
 ```
+The CLI is Experimental, buggy and beta software -- use at your own risk!
+```
+
+The trustdidweb-ts package provides a Command Line Interface (CLI) for managing Decentralized Identifiers (DIDs) using the `did:tdw` method.
 
-### Development mode
+
+### Usage
+
+The general syntax for using the CLI is:
 
 ```bash
-bun run test:watch
+bun run cli [command] [options]
 ```
 
-## Run the tests and save a log
+To output the help using the CLI:
 
 ```bash
-bun run test:log
+bun run cli help
 ```
+
+### Commands
+
+1. **Create a DID**
+
+   ```bash
+   bun run cli create [options]
+   ```
+
+   Options:
+   - `--domain [domain]`: (Required) Domain for the DID
+   - `--output [file]`: (Optional) Path to save the DID log
+   - `--portable`: (Optional) Make the DID portable
+   - `--prerotation`: (Optional) Enable pre-rotation
+   - `--witness [witness]`: (Optional) Add a witness (can be used multiple times)
+   - `--witness-threshold [n]`: (Optional) Set witness threshold
+
+   Example:
+   ```bash
+   bun run cli create --domain example.com --portable --witness did:tdw:QmWitness1:example.com --witness did:tdw:QmWitness2...:example.com
+   ```
+
+2. **Resolve a DID**
+
+   ```bash
+   bun run cli resolve --did [did]
+   ```
+
+   Example:
+   ```bash
+   bun run cli resolve --did did:tdw:Qm...:example.com
+   ```
+
+3. **Update a DID**
+
+   ```bash
+   bun run cli update [options]
+   ```
+
+   Options:
+   - `--log [file]`: (Required) Path to the DID log file
+   - `--output [file]`: (Optional) Path to save the updated DID log
+   - `--prerotation`: (Optional) Enable pre-rotation
+   - `--witness [witness]`: (Optional) Add a witness (can be used multiple times)
+   - `--witness-threshold [n]`: (Optional) Set witness threshold
+   - `--service [service]`: (Optional) Add a service (format: type,endpoint)
+   - `--add-vm [type]`: (Optional) Add a verification method
+   - `--also-known-as [alias]`: (Optional) Add an alsoKnownAs alias
+
+   Example:
+   ```bash
+   bun run cli update --log ./did.jsonl --output ./updated-did.jsonl --add-vm keyAgreement --service LinkedDomains,https://example.com
+   ```
+
+4. **Deactivate a DID**
+
+   ```bash
+   bun run cli deactivate [options]
+   ```
+
+   Options:
+   - `--log [file]`: (Required) Path to the DID log file
+   - `--output [file]`: (Optional) Path to save the deactivated DID log
+
+   Example:
+   ```bash
+   bun run cli deactivate --log ./did.jsonl --output ./deactivated-did.jsonl
+   ```
+
+### Additional Notes
+
+- The CLI automatically generates new authentication keys when creating or updating a DID.
+- The `--portable` option in the create command allows the DID to be moved to a different domain later.
+- The `--prerotation` option enables key pre-rotation, which helps prevent loss of control if an active private key is compromised.
+- Witness functionality allows for third-party attestation of DID operations.
+- The CLI saves the DID log to a file when the `--output` option is provided.
+- For the update and deactivate commands, the existing DID log must be provided using the `--log` option.
diff --git a/package.json b/package.json
@@ -9,7 +9,7 @@
     "test:watch": "bun test --watch witness",
     "test:bail": "bun test --watch --bail --verbose",
     "test:log": "mkdir -p ./test/logs && LOG_RESOLVES=true bun test &> ./test/logs/test-run.txt",
-    "cli": "bun run src/cli.ts --"
+    "cli": "bun run src/cli.ts"
   },
   "devDependencies": {
     "bun-bagel": "^1.1.0",

diff --git a/src/cli.ts b/src/cli.ts
@@ -3,7 +3,7 @@ import { createSigner, generateEd25519VerificationMethod } from './cryptography'
 import { getFileUrl, readLogFromDisk, writeLogToDisk, writeVerificationMethodToEnv } from './utils';
 
 const usage = `
-Usage: bun run cli -- [command] [options]
+Usage: bun run cli [command] [options]
 
 Commands:
   create     Create a new DID
@@ -24,10 +24,10 @@ Options:
   --also-known-as [alias]   Add an alsoKnownAs alias (can be used multiple times)
 
 Examples:
-  bun run cli -- create --domain example.com --portable --witness did:example:witness1 --witness did:example:witness2
-  bun run cli -- resolve --did did:tdw:123456:example.com
-  bun run cli -- update --log ./did.jsonl --output ./updated-did.jsonl --add-vm keyAgreement --service LinkedDomains,https://example.com
-  bun run cli -- deactivate --log ./did.jsonl --output ./deactivated-did.jsonl
+  bun run cli create --domain example.com --portable --witness did:example:witness1 --witness did:example:witness2
+  bun run cli resolve --did did:tdw:123456:example.com
+  bun run cli update --log ./did.jsonl --output ./updated-did.jsonl --add-vm keyAgreement --service LinkedDomains,https://example.com
+  bun run cli deactivate --log ./did.jsonl --output ./deactivated-did.jsonl
 `;
 
 async function main() {
@@ -91,9 +91,9 @@ async function handleCreate(args: string[]) {
   });
 
   console.log('Created DID:', did);
-  console.log('DID Document:', JSON.stringify(doc, null, 2));
-  console.log('Meta:', JSON.stringify(meta, null, 2));
-  console.log('DID Log:', JSON.stringify(log, null, 2));
+  // console.log('DID Document:', JSON.stringify(doc, null, 2));
+  // console.log('Meta:', JSON.stringify(meta, null, 2));
+  // console.log('DID Log:', JSON.stringify(log, null, 2));
 
   if (output) {
     writeLogToDisk(output, log);

diff --git a/test/fixtures/not-authorized.log b/test/fixtures/not-authorized.log
@@ -1,2 +1,2 @@
-["1-QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y","2024-10-03T07:48:27Z",{"method":"did:tdw:0.3","scid":"QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y","updateKeys":["z6MkfHBiVHnA94aXL5deHRsZmpoWPXe5hhG23LbLt6BSHoD3"],"portable":false,"prerotation":false,"nextKeyHashes":[],"witnesses":[],"witnessThreshold":0,"deactivated":false},{"value":{"@context":["https://www.w3.org/ns/did/v1","https://w3id.org/security/multikey/v1"],"id":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com","controller":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com","authentication":["did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#t6BSHoD3"],"assertionMethod":["did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#GeX2XAXN"],"verificationMethod":[{"id":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#t6BSHoD3","controller":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com","type":"Multikey","publicKeyMultibase":"z6MkfHBiVHnA94aXL5deHRsZmpoWPXe5hhG23LbLt6BSHoD3"},{"id":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#GeX2XAXN","controller":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com","type":"Multikey","publicKeyMultibase":"z6MknYjAzJn1wj1DepJZs76wVcPPtWcDksXEvmmaGeX2XAXN"}]}},[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","verificationMethod":"did:key:z6MkfHBiVHnA94aXL5deHRsZmpoWPXe5hhG23LbLt6BSHoD3","created":"2024-10-03T07:48:27Z","proofPurpose":"authentication","challenge":"1-QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y","proofValue":"z5aj3aN9gc6EgjhfyLECY79PyCdr58Vz45ZhhzAvf24eTjYi9AkwvuVGT4pjEAr8Md4VcAJweMmEVEUZAjnWCYULD"}]]
-["2-QmdNPRMQjFwozccAZrLCd8LFy4F99rpTQ2XmuuReE4xnXx","2024-10-03T07:48:27Z",{"witnesses":[],"witnessThreshold":0},{"patch":[{"op":"replace","path":"/verificationMethod/1/publicKeyMultibase","value":"z6MkpeqiSPWWykNF1mZLHuyC7kwryGqhy5ci6KTJcn13n6qz"},{"op":"replace","path":"/verificationMethod/1/id","value":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#cn13n6qz"},{"op":"replace","path":"/verificationMethod/0/publicKeyMultibase","value":"z6MkkhwFGyJM9GaXcyop3iCPzYqTmrWnQksTF7MKSUGLnsNK"},{"op":"replace","path":"/verificationMethod/0/id","value":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#SUGLnsNK"},{"op":"replace","path":"/assertionMethod/0","value":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#cn13n6qz"},{"op":"replace","path":"/authentication/0","value":"did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com#SUGLnsNK"},{"op":"replace","path":"/controller","value":["did:tdw:QmNvB56V4e8AtoX1CWwSfb5y4ZJaJj5VRJV6nkBnPXGM7y:example.com"]}]},[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","verificationMethod":"did:key:z6MknYjAzJn1wj1DepJZs76wVcPPtWcDksXEvmmaGeX2XAXN","created":"2024-10-03T07:48:27Z","proofPurpose":"authentication","challenge":"2-QmdNPRMQjFwozccAZrLCd8LFy4F99rpTQ2XmuuReE4xnXx","proofValue":"z5PgHFvTK2BaWGkoFjgT2fPrbvtUaLgpTfFHiiRh9Dk5JHQ7vk88KdxBYQk44LEhGWrnkXKNFUyrXdZRDPsToJhKE"}]]
+["1-QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5","2024-10-04T06:34:25Z",{"method":"did:tdw:0.3","scid":"QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5","updateKeys":["z6MkpM4hdAMAFSf4oAZ3r9Pz5cSzZAEb9AxKbWNx7PEdLthC"],"portable":false,"prerotation":false,"nextKeyHashes":[],"witnesses":[],"witnessThreshold":0,"deactivated":false},{"value":{"@context":["https://www.w3.org/ns/did/v1","https://w3id.org/security/multikey/v1"],"id":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com","controller":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com","authentication":["did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#7PEdLthC"],"assertionMethod":["did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#ko8yVqZf"],"verificationMethod":[{"id":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#7PEdLthC","controller":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com","type":"Multikey","publicKeyMultibase":"z6MkpM4hdAMAFSf4oAZ3r9Pz5cSzZAEb9AxKbWNx7PEdLthC"},{"id":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#ko8yVqZf","controller":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com","type":"Multikey","publicKeyMultibase":"z6MktbW9Q3SRRZH9KGgi992FAP3zsHbRNRVghua1ko8yVqZf"}]}},[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","verificationMethod":"did:key:z6MkpM4hdAMAFSf4oAZ3r9Pz5cSzZAEb9AxKbWNx7PEdLthC","created":"2024-10-04T06:34:25Z","proofPurpose":"authentication","challenge":"1-QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5","proofValue":"z2dUb12ES25JLmJ6STDD6LKvwS3Ro8KPHp7L1oixyitcJy8CwqK4NjEWimMmGKGz7vYz5Ryod9JL34voVXsMnFNzk"}]]
+["2-Qma6VjkU24hF7mvnjEWc1eycwxnD3PQzrGHrm6que5wcTY","2024-10-04T06:34:25Z",{"witnesses":[],"witnessThreshold":0},{"patch":[{"op":"replace","path":"/verificationMethod/1/publicKeyMultibase","value":"z6MkoiGV33WxKg5eGAB92eekgropaE98PUqRW92k2GfKGfca"},{"op":"replace","path":"/verificationMethod/1/id","value":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#2GfKGfca"},{"op":"replace","path":"/verificationMethod/0/publicKeyMultibase","value":"z6MksuN1RkD78bPEnbc8UdFAetgKjKHJyVu6NypGfJypQe4T"},{"op":"replace","path":"/verificationMethod/0/id","value":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#fJypQe4T"},{"op":"replace","path":"/assertionMethod/0","value":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#2GfKGfca"},{"op":"replace","path":"/authentication/0","value":"did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com#fJypQe4T"},{"op":"replace","path":"/controller","value":["did:tdw:QmdK2cazkgA3Qxr3oUdZzZyJQ9tuqXrcELSbqbff2wgJU5:example.com"]}]},[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","verificationMethod":"did:key:z6MktbW9Q3SRRZH9KGgi992FAP3zsHbRNRVghua1ko8yVqZf","created":"2024-10-04T06:34:25Z","proofPurpose":"authentication","challenge":"2-Qma6VjkU24hF7mvnjEWc1eycwxnD3PQzrGHrm6que5wcTY","proofValue":"z4r9YokjSkvKAnt9DgMDN8CwvKAgYG1G5tHcydJdFGFDkpsdJio2hTGpgPHvLstBjAFeFH5x24jviuBD4u7AHxKu2"}]]