@playrunner/github 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,10 @@
 
 GitHub authentication and repository access for Playrunner workflows.
 
+[![npm version](https://img.shields.io/npm/v/@playrunner/github.svg)](https://www.npmjs.com/package/@playrunner/github)
+
+[View source on GitHub](https://github.com/playrunner/playrunner/tree/main/packages/github)
+
 ## Install
 
 ```bash
@@ -14,6 +18,7 @@ Add the package as a direct production dependency of the Playrunner frontend and
 
 - `@playrunner/github` exports the GitHub integration, icon, and settings UI.
 - `@playrunner/github/api` exports token exchange and refresh API routes.
+- `@playrunner/github/e2e` exports the package-owned E2E contribution.
 - `@playrunner/github/assets/github.svg` exports the package-owned icon.
 
 ```ts
@@ -21,6 +26,22 @@ import githubIntegration, { GithubSettingsModal } from '@playrunner/github';
 import githubApiContribution from '@playrunner/github/api';
 ```
 
+## Testing
+
+Run the package checks from the repository root:
+
+```bash
+npm run format:check --prefix packages/github
+npm run lint --prefix packages/github
+npm run typecheck --prefix packages/github
+npm run test:e2e:mock -- --grep @github
+```
+
+The E2E scenario validates the GitHub OAuth setup form. It runs in deterministic
+mock mode through the shared Playrunner browser harness, which uses the real
+frontend, API, authentication, and dedicated E2E database. No GitHub
+credentials or live provider requests are required.
+
 ## Documentation
 
 See the [GitHub integration documentation](https://playrunner.dev/docs/integration-packages/github/) for GitHub App setup, exports, and Playrunner build integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playrunner/github",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "GitHub integration package for Playrunner.",
   "keywords": [
     "playrunner",
@@ -27,7 +27,8 @@
     "integration": {
       "id": "github",
       "frontend": ".",
-      "api": "./api"
+      "api": "./api",
+      "e2e": "./e2e"
     }
   },
   "exports": {
@@ -49,6 +50,12 @@
       "require": "./src/api/index.ts",
       "default": "./src/api/index.ts"
     },
+    "./e2e": {
+      "types": "./src/e2e/index.ts",
+      "import": "./src/e2e/index.ts",
+      "require": "./src/e2e/index.ts",
+      "default": "./src/e2e/index.ts"
+    },
     "./assets/github.svg": "./assets/github.svg"
   },
   "files": [
@@ -68,11 +75,15 @@
     "express": "^5.2.1"
   },
   "peerDependencies": {
+    "@playwright/test": "^1.61.0",
     "@playrunner/integration-sdk": "^0.1.0",
     "lucide-react": "^0.546.0",
     "react": "^19.0.0"
   },
   "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
     "@playrunner/integration-sdk": {
       "optional": true
     },
@@ -85,6 +96,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@playwright/test": "1.61.0",
     "@types/express": "^5.0.6",
     "@types/react": "^19.2.14",
     "eslint": "^9.39.4",

package/src/api/index.ts

@@ -1,4 +1,10 @@
 import { Router } from 'express';
+import type { IntegrationCredentialStore } from '@playrunner/integration-sdk/api';
+
+function credentialStore(req: unknown): IntegrationCredentialStore | undefined {
+  return (req as { integrationCredentials?: IntegrationCredentialStore })
+    .integrationCredentials;
+}
 
 export const githubRouter = Router();
 
@@ -6,13 +12,151 @@ export const githubApiContribution = {
   id: 'github',
   mountPath: '/api/github',
   router: githubRouter,
+  prepareCredentials: refreshGithubCredentials,
 };
 
 export default githubApiContribution;
 
+async function refreshGithubCredentials(
+  store: IntegrationCredentialStore,
+  _kind?: 'cloud' | 'integration',
+  force = false,
+) {
+  const connection = await store.resolve('integration', 'github');
+  if (!connection) return;
+  const expiresAt = connection.secrets.expiresAt;
+  if (
+    !force &&
+    (typeof expiresAt !== 'number' || Date.now() < expiresAt - 5 * 60 * 1000)
+  )
+    return;
+  const { clientId, clientSecret, refreshToken } = connection.secrets;
+  const hasRefreshCredentials = [clientId, clientSecret, refreshToken].every(
+    (value) => typeof value === 'string' && value,
+  );
+  if (!hasRefreshCredentials) {
+    if (force)
+      throw new Error('Saved GitHub refresh credentials are incomplete.');
+    return;
+  }
+  const response = await fetch('https://github.com/login/oauth/access_token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'User-Agent': 'Playrunner-App',
+    },
+    body: JSON.stringify({
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: refreshToken,
+      grant_type: 'refresh_token',
+    }),
+  });
+  const data = (await response.json()) as Record<string, any>;
+  if (!response.ok || typeof data.access_token !== 'string')
+    throw new Error('GitHub authorization has expired. Reconnect GitHub.');
+  await store.updateSecrets('integration', 'github', {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token || refreshToken,
+    expiresAt: data.expires_in
+      ? Date.now() + data.expires_in * 1000
+      : undefined,
+    refreshTokenExpiresAt: data.refresh_token_expires_in
+      ? Date.now() + data.refresh_token_expires_in * 1000
+      : undefined,
+  });
+}
+
+async function getGithubConnection(req: unknown) {
+  const store = credentialStore(req);
+  if (!store) {
+    throw Object.assign(new Error('Credential storage is unavailable.'), {
+      statusCode: 500,
+    });
+  }
+  await refreshGithubCredentials(store);
+  const connection = await store.resolve('integration', 'github');
+  const accessToken = connection?.secrets.accessToken;
+  if (typeof accessToken !== 'string' || !accessToken) {
+    throw Object.assign(new Error('GitHub is not connected.'), {
+      statusCode: 401,
+    });
+  }
+  return { accessToken, connection, store };
+}
+
+async function githubGet(accessToken: string, url: string) {
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message =
+      data &&
+      typeof data === 'object' &&
+      'message' in data &&
+      typeof data.message === 'string'
+        ? data.message
+        : 'GitHub API request failed.';
+    throw Object.assign(new Error(message), { statusCode: response.status });
+  }
+  return data;
+}
+
+function errorStatusCode(error: unknown) {
+  return error &&
+    typeof error === 'object' &&
+    'statusCode' in error &&
+    typeof error.statusCode === 'number'
+    ? error.statusCode
+    : undefined;
+}
+
+async function createGithubApiClient(req: unknown) {
+  const {
+    accessToken: initialAccessToken,
+    connection,
+    store,
+  } = await getGithubConnection(req);
+  let accessToken = initialAccessToken;
+  let refreshPromise: Promise<void> | undefined;
+
+  async function refreshAccessTokenOnce() {
+    refreshPromise ??= (async () => {
+      await refreshGithubCredentials(store, 'integration', true);
+      const refreshed = await store.resolve('integration', 'github');
+      const refreshedAccessToken = refreshed?.secrets.accessToken;
+      if (typeof refreshedAccessToken !== 'string' || !refreshedAccessToken) {
+        throw new Error('GitHub authorization has expired. Reconnect GitHub.');
+      }
+      accessToken = refreshedAccessToken;
+    })();
+    await refreshPromise;
+  }
+
+  return {
+    connection,
+    async get(url: string) {
+      try {
+        return await githubGet(accessToken, url);
+      } catch (error) {
+        if (errorStatusCode(error) !== 401) throw error;
+        await refreshAccessTokenOnce();
+        return githubGet(accessToken, url);
+      }
+    },
+  };
+}
+
 // Proxy endpoint to exchange GitHub OAuth code for an access token to bypass CORS
 githubRouter.post('/token', async (req, res) => {
-  const { code, client_id, client_secret } = req.body;
+  const { code, client_id, client_secret, app_name, installation_id } =
+    req.body;
 
   try {
     const gRes = await fetch('https://github.com/login/oauth/access_token', {
@@ -32,12 +176,41 @@ githubRouter.post('/token', async (req, res) => {
     const text = await gRes.text();
     try {
       const data = JSON.parse(text);
-      res.json(data);
+      if (!gRes.ok || !data.access_token) {
+        return res
+          .status(gRes.status)
+          .json({ error: 'GitHub token exchange failed.' });
+      }
+      const store = credentialStore(req);
+      if (!store) {
+        return res
+          .status(500)
+          .json({ error: 'Credential storage is unavailable.' });
+      }
+      await store.save('integration', 'github', {
+        provider: 'github',
+        config: {
+          appName: app_name,
+          appSlug: app_name,
+          ...(installation_id ? { installationId: installation_id } : {}),
+        },
+        secrets: {
+          clientId: client_id,
+          clientSecret: client_secret,
+          accessToken: data.access_token,
+          refreshToken: data.refresh_token,
+          expiresAt: data.expires_in
+            ? Date.now() + data.expires_in * 1000
+            : undefined,
+          refreshTokenExpiresAt: data.refresh_token_expires_in
+            ? Date.now() + data.refresh_token_expires_in * 1000
+            : undefined,
+        },
+      });
+      return res.json({ connected: true });
     } catch {
-      console.error('Token exchange failed. GitHub returned non-JSON:', text);
-      res
-        .status(500)
-        .json({ error: 'Failed to exchange token', details: text });
+      console.error('Token exchange failed. GitHub returned non-JSON.');
+      res.status(500).json({ error: 'Failed to exchange token' });
     }
   } catch (err) {
     console.error('Token exchange error:', err);
@@ -47,34 +220,129 @@ githubRouter.post('/token', async (req, res) => {
 
 // Proxy endpoint to refresh GitHub OAuth token
 githubRouter.post('/refresh', async (req, res) => {
-  const { refresh_token, client_id, client_secret } = req.body;
+  try {
+    const store = credentialStore(req);
+    if (!store)
+      return res
+        .status(500)
+        .json({ error: 'Credential storage is unavailable.' });
+    await refreshGithubCredentials(store, 'integration', true);
+    return res.json({ connected: true });
+  } catch (err) {
+    console.error('Token refresh error:', err);
+    return res.status(500).json({ error: 'Failed to refresh token' });
+  }
+});
 
+githubRouter.get('/repositories', async (req, res) => {
   try {
-    const gRes = await fetch('https://github.com/login/oauth/access_token', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        'User-Agent': 'Playrunner-App',
-      },
-      body: JSON.stringify({
-        client_id,
-        client_secret,
-        refresh_token,
-        grant_type: 'refresh_token',
+    const github = await createGithubApiClient(req);
+    const { connection } = github;
+    const savedInstallationId = connection.config.installationId;
+    let installationIds: string[] = [];
+
+    if (
+      (typeof savedInstallationId === 'string' && savedInstallationId) ||
+      typeof savedInstallationId === 'number'
+    ) {
+      installationIds = [String(savedInstallationId)];
+    } else {
+      const installations = (await github.get(
+        'https://api.github.com/user/installations?per_page=100',
+      )) as { installations?: Array<{ id?: string | number }> };
+      installationIds = (installations.installations ?? [])
+        .map((installation) => installation.id)
+        .filter(
+          (id): id is string | number =>
+            (typeof id === 'string' && Boolean(id)) || typeof id === 'number',
+        )
+        .map(String);
+    }
+
+    const repositoryLists = await Promise.all(
+      installationIds.map(async (installationId) => {
+        const data = (await github.get(
+          `https://api.github.com/user/installations/${encodeURIComponent(installationId)}/repositories?per_page=100`,
+        )) as {
+          repositories?: Array<{ id?: string | number; full_name?: string }>;
+        };
+        return data.repositories ?? [];
       }),
