From 6cd6831fbf207d3fffd195c8db912e26f0c2dea9 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 4 Jan 2024 15:21:30 -0500 Subject: [PATCH 1/7] Add web5/crypto to docs ci check --- .github/workflows/docs-ci.yml | 7 ++++++- packages/crypto/src/index.ts | 3 ++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index e470ca47d..d39865475 100644 --- a/.github/workflows/docs-ci.yml +++ b/.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 @@ -42,6 +42,11 @@ jobs: - file: packages/api/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-markdown + - file: packages/crypto/src/index.ts + docsGenerator: typedoc-markdown + docsReporter: api-extractor + docsReporterIgnore: + - extractor:ae-missing-release-tag - name: Save Artifacts uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 diff --git a/packages/crypto/src/index.ts b/packages/crypto/src/index.ts index d2952615e..964afe565 100644 --- a/packages/crypto/src/index.ts +++ b/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'; From 23cf9bc90fc39d2d3f2d790caf6245b027108a39 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 4 Jan 2024 16:17:50 -0500 Subject: [PATCH 2/7] Add web5/crypto-aws-kms to docs ci check --- .github/workflows/docs-ci.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index d39865475..dceb27fde 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -47,6 +47,11 @@ jobs: docsReporter: api-extractor docsReporterIgnore: - extractor:ae-missing-release-tag + - file: packages/crypto-aws-kms/src/index.ts + docsGenerator: typedoc-markdown + docsReporter: api-extractor + docsReporterIgnore: + - extractor:ae-missing-release-tag - name: Save Artifacts uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 From eac6a582a33e83a6a50a204e9dbd888e9e44c598 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 4 Jan 2024 16:34:06 -0500 Subject: [PATCH 3/7] fix docs warnings --- packages/crypto-aws-kms/src/api.ts | 2 +- packages/crypto/src/algorithms/aes-ctr.ts | 2 +- packages/crypto/src/algorithms/aes-gcm.ts | 2 +- packages/crypto/src/algorithms/ecdsa.ts | 2 +- packages/crypto/src/algorithms/eddsa.ts | 2 +- packages/crypto/src/primitives/aes-ctr.ts | 4 ++-- packages/crypto/src/primitives/aes-gcm.ts | 10 +++++----- packages/crypto/src/primitives/concat-kdf.ts | 4 ++-- packages/crypto/src/primitives/sha256.ts | 2 +- packages/crypto/src/types/crypto-api.ts | 2 +- packages/crypto/src/utils.ts | 10 +++++----- 11 files changed, 21 insertions(+), 21 deletions(-) diff --git a/packages/crypto-aws-kms/src/api.ts b/packages/crypto-aws-kms/src/api.ts index b16555b83..dbb5181d3 100644 --- a/packages/crypto-aws-kms/src/api.ts +++ b/packages/crypto-aws-kms/src/api.ts @@ -413,7 +413,7 @@ export class AwsKmsCrypto implements CryptoApi { * * @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 diff --git a/packages/crypto/src/algorithms/aes-ctr.ts b/packages/crypto/src/algorithms/aes-ctr.ts index 49979091f..0a31ab04a 100644 --- a/packages/crypto/src/algorithms/aes-ctr.ts +++ b/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 diff --git a/packages/crypto/src/algorithms/aes-gcm.ts b/packages/crypto/src/algorithms/aes-gcm.ts index 9d22126a5..378ec5ffa 100644 --- a/packages/crypto/src/algorithms/aes-gcm.ts +++ b/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 diff --git a/packages/crypto/src/algorithms/ecdsa.ts b/packages/crypto/src/algorithms/ecdsa.ts index bac78d01a..804a52d28 100644 --- a/packages/crypto/src/algorithms/ecdsa.ts +++ b/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. * diff --git a/packages/crypto/src/algorithms/eddsa.ts b/packages/crypto/src/algorithms/eddsa.ts index ac093b4a9..e0092a0ad 100644 --- a/packages/crypto/src/algorithms/eddsa.ts +++ b/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. * diff --git a/packages/crypto/src/primitives/aes-ctr.ts b/packages/crypto/src/primitives/aes-ctr.ts index 6e9bd2634..7fc8e31d1 100644 --- a/packages/crypto/src/primitives/aes-ctr.ts +++ b/packages/crypto/src/primitives/aes-ctr.ts @@ -26,8 +26,8 @@ const AES_BLOCK_SIZE = 128; * * @remarks * NIST publication FIPS 197 states: - * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt - * > and decrypt data in blocks of 128 bits. + * \> The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt + * \> and decrypt data in blocks of 128 bits. * * This implementation does not support key lengths that are different from the three values * defined by this constant. diff --git a/packages/crypto/src/primitives/aes-gcm.ts b/packages/crypto/src/primitives/aes-gcm.ts index e80274bf9..031c78c47 100644 --- a/packages/crypto/src/primitives/aes-gcm.ts +++ b/packages/crypto/src/primitives/aes-gcm.ts @@ -10,8 +10,8 @@ import { computeJwkThumbprint, isOctPrivateJwk } from '../jose/jwk.js'; * * @remarks * NIST Special Publication 800-38D, Section 5.2.1.1 states that the IV length: - * > For IVs, it is recommended that implementations restrict support to the length of 96 bits, to - * > promote interoperability, efficiency, and simplicity of design. + * \> For IVs, it is recommended that implementations restrict support to the length of 96 bits, to + * \> promote interoperability, efficiency, and simplicity of design. * * This implementation does not support IV lengths that are different from the value defined by * this constant. @@ -25,8 +25,8 @@ const AES_GCM_IV_LENGTH = 96; * * @remarks * NIST publication FIPS 197 states: - * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt - * > and decrypt data in blocks of 128 bits. + * \> The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt + * \> and decrypt data in blocks of 128 bits. * * This implementation does not support key lengths that are different from the three values * defined by this constant. @@ -40,7 +40,7 @@ const AES_KEY_LENGTHS = [128, 192, 256] as const; * * @remarks * NIST Special Publication 800-38D, Section 5.2.1.2 states that the tag length: - * > may be any one of the following five values: 128, 120, 112, 104, or 96 + * \> may be any one of the following five values: 128, 120, 112, 104, or 96 * * Although the NIST specification allows for tag lengths of 32 or 64 bits in certain applications, * the use of shorter tag lengths can be problematic for GCM due to targeted forgery attacks. As a diff --git a/packages/crypto/src/primitives/concat-kdf.ts b/packages/crypto/src/primitives/concat-kdf.ts index 568e8a0e8..01239858d 100644 --- a/packages/crypto/src/primitives/concat-kdf.ts +++ b/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; diff --git a/packages/crypto/src/primitives/sha256.ts b/packages/crypto/src/primitives/sha256.ts index 44a1dfe5a..701d8eb2f 100644 --- a/packages/crypto/src/primitives/sha256.ts +++ b/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. * diff --git a/packages/crypto/src/types/crypto-api.ts b/packages/crypto/src/types/crypto-api.ts index 1069c74ef..c1bf5e6cf 100644 --- a/packages/crypto/src/types/crypto-api.ts +++ b/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 diff --git a/packages/crypto/src/utils.ts b/packages/crypto/src/utils.ts index fc3fcdeee..9c05b8f4a 100644 --- a/packages/crypto/src/utils.ts +++ b/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 | Array | Map | Set @@ -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. * From a493df1372f100118331ba3e0b421c2a85adaf07 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 4 Jan 2024 16:43:30 -0500 Subject: [PATCH 4/7] add docs generation --- .github/workflows/docs-ci.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index dceb27fde..36d1a52a9 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -38,17 +38,18 @@ 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 docsReporter: api-extractor - docsGenerator: typedoc-markdown - file: packages/crypto/src/index.ts - docsGenerator: typedoc-markdown + docsGenerator: typedoc-html docsReporter: api-extractor docsReporterIgnore: - extractor:ae-missing-release-tag - file: packages/crypto-aws-kms/src/index.ts - docsGenerator: typedoc-markdown + docsGenerator: typedoc-html docsReporter: api-extractor docsReporterIgnore: - extractor:ae-missing-release-tag From a22665b63ed069814cc532bf13bf3c09c4764c83 Mon Sep 17 00:00:00 2001 From: Frank Hinek Date: Fri, 5 Jan 2024 11:47:36 -0500 Subject: [PATCH 5/7] Adding / improving docs Signed-off-by: Frank Hinek --- packages/crypto/src/types/crypto-api.ts | 16 ++++++++++++---- packages/crypto/src/types/params-direct.ts | 14 +++++++------- packages/crypto/src/types/params-kms.ts | 11 ++++++++--- 3 files changed, 27 insertions(+), 14 deletions(-) diff --git a/packages/crypto/src/types/crypto-api.ts b/packages/crypto/src/types/crypto-api.ts index c1bf5e6cf..09041802b 100644 --- a/packages/crypto/src/types/crypto-api.ts +++ b/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, Signer { /** + * 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; } \ No newline at end of file diff --git a/packages/crypto/src/types/params-direct.ts b/packages/crypto/src/types/params-direct.ts index 6fca8c069..e841caf41 100644 --- a/packages/crypto/src/types/params-direct.ts +++ b/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,7 +76,7 @@ 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; } @@ -84,7 +84,7 @@ export interface GetPublicKeyParams { * 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. */ diff --git a/packages/crypto/src/types/params-kms.ts b/packages/crypto/src/types/params-kms.ts index 705a32f98..40184a067 100644 --- a/packages/crypto/src/types/params-kms.ts +++ b/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. */ From edee53227caa6704678ce5ce202d017c86f2302b Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Fri, 5 Jan 2024 13:47:46 -0500 Subject: [PATCH 6/7] rollback backslash escapes --- .github/workflows/docs-ci.yml | 4 ++++ packages/crypto/src/primitives/aes-ctr.ts | 4 ++-- packages/crypto/src/primitives/aes-gcm.ts | 10 +++++----- packages/crypto/src/primitives/sha256.ts | 2 +- packages/crypto/src/utils.ts | 2 +- 5 files changed, 13 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index 36d1a52a9..4ff0dcb7d 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -48,11 +48,15 @@ jobs: 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 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 diff --git a/packages/crypto/src/primitives/aes-ctr.ts b/packages/crypto/src/primitives/aes-ctr.ts index 7fc8e31d1..6e9bd2634 100644 --- a/packages/crypto/src/primitives/aes-ctr.ts +++ b/packages/crypto/src/primitives/aes-ctr.ts @@ -26,8 +26,8 @@ const AES_BLOCK_SIZE = 128; * * @remarks * NIST publication FIPS 197 states: - * \> The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt - * \> and decrypt data in blocks of 128 bits. + * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt + * > and decrypt data in blocks of 128 bits. * * This implementation does not support key lengths that are different from the three values * defined by this constant. diff --git a/packages/crypto/src/primitives/aes-gcm.ts b/packages/crypto/src/primitives/aes-gcm.ts index 031c78c47..e80274bf9 100644 --- a/packages/crypto/src/primitives/aes-gcm.ts +++ b/packages/crypto/src/primitives/aes-gcm.ts @@ -10,8 +10,8 @@ import { computeJwkThumbprint, isOctPrivateJwk } from '../jose/jwk.js'; * * @remarks * NIST Special Publication 800-38D, Section 5.2.1.1 states that the IV length: - * \> For IVs, it is recommended that implementations restrict support to the length of 96 bits, to - * \> promote interoperability, efficiency, and simplicity of design. + * > For IVs, it is recommended that implementations restrict support to the length of 96 bits, to + * > promote interoperability, efficiency, and simplicity of design. * * This implementation does not support IV lengths that are different from the value defined by * this constant. @@ -25,8 +25,8 @@ const AES_GCM_IV_LENGTH = 96; * * @remarks * NIST publication FIPS 197 states: - * \> The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt - * \> and decrypt data in blocks of 128 bits. + * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt + * > and decrypt data in blocks of 128 bits. * * This implementation does not support key lengths that are different from the three values * defined by this constant. @@ -40,7 +40,7 @@ const AES_KEY_LENGTHS = [128, 192, 256] as const; * * @remarks * NIST Special Publication 800-38D, Section 5.2.1.2 states that the tag length: - * \> may be any one of the following five values: 128, 120, 112, 104, or 96 + * > may be any one of the following five values: 128, 120, 112, 104, or 96 * * Although the NIST specification allows for tag lengths of 32 or 64 bits in certain applications, * the use of shorter tag lengths can be problematic for GCM due to targeted forgery attacks. As a diff --git a/packages/crypto/src/primitives/sha256.ts b/packages/crypto/src/primitives/sha256.ts index 701d8eb2f..27155e9ab 100644 --- a/packages/crypto/src/primitives/sha256.ts +++ b/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. * diff --git a/packages/crypto/src/utils.ts b/packages/crypto/src/utils.ts index 9c05b8f4a..0400cf78d 100644 --- a/packages/crypto/src/utils.ts +++ b/packages/crypto/src/utils.ts @@ -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. * From 2ca3e0c7db8a2db5df9a8e507acd9e53f8a2e44e Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Fri, 5 Jan 2024 17:39:14 -0500 Subject: [PATCH 7/7] Add README files and tbdocs instructions --- .github/workflows/docs-ci.yml | 3 +++ .gitignore | 5 ++++- CONTRIBUTING.md | 22 ++++++++++++++++++++- scripts/tbdocs-check-local.sh | 37 +++++++++++++++++++++++++++++++++++ 4 files changed, 65 insertions(+), 2 deletions(-) create mode 100755 scripts/tbdocs-check-local.sh diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index 4ff0dcb7d..4a8069078 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -42,9 +42,11 @@ jobs: 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 @@ -52,6 +54,7 @@ jobs: - 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 diff --git a/.gitignore b/.gitignore index e0b5c2fdb..807cfd93e 100644 --- a/.gitignore +++ b/.gitignore @@ -159,4 +159,7 @@ dist # IntelliJ .idea -results.xml \ No newline at end of file +results.xml + +.tbdocs +temp diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3949c38c..81b421c3b 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/scripts/tbdocs-check-local.sh b/scripts/tbdocs-check-local.sh new file mode 100755 index 000000000..a7d7b6fbd --- /dev/null +++ b/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