@dytsou/shorten-url 2.4.3 → 2.4.5

package/README.md

@@ -1,231 +1,206 @@
 # URL Shortener
 
-A modern, fast URL shortener built with Cloudflare Workers and a responsive web interface. This project allows anyone to create short URLs with optional custom slugs, featuring a clean UI and robust backend with comprehensive API documentation.
+A URL shortener built with Cloudflare Workers, Cloudflare KV, and a responsive React interface. The Worker serves the product UI and redirects, while `docs/` contains the documentation and OpenAPI reference.
+
+[![Built with Cloudflare](https://workers.cloudflare.com/built-with-cloudflare.svg)](https://cloudflare.com)
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/dytsou/shorten-url)
 
 ## Features
 
-- **URL Shortening**: Convert long URLs into short, shareable links
-- **Custom Slugs**: Create personalized short URLs (optional)
-- **Protected Shortening**: Short URL creation is protected behind Cloudflare Access / WARP for safer usage
-- **Responsive Design**: Works seamlessly on desktop and mobile devices
-- **Fast Performance**: Built on Cloudflare Workers for global edge deployment
-- **Security Features**: URL validation, rate limiting, and optional Safe Browsing integration
-- **Modern Copy Function**: One-click copying with fallbacks for all browsers
-- **Custom Error Pages**: Beautiful 404, security warning, and redirect pages (fully customizable via your GitHub Pages)
-- **API Documentation**: Interactive Swagger UI with OpenAPI 3.1.0 specification
-- **Analytics Ready**: Optional click tracking and analytics integration
+- **URL Shortening**: Create short links stored in Cloudflare KV and redirect with HTTP 302
+- **Custom Slugs**: Optionally choose a slug using letters, numbers, hyphens, or underscores
+- **Cloudflare Access**: The Worker checks for Cloudflare Access JWT and email headers before creating links
+- **Responsive Design**: Worker-hosted React interface supports desktop and mobile screens
+- **Flagship Controls**: Shorten and protected Flagship views share one interface
+- **Unique Links**: Optionally reuse the same short key when the destination URL already exists
+- **URL Safety**: Validate submitted URLs and optionally check redirect destinations with Google Safe Browsing
+- **Copy Support**: Copy shortened URLs with a manual-selection fallback
+- **Hosted Error Pages**: Configure external 404, error, Safe Browsing warning, and no-referrer pages
+- **API Documentation**: Static Swagger UI with an OpenAPI 3.1 specification
+- **Worker Observability**: Structured logs and traces are supported
+
+The Worker does not implement click analytics, per-IP rate limiting, or blocked-domain lists. The similarly named settings in `config/config.js` are not used by the current Worker.
 
 ## Quick Start
 
-### Prerequisites
+### Worker-hosted React frontend
 
-- A Cloudflare account with Workers enabled
-- GitHub account for hosting the frontend (or any static hosting)
-- Basic knowledge of Git and command line
+The product UI is React source in `frontend/`, compiled to `frontend/dist`, and served by the Worker through its `ASSETS` binding. Worker routing and APIs remain in `src/`; the API reference from `docs/api/` is bundled into Worker assets at `/api/` and `/api/openapi.yaml`. The separate Cloudflare Pages site can publish the documentation landing page from `docs/`; `docs/index.html` is not a product asset.
 
-### 1. Clone the Repository
+For a clean local setup, install both declared packages and use the root commands:
 
 ```bash
-git clone https://github.com/dytsou/shorten-url.git
-cd shorten-url
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm --dir frontend install --frozen-lockfile --ignore-scripts
+cp wrangler.toml.example wrangler.toml
+# Set a real LINKS namespace and production-only Access values in wrangler.toml or secrets.
+pnpm build
+pnpm dev
 ```
 
-### 2. Setup Configuration
-
-```bash
-# Copy the example configuration
-cp config/config.example.js config/config.js
-
-# Edit the configuration file
-vim config/config.js
-```
+`pnpm dev`, `pnpm preview`, and `pnpm deploy` build `frontend/dist` before running Wrangler. The Worker serves the UI at `GET /`. Only the `production` branch mounts its product page at `/shorten`; other branch previews stay at `/`. Regardless of the page path, the UI sends API requests to `POST /` and `/settings/api/*`. Standalone settings pages are not exposed.
 
-Update the `config/config.js` file with your settings:
+Production must use an Access-protected custom hostname, set `workers_dev = false`, and set `ACCESS_ALLOWED_HOSTS` to that hostname. Keep `CLOUDFLARE_API_TOKEN`, `FLAGSHIP_CSRF_SECRET`, and provider credentials in Cloudflare/GitHub secrets, never Vite metadata or tracked configuration. Optional `FRONTEND_URL` and `FRONTEND_PAGES_BASE` retain legacy error/interstitial pages only; they are not used to serve the normal UI.
 
-```javascript
-const config = {
-  frontend: {
-    // IMPORTANT: Update this to your GitHub Pages URL or custom domain
-    url: "https://yourusername.github.io/shorten-url/",
-  },
-  // ... other settings
-};
-```
+The Worker deployment workflow reads the non-secret GitHub variables
+`LINKS_KV_NAMESPACE_ID` and `ACCESS_ALLOWED_HOSTS`, plus the
+`CLOUDFLARE_API_TOKEN` secret, to create its ignored `wrangler.toml` at build
+time.
 
-### 3. Deploy Frontend
+### Prerequisites
 
-#### Option A: GitHub Pages (Recommended)
+- A Cloudflare account with Workers and Pages; the Deploy to Cloudflare button provisions the required KV namespace
+- A GitHub or GitLab account to receive the repository created by the Deploy to Cloudflare button
+- A Cloudflare Pages project to publish `docs/`
+- Node.js 24 or newer and pnpm 10.22.0 for manual deployment
 
-1. Push your code to GitHub
-2. Go to your repository settings
-3. Enable GitHub Pages for the main branch
-4. Your frontend will be available at `https://yourusername.github.io/shorten-url/`
+### 1. Deploy with Cloudflare (Recommended)
 
-#### Option B: Custom Domain
+1. Click the **Deploy to Cloudflare** button near the top of this README.
+2. Connect your Cloudflare and GitHub or GitLab accounts, then choose the destination repository and Worker name.
+3. Confirm the `LINKS` KV binding. Cloudflare provisions the namespace and deploys the Worker from the `main` branch.
 
-1. Upload the `docs/` directory to your web hosting
-2. Update the `frontend.url` in `config/config.js` to match your domain
+The button deploys the Worker; it does not publish `docs/`. Connect the created repository to Cloudflare Pages, leave the build command blank, and set the output directory to `docs`. The React product UI is built into `frontend/dist` and served by the Worker through `ASSETS`; use the Worker deployment workflow or `pnpm deploy` to build and deploy those assets.
 
-### 4. Setup Cloudflare Workers
+### 2. Alternative: Manual Worker Deployment
 
-#### Install Wrangler CLI
+Clone the repository and install the pinned Wrangler version:
 
 ```bash
-npm install -g wrangler
+git clone https://github.com/dytsou/shorten-url.git
+cd shorten-url
+corepack enable
+pnpm install
 ```
 
-#### Configure Wrangler
+The Worker serves the product UI from `ASSETS`. To deploy manually, install both packages, create the local Wrangler file from the tracked example, set the `LINKS` namespace ID and Access hostname, then build and deploy:
 
 ```bash
-# Login to Cloudflare
-wrangler auth login
-
-# Create a new KV namespace for storing URLs
-wrangler kv:namespace create "LINKS"
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm --dir frontend install --frozen-lockfile --ignore-scripts
+cp wrangler.toml.example wrangler.toml
+# Set the LINKS namespace ID and ACCESS_ALLOWED_HOSTS.
+pnpm build
+pnpm exec wrangler login
+pnpm deploy
 ```
 
-#### Create wrangler.toml
+The `LINKS` binding in `wrangler.toml` omits an account-specific namespace ID so Wrangler can provision it. To use an existing KV namespace, create it with `pnpm exec wrangler kv namespace create LINKS` and set its ID in `wrangler.toml` before deploying.
 
-Create a `wrangler.toml` file in your project root:
+### 3. Deploy Documentation to Cloudflare Pages
 
-```toml
-name = "url-shortener"
-main = "src/worker.js"
-compatibility_date = "2024-01-01"
+The `docs/` directory contains the API reference and documentation. To create a Pages site, connect your repository, set the production branch to the branch containing your documentation, leave the build command blank, and use `docs` as the output directory.
 
-[[kv_namespaces]]
-binding = "LINKS"
-id = "your-kv-namespace-id-here"
-```
-
-Replace `your-kv-namespace-id-here` with the ID from the KV namespace creation command.
+This repository's Cloudflare Pages project publishes `docs/` from the `production` branch. The product UI is served by the Worker and does not depend on the Pages site.
 
-#### Deploy the Worker
+For custom error and interstitial pages, set `frontend.pagesBase` to the directory containing those files.
 
-```bash
-wrangler deploy
-```
-
-### 5. Update Configuration
-
-After deploying, update your `config/config.js` with the worker URL:
-
-```javascript
-const config = {
-  frontend: {
-    url: "https://yourusername.github.io/shorten-url/",
-  },
-  // ... other settings
-};
-```
+The Worker returns short URLs using the request's origin, so configure its public domain in Cloudflare separately from `frontend.url`.
 
 ## ⚙️ Configuration Options
 
 ### Frontend Configuration
 
-| Option                   | Description                             | Default  |
-| ------------------------ | --------------------------------------- | -------- |
-| `frontend.url`           | URL where your frontend is hosted       | Required |
-| `frontend.displayDomain` | Domain shown in UI (null = auto-detect) | `null`   |
-| `frontend.theme`         | UI theme selection                      | `""`     |
+| Option                   | Description                                             | Default |
+| ------------------------ | ------------------------------------------------------- | ------- |
+| `frontend.url`           | Optional origin for legacy error and interstitial pages | `""`    |
+| `frontend.pagesBase`     | Base URL for hosted error and interstitial pages        | `url`   |
+| `frontend.workerOrigin`  | Public Worker origin for a separately hosted frontend   | `""`    |
+| `frontend.displayDomain` | Domain shown in UI (null = auto-detect)                 | `null`  |
+| `frontend.theme`         | UI theme selection                                      | `""`    |
 
 ### Worker Configuration
 
-| Option                          | Description                       | Default    |
-| ------------------------------- | --------------------------------- | ---------- |
-| `worker.no_ref`                 | Hide HTTP referrer header         | `"off"`    |
-| `worker.cors`                   | Enable CORS for API requests      | `"on"`     |
-| `worker.unique_link`            | Same URL = same short link        | `true`     |
-| `worker.custom_link`            | Allow custom slugs                | `true`     |
-| `worker.safe_browsing_api_key`  | Google Safe Browsing API key      | `""`       |
-| `worker.min_random_key_length`  | Minimum length for generated keys | `6`        |
-| `worker.max_custom_slug_length` | Maximum length for custom slugs   | `50`       |
-| `worker.reserved_slugs`         | List of reserved slugs            | See config |
+| Option                          | Description                                                     | Default    |
+| ------------------------------- | --------------------------------------------------------------- | ---------- |
+| `worker.no_ref`                 | Use the hosted no-referrer interstitial before redirecting      | `"off"`    |
+| `worker.cors`                   | Add wildcard CORS headers for API responses                     | `"on"`     |
+| `worker.unique_link`            | Reuse a key when the same URL has already been shortened        | `true`     |
+| `worker.custom_link`            | Allow custom slugs                                              | `true`     |
+| `SAFE_BROWSING_API_KEY`         | Optional Google Safe Browsing API key stored as a Worker secret | Unset      |
+| `worker.min_random_key_length`  | Minimum length for generated keys                               | `6`        |
+| `worker.random_chars`           | Characters used for generated keys                              | See config |
+| `worker.max_custom_slug_length` | Maximum length for custom slugs                                 | `50`       |
+| `worker.reserved_slugs`         | Slugs that cannot be used as custom links                       | See config |
 
 ### Security Configuration
 
-| Option                     | Description                | Default |
-| -------------------------- | -------------------------- | ------- |
-| `security.rate_limit`      | Requests per minute per IP | `10`    |
-| `security.validate_urls`   | Enable URL validation      | `true`  |
-| `security.blocked_domains` | List of blocked domains    | `[]`    |
+| Option                              | Description                                                        | Default |
+| ----------------------------------- | ------------------------------------------------------------------ | ------- |
+| `security.rate_limit`               | Not implemented by the Worker                                      | Unused  |
+| `security.validate_urls`            | URLs are always validated; this setting does not toggle validation | Unused  |
+| `security.blocked_domains`          | Domain blocklists are not implemented by the Worker                | Unused  |
+| `security.block_suspicious_domains` | Domain blocklists are not implemented by the Worker                | Unused  |
 
 ### Storage Configuration
 
-| Option                 | Description               | Default   |
-| ---------------------- | ------------------------- | --------- |
-| `storage.binding_name` | KV namespace binding name | `"LINKS"` |
+| Option                 | Description                                                          | Default   |
+| ---------------------- | -------------------------------------------------------------------- | --------- |
+| `storage.binding_name` | Worker reads KV from `env.LINKS`; this config value is not consulted | `"LINKS"` |
 
 ## 🔧 Advanced Setup
 
 ### Custom Domain
 
-1. Add a custom domain in Cloudflare Workers dashboard
-2. Update your DNS records to point to Cloudflare
-3. Update the worker URL in your configuration
+1. Add a custom domain to the Cloudflare Worker and protect it with Cloudflare Access.
+2. Add a custom domain to the Cloudflare Pages project for documentation.
+3. Set `frontend.url` only when using separately hosted legacy error or interstitial pages.
 
 ### Google Safe Browsing
 
 1. Get an API key from [Google Cloud Console](https://developers.google.com/safe-browsing/v4/get-started)
-2. Add the key to your `config.js`:
+2. Store it as a Worker secret:
 
-```javascript
-worker: {
-    safe_browsing_api_key: "your-api-key-here",
-}
+```bash
+pnpm exec wrangler secret put SAFE_BROWSING_API_KEY
 ```
 
+The Worker reads this secret at runtime. The key is not stored in `config/config.js`.
+
 ### Analytics Integration
 
-Configure analytics in your `config.js`:
-
-```javascript
-analytics: {
-    enable_tracking: true,
-    ga_tracking_id: "G-XXXXXXXXXX", // Google Analytics 4
-    analytics_endpoint: "https://your-analytics-endpoint.com"
-}
-```
+Click analytics is not implemented, and the `analytics` object in `config/config.js` is not used by the Worker. Cloudflare Worker logs and traces are enabled in `wrangler.toml`.
 
 ### Custom Error Pages
 
-The system fetches error and redirect pages from your GitHub Pages repository, so you can fully customize their content and design:
-
-- **404 Page**: <code>https://dytsou.github.io/404.html</code>
-- **Security Warning**: <code>https://dytsou.github.io/safe-browsing-warning.html</code>
-- **No-Referrer Redirect**: <code>https://dytsou.github.io/no-ref-page.html</code>
+The Worker fetches optional error and interstitial pages from `frontend.pagesBase` (or `frontend.url` when `pagesBase` is not set). Add these files to your static host to customize them:
 
-You can edit these HTML files in your GitHub Pages repo to change the look, text, or behavior at any time. The worker will always serve the latest version from your site.
+- **404 Page**: `404.html`
+- **Error Page**: `error.html`
+- **Security Warning**: `safe-browsing-warning.html`
+- **No-Referrer Redirect**: `no-ref-page.html`
 
-All pages feature responsive design with glassmorphism effects matching your main interface.
+These files are not included in this repository. The Worker fetches their current contents from your static host when needed.
 
 ## 📖 API Documentation
 
-The project includes comprehensive API documentation available at `/api` endpoint with interactive Swagger UI.
+The API reference is a static Swagger UI built from `docs/api/` and bundled into Worker assets. `/api` redirects to `/api/`, where the interactive reference is served.
 
 ### OpenAPI Specification
 
 - **Format**: OpenAPI 3.1.0
 - **Location**: [docs/api/openapi.yaml](docs/api/openapi.yaml)
-- **Interactive UI**: Available at `/api` endpoint on your deployed worker
+- **Interactive UI**: [docs/api/index.html](docs/api/index.html), bundled into Worker assets and served at `/api/`
 - **Offline Access**: [docs/api/index.html](docs/api/index.html) for local viewing
 
 ### Shorten URL
 
-**POST** `/shorten`
+**POST** `/`
 
 ```json
 {
   "url": "https://example.com/very-long-url",
-  "custom_slug": "my-link" // optional
+  "custom_slug": "my-link"
 }
 ```
 
-**Response:**
+The endpoint stays at the origin root even when the production page is mounted at `/shorten`. `custom_slug` is optional. The default Worker template requires Cloudflare Access headers before creating a link.
+
+**Response (201 Created):**
 
 ```json
 {
-  "short_url": "https://url.tsou.me/abc123"
+  "short_url": "https://your-worker-domain.example/abc123"
 }
 ```
 
@@ -242,11 +217,26 @@ The project includes comprehensive API documentation available at `/api` endpoin
 
 **GET** `/{key}`
 
-Redirects to the original URL or shows appropriate error page.
+Redirects to the stored destination with HTTP 302. Query parameters from the short URL are appended to the destination.
 
 ### Additional Endpoints
 
-- **GET** `/api` - Interactive API documentation (Swagger UI)
+- **GET** `/` - Serves the Worker-hosted React interface
+- **OPTIONS** - Returns a CORS preflight response
+
+### Flagship Management API
+
+The authenticated control plane manages the `shorten-routing` flag under `/settings/api`. Requests require Cloudflare Access authentication. Fetch a CSRF token before sending a write; POST and PUT requests must include that token in `X-CSRF-Token`, use `application/json`, and come from the same origin as the UI.
+
+| Method | Path                                         | Purpose                                                   |
+| ------ | -------------------------------------------- | --------------------------------------------------------- |
+| `GET`  | `/settings/api/csrf`                         | Get a CSRF token for the signed-in Access user and origin |
+| `GET`  | `/settings/api/flags`                        | Read the saved shortening flag                            |
+| `POST` | `/settings/api/flag`                         | Create the `shorten-routing` flag                         |
+| `PUT`  | `/settings/api/flag/shorten-routing`         | Save a draft with `expectedUpdatedAt` concurrency control |
+| `POST` | `/settings/api/flag/shorten-routing/publish` | Publish the saved version                                 |
+
+Targeting rules are evaluated by ascending priority. Conditions in a rule are combined with AND and can target country, region, continent, timezone, browser language, or UTM source, medium, and campaign. Supported operators are `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `in`, and `not_in`. A rule can also set `rolloutPercentage` from 0 to 100; the Worker uses a stable visitor key for the canary assignment. See the OpenAPI schema for request and response shapes.
 
 ## 🛠️ Development
 
@@ -254,45 +244,50 @@ Redirects to the original URL or shows appropriate error page.
 
 ```bash
 # Start local development server (see wrangler.toml for port / host)
-wrangler dev
+pnpm dev
 
-# Test with curl (example; in production, requests must pass through Cloudflare Access/WARP)
-curl -X POST http://localhost:8787/shorten \
+# Local-only example. The handler checks for both headers; Cloudflare Access must
+# authenticate production requests before they reach the Worker.
+curl -X POST http://localhost:8787/ \
   -H "Content-Type: application/json" \
+  -H "Cf-Access-Jwt-Assertion: local-test" \
+  -H "Cf-Access-Authenticated-User-Email: you@example.com" \
   -d '{"url": "https://example.com"}'
 ```
 
+The Worker combines built-in defaults with non-secret Wrangler variables; keep credentials in Wrangler secrets. Run `pnpm test` to execute the Worker tests.
+
 ### File Structure
 
 ```
 shorten-url/
 ├── src/
-│   ├── worker.js           # Production Cloudflare Worker
-│   ├── worker.dev.js       # Development Cloudflare Worker
-│   └── worker.example.js   # Worker template
+│   ├── lib/                 # Validation, routes, KV, assets, and observability
+│   ├── worker.js            # Production Worker entrypoint
+│   └── worker.example.js    # Example Worker entrypoint
+├── frontend/               # React product UI, about-page template, and build configuration
 ├── docs/
-│   ├── index.html          # Homepage interface
+│   ├── index.html          # Documentation site homepage
+│   ├── about.md            # Content rendered as the /about website page
 │   └── api/
 │       ├── index.html      # Swagger UI for API docs
 │       └── openapi.yaml    # OpenAPI 3.1.0 specification
 ├── config/
-│   ├── config.js           # Configuration (not in git)
-│   └── config.example.js   # Configuration template
-├── .cursor/                # Cursor IDE rules and workflow
+│   ├── config.js            # Existing deployment template
+│   └── config.example.js    # Configuration example
+├── wrangler.toml.example    # Wrangler deployment template
 ├── .github/                # GitHub workflows and templates
-├── .gitignore             # Git ignore rules
-├── README.md              # This file
-└── wrangler.toml          # Wrangler configuration
+├── .gitignore              # Ignores local-only files
+└── README.md               # This file
 ```
 
 ## Security Considerations
 
-- Keep your `config.js` file private (it's in `.gitignore`)
-- Use environment variables for sensitive data in production
-- Enable rate limiting to prevent abuse
-- Consider enabling Google Safe Browsing for malicious URL detection
+- Keep API keys out of version control; store them with Wrangler secrets
+- Configure a Cloudflare Access policy in front of the Worker; the handler checks for Access headers but does not verify JWT signatures itself
+- The Worker has no built-in per-IP rate limit or blocked-domain list
+- Consider enabling Google Safe Browsing for redirect destinations
 - Regularly monitor your KV storage usage
-- Configure Cloudflare Access / WARP correctly, as URL shortening is intended to be available only to authenticated/requesters you control
 
 ## Troubleshooting
 
@@ -305,7 +300,9 @@ shorten-url/
 
 **Worker deployment fails:**
 
-- Check your `wrangler.toml` configuration
+- Confirm `src/worker.js`, `wrangler.toml.example`, and `frontend/` are present
+- Build the frontend so `frontend/dist/index.html` exists
+- Ensure the `LINKS` KV namespace ID in `wrangler.toml` is valid
 - Ensure KV namespace ID is correct
 - Verify you're logged into the correct Cloudflare account
 
@@ -317,13 +314,13 @@ shorten-url/
 
 **Frontend not loading:**
 
-- Update `frontend.url` in your config to match your hosting URL
-- Ensure CORS is enabled in worker configuration
+- Check that the Worker has an `ASSETS` binding and `frontend/dist/index.html` was built
+- If shortening returns an invalid-path response, check that the frontend POST path is `/`
+- Enable CORS if the frontend and Worker use different origins
 
 **Rate limiting issues:**
 
-- Adjust `security.rate_limit` in your configuration
-- Consider implementing IP allowlisting for trusted sources
+- The Worker does not currently rate-limit requests. Protect shortening with Cloudflare Access or add a rate limiter.
 
 ## License
 
@@ -347,12 +344,14 @@ If you encounter any issues or have questions:
 
 ## Deployment Checklist
 
-- [ ] Updated `config.js` with your settings
-- [ ] Deployed frontend to GitHub Pages or custom hosting
+- [ ] Set `LINKS_KV_NAMESPACE_ID` and `ACCESS_ALLOWED_HOSTS` for Worker deployment
+- [ ] Build the React frontend into `frontend/dist`
+- [ ] Deployed `docs/` to Cloudflare Pages
 - [ ] Created Cloudflare KV namespace
 - [ ] Configured `wrangler.toml` with correct KV namespace ID
-- [ ] Deployed worker using `wrangler deploy`
-- [ ] Tested URL shortening functionality
+- [ ] Protected the Worker with a Cloudflare Access policy
+- [ ] Deployed the Worker using `pnpm deploy`
+- [ ] Tested URL shortening at `POST /`
 - [ ] Verified copy-to-clipboard feature works
 - [ ] Tested custom error pages (404, security warnings)
 - [ ] (Optional) Configured custom domain

package/config/config.example.js

@@ -9,9 +9,15 @@
 const config = {
   // Frontend Configuration
   frontend: {
-    // URL where your frontend is hosted (used by worker to serve the main page)
-    // REQUIRED: Change this to your GitHub Pages URL or custom domain
-    url: "https://yourusername.github.io/your-repo-name/",
+    // Leave empty when the Worker serves the React UI. Set this only for
+    // separately hosted legacy error/interstitial pages.
+    url: "",
+
+    // Public Worker origin used by frontend/index.html for shortening and
+    // protected settings APIs when the frontend is hosted separately. Keep it in
+    // sync with the HTML meta tag or VITE_WORKER_ORIGIN; leave empty when the
+    // Worker serves the page.
+    workerOrigin: "",
 
     // Domain displayed in the custom slug input prefix
     // If null, will use the current domain automatically
@@ -64,6 +70,7 @@ const config = {
       "support",
       "contact",
       "about",
+      "settings",
     ],
   },
 
@@ -73,6 +80,18 @@ const config = {
     binding_name: "LINKS",
   },
 
+  // Flagship Configuration (optional until the binding and secrets are provisioned)
+  flagship: {
+    // Wrangler binding name. The Worker expects the official `env.FLAGS` binding.
+    binding_name: "FLAGS",
+    // Set in the Flagship binding block in wrangler.toml; do not put credentials here.
+    app_id: "",
+    // Worker secrets/variables used only by protected settings management:
+    // CLOUDFLARE_ACCOUNT_ID, FLAGSHIP_APP_ID, FLAGSHIP_API_TOKEN,
+    // FLAGSHIP_CSRF_SECRET, CF_ACCESS_ISSUER, CF_ACCESS_AUDIENCE,
+    // and optionally CF_ACCESS_JWKS_URL.
+  },
+
   // Security Configuration
   security: {
     // Rate limiting (requests per minute per IP)