@rdlabo/workers-hono-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rdlabo-team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @rdlabo/workers-hono-kit
+
+Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudflare Workers](https://workers.cloudflare.com).
+
+It provides the building blocks a NestJS-style API needs but that don't run on `workerd` (no Node.js AWS SDK, no `firebase-admin`), plus middleware that matches Express / NestJS response semantics byte-for-byte:
+
+- **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
+- **AWS Secrets Manager** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) — no AWS SDK.
+- **Middleware**: `finalizeResponse` (Express-compatible weak ETag + JSON charset), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
+- **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff).
+- **HTTP helpers**: `getUserProtocol`, `getAppInfo`, `HttpStatus`.
+
+## Install
+
+```bash
+npm install @rdlabo/workers-hono-kit
+```
+
+Peer dependencies — install the ones you use:
+
+```bash
+npm install hono zod @hono/zod-validator jose aws4fetch
+```
+
+> **TypeScript sources, no build step.** The package is published as `.ts` via the `exports` field and is meant to be consumed by a bundler that compiles TypeScript — wrangler/esbuild, Vite, etc. — targeting `workerd` or another edge runtime. It relies only on Web-standard APIs (`fetch`, `crypto.subtle`, `Response`) available on Cloudflare Workers.
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `finalizeResponse()` | Middleware that adds an Express-compatible weak `ETag` and JSON `charset=utf-8`. |
+| `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). |
+| `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). |
+| `getAuthenticationSecret<T>(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). |
+| `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. |
+| `JoseFirebaseVerifier` / `FirebaseVerifier` / `DecodedIdToken` | Firebase ID-token verification (`verifyIdToken`, `getUser`, `deleteUser`). |
+| `createRemoteFirebaseVerifier(projectId)` | Convenience factory: production verifier with a cached remote JWKS (verification only). |
+| `createServiceAccountVerifier(serviceAccountJson)` | Cached verifier built from a service-account JSON, **with `IdentityToolkit`** (getUser/deleteUser). One per isolate, re-created only when the SA JSON changes. |
+| `IdentityToolkit` / `ServiceAccount` / `SECURETOKEN_JWK_URL` | Identity Toolkit REST client + constants for `getUser` / `deleteUser`. |
+| `retryWhenDeadlock(fn, retries?, delay?)` | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff. |
+| `getUserProtocol(c)` / `IUserProtocol` | Read client IP / UA (`CF-Connecting-IP` → `X-Forwarded-For`). |
+| `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. |
+| `HttpStatus` | HTTP status enum identical to NestJS `@nestjs/common`. |
+| `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. |
+| `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
+| `NEST_REASON_PHRASES` | `{ 400, 401, 403, 404 }` → NestJS reason phrases. |
+| `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
+| `ErrorReporter` / `ErrorReportContext` | Types for a `container.reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
+| `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). `appName`/`version` per repo. |
+| `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin per `/api` parity). |
+
+## Usage
+
+### Response finalization (ETag / charset)
+
+```ts
+import { Hono } from 'hono';
+import { finalizeResponse } from '@rdlabo/workers-hono-kit';
+
+const app = new Hono();
+app.use('*', finalizeResponse());
+```
+
+### Request validation
+
+```ts
+import { validate } from '@rdlabo/workers-hono-kit';
+import { z } from 'zod';
+
+app.post('/users', validate('json', z.object({ name: z.string() })), (c) => {
+  const body = c.req.valid('json'); // typed & validated
+  return c.json(body, 201);
+});
+
+// Report validation failures (response is unchanged):
+validate('json', schema, {
+  onValidationError: (err, c) => Sentry.captureException(err),
+});
+```
+
+`param` / `query` values arrive as strings — coerce numbers with the zod helpers:
+
+```ts
+import { zNum, zNumOptional } from '@rdlabo/workers-hono-kit';
+
+const Params = z.object({ id: zNum(z.number().int()), page: zNumOptional() });
+```
+
+### Firebase ID-token verification
+
+```ts
+import { createRemoteFirebaseVerifier } from '@rdlabo/workers-hono-kit';
+
+const verifier = createRemoteFirebaseVerifier(projectId);
+const decoded = await verifier.verifyIdToken(idToken); // { uid, email, ... }
+```
+
+With `getUser` / `deleteUser` (needs a service account):
+
+```ts
+import { createRemoteJWKSet } from 'jose';
+import { JoseFirebaseVerifier, IdentityToolkit, SECURETOKEN_JWK_URL } from '@rdlabo/workers-hono-kit';
+
+const verifier = new JoseFirebaseVerifier({
+  projectId,
+  keyResolver: createRemoteJWKSet(new URL(SECURETOKEN_JWK_URL)),
+  identity: new IdentityToolkit(serviceAccount),
+});
+```
+
+### AWS Secrets Manager
+
+```ts
+import { getAuthenticationSecret } from '@rdlabo/workers-hono-kit';
+
+interface MySecret {
+  firebaseProduction: string;
+  stripeSecret: string;
+}
+
+const secret = await getAuthenticationSecret<MySecret>(
+  {
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+    region: 'ap-northeast-1',
+  },
+  'myapp/secret',
+);
+```
+
+### Deadlock retry & HTTP helpers
+
+```ts
+import { retryWhenDeadlock, getUserProtocol, getAppInfo, HttpStatus } from '@rdlabo/workers-hono-kit';
+
+await retryWhenDeadlock(() => db.transaction(/* ... */));
+
+const { ipAddress, userAgent } = getUserProtocol(c);
+const appInfo = getAppInfo(c);
+return c.json(body, HttpStatus.CREATED);
+```
+
+### NestJS-shaped error / 404 handlers
+
+`createNestErrorHandler()` renders a thrown `HTTPException` as the NestJS exception-filter
+body, and `nestNotFoundHandler` gives the Express/Nest default 404. The defaults match the
+NestJS canonical shape (`{ statusCode, message, error? }`, `401` omits `error`); each repo
+keeps its own byte-parity via options.
+
+```ts
+import { createNestErrorHandler, nestNotFoundHandler } from '@rdlabo/workers-hono-kit';
+
+app.notFound(nestNotFoundHandler);
+app.onError(createNestErrorHandler());
+
+// Repo-specific parity deltas:
+app.onError(
+  createNestErrorHandler({
+    fieldOrder: 'message-first', // emit { message, error, statusCode } instead of statusCode-first
+    onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') }),
+    isHttpError: (e): e is HttpError => e instanceof HttpError, // a custom error class with a `.body` escape hatch
+  }),
+);
+```
+
+### Auth middleware
+
+Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id →
+set context, with `console.error` + a configurable failure on error). Inject the repo's
+verify/resolver, context-variable names, and failure mode.
+
+`createAuthMiddleware<Env, Verified, Id>` is generic over your Hono `Env`, so `c.set(...)` in
+`setContext` is type-checked against your `Variables`.
+
+```ts
+import { createAuthMiddleware } from '@rdlabo/workers-hono-kit';
+
+// AuthGuard: verify + resolve (and provision) the DB user id.
+const userAuth = createAuthMiddleware<AppEnv, UserRecord, number>({
+  verify: (token) => container.firebase.verifyIdToken(token),
+  resolveUserId: (record, _c, appInfo) =>
+    container.auth.getUserIdFromFirebase(record, appInfo).catch(() => container.auth.createUser(record)),
+  setContext: (c, { verified, appInfo, userId }) => {
+    c.set('userRecord', verified);
+    c.set('userId', userId);
+    c.set('appInfo', appInfo);
+  },
+});
+
+// TokenGuard (login): verify only — omit resolveUserId. Override the failure if needed.
+const tokenAuth = createAuthMiddleware<AppEnv, UserRecord>({
+  verify: (token) => container.firebase.verifyIdToken(token),
+  setContext: (c, { verified }) => c.set('userRecord', verified),
+  onFailure: (_e, c) => c.json({ message: 'Unauthorized', statusCode: 401 }, 401),
+});
+```
+
+### KV cache
+
+```ts
+import { KVCache } from '@rdlabo/workers-hono-kit';
+
+const cache = new KVCache(env.CACHE, { appName: 'myapp' }); // version defaults to 'v8_'
+await cache.set('users', 'byId', userId, user, 600);
+const hit = await cache.get<User>('users', 'byId', userId);
+```
+
+### Stripe (Workers-native)
+
+```ts
+import { createStripeClient, verifyStripeWebhook } from '@rdlabo/workers-hono-kit';
+
+const stripe = createStripeClient(secret); // or { apiVersion: '2024-04-10' } to pin
+const event = await verifyStripeWebhook(secret, webhookSecret, rawBody, c.req.header('stripe-signature') ?? '');
+```
+
+## Local development / linking
+
+If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit": "../../hono-kit"`) rather than from npm, TypeScript and esbuild resolve the package's bare imports from *its own* `node_modules`, which can create a second `zod` instance. That breaks types where your zod-inferred values flow into other libraries (e.g. Drizzle inserts). Dedupe with tsconfig `paths`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "zod": ["node_modules/zod"],
+      "zod/*": ["node_modules/zod/*"],
+      "@hono/zod-validator": ["node_modules/@hono/zod-validator"]
+    }
+  }
+}
+```
+
+When installed from npm normally, package managers dedupe `zod` to a single copy and this is not needed.
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm test            # vitest
+```
+
+## License
+
+[MIT](./LICENSE) © rdlabo-team

