How PicList Handles API Authentication: OAuth, Tokens, and HTTP Auth Methods

PicList implements a multi-layered authentication system using OAuth Device Flow for GitHub integrations, Bearer tokens for cloud synchronization, and configurable HTTP authentication schemes including Basic, Digest, and signature-based methods for various storage backends.

The kuingsmile/piclist repository is a cross-platform image hosting tool that supports diverse storage backends and cloud services. Understanding PicList API authentication is essential for developers extending its functionality or configuring custom storage providers. The application handles credentials securely across renderer and main processes, adapting its strategy to match each service's security requirements.

GitHub OAuth Device Flow for Script Marketplace

When users access the script marketplace, PicList initiates an OAuth Device Flow through IPC communication between the renderer and main processes. The UI triggers an authentication request that opens a browser window where users authorize the application using a device code.

In src/renderer/pages/ScriptPage.vue, lines 875–880 handle the authentication response:

// src/renderer/pages/ScriptPage.vue (lines 875-880)
const authResult: IGitHubAuth = await window.electron.triggerRPC('github-auth-request')
if (authResult.isAuthenticated) {
  this.githubUsername = authResult.username
  this.$message.success(`Authenticated as ${authResult.username}`)
}

The backend implementation in src/main/utils/githubAuth.ts manages the device code generation, opens the system browser, and polls GitHub's OAuth endpoints until the user completes authorization. Once confirmed, it returns the IGitHubAuth object containing isAuthenticated status and the GitHub username.

Bearer Token Authentication for Cloud Sync Settings

For synchronizing user settings across devices, PicList employs Bearer token authentication. The sync utility reads the token from user configuration and attaches it to all HTTP requests via a custom TOKEN scheme.

In src/main/utils/syncSettings.ts, line 102 implements the header injection:

// src/main/utils/syncSettings.ts (line 102)
const response = await fetch(syncConfig.server, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `TOKEN ${syncConfig.token}`
  },
  body: JSON.stringify(settingsData)
})

Users provide the syncConfig.token through the settings interface, allowing PicList to authenticate against private sync servers without storing credentials in cloud storage.

WebDAV Authentication: Basic vs Digest

PicList supports both Basic and Digest authentication for WebDAV storage backends. The authentication type is configurable in the settings UI, with the backend adapting its header generation strategy accordingly.

In src/renderer/pages/PicGoSetting.vue, line 1401 defines the configuration option:

<!-- src/renderer/pages/PicGoSetting.vue (line 1401) -->
<el-select v-model="webdavConfig.authType" placeholder="Select auth type">
  <el-option label="Basic" value="basic" />
  <el-option label="Digest" value="digest" />
</el-select>

For Digest authentication, src/main/utils/digestAuth.ts (lines 50–66) calculates the proper challenge-response hash:

// src/main/utils/digestAuth.ts (lines 50-66)
export function digestAuthHeader(
  username: string, 
  password: string, 
  challenge: WWWAuthenticateChallenge
): string {
  const ha1 = md5(`${username}:${challenge.realm}:${password}`)
  const ha2 = md5(`PUT:${challenge.uri}`)
  const response = md5(
    `${ha1}:${challenge.nonce}:${challenge.nc}:${challenge.cnonce}:auth:${ha2}`
  )
  return `Digest username="${username}", realm="${challenge.realm}", nonce="${challenge.nonce}", uri="${challenge.uri}", response="${response}"`
}

The WebDAV manager in src/main/manage/apis/webdavplist.ts detects the server's WWW-Authenticate header and selects the appropriate authentication method based on the user's configuration.

Signature-Based Authentication for Third-Party Services

Services like UpYun require HMAC signature-based authentication rather than simple tokens. PicList generates request signatures using the user's access key and includes them in the Authorization header.

In src/main/manage/apis/upyun.ts, line 275 constructs the signature:

// src/main/manage/apis/upyun.ts (line 275)
const date = new Date().toUTCString()
const signString = `PUT&/${bucket}${remotePath}&${date}`
const sign = crypto.createHmac('sha1', accessKey).update(signString).digest('base64')
const authorization = `TOKEN ${accessKey}:${sign}`

// Used in request headers
headers: {
  'Authorization': authorization,
  'Date': date
}

This approach ensures that requests to UpYun storage are cryptographically signed and cannot be replayed or forged without the secret access key.

Securing Custom HTTP APIs

When configuring custom "PicBed" endpoints, users can specify an uploadServerKey to prevent unauthorized API usage. This key acts as a shared secret between the PicList client and the custom upload server.

In src/renderer/pages/PicGoSetting.vue, line 855 shows the configuration field:

<!-- src/renderer/pages/PicGoSetting.vue (line 855) -->
<el-input 
  v-model="customPicBed.uploadServerKey" 
  placeholder="Enter API key for upload server authentication"
  type="password"
  show-password
/>

The upload implementation transmits this key in the request headers or body, depending on the custom endpoint's requirements:

// Custom upload request implementation
const uploadToCustomServer = async (imageBuffer: Buffer, apiKey: string) => {
  return fetch(customUploadURL, {
    method: 'POST',
    headers: {
      'Content-Type': 'image/png',
      'X-PicList-Auth': apiKey
    },
    body: imageBuffer
  })
}

Summary

• GitHub OAuth Device Flow handles marketplace authentication via IPC between src/renderer/pages/ScriptPage.vue and src/main/utils/githubAuth.ts, returning an IGitHubAuth object upon success
• Bearer tokens secure cloud sync operations through src/main/utils/syncSettings.ts, using the TOKEN <token> scheme in Authorization headers
• WebDAV storage supports both Basic and Digest authentication, with src/main/utils/digestAuth.ts generating MD5 digest responses for challenge-based auth
• HMAC signatures authenticate UpYun requests in src/main/manage/apis/upyun.ts, creating SHA1-based tokens that combine access keys with request metadata
• Custom API keys allow users to secure private upload endpoints through the uploadServerKey configuration in src/renderer/pages/PicGoSetting.vue

Frequently Asked Questions

What authentication method does PicList use for GitHub integration?

PicList implements the OAuth Device Flow for GitHub authentication as defined in src/main/utils/githubAuth.ts. When accessing the script marketplace, the renderer process calls window.electron.triggerRPC to request authentication, which opens a system browser where users enter a device code. Once authorized, the main process receives an IGitHubAuth object containing isAuthenticated status and the GitHub username, communicated back to the UI via IPC.

How does PicList store authentication tokens for cloud sync?

Cloud sync tokens are stored in the user's local configuration object and transmitted as Bearer tokens using a custom TOKEN scheme. Specifically, src/main/utils/syncSettings.ts constructs the Authorization header as TOKEN ${syncConfig.token} (line 102), allowing secure synchronization across devices without exposing credentials in the sync payload itself.

Can PicList use Digest authentication for WebDAV servers?

Yes, PicList supports both Basic and Digest authentication for WebDAV storage. When Digest is selected in src/renderer/pages/PicGoSetting.vue (line 1401), the application uses src/main/utils/digestAuth.ts (lines 50–66) to calculate the MD5 hash response based on the server's WWW-Authenticate challenge, including the proper nonce, realm, and cnonce values in the Authorization header.

How are third-party service credentials like UpYun handled?

For signature-based services, PicList generates HMAC-SHA1 signatures using the user's access key. In src/main/manage/apis/upyun.ts (line 275), the application creates a base64-encoded signature of the request method, URI, and date, then formats it as TOKEN <accessKey>:<sign> in the Authorization header, ensuring cryptographic verification of each request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}