@vespercms/admin 0.0.0-stage → 0.1.0-next.1

package/src/github/GitHubGate.tsx

@@ -0,0 +1,298 @@
+import { Button } from '@vespercms/ui';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { App } from '../app/App.tsx';
+import type { StudioApi } from '../app/api.ts';
+import type { Account, StudioOptions } from '../types.ts';
+import { createGitHubApi } from './api.ts';
+import { indexedDbCache } from './cache.ts';
+import {
+  finishSignIn,
+  readSession,
+  signOut,
+  startSignIn,
+  type GitHubStudioSettings,
+  type Session,
+} from './session.ts';
+
+/*
+ * GitHub mode's way in (spec §6.8, §6.9): finish a sign-in GitHub sent back
+ * here, check the editor can push to the repository, then the studio with
+ * GitHub as its back end. One primary action per screen (spec §10.4).
+ */
+
+type GateOptions = Omit<StudioOptions, 'api' | 'github' | 'account' | 'cloud'>;
+
+const defaultFetch: typeof fetch = (input, init) => fetch(input, init);
+const noProps = () => Promise.resolve({});
+
+type State =
+  | { kind: 'checking' }
+  | { kind: 'signed-out'; message?: string }
+  | { kind: 'no-access'; login: string }
+  /** GitHub answered 404: most often the site's GitHub App isn't installed on the repository. */
+  | { kind: 'not-found'; login: string }
+  | { kind: 'error'; message: string }
+  | {
+      kind: 'ready';
+      session: Session;
+      login: string;
+      name: string;
+      picture: string;
+      /** The repository is public: a scheduled change can be read there early (spec §6.17). */
+      publicRepository: boolean;
+    };
+
+export function GitHubGate({
+  settings,
+  options,
+  fetcher = defaultFetch,
+}: {
+  settings: GitHubStudioSettings;
+  options: GateOptions;
+  fetcher?: typeof fetch;
+}) {
+  const [state, setState] = useState<State>({ kind: 'checking' });
+  const [expired, setExpired] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+  const apiUrl = (settings.apiUrl ?? 'https://api.github.com').replace(/\/+$/, '');
+
+  useEffect(() => {
+    let live = true;
+    const set = (next: State) => {
+      if (live) setState(next);
+    };
+    void (async () => {
+      const finished = await finishSignIn(settings, fetcher);
+      if (finished && !finished.ok) {
+        set({ kind: 'signed-out', message: finished.message });
+        return;
+      }
+      const session = finished?.session ?? readSession();
+      if (!session) {
+        set({ kind: 'signed-out' });
+        return;
+      }
+      const headers = {
+        Authorization: `Bearer ${session.token}`,
+        Accept: 'application/vnd.github+json',
+      };
+      try {
+        const repo = await fetcher(
+          `${apiUrl}/repos/${encodeURIComponent(settings.owner)}/${encodeURIComponent(settings.repo)}`,
+          { headers },
+        );
+        if (repo.status === 401) {
+          signOut();
+          set({ kind: 'signed-out', message: 'Your GitHub sign-in has expired. Sign in again.' });
+          return;
+        }
+        const user = await fetcher(`${apiUrl}/user`, { headers });
+        const profile = user.ok
+          ? ((await user.json()) as { login?: string; name?: string | null; avatar_url?: string })
+          : {};
+        const login = profile.login ?? '';
+        // A GitHub App's sign-in sees only repositories the app is installed on,
+        // so a 404 isn't the editor's access: blaming it sent an owner to ask
+        // themselves for write access (DECISIONS.md, "GitHub mode tells a missing
+        // install apart from missing access").
+        if (repo.status === 404) {
+          set({ kind: 'not-found', login });
+          return;
+        }
+        if (!repo.ok) {
+          set({
+            kind: 'error',
+            message: `GitHub couldn’t open ${settings.owner}/${settings.repo} just now. Try again in a few minutes.`,
+          });
+          return;
+        }
+        const details = (await repo.json()) as {
+          permissions?: { push?: boolean };
+          private?: boolean;
+        };
+        const permissions = details.permissions;
+        if (!permissions?.push) {
+          set({ kind: 'no-access', login });
+          return;
+        }
+        set({
+          kind: 'ready',
+          session,
+          login,
+          name: profile.name?.trim() || `@${login}`,
+          picture: avatarAt(profile.avatar_url ?? '', 64),
+          publicRepository: details.private === false,
+        });
+      } catch {
+        set({
+          kind: 'error',
+          message: 'GitHub couldn’t be reached. Check the connection and try again.',
+        });
+      }
+    })();
+    return () => {
+      live = false;
+    };
+    // `attempt` reruns the check after "Try again".
+  }, [settings, apiUrl, fetcher, attempt]);
+
+  const signIn = useCallback(() => {
+    void startSignIn(settings, window.location.hash);
+  }, [settings]);
+  const tryAgain = useCallback(() => {
+    setState({ kind: 'checking' });
+    setAttempt((n) => n + 1);
+  }, []);
+  const leave = useCallback(() => {
+    signOut();
+    setExpired(false);
+    setState({ kind: 'signed-out' });
+  }, []);
+
+  const session = state.kind === 'ready' ? state.session : null;
+  // One API per session, so its cache and services last the whole visit.
+  const api = useMemo<StudioApi | null>(
+    () =>
+      session
+        ? createGitHubApi({
+            settings,
+            token: () => session.token,
+            manifest: options.manifest,
+            loadMdxProps: options.loadMdxProps ?? noProps,
+            ...(options.loadUrlFunctions ? { loadUrlFunctions: options.loadUrlFunctions } : {}),
+            ...(options.routes ? { routes: options.routes } : {}),
+            cache: indexedDbCache(),
+            onExpired: () => {
+              setExpired(true);
+            },
+            fetch: fetcher,
+          })
+        : null,
+    [session, settings, options, fetcher],
+  );
+  const account = useMemo<Account | null>(
+    () =>
+      state.kind === 'ready'
+        ? {
+            label: `@${state.login}`,
+            name: state.name,
+            ...(state.picture ? { picture: state.picture } : {}),
+            description: `Signed in to GitHub as @${state.login}`,
+            signOutLabel: 'Sign out of GitHub',
+            signOut: leave,
+            signInAgain: signIn,
+            expired,
+            ...(state.publicRepository ? { publicRepository: true } : {}),
+          }
+        : null,
+    [state, leave, signIn, expired],
+  );
+
+  useEffect(() => {
+    // Signed in, each screen names the page itself.
+    if (state.kind !== 'ready')
+      document.title = `${titleOf(state)} · ${options.siteName ?? 'Vesper'}`;
+  }, [state, options.siteName]);
+
+  if (api && account) return <App {...options} api={api} account={account} />;
+
+  const repo = `${settings.owner}/${settings.repo}`;
+  return (
+    <div className="afterglow min-h-screen">
+      <main id="main" className="mx-auto flex max-w-2xl flex-col gap-4 px-4 py-16">
+        <h1 className="text-heading-1 text-content">{titleOf(state)}</h1>
+        {state.kind === 'checking' && (
+          <p role="status" className="text-content-muted">
+            Opening the studio…
+          </p>
+        )}
+        {state.kind === 'signed-out' && (
+          <>
+            {state.message && (
+              <p role="alert" className="rounded-md border border-danger bg-surface-raised p-4">
+                {state.message}
+              </p>
+            )}
+            <p>You’ll publish to {repo} on GitHub. Changes go live after the site rebuilds.</p>
+            <div>
+              <Button variant="primary" onPress={signIn}>
+                Sign in with GitHub
+              </Button>
+            </div>
+          </>
+        )}
+        {state.kind === 'no-access' && (
+          <>
+            <p>
+              {state.login ? `You’re signed in to GitHub as @${state.login}. ` : ''}Ask the site’s
+              owner to give your account write access to {repo}.
+            </p>
+            <div>
+              <Button onPress={leave}>Sign out of GitHub</Button>
+            </div>
+          </>
+        )}
+        {state.kind === 'not-found' && (
+          <>
+            <p>
+              {state.login ? `You’re signed in to GitHub as @${state.login}. ` : ''}The site’s
+              GitHub App may not be installed on {repo}, or your account may not be able to see it.
+            </p>
+            <p>
+              The site’s owner installs the app from its settings on GitHub, under Install App, then
+              tries again here. If it’s installed already, ask the owner to give your account write
+              access to {repo}.
+            </p>
+            <div className="flex flex-wrap gap-3">
+              <Button variant="primary" onPress={tryAgain}>
+                Try again
+              </Button>
+              <Button onPress={leave}>Sign out of GitHub</Button>
+            </div>
+          </>
+        )}
+        {state.kind === 'error' && (
+          <>
+            <p role="alert">{state.message}</p>
+            <div>
+              <Button variant="primary" onPress={tryAgain}>
+                Try again
+              </Button>
+            </div>
+          </>
+        )}
+      </main>
+    </div>
+  );
+}
+
+function titleOf(state: State): string {
+  switch (state.kind) {
+    case 'checking':
+      return 'Opening the studio';
+    case 'no-access':
+      return 'Your GitHub account can’t change this site';
+    case 'not-found':
+      return 'GitHub can’t find this site’s repository';
+    case 'error':
+      return 'GitHub couldn’t be reached';
+    default:
+      return 'Sign in to edit this site';
+  }
+}
+
+/**
+ * GitHub's picture at a size (`s`), or nothing when GitHub gave no address.
+ * It loads from GitHub's image host, which GitHub mode already trusts with
+ * every read and save (DECISIONS.md, "GitHub mode loads the editor's picture from GitHub").
+ */
+export function avatarAt(address: string, size: number): string {
+  if (!address) return '';
+  try {
+    const url = new URL(address);
+    url.searchParams.set('s', String(size));
+    return url.href;
+  } catch {
+    return '';
+  }
+}

