@rdlabo/workers-hono-kit 0.1.0 → 0.2.1

package/src/firebase/firebase-verifier.ts

@@ -1,15 +1,64 @@
-/** Firebase boundary replacing the firebase-admin Auth surface used by `/api`. */
+/**
+ * Decoded Firebase ID token payload.
+ *
+ * Shaped to match the subset of `firebase-admin`'s `DecodedIdToken` that consumers
+ * typically rely on: a stable `uid` plus an optional `email`. The index signature keeps
+ * every other JWT claim (e.g. `name`, `picture`, custom claims) accessible without
+ * enumerating them here.
+ *
+ * @remarks
+ * This is the return type of {@link FirebaseVerifier.verifyIdToken}. The `uid` is derived
+ * from the token's `sub` claim.
+ */
 export interface DecodedIdToken {
+  /** The authenticated user's unique id, taken from the token's `sub` claim. */
   uid: string;
+  /** The user's email address, when present on the token. */
   email?: string;
+  /** Any additional JWT claim carried by the token (custom claims, `name`, `picture`, ...). */
   [claim: string]: unknown;
 }
 
+/**
+ * Abstract authentication boundary that replaces the `firebase-admin` Auth surface
+ * (`verifyIdToken` / `getUser` / `deleteUser`) for environments where the Node SDK cannot
+ * run, such as Cloudflare Workers.
+ *
+ * @remarks
+ * Implementations verify Firebase ID tokens and look up or delete accounts without the
+ * `firebase-admin` Node dependency. See `JoseFirebaseVerifier` for the `jose`-based
+ * implementation and the `createRemoteFirebaseVerifier` / `createServiceAccountVerifier`
+ * factories for ready-made instances.
+ */
 export interface FirebaseVerifier {
-  /** Mirrors firebase-admin getAuth().verifyIdToken(). Throws on invalid token. */
+  /**
+   * Verify a Firebase ID token and return its decoded payload.
+   *
+   * Mirrors `firebase-admin` `getAuth().verifyIdToken()`.
+   *
+   * @param idToken - The raw Firebase ID token (JWT) to verify.
+   * @returns The decoded token payload.
+   * @throws If the token signature, issuer, audience, expiry, or other required claims are invalid.
+   */
   verifyIdToken(idToken: string): Promise<DecodedIdToken>;
-  /** Mirrors getAuth().getUser(); returns null when the user is absent. */
+  /**
+   * Look up a user record by uid.
+   *
+   * Mirrors `firebase-admin` `getAuth().getUser()`.
+   *
+   * @param uid - The user's unique id.
+   * @returns The user's `uid` and optional `email`, or `null` when the user does not exist.
+   * @throws If the backing user-management service is not configured or the lookup fails.
+   */
   getUser(uid: string): Promise<{ uid: string; email?: string } | null>;
-  /** Mirrors getAuth().deleteUser(). */
+  /**
+   * Delete a user by uid.
+   *
+   * Mirrors `firebase-admin` `getAuth().deleteUser()`.
+   *
+   * @param uid - The user's unique id.
+   * @returns A promise that resolves once the user has been deleted.
+   * @throws If the backing user-management service is not configured or the deletion fails.
+   */
   deleteUser(uid: string): Promise<void>;
 }

package/src/firebase/identity-toolkit.ts

@@ -1,28 +1,63 @@
 import { SignJWT, importPKCS8 } from 'jose';
 
 /**
- * Minimal Google Identity Toolkit client for the operations firebase-admin performed
- * that aren't token verification: accounts:lookup (getUser) and accounts:delete
- * (deleteUser). Replaces the firebase-admin Node SDK, which won't run on workerd.
+ * Minimal service-account credential consumed by {@link IdentityToolkit}.
  *
- * Auth: sign a JWT assertion with the service-account private key (jose), exchange it for
- * an OAuth2 access token, then call the REST API. Tokens are cached in-process.
+ * @remarks
+ * Corresponds to the relevant fields of a Google service-account JSON key file.
  */
 export interface ServiceAccount {
+  /** The service account's email, used as the JWT assertion issuer and subject. */
   client_email: string;
+  /** The PEM-encoded PKCS#8 RSA private key used to sign the OAuth2 assertion. */
   private_key: string;
+  /** The Google/Firebase project id the Identity Toolkit calls target. */
   project_id: string;
 }
 
