@rdlabo/workers-hono-kit 0.1.0

package/src/db/database.ts

@@ -0,0 +1,133 @@
+import { createConnection } from 'mysql2/promise';
+import type { Connection, Pool } from 'mysql2/promise';
+import { hyperdriveConnectionOptions } from './connection';
+import type { HyperdriveLike } from './connection';
+import { retryWhenDeadlock } from './retry';
+
+/**
+ * フリート共通のデータ層（NestJS/TypeORM の master/slave + retryWhenDeadlock 置換）。
+ *   - reads  → replica。透明性のため生 SQL を維持（旧 helper.slave().query 相当）。
+ *   - writes → primary。型安全のため Drizzle 経由。ただし `write(fn)`/`transaction(fn)` 経由のみで、
+ *     生 builder は公開しない。builder はここで await される（Drizzle builder は lazy thenable のため
+ *     `return builder` が黙って no-op になるフットガンを排除）。両者とも ER_LOCK_DEADLOCK を retry。
+ *
+ * 重要: kit は `drizzle-orm` の **型同一性に依存しない**。各 repo が自分の drizzle-orm で作った orm を
+ * 渡す（`Database` は orm 型 `TDrizzle` にジェネリック）。これにより kit と repo で drizzle-orm の
+ * コピーが分かれても（symlink 構成）`MySqlTable`/`SQL` のブランド衝突が起きない。
+ */
+
+/** reads 用の最小接続インターフェース（mysql2 Connection / Pool が構造的に満たす）。 */
+export interface QueryRunner {
+  query(sql: string, params?: unknown[]): Promise<unknown>;
+}
+
+/** drizzle インスタンスの `.transaction(cb)` が受け取る tx ハンドルの型を取り出す。 */
+export type TxOf<TDrizzle> = TDrizzle extends {
+  transaction(cb: (tx: infer Tx) => Promise<unknown>): Promise<unknown>;
+}
+  ? Tx
+  : unknown;
+
+export interface Database<TDrizzle, TTx = TxOf<TDrizzle>> {
+  read<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  /** 単一 INSERT/UPDATE/DELETE。primary で await + deadlock retry。 */
+  write<T>(fn: (dz: TDrizzle) => Promise<T>): Promise<T>;
+  /** 複数 write を 1 トランザクションで。deadlock 時は全体を retry。 */
+  transaction<T>(fn: (tx: TTx) => Promise<T>): Promise<T>;
+}
+
+/** dispose() を持つ Database（接続をモジュール内で開く版＝Hyperdrive / Pool 背面）。 */
+export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Database<TDrizzle, TTx> {
+  dispose(): Promise<void>;
+}
+
+interface DrizzleLike<TTx> {
+  transaction<T>(cb: (tx: TTx) => Promise<T>): Promise<T>;
+}
+
+export interface CreateMysqlDatabaseOptions<TDrizzle> {
+  /** 消費側が自分の drizzle-orm で `drizzle(primary, { schema, ... })` を作って渡す（writes 用）。 */
+  orm: TDrizzle;
+  /** reads（生 SQL）用の接続。 */
+  replica: QueryRunner;
+}
+
+/**
+ * 接続済みの orm/replica を受け取り Database を組み立てる（receptray/tipsys の MysqlDatabase 相当）。
+ * 接続・orm の生成と接続の破棄は呼び出し側（worker entry）が担う。
+ */
+export function createMysqlDatabase<TDrizzle>(options: CreateMysqlDatabaseOptions<TDrizzle>): Database<TDrizzle> {
+  return databaseFrom(options.orm, options.replica);
+}
+
+export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
+  primaryHyperdrive: HyperdriveLike;
+  replicaHyperdrive: HyperdriveLike;
+  /** 消費側の drizzle-orm で primary 接続から orm を作る factory（writes 用）。 */
+  createOrm: (primary: Connection) => TDrizzle;
+  /** createConnection に渡す追加オプション（timezone など）。disableEval:true は既定で付与。 */
+  connectionOptions?: Record<string, unknown>;
+}
+
+/**
+ * Hyperdrive バインディングから接続を遅延生成する Database（foodlabel の MysqlDatabase 相当）。
+ * リクエスト毎に new し、レスポンス後 `dispose()` で接続を閉じる。read/write/transaction の面は同一。
+ */
+export function createHyperdriveDatabase<TDrizzle>(
+  options: CreateHyperdriveDatabaseOptions<TDrizzle>,
+): DisposableDatabase<TDrizzle> {
+  const { primaryHyperdrive, replicaHyperdrive, createOrm, connectionOptions } = options;
+  let primaryConn: Promise<Connection> | undefined;
+  let replicaConn: Promise<Connection> | undefined;
+  let orm: TDrizzle | undefined;
+
+  const primary = (): Promise<Connection> => (primaryConn ??= connect(primaryHyperdrive, connectionOptions));
+  const replica = (): Promise<Connection> => (replicaConn ??= connect(replicaHyperdrive, connectionOptions));
+  const ormFor = async (): Promise<TDrizzle> => (orm ??= createOrm(await primary()));
+
+  return {
+    read<T>(sql: string, params: unknown[] = []): Promise<T[]> {
+      return retryWhenDeadlock(async () => {
+        const [rows] = (await (await replica()).query(sql, params)) as [unknown, unknown];
+        return rows as T[];
+      });
+    },
+    async write<T>(fn: (dz: TDrizzle) => Promise<T>): Promise<T> {
+      const dz = await ormFor();
+      return retryWhenDeadlock(() => fn(dz));
+    },
+    async transaction<T>(fn: (tx: TxOf<TDrizzle>) => Promise<T>): Promise<T> {
+      const dz = (await ormFor()) as DrizzleLike<TxOf<TDrizzle>>;
+      return retryWhenDeadlock(() => dz.transaction(fn));
+    },
+    async dispose(): Promise<void> {
+      await Promise.all([primaryConn?.then((c) => c.end()), replicaConn?.then((c) => c.end())]);
+    },
+  };
+}
+
+/** orm と replica 接続から Database を組み立てる内部ヘルパ。 */
+export function databaseFrom<TDrizzle>(orm: TDrizzle, replica: QueryRunner): Database<TDrizzle> {
+  const drizzleLike = orm as DrizzleLike<TxOf<TDrizzle>>;
+  return {
+    read<T>(sql: string, params: unknown[] = []): Promise<T[]> {
+      return retryWhenDeadlock(async () => {
+        const [rows] = (await replica.query(sql, params)) as [unknown, unknown];
+        return rows as T[];
+      });
+    },
+    write<T>(fn: (dz: TDrizzle) => Promise<T>): Promise<T> {
+      return retryWhenDeadlock(() => fn(orm));
+    },
+    transaction<T>(fn: (tx: TxOf<TDrizzle>) => Promise<T>): Promise<T> {
+      return retryWhenDeadlock(() => drizzleLike.transaction(fn));
+    },
+  };
+}
+
+/** Pool/Connection は mysql2 の型。kit の QueryRunner には構造的に代入可能。 */
+export type { Connection, Pool };
+
+function connect(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Promise<Connection> {
+  return createConnection(hyperdriveConnectionOptions(hyperdrive, extra));
+}

package/src/db/index.ts

@@ -0,0 +1,27 @@
+// @rdlabo/workers-hono-kit/db — mysql2 依存のデータ層ヘルパ（ルート `.` は web 標準のみのため別サブパス）。
+// drizzle-orm の型同一性には依存しない（orm は消費側が渡す）。
+
+export { retryWhenDeadlock } from './retry';
+
+export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database';
+export type {
+  Database,
+  DisposableDatabase,
+  QueryRunner,
+  TxOf,
+  CreateMysqlDatabaseOptions,
+  CreateHyperdriveDatabaseOptions,
+  Connection,
+  Pool,
+} from './database';
+
+export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result';
+export type { DzWriteResult } from './write-result';
+
+export { hyperdriveConnectionOptions, withMysqlConnections } from './connection';
+export type { HyperdriveLike, ExecutionContextLike } from './connection';
+
+export { toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst';
+
+export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig } from './orm-config';
+export type { HonoDrizzleConfigOptions } from './orm-config';

package/src/db/jst.ts

@@ -0,0 +1,56 @@
+// 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 を残す。
+
+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 に必要。
+ */
+export function toJstDate(value: string | null | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  const ms = new Date(value).getTime();
+  if (Number.isNaN(ms)) {
+    return null;
+  }
+  const jst = new Date(ms + JST_OFFSET_MS);
+  const p = (n: number): string => String(n).padStart(2, '0');
+  return `${jst.getUTCFullYear()}-${p(jst.getUTCMonth() + 1)}-${p(jst.getUTCDate())}`;
+}
+
+/** `customType` に渡す params: `timestamp(fsp)` 列（created_at 群）。Date 素通し（pass-through）。 */
+export const jstTimestampParams = (fsp?: number): { dataType: () => string } => ({
+  dataType: () => (fsp != null ? `timestamp(${fsp})` : 'timestamp'),
+});
+
+/** `customType` に渡す params: `datetime` 列（payment.limit_at 等）。Date 素通し（pass-through）。 */
+export const jstDatetimeParams = (fsp?: number): { dataType: () => string } => ({
+  dataType: () => (fsp != null ? `datetime(${fsp})` : 'datetime'),
+});
+
+/** `customType` に渡す params: `date` 列（expiry_date 等）。toJstDate で文字列を正規化。 */
+export const jstDateParams = (): {
+  dataType: () => string;
+  toDriver: (value: string | null) => string | null;
+} => ({
+  dataType: () => 'date',
+  toDriver: (value: string | null) => toJstDate(value),
+});

package/src/db/orm-config.ts

@@ -0,0 +1,71 @@
+/**
+ * Drizzle の列名 casing をフリートで一元管理する（標準: snake_case を「config」と「runtime」の両方で固定）。
+ *
+ * casing は2か所にあり別物:
+ *   ① drizzle.config.ts の top-level `casing` … `db:generate` が **作る列名** を決める（→ honoDrizzleConfig）
+ *   ② database.ts の `drizzle(conn, { …casing })` … **実行時の書き込みビルダが参照する列名** を決める（→ DRIZZLE_ORM_OPTIONS）
+ *
+ * この2つが食い違うと、明示列名を書き忘れた camelCase 複数単語列で generate と実行時がズレて実行時
+ * `Unknown column` になる（typecheck もマイグレーションも正常に見えるので発覚が遅い）。両方ここから取れば
+ * ズレが構造的に起きない。明示列名がある列では casing は無視されるので、既存挙動は変えない純粋な安全網。
+ *
+ * 注: runtime の `drizzle()` 呼び出し自体は **消費側 repo が自分の drizzle-orm で行う**（kit が drizzle() を
+ * 呼ぶと kit と repo で drizzle-orm が別コピーになり型同一性が壊れるため）。kit は「値」だけを提供する。
+ */
+
+/**
+ * runtime 用。消費側 repo の database.ts で `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` と spread して使う。
+ * mode/casing を kit が固定し、書き込みビルダの列名解決を snake_case に揃える。
+ */
+export const DRIZZLE_ORM_OPTIONS = { mode: 'default', casing: 'snake_case' } as const;
+
+export interface HonoDrizzleConfigOptions {
+  /** drizzle-kit の dbCredentials.database（localConnectionString とは別）。 */
+  database: string;
+  host?: string;
+  port?: number;
+  user?: string;
+  password?: string;
+  /** 既定 './src/db/schemes'。 */
+  schema?: string;
+  /** 既定 './drizzle'。 */
+  out?: string;
+  /** /api と DB を共有する repo は schema 由来テーブルに限定する（省略可）。 */
+  tablesFilter?: string[];
+  /** db:introspect（DB→JS）の casing。生成方向の `casing:'snake_case'` とは別軸（省略可）。 */
+  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 を読むだけ）。
+ */
+export function honoDrizzleConfig(options: HonoDrizzleConfigOptions) {
+  const {
+    database,
+    host,
+    port,
+    user,
+    password,
+    schema = './src/db/schemes',
+    out = './drizzle',
+    tablesFilter,
+    introspect,
+  } = options;
+  return {
+    dialect: 'mysql' as const,
+    schema,
+    out,
+    casing: 'snake_case' as const,
+    ...(tablesFilter ? { tablesFilter } : {}),
+    ...(introspect ? { introspect } : {}),
+    dbCredentials: {
+      host: host ?? process.env.DB_HOST ?? '127.0.0.1',
+      port: port ?? Number(process.env.DB_PORT ?? 3306),
+      user: user ?? process.env.DB_USER ?? 'root',
+      password: password ?? process.env.DB_PASSWORD ?? 'root',
+      database,
+    },
+  };
+}

package/src/db/retry.ts

@@ -0,0 +1,21 @@
+/**
+ * ER_LOCK_DEADLOCK を指数バックオフで retry する（NestJS/TypeORM の retryWhenDeadlock 相当）。
+ * MySQL はデッドロック時にトランザクション全体をロールバックするため、同じ作業単位の再実行は安全。
+ * `fn` は単一文（write）またはトランザクション全体（transaction）であること — retry は `fn` 全体を再実行する。
+ */
+export async function retryWhenDeadlock<T>(fn: () => Promise<T>, retries = 3, delay = 100): Promise<T> {
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      if (code === 'ER_LOCK_DEADLOCK' && attempt < retries - 1) {
+        await new Promise((resolve) => setTimeout(resolve, delay * (attempt + 1)));
+        continue;
+      }
+      throw error;
+    }
+  }
+  // Unreachable: the loop returns on success and throws on the final failed attempt.
+  throw new Error('retryWhenDeadlock: exhausted retries');
+}