-    });
+    );
+    const repositories = repositoryLists
+      .flat()
+      .filter(
+        (
+          repository,
+        ): repository is { id: string | number; full_name: string } =>
+          (typeof repository.id === 'string' ||
+            typeof repository.id === 'number') &&
+          typeof repository.full_name === 'string',
+      )
+      .map((repository) => ({
+        id: String(repository.id),
+        full_name: repository.full_name,
+      }))
+      .sort((left, right) => left.full_name.localeCompare(right.full_name));
 
-    const text = await gRes.text();
-    try {
-      const data = JSON.parse(text);
-      res.json(data);
-    } catch {
-      console.error('Token refresh failed. GitHub returned non-JSON:', text);
-      res.status(500).json({ error: 'Failed to refresh token', details: text });
+    return res.json({ repositories });
+  } catch (error) {
+    console.error('Failed to fetch GitHub repositories:', error);
+    const statusCode =
+      error &&
+      typeof error === 'object' &&
+      'statusCode' in error &&
+      typeof error.statusCode === 'number'
+        ? error.statusCode
+        : 500;
+    const message =
+      error instanceof Error
+        ? error.message
+        : 'Failed to fetch GitHub repositories.';
+    return res.status(statusCode).json({ error: message });
+  }
+});
+
+githubRouter.get('/branches', async (req, res) => {
+  try {
+    const repository =
+      typeof req.query.repository === 'string'
+        ? req.query.repository.trim()
+        : '';
+    const parts = repository.split('/');
+    if (parts.length !== 2 || parts.some((part) => !part)) {
+      return res
+        .status(400)
+        .json({ error: 'Repository must use the owner/name format.' });
     }
-  } catch (err) {
-    console.error('Token refresh error:', err);
-    res.status(500).json({ error: 'Failed to refresh token' });
+
+    const github = await createGithubApiClient(req);
+    const data = (await github.get(
+      `https://api.github.com/repos/${encodeURIComponent(parts[0])}/${encodeURIComponent(parts[1])}/branches?per_page=100`,
+    )) as Array<{ name?: string }>;
+    const branches = Array.isArray(data)
+      ? data
+          .filter(
+            (branch): branch is { name: string } =>
+              typeof branch.name === 'string',
+          )
+          .map((branch) => ({ name: branch.name }))
+      : [];
+
+    return res.json({ branches });
+  } catch (error) {
+    console.error('Failed to fetch GitHub branches:', error);
+    const statusCode =
+      error &&
+      typeof error === 'object' &&
+      'statusCode' in error &&
+      typeof error.statusCode === 'number'
+        ? error.statusCode
+        : 500;
+    const message =
+      error instanceof Error
+        ? error.message
+        : 'Failed to fetch GitHub branches.';
+    return res.status(statusCode).json({ error: message });
   }
 });

