Add web5/crypto to docs ci check

.github/workflows/docs-ci.yml

@@ -23,7 +23,7 @@ jobs:
         with:
           node-version: 18
           registry-url: https://registry.npmjs.org/
-          cache: 'npm'
+          cache: "npm"
 
       - name: Install dependencies
         run: npm ci
@@ -38,10 +38,28 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           report_changed_scope_only: false
           fail_on_error: false
+          group_docs: true
           entry_points: |
             - file: packages/api/src/index.ts
+              docsGenerator: typedoc-html
+              readmeFile: packages/api/README.md
               docsReporter: api-extractor
-              docsGenerator: typedoc-markdown
+            - file: packages/crypto/src/index.ts
+              docsGenerator: typedoc-html
+              readmeFile: packages/crypto/README.md
+              docsReporter: api-extractor
+              docsReporterIgnore:
+              - extractor:ae-missing-release-tag
+              - docs:tsdoc-escape-greater-than
+              - docs:tsdoc-at-sign-in-word
+            - file: packages/crypto-aws-kms/src/index.ts
+              docsGenerator: typedoc-html
+              readmeFile: packages/crypto-aws-kms/README.md
+              docsReporter: api-extractor
+              docsReporterIgnore:
+              - extractor:ae-missing-release-tag
+              - docs:tsdoc-escape-greater-than
+              - docs:tsdoc-at-sign-in-word
 
       - name: Save Artifacts
         uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3

.gitignore

@@ -159,4 +159,7 @@ dist
 # IntelliJ
 .idea
 
-results.xml
+results.xml
+
+.tbdocs
+temp

CONTRIBUTING.md

