Merge branch 'main' into credentials-refresh

.github/workflows/scorecard.yml

@@ -0,0 +1,72 @@
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '27 22 * * 4'
+  push:
+    branches: [ "main" ]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # Uncomment the permissions below if installing in a private repository.
+      # contents: read
+      # actions: read
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@e38b1902ae4f44df626f11ba0734b14fb91f8f86 # v2.1.2
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecard on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
+          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8 # v3.1.0
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard.
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@17573ee1cc1b9d061760f3a006fc4aac4f944fd5 # v2.2.4
+        with:
+          sarif_file: results.sarif

.github/workflows/tests-ci.yml

@@ -107,3 +107,36 @@ jobs:
         run: npm run test:browser --ws -- --color
         env:
           TEST_DWN_URL: http://localhost:3000
+
+  tbdocs-reporter:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install latest npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build all workspace packages
+        run: npm run build
+
+      - name: TBDocs Reporter
+        id: tbdocs-reporter-protocol
+        uses: TBD54566975/tbdocs@main
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          report_changed_scope_only: false
+          fail_on_error: false
+          entry_points: |
+            - file: packages/api/src/index.ts
+              docsReporter: api-extractor
+              docsGenerator: typedoc-markdown

CODE_OF_CONDUCT.md

@@ -118,19 +118,10 @@ community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available on [the contributor Convenant website](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
 
 Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/inclusion/blob/master/code-of-conduct-enforcement/consequence-ladder.md).
 
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+For answers to common questions about this code of conduct, see the [FAQs on the Contributor Covenant website](https://www.contributor-covenant.org/faq). Translations are available on the [translations page](https://www.contributor-covenant.org/translations).

CONTRIBUTING.md

@@ -26,7 +26,7 @@ As we work our way towards a beta release and beyond, we'll be creating more foc
 
 These issues are excellent canditates for contribution and we'd be thrilled to get all the help we can get! You can
 take a look at all of the Issues that match the labels above
-[here](https://github.com/TBD54566975/web5-js/issues?q=is%3Aopen+label%3A%22help+wanted%22%2C%22good+first+issue%22%2C%22documentation%22%2C%22bug%22+).
+[on the Issues tab](https://github.com/TBD54566975/web5-js/issues?q=is%3Aopen+label%3A%22help+wanted%22%2C%22good+first+issue%22%2C%22documentation%22%2C%22bug%22+).
 
 We suggest the following process when picking up one of these issues:
 
@@ -40,7 +40,7 @@ We suggest the following process when picking up one of these issues:
 
 ### Discussions
 
-Design discussions and proposals take place on our Web5 [discord](https://discord.com/channels/937858703112155166/969272658501976117) channel.
+Design discussions and proposals take place on our Web5 [Discord](https://discord.com/channels/937858703112155166/969272658501976117) channel.
 
 We advocate an asynchronous, written debate model - so write up your thoughts and invite the community to join in!
 
@@ -94,7 +94,7 @@ to your valuable work:
   rebase atop the upstream `main` branch. This will limit the potential for merge
   conflicts during review, and helps keep the audit trail clean. A good writeup for
   how this is done is
-  [here](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec), and if you're
+ [this beginner's guide to squashing commits](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
   having trouble - feel free to ask a member or the community for help or leave the commits as-is, and flag that you'd like
   rebasing assistance in your PR! We're here to support you.
 - Open a PR in the project to bring in the code from your feature branch.

README.md

@@ -5,10 +5,11 @@
 [![Coverage](https://img.shields.io/codecov/c/gh/TBD54566975/web5-js/main?logo=codecov&logoColor=FFFFFF&style=flat-square&token=YI87CKF1LI)](https://codecov.io/github/TBD54566975/web5-js)
 [![License](https://img.shields.io/npm/l/@web5/api.svg?style=flat-square&color=24f2ff&logo=apache&logoColor=FFFFFF&santize=true)](https://github.com/TBD54566975/web5-js/blob/main/LICENSE)
 [![Chat](https://img.shields.io/badge/chat-on%20discord-7289da.svg?style=flat-square&color=9a1aff&logo=discord&logoColor=FFFFFF&sanitize=true)](https://discord.com/channels/937858703112155166/969272658501976117)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/TBD54566975/web5-js/badge)](https://securityscorecards.dev/viewer/?uri=github.com/TBD54566975/web5-js)
 
 Making developing with Web5 components at least 5 times easier to work with.
 
-> ⚠️ WEB5 JS SDK IS CURRENTLY IN TECH PREVIEW ⚠️
+> :warning: WEB5 JS SDK IS CURRENTLY IN TECH PREVIEW :warning:
 
 The SDK is currently still under active development, but having entered the Tech Preview phase there is now a drive to avoid unnecessary changes unless backwards compatibility is provided. Additional functionality will be added in the lead up to 1.0 final, and modifications will be made to address issues and community feedback.
 
@@ -45,7 +46,7 @@ possible.
 
 Interested in contributing instantly? You can make your updates directly without cloning in the running CodeSandbox environment.
 
-[![Edit in CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/github/TBD54566975/web5-js/main)
+[![Button to click and edit code in CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/github/TBD54566975/web5-js/main)
 
 ## Installation
 
@@ -351,6 +352,7 @@ const { protocol } = await web5.dwn.protocols.configure({
   message: {
     definition: {
       protocol: "https://photos.org/protocol",
+      published: true,
       types: {
         album: {
           schema: "https://photos.org/protocol/album",

packages/agent/src/app-data-store.ts

@@ -6,10 +6,9 @@ import { DidKeyMethod } from '@web5/dids';
 import { hkdf } from '@noble/hashes/hkdf';
 import { sha256 } from '@noble/hashes/sha256';
 import { sha512 } from '@noble/hashes/sha512';
-import { randomBytes } from '@web5/crypto/utils';
 import { pbkdf2Async } from '@noble/hashes/pbkdf2';
 import { Convert, MemoryStore } from '@web5/common';
-import { CryptoKey, Jose, XChaCha20Poly1305 } from '@web5/crypto';
+import { CryptoKey, Jose, utils as cryptoUtils, XChaCha20Poly1305 } from '@web5/crypto';
 
 export type AppDataBackup = {
   /**
@@ -295,7 +294,7 @@ export class AppDataVault implements AppDataStore {
 
     /** 6. Encrypt the Identity Agent's private key with the derived VUK
      *  using XChaCha20-Poly1305 */
-    const nonce = randomBytes(24);
+    const nonce = cryptoUtils.randomBytes(24);
     const privateKey = keyPair.privateKey.material;
     const {
       ciphertext: privateKeyCiphertext,

packages/agent/src/dwn-manager.ts

@@ -9,10 +9,10 @@ import {
 } from '@tbd54566975/dwn-sdk-js';
 
 import { Jose } from '@web5/crypto';
+import { Convert } from '@web5/common';
 import { DidResolver } from '@web5/dids';
 import { Readable } from 'readable-stream';
-import * as didUtils from '@web5/dids/utils';
-import { Convert } from '@web5/common';
+import { utils as didUtils } from '@web5/dids';
 
 import {
   Cid,

packages/agent/src/kms-local.ts

@@ -1,7 +1,7 @@
 import type { Web5Crypto } from '@web5/crypto';
 import type { RequireOnly } from '@web5/common';
 
-import { isCryptoKeyPair, checkRequiredProperty } from '@web5/crypto/utils';
+import { utils as cryptoUtils } from '@web5/crypto';
 import {
   EcdhAlgorithm,
   EcdsaAlgorithm,
@@ -196,7 +196,7 @@ export class LocalKms implements KeyManagementSystem {
 
     // Create a ManagedKey or ManagedKeyPair using the generated key and store the private key material.
     let managedKeyOrKeyPair: GenerateKeyType<T>;
-    if (isCryptoKeyPair(cryptoKey)) {
+    if (cryptoUtils.isCryptoKeyPair(cryptoKey)) {
       const privateKeyType = cryptoKey.privateKey.type as Web5Crypto.PrivateKeyType;
       const id = await this._privateKeyStore.importKey({
         key   : { material: cryptoKey.privateKey.material, type: privateKeyType},
@@ -360,7 +360,7 @@ export class LocalKms implements KeyManagementSystem {
   }
 
   private getAlgorithm(algorithmIdentifier: Web5Crypto.AlgorithmIdentifier): CryptoAlgorithm {
-    checkRequiredProperty({ property: 'name', inObject: algorithmIdentifier });
+    cryptoUtils.checkRequiredProperty({ property: 'name', inObject: algorithmIdentifier });
     const algorithm = this._supportedAlgorithms.get(algorithmIdentifier.name.toUpperCase());
 
     if (algorithm === undefined) {

packages/agent/src/rpc-client.ts

@@ -1,8 +1,8 @@
+import { utils as cryptoUtils } from '@web5/crypto';
+
 import type { JsonRpcResponse } from './json-rpc.js';
 import type { DwnRpc, DwnRpcRequest, DwnRpcResponse } from './types/agent.js';
 
-import { randomUuid } from '@web5/crypto/utils';
-
 import { createJsonRpcRequest, parseJson } from './json-rpc.js';
 
 /**
@@ -54,7 +54,7 @@ class HttpDwnRpcClient implements DwnRpc {
   get transportProtocols() { return ['http:', 'https:']; }
 
   async sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse> {
-    const requestId = randomUuid();
+    const requestId = cryptoUtils.randomUuid();
     const jsonRpcRequest = createJsonRpcRequest(requestId, 'dwn.processMessage', {
       target  : request.targetDid,
       message : request.message

packages/agent/src/store-managed-key.ts

@@ -1,13 +1,17 @@
 import type { RecordsWriteMessage, RecordsWriteOptions } from '@tbd54566975/dwn-sdk-js';
 
-import { randomUuid } from '@web5/crypto/utils';
+import { utils as cryptoUtils } from '@web5/crypto';
 import { Convert, removeEmptyObjects, removeUndefinedProperties } from '@web5/common';
 
-import type { ManagedKeyPair, ManagedKeyStore, ManagedPrivateKey } from './types/managed-key.js';
+import type { DwnResponse, Web5ManagedAgent } from './types/agent.js';
+import type {
+  ManagedKey,
+  ManagedKeyPair,
+  ManagedKeyStore,
+  ManagedPrivateKey
+} from './types/managed-key.js';
 
-import { DwnResponse, Web5ManagedAgent } from './types/agent.js';
 import { isManagedKeyPair } from './utils.js';
-import { ManagedKey } from './types/managed-key.js';
 
 type EncodedPrivateKey = Omit<ManagedPrivateKey, 'material'> & {
   // Key material, encoded as Base64Url.
@@ -152,7 +156,7 @@ export class KeyStoreDwn implements ManagedKeyStore<string, ManagedKey | Managed
     } else {
       // If an ID wasn't specified, generate one.
       if (!key.id) {
-        key.id = randomUuid();
+        key.id = cryptoUtils.randomUuid();
       }
       keyId = key.id;
     }
@@ -430,7 +434,7 @@ export class KeyStoreMemory implements ManagedKeyStore<string, ManagedKey | Mana
     } else {
       // If an ID wasn't specified, generate one.
       if (!key.id) {
-        key.id = randomUuid();
+        key.id = cryptoUtils.randomUuid();
       }
       id = key.id;
     }
@@ -584,7 +588,7 @@ export class PrivateKeyStoreDwn implements ManagedKeyStore<string, ManagedPrivat
     const authorDid = await this.getAuthor({ agent, context });
 
     // Encode the managed key or key pair as bytes.
-    const id = randomUuid(); // Generate a random ID.
+    const id = cryptoUtils.randomUuid(); // Generate a random ID.
     const encodedPrivateKey = this.encodeKey({...key, id });
 
     const { reply: { status } } = await agent.dwnManager.processRequest({
@@ -723,7 +727,7 @@ export class PrivateKeyStoreMemory implements ManagedKeyStore<string, ManagedPri
     // The private key material is transferred to the new object, making the original obj.material unusable.
     const clonedKey = structuredClone(key, { transfer: [key.material.buffer] }) as ManagedPrivateKey;
 
-    clonedKey.id = randomUuid();
+    clonedKey.id = cryptoUtils.randomUuid();
     this.store.set(clonedKey.id, clonedKey);
 
     return clonedKey.id;

packages/api/README.md

@@ -343,6 +343,7 @@ const { protocol } = await web5.dwn.protocols.configure({
   message: {
     definition: {
       protocol: "https://photos.org/protocol",
+      published: true,
       types: {
         album: {
           schema: "https://photos.org/protocol/album",

packages/api/src/did-api.ts

@@ -28,6 +28,12 @@ import type { Web5Agent } from '@web5/agent';
 //   didMethodApis: DidMethodApi[];
 //   cache?: DidResolverCache;
 // }
+
+/**
+ * The DID API is used to create and resolve DIDs.
+ *
+ * @beta
+ */
 export class DidApi {
   // private didResolver: DidResolver;
   // private methodCreatorMap: Map<string, DidMethodCreator> = new Map();