DeepWiki

03.d - Token-Types-&-Lifespans

Relevant source files

This document explains the dual authentication architecture in godeep.wiki, focusing on the two distinct token types used for repository access: user OAuth tokens and installation access tokens. These tokens serve different purposes, have different lifespans, and are created through different mechanisms.

For information about the OAuth initiation flow, see GitHub OAuth Initiation. For details on the OAuth callback handling, see OAuth Callback Handler. For GitHub App installation, see GitHub App Installation Flow.

The system employs two fundamentally different token types with distinct characteristics:

CharacteristicUser OAuth TokenInstallation Access Token
PurposeUser accesses their own repositoriesOwner accesses customer repositories
Lifespan24 hours1 hour (GitHub limit)
StoragehttpOnly cookie (github_access_token)Not stored; generated on-demand
ScopeUser's selected repositoriesInstallation's authorized repositories
Authentication MethodOAuth 2.0 flowGitHub App JWT → Installation token
Generated ByGitHub OAuth endpointGitHub App API
Used In/dashboard (customer view)Admin panel & automation scripts
Refresh StrategyRe-authenticate via OAuthRegenerate via admin API

Sources: app/api/auth/github/callback/route.ts L91-L96

app/admin/page.tsx L229

CLAUDE.md L76-L79

User OAuth tokens enable customers to view their own repositories in the dashboard after connecting their GitHub account. These tokens authenticate the user who made the payment and installed the GitHub App.

Primary Use Case: Customer accessing /dashboard to verify which repositories were shared.

Sources: app/api/auth/github/callback/route.ts L80-L96

Token Exchange Flow:

The OAuth callback handler exchanges the authorization code for an access token at app/api/auth/github/callback/route.ts L60-L78

:

const response = await fetch("https://github.com/login/oauth/access_token", {  method: "POST",  headers: {    "Content-Type": "application/json",    Accept: "application/json",  },  body: JSON.stringify({    client_id: clientId,    client_secret: clientSecret,    code,  }),})

Sources: app/api/auth/github/callback/route.ts L59-L78

User OAuth tokens are stored in HTTP-only cookies to prevent XSS attacks. The cookie configuration at app/api/auth/github/callback/route.ts L91-L96

:

Cookie PropertyValuePurpose
Namegithub_access_tokenCookie identifier
httpOnlytruePrevents JavaScript access (XSS protection)
secureprocess.env.NODE_ENV === "production"HTTPS-only in production
path/Cookie available site-wide
maxAge60 * 60 * 24 (86400 seconds)24-hour expiration

Sources: app/api/auth/github/callback/route.ts L91-L96

The 24-hour lifespan balances security and user experience:

  • Security: Limits exposure window if token is compromised
  • User Experience: Users can return to dashboard within a day without re-authenticating
  • Session Continuity: Sufficient for typical user workflows (verify connection, check status)

After 24 hours, users must re-authenticate through the OAuth flow to access the dashboard.

Sources: app/api/auth/github/callback/route.ts L95

CLAUDE.md L76-L77

Installation access tokens grant the system owner (klaudioz) access to customer repositories that were authorized during GitHub App installation. These tokens enable repository cloning and documentation generation.

Primary Use Cases:

  1. Admin Panel: Manual token generation for repository access at /admin
  2. Automation Scripts: Automated repository cloning via ntfy-godeep-automation.sh

Sources: app/api/admin/generate-token/route.ts L1-L57

app/admin/page.tsx L57-L85

Installation tokens are generated through a two-step GitHub App authentication process:

Sources: lib/github-app.ts

app/api/admin/generate-token/route.ts L24-L44

The /api/admin/generate-token endpoint orchestrates installation token creation at app/api/admin/generate-token/route.ts L4-L57

:

Request Format:

{  "installationId": "12345678",  "password": "ADMIN_PASSWORD"}

Response Format:

{  "token": "ghs_xxxxxxxxxxxxx",  "expiresAt": "2024-01-01T12:00:00Z",  "repositories": [...],  "user": {    "username": "customer-github-user",    "email": "customer@example.com",    "name": "Customer Name"  }}

Authentication Flow:

  1. Verify ADMIN_PASSWORD at app/api/admin/generate-token/route.ts L8-L15
  2. Call getInstallationAccessToken(installationId)
  3. Fetch repository list via getInstallationRepositories(installationId)
  4. Fetch user details via getInstallationDetails(installationId)

Sources: app/api/admin/generate-token/route.ts L4-L57

Installation tokens have a maximum lifespan of 1 hour, enforced by GitHub's API:

Displayed in Admin Panel at app/admin/page.tsx L229

:

Token expires at: {new Date(tokenData.expiresAt).toLocaleString()} (GitHub limit: 1 hour max)

