fix: API correctness issues (SSRF protection, docs alignment)

- Add allowUrlFetch option to client options (default: false)
- Block automatic URL fetching by default for SSRF protection
- Validate URL protocols (only http/https allowed)
- Add helper method normalizeFileInput() to client
- Update README.md with import statement in Quick Start
- Add SSRF protection documentation section to README
- Update and add tests for SSRF protection behavior

Security: SSRF protection requires explicit opt-in for URL fetching.
Users must set allowUrlFetch: true to enable client-side URL fetching.

Author: jdrhyne

README.md

@@ -60,11 +60,29 @@ The documentation for Nutrient DWS TypeScript Client is also available on [Conte
 ## Quick Start
 
 ```typescript
+import { NutrientClient } from '@nutrient-sdk/dws-client-typescript';
+
 const client = new NutrientClient({
   apiKey: 'nutr_sk_your_secret_key'
 });
 ```
 
+### URL Fetching (SSRF Protection)
+
+By default, the SDK blocks automatic fetching of content from URLs to protect against Server-Side Request Forgery (SSRF) attacks. To enable URL fetching for trusted sources:
+
+```typescript
+const client = new NutrientClient({
+  apiKey: 'nutr_sk_your_secret_key',
+  allowUrlFetch: true  // Enable URL fetching (use with caution)
+});
+
+// Now you can pass URLs directly
+const result = await client.convert('https://trusted-source.com/document.pdf', 'pdf');
+```
+
+**⚠️ Security Warning:** Only enable `allowUrlFetch` if you control the URLs being processed. Never enable it when processing untrusted user input.
+
 ## Direct Methods
 
 The client provides numerous methods for document processing:

package-lock.json

@@ -239,6 +239,71 @@ describe('NutrientClient', () => {
           }),
       ).toThrow('Base URL must be a string');
     });
+
+    it('should accept allowUrlFetch option', () => {
+      const clientWithUrlFetch = new NutrientClient({
+        apiKey: 'test-key',
+        allowUrlFetch: true,
+      });
+      expect(clientWithUrlFetch).toBeDefined();
+
+      const clientWithoutUrlFetch = new NutrientClient({
+        apiKey: 'test-key',
+        allowUrlFetch: false,
+      });
+      expect(clientWithoutUrlFetch).toBeDefined();
+    });
+  });
+
+  describe('SSRF Protection', () => {
+    let client: NutrientClient;
+
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it('should pass allowUrlFetch=false to processRemoteFileInput by default', async () => {
+      (inputsModule.isRemoteFileInput as jest.Mock).mockReturnValue(true);
+      (inputsModule.processRemoteFileInput as jest.Mock).mockRejectedValue(
+        new ValidationError('SSRF protection: URL fetching disabled'),
+      );
+
+      client = new NutrientClient({
+        apiKey: 'test-key',
+      });
+
+      await expect(client.sign('https://example.com/test.pdf')).rejects.toThrow(
+        /SSRF protection/,
+      );
+      expect(inputsModule.processRemoteFileInput).toHaveBeenCalledWith(
+        'https://example.com/test.pdf',
+        false,
+      );
+    });
+
+    it('should pass allowUrlFetch=true when configured', async () => {
+      const mockBuffer = TestDocumentGenerator.generateSimplePdf('Test');
+      (inputsModule.isRemoteFileInput as jest.Mock).mockReturnValue(true);
+      (inputsModule.processRemoteFileInput as jest.Mock).mockResolvedValue({
+        data: mockBuffer,
+        filename: 'test.pdf',
+      });
+      (inputsModule.isValidPdf as jest.Mock).mockResolvedValue(true);
+      (httpModule.sendRequest as jest.Mock).mockResolvedValue({
+        data: mockBuffer,
+      });
+
+      client = new NutrientClient({
+        apiKey: 'test-key',
+        allowUrlFetch: true,
+      });
+
+      await client.sign('https://example.com/test.pdf');
+      expect(inputsModule.processRemoteFileInput).toHaveBeenCalledWith(
+        'https://example.com/test.pdf',
+        true,
+      );
+    });
   });
 
   describe('workflow()', () => {

src/__tests__/unit/client.test.ts

@@ -235,14 +235,40 @@ describe('Input Processing (Node.js only)', () => {
       (fetch as jest.Mock).mockClear();
     });
 
-    it('should process URL string input', async () => {
+    describe('SSRF Protection', () => {
+      it('should throw ValidationError when allowUrlFetch is false (default)', async () => {
+        await expect(processRemoteFileInput('https://example.com/test.pdf')).rejects.toThrow(
+          ValidationError,
+        );
+        await expect(
+          processRemoteFileInput('https://example.com/test.pdf'),
+        ).rejects.toThrow(/SSRF protection/);
+      });
+
+      it('should throw ValidationError when allowUrlFetch is explicitly false', async () => {
+        await expect(
+          processRemoteFileInput('https://example.com/test.pdf', false),
+        ).rejects.toThrow(ValidationError);
+      });
+
+      it('should throw ValidationError for non-http/https protocols', async () => {
+        await expect(
+          processRemoteFileInput('file:///etc/passwd', true),
+        ).rejects.toThrow(/Invalid URL protocol/);
+        await expect(
+          processRemoteFileInput('ftp://example.com/file.pdf', true),
+        ).rejects.toThrow(/Invalid URL protocol/);
+      });
+    });
+
+    it('should process URL string input when allowUrlFetch is true', async () => {
       const mockResponse = {
         ok: true,
         arrayBuffer: jest.fn().mockResolvedValue(new ArrayBuffer(10)),
       };
       (fetch as jest.Mock).mockResolvedValue(mockResponse);
 
-      const result = await processRemoteFileInput('https://example.com/test.pdf');
+      const result = await processRemoteFileInput('https://example.com/test.pdf', true);
 
       expect(fetch).toHaveBeenCalledWith('https://example.com/test.pdf');
       expect(mockResponse.arrayBuffer).toHaveBeenCalled();
@@ -253,7 +279,7 @@ describe('Input Processing (Node.js only)', () => {
       });
     });
 
-    it('should process URL object input', async () => {
+    it('should process URL object input when allowUrlFetch is true', async () => {
       const mockResponse = {
         ok: true,
         arrayBuffer: jest.fn().mockResolvedValue(new ArrayBuffer(10)),
@@ -263,7 +289,7 @@ describe('Input Processing (Node.js only)', () => {
       const result = await processRemoteFileInput({
         type: 'url',
         url: 'https://example.com/test.pdf',
-      });
+      }, true);
 
       expect(fetch).toHaveBeenCalledWith('https://example.com/test.pdf');
       expect(mockResponse.arrayBuffer).toHaveBeenCalled();
@@ -282,15 +308,15 @@ describe('Input Processing (Node.js only)', () => {
       };
       (fetch as jest.Mock).mockResolvedValue(mockResponse);
 
-      await expect(processRemoteFileInput('https://example.com/test.pdf')).rejects.toThrow(
+      await expect(processRemoteFileInput('https://example.com/test.pdf', true)).rejects.toThrow(
         ValidationError,
       );
     });
 
     it('should throw ValidationError when fetch fails', async () => {
       (fetch as jest.Mock).mockRejectedValue(new Error('Network error'));
 
-      await expect(processRemoteFileInput('https://example.com/test.pdf')).rejects.toThrow(
+      await expect(processRemoteFileInput('https://example.com/test.pdf', true)).rejects.toThrow(
         ValidationError,
       );
     });