@rdlabo/workers-hono-kit 0.2.0 → 0.2.1

package/dist/firebase/jose-firebase-verifier.d.ts

@@ -1,32 +1,104 @@
 import type { CryptoKey, JWK, JWTVerifyGetKey, KeyObject } from 'jose';
 import type { DecodedIdToken, FirebaseVerifier } from './firebase-verifier.js';
 import type { IdentityToolkit } from './identity-toolkit.js';
-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.
+ * 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.
  *
- * - prod: keyResolver = createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL)).
- * - test: keyResolver = the generated public key (offline, no network).
+ * @internal
+ */
+type KeyInput = CryptoKey | KeyObject | JWK | Uint8Array | JWTVerifyGetKey;
+/**
+ * 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 declare 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 declare class JoseFirebaseVerifier implements FirebaseVerifier {
     private readonly opts;
+    /**
+     * 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(opts: {
         projectId: string;
         keyResolver: KeyInput;
         identity?: IdentityToolkit;
         now?: () => number;
     });
+    /**
+     * 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.
+     */
     verifyIdToken(idToken: string): Promise<DecodedIdToken>;
+    /**
+     * 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.
+     */
     getUser(uid: string): Promise<{
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * 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.
+     */
     deleteUser(uid: string): Promise<void>;
+    /**
+     * Return the current time in seconds, using the injected clock when provided.
+     *
+     * @returns The current Unix time in seconds.
+     * @internal
+     */
     private nowSeconds;
 }
 export {};

package/dist/firebase/jose-firebase-verifier.js

@@ -1,20 +1,61 @@
 import { jwtVerify } from 'jose';
 /**
- * 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.
+ * URL of Google's securetoken JWKS endpoint, which serves the public keys used to sign
+ * Firebase ID tokens.
  *
- * - prod: keyResolver = createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL)).
- * - test: keyResolver = the generated public key (offline, no network).
- *
- * 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 {
     opts;
+    /**
+     * 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(opts) {
         this.opts = opts;
     }
+    /**
+     * 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) {
         const options = {
             issuer: `https://securetoken.google.com/${this.opts.projectId}`,
@@ -34,18 +75,38 @@ export class JoseFirebaseVerifier {
         }
         return { ...payload, uid: payload.sub, email: payload.email };
     }
+    /**
+     * 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) {
         if (!this.opts.identity) {
             throw new Error('Identity Toolkit not configured');
         }
         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) {
         if (!this.opts.identity) {
             throw new Error('Identity Toolkit not configured');
         }
         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
+     */
     nowSeconds() {
         return this.opts.now ? this.opts.now() : Math.floor(Date.now() / 1000);
     }

package/dist/firebase/remote-verifier.d.ts

@@ -1,9 +1,47 @@
 import { JoseFirebaseVerifier } from './jose-firebase-verifier.js';
+/**
+ * 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 declare function createRemoteFirebaseVerifier(projectId: string): JoseFirebaseVerifier;
 /**
- * サービスアカウント 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 declare function createServiceAccountVerifier(serviceAccountJson: string): JoseFirebaseVerifier;

package/dist/firebase/remote-verifier.js

@@ -2,15 +2,42 @@ import { createRemoteJWKSet } from 'jose';
 import { IdentityToolkit } 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;
+/**
+ * Per-`projectId` cache of token-only verifiers, memoized for the lifetime of the isolate.
+ *
+ * @internal
+ */
 const verifiers = new Map();