package/src/github/api.ts

@@ -0,0 +1,81 @@
+import {
+  GitHubError,
+  GitHubStorage,
+  type BlobCache,
+  type Manifest,
+  type UrlEntry,
+} from '@vespercms/core';
+import { ApiError, type StudioApi } from '../app/api.ts';
+import { createBrowserApi } from '../app/browser-api.ts';
+import type { GitHubStudioSettings } from './session.ts';
+
+/*
+ * GitHub mode's back end (spec §6.8): core's services in the browser over
+ * the repository's branch (app/browser-api.ts). Every save is a commit.
+ */
+
+export type GitHubApiOptions = {
+  settings: GitHubStudioSettings;
+  /** The current token. */
+  token: () => string;
+  manifest: Manifest;
+  loadMdxProps: () => Promise<Readonly<Record<string, unknown>>>;
+  loadUrlFunctions?: () => Promise<Readonly<Record<string, (entry: UrlEntry) => unknown>>>;
+  /** The site's static routes at build, for collision checks. */
+  routes?: readonly (readonly [string, string])[];
+  cache?: BlobCache;
+  /** Called when GitHub says the sign-in has expired. */
+  onExpired?: () => void;
+  fetch?: typeof fetch;
+};
+
+export function createGitHubApi(options: GitHubApiOptions): StudioApi {
+  const { settings } = options;
+  const storage = new GitHubStorage({
+    owner: settings.owner,
+    repo: settings.repo,
+    branch: settings.branch,
+    root: settings.root,
+    token: options.token,
+    ...(settings.apiUrl ? { apiUrl: settings.apiUrl } : {}),
+    ...(options.cache ? { cache: options.cache } : {}),
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+  });
+  return createBrowserApi({
+    storage,
+    manifest: options.manifest,
+    schemas: settings.schemas,
+    loadMdxProps: options.loadMdxProps,
+    ...(options.loadUrlFunctions ? { loadUrlFunctions: options.loadUrlFunctions } : {}),
+    ...(options.routes ? { routes: options.routes } : {}),
+    publishesOnSave: true,
+    mapError: (error) => apiError(error, options.onExpired),
+  });
+}
+
+/** GitHub's errors as the studio shows them: plain words, and a status the screens understand. */
+export function apiError(error: unknown, onExpired?: () => void): unknown {
+  if (!(error instanceof GitHubError)) return error;
+  switch (error.kind) {
+    case 'auth':
+      onExpired?.();
+      return new ApiError(401, 'Your GitHub sign-in has expired. Sign in again to publish.');
+    case 'rate-limit':
+      return new ApiError(
+        429,
+        error.retryAt
+          ? `GitHub asked the studio to slow down. Try again after ${error.retryAt.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}.`
+          : 'GitHub asked the studio to slow down. Try again in a few minutes.',
+      );
+    case 'network':
+      return new ApiError(0, error.message);
+    case 'forbidden':
+    case 'not-found':
+      return new ApiError(
+        error.status,
+        'Your GitHub account can’t reach this site’s repository. Ask its owner to add you.',
+      );
+    default:
+      return new ApiError(502, 'GitHub had a problem. Try again in a moment.');
+  }
+}