package/src/db/write-result.ts

@@ -0,0 +1,23 @@
+/**
+ * Drizzle(mysql2) の write 結果から insertId / affectedRows を型安全に取り出すヘルパ。
+ * 生の builder/ResultSetHeader を repo 側に晒さずに、よく使う値だけを取り出す。
+ *
+ * mysql2 の INSERT/UPDATE/DELETE 結果は `[ResultSetHeader, FieldPacket[]]` 形。
+ */
+export type DzWriteResult = readonly [{ insertId: number; affectedRows: number }, ...unknown[]];
+
+export function insertIdOf(result: DzWriteResult): number {
+  return result[0].insertId;
+}
+
+export function affectedRowsOf(result: DzWriteResult): number {
+  return result[0].affectedRows;
+}
+
+/**
+ * 一括 INSERT で連番採番された行の id 群を返す（mysql2 は先頭 insertId のみ返すため count 分を生成）。
+ */
+export function insertedIdsOf(result: DzWriteResult, count: number): number[] {
+  const base = result[0].insertId;
+  return Array.from({ length: count }, (_, i) => base + i);
+}

package/src/firebase/firebase-verifier.ts

@@ -0,0 +1,15 @@
+/** Firebase boundary replacing the firebase-admin Auth surface used by `/api`. */
+export interface DecodedIdToken {
+  uid: string;
+  email?: string;
+  [claim: string]: unknown;
+}
+
+export interface FirebaseVerifier {
+  /** Mirrors firebase-admin getAuth().verifyIdToken(). Throws on invalid token. */
+  verifyIdToken(idToken: string): Promise<DecodedIdToken>;
+  /** Mirrors getAuth().getUser(); returns null when the user is absent. */
+  getUser(uid: string): Promise<{ uid: string; email?: string } | null>;
+  /** Mirrors getAuth().deleteUser(). */
+  deleteUser(uid: string): Promise<void>;
+}