package/dist/ai/gateway.d.ts

@@ -0,0 +1,40 @@
+import type { AiGateway, AiGatewayBindingSettings, AiGatewayOptions } from 'ai-gateway-provider';
+export type { AiGateway, AiGatewayOptions } from 'ai-gateway-provider';
+/** Workers の AI binding（`env.AI.gateway(name)`）の最小形。Cloudflare の `AiGateway` が構造的に適合する。 */
+export type AiGatewayBinding = AiGatewayBindingSettings['binding'];
+/**
+ * AI Gateway 設定。2 系統:
+ *  - binding 形: Workers ランタイム（本番 / `wrangler dev`）。`env.AI.gateway(name)` を渡す。
+ *    binding 経由は同一アカウント内で事前認証されるため Gateway トークン不要。
+ *  - REST 形: Workers 外（Node の eval ハーネス等、binding 不可）。accountId + gateway + token で REST。
+ */
+export type AiGatewayConfig = {
+    /** `env.AI.gateway(name)` 等の AI Gateway binding。 */
+    binding: AiGatewayBinding;
+    /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+    options?: AiGatewayOptions;
+} | {
+    /** Cloudflare アカウント ID。 */
+    accountId: string;
+    /** AI Gateway 名。 */
+    gateway: string;
+    /**
+     * `cf-aig-authorization` に載せる Gateway 認証トークン。Authenticated Gateway のときだけ必要。
+     * unauthenticated Gateway では省略可（プロバイダの API キーではなく Gateway 自体への認証）。
+     */
+    token?: string;
+    /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+    options?: AiGatewayOptions;
+};
+export interface AiGatewayProvider {
+    /**
+     * `@ai-sdk/*` のモデルを包んで AI Gateway 経由にする。
+     * 例: `aigateway(createAnthropic({ apiKey }).('claude-...'))`。
+     * 配列を渡すとフォールバック（先頭から順に試行）になる。
+     */
+    aigateway: AiGateway;
+}
+/**
+ * AI Gateway 用のプロバイダを生成する。binding 形 / REST 形のどちらでも可（欠落時は fail-fast）。
+ */
+export declare function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvider;

