Skip to content

About

A hosting service for pretext-authored private instructor materials

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

pretext-hub

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.

How a request flows

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:

  1. admins — the admin custom claim (grant with node functions/scripts/set-admin.mjs someone@example.com),
  2. authors — verified email listed in books/{id}.authorEmails,
  3. 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.

Pages and API

  • /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.

Publishing

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}.

Data model (Firestore)

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 history

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

Development

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 ci

Deploy, 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 changed

To 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              # PowerShell

One-time project setup (outside firebase deploy)

These 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 to cors.json).
  • URL signing: the functions run as the default compute service account, which needs roles/iam.serviceAccountTokenCreator on 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.json deliberately omits emailPassword because 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 a CNAME instructors → pretext-hub.web.app and a TXT _acme-challenge.instructors record, both DNS only (grey cloud) — Cloudflare's proxy breaks Firebase's certificate provisioning.

About

A hosting service for pretext-authored private instructor materials

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages