PDFCLOUD-5556 Add digital signature support

AGENTS.md

@@ -71,6 +71,9 @@
 - Avoid `@field_validator` on payload models. Prefer existing `BeforeValidator`
   helpers (e.g., `_allowed_mime_types`) so validation remains declarative and
   consistent across schemas.
+- In Pydantic validators, raise `ValueError`/`AssertionError` (or
+  `PydanticCustomError` when needed), not `TypeError`, so callers consistently
+  receive `ValidationError` surfaces.
 - Keep user-facing `PdfRestClient` and `AsyncPdfRestClient` endpoint helpers
   thin: they should primarily assemble payload dicts and delegate validation to
   payload models (`model_validate`). Avoid duplicating payload validation in
@@ -128,6 +131,10 @@
   helpers should pass sequences through without converting to raw IDs manually.
 - When a payload accepts uploaded content, validate MIME types via
   `_allowed_mime_types` to surface clear errors before making the request.
+- Payload models should mirror pdfRest's request layout field-for-field. Do not
+  use `@model_serializer` on payload models. If callers need a friendlier input
+  shape, use `@model_validator(mode="before")` to map inputs onto the existing
+  pdfRest fields, and keep any wire formatting in field serializers.
 - When an endpoint expects JSON-encoded structures (e.g., arrays of redaction
   rules), expose typed arguments (TypedDicts, Literals, etc.) via
   `pdfrest.types` and let the payload serializer produce the JSON string for the

src/pdfrest/client.py

@@ -111,6 +111,7 @@
     PdfRedactionPreviewPayload,
     PdfRestRawFileResponse,
     PdfRestrictPayload,
+    PdfSignPayload,
     PdfSplitPayload,
     PdfTextWatermarkPayload,
     PdfToExcelPayload,
@@ -156,6 +157,8 @@
     PdfRedactionInstruction,
     PdfRestriction,
     PdfRGBColor,
+    PdfSignatureConfiguration,
+    PdfSignatureCredentials,
     PdfTextColor,
     PdfXType,
     PngColorModel,
@@ -3212,6 +3215,42 @@ def add_attachment_to_pdf(
             timeout=timeout,
         )
 
