@rdlabo/workers-hono-kit 0.2.0 → 0.2.1

package/src/firebase/remote-verifier.ts

@@ -4,16 +4,43 @@ 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,

package/src/http/nest-error.ts

@@ -2,8 +2,11 @@ import type { Context, Env } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 
 /**
- * NestJS の既定例外フィルタが付ける reason phrase（フリート共通 = receptray/winecode/foodlabel の
- * REASON_PHRASE / DEFAULT_MESSAGES と同一）。3 repo がそれぞれ手書きしていたものを一本化する。
+ * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
+ *
+ * @remarks
+ * Mirrors the `error` field values NestJS produces for common client-error statuses, so a Hono app can
+ * return byte-identical error bodies. Used as the default `reasonPhrases` map by {@link createNestErrorHandler}.
  */
 export const NEST_REASON_PHRASES: Record<number, string> = {
   400: 'Bad Request',
@@ -12,64 +15,100 @@ export const NEST_REASON_PHRASES: Record<number, string> = {
   404: 'Not Found',
 };
 
-/** 想定外エラーの通報先に渡す文脈（request id 相関など）。フリート共通の最小形。 */
+/**
+ * Contextual metadata passed to an {@link ErrorReporter} when reporting an unexpected error.
+ */
 export interface ErrorReportContext {
+  /** Correlation id for the failing request, if one is tracked. */
   requestId?: string;
 }
 
 /**
- * 想定外エラーの通報関数（Sentry 等）の型。各 repo の container.reportError がこの形。
- * `createNestErrorHandler({ onUnhandledError })` に `(err, c) => reporter(err, { requestId: c.get('requestId') })`
- * の形で差し込む。Sentry 呼び出し自体は各 repo（@sentry/cloudflare は workers-hono-kit に持ち込まない）。
+ * Signature of a function that reports an unexpected (non-HTTP) error to an external sink such as Sentry.
+ *
+ * @remarks
+ * Wire it into {@link createNestErrorHandler} via `onUnhandledError`, e.g.
+ * `(err, c) => reporter(err, { requestId: c.get('requestId') })`. The reporting client itself is
+ * intentionally kept out of this kit; the consumer supplies the implementation.
+ *
+ * @param error - The thrown value being reported.
+ * @param context - Optional correlation context for the failing request.
  */
 export type ErrorReporter = (error: unknown, context?: ErrorReportContext) => void;
 
-/** http エラーとみなされた値から status / message / body を読むための最小形。 */
+/**
+ * Minimal shape read from a value treated as an HTTP error: its status, message, and optional body.
+ *
+ * @internal
+ */
 interface HttpErrorLike {
+  /** HTTP status code to respond with. */
   status: ContentfulStatusCode;
+  /** Human-readable error message placed in the response body. */
   message: string;
-  /** repo 固有 body の脱出口（winecode の HttpError.body 相当）。あればそのまま render する。 */
+  /**
+   * Escape hatch for a fully custom response body. When present, it is rendered verbatim instead of
+   * the NestJS-shaped body.
+   */
   body?: unknown;
 }
 
+/**
+ * Options controlling how {@link createNestErrorHandler} shapes error responses.
+ *
+ * @typeParam E - The Hono environment type, so `onUnhandledError` receives a correctly typed context.
+ */
 export interface NestErrorHandlerOptions<E extends Env = Env> {
-  /** reason phrase map。既定 `NEST_REASON_PHRASES`。 */
+  /** Status-to-reason-phrase map for the `error` field. Defaults to {@link NEST_REASON_PHRASES}. */
   reasonPhrases?: Record<number, string>;
   /**
-   * `error` フィールドを省いて `{ statusCode, message }` のみ返す status。既定 `[401]`
-   * （NestJS の generic `HttpException(msg, 401)` は `error` を持たない）。
+   * Statuses that return only `{ statusCode, message }`, omitting the `error` field. Defaults to `[401]`,
+   * matching NestJS where a generic `HttpException(msg, 401)` carries no `error`.
    */
   bareStatuses?: readonly number[];
   /**
-   * 非 bare body のフィールド順序。既定 `'statusCode-first'`（= NestJS canonical / receptray・winecode）。
-   * **foodlabel は `'message-first'`** を指定して `{ message, error, statusCode }` の byte-parity を保つ。
+   * Field order of the non-bare error body. Defaults to `'statusCode-first'` (the NestJS canonical order).
+   * Use `'message-first'` to emit `{ message, error, statusCode }` when byte parity requires it.
    */
   fieldOrder?: 'statusCode-first' | 'message-first';
   /**
-   * reasonPhrases に無い（かつ bare でない）status の `error` フォールバック。既定 `undefined`
-   * （= reason 無しなら `error` を省く）。**winecode は `'Error'`** を指定し、全 status で `error` を必ず出す
-   * （NestJS 既定例外フィルタの「error は常に存在」を忠実再現）。
+   * Fallback `error` value for statuses that are neither bare nor present in `reasonPhrases`. Defaults to
+   * `undefined`, meaning the `error` field is omitted when no reason phrase is known. Set to a string such
+   * as `'Error'` to always include an `error` field, faithfully reproducing the NestJS default exception
+   * filter behavior where `error` is always present.
    */
   fallbackReason?: string;
   /**
-   * http エラー判定。既定は hono の `HTTPException`。
-   * **winecode は独自 `HttpError` を使う**ため `(e) => e instanceof HttpError` を渡す。
+   * Predicate identifying which thrown values are HTTP errors. Defaults to detecting Hono's `HTTPException`.
+   * Override it (e.g. `(e) => e instanceof MyHttpError`) when the app throws a custom HTTP error type.
    */
   isHttpError?: (err: unknown) => err is HttpErrorLike;
   /**
-   * http エラーでない（= 想定外）エラーを 500 で返す前に呼ぶフック（Sentry 通報など）。
-   * **receptray は `container.reportError?.(err, { requestId })`** を差し込む。例外は握り潰す。
+   * Hook invoked before an unexpected (non-HTTP) error is returned as a 500, typically used to report the
+   * error (e.g. to Sentry). Any exception thrown by this hook is swallowed so reporting cannot alter the
+   * error response.
    */
   onUnhandledError?: (err: unknown, c: Context<E>) => void;
-  /** 想定外エラー時の 500 body。既定 `{ statusCode: 500, message: 'Internal server error' }`。 */
+  /**
+   * Response body for unexpected errors returned as 500. Defaults to
+   * `{ statusCode: 500, message: 'Internal server error' }`.
+   */
   internalServerErrorBody?: unknown;
 }
 
 /**
- * hono の `HTTPException` を **構造的に**判定する（`instanceof` ではない）。workers-hono-kit は consumer に
- * symlink 同梱されるため、workers-hono-kit が解決する `hono` と consumer の `hono` が別インスタンスになり得る
- * （別コピーの HTTPException は `instanceof` で一致しない）。`getResponse()` と数値 `status` を持つかで
- * 判定すればモジュール境界をまたいでも、prod バンドルでも安定する。
+ * Structurally detect Hono's `HTTPException` without relying on `instanceof`.
+ *
+ * @remarks
+ * When this kit is symlinked into a consumer, the `hono` instance it resolves can differ from the
+ * consumer's `hono`, so an `HTTPException` from one copy fails an `instanceof` check against the other.
+ * Detecting the presence of a `getResponse()` method and a numeric `status` is stable across module
+ * boundaries and production bundles.
+ *
+ * @param err - The thrown value to test.
+ * @returns `true` when `err` looks like a Hono `HTTPException`.
+ *
+ * @internal
  */
 const isHTTPException = (err: unknown): err is HttpErrorLike =>
   err instanceof Error &&
@@ -77,13 +116,32 @@ const isHTTPException = (err: unknown): err is HttpErrorLike =>
   typeof (err as { status?: unknown }).status === 'number';
 
 /**
- * NestJS の例外フィルタ相当の Hono `onError` ハンドラを作る（フリート共通）。
- * - http エラー（既定 `HTTPException`）→ Nest 形 body にマップ。`body` を持つ場合はそれを verbatim で返す。
- * - bareStatuses（既定 401）は `error` フィールド無し。
- * - それ以外（想定外エラー）→ `onUnhandledError` 通報 + `console.error` + 500。
+ * Create a Hono `onError` handler that maps thrown errors to NestJS-shaped error JSON.
  *
- * `app.onError(createNestErrorHandler(...))` の形で使う。各 repo の parity 差異（body 順序・
- * エラー型・通報フック）は options で吸収し、本体の分岐ロジックは共有する。
+ * @remarks
+ * Reproduces the NestJS default exception filter so a Hono app returns byte-identical error bodies:
+ * - HTTP errors (by default `HTTPException`) are mapped to a NestJS-shaped body; if the error carries a
+ *   custom `body`, that body is returned verbatim.
+ * - Statuses listed in `bareStatuses` (default `[401]`) omit the `error` field.
+ * - Any other (unexpected) error triggers `onUnhandledError`, is logged via `console.error`, and returns 500.
+ *
+ * Per-app differences in body field order, HTTP error type, and reporting hook are absorbed through
+ * {@link NestErrorHandlerOptions}, while the branching logic stays shared.
+ *
+ * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
+ * @param options - Overrides for reason phrases, bare statuses, field order, error detection, and reporting.
+ * @returns A handler suitable for `app.onError(...)`.
+ *
+ * @example
+ * ```ts
+ * app.onError(
+ *   createNestErrorHandler({
+ *     fieldOrder: 'message-first',
+ *     fallbackReason: 'Error',
+ *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
+ *   }),
+ * );
+ * ```
  */
 export function createNestErrorHandler<E extends Env = Env>(options: NestErrorHandlerOptions<E> = {}) {
   const {
@@ -98,12 +156,12 @@ export function createNestErrorHandler<E extends Env = Env>(options: NestErrorHa
 
   return (err: Error, c: Context<E>): Response => {
     if (isHttpError(err)) {
-      // repo 固有 body の脱出口（winecode）。
+      // Escape hatch for a custom error body: render it verbatim.
       if (err.body !== undefined) {
         return c.json(err.body as object, err.status);
       }
-      // reasonPhrases[status] は型上 string だが noUncheckedIndexedAccess 無効のため実際は未定義になり得る。
-      // 未登録 status の fallbackReason フォールバックは意図的。
+      // reasonPhrases[status] is typed as string, but with noUncheckedIndexedAccess disabled it can be
+      // undefined at runtime. The fallbackReason fallback for unregistered statuses is intentional.
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       const reason = bareStatuses.includes(err.status) ? undefined : (reasonPhrases[err.status] ?? fallbackReason);
       if (reason === undefined) {
@@ -119,7 +177,7 @@ export function createNestErrorHandler<E extends Env = Env>(options: NestErrorHa
     try {
       onUnhandledError?.(err, c);
     } catch {
-      // 通報はエラーレスポンスの挙動を変えてはならない。
+      // Reporting must never change the behavior of the error response.
     }
     console.error(err);
     return c.json(internalServerErrorBody as object, 500);
@@ -127,8 +185,19 @@ export function createNestErrorHandler<E extends Env = Env>(options: NestErrorHa
 }
 
 /**
- * Express/Nest 既定の未マッチルート 404 body を返す `notFound` ハンドラ。
- * `app.notFound(nestNotFoundHandler)` で使う（receptray/winecode は未実装の parity ギャップ）。
+ * Hono `notFound` handler that returns the canonical Express/NestJS unmatched-route 404 body.
+ *
+ * @remarks
+ * Produces `{ message: "Cannot <METHOD> <path>", error: 'Not Found', statusCode: 404 }`, matching the
+ * NestJS default 404 response so unmatched routes stay byte-identical.
+ *
+ * @param c - The Hono request context for the unmatched route.
+ * @returns A 404 JSON response.
+ *
+ * @example
+ * ```ts
+ * app.notFound(nestNotFoundHandler);
+ * ```
  */
 export function nestNotFoundHandler(c: Context): Response {
   return c.json(

package/src/http/user-protocol.ts

@@ -1,14 +1,34 @@
 import type { Context } from 'hono';
 
-/** クライアントの IP / UA（NestJS の @UserProtocol デコレータ相当）。 */
+/**
+ * The client's network identity: IP address and user agent.
+ *
+ * @remarks
+ * Equivalent to the data a NestJS `@UserProtocol` decorator would expose, so a Hono app can persist the
+ * same client metadata. Both fields are nullable to map directly onto nullable database columns.
+ */
 export interface IUserProtocol {
+  /** Client IP address, or `null` when no source header is present. */
   ipAddress: string | null;
+  /** Client user-agent string, or `null` when the `User-Agent` header is absent. */
   userAgent: string | null;
 }
 
 /**
- * Hono Context からクライアント IP / UA を取得する。Cloudflare は実 IP を `CF-Connecting-IP` に入れる
- * （`X-Forwarded-For` はフォールバック）。未取得は null（DB の nullable カラムにそのまま入る）。
+ * Read the client's IP address and user agent from the Hono request context.
+ *
+ * @remarks
+ * On Cloudflare the real client IP is provided in `CF-Connecting-IP`, with `X-Forwarded-For` used as a
+ * fallback. Missing values resolve to `null` so they map cleanly onto nullable storage.
+ *
+ * @param c - The Hono request context to read headers from.
+ * @returns The client's IP address and user agent for the current request.
+ *
+ * @example
+ * ```ts
+ * const { ipAddress, userAgent } = getUserProtocol(c);
+ * await auditLog.insert({ ipAddress, userAgent });
+ * ```
  */
 export const getUserProtocol = (c: Context): IUserProtocol => ({
   ipAddress: c.req.header('cf-connecting-ip') ?? c.req.header('x-forwarded-for') ?? null,

package/src/index.ts

@@ -1,6 +1,14 @@
-// @rdlabo/workers-hono-kit — フリート共通のインフラ層ヘルパ（receptray / winecode / foodlabel）。
-// ドメイン・DB・各 repo 固有の parity 差異（auth エラー status/body、secretId、Secret スキーマ）は
-// 各 repo 側に残し、ここには「設定注入で汎用化できるインフラ」だけを置く。
+/**
+ * `@rdlabo/workers-hono-kit` — infrastructure-layer helpers for Hono on Cloudflare Workers.
+ *
+ * This package collects reusable, configuration-injected building blocks (HTTP middleware,
+ * caching, Stripe, Drizzle helpers, AI Gateway, AWS/Firebase integrations) that can be shared
+ * across services. Domain logic, database schemas, and application-specific behavior are
+ * intentionally left to the consuming application; only generic infrastructure that can be made
+ * reusable through dependency/configuration injection lives here.
+ *
+ * @packageDocumentation
+ */
 
 // middleware
 export { finalizeResponse } from './middleware/finalize-response.js';

package/src/middleware/auth.ts

@@ -4,34 +4,95 @@ import type { ContentfulStatusCode } from 'hono/utils/http-status';
 import { getAppInfo } from '../http/app-info.js';
 import type { AppInfo } from '../http/app-info.js';
 
+/**
+ * Configuration for {@link createAuthMiddleware}.
+ *
+ * @typeParam E - The Hono `Env` (bindings/variables) of the application.
+ * @typeParam Verified - The value produced by {@link AuthMiddlewareOptions.verify} (e.g. a decoded token or user record).
+ * @typeParam Id - The resolved user identifier type.
+ */
 export interface AuthMiddlewareOptions<E extends Env, Verified, Id = unknown> {
-  /** ID トークンを載せるヘッダ。既定 `'x-amz-security-token'`（フリート共通）。 */
+  /** Header carrying the ID token. Defaults to `'x-amz-security-token'`. */
   tokenHeader?: string;
-  /** 生トークンを検証して record/decoded を返す。無効なら throw / reject すること。 */
+  /**
+   * Verify the raw token and return the decoded value or user record.
+   *
+   * @param token - The raw token read from {@link AuthMiddlewareOptions.tokenHeader} (empty string if absent).
+   * @param c - The current Hono context.
+   * @returns The verified value passed to {@link AuthMiddlewareOptions.resolveUserId}/{@link AuthMiddlewareOptions.setContext}.
+   * @throws If the token is invalid; rejecting/throwing triggers the failure path.
+   */
   verify: (token: string, c: Context<E>) => Promise<Verified>;
   /**
-   * DB userId を解決（必要なら新規作成）する。**省略すると token-only**（検証のみ・login 用）になる。
-   * create-on-miss（`getUserIdFromFirebase(...).catch(() => createUser(...))`）は repo 側でここに合成する。
+   * Resolve the database user id (creating the user if necessary).
+   *
+   * @remarks
+   * Omit this to run in **token-only** mode (verification only, e.g. for login). Create-on-miss
+   * behavior (such as `getUserId(...).catch(() => createUser(...))`) should be composed here by the
+   * caller.
+   *
+   * @param verified - The value returned by {@link AuthMiddlewareOptions.verify}.
+   * @param c - The current Hono context.
+   * @param appInfo - The resolved application info for the request.
+   * @returns The resolved user id.
    */
   resolveUserId?: (verified: Verified, c: Context<E>, appInfo: AppInfo) => Promise<Id>;
-  /** 検証結果を c.var に載せる。repo 固有の var 名（`decodedToken` / `userRecord` / `userProtocol` 等）を注入する。 */
+  /**
+   * Store the verification result on the context variables.
+   *
+   * @remarks
+   * Inject the application-specific variable names here (e.g. `decodedToken`, `userRecord`, `userProtocol`).
+   *
+   * @param c - The current Hono context.
+   * @param data - The verified value, resolved app info, and (when available) the user id.
+   */
   setContext: (c: Context<E>, data: { verified: Verified; appInfo: AppInfo; userId?: Id }) => void;
   /**
-   * 失敗時の挙動。既定は `throw new HTTPException(failureStatus, { message: failureMessage })`
-   * （foodlabel/receptray と同形）。**winecode は `c.json(BODY, n)` を返す**ため上書きする。
+   * Override the failure behavior.
+   *
+   * @remarks
+   * Defaults to `throw new HTTPException(failureStatus, { message: failureMessage })`. Provide this to
+   * return a custom `Response` instead (e.g. `c.json(body, status)`).
+   *
+   * @param err - The error thrown during verification/resolution.
+   * @param c - The current Hono context.
+   * @returns The failure response to send.
    */
   onFailure?: (err: unknown, c: Context<E>) => Response;
-  /** 既定 onFailure の status。既定 `403`（token-only の 401 等は repo が上書き）。 */
+  /** Status used by the default `onFailure`. Defaults to `403`. */
   failureStatus?: ContentfulStatusCode;
-  /** 既定 onFailure の message。既定 `'Forbidden resource'`。 */
+  /** Message used by the default `onFailure`. Defaults to `'Forbidden resource'`. */
   failureMessage?: string;
 }
 
 /**
- * NestJS の AuthGuard / TokenGuard 相当の認証 middleware を作る（フリート共通）。
- * スケルトン（ヘッダ読取 → verify → getAppInfo → resolveUserId → setContext、失敗で console.error +
- * onFailure）を共有し、repo 固有部分（verify / userId 解決 / var 名 / 失敗レスポンス）だけ注入させる。
- * `resolveUserId` を省けば token-only middleware になる。
+ * Create an authentication middleware equivalent to a NestJS `AuthGuard` / `TokenGuard`.
+ *
+ * The middleware runs a fixed skeleton — read the token header, `verify`, `getAppInfo`,
+ * `resolveUserId`, `setContext`, and on error `console.error` then `onFailure` — while the
+ * application injects the variable parts (token verification, user-id resolution, context variable
+ * names, and the failure response). Omitting {@link AuthMiddlewareOptions.resolveUserId} yields a
+ * token-only middleware.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @typeParam Verified - The value produced by `verify`.
+ * @typeParam Id - The resolved user identifier type.
+ * @param options - The verification, resolution, and failure hooks; see {@link AuthMiddlewareOptions}.
+ * @returns A {@link MiddlewareHandler} that authenticates the request and populates the context.
+ * @throws HTTPException From the default failure handler when `onFailure` is not supplied.
+ *
+ * @example
+ * ```ts
+ * const auth = createAuthMiddleware({
+ *   verify: (token, c) => verifier.verifyIdToken(token),
+ *   resolveUserId: (decoded) => findUserId(decoded.uid),
+ *   setContext: (c, { verified, userId }) => {
+ *     c.set('decodedToken', verified);
+ *     c.set('userId', userId);
+ *   },
+ * });
+ * app.use('/api/*', auth);
+ * ```
  */
 export function createAuthMiddleware<E extends Env = Env, Verified = unknown, Id = unknown>(
   options: AuthMiddlewareOptions<E, Verified, Id>,
@@ -54,8 +115,9 @@ export function createAuthMiddleware<E extends Env = Env, Verified = unknown, Id
       const userId = resolveUserId ? await resolveUserId(verified, c, appInfo) : undefined;
       setContext(c, { verified, appInfo, userId });
     } catch (e) {
-      // Nest guard が false → ForbiddenException('Forbidden resource')。原因をログし、既定では throw して
-      // app.onError に Nest 形 body を描かせる（repo は onFailure で return 形に上書き可能）。
+      // Equivalent to a guard returning false → ForbiddenException('Forbidden resource'). Log the
+      // cause and, by default, throw so the app's onError renders the error body (callers can
+      // override with onFailure to return a custom response instead).
       console.error(e);
       if (onFailure) {
         return onFailure(e, c);