uncial-cms-auth 0.0.0

package/README.md

@@ -0,0 +1,108 @@
+# uncial-cms-auth
+
+A stateless Cloudflare Worker that turns a GitHub OAuth sign-in into a
+**single-repo-scoped GitHub App installation token** for
+[uncial-cms](../uncial-cms). No KV, no database, no sessions: all
+cross-request state rides in an HMAC-signed `state` value.
+
+The project runs a **canonical hosted instance** at
+`https://uncial-cms-auth.dflood.workers.dev` — point your site config's
+`authWorkerUrl` at it and no deployment is needed. Self-hosting is equally
+first-class (see below); the `uncial-cms` runtime accepts any `authWorkerUrl`.
+
+## What it guarantees
+
+- The user's OAuth token is used server-side only and is never sent to the
+  browser.
+- A token is released only if the authenticated user has **push** permission
+  on the claimed repository **and** the initiating origin is listed in that
+  repository's committed allowlist (see below).
+- The token the browser receives is a GitHub App installation access token
+  restricted to that one repository with contents read/write only (~1 hour
+  expiry).
+
+## Endpoints
+
+The canonical instance serves these at
+`https://uncial-cms-auth.dflood.workers.dev`; a self-hosted worker serves them
+at its own `*.workers.dev` (or custom) domain.
+
+- `GET /auth?repo=<owner/name>&origin=<origin>&challenge=<S256-challenge>` —
+  validates the parameters, issues a signed `state`, and redirects to GitHub's
+  authorize page (PKCE S256).
+- `GET /callback?code&state` — static relay page that `postMessage`s
+  `{ code, state }` to `window.opener` at exactly the origin recovered from
+  the verified `state`, then closes.
+- `POST /token` `{ code, state, verifier }` — verifies the state and PKCE
+  verifier, exchanges the code server-side, runs the permission and allowlist
+  checks, and responds `{ token, expiresAt, repo, user }`. The
+  `Access-Control-Allow-Origin` header echoes the state's origin only.
+
+Refusals are distinct 4xx responses with a machine-readable
+`{ "error": "<code>" }` body: `invalid_repo`, `invalid_origin`,
+`invalid_challenge`, `invalid_request`, `invalid_state`, `stale_state`,
+`invalid_verifier`, `code_exchange_failed`, `no_push_permission`,
+`app_not_installed`, `missing_allowlist`, `origin_not_allowed`.
+
+## Registering a site (site owners)
+
+There is no registration UI. Commit an allowlist file to your repository's
+default branch:
+
+```json
+// .uncial/cms.json
+{ "allowedOrigins": ["https://example.com", "http://localhost:5173"] }
+```
+
+Anyone with push access can edit this file; protect it with branch protection
+if that matters to you. Note that on shared-origin hosts (e.g.
+`<user>.github.io` project pages) allowlisting the origin authorizes every
+site served from it — a custom domain restores per-site granularity.
+
+Then install the GitHub App on the repository (the `appSlug` in your site
+config links editors to the install page).
+
+## Self-hosting
+
+The canonical instance is hosted by the project, but self-hosting is
+first-class — the `uncial-cms` runtime accepts any `authWorkerUrl`.
+
+1. **Create a GitHub App** (Settings → Developer settings → GitHub Apps):
+   - Repository permissions: **Contents: Read and write**. Nothing else.
+   - Webhooks: disabled.
+   - Callback URL: `https://<your-worker-domain>/callback`.
+   - "Request user authorization (OAuth) during installation" is not
+     required; editors authorize on first sign-in.
+   - Generate a **client secret** and a **private key**.
+2. **Convert the private key to PKCS#8** (GitHub downloads PKCS#1, which
+   WebCrypto cannot import):
+
+   ```sh
+   openssl pkcs8 -topk8 -nocrypt -in app.private-key.pem -out app.pkcs8.pem
+   ```
+
+3. **Set the five secrets** (names are the contract):
+
+   ```sh
+   wrangler secret put GITHUB_APP_ID
+   wrangler secret put GITHUB_APP_PRIVATE_KEY   # paste the PKCS#8 PEM
+   wrangler secret put GITHUB_CLIENT_ID
+   wrangler secret put GITHUB_CLIENT_SECRET
+   wrangler secret put STATE_SIGNING_SECRET     # any long random string
+   ```
+
+4. **Deploy:**
+
+   ```sh
+   wrangler deploy
+   ```
+
+Point your site config's `authWorkerUrl` at the worker and set `appSlug` to
+your GitHub App's slug.
+
+## Development
+
+```sh
+pnpm run test    # vitest, GitHub API fully mocked
+pnpm run check   # tsc --noEmit
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "uncial-cms-auth",
+	"version": "0.0.0",
+	"license": "MIT",
+	"description": "Stateless Cloudflare Worker that exchanges a GitHub OAuth dance for a single-repo-scoped GitHub App installation token, for uncial-cms.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/d-flood/uncial.git"
+	},
+	"bugs": {
+		"url": "https://github.com/d-flood/uncial/issues"
+	},
+	"homepage": "https://d-flood.github.io/uncial/",
+	"type": "module",
+	"files": [
+		"src",
+		"wrangler.jsonc",
+		"!src/**/*.spec.*"
+	],
+	"scripts": {
+		"check": "tsc --noEmit",
+		"test": "vitest",
+		"deploy": "wrangler deploy"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20250620.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.18",
+		"wrangler": "^4.0.0"
+	},
+	"keywords": [
+		"cloudflare-worker",
+		"github-app",
+		"oauth",
+		"cms"
+	]
+}

package/src/encoding.ts

@@ -0,0 +1,27 @@
+const encoder = new TextEncoder();
+
+export function utf8(value: string): Uint8Array {
+	return encoder.encode(value);
+}
+
+export function base64UrlEncode(bytes: Uint8Array | ArrayBuffer): string {
+	const view = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+	let binary = '';
+	for (const byte of view) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+
+export function base64UrlDecode(value: string): Uint8Array {
+	const padded = value.replaceAll('-', '+').replaceAll('_', '/');
+	const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+	return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+
+export async function sha256Base64Url(value: string): Promise<string> {
+	return base64UrlEncode(await crypto.subtle.digest('SHA-256', utf8(value)));
+}
+
+export function pemToBytes(pem: string): Uint8Array {
+	const body = pem.replace(/-----(BEGIN|END)[A-Z ]+-----/g, '').replace(/\s+/g, '');
+	return Uint8Array.from(atob(body), (char) => char.charCodeAt(0));
+}

package/src/github.ts

@@ -0,0 +1,150 @@
+import { appJwt } from './jwt.js';
+
+export const GITHUB_OAUTH_URL = 'https://github.com';
+export const GITHUB_API_URL = 'https://api.github.com';
+
+export interface Env {
+	GITHUB_APP_ID: string;
+	GITHUB_APP_PRIVATE_KEY: string;
+	GITHUB_CLIENT_ID: string;
+	GITHUB_CLIENT_SECRET: string;
+	STATE_SIGNING_SECRET: string;
+}
+
+/** Thrown by GitHub calls; the handler maps `code` to a 4xx/5xx `{error}` body. */
+export class RefusalError extends Error {
+	constructor(
+		public readonly code: string,
+		public readonly status: number
+	) {
+		super(code);
+	}
+}
+
+function apiHeaders(token: string, scheme: 'Bearer' = 'Bearer'): HeadersInit {
+	return {
+		Accept: 'application/vnd.github+json',
+		Authorization: `${scheme} ${token}`,
+		'X-GitHub-Api-Version': '2022-11-28',
+		'User-Agent': 'uncial-cms-auth'
+	};
+}
+
+/**
+ * Exchanges the OAuth code (+ client secret + PKCE verifier) for the user's
+ * token. The returned token is used server-side only and must never appear in
+ * any response (ticket invariant 1).
+ */
+export async function exchangeCode(
+	env: Env,
+	code: string,
+	verifier: string,
+	redirectUri: string
+): Promise<string> {
+	const response = await fetch(`${GITHUB_OAUTH_URL}/login/oauth/access_token`, {
+		method: 'POST',
+		headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+		body: JSON.stringify({
+			client_id: env.GITHUB_CLIENT_ID,
+			client_secret: env.GITHUB_CLIENT_SECRET,
+			code,
+			code_verifier: verifier,
+			redirect_uri: redirectUri
+		})
+	});
+	const body = (await response.json().catch(() => ({}))) as {
+		access_token?: string;
+		error?: string;
+	};
+	if (!response.ok || !body.access_token) throw new RefusalError('code_exchange_failed', 400);
+	return body.access_token;
+}
+
+export interface GitHubUser {
+	login: string;
+	id: number;
+	name: string | null;
+}
+
+export async function fetchUser(userToken: string): Promise<GitHubUser> {
+	const response = await fetch(`${GITHUB_API_URL}/user`, { headers: apiHeaders(userToken) });
+	if (!response.ok) throw new RefusalError('code_exchange_failed', 400);
+	return (await response.json()) as GitHubUser;
+}
+
+/** Ticket invariant 2a: the authenticated user must have push on the claimed repo. */
+export async function assertPushPermission(
+	userToken: string,
+	repo: string,
+	login: string
+): Promise<void> {
+	const response = await fetch(
+		`${GITHUB_API_URL}/repos/${repo}/collaborators/${encodeURIComponent(login)}/permission`,
+		{ headers: apiHeaders(userToken) }
+	);
+	if (!response.ok) throw new RefusalError('no_push_permission', 403);
+	const body = (await response.json()) as {
+		permission?: string;
+		user?: { permissions?: { push?: boolean } };
+	};
+	const canPush =
+		body.user?.permissions?.push === true ||
+		body.permission === 'admin' ||
+		body.permission === 'write';
+	if (!canPush) throw new RefusalError('no_push_permission', 403);
+}
+
+/**
+ * Ticket invariant 3: mints an installation access token restricted to the one
+ * claimed repository with contents read/write only.
+ */
+export async function mintScopedToken(
+	env: Env,
+	repo: string
+): Promise<{ token: string; expiresAt: number }> {
+	const jwt = await appJwt(env.GITHUB_APP_ID, env.GITHUB_APP_PRIVATE_KEY);
+
+	const installation = await fetch(`${GITHUB_API_URL}/repos/${repo}/installation`, {
+		headers: apiHeaders(jwt)
+	});
+	if (!installation.ok) throw new RefusalError('app_not_installed', 403);
+	const { id } = (await installation.json()) as { id: number };
+
+	const [, name] = repo.split('/');
+	const minted = await fetch(`${GITHUB_API_URL}/app/installations/${id}/access_tokens`, {
+		method: 'POST',
+		headers: { ...apiHeaders(jwt), 'Content-Type': 'application/json' },
+		body: JSON.stringify({ repositories: [name], permissions: { contents: 'write' } })
+	});
+	if (!minted.ok) throw new RefusalError('token_mint_failed', 502);
+	const body = (await minted.json()) as { token: string; expires_at: string };
+	return { token: body.token, expiresAt: Date.parse(body.expires_at) };
+}
+
+/**
+ * Ticket invariant 2b: `.uncial/cms.json` on the repo's default branch must
+ * list the initiating origin. Read server-to-server with the worker's own
+ * installation token — which is only released to the browser if this passes.
+ */
+export async function assertOriginAllowed(
+	installationToken: string,
+	repo: string,
+	origin: string
+): Promise<void> {
+	const response = await fetch(`${GITHUB_API_URL}/repos/${repo}/contents/.uncial/cms.json`, {
+		headers: apiHeaders(installationToken)
+	});
+	if (!response.ok) throw new RefusalError('missing_allowlist', 403);
+
+	let allowedOrigins: unknown;
+	try {
+		const file = (await response.json()) as { content?: string };
+		const decoded = atob((file.content ?? '').replace(/\s+/g, ''));
+		allowedOrigins = (JSON.parse(decoded) as { allowedOrigins?: unknown }).allowedOrigins;
+	} catch {
+		throw new RefusalError('missing_allowlist', 403);
+	}
+	if (!Array.isArray(allowedOrigins) || !allowedOrigins.includes(origin)) {
+		throw new RefusalError('origin_not_allowed', 403);
+	}
+}

package/src/index.ts

@@ -0,0 +1,183 @@
+import { sha256Base64Url } from './encoding.js';
+import {
+	assertOriginAllowed,
+	assertPushPermission,
+	exchangeCode,
+	fetchUser,
+	GITHUB_OAUTH_URL,
+	mintScopedToken,
+	RefusalError,
+	type Env
+} from './github.js';
+import { signState, verifyState } from './state.js';
+
+const STATE_MAX_AGE_MS = 10 * 60 * 1000;
+const REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+// 43 chars = base64url of 32 bytes; RFC 7636 allows 43–128 for the verifier,
+// and an S256 challenge is always exactly 43.
+const CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+function json(status: number, body: unknown, headers: HeadersInit = {}): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json', ...headers }
+	});
+}
+
+function refusal(status: number, error: string, corsOrigin?: string): Response {
+	return json(
+		status,
+		{ error },
+		corsOrigin ? { 'Access-Control-Allow-Origin': corsOrigin, Vary: 'Origin' } : {}
+	);
+}
+
+function isWebOrigin(value: string): boolean {
+	try {
+		return new URL(value).origin === value;
+	} catch {
+		return false;
+	}
+}
+
+function handleAuth(request: Request, env: Env): Promise<Response> {
+	const url = new URL(request.url);
+	const repo = url.searchParams.get('repo') ?? '';
+	const origin = url.searchParams.get('origin') ?? '';
+	const challenge = url.searchParams.get('challenge') ?? '';
+
+	if (!REPO_PATTERN.test(repo)) return Promise.resolve(refusal(400, 'invalid_repo'));
+	if (!isWebOrigin(origin)) return Promise.resolve(refusal(400, 'invalid_origin'));
+	if (!CHALLENGE_PATTERN.test(challenge)) return Promise.resolve(refusal(400, 'invalid_challenge'));
+
+	return signState({ repo, origin, challenge, iat: Date.now() }, env.STATE_SIGNING_SECRET).then(
+		(state) => {
+			const authorize = new URL(`${GITHUB_OAUTH_URL}/login/oauth/authorize`);
+			authorize.searchParams.set('client_id', env.GITHUB_CLIENT_ID);
+			authorize.searchParams.set('redirect_uri', new URL('/callback', url).toString());
+			authorize.searchParams.set('state', state);
+			authorize.searchParams.set('code_challenge', challenge);
+			authorize.searchParams.set('code_challenge_method', 'S256');
+			return Response.redirect(authorize.toString(), 302);
+		}
+	);
+}
+
+function errorPage(status: number, message: string): Response {
+	return new Response(
+		`<!doctype html><meta charset="utf-8"><title>uncial-cms sign-in</title><p>${message}</p>`,
+		{ status, headers: { 'Content-Type': 'text/html; charset=utf-8' } }
+	);
+}
+
+/**
+ * Static relay: hands {code, state} back to the opener at exactly the origin
+ * recovered from the verified state — the PKCE verifier never left the
+ * browser, so only that opener can finish the exchange at /token.
+ */
+async function handleCallback(request: Request, env: Env): Promise<Response> {
+	const url = new URL(request.url);
+	const code = url.searchParams.get('code');
+	const state = url.searchParams.get('state');
+	if (!code || !state) {
+		return errorPage(400, 'GitHub did not complete the sign-in. You can close this window.');
+	}
+
+	const payload = await verifyState(state, env.STATE_SIGNING_SECRET);
+	if (!payload) return errorPage(400, 'Invalid sign-in state. You can close this window.');
+
+	// JSON.stringify + `<` escaping keeps the embedded values inert in HTML.
+	const message = JSON.stringify({ source: 'uncial-cms-auth', code, state }).replaceAll(
+		'<',
+		'\\u003c'
+	);
+	const target = JSON.stringify(payload.origin).replaceAll('<', '\\u003c');
+	return new Response(
+		`<!doctype html><meta charset="utf-8"><title>uncial-cms sign-in</title>` +
+			`<p>Completing sign-in… you can close this window.</p>` +
+			`<script>window.opener?.postMessage(${message}, ${target});window.close();</script>`,
+		{ headers: { 'Content-Type': 'text/html; charset=utf-8' } }
+	);
+}
+
+async function handleToken(request: Request, env: Env): Promise<Response> {
+	const requestOrigin = request.headers.get('Origin') ?? '';
+
+	let body: { code?: unknown; state?: unknown; verifier?: unknown };
+	try {
+		body = (await request.json()) as typeof body;
+	} catch {
+		return refusal(400, 'invalid_request', requestOrigin);
+	}
+	const { code, state, verifier } = body;
+	if (typeof code !== 'string' || typeof state !== 'string' || typeof verifier !== 'string') {
+		return refusal(400, 'invalid_request', requestOrigin);
+	}
+
+	const payload = await verifyState(state, env.STATE_SIGNING_SECRET);
+	if (!payload) return refusal(400, 'invalid_state', requestOrigin);
+	// CORS: every response past this point is addressed to the state's origin
+	// only — never `*`, never the caller's own Origin header.
+	const cors = payload.origin;
+
+	if (Date.now() - payload.iat > STATE_MAX_AGE_MS) return refusal(400, 'stale_state', cors);
+	if ((await sha256Base64Url(verifier)) !== payload.challenge) {
+		return refusal(400, 'invalid_verifier', cors);
+	}
+
+	try {
+		const redirectUri = new URL('/callback', request.url).toString();
+		const userToken = await exchangeCode(env, code, verifier, redirectUri);
+		const user = await fetchUser(userToken);
+		await assertPushPermission(userToken, payload.repo, user.login);
+
+		const scoped = await mintScopedToken(env, payload.repo);
+		await assertOriginAllowed(scoped.token, payload.repo, payload.origin);
+
+		return json(
+			200,
+			{
+				token: scoped.token,
+				expiresAt: scoped.expiresAt,
+				repo: payload.repo,
+				user: {
+					login: user.login,
+					name: user.name ?? user.login,
+					email: `${user.id}+${user.login}@users.noreply.github.com`
+				}
+			},
+			{ 'Access-Control-Allow-Origin': cors, Vary: 'Origin' }
+		);
+	} catch (error) {
+		if (error instanceof RefusalError) return refusal(error.status, error.code, cors);
+		return refusal(502, 'github_unreachable', cors);
+	}
+}
+
+function handleTokenPreflight(request: Request): Response {
+	// The preflight only gates whether the POST may be *sent*; the response the
+	// page can actually read is still bound to the verified state origin.
+	return new Response(null, {
+		status: 204,
+		headers: {
+			'Access-Control-Allow-Origin': request.headers.get('Origin') ?? '*',
+			'Access-Control-Allow-Methods': 'POST',
+			'Access-Control-Allow-Headers': 'Content-Type',
+			'Access-Control-Max-Age': '86400',
+			Vary: 'Origin'
+		}
+	});
+}
+
+export default {
+	async fetch(request: Request, env: Env): Promise<Response> {
+		const { pathname } = new URL(request.url);
+		if (pathname === '/auth' && request.method === 'GET') return handleAuth(request, env);
+		if (pathname === '/callback' && request.method === 'GET') return handleCallback(request, env);
+		if (pathname === '/token' && request.method === 'POST') return handleToken(request, env);
+		if (pathname === '/token' && request.method === 'OPTIONS') {
+			return handleTokenPreflight(request);
+		}
+		return json(404, { error: 'not_found' });
+	}
+};

package/src/jwt.ts

@@ -0,0 +1,30 @@
+import { base64UrlEncode, pemToBytes, utf8 } from './encoding.js';
+
+/**
+ * GitHub App JWT (RS256), used for app-to-server calls: resolving the repo's
+ * installation and minting the scoped installation token. The private key must
+ * be PKCS#8 PEM (WebCrypto cannot import GitHub's default PKCS#1 download;
+ * convert once with `openssl pkcs8 -topk8 -nocrypt` — see the README).
+ */
+export async function appJwt(appId: string, privateKeyPem: string): Promise<string> {
+	const key = await crypto.subtle.importKey(
+		'pkcs8',
+		pemToBytes(privateKeyPem),
+		{ name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+		false,
+		['sign']
+	);
+
+	const now = Math.floor(Date.now() / 1000);
+	const header = base64UrlEncode(utf8(JSON.stringify({ alg: 'RS256', typ: 'JWT' })));
+	// iat backdated 60s for clock drift; 9-minute expiry (GitHub caps at 10).
+	const payload = base64UrlEncode(
+		utf8(JSON.stringify({ iat: now - 60, exp: now + 540, iss: appId }))
+	);
+	const signature = await crypto.subtle.sign(
+		'RSASSA-PKCS1-v1_5',
+		key,
+		utf8(`${header}.${payload}`)
+	);
+	return `${header}.${payload}.${base64UrlEncode(signature)}`;
+}

package/src/state.ts

@@ -0,0 +1,56 @@
+import { base64UrlDecode, base64UrlEncode, utf8 } from './encoding.js';
+
+/**
+ * Cross-request state for the stateless worker (spec D4 / ticket invariant 4):
+ * everything the /token step must trust — repo, origin, PKCE challenge, issue
+ * time — rides in an HMAC-SHA256-signed value the worker itself minted.
+ */
+export interface StatePayload {
+	repo: string; // 'owner/name'
+	origin: string; // initiating site origin
+	challenge: string; // PKCE S256 challenge (base64url)
+	iat: number; // epoch ms
+}
+
+async function hmacKey(secret: string, usage: 'sign' | 'verify'): Promise<CryptoKey> {
+	return crypto.subtle.importKey('raw', utf8(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [
+		usage
+	]);
+}
+
+export async function signState(payload: StatePayload, secret: string): Promise<string> {
+	const body = base64UrlEncode(utf8(JSON.stringify(payload)));
+	const signature = await crypto.subtle.sign('HMAC', await hmacKey(secret, 'sign'), utf8(body));
+	return `${body}.${base64UrlEncode(signature)}`;
+}
+
+export async function verifyState(state: string, secret: string): Promise<StatePayload | null> {
+	const [body, signature, ...rest] = state.split('.');
+	if (!body || !signature || rest.length > 0) return null;
+
+	let valid: boolean;
+	let payload: unknown;
+	try {
+		valid = await crypto.subtle.verify(
+			'HMAC',
+			await hmacKey(secret, 'verify'),
+			base64UrlDecode(signature),
+			utf8(body)
+		);
+		payload = JSON.parse(new TextDecoder().decode(base64UrlDecode(body)));
+	} catch {
+		return null;
+	}
+	if (!valid || typeof payload !== 'object' || payload === null) return null;
+
+	const { repo, origin, challenge, iat } = payload as Partial<StatePayload>;
+	if (
+		typeof repo !== 'string' ||
+		typeof origin !== 'string' ||
+		typeof challenge !== 'string' ||
+		typeof iat !== 'number'
+	) {
+		return null;
+	}
+	return { repo, origin, challenge, iat };
+}

package/wrangler.jsonc

@@ -0,0 +1,9 @@
+{
+	"$schema": "node_modules/wrangler/config-schema.json",
+	"name": "uncial-cms-auth",
+	"main": "src/index.ts",
+	"compatibility_date": "2026-06-01"
+	// Secrets (set with `wrangler secret put <NAME>`):
+	//   GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_CLIENT_ID,
+	//   GITHUB_CLIENT_SECRET, STATE_SIGNING_SECRET
+}