Add sourceHeaders and conditional OIDC groups

Add support for passing sourceHeaders when fetching NZB/torrent files: extend AddDownloadOptions and SABnzbd AddNZBOptions, forward headers in sabnzbd and nzbget clients, and populate sourceHeaders in download-torrent.processor (injecting Prowlarr API key as X-Api-Key for proxy URLs). Make OIDC request scope conditional: only include the 'groups' scope when group-based access control or admin-claim is enabled (update provider logic, add tests, and update setup UI text). Also remove explicit take:100 in Plex processors and add CLAUDE guidance about requesting approval before implementing code changes.

CLAUDE.md

@@ -4,6 +4,14 @@
 
 **ALWAYS DO:** When you feel work is complete, use the docker compose build readmebook to confirm you have no errors. If the build succeeds, then you can tell me it is ready to be tested.
 
+**NEVER implement without approval.** When asked to assess, investigate, or fix a problem:
+1. **Research & analyze** — Read code, trace the issue, identify root cause.
+2. **Present a solution plan** — Explain the root cause, list the specific files and changes needed, and describe the approach clearly.
+3. **Wait for explicit approval** — Do NOT write any code until the user confirms the plan.
+4. Only after approval: implement, build, and report results.
+
+This applies to bug fixes, feature requests, and any code changes. Investigation and analysis are always fine — writing code is not until approved.
+
 ---
 
 ## 1. Token-Efficient Documentation System

src/app/setup/steps/OIDCConfigStep.tsx

@@ -272,7 +272,7 @@ export function OIDCConfigStep({
               <ul className="text-sm text-blue-700 dark:text-blue-300 mt-1 space-y-1">
                 <li>• The redirect URI will be: {typeof window !== 'undefined' ? `${window.location.origin}/api/auth/oidc/callback` : '[Your Domain]/api/auth/oidc/callback'}</li>
                 <li>• Configure this redirect URI in your OIDC provider settings</li>
-                <li>• Required scopes: openid, profile, email, groups</li>
+                <li>• Required scopes: openid, profile, email (groups is added automatically when group-based access control is enabled)</li>
               </ul>
             </div>
           </div>

src/lib/integrations/nzbget.service.ts

@@ -226,6 +226,7 @@ export class NZBGetService implements IDownloadClient {
         responseType: 'arraybuffer',
         timeout: 30000,
         maxRedirects: 5,
+        headers: options?.sourceHeaders,
         httpsAgent: url.startsWith('https') ? this.httpsAgent : undefined,
       });
 

src/lib/integrations/sabnzbd.service.ts

@@ -24,6 +24,8 @@ export interface AddNZBOptions {
   category?: string;
   priority?: 'low' | 'normal' | 'high' | 'force';
   paused?: boolean;
+  /** Headers to include when fetching the NZB from the source URL */
+  sourceHeaders?: Record<string, string>;
 }
 
 export interface NZBInfo {
@@ -492,6 +494,7 @@ export class SABnzbdService implements IDownloadClient {
         responseType: 'arraybuffer',
         timeout: 30000,
         maxRedirects: 5,
+        headers: options?.sourceHeaders,
         // Use the same SSL settings as the SABnzbd client if the NZB URL
         // happens to be served over HTTPS with a self-signed cert
         httpsAgent: url.startsWith('https') ? this.httpsAgent : undefined,
@@ -787,6 +790,7 @@ export class SABnzbdService implements IDownloadClient {
       category: options?.category,
       priority: options?.priority ? priorityMap[options.priority] || 'normal' : undefined,
       paused: options?.paused,
+      sourceHeaders: options?.sourceHeaders,
     });
   }
 

src/lib/interfaces/download-client.interface.ts

@@ -102,6 +102,8 @@ export interface AddDownloadOptions {
   priority?: string;
   /** Whether to add in paused state */
   paused?: boolean;
+  /** Headers to include when fetching the source file (e.g. Prowlarr API key for proxy URLs) */
+  sourceHeaders?: Record<string, string>;
 }
 
 /** Result of a connection test */

src/lib/processors/download-torrent.processor.ts

@@ -58,10 +58,19 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
 
     logger.info(`Routing to ${client.clientType} (${client.protocol})`);
 
+    // Include Prowlarr API key as source header so NZB/torrent downloads from
+    // Prowlarr proxy URLs are authenticated (fixes 403 for indexers like NZBFinder)
+    const prowlarrApiKey = (await config.getMany(['prowlarr_api_key'])).prowlarr_api_key || process.env.PROWLARR_API_KEY;
+    const sourceHeaders: Record<string, string> = {};
+    if (prowlarrApiKey) {
+      sourceHeaders['X-Api-Key'] = prowlarrApiKey;
+    }
+
     // Add download via unified interface
     const downloadClientId = await client.addDownload(torrent.downloadUrl, {
       category,
       priority: 'normal',
+      sourceHeaders,
     });
 
     logger.info(`Download added with ID: ${downloadClientId}`);

src/lib/processors/plex-recently-added.processor.ts

@@ -265,7 +265,7 @@ export async function processPlexRecentlyAddedCheck(payload: PlexRecentlyAddedPa
           },
         },
       },