Rationale for 1-Hour Limit:

  • Minimal Exposure Window: Reduces risk if token is compromised
  • On-Demand Generation: Owner generates tokens only when needed
  • No Persistent Storage: Tokens are not stored; must be regenerated
  • Alignment with Task Duration: Sufficient time to clone repositories and complete immediate tasks

Sources: app/admin/page.tsx L229

CLAUDE.md L78-L79

No Storage - On-Demand GenerationLink copied!

Unlike user OAuth tokens, installation access tokens are never stored persistently. They exist only in:

  1. Memory: Displayed in admin panel UI after generation
  2. Temporary Use: Used immediately for git operations or API calls
  3. Automation Scripts: Stored in memory variables during script execution

Regeneration Required: If the token expires during use, the owner must return to /admin and generate a new token with the same installation_id.

Sources: app/admin/page.tsx L18-L28

app/api/admin/generate-token/route.ts

State Cookie Management:

  • github_oauth_state: Temporary cookie for CSRF protection (deleted after callback)
  • github_access_token: Persistent cookie for 24-hour user sessions

Sources: app/api/auth/github/callback/route.ts L23-L37

app/api/auth/github/callback/route.ts L91-L96

Key Differences from User Tokens:

  • No automatic refresh mechanism
  • Must be manually regenerated when expired
  • No persistent storage anywhere in the system
  • Generated only when owner explicitly requests access

Sources: app/admin/page.tsx L57-L85

app/api/admin/generate-token/route.ts L24-L44

Implementation Details:

  • Token read from cookie server-side (httpOnly prevents client-side access)
  • Used in Authorization: Bearer {token} header for GitHub API calls
  • No manual token handling required by customer

Sources: app/api/auth/github/callback/route.ts L91-L96

CLAUDE.md L76-L79

Admin Panel Usage Pattern:

The admin panel at app/admin/page.tsx L250-L297

provides copy-paste commands for repository access:

# Clone customer repository using installation tokengit clone https://x-access-token:{TOKEN}@github.com/{owner}/{repo}.git# Clone and create private mirror in owner's accountgit clone https://x-access-token:{TOKEN}@github.com/{customer}/{repo}.git temp-repo && \cd temp-repo && \rm -rf .git && \git init && \git add . && \git commit -m "Initial commit" && \gh repo create klaudioz/{email}-{reponame} --private --source=. --push

Automation Script Usage Pattern:

The automation scripts use installation tokens for unattended cloning:

  1. Extract installation_id from ntfy notification
  2. Call /api/admin/generate-token with ADMIN_PASSWORD
  3. Use returned token for git operations
  4. Token expires after automation completes (within 1 hour)

Sources: app/admin/page.tsx L250-L297

CLAUDE.md L180-L185

Token TypeExposure RiskMitigation Strategy
User OAuth TokenXSS attackshttpOnly cookie prevents JavaScript access
User OAuth TokenNetwork interceptionSecure flag enforces HTTPS in production
User OAuth TokenToken theft24-hour expiry limits damage window
Installation TokenLogged in plain textNo persistent storage; regenerated on-demand
Installation TokenExtended compromise1-hour expiry minimizes exposure window
Installation TokenUnauthorized accessRequires ADMIN_PASSWORD for generation

Sources: app/api/auth/github/callback/route.ts L91-L96

app/api/admin/generate-token/route.ts L8-L15

Critical Security Boundary:

  • User tokens cannot access customer repositories (wrong scope)
  • Installation tokens cannot access repositories not selected during installation
  • Owner never uses customer OAuth tokens (uses installation tokens instead)

Sources: CLAUDE.md L195-L209

app/api/auth/github/callback/route.ts L80-L96

Correlation Mechanism:

  1. session_id embedded in OAuth state at app/api/auth/github/route.ts
  2. session_id extracted from state at app/api/auth/github/callback/route.ts L39-L50
  3. Both session_id and installation_id logged together at app/api/auth/github/callback/route.ts L99-L112
  4. Owner matches payment to installation via logs
  5. Owner uses installation_id to generate access token

Sources: app/api/auth/github/callback/route.ts L39-L112

CLAUDE.md L44-L51

Key Takeaways:

  • Two authentication paths serve different users with different needs
  • User tokens provide convenient 24-hour dashboard access
  • Installation tokens provide secure, time-limited repository access for owner
  • Manual correlation via logs bridges payment and repository access
  • No token type can be used interchangeably with the other

Sources: app/api/auth/github/callback/route.ts

app/api/admin/generate-token/route.ts

app/admin/page.tsx

CLAUDE.md L76-L79

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

03.d - Token-Types-&-Lifespans | DeepWiki | godeep.wiki