docs: add a security tutorial and organizer checklist

Author: abraham

AGENTS.md

@@ -37,7 +37,7 @@ Run from the repo root.
 | `npm run build`                | Production build of every page to `packages/web/dist`. Reads content from the Firestore emulator, see `FIRESTORE_TARGET` below                         |
 | `npm start`                    | Emulators, functions and the Astro dev server at http://localhost:4321                                                                                 |
 | `npm run serve`                | Builds from the emulator data, then serves `dist` on the Hosting emulator at http://localhost:5000                                                     |
-| `./hb doctor`                  | Checks the local setup, Firebase login, project, billing plan and deployed functions                                                                   |
+| `./hb doctor`                  | Checks the local setup, Firebase login, project, billing plan, deployed functions, deploy roles, service account keys and browser API keys             |
 | `./hb init`                    | Sets up a site: Firebase project and web app, event details in `packages/config`, billing, first deploy. Changes production, so only run it when asked |
 
 Before finishing a change, run `npm run lint` and `npm test`, or at least the affected Vitest project and type check.

docs/README.md

@@ -8,6 +8,7 @@
 - [Styling](tutorials/03-styling.md)
 - [Deploy](tutorials/04-deploy.md)
 - [Notifications](tutorials/05-notifications.md)
+- [Security](tutorials/06-security.md)
 - [Firestore utils](tutorials/firebase-utils.md)
 
 ## Maintainers

docs/tutorials/02-firebase.md