package/src/firebase/identity-toolkit.ts

@@ -0,0 +1,82 @@
+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.
+ *
+ * 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.
+ */
+export interface ServiceAccount {
+  client_email: string;
+  private_key: string;
+  project_id: string;
+}
+
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
+const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
+
+export class IdentityToolkit {
+  private accessToken: { value: string; expiresAt: number } | null = null;
+
+  constructor(private readonly sa: ServiceAccount) {}
+
+  private async getAccessToken(nowSeconds: number): Promise<string> {
+    if (this.accessToken && this.accessToken.expiresAt > nowSeconds + 60) {
+      return this.accessToken.value;
+    }
+    const key = await importPKCS8(this.sa.private_key, 'RS256');
+    const assertion = await new SignJWT({ scope: SCOPE })
+      .setProtectedHeader({ alg: 'RS256', typ: 'JWT' })
+      .setIssuer(this.sa.client_email)
+      .setSubject(this.sa.client_email)
+      .setAudience(TOKEN_URL)
+      .setIssuedAt(nowSeconds)
+      .setExpirationTime(nowSeconds + 3600)
+      .sign(key);
+
+    const res = await fetch(TOKEN_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+        assertion,
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`Identity Toolkit token exchange failed: ${res.status}`);
+    }
+    const json = (await res.json()) as { access_token: string; expires_in: number };
+    this.accessToken = { value: json.access_token, expiresAt: nowSeconds + json.expires_in };
+    return json.access_token;
+  }
+
+  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`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ localId: [uid] }),
+    });
+    if (!res.ok) {
+      return null;
+    }
+    const json = (await res.json()) as { users?: { localId: string; email?: string }[] };
+    const user = json.users?.[0];
+    return user ? { uid: user.localId, email: user.email } : null;
+  }
+
+  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`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ localId: uid }),
+    });
+    if (!res.ok) {
+      throw new Error(`Identity Toolkit delete failed: ${res.status}`);
+    }
+  }
+}

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

