Use XDG config dir for OAuth credentials

Author: msch-nutrient

README.md

@@ -236,7 +236,7 @@ The server authenticates to the Nutrient DWS API (`https://api.nutrient.io`) usi
 | **API key** | `NUTRIENT_DWS_API_KEY` is set | Static key passed as Bearer token to DWS API |
 | **OAuth browser flow** | No API key set | Opens browser for Nutrient OAuth consent, caches token locally |
 
-When no API key is configured, the server opens a browser-based OAuth flow on the first tool call (similar to `gh auth login`). Tokens are cached at `~/.nutrient/credentials.json` and refreshed automatically.
+When no API key is configured, the server opens a browser-based OAuth flow on the first tool call (similar to `gh auth login`). Tokens are cached at `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json` and refreshed automatically.
 
 ### Environment Variables
 
@@ -253,7 +253,7 @@ When no API key is configured, the server opens a browser-based OAuth flow on th
 
 ### Security Note: Token Storage
 
-When using the OAuth browser flow, access tokens and refresh tokens are cached in plaintext at `~/.nutrient/credentials.json` (permissions `0600`). This file contains credentials equivalent to your API key. Do not commit it to version control or include it in shared backups.
+When using the OAuth browser flow, access tokens and refresh tokens are cached in plaintext at `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json` (permissions `0600`). This file contains credentials equivalent to your API key. Do not commit it to version control or include it in shared backups.
 
 ## Troubleshooting
 
@@ -262,7 +262,7 @@ When using the OAuth browser flow, access tokens and refresh tokens are cached i
 If OAuth authentication stops working, delete the cached token file to start fresh:
 
 ```bash
-rm ~/.nutrient/credentials.json
+rm "${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json"
 ```
 
 The server will automatically register a new client and open the browser for consent on the next tool call.
@@ -282,7 +282,7 @@ The server will automatically register a new client and open the browser for con
 
 **"Token exchange failed" or "OAuth authorization failed"?**
 
-- Delete `~/.nutrient/credentials.json` and try again.
+- Delete `${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json` and try again.
 - If using a custom `AUTH_SERVER_URL`, verify the server is reachable and its `/oauth/token` endpoint is working.
 
 **"Dynamic client registration failed"?**
@@ -297,7 +297,7 @@ The server will automatically register a new client and open the browser for con
 
 **Token expired but refresh fails?**
 
-- The server automatically refreshes expired tokens using the cached refresh token. If refresh fails (e.g., the refresh token was revoked), delete `~/.nutrient/credentials.json` — the server will re-authenticate via the browser on the next call.
+- The server automatically refreshes expired tokens using the cached refresh token. If refresh fails (e.g., the refresh token was revoked), delete `${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json` — the server will re-authenticate via the browser on the next call.
 
 **Files not found?**
 

src/auth/nutrient-oauth.ts

@@ -23,7 +23,7 @@ export type NutrientOAuthConfig = {
   clientName?: string
   /** OAuth scopes to request. */
   scopes: string[]
-  /** Path to cache credentials. Defaults to `~/.nutrient/credentials.json`. */
+  /** Path to cache credentials. Defaults to `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json`. */
   credentialsPath?: string
   /** OAuth resource parameter (RFC 8707). Identifies the target API. */
   resource?: string
@@ -38,10 +38,17 @@ const CachedCredentialsSchema = z.object({
 
 type CachedCredentials = z.infer<typeof CachedCredentialsSchema>
 
-const DEFAULT_CREDENTIALS_PATH = join(homedir(), '.nutrient', 'credentials.json')
 const FETCH_TIMEOUT_MS = 15_000
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
 
+export function getDefaultCredentialsPath(
+  env: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = homedir(),
+): string {
+  const configHome = env.XDG_CONFIG_HOME || join(homeDirectory, '.config')
+  return join(configHome, 'nutrient', 'credentials.json')
+}
+
 export function generateCodeVerifier(): string {
   return randomBytes(32).toString('base64url')
 }
@@ -340,7 +347,7 @@ async function performBrowserOAuthFlow(config: NutrientOAuthConfig): Promise<Cac
  * is forced to refresh or re-authenticate.
  */
 export async function invalidateCachedToken(config: NutrientOAuthConfig): Promise<void> {
-  const credentialsPath = config.credentialsPath ?? DEFAULT_CREDENTIALS_PATH
+  const credentialsPath = config.credentialsPath ?? getDefaultCredentialsPath()
   try {
     await unlink(credentialsPath)
     logger.info('Invalidated cached token', { credentialsPath })
@@ -358,7 +365,7 @@ export async function invalidateCachedToken(config: NutrientOAuthConfig): Promis
  * and falls back to a browser-based OAuth flow if no valid token is available.
  */
 export async function getToken(config: NutrientOAuthConfig): Promise<string> {
-  const credentialsPath = config.credentialsPath ?? DEFAULT_CREDENTIALS_PATH
+  const credentialsPath = config.credentialsPath ?? getDefaultCredentialsPath()
 
   logger.debug('getToken called', { credentialsPath })
 

tests/nutrient-oauth.test.ts

@@ -7,6 +7,7 @@ import { createServer, type Server } from 'node:http'
 import {
   generateCodeVerifier,
   generateCodeChallenge,
+  getDefaultCredentialsPath,
   isTokenExpired,
   readCachedCredentials,
 } from '../src/auth/nutrient-oauth.js'
@@ -114,6 +115,20 @@ describe('readCachedCredentials', () => {
   })
 })
 
+describe('getDefaultCredentialsPath', () => {
+  it('uses XDG_CONFIG_HOME when set', () => {
+    const path = getDefaultCredentialsPath({ XDG_CONFIG_HOME: '/tmp/xdg-config' }, '/home/tester')
+
+    expect(path).toBe('/tmp/xdg-config/nutrient/credentials.json')
+  })
+
+  it('falls back to ~/.config when XDG_CONFIG_HOME is not set', () => {
+    const path = getDefaultCredentialsPath({}, '/home/tester')
+
+    expect(path).toBe('/home/tester/.config/nutrient/credentials.json')
+  })
+})
+
 // ---------------------------------------------------------------------------
 // getToken integration helpers
 // ---------------------------------------------------------------------------