+/** Google OAuth2 token endpoint used to exchange a signed JWT assertion for an access token. */
 const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+/** Base URL of the Google Identity Toolkit v1 REST API. */
 const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
+/** OAuth2 scopes required for Identity Toolkit account lookup and deletion. */
 const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
 
+/**
+ * Minimal Google Identity Toolkit REST client for the user-management operations that token
+ * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
+ *
+ * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
+ * Workers (workerd).
+ *
+ * @remarks
+ * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service
+ * account's private key (via `jose`), exchanged at the OAuth2 token endpoint for an access
+ * token, and that token is then used to call the REST API. Access tokens are cached in-process
+ * and reused until shortly before they expire.
+ */
 export class IdentityToolkit {
+  /** Cached OAuth2 access token and its absolute expiry (Unix seconds), or `null` when none. */
   private accessToken: { value: string; expiresAt: number } | null = null;
 
+  /**
+   * Create a client bound to a single service account.
+   *
+   * @param sa - The service-account credential used to authenticate REST calls.
+   */
   constructor(private readonly sa: ServiceAccount) {}
 
+  /**
+   * Return a valid OAuth2 access token, minting a new one when the cache is empty or expiring.
+   *
+   * Signs a short-lived JWT assertion with the service-account key and exchanges it at the
+   * Google OAuth2 token endpoint. The result is cached and reused while it remains valid
+   * (with a 60-second safety margin).
+   *
+   * @param nowSeconds - The current Unix time in seconds, used for cache validity and JWT timestamps.
+   * @returns A bearer access token for the Identity Toolkit API.
+   * @throws If the token exchange request fails.
+   * @internal
+   */
   private async getAccessToken(nowSeconds: number): Promise<string> {
     if (this.accessToken && this.accessToken.expiresAt > nowSeconds + 60) {
       return this.accessToken.value;
@@ -53,6 +88,15 @@ export class IdentityToolkit {
     return json.access_token;
   }
 
+  /**
+   * Look up a user record by uid via the `accounts:lookup` endpoint.
+   *
+   * @param uid - The user's unique id (`localId`).
+   * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+   * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+   *   or no matching user is returned.
+   * @throws If acquiring an access token fails.
+   */
   async lookup(uid: string, nowSeconds: number): Promise<{ uid: string; email?: string } | null> {
     const token = await this.getAccessToken(nowSeconds);
     const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:lookup`, {
@@ -68,6 +112,14 @@ export class IdentityToolkit {
     return user ? { uid: user.localId, email: user.email } : null;
   }
 
+  /**
+   * Delete a user by uid via the `accounts:delete` endpoint.
+   *
+   * @param uid - The user's unique id (`localId`).
+   * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+   * @returns A promise that resolves once the user has been deleted.
+   * @throws If acquiring an access token fails or the delete request is unsuccessful.
+   */
   async remove(uid: string, nowSeconds: number): Promise<void> {
     const token = await this.getAccessToken(nowSeconds);
     const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:delete`, {

package/src/firebase/jose-firebase-verifier.ts

@@ -1,26 +1,64 @@
 import { jwtVerify } from 'jose';
 import type { CryptoKey, JWK, JWTVerifyGetKey, KeyObject } from 'jose';
-import type { DecodedIdToken, FirebaseVerifier } from './firebase-verifier';
-import type { IdentityToolkit } from './identity-toolkit';
+import type { DecodedIdToken, FirebaseVerifier } from './firebase-verifier.js';
+import type { IdentityToolkit } from './identity-toolkit.js';
 
-// jose v6 removed `KeyLike`; the verification key is a static key (prod: createRemoteJWKSet,
-// test: a CryptoKey) or a dynamic getKey function. Union both overloads' key params.
+/**
+ * Union of every key shape `jose`'s `jwtVerify` accepts.
+ *
+ * @remarks
+ * `jose` v6 removed `KeyLike`, so the verification key is modelled here as either a static
+ * key (production uses `createRemoteJWKSet`, tests use a generated `CryptoKey`) or a dynamic
+ * `JWTVerifyGetKey` resolver function. This union covers both `jwtVerify` overloads' key
+ * parameters.
+ *
+ * @internal
+ */
 type KeyInput = CryptoKey | KeyObject | JWK | Uint8Array | JWTVerifyGetKey;
 
 /**
- * Replaces firebase-admin getAuth().verifyIdToken() with jose RS256 verification against
- * Google's securetoken JWKS. Mirrors the admin SDK's checks: issuer/audience = projectId,
- * RS256, a non-empty subject (the uid), and a valid auth_time.
- *
- * - prod: keyResolver = createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL)).
- * - test: keyResolver = the generated public key (offline, no network).
+ * URL of Google's securetoken JWKS endpoint, which serves the public keys used to sign
+ * Firebase ID tokens.
  *
- * getUser/deleteUser delegate to Identity Toolkit REST (network); absent it throws.
+ * @remarks
+ * Passed to `createRemoteJWKSet` (see `createRemoteFirebaseVerifier`) so RS256 signatures can
+ * be verified against Google's rotating public keys.
  */
 export const SECURETOKEN_JWK_URL =
   'https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com';
 
+/**
+ * Verifies Firebase ID tokens with `jose` RS256 against Google's securetoken JWKS, and
+ * optionally looks up or deletes users via the Google Identity Toolkit REST API.
+ *
+ * This replaces the `firebase-admin` Auth surface (`verifyIdToken` / `getUser` /
+ * `deleteUser`) in environments where the Node SDK cannot run, such as Cloudflare Workers.
+ * Token verification mirrors the admin SDK's checks: issuer and audience equal to the
+ * project id, an RS256 signature, a non-empty subject (the uid), and a valid `auth_time`.
+ *
+ * @remarks
+ * The verification key is supplied as `keyResolver`:
+ * - Production: `createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL))`, which fetches and caches
+ *   Google's public keys.
+ * - Tests: a generated public key, allowing fully offline verification with no network.
+ *
+ * `getUser` / `deleteUser` delegate to {@link IdentityToolkit} (a network call); when no
+ * `IdentityToolkit` is configured they throw.
+ *
+ * @see {@link FirebaseVerifier} for the abstract boundary this implements.
+ */
 export class JoseFirebaseVerifier implements FirebaseVerifier {
+  /**
+   * Create a verifier.
+   *
+   * @param opts - Verifier configuration.
+   * @param opts.projectId - The Firebase project id, used as both the expected token issuer
+   *   (`https://securetoken.google.com/<projectId>`) and audience.
+   * @param opts.keyResolver - The RS256 verification key or a dynamic key resolver function.
+   * @param opts.identity - Optional Identity Toolkit client enabling `getUser` / `deleteUser`.
+   * @param opts.now - Optional clock returning the current time in seconds; injectable for
+   *   deterministic tests. Defaults to the system clock.
+   */
   constructor(
     private readonly opts: {
       projectId: string;
@@ -30,6 +68,18 @@ export class JoseFirebaseVerifier implements FirebaseVerifier {
     },
   ) {}
 
+  /**
+   * Verify a Firebase ID token and return its decoded payload.
+   *
+   * Checks the RS256 signature against the configured key, enforces the expected issuer and
+   * audience (the project id), and applies the admin SDK's extra checks: a non-empty string
+   * subject of at most 128 characters and an `auth_time` that is a number not in the future.
+   *
+   * @param idToken - The raw Firebase ID token (JWT) to verify.
+   * @returns The decoded payload, with `uid` set from `sub` and `email` lifted to a top-level field.
+   * @throws If the signature, issuer, audience, or expiry are invalid, if the subject is
+   *   missing/non-string/too long, or if `auth_time` is missing or in the future.
+   */
   async verifyIdToken(idToken: string): Promise<DecodedIdToken> {
     const options = {
       issuer: `https://securetoken.google.com/${this.opts.projectId}`,
@@ -51,6 +101,13 @@ export class JoseFirebaseVerifier implements FirebaseVerifier {
     return { ...payload, uid: payload.sub, email: payload.email as string | undefined };
   }
 
+  /**
+   * Look up a user record by uid via the Identity Toolkit REST API.
+   *
+   * @param uid - The user's unique id.
+   * @returns The user's `uid` and optional `email`, or `null` when the user does not exist.
+   * @throws If no Identity Toolkit client was configured on this verifier.
+   */
   async getUser(uid: string): Promise<{ uid: string; email?: string } | null> {
     if (!this.opts.identity) {
       throw new Error('Identity Toolkit not configured');
@@ -58,6 +115,13 @@ export class JoseFirebaseVerifier implements FirebaseVerifier {
     return this.opts.identity.lookup(uid, this.nowSeconds());
   }
 
+  /**
+   * Delete a user by uid via the Identity Toolkit REST API.
+   *
+   * @param uid - The user's unique id.
+   * @returns A promise that resolves once the user has been deleted.
+   * @throws If no Identity Toolkit client was configured on this verifier, or the deletion fails.
+   */
   async deleteUser(uid: string): Promise<void> {
     if (!this.opts.identity) {
       throw new Error('Identity Toolkit not configured');
@@ -65,6 +129,12 @@ export class JoseFirebaseVerifier implements FirebaseVerifier {
     await this.opts.identity.remove(uid, this.nowSeconds());
   }
 
+  /**
+   * Return the current time in seconds, using the injected clock when provided.
+   *
+   * @returns The current Unix time in seconds.
+   * @internal
+   */
   private nowSeconds(): number {
     return this.opts.now ? this.opts.now() : Math.floor(Date.now() / 1000);
   }

package/src/firebase/remote-verifier.ts

@@ -1,19 +1,46 @@
 import { createRemoteJWKSet } from 'jose';
-import { IdentityToolkit } from './identity-toolkit';
-import type { ServiceAccount } from './identity-toolkit';
-import { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './jose-firebase-verifier';
+import { IdentityToolkit } from './identity-toolkit.js';
+import type { ServiceAccount } from './identity-toolkit.js';
+import { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './jose-firebase-verifier.js';
 
 /**
- * 本番用の便宜ファクトリ。`createRemoteJWKSet` で Google securetoken の公開鍵を取り、
- * `JoseFirebaseVerifier` を返す。トークン検証のみ用途（getUser/deleteUser は不要 = Identity Toolkit 無し）。
+ * Shared remote JWKS for Google's securetoken keys.
  *
- * JWKS は URL 固定なので isolate 内で 1 度だけ生成して共有し（jose が内部メモリにキャッシュ）、
- * verifier は projectId ごとにメモ化する。winecode の旧 `verifyFirebaseIdToken`（module-level JWKS）の
- * キャッシュ挙動を保つための置換。
+ * @remarks
+ * The JWKS URL is fixed, so the set is created once per isolate and shared across verifiers
+ * (`jose` caches the fetched keys internally). Lazily initialised on first use.
+ *
+ * @internal
  */
 let jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
+/**
+ * Per-`projectId` cache of token-only verifiers, memoized for the lifetime of the isolate.
+ *
+ * @internal
+ */
 const verifiers = new Map<string, JoseFirebaseVerifier>();
 
+/**
+ * Create a token-verification-only Firebase verifier for the given project.
+ *
+ * Uses `createRemoteJWKSet` to fetch Google's securetoken public keys and returns a
+ * {@link JoseFirebaseVerifier}. This factory is for token verification only; it configures no
+ * Identity Toolkit client, so `getUser` / `deleteUser` are unavailable.
+ *
+ * @remarks
+ * The remote JWKS is created once per isolate and shared, and the returned verifier is
+ * memoized per `projectId`. This preserves the caching behaviour of a module-level JWKS so
+ * repeated calls do not re-fetch keys or allocate new verifiers.
+ *
+ * @param projectId - The Firebase project id whose tokens will be verified.
+ * @returns A verifier that validates ID tokens for `projectId`.
+ * @example
+ * ```ts
+ * const verifier = createRemoteFirebaseVerifier('my-firebase-project');
+ * const decoded = await verifier.verifyIdToken(idToken);
+ * console.log(decoded.uid);
+ * ```
+ */
 export function createRemoteFirebaseVerifier(projectId: string): JoseFirebaseVerifier {
   jwks ??= createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL));
   let verifier = verifiers.get(projectId);
@@ -24,13 +51,35 @@ export function createRemoteFirebaseVerifier(projectId: string): JoseFirebaseVer
   return verifier;
 }
 
+/**
+ * Single-entry cache of the service-account verifier, keyed by the raw service-account JSON.
+ *
+ * @internal
+ */
 let saVerifierCache: { key: string; verifier: JoseFirebaseVerifier } | null = null;
 
 /**
- * サービスアカウント JSON から検証器を作る便宜ファクトリ（receptray/tipsys hono の `firebaseFor` 相当）。
- * `getUser`/`deleteUser` のため `IdentityToolkit` を内包する点が `createRemoteFirebaseVerifier` との違い。
- * SA JSON 文字列をキーに isolate 内で 1 つだけキャッシュ（秘密が変わったときだけ再生成）し、
- * JWKS は `createRemoteFirebaseVerifier` と共有する。
+ * Create a Firebase verifier from a service-account JSON string.
+ *
+ * Unlike {@link createRemoteFirebaseVerifier}, the returned {@link JoseFirebaseVerifier}
+ * embeds an {@link IdentityToolkit} client, enabling `getUser` and `deleteUser` in addition to
+ * token verification.
+ *
+ * @remarks
+ * The verifier is cached for the lifetime of the isolate, keyed by the service-account JSON
+ * string, and is only rebuilt when that secret changes. The remote JWKS is shared with
+ * {@link createRemoteFirebaseVerifier}.
+ *
+ * @param serviceAccountJson - The service-account key as a JSON string (parsed into {@link ServiceAccount}).
+ * @returns A verifier that validates ID tokens and can look up or delete users.
+ * @throws If `serviceAccountJson` is not valid JSON.
+ * @example
+ * ```ts
+ * const verifier = createServiceAccountVerifier(env.FIREBASE_SERVICE_ACCOUNT);
+ * const decoded = await verifier.verifyIdToken(idToken);
+ * const user = await verifier.getUser(decoded.uid);
+ * await verifier.deleteUser(decoded.uid);
+ * ```
  */
 export function createServiceAccountVerifier(serviceAccountJson: string): JoseFirebaseVerifier {
   if (saVerifierCache?.key !== serviceAccountJson) {

package/src/http/app-env.ts

@@ -1,20 +1,53 @@
+/**
+ * The resolved runtime environment of the Worker.
+ */
 export type AppEnv = 'development' | 'production';
 
 /**
- * 実行環境（development / production）を解決する。フリート共通の判定。
+ * Resolve the runtime environment (development or production) from the Worker `env` binding.
+ *
+ * @remarks
+ * Cloudflare Workers have no filesystem or `child_process` at runtime, so the environment cannot be
+ * inferred from the presence of a `.git` directory the way a Node/NestJS process might. Instead, the
+ * development signal is carried in the committed launch command: `wrangler dev --var APP_ENV:development`
+ * injects `APP_ENV`, while `wrangler deploy` injects nothing. Only `env.APP_ENV === 'development'`
+ * resolves to `'development'`; every other case (including a missing binding, i.e. a production deploy)
+ * resolves to `'production'`. This "absence defaults to production" semantic keeps the safe side as the
+ * default.
+ *
+ * Because it reads from `env` rather than a request header, it works in both `fetch` and `scheduled`
+ * contexts and cannot be spoofed by an incoming request.
  *
- * NestJS `/api` は実行時 FS の `.git` 有無で判定し「git が throw → catch → 本番」としていた。
- * Workers は実行時に FS / child_process が無いため同じ手は使えない。代わりに dev シグナルを
- * **コミット済みの起動コマンド**に置く: `wrangler dev --var APP_ENV:development`（`deploy` は無注入）。
- * よって `env.APP_ENV === 'development'` の時だけ development、それ以外（注入無し＝本番デプロイ）は
- * production に倒す。これは `/api` の「absence/catch = 本番（安全側）」と同じ意味論。
+ * @param env - The Worker environment binding, or `null`/`undefined` when unavailable.
+ * @returns `'development'` only when `env.APP_ENV` is exactly `'development'`; otherwise `'production'`.
  *
- * `env` 由来なので fetch / scheduled どちらの文脈でも使え、リクエストヘッダ由来でないため詐称されない。
+ * @example
+ * ```ts
+ * export default {
+ *   fetch(req, env) {
+ *     if (resolveAppEnv(env) === 'development') {
+ *       // enable verbose logging
+ *     }
+ *   },
+ * };
+ * ```
  */
 export function resolveAppEnv(env: { APP_ENV?: string } | null | undefined): AppEnv {
   return env?.APP_ENV === 'development' ? 'development' : 'production';
 }
 
-/** production 判定のショートハンド。 */
+/**
+ * Shorthand for checking whether the resolved environment is production.
+ *
+ * @param env - The Worker environment binding, or `null`/`undefined` when unavailable.
+ * @returns `true` when {@link resolveAppEnv} resolves to `'production'`.
+ *
+ * @example
+ * ```ts
+ * if (isProductionEnv(env)) {
+ *   // skip dev-only diagnostics
+ * }
+ * ```
+ */
 export const isProductionEnv = (env: { APP_ENV?: string } | null | undefined): boolean =>
   resolveAppEnv(env) === 'production';

package/src/http/app-info.ts

@@ -1,14 +1,36 @@
 import type { Context } from 'hono';
 
-/** クライアントアプリのメタ情報（NestJS の x-amz-meta-* ヘッダ由来。3 repo 共通）。 */
+/**
+ * Client application metadata derived from the `x-amz-meta-*` request headers.
+ *
+ * @remarks
+ * Reproduces the per-request app identity that a NestJS service would expose so a Hono app
+ * can read the same client-supplied version/uuid pair without changing the wire contract.
+ */
 export interface AppInfo {
+  /** Client application version from `x-amz-meta-version`, or `null` when the header is absent. */
   version: string | null;
+  /** Client installation identifier from `x-amz-meta-uuid`, or `null` when the header is absent. */
   uuid: string | null;
 }
 
 /**
- * `x-amz-meta-version` / `x-amz-meta-uuid` ヘッダから AppInfo を読む。
- * auth middleware が per-request で c.set('appInfo', ...) する値（3 repo で同一仕様）。
+ * Read {@link AppInfo} from the `x-amz-meta-version` / `x-amz-meta-uuid` request headers.
+ *
+ * @remarks
+ * Typically called by an auth middleware that stores the result per request via
+ * `c.set('appInfo', getAppInfo(c))`. Missing headers resolve to `null` rather than throwing.
+ *
+ * @param c - The Hono request context to read headers from.
+ * @returns The client application metadata for the current request.
+ *
+ * @example
+ * ```ts
+ * app.use(async (c, next) => {
+ *   c.set('appInfo', getAppInfo(c));
+ *   await next();
+ * });
+ * ```
  */
 export const getAppInfo = (c: Context): AppInfo => ({
   version: c.req.header('x-amz-meta-version') ?? null,

package/src/http/http-status.ts

@@ -1,7 +1,11 @@
 /**
- * NestJS `@nestjs/common` の HttpStatus enum と同一。フリート（NestJS → Hono 移植）で
- * ステータスコードを Nest と同じ名前で参照するための共通定数。`/api` のレスポンス status と
- * バイト一致させる際の単一の参照元にする。
+ * HTTP status codes mirroring the `HttpStatus` enum from `@nestjs/common`.
+ *
+ * @remarks
+ * Provides a single source of truth for referencing status codes by the same names NestJS uses, so a
+ * Hono app can emit responses whose status matches a NestJS service byte-for-byte. The member set and
+ * numeric values intentionally track `@nestjs/common` rather than the IANA registry, including a few
+ * non-standard codes that NestJS ships.
  */
 export enum HttpStatus {
   CONTINUE = 100,
@@ -17,7 +21,9 @@ export enum HttpStatus {
   PARTIAL_CONTENT = 206,
   MULTI_STATUS = 207,
   ALREADY_REPORTED = 208,
+  /** Non-standard WebDAV extension carried over from NestJS. */
   CONTENT_DIFFERENT = 210,
+  /** Multiple Choices (300). Named `AMBIGUOUS` to match NestJS. */
   AMBIGUOUS = 300,
   MOVED_PERMANENTLY = 301,
   FOUND = 302,
@@ -43,13 +49,16 @@ export enum HttpStatus {
   UNSUPPORTED_MEDIA_TYPE = 415,
   REQUESTED_RANGE_NOT_SATISFIABLE = 416,
   EXPECTATION_FAILED = 417,
+  /** "I'm a teapot" (418), from RFC 2324. */
   I_AM_A_TEAPOT = 418,
+  /** Misdirected Request (421). Named `MISDIRECTED` to match NestJS. */
   MISDIRECTED = 421,
   UNPROCESSABLE_ENTITY = 422,
   LOCKED = 423,
   FAILED_DEPENDENCY = 424,
   PRECONDITION_REQUIRED = 428,
   TOO_MANY_REQUESTS = 429,
+  /** Non-standard code carried over from NestJS. */
   UNRECOVERABLE_ERROR = 456,
   INTERNAL_SERVER_ERROR = 500,
   NOT_IMPLEMENTED = 501,