package/src/e2e/GithubE2EPom.ts

@@ -0,0 +1,31 @@
+import type { Locator, Page } from '@playwright/test';
+import type { PlayrunnerE2EHost } from '@playrunner/integration-sdk/e2e';
+
+export class GithubE2EPom {
+  readonly appNameInput: Locator;
+  readonly authenticateButton: Locator;
+  readonly clientIdInput: Locator;
+  readonly clientSecretInput: Locator;
+  readonly dialog: Locator;
+  readonly setupGuideLink: Locator;
+
+  constructor(
+    readonly page: Page,
+    private readonly host: PlayrunnerE2EHost,
+  ) {
+    this.dialog = page.getByRole('dialog', { name: 'Connect to GitHub' });
+    this.appNameInput = this.dialog.getByLabel('GitHub App Name (URL Slug)');
+    this.clientIdInput = this.dialog.getByLabel('Client ID');
+    this.clientSecretInput = this.dialog.getByLabel('Client Secret');
+    this.authenticateButton = this.dialog.getByRole('button', {
+      name: 'Authenticate',
+    });
+    this.setupGuideLink = this.dialog.getByRole('link', {
+      name: 'Open GitHub setup guide',
+    });
+  }
+
+  async open() {
+    await this.host.openIntegration({ id: 'github', name: 'GitHub' });
+  }
+}

