SecurityApi

The Security dialog, headless. protect() and removeProtection() need the export feature (password protection ships with the file) and refuse with FEATURE_NOT_LICENSED without it; isEncrypted, permissions and unlockOwnerPermissions() need none. Permissions you do not mention stay allowed. High-quality printing is a degree of printing: print: false denies printHighQuality too, and permissions reports it denied whenever print is. Encryption applies to the open document and reaches the file through doc.save() — nothing on disk changes until you write those bytes somewhere.

What the viewer does with a document's permissions. A document opened with its open (user) password grants only what its permissions allow, and the viewer honors them as Acrobat does. Opened with its owner password, protected in this session, or after unlockOwnerPermissions(password) succeeds, everything is allowed — the viewer follows an unlock at once, and the unlock outlives every later reload (an edit, an undo). When the document forbids comments (annotate), Highlight, Mark text, Note, Text box, Draw, the shapes, Stamp, Link and Erase are grayed out, and so are the selection bar's markups and Add a note. Changes (modify): Edit text, Add text, Image, Sign, Erase and the selection bar's Black out are grayed out; attachments cannot be added or removed. Changing pages (assemble): Manage pages is grayed out, the thumbnails offer no rotate, move, duplicate or delete, and bookmarks cannot be edited. Filling in (fillForms, which the comment right also grants): form fields show their values read-only. Printing (print): Print is grayed out, print() and Ctrl+P refuse, and the browser's own print command prints blank pages. Copying (copy): the selection bar's Copy is grayed out, and copying from the page or from a read-only field puts nothing on the clipboard. A grayed-out control stays where it is: its tooltip says why, and a tap, click or Enter on it shows the reason instead of acting. activateTool() and print() refuse what is forbidden with PERMISSION_DENIED; toolBlockedReason(tool) gives the reason for a host's own chrome. There is no option to lift these: only the owner password does.

The document API (doc.pages, doc.annotations, doc.forms.setValues, doc.save(), …) is your own code acting on the file and is not restricted: permissions are the author's stated intent for the _people_ reading the document: a reader restricts its users, not an application its own code. Every PDF SDK reads it the same way, so a host that wants its own code held to the permissions reads doc.security.permissions and decides. What your code saves keeps the encryption and the bits as they are.

namespacedoc.security

Usage

TypeScript

await doc.security.protect({
  userPassword: 'open-me',
  ownerPassword: 'change-me',
  permissions: { modify: false, copy: false },
});

const bytes = await doc.save(); // the protection lives in these bytes

Reading

isEncryptedgettersince 1.0.0

get isEncrypted(): boolean

Whether the document is encrypted. A getter: answers at once, and throws DOCUMENT_CLOSED on a closed document.

Returns boolean

DOCUMENT_CLOSED — read on a closed document.

TypeScript

if (doc.security.isEncrypted) badge.hidden = false;

permissionsgettersince 1.0.0

get permissions(): Required<DocumentPermissions>

What the document allows, as a DocumentPermissions with every entry present. printHighQuality is reported denied whenever print is. A getter: answers at once, and throws DOCUMENT_CLOSED on a closed document.

Returns Required<DocumentPermissions> print, printHighQuality, modify, copy, annotate, fillForms, extractForAccessibility and assemble, every entry present.

DOCUMENT_CLOSED — read on a closed document.

TypeScript

// Hold your own code to the document's permissions
if (!doc.security.permissions.modify) throw new Error('This document forbids changes');

Protection

protectmethodsince 1.0.0

protect(settings: ProtectionSettings): Promise<void>

Encrypts with passwords and permissions (AES-256). Permissions you do not mention stay allowed. An owner password equal to the open password protects nothing — a reader who holds the owner password can lift every restriction — so restricting anything needs an ownerPassword that differs from userPassword. Protecting a signed document changes what the signature covers, so it would no longer verify: refused as Acrobat refuses, unless settings.invalidateSignatures, and once told, the session asks no more. Needs the export feature.

Parameter	Type	Description
settings	ProtectionSettings	`userPassword` (required to open the document at all; leave empty for a document anyone can open but only the owner can change), `ownerPassword` (required to change permissions or remove protection), `permissions` (a `DocumentPermissions`, all optional) and `invalidateSignatures`.

Returns Promise<void>

INVALID_ARGUMENT — no password at all, or restricting anything without an ownerPassword that differs from userPassword.
INVALID_STATE — a signed document, unless settings.invalidateSignatures; or a progressive document still downloading.
FEATURE_NOT_LICENSED — the license lacks export.
PAGE_ERROR — the document could not be encrypted.
DOCUMENT_CLOSED — the document has been closed.

TypeScript

// Anyone can open it; only the owner can print or change it
await doc.security.protect({
  ownerPassword: 'change-me',
  permissions: { print: false, modify: false },
});

removeProtectionmethodsince 1.0.0

removeProtection(options?: SignedDocumentOptions): Promise<void>

Removes encryption. Refuses a signed document, as Acrobat refuses, unless options.invalidateSignatures. Needs the export feature.

Parameter	Type	Description
options?	SignedDocumentOptions	`{ invalidateSignatures? }`.

Returns Promise<void>

INVALID_STATE — a signed document, unless options.invalidateSignatures; or a progressive document still downloading.
FEATURE_NOT_LICENSED — the license lacks export.
DOCUMENT_CLOSED — the document has been closed.

TypeScript

await doc.security.removeProtection();
const plain = await doc.save();

unlockOwnerPermissionsmethodsince 1.0.0

unlockOwnerPermissions(ownerPassword: string): Promise<boolean>

Unlocks a document opened with the user password. Once accepted, everything is allowed: the viewer follows the unlock at once, and the unlock outlives every later reload (an edit, an undo). Needs no feature.

Parameter	Type	Description
ownerPassword	string	The document's owner password.

Returns Promise<boolean> Whether the password was accepted.

DOCUMENT_CLOSED — the document has been closed.

TypeScript

const unlocked = await doc.security.unlockOwnerPermissions(ownerPassword);
if (!unlocked) showError('Wrong owner password');