@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

package/src/db/jst.ts

@@ -1,27 +1,45 @@
-// JST 日時の整形を「DB 書き込みの副作用」として列の境界に寄せるための共有部品。
-// drizzle-orm の値・型は import しない（kit の脱・型同一性方針）。kit で完成した customType 列を
-// export すると、消費側と drizzle-orm のコピーが分かれた場合に `.default(sql\`…\`)` 等で `SQL` の
-// private プロパティ（shouldInlineParams）が nominal 不一致になり型衝突する（実測で確認）。そのため
-// 列生成は消費側の `customType` に委ね、kit は params とヘルパだけ供給する:
-//
-//   import { customType } from 'drizzle-orm/mysql-core';
-//   import { jstTimestampParams, jstDateParams } from '@rdlabo/workers-hono-kit/db';
-//   export const jstTimestamp = (name: string, opts?: { fsp?: number }) =>
-//     customType<{ data: string | Date; driverData: string | Date }>(jstTimestampParams(opts?.fsp))(name);
-//   export const jstDate = (name: string) =>
-//     customType<{ data: string | null; driverData: string | null }>(jstDateParams())(name);
-//
-// timestamp/datetime は toDriver を置かず Date を素通し → 接続の `timezone:'+09:00'`（hyperdrive
-// 既定）で mysql2 が JST 整形、整形済み文字列も素通し。Drizzle ネイティブ `mode:'date'` は Date を
-// tz 層より前に UTC 文字列化して −9h で壊れるため使わない（customType pass-through が唯一クリーン）。
-// date 列はクライアントの ISO/空文字を MySQL DATE が弾く＋JST 日跨ぎ正規化が要るので toJstDate を残す。
+/**
+ * Shared building blocks for normalizing JST (Asia/Tokyo) date/time values.
+ *
+ * @remarks
+ * JST normalization is applied at the column boundary as a write-time side effect, and neither
+ * values nor types from `drizzle-orm` are imported here on purpose. Exporting a fully-built
+ * `customType` column from the kit would cause type collisions when the kit and the consumer
+ * resolve separate copies of `drizzle-orm` (the private `SQL` brand stops being nominally
+ * compatible). Instead the kit ships only the params and helpers, and the consumer builds the
+ * column with its own `customType`:
+ *
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstTimestampParams, jstDateParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * export const jstTimestamp = (name: string, opts?: { fsp?: number }) =>
+ *   customType<{ data: string | Date; driverData: string | Date }>(jstTimestampParams(opts?.fsp))(name);
+ * export const jstDate = (name: string) =>
+ *   customType<{ data: string | null; driverData: string | null }>(jstDateParams())(name);
+ * ```
+ *
+ * `timestamp`/`datetime` columns omit `toDriver` and pass `Date` values straight through, so the
+ * connection's `timezone: '+09:00'` default makes mysql2 format them as JST; pre-formatted strings
+ * also pass through. Drizzle's native `mode: 'date'` is avoided because it stringifies `Date` to
+ * UTC before the timezone layer, shifting values by -9h. `date` columns keep `toJstDate` because
+ * MySQL `DATE` rejects ISO/empty strings and a JST day-boundary normalization is required.
+ */
 
 const JST_OFFSET_MS = 9 * 60 * 60 * 1000;
 
 /**
- * クライアント送出の日付（ISO 8601 `...Z` / `YYYY-MM-DD` / 空文字）を MySQL DATE 用の
- * `YYYY-MM-DD`（JST）へ正規化。nullish/空/解釈不能は null。MySQL DATE は ISO を弾く
- * （ER_TRUNCATED_WRONG_VALUE）ため driver では代替できず、列の toDriver に必要。
+ * Normalize a client-supplied date to the `YYYY-MM-DD` (JST) form accepted by a MySQL `DATE` column.
+ *
+ * Accepts ISO 8601 (`...Z`), `YYYY-MM-DD`, or an empty string. Nullish, empty, or unparseable input
+ * resolves to `null`.
+ *
+ * @remarks
+ * MySQL `DATE` rejects ISO strings with `ER_TRUNCATED_WRONG_VALUE`, so this cannot be handled by the
+ * driver alone; it is needed as the `toDriver` transform for a `date` column.
+ *
+ * @param value - the raw date string from the client (ISO 8601, `YYYY-MM-DD`, or empty), or nullish.
+ * @returns the JST calendar date as `YYYY-MM-DD`, or `null` when the input is empty or unparseable.
  */
 export function toJstDate(value: string | null | undefined): string | null {
   if (!value) {
@@ -36,17 +54,65 @@ export function toJstDate(value: string | null | undefined): string | null {
   return `${jst.getUTCFullYear()}-${p(jst.getUTCMonth() + 1)}-${p(jst.getUTCDate())}`;
 }
 
-/** `customType` に渡す params: `timestamp(fsp)` 列（created_at 群）。Date 素通し（pass-through）。 */
+/**
+ * Build the params for a `customType` backing a MySQL `timestamp` column with `Date` pass-through.
+ *
+ * The column omits `toDriver`, so `Date` values flow straight to mysql2 and are formatted as JST by
+ * the connection's `timezone: '+09:00'` default.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `timestamp(fsp)`.
+ * @returns the `customType` params object exposing the column's `dataType`.
+ * @example
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstTimestampParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * const jstTimestamp = (name: string) =>
+ *   customType<{ data: string | Date; driverData: string | Date }>(jstTimestampParams())(name);
+ * ```
+ */
 export const jstTimestampParams = (fsp?: number): { dataType: () => string } => ({
   dataType: () => (fsp != null ? `timestamp(${fsp})` : 'timestamp'),
 });
 
-/** `customType` に渡す params: `datetime` 列（payment.limit_at 等）。Date 素通し（pass-through）。 */
+/**
+ * Build the params for a `customType` backing a MySQL `datetime` column with `Date` pass-through.
+ *
+ * Behaves like {@link jstTimestampParams} but emits a `datetime` data type; `Date` values pass
+ * through and are formatted as JST by the connection's `timezone: '+09:00'` default.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `datetime(fsp)`.
+ * @returns the `customType` params object exposing the column's `dataType`.
+ * @example
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstDatetimeParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * const jstDatetime = (name: string) =>
+ *   customType<{ data: string | Date; driverData: string | Date }>(jstDatetimeParams())(name);
+ * ```
+ */
 export const jstDatetimeParams = (fsp?: number): { dataType: () => string } => ({
   dataType: () => (fsp != null ? `datetime(${fsp})` : 'datetime'),
 });
 
-/** `customType` に渡す params: `date` 列（expiry_date 等）。toJstDate で文字列を正規化。 */
+/**
+ * Build the params for a `customType` backing a MySQL `date` column with JST normalization.
+ *
+ * Unlike the timestamp/datetime params, this defines a `toDriver` transform that runs
+ * {@link toJstDate} so client-supplied ISO/empty strings are normalized to a JST `YYYY-MM-DD` value
+ * the column accepts.
+ *
+ * @returns the `customType` params object exposing the column's `dataType` and `toDriver`.
+ * @example
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstDateParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * const jstDate = (name: string) =>
+ *   customType<{ data: string | null; driverData: string | null }>(jstDateParams())(name);
+ * ```
+ */
 export const jstDateParams = (): {
   dataType: () => string;
   toDriver: (value: string | null) => string | null;

package/src/db/orm-config.ts

@@ -1,45 +1,87 @@
 /**
- * Drizzle の列名 casing をフリートで一元管理する（標準: snake_case を「config」と「runtime」の両方で固定）。
+ * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
+ * config and the runtime ORM.
  *
- * casing は2か所にあり別物:
- *   ① drizzle.config.ts の top-level `casing` … `db:generate` が **作る列名** を決める（→ honoDrizzleConfig）
- *   ② database.ts の `drizzle(conn, { …casing })` … **実行時の書き込みビルダが参照する列名** を決める（→ DRIZZLE_ORM_OPTIONS）
+ * @remarks
+ * Casing is configured in two distinct places:
  *
- * この2つが食い違うと、明示列名を書き忘れた camelCase 複数単語列で generate と実行時がズレて実行時
- * `Unknown column` になる（typecheck もマイグレーションも正常に見えるので発覚が遅い）。両方ここから取れば
- * ズレが構造的に起きない。明示列名がある列では casing は無視されるので、既存挙動は変えない純粋な安全網。
+ * 1. The top-level `casing` in `drizzle.config.ts` decides the column names that `db:generate`
+ *    **creates** (see {@link honoDrizzleConfig}).
+ * 2. The `drizzle(conn, { …casing })` call decides the column names the **runtime write builder**
+ *    resolves to (see {@link DRIZZLE_ORM_OPTIONS}).
  *
- * 注: runtime の `drizzle()` 呼び出し自体は **消費側 repo が自分の drizzle-orm で行う**（kit が drizzle() を
- * 呼ぶと kit と repo で drizzle-orm が別コピーになり型同一性が壊れるため）。kit は「値」だけを提供する。
+ * If these two disagree, a multi-word camelCase column without an explicit column name will be
+ * generated with one name but queried with another, producing a runtime `Unknown column` error —
+ * something neither the type-check nor the migration surface, so it is caught late. Sourcing both
+ * from here makes the mismatch structurally impossible. Casing is ignored for columns that declare
+ * an explicit name, so this is a pure safety net that does not change existing behavior.
+ *
+ * The runtime `drizzle()` call itself is made by the consuming app with its own `drizzle-orm`; the
+ * kit only ever provides values, never the ORM instance, to avoid splitting `drizzle-orm` into two
+ * copies and breaking type identity.
  */
 
 /**
- * runtime 用。消費側 repo の database.ts で `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` と spread して使う。
- * mode/casing を kit が固定し、書き込みビルダの列名解決を snake_case に揃える。
+ * Runtime ORM options shared by the consuming app's `drizzle()` call.
+ *
+ * Spread into the runtime ORM as `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` so the write
+ * builder resolves column names as `snake_case`, matching what `db:generate` creates.
+ *
+ * @remarks
+ * Fixes `mode: 'default'` and `casing: 'snake_case'`. See the module-level documentation for why
+ * the same casing must be used by both the config and the runtime ORM.
  */
 export const DRIZZLE_ORM_OPTIONS = { mode: 'default', casing: 'snake_case' } as const;
 
+/**
+ * Options for {@link honoDrizzleConfig}.
+ */
 export interface HonoDrizzleConfigOptions {
-  /** drizzle-kit の dbCredentials.database（localConnectionString とは別）。 */
+  /** drizzle-kit `dbCredentials.database` — the database name to connect to. */
   database: string;
+  /** Database host; defaults to `process.env.DB_HOST` then `127.0.0.1`. */
   host?: string;
+  /** Database port; defaults to `process.env.DB_PORT` then `3306`. */
   port?: number;
+  /** Database user; defaults to `process.env.DB_USER` then `root`. */
   user?: string;
+  /** Database password; defaults to `process.env.DB_PASSWORD` then `root`. */
   password?: string;
-  /** 既定 './src/db/schemes'。 */
+  /** Path to the schema directory; defaults to `'./src/db/schemes'`. */
   schema?: string;
-  /** 既定 './drizzle'。 */
+  /** Output directory for generated migrations; defaults to `'./drizzle'`. */
   out?: string;
-  /** /api と DB を共有する repo は schema 由来テーブルに限定する（省略可）。 */
+  /**
+   * Optional table allow-list. Use this to restrict drizzle-kit to the schema's own tables when the
+   * database is shared with another application.
+   */
   tablesFilter?: string[];
-  /** db:introspect（DB→JS）の casing。生成方向の `casing:'snake_case'` とは別軸（省略可）。 */
+  /**
+   * Optional `db:introspect` (DB → JS) casing. This is an independent axis from the generation-side
+   * `casing: 'snake_case'` and only affects introspection output.
+   */
   introspect?: { casing: 'camel' | 'preserve' };
 }
 
 /**
- * drizzle.config.ts 用ファクトリ。`export default honoDrizzleConfig({ database })` で使う。
- * casing:'snake_case'・schema/out・dbCredentials（env 既定）を kit が owner として固定する。
- * drizzle-kit を kit の依存にしないため plain object を返す（drizzle-kit CLI は default export を読むだけ）。
+ * Build a `drizzle.config.ts` configuration object with the kit's standard defaults.
+ *
+ * Fixes `casing: 'snake_case'`, the `schema`/`out` paths, and `dbCredentials` (with env-based
+ * defaults), while leaving `tablesFilter` and `introspect` opt-in.
+ *
+ * @remarks
+ * Returns a plain object rather than a typed drizzle-kit config so that `drizzle-kit` need not be a
+ * dependency of the kit; the drizzle-kit CLI only reads the default export.
+ *
+ * @param options - configuration overrides; only `database` is required.
+ * @returns a plain configuration object suitable for `export default` in `drizzle.config.ts`.
+ * @example
+ * ```ts
+ * // drizzle.config.ts
+ * import { honoDrizzleConfig } from '@rdlabo/workers-hono-kit/db';
+ *
+ * export default honoDrizzleConfig({ database: 'app' });
+ * ```
  */
 export function honoDrizzleConfig(options: HonoDrizzleConfigOptions) {
   const {

package/src/db/retry.ts

@@ -1,7 +1,29 @@
 /**
- * ER_LOCK_DEADLOCK を指数バックオフで retry する（NestJS/TypeORM の retryWhenDeadlock 相当）。
- * MySQL はデッドロック時にトランザクション全体をロールバックするため、同じ作業単位の再実行は安全。
- * `fn` は単一文（write）またはトランザクション全体（transaction）であること — retry は `fn` 全体を再実行する。
+ * Run an async unit of work, retrying it on MySQL deadlock errors with exponential backoff.
+ *
+ * Retries are triggered only by the `ER_LOCK_DEADLOCK` error code. Each failed attempt waits
+ * `delay * attempt` milliseconds (linear growth of the base delay) before the next try, and any
+ * non-deadlock error is rethrown immediately without retrying.
+ *
+ * @remarks
+ * MySQL rolls back the entire transaction when it detects a deadlock, so re-running the same unit
+ * of work is safe. Pass a `fn` that represents one complete unit — a single statement or an entire
+ * transaction — because the whole `fn` is re-executed on each retry.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param fn - the unit of work to execute; it is invoked again from scratch on each retry.
+ * @param retries - maximum number of attempts (default `3`).
+ * @param delay - base backoff in milliseconds; attempt N waits `delay * N` (default `100`).
+ * @returns the value resolved by the first successful call to `fn`.
+ * @throws the last error thrown by `fn` once retries are exhausted, or any non-deadlock error on
+ * the first occurrence.
+ * @example
+ * ```ts
+ * await retryWhenDeadlock(() => db.transaction(async (tx) => {
+ *   await tx.insert(orders).values(order);
+ *   await tx.update(stock).set({ qty: sql`qty - 1` }).where(eq(stock.id, order.itemId));
+ * }));
+ * ```
  */
 export async function retryWhenDeadlock<T>(fn: () => Promise<T>, retries = 3, delay = 100): Promise<T> {
   for (let attempt = 0; attempt < retries; attempt++) {

package/src/db/write-result.ts

@@ -1,21 +1,44 @@
 /**
- * Drizzle(mysql2) の write 結果から insertId / affectedRows を型安全に取り出すヘルパ。
- * 生の builder/ResultSetHeader を repo 側に晒さずに、よく使う値だけを取り出す。
+ * Shape of a Drizzle (mysql2) write result, narrowed to the fields callers actually read.
  *
- * mysql2 の INSERT/UPDATE/DELETE 結果は `[ResultSetHeader, FieldPacket[]]` 形。
+ * @remarks
+ * A mysql2 INSERT/UPDATE/DELETE result is the tuple `[ResultSetHeader, FieldPacket[]]`. Typing the
+ * result this way lets repositories extract the common values without exposing the raw query
+ * builder or the full `ResultSetHeader` to the rest of the codebase.
  */
 export type DzWriteResult = readonly [{ insertId: number; affectedRows: number }, ...unknown[]];
 
+/**
+ * Extract the auto-increment `insertId` from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `insertId` reported by mysql2 (the id of the first inserted row).
+ */
 export function insertIdOf(result: DzWriteResult): number {
   return result[0].insertId;
 }
 
+/**
+ * Extract the number of affected rows from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `affectedRows` count reported by mysql2.
+ */
 export function affectedRowsOf(result: DzWriteResult): number {
   return result[0].affectedRows;
 }
 
 /**
- * 一括 INSERT で連番採番された行の id 群を返す（mysql2 は先頭 insertId のみ返すため count 分を生成）。
+ * Reconstruct the auto-increment ids assigned by a bulk INSERT.
+ *
+ * @remarks
+ * mysql2 reports only the first `insertId` for a multi-row INSERT, so the remaining ids are derived
+ * by assuming a contiguous sequence (`base`, `base + 1`, …). This holds for tables with a standard
+ * `AUTO_INCREMENT` column and the default `innodb_autoinc_lock_mode`.
+ *
+ * @param result - the result of a bulk INSERT.
+ * @param count - the number of rows that were inserted.
+ * @returns an array of the `count` auto-increment ids, starting at the reported `insertId`.
  */
 export function insertedIdsOf(result: DzWriteResult, count: number): number[] {
   const base = result[0].insertId;

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

@@ -3,24 +3,62 @@ import type { CryptoKey, JWK, JWTVerifyGetKey, KeyObject } from 'jose';
 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);
   }