package/dist/ai/gateway.js

@@ -0,0 +1,36 @@
+/**
+ * Cloudflare AI Gateway のプロバイダ生成（`ai` SDK + `ai-gateway-provider`）。
+ * フリート共通 = foodlabel / winecode / receptray hono の AI 呼び出しを必ず Gateway 経由にする。
+ *
+ * `createAiGateway` が返す wrapper で `@ai-sdk/*` のモデルを包むと、SDK が組み立てた
+ * プロバイダ宛リクエスト（api.openai.com / api.anthropic.com / *-aiplatform.googleapis.com 等）を
+ * AI Gateway の Universal Endpoint 経由に差し替える。OpenAI / Anthropic / Google Vertex(SA) の
+ * いずれも同じ `aigateway(model)` で透過的にルーティングされる（Vertex も対応）。
+ *
+ * ここはインフラ層（Gateway 識別子と認証トークンの注入だけ）。プロバイダの API キーや
+ * Vertex の SA 認証情報は各 repo 側でモデル生成時に渡す（pass-through）。
+ */
+import { createAiGateway } from 'ai-gateway-provider';
+/**
+ * AI Gateway 用のプロバイダを生成する。binding 形 / REST 形のどちらでも可（欠落時は fail-fast）。
+ */
+export function createAiGatewayProvider(config) {
+    if ('binding' in config) {
+        return { aigateway: createAiGateway({ binding: config.binding, options: config.options }) };
+    }
+    if (!config.accountId) {
+        throw new Error('AI Gateway: accountId が未設定です');
+    }
+    if (!config.gateway) {
+        throw new Error('AI Gateway: gateway 名が未設定です');
+    }
+    // token は Authenticated Gateway のときだけ apiKey として送る。unauthenticated では undefined で可。
+    return {
+        aigateway: createAiGateway({
+            accountId: config.accountId,
+            gateway: config.gateway,
+            apiKey: config.token,
+            options: config.options,
+        }),
+    };
+}

