@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -40,7 +40,8 @@
     "!src/**/*.spec.ts"
   ],
   "bin": {
-    "workers-hono-kit-sync-dev-aws": "./scripts/sync-dev-aws.mjs"
+    "workers-hono-kit-sync-dev-aws": "./scripts/sync-dev-aws.mjs",
+    "workers-hono-kit-check-subrequest-fanout": "./scripts/check-subrequest-fanout.mjs"
   },
   "exports": {
     ".": {

package/scripts/check-subrequest-fanout.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * check-subrequest-fanout — flag per-item external-call fan-outs that scale with data size.
+ *
+ * Cloudflare Workers cap subrequests per invocation (50 free / 1000 paid). Looping an external call
+ * (fetch / AI / Stripe / push / ES) once per row reintroduces an unbounded fan-out that eventually
+ * exceeds the cap as the userbase/data grows. This gate greps for the concurrency-loop markers that
+ * usually wrap such fan-outs and fails CI unless the site is explicitly annotated as safe.
+ *
+ * Markers: `runWithConcurrency(`, `PromisePool`, `.withConcurrency(`.
+ *
+ * To allow a genuinely-safe site (e.g. the loop body only writes to the DB over TCP, which is NOT a
+ * subrequest, or the iteration count is hard-capped), put `subrequest-ok` in a comment on the same
+ * line or the line immediately above. Prefer a short reason, e.g. `// subrequest-ok: DB writes only`.
+ *
+ * Usage:
+ *   node node_modules/@rdlabo/workers-hono-kit/scripts/check-subrequest-fanout.mjs [dir ...]
+ * Defaults to scanning `src`. Exits 1 if any un-annotated marker is found.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MARKER = /runWithConcurrency\(|PromisePool|\.withConcurrency\(/;
+const ALLOW = /subrequest-ok/;
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', 'coverage']);
+
+/** Recursively collect .ts files (excluding *.spec.ts / *.test.ts). */
+function collect(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      if (!SKIP_DIRS.has(name)) {
+        out.push(...collect(full));
+      }
+    } else if (name.endsWith('.ts') && !name.endsWith('.spec.ts') && !name.endsWith('.test.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+const targets = process.argv.slice(2);
+const roots = targets.length > 0 ? targets : ['src'];
+
+const violations = [];
+for (const root of roots) {
+  for (const file of collect(root)) {
+    const lines = readFileSync(file, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      if (!MARKER.test(line)) {
+        return;
+      }
+      // Only flag executable code, not porting notes / JSDoc that merely mention the markers.
+      const trimmed = line.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+        return;
+      }
+      const prev = i > 0 ? lines[i - 1] : '';
+      if (ALLOW.test(line) || ALLOW.test(prev)) {
+        return;
+      }
+      violations.push({ file, line: i + 1, text: trimmed });
+    });
+  }
+}
+
+if (violations.length > 0) {
+  console.error('✖ subrequest fan-out gate: un-annotated concurrency loop(s) found.');
+  console.error('  Each may loop an external call per item (fetch/AI/Stripe/push/ES) and blow the');
+  console.error('  Workers subrequest cap as data grows. Move it behind a queue / cap it, or, if the');
+  console.error('  loop body is DB-only or hard-capped, annotate with `// subrequest-ok: <reason>`.\n');
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.line}  ${v.text}`);
+  }
+  process.exit(1);
+}
+
+console.log('✓ subrequest fan-out gate: no un-annotated concurrency loops.');

package/src/ai/gateway.ts

@@ -1,61 +1,100 @@
 /**
- * Cloudflare AI Gateway のプロバイダ生成（`ai` SDK + `ai-gateway-provider`）。
- * フリート共通 = foodlabel / winecode / receptray hono の AI 呼び出しを必ず Gateway 経由にする。
+ * Cloudflare AI Gateway provider factory built on the Vercel AI SDK and `ai-gateway-provider`.
  *
- * `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 も対応）。
+ * Routes OpenAI, Anthropic, and Google Vertex `@ai-sdk/*` models through the AI Gateway Universal
+ * Endpoint. The wrapper returned by `createAiGateway` intercepts the provider-bound requests the SDK
+ * assembles (`api.openai.com`, `api.anthropic.com`, `*-aiplatform.googleapis.com`, etc.) and redirects
+ * them through the Gateway. Every provider is routed transparently via the same `aigateway(model)` call.
  *
- * ここはインフラ層（Gateway 識別子と認証トークンの注入だけ）。プロバイダの API キーや
- * Vertex の SA 認証情報は各 repo 側でモデル生成時に渡す（pass-through）。
+ * @remarks
+ * This module is purely the infrastructure layer: it injects only the Gateway identifier and (optionally)
+ * the Gateway authentication token. Provider API keys and Vertex service-account credentials are supplied
+ * by the caller at model-construction time and passed through untouched.
  */
 import { createAiGateway } from 'ai-gateway-provider';
 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` が構造的に適合する。 */
+/**
+ * Minimal shape of a Workers AI binding (`env.AI.gateway(name)`).
+ *
+ * @remarks
+ * Cloudflare's runtime `AiGateway` type is structurally compatible with this binding shape.
+ */
 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。
+ * Configuration for the AI Gateway provider. This is a union with two mutually exclusive forms.
+ *
+ * @remarks
+ * - **Binding form** — for the Workers runtime (production and `wrangler dev`). Pass the
+ *   `env.AI.gateway(name)` binding. Requests through a binding are pre-authenticated within the same
+ *   Cloudflare account, so no Gateway token is required.
+ * - **REST form** — for non-Workers contexts where a binding is unavailable (e.g. a Node evaluation
+ *   harness). Supply `accountId`, `gateway`, and (for authenticated Gateways) `token` to reach the
+ *   Gateway over REST.
  */
 export type AiGatewayConfig =
   | {
-      /** `env.AI.gateway(name)` 等の AI Gateway binding。 */
+      /** The AI Gateway binding, typically obtained via `env.AI.gateway(name)`. */
       binding: AiGatewayBinding;
-      /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+      /** Optional Gateway options such as caching, retries, and request metadata. */
       options?: AiGatewayOptions;
     }
   | {
-      /** Cloudflare アカウント ID。 */
+      /** Cloudflare account ID that owns the Gateway. */
       accountId: string;
-      /** AI Gateway 名。 */
+      /** AI Gateway name. */
       gateway: string;
       /**
-       * `cf-aig-authorization` に載せる Gateway 認証トークン。Authenticated Gateway のときだけ必要。
-       * unauthenticated Gateway では省略可（プロバイダの API キーではなく Gateway 自体への認証）。
+       * Gateway authentication token sent in the `cf-aig-authorization` header. Required only for an
+       * Authenticated Gateway; omit it for an unauthenticated Gateway. This authenticates the request to
+       * the Gateway itself and is distinct from any provider API key.
        */
       token?: string;
-      /** キャッシュ / リトライ / メタデータ等の Gateway オプション（任意）。 */
+      /** Optional Gateway options such as caching, retries, and request metadata. */
       options?: AiGatewayOptions;
     };
 
+/** Provider object exposing the AI Gateway model wrapper. */
 export interface AiGatewayProvider {
   /**
-   * `@ai-sdk/*` のモデルを包んで AI Gateway 経由にする。
-   * 例: `aigateway(createAnthropic({ apiKey }).('claude-...'))`。
-   * 配列を渡すとフォールバック（先頭から順に試行）になる。
+   * Wraps an `@ai-sdk/*` model so its requests are routed through the AI Gateway.
+   *
+   * @remarks
+   * Example invocation: `aigateway(createAnthropic({ apiKey })('claude-...'))`. Passing an array of
+   * models enables fallback behavior — each model is attempted in order from the start of the array.
    */
   aigateway: AiGateway;
 }
 
 /**
- * AI Gateway 用のプロバイダを生成する。binding 形 / REST 形のどちらでも可（欠落時は fail-fast）。
+ * Create an AI Gateway provider from either the binding form or the REST form of the configuration.
+ *
+ * @param config - The Gateway configuration; either the binding form or the REST form.
+ * @returns A provider whose `aigateway` wrapper routes models through the AI Gateway.
+ * @throws Error When the REST form is used and `accountId` or `gateway` is missing (fail-fast).
+ * @example
+ * ```ts
+ * // Binding form (Workers runtime: production / wrangler dev)
+ * import { createAnthropic } from '@ai-sdk/anthropic';
+ *
+ * const { aigateway } = createAiGatewayProvider({ binding: env.AI.gateway('my-gateway') });
+ * const model = aigateway(createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-3-5-sonnet-latest'));
+ * ```
+ * @example
+ * ```ts
+ * // REST form (non-Workers context, e.g. a Node evaluation harness)
+ * import { createOpenAI } from '@ai-sdk/openai';
+ *
+ * const { aigateway } = createAiGatewayProvider({
+ *   accountId: process.env.CF_ACCOUNT_ID!,
+ *   gateway: 'my-gateway',
+ *   token: process.env.CF_AIG_TOKEN, // only for an Authenticated Gateway
+ * });
+ * const model = aigateway(createOpenAI({ apiKey: process.env.OPENAI_API_KEY })('gpt-4o'));
+ * ```
  */
 export function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvider {
   if ('binding' in config) {
@@ -63,13 +102,13 @@ export function createAiGatewayProvider(config: AiGatewayConfig): AiGatewayProvi
   }
 
   if (!config.accountId) {
-    throw new Error('AI Gateway: accountId が未設定です');
+    throw new Error('AI Gateway: accountId is not set');
   }
   if (!config.gateway) {
-    throw new Error('AI Gateway: gateway 名が未設定です');
+    throw new Error('AI Gateway: gateway name is not set');
   }
 
-  // token は Authenticated Gateway のときだけ apiKey として送る。unauthenticated では undefined で可。
+  // The token is sent as apiKey only for an Authenticated Gateway; undefined is fine when unauthenticated.
   return {
     aigateway: createAiGateway({
       accountId: config.accountId,

package/src/aws/cloudfront.ts

@@ -1,10 +1,28 @@
 /**
- * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
- * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ * Generate a CloudFront signed URL using a canned policy, implemented natively for Cloudflare Workers.
  *
- * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
- *   '+' -> '-' , '/' -> '~' , '=' -> '_'
- * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ * Reimplements `getSignedUrl` from `@aws-sdk/cloudfront-signer` on top of the Web Crypto API, so no
+ * `@aws-sdk` dependency is required. The canned policy is signed with RSASSA-PKCS1-v1_5 and SHA-1, the
+ * signature is converted to AWS URL-safe base64 (`+` -> `-`, `/` -> `~`, `=` -> `_`), and the query
+ * parameters are appended in the order `Expires`, `Key-Pair-Id`, `Signature`.
+ *
+ * @remarks
+ * The output is byte-for-byte identical to that of `@aws-sdk/cloudfront-signer`.
+ *
+ * @param url - The resource URL to sign.
+ * @param privateKeyPem - The CloudFront key group private key in PKCS#8 PEM format.
+ * @param keyPairId - The CloudFront public key (key pair) ID associated with the private key.
+ * @param dateLessThan - Expiry time, accepted as a `Date`, epoch-millisecond number, or date string.
+ * @returns The signed URL with the `Expires`, `Key-Pair-Id`, and `Signature` query parameters appended.
+ * @example
+ * ```ts
+ * const signedUrl = await getCloudFrontSignedUrl(
+ *   'https://cdn.example.com/private/video.mp4',
+ *   env.CLOUDFRONT_PRIVATE_KEY,
+ *   env.CLOUDFRONT_KEY_PAIR_ID,
+ *   Date.now() + 60 * 60 * 1000, // valid for one hour
+ * );
+ * ```
  */
 export async function getCloudFrontSignedUrl(
   url: string,
@@ -34,14 +52,29 @@ export async function getCloudFrontSignedUrl(
   const signature = toUrlSafeBase64(arrayBufferToBase64(signatureBuffer));
   const separator = url.includes('?') ? '&' : '?';
 
-  // @aws-sdk/cloudfront-signer のクエリ順: Expires -> Key-Pair-Id -> Signature
+  // Query order used by @aws-sdk/cloudfront-signer: Expires -> Key-Pair-Id -> Signature
   return `${url}${separator}Expires=${epochSeconds}&Key-Pair-Id=${keyPairId}&Signature=${signature}`;
 }
 
+/**
+ * Convert standard base64 to the URL-safe alphabet expected in CloudFront signatures.
+ *
+ * @param value - A standard base64 string.
+ * @returns The base64 string with `+` -> `-`, `=` -> `_`, and `/` -> `~`.
+ * @internal
+ */
+
 function toUrlSafeBase64(value: string): string {
   return value.replace(/\+/g, '-').replace(/=/g, '_').replace(/\//g, '~');
 }
 
+/**
+ * Encode an `ArrayBuffer` to standard base64.
+ *
+ * @param buffer - The raw bytes to encode.
+ * @returns The standard base64 representation of the buffer.
+ * @internal
+ */
 function arrayBufferToBase64(buffer: ArrayBuffer): string {
   const bytes = new Uint8Array(buffer);
   let binary = '';
@@ -51,6 +84,13 @@ function arrayBufferToBase64(buffer: ArrayBuffer): string {
   return btoa(binary);
 }
 
+/**
+ * Decode a PKCS#8 PEM private key into its DER `ArrayBuffer`.
+ *
+ * @param pem - The PEM-encoded key, including the BEGIN/END armor.
+ * @returns The decoded DER bytes, suitable for `crypto.subtle.importKey('pkcs8', ...)`.
+ * @internal
+ */
 function pemToDer(pem: string): ArrayBuffer {
   const base64 = pem
     .replace(/-----BEGIN [^-]+-----/, '')

package/src/aws/secrets-manager.ts

@@ -1,26 +1,66 @@
 import { AwsClient } from 'aws4fetch';
 
 /**
- * AWS Secrets Manager の GetSecretValue を aws4fetch（SigV4 署名 fetch）で叩く汎用ヘルパ。
- * Cloudflare Workers には AWS SDK も IAM ロールも無いため、AWS の静的キーを Workers secrets として
- * 渡して署名する（移植元 `api/src/secrets-manager.ts` 相当）。DB 認証情報は Hyperdrive 側に持つので対象外。
+ * AWS credentials used to sign Secrets Manager requests.
  *
- * Secret の中身（スキーマ）と secretId は repo ごとに異なるため、`<T>` と `secretId` を呼び出し側が渡す。
+ * @remarks
+ * Cloudflare Workers have neither the AWS SDK nor IAM role credentials, so static AWS keys are supplied
+ * as Workers secrets and used to produce a SigV4 signature.
  */
 export interface AwsSecretsOptions {
+  /** AWS access key ID. */
   accessKeyId: string;
+  /** AWS secret access key. */
   secretAccessKey: string;
+  /** Optional STS session token, required when using temporary credentials. */
   sessionToken?: string;
+  /** AWS region of the Secrets Manager endpoint, e.g. `ap-northeast-1`. */
   region: string;
 }
 
 /**
- * Per-isolate cache: Secrets Manager は isolate ごと 1 回だけ叩く。region+accessKeyId+secretId を
- * キーにし、資格情報ローテーション時は再取得する。promise をキャッシュして同時初回リクエストが 1 回の
- * 呼び出しを共有する。reject 時はキャッシュをクリアして retry を許す。
+ * Per-isolate cache for the fetched secret.
+ *
+ * @remarks
+ * Secrets Manager is queried at most once per isolate. The entry is keyed by
+ * `region:accessKeyId:secretId`, so rotating credentials triggers a fresh fetch. The in-flight promise
+ * itself is cached so that concurrent first-time callers share a single request. On rejection the cache
+ * is cleared so a failed fetch can be retried.
+ *
+ * @internal
  */
 let cache: { key: string; value: Promise<unknown> } | null = null;
 
+/**
+ * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
+ *
+ * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
+ * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
+ * cache entry so the next call retries.
+ *
+ * @typeParam T - The shape of the JSON-parsed secret payload, supplied by the caller.
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The parsed secret value cast to `T`.
+ * @throws Error When the Secrets Manager response is not OK, or when it contains no `SecretString`.
+ * @example
+ * ```ts
+ * interface DbSecret {
+ *   username: string;
+ *   password: string;
+ * }
+ *
+ * const secret = await getAuthenticationSecret<DbSecret>(
+ *   {
+ *     accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *     secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *     region: 'ap-northeast-1',
+ *   },
+ *   'prod/db/credentials',
+ * );
+ * ```
+ */
 export function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId: string): Promise<T> {
   const key = `${options.region}:${options.accessKeyId}:${secretId}`;
   if (cache?.key !== key) {
@@ -33,6 +73,15 @@ export function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId:
   return cache.value as Promise<T>;
 }
 
+/**
+ * Perform the SigV4-signed `GetSecretValue` request and parse the returned `SecretString`.
+ *
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The JSON-parsed secret payload.
+ * @throws Error When the response is not OK, or when it contains no `SecretString`.
+ * @internal
+ */
 async function fetchSecret(options: AwsSecretsOptions, secretId: string): Promise<unknown> {
   const aws = new AwsClient({
     accessKeyId: options.accessKeyId,