+    def sign_pdf(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        signature_configuration: PdfSignatureConfiguration,
+        credentials: PdfSignatureCredentials,
+        logo: PdfRestFile | Sequence[PdfRestFile] | None = None,
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Digitally sign a PDF using PFX credentials or a certificate/private key."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "signature_configuration": signature_configuration,
+            "credentials": credentials,
+        }
+
+        if logo is not None:
+            payload["logo"] = logo
+        if output is not None:
+            payload["output"] = output
+
+        return self._post_file_operation(
+            endpoint="/signed-pdf",
+            payload=payload,
+            payload_model=PdfSignPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def blank_pdf(
         self,
         *,
@@ -5109,6 +5148,42 @@ async def add_attachment_to_pdf(
             timeout=timeout,
         )
 
+    async def sign_pdf(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        signature_configuration: PdfSignatureConfiguration,
+        credentials: PdfSignatureCredentials,
+        logo: PdfRestFile | Sequence[PdfRestFile] | None = None,
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Digitally sign a PDF using PFX credentials or a certificate/private key."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "signature_configuration": signature_configuration,
+            "credentials": credentials,
+        }
+
+        if logo is not None:
+            payload["logo"] = logo
+        if output is not None:
+            payload["output"] = output
+
+        return await self._post_file_operation(
+            endpoint="/signed-pdf",
+            payload=payload,
+            payload_model=PdfSignPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def blank_pdf(
         self,
         *,

src/pdfrest/models/_internal.py

@@ -229,6 +229,12 @@ def _serialize_text_objects(value: list[BaseModel]) -> str:
     return to_json(payload).decode()
 
 
+def _serialize_signature_configuration(
+    value: _PdfSignatureConfigurationModel,
+) -> str:
+    return value.model_dump_json(exclude_none=True)
+
+
 def _allowed_mime_types(
     allowed_mime_types: str, *more_allowed_mime_types: str, error_msg: str | None
 ) -> Callable[[Any], Any]:
@@ -242,7 +248,10 @@ def allowed_mime_types_validator(
                 _ = allowed_mime_types_validator(item)
             return value
         if value.type not in combined_allowed_mime_types:
-            msg = error_msg or f"The file type must be one of: {allowed_mime_types}"
+            msg = (
+                error_msg
+                or f"The file type must be one of: {combined_allowed_mime_types}"
+            )
             raise ValueError(msg)
         return value
 
@@ -978,6 +987,44 @@ class PdfPresetRedactionModel(BaseModel):
     value: PdfRedactionPreset
 
 
+class _PdfSignaturePointModel(BaseModel):
+    x: float
+    y: float
+
+
+class _PdfSignatureLocationModel(BaseModel):
+    bottom_left: _PdfSignaturePointModel
+    top_right: _PdfSignaturePointModel
+    page: str | int
+
+
+class _PdfSignatureDisplayModel(BaseModel):
+    include_distinguished_name: bool | None = None
+    include_datetime: bool | None = None
+    contact: str | None = None
+    location: str | None = None
+    name: str | None = None
+    reason: str | None = None
+
+
+class _PdfSignatureConfigurationModel(BaseModel):
+    type: Literal["new", "existing"]
+    name: str | None = None
+    logo_opacity: Annotated[float | None, Field(gt=0, le=1, default=None)] = None
+    location: _PdfSignatureLocationModel | None = None
+    display: _PdfSignatureDisplayModel | None = None
+
+    @model_validator(mode="after")
+    def _validate_location_requirements(self) -> _PdfSignatureConfigurationModel:
+        if self.type == "new" and self.location is None:
+            msg = (
+                "Missing location information for a new digital signature field. "
+                "See documentation for required fields."
+            )
+            raise ValueError(msg)
+        return self
+
+
 _PdfRedactionVariant = Annotated[
     PdfLiteralRedactionModel | PdfRegexRedactionModel | PdfPresetRedactionModel,
     Field(discriminator="type"),
@@ -1435,6 +1482,190 @@ class PdfExportFormDataPayload(BaseModel):
     ] = None
 
 
+class PdfSignPayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready sign request payload."""
+
+    files: Annotated[
+        list[PdfRestFile],
+        Field(
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("file", "files"),
+            serialization_alias="id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types("application/pdf", error_msg="Must be a PDF file")
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ]
+    signature_configuration: Annotated[
+        _PdfSignatureConfigurationModel,
+        Field(serialization_alias="signature_configuration"),
+        PlainSerializer(_serialize_signature_configuration),
+    ]
+    pfx_credential: Annotated[
+        list[PdfRestFile] | None,
+        Field(
+            default=None,
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("pfx", "pfx_credential"),
+            serialization_alias="pfx_credential_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types(
+                "application/x-pkcs12",
+                "application/pkcs12",
+                "application/octet-stream",
+                error_msg="PFX credentials must be a .pfx or .p12 file",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ] = None
+    pfx_passphrase: Annotated[
+        list[PdfRestFile] | None,
+        Field(
+            default=None,
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("pfx_passphrase", "passphrase"),
+            serialization_alias="pfx_passphrase_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types(
+                "text/plain",
+                "application/octet-stream",
+                error_msg="PFX passphrase must be a text file",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ] = None
+    certificate: Annotated[
+        list[PdfRestFile] | None,
+        Field(
+            default=None,
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("certificate", "cert"),
+            serialization_alias="certificate_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            # DER cert/key uploads are frequently tagged as x509-ca-cert (or octet-stream
+            # in some environments), so we intentionally keep this allowlist broad.
+            _allowed_mime_types(
+                "application/pkix-cert",
+                "application/x-x509-ca-cert",
+                "application/x-pem-file",
+                "application/pem-certificate-chain",
+                "application/octet-stream",
+                error_msg="Certificate must be a .pem or .der file",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ] = None
+    private_key: Annotated[
+        list[PdfRestFile] | None,
+        Field(
+            default=None,
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("private_key", "key"),
+            serialization_alias="private_key_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            # Keep parity with provider/browser MIME detection for DER private keys.
+            _allowed_mime_types(
+                "application/pkix-cert",
+                "application/x-x509-ca-cert",
+                "application/pkcs8",
+                "application/x-pem-file",
+                "application/pem-certificate-chain",
+                "application/octet-stream",
+                error_msg="Private key must be a .pem or .der file",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ] = None
+    logo: Annotated[
+        list[PdfRestFile] | None,
+        Field(
+            default=None,
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("logo", "logos"),
+            serialization_alias="logo_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types(
+                "image/jpeg",
+                "image/png",
+                "image/tiff",
+                "image/bmp",
+                error_msg="Logo must be an image file",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ] = None
+    output: Annotated[
+        str | None,
+        Field(serialization_alias="output", min_length=1, default=None),
+        AfterValidator(_validate_output_prefix),
+    ] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_credentials(cls, data: Any) -> Any:
+        if not isinstance(data, Mapping):
+            return data
+
+        payload = cast(Mapping[object, Any], data)
+        credentials = payload.get("credentials")
+        if credentials is None:
+            return {str(key): value for key, value in payload.items()}
+        if not isinstance(credentials, Mapping):
+            msg = (
+                "credentials must be a mapping with either pfx/passphrase or "
+                "certificate/private_key."
+            )
+            raise ValueError(msg)  # noqa: TRY004
+
+        normalized: dict[str, Any] = {str(key): value for key, value in payload.items()}
+        credential_map = cast(Mapping[object, Any], credentials)
+        for raw_key, value in credential_map.items():
+            key = str(raw_key)
+            if key not in normalized:
+                normalized[key] = value
+        return normalized
+
+    @model_validator(mode="after")
+    def _validate_credentials(self) -> PdfSignPayload:
+        has_pfx = self.pfx_credential is not None or self.pfx_passphrase is not None
+        has_pem = self.certificate is not None or self.private_key is not None
+
+        if has_pfx and has_pem:
+            msg = "Provide either PFX credentials (pfx + passphrase) or certificate/private_key, not both."
+            raise ValueError(msg)
+        if has_pfx:
+            if not self.pfx_credential or not self.pfx_passphrase:
+                msg = "Both pfx and passphrase are required when supplying PFX credentials."
+                raise ValueError(msg)
+        elif has_pem:
+            if not self.certificate or not self.private_key:
+                msg = "Both certificate and private_key are required when supplying PEM/DER credentials."
+                raise ValueError(msg)
+        else:
+            msg = "Either PFX credentials (pfx + passphrase) or certificate/private_key credentials are required."
+            raise ValueError(msg)
+
+        return self
+
+
 class PdfCompressPayload(BaseModel):
     """Adapt caller options into a pdfRest-ready compress request payload."""