package/dist/aws/cloudfront.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
+ * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ *
+ * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
+ *   '+' -> '-' , '/' -> '~' , '=' -> '_'
+ * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ */
+export declare function getCloudFrontSignedUrl(url: string, privateKeyPem: string, keyPairId: string, dateLessThan: string | number | Date): Promise<string>;

package/dist/aws/cloudfront.js

@@ -0,0 +1,43 @@
+/**
+ * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
+ * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ *
+ * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
+ *   '+' -> '-' , '/' -> '~' , '=' -> '_'
+ * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ */
+export async function getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan) {
+    const epochSeconds = Math.round(new Date(dateLessThan).getTime() / 1000);
+    const policy = JSON.stringify({
+        Statement: [{ Resource: url, Condition: { DateLessThan: { 'AWS:EpochTime': epochSeconds } } }],
+    });
+    const key = await crypto.subtle.importKey('pkcs8', pemToDer(privateKeyPem), { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-1' }, false, ['sign']);
+    const signatureBuffer = await crypto.subtle.sign({ name: 'RSASSA-PKCS1-v1_5' }, key, new TextEncoder().encode(policy));
+    const signature = toUrlSafeBase64(arrayBufferToBase64(signatureBuffer));
+    const separator = url.includes('?') ? '&' : '?';
+    // @aws-sdk/cloudfront-signer のクエリ順: Expires -> Key-Pair-Id -> Signature
+    return `${url}${separator}Expires=${epochSeconds}&Key-Pair-Id=${keyPairId}&Signature=${signature}`;
+}
+function toUrlSafeBase64(value) {
+    return value.replace(/\+/g, '-').replace(/=/g, '_').replace(/\//g, '~');
+}
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (const b of bytes) {
+        binary += String.fromCharCode(b);
+    }
+    return btoa(binary);
+}
+function pemToDer(pem) {
+    const base64 = pem
+        .replace(/-----BEGIN [^-]+-----/, '')
+        .replace(/-----END [^-]+-----/, '')
+        .replace(/\s+/g, '');
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}

package/dist/aws/secrets-manager.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AWS Secrets Manager の GetSecretValue を aws4fetch（SigV4 署名 fetch）で叩く汎用ヘルパ。
+ * Cloudflare Workers には AWS SDK も IAM ロールも無いため、AWS の静的キーを Workers secrets として
+ * 渡して署名する（移植元 `api/src/secrets-manager.ts` 相当）。DB 認証情報は Hyperdrive 側に持つので対象外。
+ *
+ * Secret の中身（スキーマ）と secretId は repo ごとに異なるため、`<T>` と `secretId` を呼び出し側が渡す。
+ */
+export interface AwsSecretsOptions {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    region: string;
+}
+export declare function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId: string): Promise<T>;

package/dist/aws/secrets-manager.js

@@ -0,0 +1,43 @@
+import { AwsClient } from 'aws4fetch';
+/**
+ * Per-isolate cache: Secrets Manager は isolate ごと 1 回だけ叩く。region+accessKeyId+secretId を
+ * キーにし、資格情報ローテーション時は再取得する。promise をキャッシュして同時初回リクエストが 1 回の
+ * 呼び出しを共有する。reject 時はキャッシュをクリアして retry を許す。
+ */
+let cache = null;
+export function getAuthenticationSecret(options, secretId) {
+    const key = `${options.region}:${options.accessKeyId}:${secretId}`;
+    if (cache?.key !== key) {
+        const value = fetchSecret(options, secretId).catch((error) => {
+            cache = null;
+            throw error;
+        });
+        cache = { key, value };
+    }
+    return cache.value;
+}
+async function fetchSecret(options, secretId) {
+    const aws = new AwsClient({
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+        sessionToken: options.sessionToken,
+        service: 'secretsmanager',
+        region: options.region,
+    });
+    const response = await aws.fetch(`https://secretsmanager.${options.region}.amazonaws.com/`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-amz-json-1.1',
+            'X-Amz-Target': 'secretsmanager.GetSecretValue',
+        },
+        body: JSON.stringify({ SecretId: secretId, VersionStage: 'AWSCURRENT' }),
+    });
+    if (!response.ok) {
+        throw new Error(`Secrets Manager GetSecretValue failed: ${response.status} ${await response.text()}`);
+    }
+    const body = (await response.json());
+    if (!body.SecretString) {
+        throw new Error('Secrets Manager GetSecretValue returned no SecretString');
+    }
+    return JSON.parse(body.SecretString);
+}