package/src/github/cache.ts

@@ -0,0 +1,64 @@
+import type { BlobCache } from '@vespercms/core';
+
+/*
+ * File bytes by git blob SHA, kept in IndexedDB between visits. A SHA always
+ * means the same bytes, so nothing here ever goes stale: a later visit reads
+ * from GitHub only the files that changed. Without IndexedDB (a private
+ * window, blocked storage) it quietly does nothing.
+ */
+
+const DB = 'vesper-github';
+const STORE = 'blobs';
+
+export function indexedDbCache(): BlobCache {
+  let opened: Promise<IDBDatabase | null> | null = null;
+  const open = () => {
+    opened ??= new Promise((resolve) => {
+      try {
+        const request = indexedDB.open(DB, 1);
+        request.onupgradeneeded = () => {
+          request.result.createObjectStore(STORE);
+        };
+        request.onsuccess = () => {
+          resolve(request.result);
+        };
+        request.onerror = () => {
+          resolve(null);
+        };
+      } catch {
+        resolve(null);
+      }
+    });
+    return opened;
+  };
+  const run = <T>(mode: IDBTransactionMode, act: (store: IDBObjectStore) => IDBRequest<T>) =>
+    open().then(
+      (db) =>
+        new Promise<T | undefined>((resolve) => {
+          if (!db) {
+            resolve(undefined);
+            return;
+          }
+          try {
+            const request = act(db.transaction(STORE, mode).objectStore(STORE));
+            request.onsuccess = () => {
+              resolve(request.result);
+            };
+            request.onerror = () => {
+              resolve(undefined);
+            };
+          } catch {
+            resolve(undefined);
+          }
+        }),
+    );
+  return {
+    get: async (sha) => {
+      const found = await run<unknown>('readonly', (store) => store.get(sha));
+      return found instanceof Uint8Array ? found : undefined;
+    },
+    put: async (sha, bytes) => {
+      await run('readwrite', (store) => store.put(bytes, sha));
+    },
+  };
+}