@@ -35,7 +35,7 @@ Turn on the sign-in methods in `auth.providers` in the [Firebase console](https:
 - `google`: add **Google**.
 - `facebook` and `twitter`: add them with the app ID and secret from Facebook or X.
 
-The link in the email opens the page the visitor signed in from. Its domain must be under **Authentication** > **Settings** > **Authorized domains**. Firebase adds `localhost` and the project's `web.app` and `firebaseapp.com` domains. Add a custom domain yourself.
+The link in the email opens the page the visitor signed in from. Its domain must be under **Authentication** > **Settings** > **Authorized domains**. Firebase adds `localhost` and the project's `web.app` and `firebaseapp.com` domains. Add a custom domain yourself, and remove `localhost`. See [Security](06-security.md#what-you-set).
 
 Locally, the Auth emulator doesn't send email. Find the sign-in link under **Authentication** in the Emulator UI at http://localhost:4000, or in the emulator's log, and open it in the browser.
 

docs/tutorials/04-deploy.md

@@ -35,6 +35,7 @@ Your Firebase project must be on the Blaze plan. See [Billing](02-firebase.md#bi
 In the [`.github/workflows`](.github/workflows) folder, you can find two workflows to help you develop and deploy Hoverboard to Firebase:
 
 - [`main.yaml`](.github/workflows/main.yaml) Builds the project, runs the linter and the tests on every push.
+- [`security.yaml`](.github/workflows/security.yaml) Checks the workflows with zizmor, and the dependencies for known vulnerabilities.
 - [`deploy-preview.yaml`](.github/workflows/deploy-preview.yaml) Checks `packages/config` with `./hb validate-config`, then deploys a preview of the website to Firebase after every push to a pull request. Functions and Firestore rules are not deployed. See [Editing on GitHub](01-configure-app.md#editing-on-github).
 - [`deploy.yaml`](.github/workflows/deploy.yaml) Deploys the project to Firebase after every push to the `main` branch. You can also run it by hand, for example after you change content in Firestore: open **Actions** > **Deploy** > **Run workflow** on GitHub, or run `gh workflow run deploy.yaml`. It only deploys from `main`. It deploys with `--force`, so it deletes functions that are no longer in the code without asking.
 
@@ -55,7 +56,7 @@ Both workflows sign in to Google Cloud with Workload Identity Federation. GitHub
 The command uses your Firebase CLI login. It needs the Owner role, or permission to create service accounts, workload identity pools and IAM bindings. It is safe to run again. It:
 
 1. Enables the IAM, IAM Credentials, Security Token Service and Cloud Resource Manager APIs.
-1. Creates a `github-deploy` service account with the roles a deploy needs: `Firebase Hosting Admin`, `Firebase Rules Admin`, `Cloud Datastore Index Admin`, `Cloud Datastore Viewer` (the build reads your content), `Firebase Storage Viewer`, `Storage Bucket Viewer`, `Cloud Functions Admin`, `Cloud Scheduler Admin`, `Service Usage Consumer` and `Service Account User`. It can't write to Firestore or read Auth users and Storage files. Earlier versions granted `Firebase Admin`, `Cloud Run Admin`, `Artifact Registry Writer` and `Service Usage Admin`, and the command takes them away (verify with a deploy of every target).
+1. Creates a `github-deploy` service account with the roles a deploy needs: `Firebase Hosting Admin`, `Firebase Rules Admin`, `Cloud Datastore Index Admin`, `Cloud Datastore Viewer` (the build reads your content), `Firebase Storage Viewer`, `Storage Bucket Viewer`, `Cloud Functions Admin`, `Cloud Scheduler Admin`, `Service Usage Consumer` and `Service Account User`. It can't write to Firestore or read Auth users and Storage files. Earlier versions granted `Firebase Admin`, `Cloud Run Admin`, `Artifact Registry Writer` and `Service Usage Admin`, and the command takes them away.
 1. Creates a `github` workload identity pool and provider that only accept tokens from your repository. It reads the repository from the `origin` remote. Pass `--repo owner/name` to choose another one.
 1. Sets the `WIF_PROVIDER` and `DEPLOY_SERVICE_ACCOUNT` repository variables with the [GitHub CLI](https://cli.github.com/). Without it, the command prints the values to add in the repository settings.
 
@@ -74,3 +75,5 @@ The preview and the live deploys use the same service account. A pull request's
 The first deploy, from `./hb init` or `./hb deploy`, runs with your own account. It enables the APIs, creates the Firestore database, and grants Google's service agents the roles functions need. The deploy account can't do these, so if a new kind of function needs another API, deploy once from your computer.
 
 You can now push to your `main` branch and it'll deploy to the production (`live`) Firebase Hosting channel and pull requests will deploy a temporary preview.
+
+Before the event, go through the [security checklist](06-security.md#what-you-set).

docs/tutorials/06-security.md

@@ -0,0 +1,47 @@
+# Security
+
+What Hoverboard protects for you, and what you set in your own Firebase project and GitHub repository.
+
+## What Hoverboard does
+
+- **Firestore rules.** Visitors can only read your content. You change it in the Firebase console or with `./hb firestore-*`. Signed-in visitors can write only their own bookmarks, notification settings and feedback. The subscribe and partner forms can only add documents, with checked fields and sizes, and nobody can read them from the site. Export them with [`./hb firestore-csv`](01-configure-app.md#subscribers-and-partner-leads).
+- **Storage rules.** The site can't read or write your Storage bucket.
+- **Content.** Links in your config and content can only be `https:`, `http:`, `mailto:` or a path on your site. The site drops other links, such as `javascript:` ones, even when they come straight from the Firebase console. Markdown is sanitized before it is shown, and the build sanitizes the hero illustration.
+- **Headers.** `firebase.json` sends `Strict-Transport-Security`, `Referrer-Policy`, `Permissions-Policy` and other headers on every page, and every page has a [Content Security Policy](01-configure-app.md#content-security-policy).
+- **Sign-out.** Signing out deletes the copy of the visitor's data that the site keeps in the browser for offline use.
+- **Logs.** The functions don't log emails, push tokens or user IDs.
+- **Deploys.** GitHub Actions deploy without a service account key, with only the roles a deploy needs. See [Deploying to Firebase with Github Actions](04-deploy.md#deploying-to-firebase-with-github-actions).
+
+The functions run as the project's default compute service account, which has the Editor role. Only code you deploy runs as it.
+
+## What you set
+
+Do these once when you set up a site, and check them again before the event.
+
+1. **Run `./hb doctor`.** It checks most of the settings below.
+1. **API keys.** Restrict the Firebase web app's browser key to your site's domains and to the APIs the site uses. Use a separate key for Google Maps, restricted to your domain and the Maps JavaScript API. `./hb doctor` checks both keys. See [Deploying to Firebase with Github Actions](04-deploy.md#deploying-to-firebase-with-github-actions).
+1. **Authorized domains.** In the Firebase console under **Authentication** > **Settings** > **Authorized domains**, keep only your site's domains. Remove `localhost`: local development uses the emulators, not your project. Preview deploys add their own domain. Remove the domains of previews that no longer exist.
+1. **Email enumeration protection.** Turn it on under **Authentication** > **Settings** > **User actions**, so sign-in doesn't tell anyone which emails have accounts. New projects have it on (verify).
+1. **Budgets.** Set a spend cap and a budget alert, so abuse can't run up a large bill. See [Spend cap and budget](02-firebase.md#spend-cap-and-budget).
+1. **Service account keys.** You don't need any. `./hb doctor` warns about keys and about the old `github-action-*` accounts. Delete them, and the GitHub secrets that held them.
+1. **Repository access.** Anyone who can push a branch can deploy to your live site and read your Firestore data. Only give write access to people you would trust with the Firebase console.
+1. **Repository settings.** On GitHub, under **Settings**:
+   - **Advanced Security**: turn on Dependabot alerts, secret scanning, push protection and private vulnerability reporting.
+   - **Actions** > **General**: set the workflow permissions to read, and turn off "Allow GitHub Actions to create and approve pull requests" unless you use release-please.
+   - **Rules**: add a ruleset for `main` that requires a pull request and the `build`, `test` and `lint` checks, and blocks force pushes.
+
+## What `./hb doctor` checks
+
+- Your Node.js version, Firebase login, project and site config.
+- No service account key files in the repository root.
+- The Blaze plan, and that every function is deployed as 2nd gen.
+- The Realtime Database is off.
+- The GitHub deploy setup and its roles, as `./hb setup-github` sets them.
+- Service account keys, and old `github-action-*` accounts.
+- The browser API key and the Maps key: which sites and APIs they allow.
+
+Each problem comes with what to change. Some checks need an API turned on in your project, and say so.
+
+## Reporting a vulnerability
+
+To report a vulnerability in Hoverboard, see the [security policy](../../.github/SECURITY.md).