@rdlabo/workers-hono-kit 0.1.0

package/src/http/nest-error.ts

@@ -0,0 +1,138 @@
+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 がそれぞれ手書きしていたものを一本化する。
+ */
+export const NEST_REASON_PHRASES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+};
+
+/** 想定外エラーの通報先に渡す文脈（request id 相関など）。フリート共通の最小形。 */
+export interface ErrorReportContext {
+  requestId?: string;
+}
+
+/**
+ * 想定外エラーの通報関数（Sentry 等）の型。各 repo の container.reportError がこの形。
+ * `createNestErrorHandler({ onUnhandledError })` に `(err, c) => reporter(err, { requestId: c.get('requestId') })`
+ * の形で差し込む。Sentry 呼び出し自体は各 repo（@sentry/cloudflare は workers-hono-kit に持ち込まない）。
+ */
+export type ErrorReporter = (error: unknown, context?: ErrorReportContext) => void;
+
+/** http エラーとみなされた値から status / message / body を読むための最小形。 */
+interface HttpErrorLike {
+  status: ContentfulStatusCode;
+  message: string;
+  /** repo 固有 body の脱出口（winecode の HttpError.body 相当）。あればそのまま render する。 */
+  body?: unknown;
+}
+
+export interface NestErrorHandlerOptions<E extends Env = Env> {
+  /** reason phrase map。既定 `NEST_REASON_PHRASES`。 */
+  reasonPhrases?: Record<number, string>;
+  /**
+   * `error` フィールドを省いて `{ statusCode, message }` のみ返す status。既定 `[401]`
+   * （NestJS の generic `HttpException(msg, 401)` は `error` を持たない）。
+   */
+  bareStatuses?: readonly number[];
+  /**
+   * 非 bare body のフィールド順序。既定 `'statusCode-first'`（= NestJS canonical / receptray・winecode）。
+   * **foodlabel は `'message-first'`** を指定して `{ message, error, statusCode }` の byte-parity を保つ。
+   */
+  fieldOrder?: 'statusCode-first' | 'message-first';
+  /**
+   * reasonPhrases に無い（かつ bare でない）status の `error` フォールバック。既定 `undefined`
+   * （= reason 無しなら `error` を省く）。**winecode は `'Error'`** を指定し、全 status で `error` を必ず出す
+   * （NestJS 既定例外フィルタの「error は常に存在」を忠実再現）。
+   */
+  fallbackReason?: string;
+  /**
+   * http エラー判定。既定は hono の `HTTPException`。
+   * **winecode は独自 `HttpError` を使う**ため `(e) => e instanceof HttpError` を渡す。
+   */
+  isHttpError?: (err: unknown) => err is HttpErrorLike;
+  /**
+   * http エラーでない（= 想定外）エラーを 500 で返す前に呼ぶフック（Sentry 通報など）。
+   * **receptray は `container.reportError?.(err, { requestId })`** を差し込む。例外は握り潰す。
+   */
+  onUnhandledError?: (err: unknown, c: Context<E>) => void;
+  /** 想定外エラー時の 500 body。既定 `{ 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 バンドルでも安定する。
+ */
+const isHTTPException = (err: unknown): err is HttpErrorLike =>
+  err instanceof Error &&
+  typeof (err as { getResponse?: unknown }).getResponse === 'function' &&
+  typeof (err as { status?: unknown }).status === 'number';
+
+/**
+ * NestJS の例外フィルタ相当の Hono `onError` ハンドラを作る（フリート共通）。
+ * - http エラー（既定 `HTTPException`）→ Nest 形 body にマップ。`body` を持つ場合はそれを verbatim で返す。
+ * - bareStatuses（既定 401）は `error` フィールド無し。
+ * - それ以外（想定外エラー）→ `onUnhandledError` 通報 + `console.error` + 500。
+ *
+ * `app.onError(createNestErrorHandler(...))` の形で使う。各 repo の parity 差異（body 順序・
+ * エラー型・通報フック）は options で吸収し、本体の分岐ロジックは共有する。
+ */
+export function createNestErrorHandler<E extends Env = Env>(options: NestErrorHandlerOptions<E> = {}) {
+  const {
+    reasonPhrases = NEST_REASON_PHRASES,
+    bareStatuses = [401],
+    fieldOrder = 'statusCode-first',
+    isHttpError = isHTTPException,
+    onUnhandledError,
+    internalServerErrorBody = { statusCode: 500, message: 'Internal server error' },
+    fallbackReason,
+  } = options;
+
+  return (err: Error, c: Context<E>): Response => {
+    if (isHttpError(err)) {
+      // repo 固有 body の脱出口（winecode）。
+      if (err.body !== undefined) {
+        return c.json(err.body as object, err.status);
+      }
+      // reasonPhrases[status] は型上 string だが noUncheckedIndexedAccess 無効のため実際は未定義になり得る。
+      // 未登録 status の fallbackReason フォールバックは意図的。
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const reason = bareStatuses.includes(err.status) ? undefined : (reasonPhrases[err.status] ?? fallbackReason);
+      if (reason === undefined) {
+        return c.json({ statusCode: err.status, message: err.message }, err.status);
+      }
+      const body =
+        fieldOrder === 'message-first'
+          ? { message: err.message, error: reason, statusCode: err.status }
+          : { statusCode: err.status, message: err.message, error: reason };
+      return c.json(body, err.status);
+    }
+
+    try {
+      onUnhandledError?.(err, c);
+    } catch {
+      // 通報はエラーレスポンスの挙動を変えてはならない。
+    }
+    console.error(err);
+    return c.json(internalServerErrorBody as object, 500);
+  };
+}
+
+/**
+ * Express/Nest 既定の未マッチルート 404 body を返す `notFound` ハンドラ。
+ * `app.notFound(nestNotFoundHandler)` で使う（receptray/winecode は未実装の parity ギャップ）。
+ */
+export function nestNotFoundHandler(c: Context): Response {
+  return c.json(
+    { message: `Cannot ${c.req.method} ${new URL(c.req.url).pathname}`, error: 'Not Found', statusCode: 404 },
+    404,
+  );
+}

package/src/http/user-protocol.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'hono';
+
+/** クライアントの IP / UA（NestJS の @UserProtocol デコレータ相当）。 */
+export interface IUserProtocol {
+  ipAddress: string | null;
+  userAgent: string | null;
+}
+
+/**
+ * Hono Context からクライアント IP / UA を取得する。Cloudflare は実 IP を `CF-Connecting-IP` に入れる
+ * （`X-Forwarded-For` はフォールバック）。未取得は null（DB の nullable カラムにそのまま入る）。
+ */
+export const getUserProtocol = (c: Context): IUserProtocol => ({
+  ipAddress: c.req.header('cf-connecting-ip') ?? c.req.header('x-forwarded-for') ?? null,
+  userAgent: c.req.header('user-agent') ?? null,
+});

package/src/index.ts

@@ -0,0 +1,55 @@
+// @rdlabo/workers-hono-kit — フリート共通のインフラ層ヘルパ（receptray / winecode / foodlabel）。
+// ドメイン・DB・各 repo 固有の parity 差異（auth エラー status/body、secretId、Secret スキーマ）は
+// 各 repo 側に残し、ここには「設定注入で汎用化できるインフラ」だけを置く。
+
+// middleware
+export { finalizeResponse } from './middleware/finalize-response';
+export { validate, createSentryValidate } from './middleware/validation';
+export type {
+  ValidateOptions,
+  ValidationTarget,
+  ZodErrorLike,
+  SentryLike,
+  SentryScopeLike,
+} from './middleware/validation';
+export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce';
+export { createAuthMiddleware } from './middleware/auth';
+export type { AuthMiddlewareOptions } from './middleware/auth';
+
+// http
+export { getUserProtocol } from './http/user-protocol';
+export type { IUserProtocol } from './http/user-protocol';
+export { getAppInfo } from './http/app-info';
+export type { AppInfo } from './http/app-info';
+export { resolveAppEnv, isProductionEnv } from './http/app-env';
+export type { AppEnv } from './http/app-env';
+export { HttpStatus } from './http/http-status';
+export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error';
+export type { NestErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/nest-error';
+
+// cache
+export { KVCache } from './cache/kv-cache';
+export type { KVNamespace, KVCacheOptions } from './cache/kv-cache';
+
+// stripe
+export { createStripeClient, verifyStripeWebhook } from './stripe/client';
+export type { CreateStripeClientOptions } from './stripe/client';
+
+// db
+export { retryWhenDeadlock } from './db/retry';
+
+// ai
+export { createAiGatewayProvider } from './ai/gateway';
+export type { AiGatewayConfig, AiGatewayProvider, AiGatewayBinding, AiGateway, AiGatewayOptions } from './ai/gateway';
+
+// aws
+export { getAuthenticationSecret } from './aws/secrets-manager';
+export type { AwsSecretsOptions } from './aws/secrets-manager';
+export { getCloudFrontSignedUrl } from './aws/cloudfront';
+
+// firebase
+export type { DecodedIdToken, FirebaseVerifier } from './firebase/firebase-verifier';
+export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier';
+export { IdentityToolkit } from './firebase/identity-toolkit';
+export type { ServiceAccount } from './firebase/identity-toolkit';
+export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier';

package/src/middleware/auth.ts

@@ -0,0 +1,67 @@
+import type { Context, Env, MiddlewareHandler } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { getAppInfo } from '../http/app-info';
+import type { AppInfo } from '../http/app-info';
+
+export interface AuthMiddlewareOptions<E extends Env, Verified, Id = unknown> {
+  /** ID トークンを載せるヘッダ。既定 `'x-amz-security-token'`（フリート共通）。 */
+  tokenHeader?: string;
+  /** 生トークンを検証して record/decoded を返す。無効なら throw / reject すること。 */
+  verify: (token: string, c: Context<E>) => Promise<Verified>;
+  /**
+   * DB userId を解決（必要なら新規作成）する。**省略すると token-only**（検証のみ・login 用）になる。
+   * create-on-miss（`getUserIdFromFirebase(...).catch(() => createUser(...))`）は repo 側でここに合成する。
+   */
+  resolveUserId?: (verified: Verified, c: Context<E>, appInfo: AppInfo) => Promise<Id>;
+  /** 検証結果を c.var に載せる。repo 固有の var 名（`decodedToken` / `userRecord` / `userProtocol` 等）を注入する。 */
+  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)` を返す**ため上書きする。
+   */
+  onFailure?: (err: unknown, c: Context<E>) => Response;
+  /** 既定 onFailure の status。既定 `403`（token-only の 401 等は repo が上書き）。 */
+  failureStatus?: ContentfulStatusCode;
+  /** 既定 onFailure の message。既定 `'Forbidden resource'`。 */
+  failureMessage?: string;
+}
+
+/**
+ * NestJS の AuthGuard / TokenGuard 相当の認証 middleware を作る（フリート共通）。
+ * スケルトン（ヘッダ読取 → verify → getAppInfo → resolveUserId → setContext、失敗で console.error +
+ * onFailure）を共有し、repo 固有部分（verify / userId 解決 / var 名 / 失敗レスポンス）だけ注入させる。
+ * `resolveUserId` を省けば token-only middleware になる。
+ */
+export function createAuthMiddleware<E extends Env = Env, Verified = unknown, Id = unknown>(
+  options: AuthMiddlewareOptions<E, Verified, Id>,
+): MiddlewareHandler<E> {
+  const {
+    tokenHeader = 'x-amz-security-token',
+    verify,
+    resolveUserId,
+    setContext,
+    onFailure,
+    failureStatus = 403,
+    failureMessage = 'Forbidden resource',
+  } = options;
+
+  return async (c, next) => {
+    try {
+      const token = c.req.header(tokenHeader) ?? '';
+      const verified = await verify(token, c);
+      const appInfo = getAppInfo(c);
+      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 形に上書き可能）。
+      console.error(e);
+      if (onFailure) {
+        return onFailure(e, c);
+      }
+      throw new HTTPException(failureStatus, { message: failureMessage });
+    }
+    await next();
+  };
+}

package/src/middleware/finalize-response.ts

@@ -0,0 +1,61 @@
+import type { MiddlewareHandler } from 'hono';
+
+/**
+ * レスポンス最終化ミドルウェア。Express/Nest（移植元 `../api`）との byte 一致のため 2 点を行う
+ * （フリート共通仕様 = receptray/winecode hono と同一）:
+ *
+ * 1. **JSON の charset**: Express の res.json は `application/json; charset=utf-8` を返すが、
+ *    Hono の c.json は `application/json`（charset 無し）なので合わせる。
+ * 2. **weak ETag**: Express/`etag` パッケージ互換の
+ *    `W/"<byteLength(16進)>-<sha1(body)をbase64して先頭27文字>"`。Express(=Nest) は GET 等のレスポンスに
+ *    既定で付与するため、hono/etag の独自形式ではなく Express の算法に厳密一致させる。
+ *
+ * SSE（text/event-stream）はストリームを buffer できないため両方スキップ。
+ */
+async function weakEtag(body: ArrayBuffer): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-1', body);
+  const bytes = new Uint8Array(digest);
+  let bin = '';
+  for (const b of bytes) {
+    bin += String.fromCharCode(b);
+  }
+  const b64 = btoa(bin).substring(0, 27);
+  return `W/"${body.byteLength.toString(16)}-${b64}"`;
+}
+
+export function finalizeResponse(): MiddlewareHandler {
+  return async (c, next) => {
+    await next();
+
+    const status = c.res.status;
+    const contentType = c.res.headers.get('content-type') ?? '';
+
+    // SSE / ストリームは触らない。
+    if (contentType.includes('text/event-stream')) {
+      return;
+    }
+
+    // charset 補正対象（JSON で charset 未指定なら付与）。
+    const needsCharset = contentType === 'application/json';
+    // ETag 対象（Express は 204/304 では付けない・既存 ETag は尊重）。
+    const needsEtag = status !== 204 && status !== 304 && !c.res.headers.has('etag') && !!c.res.body;
+
+    if (!needsCharset && !needsEtag) {
+      return;
+    }
+
+    const headers = new Headers(c.res.headers);
+    if (needsCharset) {
+      headers.set('content-type', 'application/json; charset=utf-8');
+    }
+
+    if (needsEtag) {
+      const buf = await c.res.clone().arrayBuffer();
+      headers.set('ETag', await weakEtag(buf));
+      c.res = new Response(buf, { status, statusText: c.res.statusText, headers });
+    } else {
+      // body を読まずヘッダだけ差し替え。
+      c.res = new Response(c.res.body, { status, statusText: c.res.statusText, headers });
+    }
+  };
+}

package/src/middleware/validation.ts

@@ -0,0 +1,84 @@
+import { zValidator } from '@hono/zod-validator';
+import type { Context } from 'hono';
+import type { ZodType } from 'zod';
+
+/** zod v3(ZodError) / v4(core $ZodError) どちらの error でも受けられる最小形 */
+export interface ZodErrorLike {
+  issues: readonly { path: PropertyKey[]; message: string }[];
+}
+
+export type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'cookie' | 'form';
+
+export interface ValidateOptions {
+  /**
+   * 検証失敗時のフック（Sentry 通報など）。**検証の挙動は変えない** — レスポンスは常に
+   * NestJS ValidationPipe 同形の 400 を返す。例外を投げても握り潰す。
+   * 既定は no-op（receptray 互換 = 4xx を通報しない）。foodlabel は Sentry 実通報を差し込む。
+   */
+  onValidationError?: (error: ZodErrorLike, c: Context) => void;
+}
+
+/**
+ * Zod 検証ミドルウェア（フリート共通 = receptray/winecode hono と同一仕様）。
+ * 失敗時は NestJS の ValidationPipe と同形の body を返す:
+ *   { statusCode: 400, message: string[], error: 'Bad Request' }
+ *
+ * NOTE(parity): message の文字列内容は class-validator と Zod で異なる。各 repo の固定 app の
+ * 正常系では DTO 検証 400 は発生しない前提（ビジネス 400 は各エンドポイントで HttpError 忠実再現）。
+ */
+
+function zodToMessages(error: ZodErrorLike): string[] {
+  return error.issues.map((issue) => {
+    const path = issue.path.map(String).join('.');
+    return path ? `${path}: ${issue.message}` : issue.message;
+  });
+}
+
+export function validate<T>(target: ValidationTarget, schema: ZodType<T>, options?: ValidateOptions) {
+  return zValidator(target, schema, (result, c) => {
+    if (!result.success) {
+      const messages = zodToMessages(result.error);
+      // Surface the failing fields in the runtime log. Without this the 400 is
+      // invisible in `wrangler dev`/Workers logs (Sentry is the only sink, and
+      // it is not visible locally), so a field-level type mismatch — e.g. a
+      // string sent to `z.number()` — dies silently and is painful to diagnose.
+      // Paths + zod messages only; no request values are logged.
+      console.warn(`[validation] ${c.req.method} ${c.req.path} (${target}) → 400: ${messages.join('; ')}`);
+      try {
+        options?.onValidationError?.(result.error, c);
+      } catch {
+        // Reporting must never change validation error behavior.
+      }
+      return c.json({ statusCode: 400, message: messages, error: 'Bad Request' }, 400);
+    }
+    return undefined;
+  });
+}
+
+/** Sentry の最小形（`@sentry/cloudflare` 等への直接依存を避けるための構造型）。 */
+export interface SentryScopeLike {
+  setTag(key: string, value: string): void;
+  setContext(key: string, context: Record<string, unknown> | null): void;
+}
+export interface SentryLike {
+  withScope(callback: (scope: SentryScopeLike) => void): void;
+  captureException(error: unknown): void;
+}
+
+/**
+ * DTO 検証 400 を Sentry に通報する `validate` を返すファクトリ（foodlabel/tipsys/winecode で重複していた
+ * reportValidationToSentry を集約）。kit は `@sentry/cloudflare` に依存せず、Sentry モジュールを注入する。
+ * 通報は `tag error.type=dto_validation` ＋ `context validation={errorCount, errors}`（各 /api の
+ * sentry-validation.pipe.ts 準拠）。検証の挙動・レスポンスは `validate` と同一（通報は副作用のみ）。
+ */
+export function createSentryValidate(sentry: SentryLike) {
+  const onValidationError = (error: ZodErrorLike): void => {
+    const messages = zodToMessages(error);
+    sentry.withScope((scope) => {
+      scope.setTag('error.type', 'dto_validation');
+      scope.setContext('validation', { errorCount: messages.length, errors: messages });
+      sentry.captureException(error);
+    });
+  };
+  return <T>(target: ValidationTarget, schema: ZodType<T>) => validate(target, schema, { onValidationError });
+}

package/src/middleware/zod-coerce.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * `/api` の class-transformer @Transform（number-transform.util.ts）を Zod preprocess で忠実再現する。
+ * path/query は常に文字列で来るため数値強制が必要。空白のみ文字列は NaN にして後段の数値スキーマで弾く
+ * （class-validator の @IsInt/@IsNumber が NaN を拒否する挙動と一致。zod v4 は z.number() が NaN を既定拒否）。
+ */
+
+const isBlankString = (value: unknown): value is string => typeof value === 'string' && value.trim() === '';
+
+// toNumber: 空白文字列 → NaN、それ以外 → Number(value)
+const rawToNumber = (value: unknown): unknown => (isBlankString(value) ? Number(undefined) : Number(value));
+
+// toNumberWithDefault: undefined/'' → default、空白 → NaN、else Number
+const rawToNumberWithDefault =
+  (defaultValue: number) =>
+  (value: unknown): unknown => {
+    if (value === undefined || value === '') {
+      return defaultValue;
+    }
+    if (isBlankString(value)) {
+      return Number(undefined);
+    }
+    return Number(value);
+  };
+
+// toOptionalNumber: undefined/null/'' → undefined、空白 → NaN、else Number
+const rawToOptionalNumber = (value: unknown): unknown => {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (isBlankString(value)) {
+    return Number(undefined);
+  }
+  return Number(value);
+};
+
+// toNullableNumber: null/undefined → passthrough、'' → undefined、空白 → NaN、else Number
+const rawToNullableNumber = (value: unknown): unknown => {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (value === '') {
+    return undefined;
+  }
+  if (isBlankString(value)) {
+    return Number(undefined);
+  }
+  return Number(value);
+};
+
+/**
+ * 数値強制スキーマ。`inner` に `z.number().int()` 等を渡して制約を足せる（既定は z.number()）。
+ * 例: zNum(z.number().int()) で整数必須。
+ */
+export const zNum = (inner: z.ZodNumber = z.number()): z.ZodType<number> => z.preprocess(rawToNumber, inner);
+
+export const zNumWithDefault = (defaultValue: number, inner: z.ZodNumber = z.number()): z.ZodType<number> =>
+  z.preprocess(rawToNumberWithDefault(defaultValue), inner);
+
+export const zNumOptional = (inner: z.ZodNumber = z.number()): z.ZodType<number | undefined> =>
+  z.preprocess(rawToOptionalNumber, inner.optional());
+
+export const zNumNullable = (inner: z.ZodNumber = z.number()): z.ZodType<number | null | undefined> =>
+  z.preprocess(rawToNullableNumber, inner.nullish());

package/src/stripe/client.ts

@@ -0,0 +1,48 @@
+import Stripe from 'stripe';
+
+/**
+ * Stripe クライアント生成（フリート共通 = receptray/tipsys hono）。Cloudflare Workers には Node の
+ * http スタックが無いため、Stripe SDK の fetch ベース HttpClient を使う。
+ *
+ * `apiVersion` は **任意**: 各 repo の `/api`（NestJS）と挙動を一致させるため、固定したい repo は
+ * 渡し（例 tipsys は `'2024-04-10'`）、SDK 既定で良い repo は省く（例 receptray）。
+ */
+export interface CreateStripeClientOptions {
+  /** 固定する Stripe API バージョン。省略すると SDK 既定。 */
+  apiVersion?: string;
+}
+
+export function createStripeClient(secret: string, options: CreateStripeClientOptions = {}): Stripe {
+  if (!secret) {
+    throw new Error('Stripe secret is not set');
+  }
+  const config: Stripe.StripeConfig = { httpClient: Stripe.createFetchHttpClient() };
+  if (options.apiVersion) {
+    config.apiVersion = options.apiVersion as Stripe.StripeConfig['apiVersion'];
+  }
+  return new Stripe(secret, config);
+}
+
+/**
+ * Webhook 署名の検証。Workers では同期版 `constructEvent` が使えない（SubtleCrypto が非同期）ため
+ * `constructEventAsync` + `SubtleCryptoProvider` を使う。`secret` は署名検証には無関係だが、検証用の
+ * クライアント生成に必要（API コールはしない）。
+ */
+export function verifyStripeWebhook(
+  secret: string,
+  webhookSecret: string,
+  payload: string | ArrayBuffer,
+  signature: string,
+): Promise<Stripe.Event> {
+  if (!webhookSecret) {
+    throw new Error('Stripe webhook secret is not set');
+  }
+  const stripe = createStripeClient(secret);
+  return stripe.webhooks.constructEventAsync(
+    payload as string,
+    signature,
+    webhookSecret,
+    undefined,
+    Stripe.createSubtleCryptoProvider(),
+  );
+}

package/src/testing/auth.ts

@@ -0,0 +1,62 @@
+import type { Pool } from 'mysql2/promise';
+import type { DecodedIdToken } from '../firebase/firebase-verifier';
+import type { FakeFirebaseVerifier } from './fakes';
+
+/**
+ * app interceptor 互換の認証ヘッダ（`x-amz-security-token` + `x-amz-meta-*`）を組む。
+ * fleet 全 hono repo の route spec で同形に重複していたものを集約。
+ *
+ * - `version` は `app_version`(varchar(10)) に入るため 10 文字以内。
+ * - `contentType: null` を渡すと content-type を付けない（GET 等）。
+ */
+export function authHeaders(
+  token: string,
+  opts: { version?: string; uuid?: string; contentType?: string | null } = {},
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'x-amz-security-token': token,
+    'x-amz-meta-version': opts.version ?? '1.0.0',
+    'x-amz-meta-uuid': opts.uuid ?? 'test-uuid',
+  };
+  if (opts.contentType !== null) {
+    headers['content-type'] = opts.contentType ?? 'application/json';
+  }
+  return headers;
+}
+
+/**
+ * fake firebase にトークンを登録するだけの薄いヘルパ（DB を触らない）。戻り値はトークン。
+ * `users` テーブル形が repo 固有（例: airlec は email 主）で provisionUser が合わない場合に使う。
+ */
+export function registerFirebaseToken(
+  firebase: FakeFirebaseVerifier,
+  uid: string,
+  record: Partial<DecodedIdToken> = {},
+  token = `tok-${uid}`,
+): string {
+  firebase.register(token, { uid, ...record });
+  return token;
+}
+
+/**
+ * fake firebase にトークンを登録し、`users(firebase_uid)` 行を用意して userId を返す。
+ * `users(id, firebase_uid, agree)` の fleet 共通形を前提（foodlabel/receptray など）。同 uid の
+ * 既存行があれば再利用する（冪等）。users テーブル形が異なる repo は registerFirebaseToken + 独自
+ * provision を使う。
+ */
+export async function provisionUser(
+  pool: Pool,
+  firebase: FakeFirebaseVerifier,
+  opts: { uid: string; token?: string; agree?: number; email?: string },
+): Promise<{ userId: number; uid: string; token: string }> {
+  const token = registerFirebaseToken(firebase, opts.uid, opts.email ? { email: opts.email } : {}, opts.token);
+
+  const [existing] = await pool.query('SELECT id FROM users WHERE firebase_uid = ?', [opts.uid]);
+  const rows = existing as { id: number }[];
+  if (rows.length > 0) {
+    return { userId: rows[0].id, uid: opts.uid, token };
+  }
+
+  const [res] = await pool.query('INSERT INTO users (agree, firebase_uid) VALUES (?, ?)', [opts.agree ?? 1, opts.uid]);
+  return { userId: (res as { insertId: number }).insertId, uid: opts.uid, token };
+}

package/src/testing/configurable-fake.ts

@@ -0,0 +1,33 @@
+/**
+ * 部分実装から test double を作る。設定済みメソッドはそのまま、未設定メソッドを呼ぶと
+ * `${name}.${method} not configured` で明示的に失敗する。
+ *
+ * 各 repo の Fake*Gateway に散っていた「`Partial<impl>` を受け取り、未設定なら throw する手書き
+ * クラス」の定型を一本化する。interface がドメインごとに異なる gateway（Stripe 等）でも、これで
+ * 1 行で必要メソッドだけ差した fake を作れる:
+ *
+ *   const stripe = configurableFake<StripeGateway>(
+ *     { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
+ *     'FakeStripeGateway',
+ *   );
+ */
+export function configurableFake<T extends object>(impl: Partial<T>, name = 'fake'): T {
+  return new Proxy(impl, {
+    get(target, prop) {
+      if (prop in target) {
+        return (target as Record<string | symbol, unknown>)[prop];
+      }
+      // Promise インターロップ用プロパティには「未設定メソッド」関数を返さない。返すと fake 自身が
+      // thenable 扱いされ、誤って await / Promise.resolve した瞬間に then() が呼ばれて throw する罠になる。
+      if (prop === 'then' || prop === 'catch' || prop === 'finally') {
+        return undefined;
+      }
+      if (typeof prop === 'string') {
+        return () => {
+          throw new Error(`${name}.${prop} not configured`);
+        };
+      }
+      return undefined;
+    },
+  }) as T;
+}