Release/3.0.0 (#45)

* feat: add security changes

* Update docs/MIGRATION.md

Co-authored-by: Nick Winder <nfxdevelopment@gmail.com>

* Update docs/MIGRATION.md

Co-authored-by: Nick Winder <nfxdevelopment@gmail.com>

* Rename FileInputWithUrl to FileInput, add UrlFileInput alias

Replace the ambiguous FileInputWithUrl name with explicit type aliases:
- LocalFileInput = Path | bytes | BinaryIO (unchanged)
- UrlFileInput = str (new, explicit URL type)
- FileInput = UrlFileInput | LocalFileInput (combined, replaces FileInputWithUrl)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Fix rotate and delete_pages with negative page indices

- rotate(): change `start > 0` to `start != 0` so prefix pages are
  included when a negative start index is used (e.g. start=-3)
- delete_pages(): rewrite keep-range algorithm to handle negative
  delete indices; previously all-negative inputs raised a spurious
  ValidationError instead of keeping the correct page range

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Fix ruff per-file-ignores and remove unused variable in test

- pyproject.toml: add D102 to tests/* per-file-ignores so test methods
  are not required to have docstrings (the comment indicated this intent
  but the empty array had no effect)
- test_client.py: remove unused `result` assignment in
  test_password_protect_pdf_with_permissions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Sort __all__ in __init__.py

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Nick Winder <nfxdevelopment@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.0.0] - 2026-01-30
+
+### Security
+
+- **CRITICAL**: Removed client-side URL fetching to prevent SSRF vulnerabilities
+- URLs are now passed to the server for secure server-side fetching
+- Restricted `sign()` method to local files only (API limitation)
+
+### Changed
+
+- **BREAKING**: `sign()` only accepts local files (paths, bytes, file objects) - no URLs
+- **BREAKING**: Most methods now accept `FileInputWithUrl` - URLs passed to server
+- **BREAKING**: Removed client-side PDF parsing - leverage API's negative index support
+- Methods like `rotate()`, `split()`, `deletePages()` now support negative indices (-1 = last page)
+- All methods except `sign()` accept URLs that are passed securely to the server
+
+### Removed
+
+- **BREAKING**: Removed `process_remote_file_input()` from public API (security risk)
+- **BREAKING**: Removed `get_pdf_page_count()` from public API (client-side PDF parsing)
+- **BREAKING**: Removed `is_valid_pdf()` from public API (internal use only)
+- Removed ~200 lines of client-side PDF parsing code
+
+### Added
+
+- SSRF protection documentation in README
+- Migration guide (docs/MIGRATION.md)
+- Security best practices for handling remote files
+- Support for negative page indices in all page-based methods
+
+## [2.0.0] - 2025-01-09
+
+- Initial stable release with full API coverage
+- Async-first design with httpx and aiofiles
+- Comprehensive type hints and mypy strict mode
+- Workflow builder with staged pattern
+- Error hierarchy with typed exceptions

docs/MIGRATION.md

@@ -0,0 +1,75 @@
+# Migration Guide: v2.x to v3.0
+
+## Overview
+
+Version 3.0.0 introduces SSRF protection and removes client-side PDF parsing.
+
+## Key Changes
+
+### 1. `sign()` No Longer Accepts URLs (API Limitation)
+
+**Before (v2.x)**:
+```python
+result = await client.sign('https://example.com/document.pdf', {...})
+```
+
+**After (v3.0)** - Fetch file first:
+```python
+import httpx
+
+async with httpx.AsyncClient() as http:
+    url = 'https://example.com/document.pdf'
+
+    # IMPORTANT: Validate URL
+    if not url.startswith('https://trusted-domain.com/'):
+        raise ValueError('URL not from trusted domain')
+
+    response = await http.get(url, timeout=10.0)
+    response.raise_for_status()
+    pdf_bytes = response.content
+
+result = await client.sign(pdf_bytes, {...})
+```
+
+### 2. Most Methods Now Accept URLs (Passed directly to DWS)
+
+Good news! These methods now support URLs passed securely to the DWS:
+- `rotate()`, `split()`, `add_page()`, `duplicate_pages()`, `delete_pages()`
+- `set_page_labels()`, `set_metadata()`, `optimize()`
+- `flatten()`, `apply_instant_json()`, `apply_xfdf()`
+- All redaction methods
+- `convert()`, `ocr()`, `watermark_*()`, `extract_*()`, `merge()`, `password_protect()`
+
+**Example**:
+```python
+# This now works!
+result = await client.rotate('https://example.com/doc.pdf', 90, pages={'start': 0, 'end': 5})
+```
+
+### 3. Negative Page Indices Now Supported
+
+Use negative indices for "from end" references:
+- `-1` = last page
+- `-2` = second-to-last page
+- etc.
+
+**Examples**:
+```python
+# Rotate last 3 pages
+await client.rotate(pdf, 90, pages={'start': -3, 'end': -1})
+
+# Delete first and last pages
+await client.delete_pages(pdf, [0, -1])
+
+# Split: keep middle pages, excluding first and last
+await client.split(pdf, [{'start': 1, 'end': -2}])
+```
+
+### 4. Removed from Public API
+
+- `process_remote_file_input()` - No longer needed (URLs passed to server)
+- `get_pdf_page_count()` - Use negative indices instead
+- `is_valid_pdf()` - Let server validate (internal use only)
+
+**Still Available:**
+- `is_remote_file_input()` - Helper to detect if input is a URL (still public)

pyproject.toml

@@ -18,7 +18,7 @@ nutrient_dws_scripts = [
 
 [project]
 name = "nutrient-dws"
-version = "2.0.0"
+version = "3.0.0"
 description = "Python client library for Nutrient Document Web Services API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -112,7 +112,7 @@ ignore = [
 convention = "google"
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = []  # Don't require docstrings in tests, allow asserts
+"tests/*" = ["D102"]  # Don't require docstrings in tests
 
 [tool.mypy]
 python_version = "3.10"

src/nutrient_dws/__init__.py

@@ -12,24 +12,28 @@
     ValidationError,
 )
 from nutrient_dws.inputs import (
+    FileInput,
+    LocalFileInput,
+    UrlFileInput,
     is_remote_file_input,
     process_file_input,
-    process_remote_file_input,
     validate_file_input,
 )
 from nutrient_dws.utils import get_library_version, get_user_agent
 
 __all__ = [
     "APIError",
     "AuthenticationError",
+    "FileInput",
+    "LocalFileInput",
     "NetworkError",
     "NutrientClient",
     "NutrientError",
+    "UrlFileInput",
     "ValidationError",
     "get_library_version",
     "get_user_agent",
     "is_remote_file_input",
     "process_file_input",
-    "process_remote_file_input",
     "validate_file_input",
 ]

src/nutrient_dws/builder/builder.py

@@ -85,7 +85,7 @@ def _register_asset(self, asset: FileInput) -> str:
         """Register an asset in the workflow and return its key for use in actions.
 
         Args:
-            asset: The asset to register
+            asset: The asset to register (must be local, not URL)
 
         Returns:
             The asset key that can be used in BuildActions