@@ -0,0 +1,71 @@
+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';
+
+// 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.
+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).
+ *
+ * getUser/deleteUser delegate to Identity Toolkit REST (network); absent it throws.
+ */
+export const SECURETOKEN_JWK_URL =
+  'https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com';
+
+export class JoseFirebaseVerifier implements FirebaseVerifier {
+  constructor(
+    private readonly opts: {
+      projectId: string;
+      keyResolver: KeyInput;
+      identity?: IdentityToolkit;
+      now?: () => number; // seconds; injectable for tests
+    },
+  ) {}
+
+  async verifyIdToken(idToken: string): Promise<DecodedIdToken> {
+    const options = {
+      issuer: `https://securetoken.google.com/${this.opts.projectId}`,
+      audience: this.opts.projectId,
+      algorithms: ['RS256'] as string[],
+    };
+    // Branch so each call matches a single jwtVerify overload (static key vs getKey fn).
+    const key = this.opts.keyResolver;
+    const { payload } =
+      typeof key === 'function' ? await jwtVerify(idToken, key, options) : await jwtVerify(idToken, key, options);
+    // Mirror firebase-admin's extra checks beyond signature/iss/aud/exp:
+    if (!payload.sub || typeof payload.sub !== 'string' || payload.sub.length > 128) {
+      throw new Error('Firebase ID token has an invalid subject');
+    }
+    const authTime = payload.auth_time;
+    if (typeof authTime !== 'number' || authTime > this.nowSeconds()) {
+      throw new Error('Firebase ID token has an invalid auth_time');
+    }
+    return { ...payload, uid: payload.sub, email: payload.email as string | undefined };
+  }
+
+  async getUser(uid: string): Promise<{ uid: string; email?: string } | null> {
+    if (!this.opts.identity) {
+      throw new Error('Identity Toolkit not configured');
+    }
+    return this.opts.identity.lookup(uid, this.nowSeconds());
+  }
+
+  async deleteUser(uid: string): Promise<void> {
+    if (!this.opts.identity) {
+      throw new Error('Identity Toolkit not configured');
+    }
+    await this.opts.identity.remove(uid, this.nowSeconds());
+  }
+
+  private nowSeconds(): number {
+    return this.opts.now ? this.opts.now() : Math.floor(Date.now() / 1000);
+  }
+}