package/dist/cache/kv-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Workers KV を使った cache-aside キャッシュ（フリート共通 = winecode/tipsys hono の CacheService）。
+ * 同一 DB を参照する透過キャッシュなので `/api` とレスポンスは一致する（perf 層であり parity に影響しない）。
+ *
+ * キー構成は各 repo の `/api`（旧 Valkey）と一致させる:
+ *   `${appName}${version}${table}_${type}_${column}`  （column: id が string なら sha256hex、number はそのまま）
+ * KV の expirationTtl は 60s 下限のため lifetime を 60 でクランプする。
+ */
+/** @cloudflare/workers-types の KVNamespace 最小サブセット（get/put/delete のみ使用）。 */
+export interface KVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface KVCacheOptions {
+    /** キー前置（repo 名）。例 `'winecode'` / `'tipsys'`。 */
+    appName: string;
+    /** バージョン前置。既定 `'v8_'`。 */
+    version?: string;
+    /** lifetime の下限秒（KV の最小 TTL）。既定 `60`。 */
+    minTtlSeconds?: number;
+    /** lifetime 未指定時の既定秒。既定 `600`。 */
+    defaultLifetime?: number;
+}
+interface CacheSetItem {
+    table: string;
+    type: string | number;
+    id: string | number;
+    data: unknown;
+    lifetime?: number;
+}
+interface CacheKeyItem {
+    table: string;
+    type: string | number;
+    id: string | number;
+}
+export declare class KVCache {
+    #private;
+    constructor(kv: KVNamespace, options: KVCacheOptions);
+    get<T>(table: string, type: string | number, id: string | number): Promise<T | undefined>;
+    set(table: string, type: string | number, id: string | number, data: unknown, lifetime?: number): Promise<void>;
+    setMany(items: CacheSetItem[]): Promise<void>;
+    getMany<T>(items: CacheKeyItem[]): Promise<{
+        id: string | number;
+        value: T | undefined;
+    }[]>;
+    delete(table: string, type: string | number, id: string | number): Promise<void>;
+}
+export {};

package/dist/cache/kv-cache.js

