Merge pull request #225 from dajiaji/fix-doc

Deploy tsdoc-based document to pages.

.github/workflows/ci_browser.yml

@@ -21,6 +21,9 @@ jobs:
         with:
           node-version: v18.x
       - run: |
+          npm install -g typescript
+          npm install -g typedoc
+          npx typedoc --name "hpke-js $(git describe --tags $(git rev-list --tags --max-count=1))" --out test/runtimes/browsers/pages/docs mod.ts
           npm install -g esbuild
           deno task dnt
           deno task minify > test/runtimes/browsers/pages/src/hpke.js
@@ -36,6 +39,7 @@ jobs:
           cp -rf x/dhkem-secp256k1/test/runtimes/browsers/pages/* test/runtimes/browsers/pages/dhkem-secp256k1
       - working-directory: ./core
         run: |
+          npx typedoc --name "@hpke/core $(git describe --tags $(git rev-list --tags --max-count=1))" --out ../test/runtimes/browsers/pages/core/docs mod.ts
           deno task dnt
           deno task minify > ../test/runtimes/browsers/pages/core/src/hpke-core.js
           deno task minify > ../test/runtimes/browsers/pages/dhkem-x25519/src/hpke-core.js
@@ -44,18 +48,22 @@ jobs:
           deno task minify > ../test/runtimes/browsers/pages/dhkem-secp256k1/src/hpke-core.js
       - working-directory: ./x/dhkem-x25519
         run: |
+          npx typedoc --name "@hpke/dhkem-x25519 $(git describe --tags $(git rev-list --tags --max-count=1))" --out ../test/runtimes/browsers/pages/dhkem-x25519/docs mod.ts
           deno task dnt
           deno task minify > ../../test/runtimes/browsers/pages/dhkem-x25519/src/hpke-dhkem-x25519.js
       - working-directory: ./x/dhkem-x448
         run: |
+          npx typedoc --name "@hpke/dhkem-x448 $(git describe --tags $(git rev-list --tags --max-count=1))" --out ../test/runtimes/browsers/pages/dhkem-x448/docs mod.ts
           deno task dnt
           deno task minify > ../../test/runtimes/browsers/pages/dhkem-x448/src/hpke-dhkem-x448.js
       - working-directory: ./x/chacha20poly1305
         run: |
+          npx typedoc --name "@hpke/chacha20poly1305 $(git describe --tags $(git rev-list --tags --max-count=1))" --out ../test/runtimes/browsers/pages/chacha20poly1305/docs mod.ts
           deno task dnt
           deno task minify > ../../test/runtimes/browsers/pages/chacha20poly1305/src/hpke-chacha20poly1305.js
       - working-directory: ./x/dhkem-secp256k1
         run: |
+          npx typedoc --name "@hpke/dhkem-secp256k1 $(git describe --tags $(git rev-list --tags --max-count=1))" --out ../test/runtimes/browsers/pages/dhkem-secp256k1/docs mod.ts
           deno task dnt
           deno task minify > ../../test/runtimes/browsers/pages/dhkem-secp256k1/src/hpke-dhkem-secp256k1.js
       - uses: peaceiris/actions-gh-pages@v3

core/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "module": "es2022",
+    "target": "es2022",
+    "allowImportingTsExtensions": true
+  }, 
+  "include": [
+    "mod.ts",
+    "src/**/*"
+  ]
+}

src/aeads/chacha20Poly1305.ts

@@ -1,3 +1,4 @@
+// @ts-ignore: for "npm:"
 import { chacha20_poly1305 } from "npm:@noble/[email protected]/chacha";
 
 import type { AeadEncryptionContext } from "../interfaces/aeadEncryptionContext.ts";

src/cipherSuite.ts