package/src/firebase/remote-verifier.ts

@@ -0,0 +1,49 @@
+import { createRemoteJWKSet } from 'jose';
+import { IdentityToolkit } from './identity-toolkit';
+import type { ServiceAccount } from './identity-toolkit';
+import { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './jose-firebase-verifier';
+
+/**
+ * 本番用の便宜ファクトリ。`createRemoteJWKSet` で Google securetoken の公開鍵を取り、
+ * `JoseFirebaseVerifier` を返す。トークン検証のみ用途（getUser/deleteUser は不要 = Identity Toolkit 無し）。
+ *
+ * JWKS は URL 固定なので isolate 内で 1 度だけ生成して共有し（jose が内部メモリにキャッシュ）、
+ * verifier は projectId ごとにメモ化する。winecode の旧 `verifyFirebaseIdToken`（module-level JWKS）の
+ * キャッシュ挙動を保つための置換。
+ */
+let jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
+const verifiers = new Map<string, JoseFirebaseVerifier>();
+
+export function createRemoteFirebaseVerifier(projectId: string): JoseFirebaseVerifier {
+  jwks ??= createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL));
+  let verifier = verifiers.get(projectId);
+  if (!verifier) {
+    verifier = new JoseFirebaseVerifier({ projectId, keyResolver: jwks });
+    verifiers.set(projectId, verifier);
+  }
+  return verifier;
+}
+
+let saVerifierCache: { key: string; verifier: JoseFirebaseVerifier } | null = null;
+
+/**
+ * サービスアカウント JSON から検証器を作る便宜ファクトリ（receptray/tipsys hono の `firebaseFor` 相当）。
+ * `getUser`/`deleteUser` のため `IdentityToolkit` を内包する点が `createRemoteFirebaseVerifier` との違い。
+ * SA JSON 文字列をキーに isolate 内で 1 つだけキャッシュ（秘密が変わったときだけ再生成）し、
+ * JWKS は `createRemoteFirebaseVerifier` と共有する。
+ */
+export function createServiceAccountVerifier(serviceAccountJson: string): JoseFirebaseVerifier {
+  if (saVerifierCache?.key !== serviceAccountJson) {
+    jwks ??= createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL));
+    const sa = JSON.parse(serviceAccountJson) as ServiceAccount;
+    saVerifierCache = {
+      key: serviceAccountJson,
+      verifier: new JoseFirebaseVerifier({
+        projectId: sa.project_id,
+        keyResolver: jwks,
+        identity: new IdentityToolkit(sa),
+      }),
+    };
+  }
+  return saVerifierCache.verifier;
+}

