こんにちは、@key60228です。
この記事はAI Shift Advent Calendar 2025、Hono Advent Calendar 2025の7日目の記事です。
この生成AI時代、ドキュメントもAIエージェントフレンドリーにGitとMarkdownで管理したいな〜〜でもあまりMarkdownに馴染みのないビジネスメンバーも簡単に確認できるよう、Webで見れるようにしておきたいな〜〜でもPublicにはしたくないな〜〜って考えてる方、いらっしゃるんじゃないでしょうか。
かくいう自分もその一人で、先日Cloudflare PagesとZero TrustとOIDC IdPとmdBookでサクッとMarkdownドキュメントを限定公開する記事を書きましたが、いくつかの課題が残ったままになっていました。
- 現在はCloudflare PagesよりCloudflare Workersの利用が推奨されている[1]
- Cloudflare Zero TrustのFreeプランだと50人までしか限定公開の対象にできない[2]
- プロジェクト/ドキュメントが増える度に手作業が必要となり、トイル化している
そこで今回は改めてCloudflare WorkersとHonoで"ちゃんと"限定公開する記事を書きます！
やりたいこと (前回とほぼ同じ)
- ドキュメントをgit管理下におきたい (≒ Markdownで書きたい)
- ドキュメントをどこかにホスティングしたい
- ホスティングしたドキュメントを閲覧できる人を制限したい (閲覧する人の属性はDeveloper、ML/DS、その他ビジネスメンバーと幅広い)
- 公開対象者/範囲をスケーラブルにしたい <- new!
- ドキュメントやプロジェクトが増えても極力手作業が発生しないようにしたい <- new!
リポジトリ
いいからモノを見せんかい、って方はこちら。
How to
OIDC IdPの準備
PKCEに対応しているOIDC IdPであればGoogleでもAuth0でもKeycloakでもなんでもOKです。
前回はサイバーエージェントの社内認証/認可基盤のPERMANを使いましたが、今回は自前のZITADEL Cloudで試します。
ISSUER URLとClient IDを取得しておきます。 (詳細は省きます)
認証 & 配信サーバー / OIDC Clientの実装
今回のケースでは認証 & 静的配信サーバーとOIDC Clientを自前で実装する必要があります。
前回はCloudflare PagesとZero Trustに丸っとお任せしてましたが、今回はHonoを使って実装していきます。
今回提供するエンドポイントは以下の4つです。
- ログイン
- OIDCコールバック
- ログアウト
- 静的アセット配信
静的アセット配信エンドポイントにはmiddlewareを噛ませ、認証を通ったアクセスのみアセットに到達できるようにし、未認証のアクセスはログインエンドポイントにリダイレクトするようにします。
ログイン、OIDCコールバック処理では、OAuth2.0 PKCEの仕組みにのっとり、code_verifier/code_challengeの生成・検証を行います。
認証に成功した場合はセッション情報をCloudflare KVに格納、ユーザーにはCookieを付与するようにしています。
こうしたmiddlewareやcookieをsimpleに実現できるのもHonoの良いところですね。
配信エンドポイントではCloudflare WorkersのStatic Assetsという機能を使ってドキュメントを配信します。
npm create cloudflare@latest で作成した際の初期パスである ./public をバインディングしています。
ドキュメントの準備
前回同様、mdBookプロジェクトを作成し、ドキュメントを更新し、ビルドします。
デフォルトではビルドアセットは book に出力されますが、Static Assetsでバインディングしているパスに変更するようにしてください。
タイトルに盛り込んでこそしまいましたが、最終的にhtmlとなればDocusaurusでもMkDocsでもなんでもOKだと思います。
CI/CDの整備
GitHub ActionsでCI/CDも構築しました。
とはいえあまり大したことはしておらず、CIではmdBookのbuild、Honoのformat/type checkを、CDではmdBookのbuildとwrangler deployを行うようにしています。
もしこのリポジトリをforkする場合はGitHub Actionsのsecretに CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID を設定することをお忘れなきよう…
Secretの設定
Cloudflare Workersに対してSecretで ISSUER と CLIENT_ID を設定しましょう。
コンソールからでもwrangler CLIからでもOKです。
動作確認
以上でプロジェクトのセットアップは完了です。
該当のドメインにアクセスすると、IdPのログイン画面にリダイレクトされ、ログインに成功した場合は正しくドキュメントを参照できるかと思います。
まとめ
元々Notionで管理していたドキュメントをMarkdown&Gitで管理したい！というモチベーションからスタートしたプロジェクトで、前回の内容でも必要十分ではありましたが、スケーラビリティとトイル削減のため今回改めて取り組むことにしました。
PRDなどをこのリポジトリで管理し、プロダクトリポジトリにsubmoduleとして取り込むことで、コーディングエージェントを使った開発を加速させることができるのでは？と画策しています。
リポジトリは汎用性を意識して実装したので、もし同じような悩みを抱えている方がいらっしゃったらscaffold的に使ってもらえたら嬉しいです！
宣伝
AI Shiftではエンジニアの採用に力を入れています！
少しでも興味を持っていただけましたら、カジュアル面談でお話しませんか？
（オンライン・19時以降の面談も可能です！）
【面談フォームはこちら】
Discussion