@@ -33,9 +33,6 @@ import * as errors from "./errors.ts";
 export class CipherSuite extends CipherSuiteNative {
   /**
    * @param params A set of parameters for building a cipher suite.
-   *
-   * If the error occurred, throws `InvalidParamError`.
-   *
    * @throws {@link InvalidParamError}
    */
   constructor(params: CipherSuiteParams) {

src/errors.ts

@@ -14,9 +14,6 @@ class HpkeError extends Error {
     }
     super(message);
 
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
     this.name = this.constructor.name;
     if (this.message === "") {
       this.message = this.name;

src/identifiers.ts

@@ -13,20 +13,14 @@ export type Mode = typeof Mode[keyof typeof Mode];
 /**
  * Supported Key Encapsulation Mechanisms (KEMs).
  *
- * DEPRECATED. Use KdfId.
+ * @deprecated Use {@link KdfId} instead.
  */
 export const Kem = {
-  /** DHKEM (P-256, HKDF-SHA256). */
   DhkemP256HkdfSha256: 0x0010,
-  /** DHKEM (P-384, HKDF-SHA384). */
   DhkemP384HkdfSha384: 0x0011,
-  /** DHKEM (P-521, HKDF-SHA512). */
   DhkemP521HkdfSha512: 0x0012,
-  /** DHKEM (secp256k1, HKDF-SHA256). EXPERIMENTAL. The KEM id can be changed in the standardization process. */
   DhkemSecp256k1HkdfSha256: 0x0013,
-  /** DHKEM (X25519, HKDF-SHA256) */
   DhkemX25519HkdfSha256: 0x0020,
-  /** DHKEM (X448, HKDF-SHA512) */
   DhkemX448HkdfSha512: 0x0021,
 } as const;
 
@@ -41,14 +35,11 @@ export type KemId = typeof KemId[keyof typeof KemId];
 /**
  * Supported Key Derivation Functions (KDFs).
  *
- * DEPRECATED. Use KdfId.
+ * @deprecated Use {@link KdfId} instead.
  */
 export const Kdf = {
-  /** HKDF-SHA256. */
   HkdfSha256: 0x0001,
-  /** HKDF-SHA384. */
   HkdfSha384: 0x0002,
-  /** HKDF-SHA512. */
   HkdfSha512: 0x0003,
 } as const;
 
@@ -63,19 +54,12 @@ export type KdfId = typeof KdfId[keyof typeof KdfId];
 /**
  * Supported Authenticated Encryption with Associated Data (AEAD) Functions.
  *
- * DEPRECATED. Use AeadId.
+ * @deprecated Use {@link AeadId} instead.
  */
 export const Aead = {
-  /** AES-128-GCM. */
   Aes128Gcm: 0x0001,
-  /** AES-256-GCM. */
   Aes256Gcm: 0x0002,
-  /** ChaCha20Poly1305. */
   Chacha20Poly1305: 0x0003,
-  /**
-   * Export-only mode for applications that only use the export() function
-   * to get secrets for AEAD.
-   */
   ExportOnly: 0xFFFF,
 } as const;
 

src/interfaces/aeadInterface.ts

@@ -16,7 +16,7 @@ export interface AeadInterface {
   readonly tagSize: number;
 
   /**
-   * Initializes the key by setting the SubtleCrypto.
+   * Initializes the instance by setting a SubtleCrypto API.
    *
    * @param api A SubtleCrypto API.
    */
@@ -26,7 +26,6 @@ export interface AeadInterface {
    * Creates an AEAD encryption context which has seal/open operation.
    *
    * @param key A byte string of the raw key.
-   *
    * @returns An AEAD encryption context.
    */
   createEncryptionContext(key: ArrayBuffer): AeadEncryptionContext;

src/interfaces/cipherSuiteParams.ts

@@ -10,9 +10,9 @@ export interface CipherSuiteParams {
   /** The KEM (Key Encapsulation Mechanism) identifier or the KEM object. */
   kem: KemId | KemInterface;
 
-  /** The KDF (Key Derivation Function) identifier. */
+  /** The KDF (Key Derivation Function) identifier or the KDF object. */
   kdf: KdfId | KdfInterface;
 
-  /** The AEAD (Authenticated Encryption with Addtional Data) identifier. */
+  /** The AEAD (Authenticated Encryption with Addtional Data) identifier or the AEAD object. */
   aead: AeadId | AeadInterface;
 }

src/interfaces/kdfInterface.ts

@@ -9,39 +9,101 @@ export interface KdfInterface {
   /** The output size of the extract() function in bytes (Nh). */
   readonly hashSize: number;
 
+  /**
+   * Initializes the instance by setting a SubtleCrypto API.
+   *
+   * @param api A SubtleCrypto API.
+   */
+  init(api: SubtleCrypto, suiteId: Uint8Array): void;
+
+  /**
+   * Builds a labeled input keying material.
+   *
+   * @param label A byte string indicating the cryptographic context/operation.
+   * @param info An additional byte string.
+   * @returns An input keying material as bytes.
+   */
   buildLabeledIkm(label: Uint8Array, ikm: Uint8Array): Uint8Array;
+
+  /**
+   * Builds a labeled info string.
+   *
+   * @param label A byte string indicating the cryptographic context/operation.
+   * @param info An additional byte string.
+   * @param len The length of the output byte string.
+   * @returns An info string as bytes.
+   */
   buildLabeledInfo(
     label: Uint8Array,
     info: Uint8Array,
     len: number,
   ): Uint8Array;
 
-  init(api: SubtleCrypto, suiteId: Uint8Array): void;
-
+  /**
+   * Extracts a pseudorandom key of fixed length (Nh) bytes.
+   *
+   * @param salt An additional random byte string.
+   * @param ikm An input keying material
+   * @returns A pseudorandom key as bytes.
+   */
   extract(
     salt: ArrayBuffer,
     ikm: ArrayBuffer,
   ): Promise<ArrayBuffer>;
 
+  /**
+   * Expands a pseudorandom key `prk`.
+   *
+   * @param prk A pseudorandom key.
+   * @param info An additional byte string.
+   * @param len The length in bytes of the output keying material.
+   * @returns An output keying material as bytes.
+   */
   expand(
     prk: ArrayBuffer,
     info: ArrayBuffer,
     len: number,
   ): Promise<ArrayBuffer>;
 
+  /**
+   * -
+   *
+   * @param salt An additional random byte string.
+   * @param ikm An input keying material
+   * @param info An additional byte string.
+   * @param len The length in bytes of the output keying material.
+   * @returns An output keying material as bytes.
+   */
   extractAndExpand(
     salt: ArrayBuffer,
     ikm: ArrayBuffer,
     info: ArrayBuffer,
     len: number,
   ): Promise<ArrayBuffer>;
 
+  /**
+   * Extracts a pseudorandom key with label.
+   *
+   * @param salt An additional random byte string.
+   * @param label A byte string indicating the cryptographic context/operation.
+   * @param ikm An input keying material
+   * @returns A pseudorandom key as bytes.
+   */
   labeledExtract(
     salt: ArrayBuffer,
     label: Uint8Array,
     ikm: Uint8Array,
   ): Promise<ArrayBuffer>;
 
+  /**
+   * Extracts a pseudorandom key with label.
+   *
+   * @param prk A pseudorandom key.
+   * @param label A byte string indicating the cryptographic context/operation.
+   * @param info An additional byte string.
+   * @param len The length in bytes of the output keying material.
+   * @returns An output keying material as bytes.
+   */
   labeledExpand(
     prk: ArrayBuffer,
     label: Uint8Array,

src/interfaces/kemInterface.ts

@@ -18,30 +18,51 @@ export interface KemInterface {
   /** The length in bytes of an encoded private key for this KEM (Nsk). */
   readonly privateKeySize: number;
 
+  /**
+   * Initializes the instance by setting a SubtleCrypto API.
+   *
+   * @param api A SubtleCrypto API.
+   */
   init(api: SubtleCrypto): void;
 
   /**
    * Generates a key pair.
+   *
+   * @returns A key pair.
    */
   generateKeyPair(): Promise<CryptoKeyPair>;
 
   /**
    * Derives a key pair from the byte string ikm.
+   *
+   * @param ikm An input keying material.
+   * @returns A key pair.
    */
   deriveKeyPair(ikm: ArrayBuffer): Promise<CryptoKeyPair>;
 
   /**
    * Serializes a public key as CryptoKey to a byte string of length `Npk`.
+   *
+   * @param key A CryptoKey.
+   * @returns A key as bytes.
    */
   serializePublicKey(key: CryptoKey): Promise<ArrayBuffer>;
 
   /**
    * Deserializes a public key as a byte string of length `Npk` to CryptoKey.
+   *
+   * @param key A key as bytes.
+   * @returns A CryptoKey.
    */
   deserializePublicKey(key: ArrayBuffer): Promise<CryptoKey>;
 
   /**
    * Imports a key for the KEM.
+   *
+   * @param format An imput KEM key format.
+   * @param key A KEM key.
+   * @param isPublic The indicator whether the KEM key is public or not.
+   * @returns A CryptoKey.
    */
   importKey(
     format: "raw" | "jwk",
@@ -53,13 +74,19 @@ export interface KemInterface {
    * Generates an ephemeral, fixed-length symmetric key and
    * a fixed-length encapsulation of the key that can be decapsulated
    * by the holder of the private key corresponding to `pkR`.
+   *
+   * @param params A set of parameters for the sender context.
+   * @returns A shared secret and an encapsulated key as the output of the encapsulation step.
    */
   encap(
     params: SenderContextParams,
   ): Promise<{ sharedSecret: ArrayBuffer; enc: ArrayBuffer }>;
 
   /**
    * Recovers the ephemeral symmetric key from its encapsulated representation `enc`.
+   *
+   * @param params A set of parameters for the recipient context.
+   * @returns A shared secret as the output of the decapsulation step.
    */
   decap(params: RecipientContextParams): Promise<ArrayBuffer>;
 }

src/kdfs/hkdfSha256.ts

@@ -1,4 +1,6 @@
+// @ts-ignore: for "npm:"
 import { hmac } from "npm:@noble/[email protected]/hmac";
+// @ts-ignore: for "npm:"
 import { sha256 } from "npm:@noble/[email protected]/sha256";
 
 import { HkdfSha256Native } from "./hkdf.ts";

src/kdfs/hkdfSha384.ts

@@ -1,4 +1,6 @@
+// @ts-ignore: for "npm:"
 import { hmac } from "npm:@noble/[email protected]/hmac";
+// @ts-ignore: for "npm:"
 import { sha384 } from "npm:@noble/[email protected]/sha512";
 
 import { HkdfSha384Native } from "./hkdf.ts";

src/kdfs/hkdfSha512.ts

@@ -1,4 +1,6 @@
+// @ts-ignore: for "npm:"
 import { hmac } from "npm:@noble/[email protected]/hmac";
+// @ts-ignore: for "npm:"
 import { sha512 } from "npm:@noble/[email protected]/sha512";
 
 import { HkdfSha512Native } from "./hkdf.ts";

src/kems/dhkemPrimitives/x25519.ts

@@ -1,3 +1,4 @@
+// @ts-ignore: for "npm:"
 import { ed25519, x25519 } from "npm:@noble/[email protected]/ed25519";
 
 import type { KemPrimitives } from "../../interfaces/kemPrimitives.ts";

src/kems/dhkemPrimitives/x448.ts

@@ -1,3 +1,4 @@
+// @ts-ignore: for "npm:"
 import { ed448, x448 } from "npm:@noble/[email protected]/ed448";
 
 import type { KemPrimitives } from "../../interfaces/kemPrimitives.ts";

src/webCrypto.ts

@@ -11,6 +11,7 @@ export async function loadCrypto(): Promise<Crypto> {
   }
 
   try {
+    // @ts-ignore: to ignore "crypto"
     const { webcrypto } = await import("crypto"); // node:crypto
     return (webcrypto as unknown as Crypto);
   } catch (_e: unknown) {
@@ -27,6 +28,7 @@ export async function loadSubtleCrypto(): Promise<SubtleCrypto> {
   }
 
   try {
+    // @ts-ignore: to ignore "crypto"
     const { webcrypto } = await import("crypto"); // node:crypto
     return (webcrypto as unknown as Crypto).subtle;
   } catch (_e: unknown) {