package/src/http/app-env.ts

@@ -0,0 +1,20 @@
+export type AppEnv = 'development' | 'production';
+
+/**
+ * 実行環境（development / production）を解決する。フリート共通の判定。
+ *
+ * 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 = 本番（安全側）」と同じ意味論。
+ *
+ * `env` 由来なので fetch / scheduled どちらの文脈でも使え、リクエストヘッダ由来でないため詐称されない。
+ */
+export function resolveAppEnv(env: { APP_ENV?: string } | null | undefined): AppEnv {
+  return env?.APP_ENV === 'development' ? 'development' : 'production';
+}
+
+/** production 判定のショートハンド。 */
+export const isProductionEnv = (env: { APP_ENV?: string } | null | undefined): boolean =>
+  resolveAppEnv(env) === 'production';

package/src/http/app-info.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'hono';
+
+/** クライアントアプリのメタ情報（NestJS の x-amz-meta-* ヘッダ由来。3 repo 共通）。 */
+export interface AppInfo {
+  version: string | null;
+  uuid: string | null;
+}
+
+/**
+ * `x-amz-meta-version` / `x-amz-meta-uuid` ヘッダから AppInfo を読む。
+ * auth middleware が per-request で c.set('appInfo', ...) する値（3 repo で同一仕様）。
+ */
+export const getAppInfo = (c: Context): AppInfo => ({
+  version: c.req.header('x-amz-meta-version') ?? null,
+  uuid: c.req.header('x-amz-meta-uuid') ?? null,
+});

