cloudflare-maintenance-worker 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Second Fiddle Co., Ltd.
+
+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.ja.md

@@ -0,0 +1,238 @@
+# cloudflare-maintenance-worker
+
+[English](README.md)
+
+重い migration や DB 作業のあいだ、利用者からのアクセスに `503` とメンテナンスページを返す Cloudflare Worker と、メンテナンスの開始と終了を切り替えるスクリプトです。
+
+Worker は普段リクエストを受けません。対象ホストの Workers Route をこの Worker に付けるとメンテナンスに入り、外すと抜けます。付け外しは `maintenance-worker on` と `off` が Cloudflare API で行います。`wrangler.jsonc` にルートを書かないのは、書くと `wrangler deploy` のたびにルートが付き、デプロイしただけでサイトが止まるためです。デプロイとメンテナンスの開始は、意図して別の操作にしています。
+
+## 振る舞い
+
+- 通常のリクエストには、メンテナンスページを `503` で返します。`Retry-After`（既定は 3600 秒）と `Cache-Control: no-store` を付け、Cloudflare にもブラウザにもページを残させません。
+- API クライアントへの JSON のエラーや、Inertia.js の画面遷移への `409` のように、リクエストによって応答を変えたいときは、関数を差し込めます。「[独自の応答](#独自の応答)」を読んでください。
+- 作業者は、合言葉か許可 IP で通れます。任意の URL に `?maintenance_bypass=<合言葉>` を付けて開くと、パラメーターを外した同じ URL へリダイレクトし、12 時間有効の Cookie を発行します。リダイレクトするのは、合言葉がアドレスバーに残らないようにするためです。
+
+パラメーター名の `maintenance_bypass` は秘密ではありません。名前を知られても、合言葉が無ければ誰も通れません。合言葉は定数時間で比べ、Cookie には合言葉から導いたハッシュだけを入れ、合言葉そのものは入れません。Cookie の値は合言葉から導いていて、サーバー側に有効期限の一覧を持たないので、合言葉を変えればそれまでに発行した Cookie はすべて無効になります。合言葉が未設定なら、合言葉でも Cookie でも誰も通しません（fail-closed）。
+
+同じルートのパターンを別の Worker がすでに持っていると、`on` は何も変更せずに止まります。対象ホストに別の Worker のもっと狭いルート（たとえば `app.example.com/api/*`）があると、そのパスはメンテナンス中も止まらないので、`on` と `status` が警告を出します。
+
+呼び出しログは `wrangler.jsonc` で切っています。リクエスト URL を残すので、作業者が合言葉を使うと平文で入ってしまうためです。有効に戻さないでください。
+
+## セットアップ
+
+おすすめの持ち方は、自分のリポジトリには設定だけを置き、コードは依存として取り込む形です。Node 22 以降と pnpm が要ります。npm でも動きますが、npm は `--dry-run` などのオプションを自分で受け取ってしまうので、environment 名の前に `--` を入れます（`npm run deploy -- develop --dry-run`）。
+
+ディレクトリを作り、次の 4 つのファイルを置きます。
+
+`package.json`:
+
+```json
+{
+  "name": "my-maintenance",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev --env develop",
+    "deploy": "maintenance-worker deploy",
+    "on": "maintenance-worker on",
+    "off": "maintenance-worker off",
+    "status": "maintenance-worker status"
+  },
+  "devDependencies": {
+    "cloudflare-maintenance-worker": "github:second-fiddle-jp/cloudflare-maintenance-worker#v0.2.0",
+    "wrangler": "4.123.0"
+  }
+}
+```
+
+`src/index.js` は Worker を再エクスポートするだけです（一部のリクエストに独自の応答を返すときは「[独自の応答](#独自の応答)」）。
+
+```js
+export { default } from 'cloudflare-maintenance-worker'
+```
+
+`wrangler.jsonc` と `maintenance.config.json` は、このリポジトリの直下にあるサンプルをコピーし、名前とホストを書き換えます。中身は「[設定](#設定)」で説明します。
+
+インストールして、wrangler にログインします。
+
+```bash
+pnpm install
+pnpm exec wrangler login
+```
+
+wrangler は自分の `devDependencies` でバージョンを固定してください。スクリプトはインストールされた wrangler を使います。
+
+このリポジトリを clone して、サンプルをそのまま書き換えて使うこともできます。clone した側の `package.json` にも同じスクリプトがあるので、以下のコマンドはどちらでも同じです。
+
+## 設定
+
+サイト固有の値は、`wrangler.jsonc` の vars と `maintenance.config.json` の 2 か所に置きます。コードにはサイト固有の値がありません。
+
+### Worker の vars と secret
+
+vars は `wrangler.jsonc` の `env.<environment>.vars` に書きます。wrangler は top-level の `vars` を environment に継承しないので、同じ値でも environment ごとに全部書きます。値は文字列で書きます。数値や真偽値で書いても文字列として扱うので、`"RETRY_AFTER": 120` も `"120"` と同じく有効です。
+
+| 名前 | 意味 | 未設定のとき |
+|---|---|---|
+| `RETRY_AFTER` | `Retry-After` に入れる秒数 | `3600` |
+| `BYPASS_COOKIE` | バイパス Cookie の名前。Cookie の Domain を共有する environment どうしでは別の名前にする | `maintenance_bypass` |
+| `COOKIE_DOMAIN` | バイパス Cookie の `Domain`。`.example.com` のように書くと、1 つの Cookie がサブドメインをまたいで効く | `Domain` を付けず、合言葉を開いたホストだけで効く |
+| `BRAND` | ページに出すブランド名。タイトルの末尾にも ` \| <BRAND>` として付く | ブランドを出さない |
+| `PAGE_LANG` | ページの `lang` 属性 | `en` |
+| `PAGE_TITLE` | ページのタイトル | `Under maintenance` |
+| `PAGE_HEADING` | ページの見出し | `We are currently down for maintenance` |
+| `PAGE_MESSAGE` | 見出しの下の本文。改行は `<br>` になる | お詫びと、時間をおいてアクセスし直すよう促す 2 行の英文 |
+| `BYPASS_SECRET`（secret） | 合言葉 | 合言葉でも Cookie でも通さない |
+| `ALLOW_IPS`（secret） | メンテナンス中も通す IP（カンマ区切り） | IP では通さない |
+
+既定の文言は英語です。日本語のページにするなら、`PAGE_LANG` を `ja` にし、`PAGE_TITLE`・`PAGE_HEADING`・`PAGE_MESSAGE` を environment ごとに書いてください。ページに差し込む値は HTML エスケープするので、vars に `<` を書いてもタグにはなりません。文言より大きく見た目を変えたいときは、clone して `src/page.js` の HTML と CSS を編集します。HTML を別ファイルにしていないのは、`.html` を Worker のモジュールとして読み込むと `node --test` から import できなくなるためです。
+
+### 独自の応答
+
+メンテナンス中の応答をリクエストによって変えたいときは、`src/index.js` で `createWorker` に関数を渡します。関数は `(request, env, { headers })` を受け取ります。`Response` を返すとそれが応答になり、`undefined` を返すと次の関数へ、最後はメンテナンスページへ進みます。関数は配列の順に呼びます。`headers` には、メンテナンスページと同じ `Cache-Control` と `Retry-After` が入っています。Cookie や許可 IP で通る作業者のリクエストは、関数に届きません。
+
+次の例は、Inertia.js の画面遷移にページ全体を読み込み直させるものと、API のホストに JSON-RPC のエラーを返すものです。
+
+```js
+import { createWorker } from 'cloudflare-maintenance-worker'
+
+// Inertia の XHR に 503 の HTML を返すとモーダルの中にページが出るので、409 でページ全体を読み込み直させる
+const inertia = (request) =>
+  request.headers.has('X-Inertia')
+    ? new Response(null, { status: 409, headers: { 'X-Inertia-Location': request.url, 'Cache-Control': 'no-store' } })
+    : undefined
+
+// ページを読めない API クライアントには、JSON-RPC のエラーを返す
+const jsonRpc = (request, env, { headers }) =>
+  new URL(request.url).hostname === 'api.example.com'
+    ? Response.json({ jsonrpc: '2.0', error: { code: -32000, message: 'Service under maintenance' }, id: null }, { status: 503, headers })
+    : undefined
+
+export default createWorker({ respond: [inertia, jsonRpc] })
+```
+
+### maintenance.config.json
+
+ルートを付け外しするスクリプトが読む設定で、ゾーンと、environment ごとに付けるルートのパターンを書きます。
+
+```json
+{
+  "zone": "example.com",
+  "environments": {
+    "develop": { "patterns": ["dev.example.com/*"] },
+    "production": { "patterns": ["example.com/*", "www.example.com/*"] }
+  }
+}
+```
+
+パターンは上から順に付けます。`*.example.com/*` のようなワイルドカードにせず、ホストごとに書いてください。ワイルドカードにすると、公開ストレージのバケットのように止めるつもりの無いホストまで止まります。
+
+environment の名前は、`wrangler.jsonc` の `env` と同じ組にそろえます。各 environment の Worker 名は `wrangler.jsonc` の `name` に environment 名を付けた `<name>-<env>`（env で `name` を上書きしていればその名前）で、スクリプトも同じ規則で導きます。`maintenance.config.json` にだけある environment や、`patterns` が無い environment は、その environment を操作しようとしたときだけ理由を示して止まります。`wrangler.jsonc` にだけある environment は警告を出すだけです。メンテナンスの最中に無関係な environment の設定を誤っても、`off` と `status` を使えるようにするためです。
+
+スクリプトは `wrangler.jsonc` を wrangler を使わずに読みます。行コメント、ブロックコメント、末尾カンマのどれも書けます。
+
+## デプロイと secret の登録
+
+Worker のデプロイは、`deploy` スクリプトに environment 名を付けて行います。素の `wrangler deploy` は top-level の `name` で vars を持たない Worker を作ってしまうので、`deploy` は environment 名が無いときや空のときは止まります。`pnpm deploy` は pnpm の組み込みコマンドなので、必ず `pnpm run deploy` と書きます。`--dry-run` など `wrangler deploy` のオプションは、environment 名のあとに続けます（`pnpm run deploy develop --dry-run`。npm なら `npm run deploy -- develop --dry-run`）。
+
+```bash
+pnpm run deploy develop
+pnpm run deploy production
+```
+
+デプロイしてもルートは付かないので、サイトは通常どおり動き続けます。
+
+合言葉と許可 IP は、最初のデプロイのあとに Worker の secret として登録します。Worker が無い状態だと、`wrangler secret put` は Worker を作ってよいかを対話で尋ねてきます。
+
+```bash
+pnpm exec wrangler secret put BYPASS_SECRET --env production
+pnpm exec wrangler secret put ALLOW_IPS --env production
+```
+
+合言葉は environment ごとに別の値にし、`openssl rand -hex 32` で作ります。16 進数だけなので URL エンコードが要りません。メンテナンスのたびに合言葉を変えてください。前回配った Cookie は、そうすることで無効になります。
+
+## ルートを付け外しする API トークン
+
+ルートの付け外しは Cloudflare API を直接呼ぶので、専用の API トークンを作ります。権限は Zone → Workers Routes: Edit と Zone → Zone: Read の 2 つで、対象は自分のゾーンだけにします。トークンは `CLOUDFLARE_API_TOKEN` 環境変数で渡します。コマンドラインに直接書くとシェルの履歴に残るので、次のように読み込みます。
+
+```bash
+read -s CLOUDFLARE_API_TOKEN && export CLOUDFLARE_API_TOKEN
+```
+
+wrangler も `CLOUDFLARE_API_TOKEN` があればそれを使い、`wrangler login` のログインより優先します。このトークンには Account の権限が無いので、export したまま `deploy` や `wrangler secret put` を実行すると「Failed to automatically retrieve account IDs」で止まります。wrangler のコマンドは、環境変数を外して実行してください。
+
+```bash
+env -u CLOUDFLARE_API_TOKEN pnpm run deploy production
+```
+
+## メンテナンスに入る・抜ける
+
+まず、その environment に Worker がデプロイ済みであること、今回の合言葉に差し替えたこと、いまが通常稼働であることを確かめます。`status` が「メンテナンスのルートは無い」と返せば通常稼働です。
+
+```bash
+pnpm run status production
+```
+
+メンテナンスに入ります。ここから利用者には `503` が返ります。
+
+```bash
+pnpm run on production
+```
+
+別の Worker が同じパターンを持っていれば、`on` は何も変更せずに止まります。途中で失敗したときは、ルートを数え直して、1 本も付いていないのか、一部だけ付いたのか、全部付いたのかを伝えます。一部だけ付いたときは `status` で確かめ、必要なら `off` を実行してください。Worker がまだデプロイされていなければ、ルートは 1 本も付かず、先にデプロイするよう案内が出ます。
+
+作業者は `https://<ホスト>/?maintenance_bypass=<合言葉>` を開いて Cookie を受け取るか、`ALLOW_IPS` に登録した IP から作業します。IPv6 はアドレスが変わりやすいので、IPv4 で登録するか Cookie を使うほうが確実です。
+
+Worker が止めるのは外からの HTTP だけです。サーバー内のキューワーカー、cron、スケジューラーは動き続けるので、作業に応じて自分で止めてください。
+
+作業が終わったら、メンテナンスを抜けて確かめます。
+
+```bash
+pnpm run off production
+pnpm run status production
+```
+
+`status` が再び「メンテナンスのルートは無い」と返すことを確かめ、Cookie を持たないブラウザ（シークレットウィンドウなど）でも開けることを確認します。
+
+Webhook の送信元や外形監視にも、メンテナンス中は `503` が返ります。多くの送信元は再送しますが、メンテナンスが長くなるときは再送の上限を確かめておいてください。
+
+### 一部のホストだけをメンテナンスにする
+
+environment のうち一部のサイトだけを止めるときは、`on` に `--host` でホストを渡します。`maintenance.config.json` のパターンのうち、そのホストのものだけが付きます。ホストはパターンの最初の `/` より前と、大文字と小文字も区別して完全一致で比べるので、`--host example.com` で `app.example.com` は選ばれません。`*.example.com/*` のようなワイルドカードのパターンは、同じ文字列をシェルでクォートして渡します（`--host '*.example.com'`）。複数のホストは `--host` を繰り返して渡し、あとから別のホストを `on --host` で足すこともできます。
+
+```bash
+pnpm run on production --host app.example.com
+pnpm run status production
+```
+
+`status` は、たとえば `In maintenance: 1 / 3 routes` と出し、付いているルートを並べます。`off` は `--host` を受け付けず、いつも Worker のルートを全部外すので、一部だけのメンテナンスも `off production` 一つで抜けられます。environment のパターンに無いホストを渡すと、`on` は何も変えずに止まります。
+
+一部のホストだけを止めてよいのは、作業がそのサイトに閉じているときだけです。サイトどうしが DB を共有していれば、止めていないサイトは作業中も DB を使い続けます。
+
+## ローカルで確かめる
+
+`wrangler.jsonc` と同じディレクトリの `.dev.vars` に secret を書き、Worker を起動します。
+
+```
+BYPASS_SECRET=<合言葉>
+ALLOW_IPS=<許可する IP>
+```
+
+```bash
+pnpm run dev
+curl -i http://localhost:8787/
+```
+
+`dev` は `develop` environment の vars で動きます。独自の応答を確かめるときは、`-H 'X-Inertia: true'` や `Host` ヘッダーを付けるなど、その条件に合うリクエストを送ります。
+
+## テスト
+
+```bash
+node --test
+```
+
+テストは Node の標準 API だけを使うので、インストールは要りません。
+
+## ライセンス
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# cloudflare-maintenance-worker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[日本語](README.ja.md)
+
+A Cloudflare Worker that answers with `503` and a maintenance page while you run heavy migrations or other database work, plus the scripts that switch maintenance on and off.
+
+The Worker normally receives no traffic at all. Maintenance starts when Workers Routes for your hosts are attached to it, and ends when they are detached. The `maintenance-worker on` and `off` commands do this through the Cloudflare API. Routes are deliberately left out of `wrangler.jsonc`: if they were there, every `wrangler deploy` would attach them and a deploy alone would take the site down. Deploying the Worker and entering maintenance are separate actions on purpose.
+
+## What it does
+
+- It answers ordinary requests with the maintenance page as `503`, with `Retry-After` (3600 seconds by default) and `Cache-Control: no-store`, so neither Cloudflare nor browsers keep the page.
+- When some requests need a different answer, such as a JSON error for API clients or a `409` for Inertia.js visits, you can plug in functions that give it. See [Custom responses](#custom-responses).
+- Operators get through with a passphrase or from an allowed IP. Opening any URL with `?maintenance_bypass=<passphrase>` redirects to the same URL without the parameter and sets a cookie that is valid for 12 hours. The redirect keeps the passphrase from staying in the address bar.
+
+The name of the parameter, `maintenance_bypass`, is not a secret. Anyone may know it and it lets nobody in without the passphrase. The passphrase is compared in constant time, and the cookie holds a hash derived from it, never the passphrase itself. Because the cookie value is derived from the passphrase and the server keeps no expiry list, changing the passphrase invalidates every cookie issued so far. If no passphrase is set, nobody gets through by passphrase or cookie: the Worker fails closed.
+
+`on` refuses to start if another Worker already holds one of the same route patterns, and changes nothing. If another Worker holds a narrower route on one of your hosts (for example `app.example.com/api/*`), those paths keep serving during maintenance, so `on` and `status` print a warning about them.
+
+Invocation logs are turned off in `wrangler.jsonc` because they record the request URL, which contains the passphrase in plain text when an operator uses it. Do not turn them back on.
+
+## Setting up
+
+The recommended setup keeps only your configuration in your repository and installs the code as a dependency. You need Node 22 or later and pnpm. npm works too, but it takes options such as `--dry-run` for itself, so put `--` before the environment name: `npm run deploy -- develop --dry-run`.
+
+Create a directory with these four files.
+
+`package.json`:
+
+```json
+{
+  "name": "my-maintenance",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev --env develop",
+    "deploy": "maintenance-worker deploy",
+    "on": "maintenance-worker on",
+    "off": "maintenance-worker off",
+    "status": "maintenance-worker status"
+  },
+  "devDependencies": {
+    "cloudflare-maintenance-worker": "github:second-fiddle-jp/cloudflare-maintenance-worker#v0.2.0",
+    "wrangler": "4.123.0"
+  }
+}
+```
+
+`src/index.js`, which only re-exports the Worker (to answer some requests your own way, see [Custom responses](#custom-responses)):
+
+```js
+export { default } from 'cloudflare-maintenance-worker'
+```
+
+`wrangler.jsonc` and `maintenance.config.json`: copy the samples at the root of this repository and replace the names and hosts. They are described under [Configuration](#configuration).
+
+Then install and log in to wrangler:
+
+```bash
+pnpm install
+pnpm exec wrangler login
+```
+
+Pin wrangler to an exact version in your own `devDependencies`. The scripts run the wrangler you installed.
+
+You can also clone this repository and edit the samples in place. All commands below work the same in the clone, because its own `package.json` defines the same scripts.
+
+## Configuration
+
+Values that belong to your site live in two files: the vars in `wrangler.jsonc` and `maintenance.config.json`. The code has no site-specific values.
+
+### Worker vars and secrets
+
+Write vars under `env.<environment>.vars` in `wrangler.jsonc`. wrangler does not inherit top-level `vars` into environments, so write every var in every environment even when the value is the same. Write values as strings; numbers and booleans are converted to strings, so `"RETRY_AFTER": 120` works the same as `"120"`.
+
+| Name | Meaning | When unset |
+|---|---|---|
+| `RETRY_AFTER` | Seconds to put in `Retry-After` | `3600` |
+| `BYPASS_COOKIE` | Name of the bypass cookie. Environments that share a cookie domain need different names | `maintenance_bypass` |
+| `COOKIE_DOMAIN` | `Domain` of the bypass cookie, such as `.example.com`, so one cookie works across subdomains | No `Domain`: the cookie works only on the host where the passphrase was used |
+| `BRAND` | Brand name shown on the page and appended to the title as ` \| <BRAND>` | No brand is shown |
+| `PAGE_LANG` | The page's `lang` attribute | `en` |
+| `PAGE_TITLE` | The page title | `Under maintenance` |
+| `PAGE_HEADING` | The page heading | `We are currently down for maintenance` |
+| `PAGE_MESSAGE` | The text under the heading. Newlines become `<br>` | A two-line apology asking visitors to try again later |
+| `BYPASS_SECRET` (secret) | The passphrase | No passphrase or cookie gets through |
+| `ALLOW_IPS` (secret) | IPs let through during maintenance (comma-separated) | No IP is let through |
+
+Values inserted into the page are HTML-escaped, so a `<` in a var never becomes a tag. To change more than the text, edit the HTML and CSS in `src/page.js` (in a clone) or render your own page. The HTML is not a separate file because importing `.html` as a Worker module would break `node --test`.
+
+### Custom responses
+
+To answer some requests differently during maintenance, pass functions to `createWorker` in `src/index.js`. Each function receives `(request, env, { headers })`. If it returns a `Response`, that is the answer; if it returns `undefined`, the request goes on to the next function and finally to the maintenance page. The functions are called in order. `headers` holds the `Cache-Control` and `Retry-After` the maintenance page uses. Requests from operators, who get through with the cookie or an allowed IP, never reach the functions.
+
+The example below makes Inertia.js visits reload the whole page, and gives a JSON-RPC error to an API host.
+
+```js
+import { createWorker } from 'cloudflare-maintenance-worker'
+
+// A 503 HTML page returned to an Inertia XHR shows up inside a modal, so make the client reload the whole page with 409
+const inertia = (request) =>
+  request.headers.has('X-Inertia')
+    ? new Response(null, { status: 409, headers: { 'X-Inertia-Location': request.url, 'Cache-Control': 'no-store' } })
+    : undefined
+
+// API clients cannot read a page, so give them a JSON-RPC error
+const jsonRpc = (request, env, { headers }) =>
+  new URL(request.url).hostname === 'api.example.com'
+    ? Response.json({ jsonrpc: '2.0', error: { code: -32000, message: 'Service under maintenance' }, id: null }, { status: 503, headers })
+    : undefined
+
+export default createWorker({ respond: [inertia, jsonRpc] })
+```
+
+### maintenance.config.json
+
+This file tells the route scripts which zone to use and which route patterns to attach for each environment.
+
+```json
+{
+  "zone": "example.com",
+  "environments": {
+    "develop": { "patterns": ["dev.example.com/*"] },
+    "production": { "patterns": ["example.com/*", "www.example.com/*"] }
+  }
+}
+```
+
+Patterns are attached in order. List each host explicitly rather than using a wildcard such as `*.example.com/*`, which would also stop hosts you did not mean to stop, such as a public storage bucket.
+
+Keep the environment names the same as the `env` keys in `wrangler.jsonc`. The Worker name for each environment is `<name>-<env>` from `wrangler.jsonc` (or the `name` an env overrides), and the scripts derive it the same way. An environment that exists only in `maintenance.config.json`, or has no patterns, stops the scripts with a reason, but only when you operate on that environment. An environment that exists only in `wrangler.jsonc` produces a warning and nothing else. This way a mistake in an unrelated environment never blocks `off` or `status` in the middle of maintenance.
+
+The scripts read `wrangler.jsonc` without wrangler. Line comments, block comments and trailing commas are all accepted.
+
+## Deploying and registering secrets
+
+Deploy with the `deploy` script and an environment name. Plain `wrangler deploy` would create a Worker named after the top-level `name` with no vars, so `deploy` refuses to run without an environment name, or with an empty one. `pnpm deploy` is a built-in pnpm command, so always write `pnpm run deploy`. Options for `wrangler deploy`, such as `--dry-run`, go after the environment name (`pnpm run deploy develop --dry-run`; with npm, `npm run deploy -- develop --dry-run`).
+
+```bash
+pnpm run deploy develop
+pnpm run deploy production
+```
+
+Deploying attaches no routes, so the site keeps serving normally.
+
+Register the passphrase and the allowed IPs as Worker secrets after the first deploy. If the Worker does not exist yet, `wrangler secret put` asks interactively whether to create it.
+
+```bash
+pnpm exec wrangler secret put BYPASS_SECRET --env production
+pnpm exec wrangler secret put ALLOW_IPS --env production
+```
+
+Use a different passphrase for each environment, generated with `openssl rand -hex 32`. Hex characters need no URL encoding. Change the passphrase before every maintenance window; that is what invalidates the cookies handed out last time.
+
+## The API token for routes
+
+Attaching and detaching routes calls the Cloudflare API directly, so create a dedicated API token with two permissions, Zone → Workers Routes: Edit and Zone → Zone: Read, limited to your zone. Pass it in the `CLOUDFLARE_API_TOKEN` environment variable. To keep it out of your shell history, read it instead of typing it on the command line:
+
+```bash
+read -s CLOUDFLARE_API_TOKEN && export CLOUDFLARE_API_TOKEN
+```
+
+wrangler also uses `CLOUDFLARE_API_TOKEN` when it is set, ahead of your `wrangler login` session. This token has no account permissions, so with it exported, `deploy` and `wrangler secret put` stop with "Failed to automatically retrieve account IDs". Run wrangler commands without the variable:
+
+```bash
+env -u CLOUDFLARE_API_TOKEN pnpm run deploy production
+```
+
+## Entering and leaving maintenance
+
+First check that the Worker is deployed in that environment, that the passphrase has been changed for this window, and that the site is currently serving normally. `status` should report that there are no maintenance routes.
+
+```bash
+pnpm run status production
+```
+
+Enter maintenance. From here on, visitors get `503`.
+
+```bash
+pnpm run on production
+```
+
+If another Worker holds the same pattern, `on` stops without changing anything. If it fails part way, it counts the routes again and tells you whether none, some or all of them were attached. When only some are attached, check with `status` and run `off` if needed. If the Worker has not been deployed yet, no route is attached and `on` tells you to deploy first.
+
+Operators then open `https://<host>/?maintenance_bypass=<passphrase>` to get the cookie, or work from an IP listed in `ALLOW_IPS`. IPv6 addresses change often, so register IPv4 addresses or use the cookie.
+
+Remember that the Worker only stops HTTP traffic from outside. Queue workers, cron jobs and schedulers on your servers keep running, so stop them yourself if your work needs it.
+
+When the work is done, leave maintenance and confirm:
+
+```bash
+pnpm run off production
+pnpm run status production
+```
+
+`status` should again report no maintenance routes. Open the site in a browser without the cookie, such as a private window, to confirm it serves normally.
+
+Webhook senders and uptime monitors also receive `503` during maintenance. Most webhook senders retry, but check their retry limits if the window is long.
+
+### Putting only some hosts into maintenance
+
+To stop only some sites of an environment, give their hosts to `on` with `--host`. Only the patterns of those hosts in `maintenance.config.json` are attached. The host is compared with the part of each pattern before the first `/`, exactly and case-sensitively, so `--host example.com` does not select `app.example.com`. For a wildcard pattern such as `*.example.com/*`, pass the same text and quote it in the shell (`--host '*.example.com'`). Repeat `--host` for several hosts, and run `on --host` again later to add another host.
+
+```bash
+pnpm run on production --host app.example.com
+pnpm run status production
+```
+
+`status` then reports, for example, `In maintenance: 1 / 3 routes` and lists the attached routes. `off` takes no `--host` and always detaches every route of the Worker, so a single `off production` ends a partial maintenance too. A host that is not in the patterns of the environment stops `on` before anything is changed.
+
+Stopping only some hosts is safe only for work that is confined to those sites. If the sites share a database, the sites left running keep using it during the work.
+
+## Trying it locally
+
+Put the secrets in `.dev.vars` next to `wrangler.jsonc` and start the Worker:
+
+```
+BYPASS_SECRET=<passphrase>
+ALLOW_IPS=<allowed IP>
+```
+
+```bash
+pnpm run dev
+curl -i http://localhost:8787/
+```
+
+`dev` runs with the vars of the `develop` environment. To check a custom response, send a request that matches its condition, for example with `-H 'X-Inertia: true'` or a `Host` header.
+
+## Tests
+
+```bash
+node --test
+```
+
+The tests use Node's standard API only and need no install.
+
+## License
+
+[MIT](LICENSE)

package/bin/maintenance-worker.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// maintenance-worker <deploy|on|off|status> <env> [...]
+// Run it in the project directory that holds wrangler.jsonc and maintenance.config.json
+// (pnpm run sets the current directory to the package that defines the script).
+
+import { deploy } from '../scripts/deploy.mjs'
+import { routes } from '../scripts/routes.mjs'
+
+const USAGE = 'usage: maintenance-worker deploy <env> [wrangler deploy options]\n       maintenance-worker <on|off|status> <env> [--host <host> ...]'
+
+// pnpm run on -- <env> passes the -- through, so it may come before the command name too
+const argv = process.argv.slice(2)
+const [command, ...rest] = argv[0] === '--' ? argv.slice(1) : argv
+
+// Set exitCode instead of calling process.exit, so output piped to another command is flushed before the process ends.
+if (command === 'deploy') {
+  process.exitCode = deploy(rest)
+} else if (['on', 'off', 'status'].includes(command)) {
+  process.exitCode = await routes([command, ...rest])
+} else {
+  console.error(USAGE)
+  process.exitCode = 1
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "cloudflare-maintenance-worker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A Cloudflare Worker that serves a maintenance page, switched on and off by attaching and detaching its routes",
+  "license": "MIT",
+  "repository": "github:second-fiddle-jp/cloudflare-maintenance-worker",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "maintenance-worker": "bin/maintenance-worker.mjs"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "src"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "dev": "wrangler dev --env develop",
+    "deploy": "node bin/maintenance-worker.mjs deploy",
+    "on": "node bin/maintenance-worker.mjs on",
+    "off": "node bin/maintenance-worker.mjs off",
+    "status": "node bin/maintenance-worker.mjs status"
+  },
+  "peerDependencies": {
+    "wrangler": ">=4"
+  },
+  "devDependencies": {
+    "wrangler": "4.123.0"
+  }
+}

package/scripts/apply-on.mjs

@@ -0,0 +1,52 @@
+// Attaches routes one by one for on, and decides what to tell the operator on failure. Does not talk to Cloudflare (the caller passes post).
+
+// The Cloudflare API error code returned when attaching a route to a Worker that does not exist.
+export const WORKER_NOT_FOUND = 10019
+
+/** The Cloudflare API returned a failure. errors is the API's errors array (empty when the body was not JSON). */
+export class ApiError extends Error {
+  constructor(message, errors = []) {
+    super(message)
+    this.name = 'ApiError'
+    this.errors = errors
+  }
+}
+
+/** Posts each pattern in order. Stops at the first failure and returns the patterns attached so far and the error. */
+export const applyOn = async ({ create, post }) => {
+  const created = []
+  for (const pattern of create) {
+    try {
+      await post(pattern)
+    } catch (error) {
+      return { created, error }
+    }
+    created.push(pattern)
+  }
+  return { created, error: undefined }
+}
+
+/**
+ * The guidance after on fails part way. attached is the number of this Worker's routes counted from a fresh
+ * route list after the failure, or undefined when the list could not be fetched. total is the number of target routes.
+ * Both count only the target patterns. elsewhere is the number of this Worker's other routes, attached earlier by on --host.
+ * A failed POST does not prove the route was not attached (a 502 from a proxy, for example), so the count decides.
+ */
+export const describeOnFailure = ({ envName, script, error, attached, total, elsewhere = 0 }) => {
+  if (attached === undefined) {
+    return `Some hosts may be in maintenance. Check with status ${envName} and run off ${envName} if needed`
+  }
+  if (attached >= total) {
+    return `A failure was returned, but all ${total} routes are attached. Check with status ${envName}`
+  }
+  if (attached > 0) {
+    return `Only some hosts are in maintenance. Check with status ${envName} and run off ${envName} if needed`
+  }
+  if (error instanceof ApiError && error.errors.some((e) => e.code === WORKER_NOT_FOUND)) {
+    return `Worker ${script} has not been deployed yet. No routes were attached (still serving normally). Run deploy ${envName} first, then run on ${envName} again`
+  }
+  if (elsewhere > 0) {
+    return `No routes were attached for the selected hosts. Routes attached earlier are still attached (${elsewhere}), so those hosts stay in maintenance. Check with status ${envName} and run off ${envName} if needed`
+  }
+  return 'No routes were attached (still serving normally)'
+}

package/scripts/deploy-args.mjs

@@ -0,0 +1,15 @@
+// Builds the wrangler arguments from the arguments given to deploy. Does not run wrangler.
+
+export const DEPLOY_USAGE = 'usage: deploy <env> [wrangler deploy options]'
+
+/**
+ * Passes the first argument to --env as the environment name and appends the rest as is.
+ * A leading -- is skipped (pnpm passes it through for pnpm run deploy -- <env>).
+ * Throws when the environment name is missing, empty or an option: plain wrangler deploy and --env ""
+ * would create a Worker without vars. wrangler itself checks that the name exists in wrangler.jsonc.
+ */
+export const buildDeployArgs = (argv) => {
+  const [envName, ...rest] = argv[0] === '--' ? argv.slice(1) : argv
+  if (envName === undefined || envName === '' || envName.startsWith('-')) throw new Error(DEPLOY_USAGE)
+  return ['deploy', '--env', envName, ...rest]
+}

package/scripts/deploy.mjs

@@ -0,0 +1,43 @@
+// Deploys the Worker. Requires an environment name and runs wrangler deploy.
+// Uses Node's standard API only.
+
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { buildDeployArgs } from './deploy-args.mjs'
+
+/** Finds wrangler's bin from the project's own dependencies first, then from this package's. */
+const resolveWrangler = (dir) => {
+  let manifestPath
+  for (const from of [join(dir, 'package.json'), import.meta.url]) {
+    try {
+      manifestPath = createRequire(from).resolve('wrangler/package.json')
+      break
+    } catch {}
+  }
+  if (manifestPath === undefined) throw new Error('wrangler is not installed. Add it to devDependencies')
+  const { bin } = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  return join(dirname(manifestPath), bin.wrangler)
+}
+
+/** Runs deploy and returns the exit code. dir is the project directory (where wrangler.jsonc is). */
+export const deploy = (argv, dir = process.cwd()) => {
+  let args
+  let wrangler
+  try {
+    args = buildDeployArgs(argv)
+    wrangler = resolveWrangler(dir)
+  } catch (error) {
+    console.error(error.message)
+    return 1
+  }
+
+  // Run wrangler's bin with node directly. No shell is involved, so arguments pass through unchanged on Windows too.
+  const result = spawnSync(process.execPath, [wrangler, ...args], { stdio: 'inherit', cwd: dir })
+  if (result.error) {
+    console.error(result.error.message)
+    return 1
+  }
+  return result.status ?? 1
+}

package/scripts/environments.mjs

@@ -0,0 +1,42 @@
+// The Worker name and the routes to attach during maintenance, per environment.
+// The zone and hosts live in maintenance.config.json. The Worker name is wrangler.jsonc's name plus the environment name.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { readWranglerConfig, stripBom } from './wrangler-config.mjs'
+
+const isNonEmptyString = (value) => typeof value === 'string' && value !== ''
+
+/**
+ * Builds the environments from the config and wrangler.jsonc.
+ * Mismatches and mistakes are returned per environment as problems / warnings instead of throwing,
+ * so a mistake in an unrelated environment cannot block off or status in the middle of maintenance.
+ */
+export const buildEnvironments = (config, wrangler) => {
+  if (!isNonEmptyString(config.zone)) throw new Error('zone is not set in maintenance.config.json')
+
+  const deployed = wrangler.env ?? {}
+  const environments = {}
+  const problems = {}
+  for (const [name, { patterns } = {}] of Object.entries(config.environments ?? {})) {
+    if (!(name in deployed)) {
+      problems[name] = `${name}: in maintenance.config.json but not in the env of wrangler.jsonc`
+    } else if (!Array.isArray(patterns) || patterns.length === 0 || !patterns.every(isNonEmptyString)) {
+      problems[name] = `${name}: patterns in maintenance.config.json must be an array of one or more patterns`
+    } else {
+      // When an env overrides name, wrangler deploys under that name.
+      environments[name] = { script: deployed[name].name ?? `${wrangler.name}-${name}`, patterns }
+    }
+  }
+
+  const warnings = Object.keys(deployed)
+    .filter((name) => !(name in (config.environments ?? {})))
+    .map((name) => `${name}: in the env of wrangler.jsonc but not in maintenance.config.json (its routes cannot be managed)`)
+
+  return { zone: config.zone, environments, problems, warnings }
+}
+
+/** Reads maintenance.config.json and wrangler.jsonc in dir (the project directory; defaults to the current directory). */
+export const loadEnvironments = (dir = process.cwd()) => {
+  const config = JSON.parse(stripBom(readFileSync(join(dir, 'maintenance.config.json'), 'utf8')))
+  return buildEnvironments(config, readWranglerConfig(dir))
+}

package/scripts/route-plan.mjs

@@ -0,0 +1,25 @@
+// Decides which routes on / off create and delete. Does not talk to Cloudflare.
+
+/** Creates only the patterns that do not exist yet. A pattern held by another Worker is returned in conflicts. */
+export const planOn = (existing, { script, patterns }) => {
+  const conflicts = existing.filter((route) => patterns.includes(route.pattern) && route.script !== script)
+  const taken = new Set(existing.filter((route) => patterns.includes(route.pattern)).map((route) => route.pattern))
+  return { create: patterns.filter((pattern) => !taken.has(pattern)), conflicts }
+}
+
+/** Returns only this maintenance Worker's routes. Routes of other Workers are never touched. */
+export const planOff = (existing, { script }) => existing.filter((route) => route.script === script)
+
+/** Routes of other Workers on the target hosts. Those paths keep serving during maintenance, so they are warned about. */
+export const findShadowingRoutes = (existing, { script, patterns }) => {
+  const hosts = new Set(patterns.map(hostOf))
+  return existing.filter((route) => route.script !== script && hosts.has(hostOf(route.pattern)))
+}
+
+const hostOf = (pattern) => pattern.split('/')[0]
+
+/** Keeps the patterns whose host is one of hosts, in the order of the config. Hosts that no pattern has are returned in unknown. */
+export const selectHosts = (patterns, hosts) => ({
+  patterns: patterns.filter((pattern) => hosts.includes(hostOf(pattern))),
+  unknown: hosts.filter((host) => !patterns.some((pattern) => hostOf(pattern) === host)),
+})

package/scripts/routes.mjs

@@ -0,0 +1,166 @@
+// Attaches and detaches the maintenance Worker's routes. The site is in maintenance while the routes are attached.
+// The API token comes from the CLOUDFLARE_API_TOKEN environment variable (Zone: Workers Routes Edit / Zone Read).
+// Uses Node's standard API only.
+
+import { loadEnvironments } from './environments.mjs'
+import { ApiError, applyOn, describeOnFailure } from './apply-on.mjs'
+import { findShadowingRoutes, planOff, planOn, selectHosts } from './route-plan.mjs'
+
+const API = 'https://api.cloudflare.com/client/v4'
+
+class Failure extends Error {}
+
+const fail = (message) => {
+  throw new Failure(message)
+}
+
+/**
+ * Splits the options after the environment name. Only --host <host> / --host=<host> exists, and it may be repeated.
+ * Returns the hosts, or the reason the options cannot be used.
+ */
+export const parseOptions = (options) => {
+  const hosts = []
+  for (let i = 0; i < options.length; i++) {
+    const option = options[i]
+    if (option === '--host') {
+      const host = options[++i]
+      if (host === undefined || host === '' || host.startsWith('-')) return { error: '--host needs a host, such as --host app.example.com' }
+      hosts.push(host)
+    } else if (option.startsWith('--host=')) {
+      const host = option.slice('--host='.length)
+      if (host === '') return { error: '--host needs a host, such as --host app.example.com' }
+      hosts.push(host)
+    } else {
+      return { error: option.startsWith('-') ? `Unknown option: ${option}` : `Unexpected argument: ${option}` }
+    }
+  }
+  return { hosts }
+}
+
+/**
+ * Runs on / off / status and returns the exit code.
+ * argv is [command, env, ...options]; a -- anywhere is skipped (pnpm passes it through for pnpm run on -- <env>).
+ * on --host <host> attaches only the patterns of that host; off always detaches every route of this Worker.
+ * dir is the project directory (where maintenance.config.json and wrangler.jsonc are).
+ */
+export const routes = async (argv, dir = process.cwd()) => {
+  try {
+    await run(argv, dir)
+    return 0
+  } catch (error) {
+    console.error(error.message)
+    return 1
+  }
+}
+
+const run = async (argv, dir) => {
+  const { zone: zoneName, environments, problems, warnings } = loadEnvironments(dir)
+  for (const warning of warnings) console.error(`[warn] ${warning}`)
+
+  const [command, envName, ...options] = argv.filter((arg) => arg !== '--')
+  if (problems[envName] !== undefined) fail(`${envName} cannot be operated on because of a configuration error:\n  ${problems[envName]}`)
+  const target = environments[envName]
+  const usage = `usage: <on|off|status> <${Object.keys(environments).join('|')}> [--host <host> ...]`
+  if (envName?.startsWith('-')) fail(`Options go after the environment name.\n${usage}`)
+  if (!['on', 'off', 'status'].includes(command) || target === undefined) fail(usage)
+
+  const { hosts, error: optionError } = parseOptions(options)
+  if (optionError !== undefined) fail(`${optionError}\n${usage}`)
+  if (hosts.length > 0 && command !== 'on') {
+    const offNote = command === 'off' ? ` off always detaches every route of ${target.script}.` : ''
+    fail(`--host can only be used with on, not ${command}.${offNote}\n${usage}`)
+  }
+  const selected = selectHosts(target.patterns, hosts)
+  if (selected.unknown.length > 0) {
+    const verb = selected.unknown.length === 1 ? 'is' : 'are'
+    fail(`${selected.unknown.join(', ')} ${verb} not in the patterns of ${envName} in maintenance.config.json:\n${target.patterns.map((p) => `  ${p}`).join('\n')}`)
+  }
+  // The routes on attaches: every pattern, or only those of the hosts given with --host.
+  const onTarget = hosts.length > 0 ? { ...target, patterns: selected.patterns } : target
+
+  const token = process.env.CLOUDFLARE_API_TOKEN
+  if (!token) fail('CLOUDFLARE_API_TOKEN is not set (see the README)')
+
+  const api = async (method, path, body) => {
+    const res = await fetch(`${API}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const isJson = (res.headers.get('content-type') ?? '').includes('json')
+    const json = isJson ? await res.json().catch(() => undefined) : undefined
+    if (!res.ok || json === undefined) {
+      const detail = json === undefined ? '' : ` ${JSON.stringify(json.errors)}`
+      throw new ApiError(`${method} ${path} failed: HTTP ${res.status}${detail}`, json?.errors ?? [])
+    }
+    if (!json.success) throw new ApiError(`${method} ${path} failed: ${JSON.stringify(json.errors)}`, json.errors ?? [])
+    return json.result
+  }
+
+  const zones = await api('GET', `/zones?name=${encodeURIComponent(zoneName)}`)
+  if (zones.length === 0) fail(`Zone ${zoneName} not found (check the token's Zone Read permission)`)
+  const zoneId = zones[0].id
+  const listRoutes = () => api('GET', `/zones/${zoneId}/workers/routes`)
+
+  const printStatus = async () => {
+    const all = await listRoutes()
+    const ours = planOff(all, target)
+    // While in maintenance, narrower routes matter only on the hosts that are in it. While serving normally, check every host as a preflight.
+    const watched = ours.length > 0 ? { ...target, patterns: ours.map((route) => route.pattern) } : target
+    const shadowing = findShadowingRoutes(all, watched)
+    if (shadowing.length > 0) {
+      console.log('[warn] These routes belong to other Workers and keep serving during maintenance:')
+      for (const route of shadowing) console.log(`  ${route.pattern} -> ${route.script}`)
+    }
+    if (ours.length === 0) {
+      console.log(`[${envName}] No maintenance routes (serving normally)`)
+      return
+    }
+    // Count only the patterns of the config, so routes left from an older config do not give counts like 4 / 3.
+    const configured = ours.filter((route) => target.patterns.includes(route.pattern))
+    const leftover = ours.filter((route) => !target.patterns.includes(route.pattern))
+    console.log(`[${envName}] In maintenance: ${configured.length} / ${target.patterns.length} routes`)
+    for (const route of configured) console.log(`  ${route.pattern} -> ${route.script}`)
+    if (leftover.length > 0) {
+      console.log(`[warn] Routes of this Worker that are not in maintenance.config.json (off detaches them too):`)
+      for (const route of leftover) console.log(`  ${route.pattern} -> ${route.script}`)
+    }
+  }
+
+  if (command === 'on') {
+    const existing = await listRoutes()
+    const { create, conflicts } = planOn(existing, onTarget)
+    if (conflicts.length > 0) {
+      fail(`Another Worker holds the same routes. Nothing was changed:\n${conflicts.map((r) => `  ${r.pattern} -> ${r.script}`).join('\n')}`)
+    }
+    const { error } = await applyOn({
+      create,
+      post: async (pattern) => {
+        await api('POST', `/zones/${zoneId}/workers/routes`, { pattern, script: onTarget.script })
+        console.log(`[add] ${pattern}`)
+      },
+    })
+    if (error !== undefined) {
+      // A failure response may still have attached the route, so count from a fresh list. If that fails too, treat it as unknown.
+      // With --host, count only the patterns this on tried to attach and report routes attached earlier separately.
+      // Without --host, count every route of this Worker, as before.
+      const counts = await listRoutes().then(
+        (all) => {
+          const ours = planOff(all, onTarget)
+          if (hosts.length === 0) return { attached: ours.length }
+          const attached = ours.filter((route) => onTarget.patterns.includes(route.pattern)).length
+          return { attached, elsewhere: ours.length - attached }
+        },
+        () => ({ attached: undefined }),
+      )
+      fail(`${error.message}\n${describeOnFailure({ envName, script: onTarget.script, error, total: onTarget.patterns.length, ...counts })}`)
+    }
+  } else if (command === 'off') {
+    for (const route of planOff(await listRoutes(), target)) {
+      await api('DELETE', `/zones/${zoneId}/workers/routes/${route.id}`)
+      console.log(`[remove] ${route.pattern}`)
+    }
+  }
+
+  await printStatus()
+}

package/scripts/wrangler-config.mjs

@@ -0,0 +1,63 @@
+// Reads wrangler.jsonc into plain JSON with Node's standard API only (no dependency on wrangler).
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Walks text, calling onOutside for each character outside a string; string contents are copied as is. */
+const scan = (text, onOutside) => {
+  let out = ''
+  let inString = false
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inString) {
+      out += ch
+      if (ch === '\\') out += text[++i] ?? ''
+      else if (ch === '"') inString = false
+    } else if (ch === '"') {
+      inString = true
+      out += ch
+    } else {
+      const result = onOutside(text, i)
+      out += result.text
+      i = result.next - 1
+    }
+  }
+  return out
+}
+
+/** Drops // line comments and /* *\/ block comments outside strings. */
+export const stripComments = (text) =>
+  scan(text, (s, i) => {
+    if (s[i] === '/' && s[i + 1] === '/') {
+      const end = s.indexOf('\n', i)
+      return { text: '\n', next: end === -1 ? s.length : end + 1 }
+    }
+    if (s[i] === '/' && s[i + 1] === '*') {
+      const end = s.indexOf('*/', i + 2)
+      if (end === -1) throw new Error('unterminated block comment')
+      // Keep the newlines so JSON.parse still reports useful line numbers.
+      return { text: s.slice(i, end + 2).replace(/[^\n]/g, ''), next: end + 2 }
+    }
+    return { text: s[i], next: i + 1 }
+  })
+
+/** Drops a comma that is followed only by whitespace and a closing } or ]. Run after stripComments. */
+export const stripTrailingCommas = (text) =>
+  scan(text, (s, i) => {
+    if (s[i] === ',' && /^\s*[}\]]/.test(s.slice(i + 1))) return { text: '', next: i + 1 }
+    return { text: s[i], next: i + 1 }
+  })
+
+/** Drops a leading byte order mark, which some editors on Windows write and JSON.parse rejects. */
+export const stripBom = (text) => text.replace(/^\uFEFF/, '')
+
+/** Parses the contents of wrangler.jsonc. Accepts // and /* *\/ comments and trailing commas, as wrangler does. */
+export const parseWranglerConfig = (text) => {
+  try {
+    return JSON.parse(stripTrailingCommas(stripComments(stripBom(text))))
+  } catch (error) {
+    throw new Error(`Cannot read wrangler.jsonc: ${error.message}`)
+  }
+}
+
+/** Reads wrangler.jsonc in dir (the project directory; defaults to the current directory). */
+export const readWranglerConfig = (dir = process.cwd()) => parseWranglerConfig(readFileSync(join(dir, 'wrangler.jsonc'), 'utf8'))

package/src/bypass.js

@@ -0,0 +1,77 @@
+// Decides which requests are let through to the origin during maintenance.
+// The passphrase is the Worker secret BYPASS_SECRET; allowed IPs are the secret ALLOW_IPS (comma-separated).
+// With COOKIE_DOMAIN empty the cookie is host-only and does not work across subdomains.
+
+const BYPASS_PARAM = 'maintenance_bypass'
+const COOKIE_MAX_AGE = 60 * 60 * 12
+const DEFAULT_COOKIE_NAME = 'maintenance_bypass'
+
+const digest = async (value) =>
+  new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)))
+
+const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+
+/** Hashes both sides with SHA-256 so the lengths match, then compares in constant time. */
+const safeEqual = async (a, b) => {
+  const [x, y] = await Promise.all([digest(a), digest(b)])
+  let diff = 0
+  for (let i = 0; i < x.length; i += 1) diff |= x[i] ^ y[i]
+  return diff === 0
+}
+
+const parseList = (value) =>
+  String(value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item !== '')
+
+/** The same name is used to issue and to check the cookie. Falls back to the default when BYPASS_COOKIE is empty. */
+const cookieName = (env) => String(env.BYPASS_COOKIE || DEFAULT_COOKIE_NAME)
+
+const readCookie = (header, name) => {
+  for (const part of (header ?? '').split(';')) {
+    const index = part.indexOf('=')
+    if (index === -1) continue
+    if (part.slice(0, index).trim() === name) return part.slice(index + 1).trim()
+  }
+  return null
+}
+
+/** The cookie value. It never contains the passphrase itself. */
+export const bypassCookieValue = async (secret) => toHex(await digest(`cookie:${secret}`))
+
+/** For a URL carrying the correct passphrase, returns a redirect to the URL without it, plus the cookie. Otherwise null. */
+export const bypassRedirect = async (request, env) => {
+  const secret = env.BYPASS_SECRET ?? ''
+  const url = new URL(request.url)
+  const given = url.searchParams.get(BYPASS_PARAM)
+  if (secret === '' || given === null || !(await safeEqual(given, secret))) return null
+
+  url.searchParams.delete(BYPASS_PARAM)
+  const domain = String(env.COOKIE_DOMAIN ?? '')
+  const cookie = [
+    `${cookieName(env)}=${await bypassCookieValue(secret)}`,
+    ...(domain === '' ? [] : [`Domain=${domain}`]),
+    'Path=/',
+    `Max-Age=${COOKIE_MAX_AGE}`,
+    'HttpOnly',
+    'Secure',
+    'SameSite=Lax',
+  ].join('; ')
+
+  return new Response(null, {
+    status: 302,
+    headers: { Location: url.toString(), 'Set-Cookie': cookie, 'Cache-Control': 'no-store' },
+  })
+}
+
+/** True for an allowed IP or a request carrying the issued cookie. */
+export const shouldPassThrough = async (request, env) => {
+  const ip = request.headers.get('CF-Connecting-IP')
+  if (ip !== null && parseList(env.ALLOW_IPS).includes(ip)) return true
+
+  const secret = env.BYPASS_SECRET ?? ''
+  if (secret === '') return false
+  const cookie = readCookie(request.headers.get('Cookie'), cookieName(env))
+  return cookie !== null && (await safeEqual(cookie, await bypassCookieValue(secret)))
+}

package/src/handler.js

@@ -0,0 +1,30 @@
+import { bypassRedirect, shouldPassThrough } from './bypass.js'
+import { renderMaintenancePage } from './page.js'
+
+const DEFAULT_RETRY_AFTER = '3600'
+
+/** The headers every maintenance response carries. Neither Cloudflare nor the browser may cache it. */
+const maintenanceHeaders = (env) => ({ 'Cache-Control': 'no-store', 'Retry-After': String(env.RETRY_AFTER || DEFAULT_RETRY_AFTER) })
+
+/**
+ * Answers a request: the passphrase redirect, operators to the origin, everyone else the maintenance page.
+ * respond holds functions that may answer instead of the page, such as a JSON error for API clients.
+ * Each gets (request, env, { headers }) and returns a Response, or undefined / null to leave the request to the next one.
+ * They are consulted only for requests that would get the page, never for operators.
+ */
+export const handle = async (request, env, upstream = fetch, respond = []) => {
+  const redirect = await bypassRedirect(request, env)
+  if (redirect !== null) return redirect
+
+  if (await shouldPassThrough(request, env)) return upstream(request)
+
+  for (const answer of respond) {
+    const response = await answer(request, env, { headers: maintenanceHeaders(env) })
+    if (response != null) return response
+  }
+
+  return new Response(renderMaintenancePage(env), {
+    status: 503,
+    headers: { ...maintenanceHeaders(env), 'Content-Type': 'text/html; charset=utf-8' },
+  })
+}

package/src/index.js

@@ -0,0 +1,14 @@
+import { handle } from './handler.js'
+
+/**
+ * Builds the Worker. Pass respond to answer some requests your own way during maintenance
+ * (for example a JSON error for API clients); see handle in handler.js for how the functions are called.
+ */
+export const createWorker = ({ respond = [] } = {}) => {
+  if (!Array.isArray(respond) || !respond.every((answer) => typeof answer === 'function')) {
+    throw new TypeError('respond must be an array of functions')
+  }
+  return { fetch: (request, env) => handle(request, env, undefined, respond) }
+}
+
+export default createWorker()

package/src/page.js

@@ -0,0 +1,53 @@
+// The maintenance page. CSS is inlined so the page renders even while the origin is down.
+// The text comes from vars (PAGE_LANG, BRAND, PAGE_TITLE, PAGE_HEADING, PAGE_MESSAGE). Edit this file to change the look.
+
+const DEFAULT_LANG = 'en'
+const DEFAULT_TITLE = 'Under maintenance'
+const DEFAULT_HEADING = 'We are currently down for maintenance'
+const DEFAULT_MESSAGE = 'We apologize for the inconvenience.\nPlease try again in a little while.'
+
+const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }
+
+const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => ESCAPES[char])
+
+// An empty string counts as unset, so leaving a var empty still shows the default.
+// wrangler can pass numbers and booleans as vars, so values are turned into strings first.
+const pick = (value, fallback) => (String(value ?? '') === '' ? fallback : String(value))
+
+/** Builds the maintenance page HTML from the env vars. */
+export const renderMaintenancePage = (env) => {
+  const brand = String(env.BRAND ?? '')
+  const lang = escapeHtml(pick(env.PAGE_LANG, DEFAULT_LANG))
+  const baseTitle = pick(env.PAGE_TITLE, DEFAULT_TITLE)
+  const title = escapeHtml(brand === '' ? baseTitle : `${baseTitle} | ${brand}`)
+  const brandLine = brand === '' ? '' : `  <div class="brand">${escapeHtml(brand)}</div>\n`
+  const heading = escapeHtml(pick(env.PAGE_HEADING, DEFAULT_HEADING))
+  // Escape first, then turn newlines into <br>. The other way round would escape the <br> too.
+  const message = escapeHtml(pick(env.PAGE_MESSAGE, DEFAULT_MESSAGE)).replace(/\r?\n/g, '<br>')
+
+  return `<!doctype html>
+<html lang="${lang}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+    background: #f5f5f5; color: #1f2937; padding: 24px; box-sizing: border-box;
+    font-family: -apple-system, BlinkMacSystemFont, "Hiragino Sans", "Noto Sans JP", "Yu Gothic", sans-serif; }
+  main { max-width: 560px; width: 100%; background: #fff; border: 1px solid #e5e7eb; border-radius: 12px;
+    padding: 40px 32px; text-align: center; }
+  h1 { font-size: 22px; margin: 0 0 16px; }
+  p { margin: 0; line-height: 1.8; color: #6b7280; font-size: 15px; }
+  .brand { font-weight: 700; letter-spacing: 0.04em; margin-bottom: 24px; }
+</style>
+</head>
+<body>
+<main>
+${brandLine}  <h1>${heading}</h1>
+  <p>${message}</p>
+</main>
+</body>
+</html>
+`
+}