@@ -0,0 +1,88 @@
+/**
+ * Workers KV を使った cache-aside キャッシュ（フリート共通 = winecode/tipsys hono の CacheService）。
+ * 同一 DB を参照する透過キャッシュなので `/api` とレスポンスは一致する（perf 層であり parity に影響しない）。
+ *
+ * キー構成は各 repo の `/api`（旧 Valkey）と一致させる:
+ *   `${appName}${version}${table}_${type}_${column}`  （column: id が string なら sha256hex、number はそのまま）
+ * KV の expirationTtl は 60s 下限のため lifetime を 60 でクランプする。
+ */
+const encoder = new TextEncoder();
+async function sha256Hex(input) {
+    const digest = await crypto.subtle.digest('SHA-256', encoder.encode(input));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+export class KVCache {
+    #kv;
+    #appName;
+    #version;
+    #minTtl;
+    #defaultLifetime;
+    constructor(kv, options) {
+        this.#kv = kv;
+        this.#appName = options.appName;
+        this.#version = options.version ?? 'v8_';
+        this.#minTtl = options.minTtlSeconds ?? 60;
+        this.#defaultLifetime = options.defaultLifetime ?? 600;
+    }
+    async #buildKey(table, type, id) {
+        const column = typeof id === 'string' ? await sha256Hex(id) : id;
+        const key = `${this.#appName}${this.#version}${table}_${type}_${column}`;
+        // KV のキーは 512〜1024 バイト上限。超えるものはキャッシュ対象外（cache-aside なので DB 直読みに落ちる）。
+        if (encoder.encode(key).byteLength > 1024) {
+            return undefined;
+        }
+        return key;
+    }
+    async get(table, type, id) {
+        const key = await this.#buildKey(table, type, id);
+        if (!key) {
+            return undefined;
+        }
+        try {
+            const data = await this.#kv.get(key);
+            if (!data) {
+                return undefined;
+            }
+            return JSON.parse(data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async set(table, type, id, data, lifetime) {
+        if (!data) {
+            return;
+        }
+        const key = await this.#buildKey(table, type, id);
+        if (!key) {
+            return;
+        }
+        let payload;
+        try {
+            payload = JSON.stringify(data);
+        }
+        catch {
+            return;
+        }
+        const ttl = Math.max(this.#minTtl, lifetime ?? this.#defaultLifetime);
+        await this.#kv.put(key, payload, { expirationTtl: ttl }).catch(() => undefined);
+    }
+    async setMany(items) {
+        if (items.length === 0) {
+            return;
+        }
+        await Promise.all(items.map((i) => this.set(i.table, i.type, i.id, i.data, i.lifetime)));
+    }
+    // T は呼び出し側が指定する戻り値型（get<T> と同じく ergonomics 目的）。
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+    async getMany(items) {
+        return Promise.all(items.map(async (i) => ({ id: i.id, value: await this.get(i.table, i.type, i.id) })));
+    }
+    async delete(table, type, id) {
+        const key = await this.#buildKey(table, type, id);
+        if (!key) {
+            return;
+        }
+        await this.#kv.delete(key).catch(() => undefined);
+    }
+}

package/dist/db/connection.d.ts

@@ -0,0 +1,41 @@
+import type { Connection } from 'mysql2/promise';
+/**
+ * Hyperdrive バインディングの最小形（@cloudflare/workers-types への依存を避けるための構造型）。
+ */
+export interface HyperdriveLike {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port: number;
+}
+/**
+ * Hyperdrive バインディングから mysql2 の createConnection 用オプションを作る。
+ * `disableEval: true`（Workers で eval 不可）は既定で付与。`extra` で timezone 等を上書き/追加。
+ *
+ * `decimalNumbers: true`: DECIMAL/NEWDECIMAL を文字列でなく JS number で返す。Drizzle の
+ * `$inferSelect`（decimal→string）と生 SQL reads の戻り値を、各 repo の数値ドメイン型
+ * （nutrition の number 等）に揃えるため既定で有効化。precision/scale が JS の安全整数域
+ * （decimal(15,2) 程度まで）を超える列が無いことが前提。
+ *
+ * `timezone: '+09:00'`: フリートの接続先 RDB は session time_zone=Asia/Tokyo。mysql2 の driver
+ * `timezone` 既定は `'local'`＝Workers では UTC で、揃わないと `datetime/timestamp` の生 Date 読みが
+ * +9h・生 Date 書きが −9h ズレる（NestJS は JST 実行で一致＝移植で顕在化する潜在バグ）。driver を
+ * 固定すれば round-trip の観測値は DB の session tz に非依存（内部格納 UTC 値だけ変わるが app 不可視）。
+ * 非 JST repo は `extra: { timezone: '...' }` で上書き可。
+ */
+export declare function hyperdriveConnectionOptions(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Record<string, unknown>;
+export interface ExecutionContextLike {
+    waitUntil(promise: Promise<unknown>): void;
+}
+/**
+ * primary/replica の接続を開いて `fn` を実行し、finally で `ctx.waitUntil` 越しに閉じる
+ * （receptray/tipsys の worker entry の接続ライフサイクル相当）。
+ */
+export declare function withMysqlConnections<T>(hyperdrives: {
+    primary: HyperdriveLike;
+    replica: HyperdriveLike;
+}, ctx: ExecutionContextLike, fn: (connections: {
+    primary: Connection;
+    replica: Connection;
+}) => Promise<T>, connectionOptions?: Record<string, unknown>): Promise<T>;