♻️ Extract GitHub API utilities and integrate token refresh

.env.template

@@ -24,3 +24,15 @@ SENTRY_ORG=""
 SENTRY_PROJECT=""
 SUPABASE_SERVICE_ROLE_KEY=""
 NEXT_PUBLIC_ALLOWED_DOMAINS=""
+
+# GitHub OAuth token encryption keyring
+# LIAM_GITHUB_OAUTH_KEYRING
+# Usage: AES-256-GCM keyring for encrypting GitHub OAuth tokens in HttpOnly cookies.
+# Format: comma-separated entries "<kid>:<base64key>" — first entry is the current key.
+# - <kid>: recommended format is a readable version like "kYYYY-MM" (e.g., k2025-01)
+# - <base64key>: 32-byte random key, base64-encoded
+# Generate 32-byte key (Node.js):
+#   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+# Example (current key first, with a rotated fallback):
+#   LIAM_GITHUB_OAUTH_KEYRING="k2025-01:BASE64_KEY_FOR_2025_01,k2024-12:BASE64_KEY_FOR_2024_12"
+LIAM_GITHUB_OAUTH_KEYRING=""

frontend/apps/app/app/api/auth/logout/route.ts

@@ -0,0 +1,11 @@
+import { fromAsyncThrowable } from '@liam-hq/neverthrow'
+import { NextResponse } from 'next/server'
+import { clearTokens } from '../../../../libs/github/cookie'
+
+export async function POST() {
+  await fromAsyncThrowable(clearTokens)().match(
+    () => undefined,
+    () => undefined,
+  )
+  return NextResponse.json({ ok: true })
+}

frontend/apps/app/app/api/github/token/refresh/route.ts

@@ -0,0 +1,143 @@
+import {
+  fromPromise,
+  fromValibotSafeParse,
+  type Result,
+} from '@liam-hq/neverthrow'
+import * as Sentry from '@sentry/nextjs'
+import type { ResultAsync as NeverthrowResultAsync } from 'neverthrow'
+import { err, ok, ResultAsync } from 'neverthrow'
+import { NextResponse } from 'next/server'
+import * as v from 'valibot'
+import type { TokenPayload } from '../../../../../libs/github/cookie'
+import {
+  readRefreshToken,
+  writeAccessToken,
+  writeRefreshToken,
+} from '../../../../../libs/github/cookie'
+
+const getClientCredentials = (): Result<
+  { clientId: string; clientSecret: string },
+  Error
+> => {
+  const clientId = process.env.GITHUB_CLIENT_ID
+  const clientSecret = process.env.GITHUB_CLIENT_SECRET
+  if (!clientId || !clientSecret) {
+    return err(new Error('Missing GitHub OAuth client credentials'))
+  }
+  return ok({ clientId, clientSecret })
+}
+
+type RefreshAccessTokenResult = {
+  accessToken: string
+  refreshToken: string
+  refreshTokenExpiresIn: number
+  newExpiresAt: string
+}
+
+// GitHub OAuth token refresh response schema
+const GitHubTokenRefreshResponseSchema = v.object({
+  access_token: v.string(),
+  token_type: v.string(),
+  scope: v.optional(v.string()),
+  expires_in: v.number(),
+  refresh_token: v.string(),
+  refresh_token_expires_in: v.optional(v.number()),
+})
+
+function refreshAccessToken(
+  refreshToken: string,
+  clientId: string,
+  clientSecret: string,
+): ResultAsync<RefreshAccessTokenResult, Error> {
+  const body = new URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+  }).toString()
+
+  return ResultAsync.fromPromise(
+    fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body,
+    }),
+    (e) => (e instanceof Error ? e : new Error(String(e))),
+  )
+    .andThen((res) => {
+      if (!res.ok) {
+        return err(new Error(`GitHub token refresh failed: ${res.status}`))
+      }
+      return ResultAsync.fromPromise(res.json() as Promise<unknown>, (e) =>
+        e instanceof Error ? e : new Error(String(e)),
+      )
+    })
+    .andThen((data) =>
+      fromValibotSafeParse(GitHubTokenRefreshResponseSchema, data),
+    )
+    .map((data) => {
+      const now = Date.now()
+      const newExpiresAt = new Date(
+        now + Math.max(0, data.expires_in) * 1000,
+      ).toISOString()
+      const refreshTokenExpiresIn = data.refresh_token_expires_in ?? 0
+
+      return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        refreshTokenExpiresIn,
+        newExpiresAt,
+      }
+    })
+}
+
+async function handler(): Promise<NextResponse> {
+  // 1) Load client credentials
+  const creds = getClientCredentials()
+  if (creds.isErr()) {
+    Sentry.captureException(creds.error, { tags: { area: 'refresh_api' } })
+    return NextResponse.json(
+      { ok: false, error: 'server_misconfigured' },
+      { status: 500 },
+    )
+  }
+  const { clientId, clientSecret } = creds.value
+
+  // 2) Read refresh token and refresh via GitHub
+  const refreshTokenResult: NeverthrowResultAsync<TokenPayload, Error> =
+    readRefreshToken()
+  const result = await refreshTokenResult
+    .andThen(({ token }: TokenPayload) =>
+      refreshAccessToken(token, clientId, clientSecret),
+    )
+    .andThen((refreshed: RefreshAccessTokenResult) => {
+      const rtei = refreshed.refreshTokenExpiresIn
+      const refreshTtlMs = rtei * 1000
+      const refreshExpiresAt = new Date(Date.now() + refreshTtlMs).toISOString()
+
+      // Ensure cookie writes complete and propagate failures
+      return fromPromise(
+        Promise.all([
+          writeAccessToken(refreshed.accessToken, refreshed.newExpiresAt),
+          writeRefreshToken(refreshed.refreshToken, refreshExpiresAt),
+        ]),
+      ).map(() => NextResponse.json({ ok: true }))
+    })
+
+  if (result.isErr()) {
+    Sentry.captureException(result.error, { tags: { area: 'refresh_api' } })
+    return NextResponse.json(
+      { ok: false, error: 'refresh_failed' },
+      { status: 401 },
+    )
+  }
+
+  return result.value
+}
+
+export async function POST() {
+  return handler()
+}

