andrew.dunn.dev

Sveltia Identity Translator

~3 min
cmsauthcloudflare-workersgitlab
Source

A translated-identity proxy for Sveltia CMS. Editors sign in with their existing identity provider (Google Workspace today; the IdP shape fits other OIDC providers with a hosted-domain claim, none tried yet); a single service-account Personal Access Token at the git host holds the only credential that ever touches the API; commits attribute correctly to the editor via git’s author/committer split. Editors save changes without ever creating a GitLab account.

signs inbot tokenEDITORSveltia /admin/no git-host accountWORKERtranslatorOAuth, JWT, proxyGIT HOSTGitLab APIauthor = editor
Editors sign in with their own identity provider, the worker swaps that for one bot token at the git host, and the commit still lands with the editor as author.
TRANSLATOR (WORKER)API callsEDITORSveltia /admin/Workspace accountno git-host account1/oauth/authorize + /callbackverify hd claim, mint 8h JWT2JWT mint (HS256)sub, email, name; 8h expiry3/gitlab/* REST proxyJWT verify → route + allowlist →swap to PAT → inject author_*4/gitlab/graphqlparsed; Sveltia reads only, else 4035synthesized identity/user, users?search from JWTIDENTITY PROVIDERGoogle consentOAuth 2.0 + OIDChd: example.orgGIT HOSTGitLab api/v4single bot PATcommit:author = editorcommitter = bot
Five worker routes sit between the editor's browser and the git host, so the identity provider proves who is editing and one bot token makes every API call.

The default git-backed CMS auth model assumes a 1:1 mapping between editor and git-host user. For schools, nonprofits, and other small orgs whose editors live in their existing IdP and shouldn’t be onboarded onto another platform, that assumption breaks. The translator pattern keeps the git host out of the editor’s day entirely while preserving correct git history attribution.

Highlights

  • A small TypeScript Worker with an offline test suite and CI. Runs on Cloudflare Workers’ free tier.
  • Default-deny: editors.yml lists who may sign in, which repo and paths each may write, the file types allowed under each write root, and the one branch commits may target. Signed OAuth state with PKCE, 8-hour sessions, a fixed REST route table, and GraphQL parsed down to Sveltia’s read queries.
  • createWorker({ editors }) export, so a deployment is a wrangler.toml, an editors.yml and a few lines of index.ts with the translator as a dependency.
  • Smoke harness that exercises OAuth, JWT, REST, GraphQL, and allowlist enforcement against a deployed Worker.
  • Setup walkthrough for Google OAuth, GitLab service account, Cloudflare deploy, and Sveltia config wiring (Sveltia 0.179 or later).
  • MIT licensed. Built in collaboration with Andrew DeJong (@adejong5).

The full architectural reasoning, the load-bearing decisions, and the upstream contribution plan are in Enabling Editors to Use Git Without Knowing.