package/src/e2e/data.ts

@@ -0,0 +1,18 @@
+import type { PlayrunnerE2EDataContext } from '@playrunner/integration-sdk/e2e';
+
+export interface GithubE2EData {
+  appName: string;
+  clientId: string;
+  clientSecret: string;
+}
+
+export function createGithubE2EData({
+  runId,
+}: PlayrunnerE2EDataContext): GithubE2EData {
+  const suffix = runId.replace(/[^a-zA-Z0-9]/g, '-');
+  return {
+    appName: `playrunner-e2e-${suffix}`,
+    clientId: `github-client-${suffix}`,
+    clientSecret: `github-secret-${suffix}`,
+  };
+}

package/src/e2e/index.ts

@@ -0,0 +1,38 @@
+import { definePlayrunnerE2EContribution } from '@playrunner/integration-sdk/e2e';
+import { createGithubE2EData } from './data';
+import { GithubE2EPom } from './GithubE2EPom';
+
+export const githubE2EContribution = definePlayrunnerE2EContribution({
+  id: 'github',
+  createData: createGithubE2EData,
+  createPom: ({ host, page }) => new GithubE2EPom(page, host),
+  scenarios: [
+    {
+      id: 'oauth-setup',
+      mode: 'mock',
+      title: 'validates the GitHub OAuth setup form',
+      tags: ['@github', '@integration'],
+      async run({ data, expect, pom }) {
+        await pom.open();
+
+        await expect(pom.setupGuideLink).toHaveAttribute('target', '_blank');
+        await expect(pom.clientSecretInput).toHaveAttribute('type', 'password');
+        await expect(pom.authenticateButton).toBeDisabled();
+
+        await pom.appNameInput.click();
+        await pom.appNameInput.fill(data.appName);
+        await pom.clientIdInput.click();
+        await pom.clientIdInput.fill(data.clientId);
+        await pom.clientSecretInput.click();
+        await pom.clientSecretInput.fill(data.clientSecret);
+        await expect(pom.authenticateButton).toBeEnabled();
+      },
+    },
+  ],
+});
+
+export default githubE2EContribution;
+
+export { createGithubE2EData } from './data';
+export type { GithubE2EData } from './data';
+export { GithubE2EPom } from './GithubE2EPom';

