A hosting service for PreTeXt-authored private instructor materials (solutions manuals, activity guides, …) with per-book instructor allowlists managed by book authors.
Live pieces: Firebase Hosting + Cloud Functions (v2, Node 22) +
Firestore + Cloud Storage, all in project pretext-hub.
All dynamic URLs (/b/**, /api/**) are rewritten to a single Cloud
Function, app (functions/src/index.ts), which routes by path to the
gatekeeper, the session endpoints, or the JSON API. Keeping it to one
function means a visit pays at most one cold start (2–5 s) instead of one
per endpoint.
Every materials URL goes through the gatekeeper
(functions/src/serveMaterials.ts):
/b/{book}/files/{name} → Storage: books/{book}/files/{name}
/b/{book}/{slot}/{...rest} → Storage: books/{book}/builds/{slot}/{ts}/{...rest}
where ts = books/{book}.currentBuilds[slot]
Auth is a 14-day HttpOnly __session cookie minted by /api/sessionLogin
from a fresh Firebase sign-in (/signin/, Google popup or email magic
link). After minting, the browser signs out of the Firebase SDK — the
cookie is the only credential, so clients can never talk to Firestore or
Storage directly and both rulesets stay deny-all permanently.
Access to a book (functions/src/access.ts) is granted to:
- admins — the
admincustom claim (grant withnode functions/scripts/set-admin.mjs someone@example.com), - authors — verified email listed in
books/{id}.authorEmails, - instructors — a doc exists at
books/{id}/instructors/{email}.
All email comparisons use normalizeEmail (trim + lowercase + Gmail-dot
strip) on both sides; anything writing emails must use the same function.
/book/{bookId}— materials index for anyone with access: build slots and standalone files, request-access message otherwise./dashboard/— authors manage instructor allowlists, book settings, standalone files, and publish builds; admins additionally create books and assign authors./api/**(functions/src/api.ts) — cookie-authenticated JSON API behind the dashboard and book pages:me, book get/patch, instructor list/add/remove, admin book list/create, and the publish endpoints.
From the dashboard, an author picks a slot name (e.g. solutions) and the
folder of built HTML. The browser uploads every file straight to
books/{id}/builds/{slot}/{buildId}/ using short-lived signed PUT URLs
(publish/start → publish/sign → publish/finish); nothing is visible
until finish verifies an index.html exists and flips
currentBuilds[slot]. The replaced build is kept for manual rollback
(repoint currentBuilds in the Firestore console); older ones are pruned.
Standalone files (PDFs etc.) upload the same way into files/.
The dashboard's Materials editor arranges everything in one ordered list —
headings, PreTeXt builds, files and external links, each with an optional
title and short description — saved via PUT /api/books/{id}/layout.
Builds/files with no layout entry are appended at the end when read, so
uploads never go missing; builds/delete and files/delete also drop the
entry. Admins can delete a whole book (POST /api/admin/books/delete).
Every HTML page served from a build gets
<script src="/omb-banner.js" data-…> inserted before </head> by the
gatekeeper; public/omb-banner.js draws a thin
"Instructor resources for ⟨book⟩" bar with a back link to /book/{id}.
books/{bookId}:
title, contactEmail, authorEmails[], currentBuilds{slot: ts},
layout[] — ordered materials list (functions/src/layout.ts):
{kind:"heading", id, title}
{kind:"build", key: slot, title, description}
{kind:"file", key: file name, title, description}
{kind:"link", id, title, url, description}
createdAt, createdBy
books/{bookId}/instructors/{normalizedEmail}:
email (duplicated for the collection-group query), addedBy, addedAt
| Phase | Scope | Status |
|---|---|---|
| 0–1 | Firebase setup, gatekeeper, session auth, sign-in page | done |
| 2 | Cookie-authed API, instructor management, author dashboard | done |
| 3 | /book/{bookId} materials index |
done |
| 4 | Admin tools (create books, assign authors, admin bootstrap) | done |
| 5 | Publish pipeline via signed upload URLs | done |
There is no package.json at the repo root; the only npm project is
functions/. You don't need to build by hand: firebase.json has a
functions predeploy hook that runs tsc on every deploy.
First time only (or after dependency changes):
npm --prefix functions ciDeploy, from the repo root:
firebase deploy # everything: hosting + functions + rules + indexes
firebase deploy --only hosting # only public/ changed (fast)
firebase deploy --only functions # only functions/src changedTo just type-check without deploying: npm --prefix functions run build.
If deploy fails with "User code failed to load … Timeout after 10000",
the CLI's function discovery is just slow on this machine; set
FUNCTIONS_DISCOVERY_TIMEOUT=60 and retry:
FUNCTIONS_DISCOVERY_TIMEOUT=60 firebase deploy # bash
$env:FUNCTIONS_DISCOVERY_TIMEOUT=60; firebase deploy # PowerShellThese live in GCP, not in anything firebase deploy touches. All were done
on 2026-11-12 with the gcloud CLI (gcloud auth login --update-adc).
- Storage CORS so the dashboard can PUT to signed upload URLs:
gcloud storage buckets update gs://pretext-hub.firebasestorage.app --cors-file=cors.json(re-run after adding a new origin/custom domain tocors.json). - URL signing: the functions run as the default compute service account,
which needs
roles/iam.serviceAccountTokenCreatoron itself to sign URLs:SA=46558030980-compute@developer.gserviceaccount.com gcloud iam service-accounts add-iam-policy-binding $SA \ --member=serviceAccount:$SA --role=roles/iam.serviceAccountTokenCreator
- Email-link sign-in: Auth → Sign-in method → Email/Password must have
"Email link (passwordless sign-in)" on (API:
signIn.email.passwordRequired = false).firebase.jsondeliberately omitsemailPasswordbecause the CLI can only express "password", not "link". - Admin bootstrap:
node functions/scripts/set-admin.mjs you@example.com. - Custom domain
instructors.openmathbooks.org: registered on Hosting and added to Firebase Auth's authorized domains. DNS (Cloudflare) needs aCNAME instructors → pretext-hub.web.appand aTXT _acme-challenge.instructorsrecord, both DNS only (grey cloud) — Cloudflare's proxy breaks Firebase's certificate provisioning.