package/src/http/http-status.ts

@@ -0,0 +1,62 @@
+/**
+ * NestJS `@nestjs/common` の HttpStatus enum と同一。フリート（NestJS → Hono 移植）で
+ * ステータスコードを Nest と同じ名前で参照するための共通定数。`/api` のレスポンス status と
+ * バイト一致させる際の単一の参照元にする。
+ */
+export enum HttpStatus {
+  CONTINUE = 100,
+  SWITCHING_PROTOCOLS = 101,
+  PROCESSING = 102,
+  EARLYHINTS = 103,
+  OK = 200,
+  CREATED = 201,
+  ACCEPTED = 202,
+  NON_AUTHORITATIVE_INFORMATION = 203,
+  NO_CONTENT = 204,
+  RESET_CONTENT = 205,
+  PARTIAL_CONTENT = 206,
+  MULTI_STATUS = 207,
+  ALREADY_REPORTED = 208,
+  CONTENT_DIFFERENT = 210,
+  AMBIGUOUS = 300,
+  MOVED_PERMANENTLY = 301,
+  FOUND = 302,
+  SEE_OTHER = 303,
+  NOT_MODIFIED = 304,
+  TEMPORARY_REDIRECT = 307,
+  PERMANENT_REDIRECT = 308,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  PAYMENT_REQUIRED = 402,
+  FORBIDDEN = 403,
+  NOT_FOUND = 404,
+  METHOD_NOT_ALLOWED = 405,
+  NOT_ACCEPTABLE = 406,
+  PROXY_AUTHENTICATION_REQUIRED = 407,
+  REQUEST_TIMEOUT = 408,
+  CONFLICT = 409,
+  GONE = 410,
+  LENGTH_REQUIRED = 411,
+  PRECONDITION_FAILED = 412,
+  PAYLOAD_TOO_LARGE = 413,
+  URI_TOO_LONG = 414,
+  UNSUPPORTED_MEDIA_TYPE = 415,
+  REQUESTED_RANGE_NOT_SATISFIABLE = 416,
+  EXPECTATION_FAILED = 417,
+  I_AM_A_TEAPOT = 418,
+  MISDIRECTED = 421,
+  UNPROCESSABLE_ENTITY = 422,
+  LOCKED = 423,
+  FAILED_DEPENDENCY = 424,
+  PRECONDITION_REQUIRED = 428,
+  TOO_MANY_REQUESTS = 429,
+  UNRECOVERABLE_ERROR = 456,
+  INTERNAL_SERVER_ERROR = 500,
+  NOT_IMPLEMENTED = 501,
+  BAD_GATEWAY = 502,
+  SERVICE_UNAVAILABLE = 503,
+  GATEWAY_TIMEOUT = 504,
+  HTTP_VERSION_NOT_SUPPORTED = 505,
+  INSUFFICIENT_STORAGE = 507,
+  LOOP_DETECTED = 508,
+}