package/src/frontend/GithubSettingsModal.tsx

@@ -51,6 +51,7 @@ export function GithubSettingsModal({
   const [githubAppSlug, setGithubAppSlug] = useState<string | null>(null);
   const [isAuthenticating, setIsAuthenticating] = useState(false);
   const [authSuccess, setAuthSuccess] = useState(false);
+  const [authError, setAuthError] = useState('');
   const [copiedUrl, setCopiedUrl] = useState(false);
   const popupRef = React.useRef<Window | null>(null);
 
@@ -72,18 +73,19 @@ export function GithubSettingsModal({
             'github',
           );
           if (data && isMounted) {
-            if (data.clientId && data.accessToken) {
-              setGithubAppName(data.appName || data.appSlug || '');
-              setGithubClientId(data.clientId);
-              setGithubClientSecret(data.clientSecret || '');
-              if (data.appSlug) setGithubAppSlug(data.appSlug);
-              setAuthSuccess(true);
-            } else if (data.clientId) {
-              setGithubAppName(data.appName || data.appSlug || '');
-              setGithubClientId(data.clientId);
-              setGithubClientSecret(data.clientSecret || '');
-              if (data.appSlug) setGithubAppSlug(data.appSlug);
-            }
+            const appName =
+              typeof data.config?.appName === 'string'
+                ? data.config.appName
+                : typeof data.config?.appSlug === 'string'
+                  ? data.config.appSlug
+                  : '';
+            const appSlug =
+              typeof data.config?.appSlug === 'string'
+                ? data.config.appSlug
+                : null;
+            setGithubAppName(appName);
+            setGithubAppSlug(appSlug);
+            setAuthSuccess(Boolean(data.credentialStatus?.configured));
           }
         } catch (error) {
           console.error('Failed to fetch Github credentials', error);
@@ -95,6 +97,7 @@ export function GithubSettingsModal({
       fetchCredentials();
     } else {
       setAuthSuccess(false);
+      setAuthError('');
       setIsAuthenticating(false);
       setGithubAppName('');
       setGithubClientId('');
@@ -110,28 +113,26 @@ export function GithubSettingsModal({
   const handleAuthenticateGithub = async () => {
     try {
       setIsAuthenticating(true);
-
-      const currentUser = auth.currentUser;
-
-      if (currentUser) {
-        await store.saveIntegration(currentUser.uid, 'github', {
-          appName: githubAppName,
-          clientId: githubClientId,
-          clientSecret: githubClientSecret,
-          updatedAt: new Date().toISOString(),
-        });
-      }
+      setAuthError('');
 
       let isProcessing = false;
+      let installationId: string | undefined;
+      const oauthState = crypto.randomUUID();
       const messageListener = async (event: MessageEvent) => {
         if (event.origin !== window.location.origin) return;
         if (event.data?.type === 'oauth_callback' && event.data?.success) {
           if (isProcessing) return;
           isProcessing = true;
 
+          let didConnect = false;
           if (auth.currentUser) {
             if (event.data?.params?.code) {
               try {
+                if (event.data.params.state !== oauthState) {
+                  throw new Error(
+                    'GitHub returned an invalid OAuth state. Try connecting again.',
+                  );
+                }
                 // Exchange the code for an access token
                 const token = await auth.currentUser.getIdToken();
                 const tokenRes = await fetch('/api/github/token', {
@@ -144,47 +145,22 @@ export function GithubSettingsModal({
                     code: event.data.params.code,
                     client_id: githubClientId,
                     client_secret: githubClientSecret,
+                    app_name: githubAppName,
+                    installation_id:
+                      event.data.params.installation_id || installationId,
                   }),
                 });
 
                 const tokenData = await tokenRes.json();
 
-                if (!tokenData.access_token) {
+                if (!tokenRes.ok || !tokenData.connected) {
                   throw new Error(
                     `Failed to retrieve access token: ${JSON.stringify(tokenData)}`,
                   );
                 }
 
-                const integrationData: any = {
-                  appName: githubAppName,
-                  clientId: githubClientId,
-                  clientSecret: githubClientSecret,
-                  code: event.data.params.code,
-                  accessToken: tokenData.access_token,
-                  refreshToken: tokenData.refresh_token,
-                  expiresAt: tokenData.expires_in
-                    ? Date.now() + tokenData.expires_in * 1000
-                    : undefined,
-                  refreshTokenExpiresAt: tokenData.refresh_token_expires_in
-                    ? Date.now() + tokenData.refresh_token_expires_in * 1000
-                    : undefined,
-                  appSlug: githubAppName,
-                  updatedAt: new Date().toISOString(),
-                };
-
-                // Store installation_id if it was provided
-                if (event.data.params.installation_id) {
-                  integrationData.installationId =
-                    event.data.params.installation_id;
-                }
-
-                await store.saveIntegration(
-                  auth.currentUser.uid,
-                  'github',
-                  integrationData,
-                );
-
                 setGithubAppSlug(githubAppName);
+                didConnect = true;
                 if (popupRef.current)
                   popupRef.current.postMessage(
                     { type: 'oauth_close' },
@@ -192,24 +168,10 @@ export function GithubSettingsModal({
                   );
               } catch (err) {
                 console.error('Failed to save auth code:', err);
-                if (popupRef.current)
-                  popupRef.current.postMessage(
-                    { type: 'oauth_close' },
-                    window.location.origin,
-                  );
-              }
-            } else if (event.data?.params?.installation_id) {
-              if (event.data?.params?.setup_action === 'update') {
-                // Just an update to the installation (e.g. adding repositories)
-                if (popupRef.current)
-                  popupRef.current.postMessage(
-                    { type: 'oauth_close' },
-                    window.location.origin,
-                  );
-              } else {
-                // If there is an installation ID but no code, they probably forgot to check "Request user authorization (OAuth) during installation"
-                alert(
-                  "Installation successful, but no OAuth code found. Please ensure you checked 'Request user authorization (OAuth) during installation' in your GitHub App settings.",
+                setAuthError(
+                  err instanceof Error
+                    ? err.message
+                    : 'Failed to save the GitHub connection.',
                 );
                 if (popupRef.current)
                   popupRef.current.postMessage(
@@ -217,25 +179,51 @@ export function GithubSettingsModal({
                     window.location.origin,
                   );
               }
+            } else if (event.data?.params?.installation_id) {
+              installationId = event.data.params.installation_id;
+              const authorizeUrl = new URL(
+                'https://github.com/login/oauth/authorize',
+              );
+              authorizeUrl.searchParams.set('client_id', githubClientId);
+              authorizeUrl.searchParams.set('redirect_uri', callbackUrl);
+              authorizeUrl.searchParams.set('state', oauthState);
+              popupRef.current?.postMessage(
+                {
+                  type: 'oauth_install_redirect',
+                  url: authorizeUrl.toString(),
+                },
+                window.location.origin,
+              );
+              isProcessing = false;
+              return;
+            } else {
+              setAuthError(
+                'GitHub returned no OAuth code. Check the GitHub App callback and OAuth settings, then try again.',
+              );
             }
+          } else {
+            setAuthError('You must be signed in to connect GitHub.');
           }
 
           setIsAuthenticating(false);
-          setAuthSuccess(true);
+          setAuthSuccess(didConnect);
           window.removeEventListener('message', messageListener);
         }
       };
 
       window.addEventListener('message', messageListener);
 
-      const authUrl = `https://github.com/apps/${githubAppName}/installations/new`;
+      const installationUrl = new URL(
+        `https://github.com/apps/${githubAppName}/installations/new`,
+      );
+      installationUrl.searchParams.set('state', oauthState);
 
       const width = 800;
       const height = 700;
       const left = window.screen.width / 2 - width / 2;
       const top = window.screen.height / 2 - height / 2;
       popupRef.current = window.open(
-        authUrl,
+        installationUrl.toString(),
         'GithubOAuth',
         `toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=${width}, height=${height}, top=${top}, left=${left}`,
       );
@@ -249,6 +237,11 @@ export function GithubSettingsModal({
       }, 500);
     } catch (error) {
       console.error('Failed to save credentials', error);
+      setAuthError(
+        error instanceof Error
+          ? error.message
+          : 'Failed to authenticate with GitHub.',
+      );
       setIsAuthenticating(false);
     }
   };
@@ -365,6 +358,15 @@ export function GithubSettingsModal({
         <div className="flex flex-col gap-6">
           <IntegrationConnectionAutofillGuard connectionId="github" />
 
+          {authError ? (
+            <div
+              role="alert"
+              className="rounded-xl border border-red-500/20 bg-red-500/10 p-3 text-sm text-red-500"
+            >
+              {authError}
+            </div>
+          ) : null}
+
           <div className="rounded-xl border border-[var(--border)] bg-[var(--surface-hover)] p-4 text-left">
             <div className="flex items-start gap-3">
               <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--background)]">

package/src/frontend/index.tsx

@@ -1,7 +1,6 @@
 import type { Integration } from '@playrunner/integration-sdk';
 import { GithubSettingsModal } from './GithubSettingsModal';
 import { GithubIcon } from './GithubIcon';
-import { refreshGithubTokenIfNeeded } from './tokenRefresh';
 
 export const githubIntegration: Integration = {
   id: 'github',
@@ -13,7 +12,6 @@ export const githubIntegration: Integration = {
   iconRenderMode: 'mask',
   getAuthPath: (uid) => `users/${uid}/integrations/github`,
   SettingsModal: GithubSettingsModal,
-  refreshStoredIntegration: refreshGithubTokenIfNeeded,
 };
 
 export default githubIntegration;

package/src/frontend/tokenRefresh.ts

@@ -1,79 +0,0 @@
-import type { IntegrationRefreshContext } from '@playrunner/integration-sdk';
-
-function isBadGithubRefreshTokenError(tokenData: any) {
-  return tokenData?.error === 'bad_refresh_token';
-}
-
-export async function refreshGithubTokenIfNeeded({
-  integrationData,
-  getApiHeaders,
-  saveIntegration,
-  deleteIntegration,
-}: IntegrationRefreshContext) {
-  if (
-    !integrationData ||
-    !integrationData.accessToken ||
-    !integrationData.refreshToken ||
-    !integrationData.expiresAt
-  ) {
-    return integrationData;
-  }
-
-  if (Date.now() + 5 * 60 * 1000 <= integrationData.expiresAt) {
-    return integrationData;
-  }
-
-  try {
-    console.log('GitHub token is expired or expiring soon, refreshing...');
-    const res = await fetch('/api/github/refresh', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...(await getApiHeaders()),
-      },
-      body: JSON.stringify({
-        refresh_token: integrationData.refreshToken,
-        client_id: integrationData.clientId,
-        client_secret: integrationData.clientSecret,
-      }),
-    });
-
-    const tokenData = await res.json();
-
-    if (tokenData.access_token) {
-      integrationData.accessToken = tokenData.access_token;
-      if (tokenData.refresh_token) {
-        integrationData.refreshToken = tokenData.refresh_token;
-      }
-      if (tokenData.expires_in) {
-        integrationData.expiresAt = Date.now() + tokenData.expires_in * 1000;
-      }
-      if (tokenData.refresh_token_expires_in) {
-        integrationData.refreshTokenExpiresAt =
-          Date.now() + tokenData.refresh_token_expires_in * 1000;
-      }
-      integrationData.updatedAt = new Date().toISOString();
-
-      await saveIntegration(integrationData);
-      console.log('GitHub token refreshed successfully.');
-      return integrationData;
-    }
-
-    if (isBadGithubRefreshTokenError(tokenData)) {
-      console.warn(
-        'GitHub refresh token is invalid or expired. Clearing the saved GitHub connection; reconnect GitHub to continue.',
-      );
-      await deleteIntegration();
-      return null;
-    }
-
-    console.error(
-      'Failed to refresh GitHub token, no access_token returned:',
-      tokenData,
-    );
-  } catch (error) {
-    console.error('Failed to refresh GitHub token:', error);
-  }
-
-  return integrationData;
-}