package/src/github/session.ts

@@ -0,0 +1,146 @@
+/*
+ * Signing in with GitHub (spec §6.8, §6.9): a top-level redirect through the
+ * site's OAuth relay, with PKCE, and no popup or third-party cookie (D14).
+ *
+ * 1. The studio keeps a random state and a PKCE verifier in sessionStorage
+ *    and goes to the relay's /authorize with the code challenge.
+ * 2. The relay sends the browser to GitHub, and back here with
+ *    `?github=<code>&state=<state>`. The code is useless without the
+ *    verifier, which never left this tab.
+ * 3. The studio posts the code and verifier to the relay's /token, which
+ *    adds the app's secret and answers with an 8-hour token.
+ *
+ * Only that token is kept, in sessionStorage: it's gone when the tab closes,
+ * and signing in again is one redirect, since GitHub remembers the approval
+ * (DECISIONS.md, "GitHub mode keeps its token in sessionStorage").
+ */
+
+/** GitHub mode's settings, as the build writes them into the studio. */
+export type GitHubStudioSettings = {
+  owner: string;
+  repo: string;
+  branch: string;
+  /** The site's folder inside the repository. */
+  root: string;
+  /** The OAuth relay's address. */
+  relay: string;
+  /** GitHub Enterprise Server's API, or a test double; GitHub's own when absent. */
+  apiUrl?: string;
+  /** The site's schemas built for the browser. */
+  schemas: string;
+};
+
+export type Session = { token: string; expiresAt: number };
+
+const SESSION_KEY = 'vesper.github.session';
+const PENDING_KEY = 'vesper.github.pending';
+/** A token this close to expiring is treated as expired, so a save never starts on one. */
+const MARGIN_MS = 5 * 60 * 1000;
+
+type Pending = { state: string; verifier: string; route: string };
+
+function storage(): Storage | null {
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function readSession(): Session | null {
+  try {
+    const raw = storage()?.getItem(SESSION_KEY);
+    const session = raw ? (JSON.parse(raw) as Partial<Session>) : null;
+    if (typeof session?.token !== 'string' || typeof session.expiresAt !== 'number') return null;
+    return session.expiresAt - MARGIN_MS > Date.now() ? (session as Session) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function signOut(): void {
+  storage()?.removeItem(SESSION_KEY);
+}
+
+const base64url = (bytes: Uint8Array) =>
+  btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+const random = (size: number) => base64url(crypto.getRandomValues(new Uint8Array(size)));
+
+/** Goes to the relay, then GitHub. `route` is the studio's hash route to come back to. */
+export async function startSignIn(settings: GitHubStudioSettings, route: string): Promise<void> {
+  const state = random(16);
+  const verifier = random(32);
+  const challenge = base64url(
+    new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))),
+  );
+  storage()?.setItem(PENDING_KEY, JSON.stringify({ state, verifier, route } satisfies Pending));
+  const back = `${window.location.origin}${window.location.pathname}`;
+  const url = new URL(`${settings.relay}/authorize`);
+  url.searchParams.set('return', back);
+  url.searchParams.set('state', state);
+  url.searchParams.set('code_challenge', challenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  window.location.assign(url.href);
+}
+
+export type Finished =
+  { ok: true; session: Session; route: string } | { ok: false; message: string };
+
+/**
+ * Finishes a sign-in when GitHub sent the browser back here, or returns
+ * null when it didn't. The code leaves the address either way.
+ */
+export async function finishSignIn(
+  settings: GitHubStudioSettings,
+  fetcher: typeof fetch = (input, init) => fetch(input, init),
+): Promise<Finished | null> {
+  const params = new URLSearchParams(window.location.search);
+  const code = params.get('github');
+  const error = params.get('github_error');
+  if (code === null && error === null) return null;
+  const pendingRaw = storage()?.getItem(PENDING_KEY);
+  storage()?.removeItem(PENDING_KEY);
+  const pending = pendingRaw ? (JSON.parse(pendingRaw) as Pending) : null;
+  const route = pending?.route ?? '';
+  history.replaceState(history.state, '', `${window.location.pathname}${route}`);
+  if (error !== null) {
+    return {
+      ok: false,
+      message:
+        error === 'access_denied'
+          ? 'GitHub sign-in was cancelled.'
+          : 'GitHub didn’t sign you in. Try again.',
+    };
+  }
+  if (!pending || pending.state !== params.get('state')) {
+    return { ok: false, message: 'That sign-in didn’t start here. Try again.' };
+  }
+  let response: Response;
+  try {
+    response = await fetcher(`${settings.relay}/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ code, code_verifier: pending.verifier }),
+    });
+  } catch {
+    return { ok: false, message: 'The sign-in service couldn’t be reached. Try again.' };
+  }
+  const body = (await response.json().catch(() => ({}))) as {
+    token?: string;
+    expiresIn?: number;
+    message?: string;
+  };
+  if (!response.ok || typeof body.token !== 'string') {
+    return { ok: false, message: body.message ?? 'GitHub didn’t sign you in. Try again.' };
+  }
+  const session = {
+    token: body.token,
+    expiresAt: Date.now() + (body.expiresIn ?? 8 * 60 * 60) * 1000,
+  };
+  storage()?.setItem(SESSION_KEY, JSON.stringify(session));
+  return { ok: true, session, route };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/*
+ * The Vesper studio (spec §6.1): the editor served at /admin. One bundle for
+ * every storage mode; the page that mounts it passes the manifest, the back
+ * end and the site's custom widgets.
+ *
+ * The stylesheet is a separate export: import '@vespercms/admin/studio.css'.
+ */
+export { mountStudio } from './mount.tsx';
+export { createLocalApi, ApiError, STUDIO_HEADER, type StudioApi } from './app/api.ts';
+export type { StudioOptions, WidgetProps, WidgetComponent, WidgetLoader } from './types.ts';