-      take: 100,
+
     });
 
     if (matchableRequests.length > 0) {

src/lib/processors/scan-plex.processor.ts

@@ -450,7 +450,7 @@ export async function processScanPlex(payload: ScanPlexPayload): Promise<any> {
           },
         },
       },
-      take: 100, // Increased from 50 to handle more eligible requests
+
     });
 
     logger.info(`Found ${matchableRequests.length} matchable requests (all non-terminal statuses)`);

src/lib/services/auth/OIDCAuthProvider.ts

@@ -98,9 +98,15 @@ export class OIDCAuthProvider implements IAuthProvider {
         timestamp: Date.now(),
       });
 
+      // Only request 'groups' scope when group-based features are configured
+      const accessMethod = await this.configService.get('oidc.access_control_method');
+      const adminClaimEnabled = await this.configService.get('oidc.admin_claim_enabled');
+      const needsGroups = accessMethod === 'group_claim' || adminClaimEnabled === 'true';
+      const scope = needsGroups ? 'openid profile email groups' : 'openid profile email';
+
       // Generate authorization URL
       const redirectUrl = client.authorizationUrl({
-        scope: 'openid profile email groups',
+        scope,
         state,
         nonce,
         code_challenge: codeChallenge,

tests/services/auth/oidc-auth-provider.test.ts

@@ -128,6 +128,64 @@ describe('OIDCAuthProvider', () => {
     expect(result.state).toBe('state-1');
   });
 
+  it('omits groups scope when access control does not need it', async () => {
+    setConfig({
+      'oidc.issuer_url': 'https://issuer',
+      'oidc.client_id': 'client',
+      'oidc.client_secret': 'secret',
+      'oidc.access_control_method': 'open',
+    });
+
+    clientMock.authorizationUrl.mockReturnValue('https://issuer/auth');
+
+    const { OIDCAuthProvider } = await import('@/lib/services/auth/OIDCAuthProvider');
+    const provider = new OIDCAuthProvider();
+    await provider.initiateLogin();
+
+    expect(clientMock.authorizationUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ scope: 'openid profile email' })
+    );
+  });
+
+  it('includes groups scope when access control uses group_claim', async () => {
+    setConfig({
+      'oidc.issuer_url': 'https://issuer',
+      'oidc.client_id': 'client',
+      'oidc.client_secret': 'secret',
+      'oidc.access_control_method': 'group_claim',
+    });
+
+    clientMock.authorizationUrl.mockReturnValue('https://issuer/auth');
+
+    const { OIDCAuthProvider } = await import('@/lib/services/auth/OIDCAuthProvider');
+    const provider = new OIDCAuthProvider();
+    await provider.initiateLogin();
+
+    expect(clientMock.authorizationUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ scope: 'openid profile email groups' })
+    );
+  });
+
+  it('includes groups scope when admin claim is enabled', async () => {
+    setConfig({
+      'oidc.issuer_url': 'https://issuer',
+      'oidc.client_id': 'client',
+      'oidc.client_secret': 'secret',
+      'oidc.access_control_method': 'allowed_list',
+      'oidc.admin_claim_enabled': 'true',
+    });
+
+    clientMock.authorizationUrl.mockReturnValue('https://issuer/auth');
+
+    const { OIDCAuthProvider } = await import('@/lib/services/auth/OIDCAuthProvider');
+    const provider = new OIDCAuthProvider();
+    await provider.initiateLogin();
+
+    expect(clientMock.authorizationUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ scope: 'openid profile email groups' })
+    );
+  });
+
   it('throws when OIDC is not fully configured', async () => {
     setConfig({
       'oidc.issuer_url': null,