POC (#68): git-backed handbook on Astro + Cloudflare — GitHub auth, review workflow, no CMS/DB

[VibratingKoala]

Custom Astro SSR app on Cloudflare Workers replacing VitePress/GitHub Pages, so the handbook can gate per-page reader access — which a static host can't do. No CMS, no database: content, access control, drafts, and publishing all live in git/GitHub.

Architecture

Browser → Astro SSR Worker (stateless, no datastore)
  CONTENT  = markdown in doc/*.md — the SAME files the legacy VitePress site
             builds from (single source, nothing ported). POC frontmatter
             (visibility/section/parent/sort) lives there; VitePress ignores it.
             Everything in the build is PUBLISHED; drafts/pending edits live on
             handbook/<slug> branches + PRs
  ACCESS   = GitHub itself: repo collaborators ARE the allow-list (nothing committed here)
  IDENTITY = GitHub username (no emails anywhere; a CI guard fails the build on any)
  SESSION  = AES-GCM encrypted cookie (+ the user's own GitHub token, auto-refreshed)

Sign in with GitHub (org GitHub App, live since 07-09). Each user's own token maps repo permission → role (resolveRoleSelf), re-verified every ~10 min; no bot token in the App path (a classic-OAuth fallback with a bot token still exists but is slated for removal).

Access model — reading vs capability are separate axes

Reading (2 tiers, roles play no part): public → anyone; internal → any signed-in person. There is deliberately no finer tier — every signed-in user is a repo collaborator who could read the markdown source on GitHub anyway. Forbidden == not-found (404, no existence signal); fail-closed everywhere (unknown visibility → internal; malformed page files → tightest tier).

Capability (from GitHub repo permission):

GitHub permission	handbook role	can
admin / maintain	admin	+ review dashboard: approve & publish / reject
write	editor	+ edit: save drafts, submit for approval
explicit collaborator	reader	read internal pages
everyone else	anonymous	public pages only

(The gate is the explicit-collaborator check (204/404), never permission=="read" — GitHub reports read for any user while the repo is public; regression-tested.)

Publishing is git-native — no status field

Save draft            commit on handbook/<slug>, NO PR — private WIP
                      (reopening the page RESUMES the draft; listing shows a
                       "draft in progress" chip; new pages get their own section)
Submit for approval   the branch gets its ONE PR per page — pending, unpublished
Approve & publish     admin merges (in-app dashboard or GitHub) → deploy → live

Every commit is authored by the signed-in person (their GitHub App user token — no bot; GitHub refuses writes the moment push access is revoked). Concurrent edits 409 via blob sha; a branch holding unmerged commits is never force-reset (data-loss regression-tested); deletes are always review requests. The dashboard honors the main ruleset fully — no self-approval, checks must pass, stale branches auto-refresh.

Agent surface (llms.txt)

/llms.txt (index), /llms-full.txt (all readable content) and per-page /<slug>.md (raw markdown) — llmstxt.org endpoints for AI tooling (the standard-repository code-quality hook points every org AI session at the handbook). Dynamic, through the same canRead gate as HTML: anonymous sees public pages only, fail closed, forbidden == 404. Supersedes the old site's build-time vitepress-plugin-llms output at cutover — same URLs, now ACL-aware. Note: the five style-guide pages must flip to visibility: public before cutover (the hook fetches anonymously) — pending sign-off.

Test locally (no GitHub setup needed)

cd app && pnpm install
cp .dev.vars.example .dev.vars   # set COOKIE_ENCRYPTION_KEY (≥32 chars), DEV_LOGIN=1
pnpm dev:edit                    # dev server + local write agent (real file+git commits)
                                 # content = ../doc/*.md directly; no seed step
# personas without OAuth:  /api/auth/dev-login?user=alice&role=editor   (reader, admin)

Real GitHub login is locally testable too: personal OAuth App (callback http://localhost:4321/api/auth/callback), DEV_LOGIN=0 — verified live.

Staging & production

• ONE worker (osbr-handbook); [env.staging] is inert with the Cloudflare adapter — see POC.md "Deploy to staging" for the mechanics (keep_vars, dashboard-managed vars, GITHUB_BRANCH POC targeting). Non-prod hosts serve an environment ribbon + X-Robots-Tag: noindex; both retire automatically on the real domain (host-based).
• The org GitHub App is live (installed on the repo since 07-09) — login, per-person commits and the full draft→submit→approve→merge loop work on the deployed staging URL.
• Deploys are currently manual (pnpm build && npx wrangler deploy). deploy-worker.yml auto-deploys pushes to this branch / main (incl. content-only doc/** merges) once a repo admin adds the CLOUDFLARE_API_TOKEN secret — required for "approve & publish" to be self-serve.
• CI: run-tests (required check) also fires on handbook/* PRs — without that, editorial merges could never satisfy the ruleset. A docs-build job keeps the legacy VitePress site green until cutover.

Verified

• 94 unit tests: ACL truth table, session crypto tamper/expiry, GitHub role mapping, PR-mode driver (branch create/reuse/force-reset guard, sha conflicts, draft vs submit), review approve→merge ordering, frontmatter parser round-trip incl. the on-disk # H1 boundary, llms.txt builders, sanitizer XSS. astro check 0/0/0, build, biome, both guards (incl. no-personal-emails).
• Live: persona×visibility matrix, editor RBAC + admin-only dashboard gating, CSRF, stored-XSS stripping, ACL-gated search, real GitHub OAuth round-trip, editor save/delete flows driven in a real browser, llms.txt/.md endpoints anon vs signed-in (2 vs 15 pages, cache headers flip). The legacy VitePress build (incl. vitepress-plugin-llms) was run against the frontmattered doc/ files — no breakage, no frontmatter leakage.
• Full multi-agent code review (8 angles → adversarial verification) — all 8 findings fixed, incl. a data-loss bug and a revocation fail-open.

After this PR merges — the roadmap

At merge time

• Merge needs one approval from another editor (no self-approval) + green run-tests (add the ci-testing label to trigger it on this branch)
• Delete the branch on merge — that deletion is what auto-flips editor submissions from targeting this branch to main (resolveBase() self-retires; GitHub retargets the existing open handbook/* PRs too)

One-time setup (parallel, any order)

• [org admin] Org GitHub App created + installed on this repo (done 2026-07-09; residual cleanup — drop GITHUB_TOKEN, GITHUB_WRITE_ENABLED, revoke the personal demo PAT/OAuth app — tracked in POC.md)
• [repo admin] Add the CLOUDFLARE_API_TOKEN repo secret (company account; Workers Scripts:Edit + Workers KV Storage:Edit) so merges auto-deploy — until then every publish is a manual deploy
• [infra] DNS Phase 0: move the osbrjp.com zone from Route 53 to the company Cloudflare account (records copied exactly — MX/email double-checked; full runbook in POC.md). Blocks only the final domain flip
• [content] Flip the five style guides to visibility: public (required by the standard-repository hook's anonymous fetch; pending sign-off)

Production

• Verify the full loop on workers.dev after merge, then flip: attach handbook.osbrjp.com as the Worker's custom domain + switch OAUTH_ORIGIN — both sites stay up throughout; rollback = recreate one CNAME
• Days later: retire GitHub Pages + release.yml + the release branch; make the repo private (check for public forks first); retire the VitePress machinery (doc/.vitepress/, root deps, docs-build job) — doc/*.md stays, it IS the content
• Cleanup task: prune POC demo pages/edit branches; drop the now-inert GITHUB_BRANCH var; set up staging isolation (separate worker) BEFORE routine post-cutover deploys; triage the stale pre-rewrite PRs (Add privacy policy page #65 Release Candidate 2026-07-09 20:09:51 +0900 #63 Fix Travel Planner Substantials #60 Modify On-boarding Guide #52 Add Accessibility Policy #44 Add a Main Visual to The Main Page #38 — POC: move handbook off VitePress to a headless CMS with reader RBAC + Google Workspace auth #71 closed 07-15) and the 35 Dependabot alerts that die with the old VitePress tree

GITHUB_WRITE_ENABLED stays wired as the editing kill switch in prod — one secret change disables editing instantly, readers unaffected.

Closes #68.

🤖 Generated with Claude Code