サンプル: Password Gate

静的な zfb サイトの前段に手書きの Cloudflare Worker を置き、アセットを返す前に共有パスワードを確認するサンプル

ライブデモ: zfb-example-password-gate.takazudomodular.com

リポジトリ: Takazudo/zfb-example-password-gate

何を示すか

• 純粋な SSG ビルド（output: "static"）の dist/ を Workers Static Assets としてデプロイする構成。

• デプロイのエントリポイントに 手書きの Worker を指定する構成（main = "src/index.ts"）。zfb のアダプタはプロジェクトのどこにも入っていません。

• [assets].run_worker_first = true — ゲートが実際に走るのか、それとも実ファイルに解決されるパスすべてで黙って迂回されるのかを決める、たった 1 行の設定。

• Cloudflare の Worker シークレット（SITE_PASSWORD）を読み、開発用フォールバックを localhost に限定し、デプロイ先でシークレットが無い場合は閉じる方法。

• zfb の設定を zfb.config.ts ではなく zfb.config.json で書く構成。オプションは同じで、設定ファイル自体の TypeScript ビルドが不要になります。

使用技術

Worker は src/index.ts にあり、Cookie の解析とシリアライズは src/cookies.ts にあります。このサンプルのサーバー側ロジックはこの 2 ファイルに収まっています。

必要なものと設定

Cloudflare アカウントなしで動く範囲。 pnpm dev、pnpm build、pnpm preview は Node と pnpm さえあれば動き、静的サイトだけを扱います。ゲートもローカルで動かせます。ビルド後に wrangler dev --local を実行すれば、ビルド済みの dist/ に対して Worker が動きます。SITE_PASSWORD が無いとき開発用パスワードにフォールバックするのは、平文 HTTP の loopback オリジンだけです。それ以外のオリジンでは、シークレットを設定するまでログインをすべて拒否します。

Cloudflare が必要になる範囲。 必要なのはデプロイだけです。

• Worker シークレット SITE_PASSWORD — pnpm exec wrangler secret put SITE_PASSWORD で設定します。これは Cloudflare 側 のシークレットで、wrangler.toml の var でも GitHub のシークレットでもありません。Worker シークレットは即座に反映され、その後のデプロイでも保持されます。

• リポジトリの deploy.yml が使う GitHub Actions シークレット: CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID。トークンには Account · Workers Scripts（Edit）、Account Settings（Read）、さらに Zone · Workers Routes（Edit）が必要です。Zone 権限は省略できません。wrangler.toml が custom_domain ルートを張っており、そのルート作成が zone レベルの操作だからです。

• プロビジョニングするリソースはありません。 KV ネームスペースも D1 データベースもマイグレーションもシードデータも不要です。ASSETS バインディングは dist/ から Cloudflare が自動で作ります。

ライブデモはゲートされていますが、書き込みはできません。 何かを保存するフォームもデータベースもユーザーごとの状態もありません。ログイン後は共有パスワードから導出した Bearer マーカー Cookie が発行されます。共有パスワードのゲートを認証とみなす前に、仕組み の最後にある注意書きを読んでください。

仕組み

なぜアダプタではなく Worker を手書きするのか

@takazudo/zfb-adapter-cloudflare は ページ をリクエスト時にレンダリングしたい場合のための仕組みです。ルートに export const prerender = false を付けると、zfb が dist/_worker.js を生成し、リクエストをページハンドラへ振り分けて Cloudflare のバインディングを渡してくれます。生成される Worker の中身については Worker 上の SSR を、実際のセットアップ手順については SSR と Cloudflare バインディング を参照してください。

このサイトはそれをまったく必要としません。どのページも静的 HTML のままで十分です。必要なのは、リクエストがどのページにも届く 前 の判断 — 画像でも CSS でも 404 でも、あらゆるパスに対して一律に効く検査です。それはページのレンダリングではなくエッジのミドルウェアであり、背後のファイルを zfb が作ったかどうかを知る必要がありません。

そのため wrangler.toml は、生成されたバンドルではなく手書きのソースを main に指しています。

name = "zfb-example-password-gate"
# The Worker source lives OUTSIDE the assets directory — this is a hand-written
# gate, not an adapter bundle, so `main` is the TS entry, not `dist/_worker.js`.
main = "src/index.ts"
compatibility_date = "2026-05-01"
compatibility_flags = ["nodejs_compat"]

このサンプルが示す判断基準はこうです。ページの HTML がリクエストに依存するならアダプタ、リクエストがそもそもページに届く必要がないなら手書きの Worker。 認証ゲート、リダイレクト、ヘッダーの書き換え、地域別ルーティングはいずれも手書き側に入ります。もちろん両者は排他ではなく、アダプタでビルドしたサイトの前段にさらに Worker のロジックを置いても構いませんが、このサンプルは使わないものを入れないことで依存関係を正直に保っています。

効いているのは run_worker_first の 1 行

[assets]
directory = "./dist"
binding = "ASSETS"
# MANDATORY — do not set to false. With the default `false` the asset layer
# answers GET/HEAD before the Worker runs, so any path resolving to a static
# file is served without ever reaching the password gate: a silent bypass that
# still looks protected. `true` forces the Worker first; it serves assets itself
# via env.ASSETS.fetch() once the request is authorized.
# scripts/smoke.mjs asserts a real static asset path is gated, which is what
# catches a regression of this line.
run_worker_first = true

Workers Static Assets では通常、実ファイルに対応するパスへの GET/HEAD は Worker のコードが動く前に アセット層が応答します。静的サイトを速くするためのデフォルトですが、ここではまさに逆効果です。dist/ 内のファイルに解決されるパスはすべて、ゲートを通らずに配信されてしまいます。

しかも壊れ方が静かです。エラーも出ずログも残らず、ただサイトが非公開でなくなるだけです。run_worker_first = true を設定すると順序が反転し、Worker が先に走り、リクエストを認可したあとに env.ASSETS.fetch(request) で自らアセットを返します。

リポジトリのスモークテストがサイトのトップページを叩くだけで終わらないのもこのためです。実行時に dist/ から実在のアセットパスを読み取り、そちら もゲートされていることをアサートします。こうしておけば、アセット層がディレクトリをどう解決するかに左右されるパスではなく、デプロイに実在するファイルにアサーションを固定できます。

ゲート本体

リクエスト処理の全体は 1 つの fetch ハンドラに収まっています。

export default {
  async fetch(request: Request, env: RuntimeEnv): Promise<Response> {
    const url = new URL(request.url);

    if (await hasValidMarker(request, env, url)) {
      return withPrivateCaching(await env.ASSETS.fetch(request));
    }

    if (url.pathname === AUTH_PATH && request.method === "POST") {
      return handleAuth(request, env);
    }

    return loginResponse(sanitizeNext(url.pathname + url.search));
  },
} satisfies ExportedHandler<RuntimeEnv>;

分岐は 3 つ、この順番です。マーカー Cookie を持つリクエストはそのままアセット層へ委譲されます。POST /__auth はログイン試行です。それ以外は — どんなパスでもどんなメソッドでも — インラインのログインページを 401 で返し、本来向かおうとしていたパスを hidden な next フィールドに保持するので、ログインに成功すると元の行き先に着地します。

真似する価値のある細部は次のとおりです。

• resolveExpectedPassword() は空でない SITE_PASSWORD を使い、開発用フォールバックは平文 HTTP の loopback オリジンに限ります。それ以外のオリジンで認証情報が無い場合は拒否します。timingSafeEqual() は SHA-256 ダイジェストを定数時間の XOR ループで比較します。

• ログインとエラーの応答には Cache-Control: no-store、X-Robots-Tag: noindex、Vary: Cookie が付きます。認証済みアセットの応答も private no-store と Cookie による Vary を設定するため、共有エッジキャッシュが訪問者間でゲート内の内容を再配信しません。

• hasValidMarker() は解決したパスワードから HMAC-SHA256 でマーカーを導出します。マーカーはソースに固定値として置かれておらず、パスワードを変えると既存 Cookie も無効になります。

• マーカー Cookie は HttpOnly かつ SameSite=Lax で、Secure が外れるのは localhost、127.0.0.1、[::1] への素の http: の場合 だけ です。それ以外のホストには必ず Secure が付きます。

• next はクライアントから渡されるリダイレクト先なので、使う前にサニタイズされます。

export function sanitizeNext(value: string): string {
  if (!value.startsWith("/") || value.startsWith("//")) return "/";

  for (const char of value) {
    const code = char.charCodeAt(0);
    if (char === "\\" || code < 0x20 || code === 0x7f) return "/";
  }

  return value;
}

プロトコル相対の //evil.example（オープンリダイレクト）、バックスラッシュを使ったパスの小細工、制御文字（改行を紛れ込ませたヘッダーインジェクション）は、いずれも / に潰されます。

これは何ではないか

ローカルで動かす

pnpm install
pnpm dev        # zfb dev
pnpm build      # zfb build → dist/
pnpm preview    # zfb preview
pnpm typecheck  # zfb check

リポジトリ自身の言葉での注意点はこうです。pnpm preview は zfb の静的プレビューサーバーを使うため Cloudflare Worker のゲートは動かず、Worker の確認は pnpm build のあとに Wrangler で行うこと。

これは SSR 系のサンプル以上に効いてきます。ここで一番試したくなる部分こそ、pnpm preview が飛ばす部分だからです。ゲートを動かすには、まずビルドしてから Wrangler を起動します。

pnpm build
pnpm exec wrangler dev --local

このとき curl -i http://localhost:8787/ は 401 のログインページを返し、正しいパスワードを form-encoded で POST /__auth すると 302 と Set-Cookie が返るはずです。上で触れた next のサニタイズ確認を含む手動チェックの一式は README にまとまっています。ライブサイトに対して同じアサーションを走らせる pnpm smoke（scripts/smoke.mjs）もあり、SMOKE_URL=http://localhost:8787 pnpm smoke でローカルの Wrangler に向けることもできます。

関連ドキュメント

• Worker 上の SSR — このサンプルがあえて使っていない、アダプタ生成の dist/_worker.js について。

• SSR と Cloudflare バインディング — ページを本当にリクエストごとにレンダリングしたい場合のアダプタ経路。

• 静的アセット — public/ のファイルが dist/ に届くまで。このゲートの背後にあるものです。

• スタイリング — 手書き CSS、zudo-wind のリセット、ユーティリティによるスタイリング。

• サンプル — その他の zfb example サイト一覧。