+/**
+ * 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) {
     jwks ??= createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL));
     let verifier = verifiers.get(projectId);
@@ -20,12 +47,34 @@ export function createRemoteFirebaseVerifier(projectId) {
     }
     return verifier;
 }
+/**
+ * Single-entry cache of the service-account verifier, keyed by the raw service-account JSON.
+ *
+ * @internal
+ */
 let saVerifierCache = 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) {
     if (saVerifierCache?.key !== serviceAccountJson) {

package/dist/http/app-env.d.ts

@@ -1,19 +1,52 @@
+/**
+ * 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 declare function resolveAppEnv(env: {
     APP_ENV?: string;
 } | null | undefined): AppEnv;
-/** 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 declare const isProductionEnv: (env: {
     APP_ENV?: string;
 } | null | undefined) => boolean;

package/dist/http/app-env.js

@@ -1,16 +1,46 @@
 /**
- * 実行環境（development / production）を解決する。フリート共通の判定。
+ * Resolve the runtime environment (development or production) from the Worker `env` binding.
  *
- * 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 = 本番（安全側）」と同じ意味論。
+ * @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.
  *
- * `env` 由来なので fetch / scheduled どちらの文脈でも使え、リクエストヘッダ由来でないため詐称されない。
+ * 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.
+ *
+ * @param env - The Worker environment binding, or `null`/`undefined` when unavailable.
+ * @returns `'development'` only when `env.APP_ENV` is exactly `'development'`; otherwise `'production'`.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   fetch(req, env) {
+ *     if (resolveAppEnv(env) === 'development') {
+ *       // enable verbose logging
+ *     }
+ *   },
+ * };
+ * ```
  */
 export function resolveAppEnv(env) {
     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) => resolveAppEnv(env) === 'production';

package/dist/http/app-info.d.ts

@@ -1,11 +1,33 @@
 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 declare const getAppInfo: (c: Context) => AppInfo;

package/dist/http/app-info.js

@@ -1,6 +1,20 @@
 /**
- * `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) => ({
     version: c.req.header('x-amz-meta-version') ?? null,

package/dist/http/http-status.d.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 declare enum HttpStatus {
     CONTINUE = 100,
@@ -17,7 +21,9 @@ export declare 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 declare 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/dist/http/http-status.js

@@ -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 var HttpStatus;
 (function (HttpStatus) {
@@ -18,7 +22,9 @@ export var HttpStatus;
     HttpStatus[HttpStatus["PARTIAL_CONTENT"] = 206] = "PARTIAL_CONTENT";
     HttpStatus[HttpStatus["MULTI_STATUS"] = 207] = "MULTI_STATUS";
     HttpStatus[HttpStatus["ALREADY_REPORTED"] = 208] = "ALREADY_REPORTED";
+    /** Non-standard WebDAV extension carried over from NestJS. */
     HttpStatus[HttpStatus["CONTENT_DIFFERENT"] = 210] = "CONTENT_DIFFERENT";
+    /** Multiple Choices (300). Named `AMBIGUOUS` to match NestJS. */
     HttpStatus[HttpStatus["AMBIGUOUS"] = 300] = "AMBIGUOUS";
     HttpStatus[HttpStatus["MOVED_PERMANENTLY"] = 301] = "MOVED_PERMANENTLY";
     HttpStatus[HttpStatus["FOUND"] = 302] = "FOUND";
@@ -44,13 +50,16 @@ export var HttpStatus;
     HttpStatus[HttpStatus["UNSUPPORTED_MEDIA_TYPE"] = 415] = "UNSUPPORTED_MEDIA_TYPE";
     HttpStatus[HttpStatus["REQUESTED_RANGE_NOT_SATISFIABLE"] = 416] = "REQUESTED_RANGE_NOT_SATISFIABLE";
     HttpStatus[HttpStatus["EXPECTATION_FAILED"] = 417] = "EXPECTATION_FAILED";
+    /** "I'm a teapot" (418), from RFC 2324. */
     HttpStatus[HttpStatus["I_AM_A_TEAPOT"] = 418] = "I_AM_A_TEAPOT";
+    /** Misdirected Request (421). Named `MISDIRECTED` to match NestJS. */
     HttpStatus[HttpStatus["MISDIRECTED"] = 421] = "MISDIRECTED";
     HttpStatus[HttpStatus["UNPROCESSABLE_ENTITY"] = 422] = "UNPROCESSABLE_ENTITY";
     HttpStatus[HttpStatus["LOCKED"] = 423] = "LOCKED";
     HttpStatus[HttpStatus["FAILED_DEPENDENCY"] = 424] = "FAILED_DEPENDENCY";
     HttpStatus[HttpStatus["PRECONDITION_REQUIRED"] = 428] = "PRECONDITION_REQUIRED";
     HttpStatus[HttpStatus["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
+    /** Non-standard code carried over from NestJS. */
     HttpStatus[HttpStatus["UNRECOVERABLE_ERROR"] = 456] = "UNRECOVERABLE_ERROR";
     HttpStatus[HttpStatus["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
     HttpStatus[HttpStatus["NOT_IMPLEMENTED"] = 501] = "NOT_IMPLEMENTED";