@@ -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
- [this beginner's guide to squashing commits](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
+  [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.
@@ -134,6 +134,26 @@ To maintain the robustness and reliability of the codebase, we highly value test
   [Discord](https://discord.com/channels/937858703112155166/969272658501976117)
   channel.
 
+### Documentation Generator
+
+We are using [tbdocs](https://github.com/TBD54566975/tbdocs) to check, generate and publish our SDK API Reference docs automatically to GH Pages.
+
+To see if the docs are being generated properly without errors, and to preview the generated docs locally execute the following script:
+
+```sh
+./scripts/tbdocs-check-local.sh
+
+# to see if there are any doc errors
+open .tbdocs/docs-report.md
+
+# to serve the generated docs locally using a static server (e.g. `npm i -g http-server`)
+http-server .tbdocs/docs
+```
+
+The errors can be found here
+
+_PS: You need to have docker installed on your computer._
+
 ### Project Versioning Guidelines
 
 This section provides guidelines for versioning Web5 JS packages. All releases are published to the

packages/crypto-aws-kms/src/api.ts

@@ -413,7 +413,7 @@ export class AwsKmsCrypto implements CryptoApi<AwsKmsGenerateKeyParams> {
    *
    * @remarks
    * This method facilitates the identification of the correct algorithm for cryptographic
-   * operations based on the `alg` or `crv` properties of a {@link Jwk | JWK} or a given AWS
+   * operations based on the `alg` or `crv` properties of a {@link @web5/crypto#Jwk | JWK} or a given AWS
    * key specification.
    *
    * @example

packages/crypto/src/algorithms/aes-ctr.ts

@@ -35,7 +35,7 @@ export interface AesCtrParams {
 /**
  * The `AesCtrAlgorithm` class provides a concrete implementation for cryptographic operations using
  * the AES algorithm in Counter (CTR) mode. This class implements both {@link Cipher | `Cipher`} and
- * { @link KeyGenerator | `KeyGenerator`} interfaces, providing key generation, encryption, and
+ * {@link KeyGenerator | `KeyGenerator`} interfaces, providing key generation, encryption, and
  * decryption features.
  *
  * This class is typically accessed through implementations that extend the

packages/crypto/src/algorithms/aes-gcm.ts

@@ -58,7 +58,7 @@ export interface AesGcmParams {
 /**
  * The `AesGcmAlgorithm` class provides a concrete implementation for cryptographic operations using
  * the AES algorithm in Galois/Counter Mode (GCM). This class implements both
- * {@link Cipher | `Cipher`} and { @link KeyGenerator | `KeyGenerator`} interfaces, providing
+ * {@link Cipher | `Cipher`} and {@link KeyGenerator | `KeyGenerator`} interfaces, providing
  * key generation, encryption, and decryption features.
  *
  * This class is typically accessed through implementations that extend the

packages/crypto/src/algorithms/ecdsa.ts

@@ -22,7 +22,7 @@ export interface EcdsaGenerateKeyParams extends GenerateKeyParams {
 /**
  * The `EcdsaAlgorithm` class provides a concrete implementation for cryptographic operations using
  * the Elliptic Curve Digital Signature Algorithm (ECDSA). This class implements both
- * {@link Signer | `Signer`} and { @link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`}
+ * {@link Signer | `Signer`} and {@link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`}
  * interfaces, providing private key generation, public key derivation, and creation/verification
  * of signatures.
  *

packages/crypto/src/algorithms/eddsa.ts

@@ -28,7 +28,7 @@ export interface EdDsaGenerateKeyParams extends GenerateKeyParams {
 /**
  * The `EdDsaAlgorithm` class provides a concrete implementation for cryptographic operations using
  * the Edwards-curve Digital Signature Algorithm (EdDSA). This class implements both
- * {@link Signer | `Signer`} and { @link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`}
+ * {@link Signer | `Signer`} and {@link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`}
  * interfaces, providing private key generation, public key derivation, and creation/verification
  * of signatures.
  *

packages/crypto/src/index.ts

@@ -1,6 +1,7 @@
 export * from './jose.js';
 export * from './local-kms-crypto.js';
-export * as utils from './utils.js';
+import * as utils from './utils.js';
+export { utils };
 
 export * from './algorithms/aes-ctr.js';
 export * from './algorithms/aes-gcm.js';

packages/crypto/src/primitives/concat-kdf.ts

@@ -109,7 +109,7 @@ export class ConcatKdf {
    * @param params.otherInfo - Additional public information to use in key derivation.
    * @returns The derived key as a Uint8Array.
    *
-   * @throws {Error} If the `keyDataLen` would require multiple rounds.
+   * @throws `Error` If the `keyDataLen` would require multiple rounds.
    */
   public static async deriveKey({ keyDataLen, otherInfo, sharedSecret }: {
     keyDataLen: number;
@@ -195,7 +195,7 @@ export class ConcatKdf {
    *
    * @returns The input data encoded as a Uint8Array.
    *
-   * @throws {TypeError} If fixed-length data is not a number.
+   * @throws `TypeError` If fixed-length data is not a number.
    */
   private static toDataLenData({ data, variableLength = true }: {
     data: unknown;

packages/crypto/src/primitives/sha256.ts

@@ -3,7 +3,7 @@ import { sha256 } from '@noble/hashes/sha256';
 /**
  * The `Sha256` class provides an interface for generating SHA-256 hash digests.
  *
- * This class utilizes the '@noble/hashes/sha256' function to generate hash digests
+ * This class utilizes the `@noble/hashes/sha256` function to generate hash digests
  * of the provided data. The SHA-256 algorithm is widely used in cryptographic
  * applications to produce a fixed-size 256-bit (32-byte) hash.
  *

packages/crypto/src/types/crypto-api.ts

@@ -25,7 +25,7 @@ import type {
  * Guidelines for implementing this interface:
  * - Must use JSON Web Keys ({@link Jwk | JWK}) as the key format.
  * - Must IANA registered JSON Object Signing and Encryption
- *   {@ link https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms | (JOSE)}
+ *   ({@link https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms | JOSE})
  *   names for algorithm, curves, etc. whenever possible.
  * - All I/O that interacts with private or secret keys must be done via reference using a
  *   {@link KeyIdentifier | `KeyIdentifier`}. Implementations can use any string as the key
@@ -47,10 +47,18 @@ export interface CryptoApi<
           Hasher<DigestInput>,
           Signer<SignInput, VerifyInput> {
   /**
+   * Retrieves the unique identifier for a cryptographic key, known as the Key URI.
    *
-   * @param params - The parameters for getting the key URI.
-   * @param params.key - The key to get the URI for.
-   * @returns The key URI.
+   * @remarks
+   * This method returns a unique identifier, or Key URI, for a given cryptographic key. The Key
+   * URI serves as a secure reference to the key, especially in systems where direct access to the
+   * key material is restricted or managed by a Key Management System (KMS). The method is designed
+   * to be flexible, accommodating various forms of key identifiers, such as JWK thumbprints or
+   * UUIDs generated by a hosted KMS.
+   *
+   * @param params - The parameters for retrieving the key URI.
+   * @param params.key - The cryptographic key for which the URI is being retrieved.
+   * @returns A Promise that resolves to the Key URI as a string, uniquely identifying the key.
    */
   getKeyUri(params: KmsGetKeyUriParams): Promise<KeyIdentifier>;
 }

packages/crypto/src/types/params-direct.ts

@@ -10,7 +10,7 @@ export interface ComputePublicKeyParams extends GetPublicKeyParams { }
  * Parameters for decrypting data.
  */
 export interface DecryptParams {
-  /** A {@link Jwk} containing the key to be used for decryption. */
+  /** A {@link Jwk | JWK} containing the key to be used for decryption. */
   key: Jwk;
 
   /** Data to be decrypted. */
@@ -21,7 +21,7 @@ export interface DecryptParams {
  * Parameters for deriving bits.
  */
 export interface DeriveBitsParams {
-  /** A {@link Jwk} containing the base key to be used for derivation. */
+  /** A {@link Jwk | JWK} containing the base key to be used for derivation. */
   key: Jwk;
 
   /**
@@ -35,7 +35,7 @@ export interface DeriveBitsParams {
  * Parameters for deriving a key.
  */
 export interface DeriveKeyParams {
-  /** A {@link Jwk} containing the base key to be used for derivation. */
+  /** A {@link Jwk | JWK} containing the base key to be used for derivation. */
   key: Jwk;
 
   /** An object defining the algorithm-specific parameters for the derived key. */
@@ -57,7 +57,7 @@ export interface DigestParams {
  * Parameters for encrypting data.
  */
 export interface EncryptParams {
-  /** A {@link Jwk} containing the key to be used for encryption. */
+  /** A {@link Jwk | JWK} containing the key to be used for encryption. */
   key: Jwk;
 
   /** Data to be encrypted. */
@@ -76,15 +76,15 @@ export interface GenerateKeyParams {
  * Parameters for retrieving a public key.
  */
 export interface GetPublicKeyParams {
-  /** A {@link Jwk} containing the key from which to derive the public key. */
+  /** A {@link Jwk | JWK} containing the key from which to derive the public key. */
   key: Jwk;
 }
 
 /**
  * Parameters for signing data.
  */
 export interface SignParams {
-  /** A {@link Jwk} containing the key used for signing. */
+  /** A {@link Jwk | JWK} containing the key used for signing. */
   key: Jwk;
 
   /** Data to be signed. */
@@ -95,7 +95,7 @@ export interface SignParams {
  * Parameters for verifying a signature.
  */
 export interface VerifyParams {
-  /** A {@link Jwk} containing the key used for verification. */
+  /** A {@link Jwk | JWK} containing the key used for verification. */
   key: Jwk;
 
   /** The signature to verify. */

packages/crypto/src/types/params-kms.ts

@@ -75,7 +75,12 @@ export interface KmsGenerateKeyParams {
   algorithm: AlgorithmIdentifier;
 }
 
+/**
+ * Parameters for retrieving the key URI for a public key from a KMS.  Intended for use with a Key
+ * Management System.
+ */
 export interface KmsGetKeyUriParams {
+  /** The {@link Jwk | JWK} for which the URI is being retrieved. */
   key: Jwk;
 }
 
@@ -92,7 +97,7 @@ export interface KmsGetPublicKeyParams {
  * Parameters for importing a private key into a KMS. Intended for use with a Key Management System.
  */
 export interface KmsImportKeyParams {
-  /** A {@link Jwk} containing the key to be imported into the KMS. */
+  /** A {@link Jwk | JWK} containing the key to be imported into the KMS. */
   key: Jwk;
 }
 
@@ -112,7 +117,7 @@ export interface KmsSignParams {
  * Management System.
  */
 export interface KmsVerifyParams {
-  /** A {@link Jwk} containing the public key to be used for verification. */
+  /** A {@link Jwk | JWK} containing the public key to be used for verification. */
   key: Jwk;
 
   /** The signature to verify. */
@@ -126,7 +131,7 @@ export interface KmsVerifyParams {
  * Parameters for wrapping a key using a KMS. Intended for use with a Key Management System.
  */
 export interface KmsWrapKeyParams {
-  /** A {@link Jwk} containing the private key to be wrapped. */
+  /** A {@link Jwk | JWK} containing the private key to be wrapped. */
   key: Jwk;
 
   /** Identifier for the private key in the KMS to be used for the wrapping operation. */

packages/crypto/src/utils.ts

@@ -16,7 +16,7 @@ import { randomBytes as nobleRandomBytes } from '@noble/hashes/utils';
  * @param params.property - Property key to check for.
  * @param params.properties - Properties object to check within.
  * @returns void
- * @throws {TypeError} If the property is not a key in the properties object.
+ * @throws `TypeError` If the property is not a key in the properties object.
  */
 export function checkRequiredProperty(params: {
   property: string,
@@ -42,10 +42,10 @@ export function checkRequiredProperty(params: {
  * checkValidProperty({ property: 'weight', allowedProperties }); // Throws TypeError
  * ```
  *
- * @param property Property key to check for.
- * @param allowedProperties Properties Array, Map, or Set to check within.
+ * @param property - Property key to check for.
+ * @param allowedProperties - Properties Array, Map, or Set to check within.
  * @returns void
- * @throws {TypeError} If the property is not a member of the allowedProperties Array, Map, or Set.
+ * @throws `TypeError` If the property is not a member of the allowedProperties Array, Map, or Set.
  */
 export function checkValidProperty(params: {
   property: string, allowedProperties: ReadonlyArray<string> | Array<string> | Map<string, unknown> | Set<string>
@@ -166,7 +166,7 @@ export function multibaseIdToKey({ multibaseKeyId }: {
  * `crypto.getRandomValues`, which defers to the operating system.
  *
  * @remarks
- * This function is a wrapper around `randomBytes` from the '@noble/hashes'
+ * This function is a wrapper around `randomBytes` from the `@noble/hashes`
  * package. It's designed to be cryptographically strong, suitable for
  * generating initialization vectors, nonces, and other random values.
  *

scripts/tbdocs-check-local.sh

@@ -0,0 +1,37 @@
+mkdir -p .tbdocs
+
+SUMMARY_FILE=.tbdocs/summary.md
+
+rm -f ${SUMMARY_FILE}
+touch ${SUMMARY_FILE}
+
+INPUT_ENTRY_POINTS="
+- file: packages/api/src/index.ts
+  docsGenerator: typedoc-html
+  readmeFile: packages/api/README.md
+  docsReporter: api-extractor
+- file: packages/crypto/src/index.ts
+  docsGenerator: typedoc-html
+  readmeFile: packages/crypto/README.md
+  docsReporter: api-extractor
+  docsReporterIgnore:
+  - extractor:ae-missing-release-tag
+  - docs:tsdoc-escape-greater-than
+  - docs:tsdoc-at-sign-in-word
+- file: packages/crypto-aws-kms/src/index.ts
+  docsGenerator: typedoc-html
+  readmeFile: packages/crypto-aws-kms/README.md
+  docsReporter: api-extractor
+  docsReporterIgnore:
+  - extractor:ae-missing-release-tag
+  - docs:tsdoc-escape-greater-than
+  - docs:tsdoc-at-sign-in-word
+"
+
+docker run -v $(pwd):/github/workspace/ \
+   --workdir /github/workspace          \
+   -e "GITHUB_REPOSITORY=TBD54566975/web5-js" \
+   -e "GITHUB_STEP_SUMMARY=${SUMMARY_FILE}" \
+   -e "INPUT_ENTRY_POINTS=${INPUT_ENTRY_POINTS}" \
+   -e "INPUT_GROUP_DOCS=true" \
+   ghcr.io/tbd54566975/tbdocs:main