ndncert: write TypeDoc for Challenge interfaces

package.json

@@ -13,11 +13,11 @@
     "test": "vitest",
     "typedoc": "bash mk/typedoc.sh"
   },
-  "packageManager": "pnpm@8.10.5",
+  "packageManager": "pnpm@8.11.0",
   "devDependencies": {
-    "@types/node": "^20.9.4",
+    "@types/node": "^20.10.0",
     "@types/wtfnode": "^0.7.3",
-    "@typescript/lib-dom": "npm:@types/[email protected].119",
+    "@typescript/lib-dom": "npm:@types/[email protected].122",
     "@vitest/coverage-v8": "^0.34.6",
     "@yoursunny/xo-config": "0.56.0",
     "codedown": "^2.2.0",

packages/ndncert/README.md

@@ -2,7 +2,7 @@
 
 This package is part of [NDNts](https://yoursunny.com/p/NDNts/), Named Data Networking libraries for the modern web.
 
-This package partially implements [NDN Certificate Management protocol v0.3](https://github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3/69d841e20515a5f7e8e5452e8366225e55bf2f86) and [challenges](https://github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3-Challenges/46700d99c67dc94d13d26f838e4594f1f66d7c76).
+This package partially implements [NDN Certificate Management protocol v0.3](https://github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3/841f2a2e66cc3256d113cfe61242420b9cdab6c1) and [challenges](https://github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3-Challenges/46700d99c67dc94d13d26f838e4594f1f66d7c76).
 This implementation is validated against the reference implementation using [ndncert-interop](../../integ/ndncert-interop/).
 
 Features:

packages/ndncert/src/client/challenge.ts

@@ -7,23 +7,45 @@ export interface ClientChallenge {
   /** Challenge module identifier. */
   readonly challengeId: string;
 
-  /** Create a message to select and start the challenge. */
+  /**
+   * Create a message to select and start the challenge.
+   * @returns parameter key-value pairs to send to server in initial CHALLENGE request.
+   */
   start: (context: ClientChallengeStartContext) => Promise<ParameterKV>;
 
-  /** Create a message to continue the challenge. */
+  /**
+   * Create a message to continue the challenge.
+   * @returns parameter key-value pairs to send to server in continuing CHALLENGE request.
+   */
   next: (context: ClientChallengeContext) => Promise<ParameterKV>;
 }
 
+/** Contextual information for challenge selection. */
 export interface ClientChallengeStartContext {
+  /** Request session ID. */
   requestId: Uint8Array;
+
+  /** Certificate name of the self-signed certificate. */
   certRequestName: Name;
 }
 
+/** Contextual information for challenge continuation. */
 export interface ClientChallengeContext {
+  /** Request session ID. */
   requestId: Uint8Array;
+
+  /** Certificate name of the self-signed certificate. */
   certRequestName: Name;
+
+  /** Challenge specific status string. */
   challengeStatus: string;
+
+  /** Number of remaining tries to complete challenge. */
   remainingTries: number;
+
+  /** Remaining time to complete challenge, in milliseconds. */
   remainingTime: number;
+
+  /** Challenge parameter key-value pairs, from CHALLENGE response packet. */
   parameters: ParameterKV;
 }

packages/ndncert/src/client/retrieve-profile.ts

@@ -23,7 +23,7 @@ export interface RetrieveCaProfileOptions {
   caCertFullName: Name;
 }
 
-/** Retrieve and verify CA profile. */
+/** Retrieve and validate CA profile. */
 export async function retrieveCaProfile({
   endpoint = new Endpoint({ retx: 4 }),
   caPrefix,

packages/ndncert/src/packet/challenge-request.ts

@@ -67,9 +67,9 @@ export namespace ChallengeRequest {
   /** Contextual information to decode and verify CHALLENGE request packet. */
   export interface Context extends ContextBase {
     /**
-     * Callback to locate certificate request session.
-     * @param requestId certificate request session ID.
-     * @returns certificate request session information, or undefined if not found.
+     * Callback to locate request session.
+     * @param requestId request session ID.
+     * @returns request session information, or undefined if not found.
      */
     lookupRequest: (requestId: Uint8Array) => Promisable<RequestInfo | undefined>;
   }
@@ -85,17 +85,17 @@ export namespace ChallengeRequest {
 
   /** Options to construct CHALLENGE request packet. */
   export interface Options extends ContextBase, Fields {
-    /** Certificate request session ID. */
+    /** Request session ID. */
     requestId: Uint8Array;
 
     /**
-     * Certificate request session encrypter.
+     * Request session encrypter.
      * @see makeSessionKey
      */
     sessionEncrypter: LLEncrypt.Key;
 
     /**
-     * Certificate request session local decrypter.
+     * Request session local decrypter.
      * @see makeSessionKey
      */
     sessionLocalDecrypter: LLDecrypt.Key;

packages/ndncert/src/packet/challenge-response.ts

@@ -78,7 +78,7 @@ function checkFieldsByStatus({
 export namespace ChallengeResponse {
   /** Fields of CHALLENGE response packet. */
   export interface Fields {
-    /** Certificate request session status. */
+    /** Request session status. */
     status: Status;
 
     /** Challenge specific status string. */
@@ -109,13 +109,13 @@ export namespace ChallengeResponse {
     profile: CaProfile;
 
     /**
-     * Certificate request session encrypter.
+     * Request session encrypter.
      * @see makeSessionKey
      */
     sessionEncrypter: LLEncrypt.Key;
 
     /**
-     * Certificate request session local decrypter.
+     * Request session local decrypter.
      * @see makeSessionKey
      */
     sessionLocalDecrypter: LLDecrypt.Key;

packages/ndncert/src/packet/error-msg.ts

@@ -4,6 +4,7 @@ import { toUtf8 } from "@ndn/util";
 
 import { ErrorCode, TT } from "./an";
 
+/** ErrorMessage packet. */
 export interface ErrorMsg {
   errorCode: number;
   errorInfo: string;
@@ -36,7 +37,7 @@ export namespace ErrorMsg {
   }
 
   /** Throw an exception if the given packet is an error message packet. */
-  export function throwOnError(data: Data) {
+  export function throwOnError(data: Data): void {
     let e: ErrorMsg | undefined;
     try { e = fromData(data); } catch { return; }
     throw new Error(`CA response error ${e.errorCode}: ${e.errorInfo}`);

packages/ndncert/src/packet/new-response.ts

@@ -45,7 +45,7 @@ export namespace NewResponse {
     /** Salt for session key generation. */
     salt: Uint8Array;
 
-    /** Certificate request session ID. */
+    /** Request session ID. */
     requestId: Uint8Array;
 
     /** Available challenge types. */

packages/ndncert/src/server/challenge.ts

@@ -7,7 +7,7 @@ export interface ServerChallenge<State = any> {
   /** Challenge module identifier. */
   readonly challengeId: string;
 
-  /** Time limit (millis). */
+  /** Time limit, in milliseconds. */
   readonly timeLimit: number;
 
   /** Retry limit, including the initial attempt. */
@@ -17,15 +17,28 @@ export interface ServerChallenge<State = any> {
   process: (request: ChallengeRequest, context: ServerChallengeContext<State>) => Promise<ServerChallengeResponse>;
 }
 
+/** Contextual information for challenge processing. */
 export interface ServerChallengeContext<State = unknown> {
+  /** CA profile packet. */
   readonly profile: CaProfile;
+
+  /** Subject name of the requested certificate. */
   readonly subjectName: Name;
+
+  /** Key name of the requested certificate. */
   readonly keyName: Name;
 
-  /** Server-side state of the challenge on a request session. */
+  /**
+   * Server-side state of the challenge on a request session.
+   *
+   * For a newly selected challenge, this field is `undefined`.
+   * The challenge module can store state information in this field and retrieve it when processing
+   * subsequently CHALLENGE request packets.
+   */
   challengeState?: State;
 }
 
+/** Result of challenge processing. */
 export interface ServerChallengeResponse {
   /**
    * If true, challenge has succeeded and server will issue the certificate.
@@ -34,7 +47,7 @@ export interface ServerChallengeResponse {
   success?: boolean;
 
   /**
-   * If true, this request counts as one failed retry.
+   * If true, this request counts as one failed try and decrements remaining tries.
    * @default false
    */
   decrementRetry?: boolean;
@@ -45,5 +58,6 @@ export interface ServerChallengeResponse {
    */
   challengeStatus?: string;
 
+  /** Parameter key-value pairs to convey to the client. */
   parameters?: ParameterKV;
 }

packages/ndncert/src/server/email-challenge_node.ts

@@ -2,7 +2,7 @@ import { AltUri } from "@ndn/naming-convention2";
 import type { Name } from "@ndn/packet";
 import { fromUtf8, toHex } from "@ndn/util";
 import type { SendMailOptions, SentMessageInfo, Transporter } from "nodemailer";
-import type { OverrideProperties } from "type-fest";
+import type { OverrideProperties, Promisable } from "type-fest";
 
 import type { ChallengeRequest } from "../packet/mod";
 import type { ServerChallengeContext, ServerChallengeResponse } from "./challenge";
@@ -100,7 +100,7 @@ export namespace ServerEmailChallenge {
    * Callback to determine whether the owner of `email` is allowed to obtain a certificate
    * of `newSubjectName`. It should throw to disallow assignment.
    */
-  export type AssignmentPolicy = (newSubjectName: Name, email: string) => Promise<void>;
+  export type AssignmentPolicy = (newSubjectName: Name, email: string) => Promisable<void>;
 
   /**
    * Email template.

packages/ndncert/src/server/server.ts

@@ -262,7 +262,7 @@ export class Server {
     };
   }
 
-  private readonly lookupContext = async (requestId: Uint8Array) => this.state.get(requestId);
+  private readonly lookupContext = (requestId: Uint8Array) => this.state.get(requestId);
 
   private deleteContext({ requestId }: ChallengeRequest) {
     this.state.delete(requestId);