Security API¶

namespace NextPDF\Core\Security;

final class Aes256Encryptor

/** 建立 AES-256 加密器 */
public static function create(): self

/**
 * 加密文件。
 *
 * @param Document          $document 要加密的文件
 * @param EncryptionOptions $options  加密選項
 * @return Document  加密後的新 Document 實例
 * @throws EncryptionException
 */
public function encrypt(Document $document, EncryptionOptions $options): Document

namespace NextPDF\Core\Security\ValueObjects;

final readonly class EncryptionOptions
{
    /**
     * @param string|null $userPassword  使用者密碼（null = 無需密碼即可開啟）
     * @param string      $ownerPassword 擁有者密碼（必填）
     * @param Permissions $permissions   文件權限
     */
    public static function create(
        ?string     $userPassword,
        string      $ownerPassword,
        Permissions $permissions = new Permissions(),
    ): self

    public static function default(): self  // 無密碼，允許所有權限
}

final class Permissions
{
    public static function create(): self

    /** 允許列印（可選：僅低解析度）*/
    public function allowPrinting(bool $highResolution = true): self

    /** 拒絕修改 */
    public function denyModification(): self

    /** 拒絕複製文字/圖形 */
    public function denyContentCopying(): self

    /** 拒絕新增/修改注釋 */
    public function denyAnnotation(): self

    /** 拒絕填寫表單 */
    public function denyFormFilling(): self

    /** 拒絕提取內容（無障礙例外）*/
    public function denyExtraction(): self

    /** 拒絕組合文件（合併、分割等）*/
    public function denyDocumentAssembly(): self

    /** 允許全部（預設）*/
    public static function allowAll(): self

    /** 拒絕全部（最嚴格）*/
    public static function denyAll(): self
}

namespace NextPDF\Core\Security;

final class PadesOrchestrator

/**
 * @param SigningCertificate $certificate 簽章憑證
 * @param ?LoggerInterface   $logger      PSR-3 日誌記錄器
 */
public static function create(
    SigningCertificate $certificate,
    ?LoggerInterface   $logger = null,
): self

/**
 * 對文件進行簽章。
 *
 * @param Document              $document   要簽章的文件
 * @param SignatureAppearance   $appearance 簽章外觀（可見 / 隱形）
 * @param string                $reason     簽章原因
 * @param string                $location   簽章地點
 * @param string                $contactInfo 連絡資訊
 * @return Document  簽章後的新 Document 實例
 * @throws SigningException
 */
public function sign(
    Document           $document,
    SignatureAppearance $appearance   = SignatureAppearance::INVISIBLE,
    string             $reason       = '',
    string             $location     = '',
    string             $contactInfo  = '',
): Document

final readonly class SigningCertificate
{
    /**
     * 從 PKCS#12（.p12 / .pfx）載入憑證。
     *
     * @param non-empty-string $path       .p12 / .pfx 檔案路徑
     * @param non-empty-string $passphrase 憑證密碼
     */
    public static function fromPkcs12(string $path, string $passphrase): self

    /**
     * 從 PEM 格式載入憑證。
     *
     * @param non-empty-string $certificate PEM 格式憑證（含鏈憑證）
     * @param non-empty-string $privateKey  PEM 格式私鑰
     * @param non-empty-string $passphrase  私鑰密碼（若有）
     */
    public static function fromPem(
        string $certificate,
        string $privateKey,
        string $passphrase = '',
    ): self

    public function subject(): string
    public function issuer(): string
    public function validFrom(): DateTimeImmutable
    public function validTo(): DateTimeImmutable
    public function isExpired(): bool
    public function fingerprint(): string   // SHA-256 指紋
}

final class SignatureAppearance
{
    /** 隱形簽章（不顯示在頁面上）*/
    public static function invisible(): self

    /**
     * 可見簽章（顯示在頁面指定位置）。
     *
     * @param Rectangle        $bounds   簽章方塊位置（mm）
     * @param Page             $page     顯示在哪一頁
     * @param ?EmbeddedImage   $image    簽名圖片（可選）
     * @param bool             $showText 是否顯示簽章資訊文字
     */
    public static function visible(
        Rectangle      $bounds,
        Page           $page,
        ?EmbeddedImage $image    = null,
        bool           $showText = true,
    ): self
}

namespace NextPDF\Core\Security;

final class DigitalSigner

public static function create(SigningCertificate $certificate): self

/** 計算文件的 ByteRange 和雜湊值 */
public function prepareForSigning(Document $document): SigningContext

/** 使用外部提供的簽章值完成簽章（適用 HSM / 遠端簽章）*/
public function completeSigning(
    Document       $document,
    SigningContext  $context,
    string         $signatureValue,  // DER 編碼的 PKCS#7 SignedData
): Document