frontend/apps/app/app/auth/callback/[provider]/route.ts

@@ -1,7 +1,13 @@
+import { fromAsyncThrowable } from '@liam-hq/neverthrow'
+import * as Sentry from '@sentry/nextjs'
 import { NextResponse } from 'next/server'
 import { ensureUserHasOrganization } from '../../../../components/LoginPage/services/ensureUserHasOrganization'
 import { sanitizeReturnPath } from '../../../../components/LoginPage/services/validateReturnPath'
 import { createClient } from '../../../../libs/db/server'
+import {
+  writeAccessToken,
+  writeRefreshToken,
+} from '../../../../libs/github/cookie'
 
 export async function GET(request: Request) {
   const { searchParams, origin } = new URL(request.url)
@@ -11,9 +17,44 @@ export async function GET(request: Request) {
 
   if (code) {
     const supabase = await createClient()
-    const { error } = await supabase.auth.exchangeCodeForSession(code)
+    const { data, error } = await supabase.auth.exchangeCodeForSession(code)
     if (!error) {
       await ensureUserHasOrganization()
+      // Persist provider tokens into encrypted HttpOnly cookies (best-effort)
+      const { session } = data
+      const access = session?.provider_token ?? ''
+      const refresh = session?.provider_refresh_token ?? ''
+      // received provider tokens for cookie write
+      // Access token expiration: 8 hours.
+      // GitHub's OAuth access tokens typically expire after 8 hours. See: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#step-3-github-redirects-back-to-your-site
+      const EIGHT_HOURS_MS = 8 * 60 * 60 * 1000
+      const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000
+
+      await fromAsyncThrowable(async () => {
+        if (access) {
+          const accessExpiresAt = new Date(
+            Date.now() + EIGHT_HOURS_MS,
+          ).toISOString()
+          await writeAccessToken(access, accessExpiresAt)
+        }
+        if (refresh) {
+          const refreshExpiresAt = new Date(
+            Date.now() + THIRTY_DAYS_MS,
+          ).toISOString()
+          await writeRefreshToken(refresh, refreshExpiresAt)
+        }
+      })().match(
+        () => undefined,
+        (e) => {
+          const err = e instanceof Error ? e : new Error(String(e))
+          Sentry.captureException(err, {
+            tags: {
+              area: 'auth_cookie_write',
+            },
+          })
+          return undefined
+        },
+      )
 
       const forwardedHost = request.headers.get('x-forwarded-host')
       const isLocalEnv = process.env.NODE_ENV === 'development'

frontend/apps/app/app/projects/new/page.tsx

@@ -1,8 +1,10 @@
 import { getInstallations } from '@liam-hq/github'
+import { fromPromise } from '@liam-hq/neverthrow'
 import { redirect } from 'next/navigation'
 import { ProjectNewPage } from '../../../components/ProjectNewPage'
 import { getOrganizationId } from '../../../features/organizations/services/getOrganizationId'
 import { createClient } from '../../../libs/db/server'
+import { getUserAccessToken } from '../../../libs/github/token'
 import { urlgen } from '../../../libs/routes'
 
 export default async function NewProjectPage() {
@@ -25,18 +27,36 @@ export default async function NewProjectPage() {
     redirect(urlgen('login'))
   }
 
-  const { data } = await supabase.auth.getSession()
-
-  if (data.session === null) {
-    redirect(urlgen('login'))
-  }
-
-  const { installations } = await getInstallations(data.session)
+  const tokenResult = await getUserAccessToken()
+
+  const { installations, needsRefresh } = await tokenResult
+    .asyncAndThen((token) => {
+      if (!token) {
+        return fromPromise(
+          Promise.resolve({
+            installations: [],
+            needsRefresh: true,
+          }),
+        )
+      }
+      return getInstallations(token).map((result) => ({
+        installations: result.installations,
+        needsRefresh: false,
+      }))
+    })
+    .match(
+      (v) => v,
+      (e) => {
+        console.error('Failed to get token or installations:', e)
+        return { installations: [], needsRefresh: true }
+      },
+    )
 
   return (
     <ProjectNewPage
       installations={installations}
       organizationId={organizationId}
+      needsRefresh={needsRefresh}
     />
   )
 }

frontend/apps/app/components/CommonLayout/AppBar/UserDropdown.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import { fromPromise } from '@liam-hq/neverthrow'
 import {
   Avatar,
   AvatarWithImage,
@@ -63,6 +64,19 @@ export const UserDropdown: FC<Props> = ({ avatarUrl, userName, userEmail }) => {
       // Delete organizationId cookie
       deleteCookie('organizationId')
 
+      // Best-effort call to logout endpoint to clear OAuth cookies
+      type HttpResponse = {
+        ok: boolean
+        headers: { get(name: string): string | null }
+        json: () => Promise<unknown>
+      }
+      await fromPromise<HttpResponse>(
+        fetch('/api/auth/logout', { method: 'POST', cache: 'no-store' }),
+      ).match(
+        () => {},
+        () => {},
+      )
+
       // Redirect with success parameter
       router.push('/login?logout=success')
     } else {

frontend/apps/app/components/ProjectNewPage/ProjectNewPage.tsx

@@ -1,23 +1,28 @@
 import type { Installation } from '@liam-hq/github'
 import type { FC } from 'react'
+import { TokenRefreshKick } from '../TokenRefreshKick'
 import { InstallationSelector } from './components/InstallationSelector'
 import styles from './ProjectNewPage.module.css'
 
 type Props = {
   installations: Installation[]
   organizationId: string
+  needsRefresh?: boolean
 }
 
 export const ProjectNewPage: FC<Props> = ({
   installations,
   organizationId,
+  needsRefresh,
 }) => {
   return (
     <div className={styles.container}>
+      <TokenRefreshKick trigger={needsRefresh} />
       <h1 className={styles.title}>Add a Project</h1>
       <InstallationSelector
         installations={installations}
         organizationId={organizationId}
+        disabled={Boolean(needsRefresh)}
       />
     </div>
   )

frontend/apps/app/components/ProjectNewPage/components/InstallationSelector/InstallationSelector.tsx

@@ -24,25 +24,27 @@ import styles from './InstallationSelector.module.css'
 type Props = {
   installations: Installation[]
   organizationId: string
+  disabled?: boolean
 }
 
 export const InstallationSelector: FC<Props> = ({
   installations,
   organizationId,
+  disabled = false,
 }) => {
   const [selectedInstallation, setSelectedInstallation] =
     useState<Installation | null>(null)
   const [isAddingProject, startAddingProjectTransition] = useTransition()
-  const [, startTransition] = useTransition()
 
   const [repositoriesState, repositoriesAction, isRepositoriesLoading] =
     useActionState(getRepositories, { repositories: [], loading: false })
 
   const githubAppUrl = process.env.NEXT_PUBLIC_GITHUB_APP_URL
 
   const handleSelectInstallation = (installation: Installation) => {
-    setSelectedInstallation(installation)
-    startTransition(() => {
+    if (disabled) return
+    startAddingProjectTransition(() => {
+      setSelectedInstallation(installation)
       const formData = new FormData()
       formData.append('installationId', installation.id.toString())
       repositoriesAction(formData)
@@ -84,8 +86,8 @@ export const InstallationSelector: FC<Props> = ({
       </div>
       <div className={styles.installationSelector}>
         <DropdownMenuRoot>
-          <DropdownMenuTrigger asChild>
-            <Button size="lg" variant="ghost-secondary">
+          <DropdownMenuTrigger asChild disabled={disabled}>
+            <Button size="lg" variant="ghost-secondary" disabled={disabled}>
               {selectedInstallation
                 ? match(selectedInstallation.account)
                     .with({ login: P.string }, (item) => item.login)
@@ -104,7 +106,7 @@ export const InstallationSelector: FC<Props> = ({
               return (
                 <DropdownMenuItem
                   key={item.id}
-                  onSelect={() => handleSelectInstallation(item)}
+                  onSelect={() => !disabled && handleSelectInstallation(item)}
                 >
                   {login}
                 </DropdownMenuItem>