Permissions

A document can be opened with less than full power: a link that lets people read and comment, a signing session that only fills in fields, a reviewer who may not download. The engine refuses everything else. This page is about building a UI that shows only what works, instead of buttons that fail.

Every verb has a check#

Every call that can be refused has a check next to it, named can and the verb. It answers one question: would this work right now, for this user?

annotation.canCreate(); // may they draw new annotations?
annotation.canUpdate(ref); // may they change this one?
selection.canCopy(); // may selected text leave the document?
form.canFill(ref); // may they fill in this field?
documents.canDownload(); // may they download the file?

A check already includes everything its call looks at: the user’s permissions, the flags on the document (a locked annotation, a read-only field) and what’s selected. You never combine them yourself, and you never read permission names: which permission a call needs is the plugin’s business, not yours.

The rule: show a button when its check is true. Read the check in your markup, like any other state: the answer changes when the selection changes or the user gets new permissions.

<script lang="ts">
  import { useAnnotation, type AnnotationRef } from '@embedpdf/svelte/annotation';
  import DrawingTools from './DrawingTools.svelte';

  let { annotationRef }: { annotationRef: AnnotationRef } = $props();

  const annotation = useAnnotation();
</script>

{#if annotation.canCreate()}
  <DrawingTools />
{/if}
<button disabled={!annotation.canDelete(annotationRef)}>Delete</button>

Each control below shows only when its check says yes. Pick another role, and the document opens again with its permissions:

<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { interactionPlugin } from '@embedpdf/svelte/interaction';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { SearchLayer, searchPlugin } from '@embedpdf/svelte/search';
  import { SelectionLayer, selectionPlugin } from '@embedpdf/svelte/selection';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { localEngine } from '@embedpdf/engine';
  import Controls from './Controls.svelte';
  import ReopenOnRoleChange from './ReopenOnRoleChange.svelte';

  import '../checks.css';

  const engine = localEngine();
  const plugins = [
    stagePlugin(),
    renderPlugin(),
    interactionPlugin(),
    selectionPlugin(),
    searchPlugin(),
  ];

  const welcome = async (): Promise<OpenInput> => {
    const response = await fetch('/pdfs/welcome.pdf');
    return { kind: 'bytes', bytes: new Uint8Array(await response.arrayBuffer()) };
  };

  // What each role may do, as permissions.
  const roles = {
    viewer: ['doc.open', 'doc.render', 'doc.text.select'],
    reviewer: ['doc.open', 'doc.render', 'doc.text.select', 'doc.text.copy', 'doc.text.search'],
    owner: [
      'doc.open',
      'doc.render',
      'doc.text.select',
      'doc.text.copy',
      'doc.text.search',
      'doc.download',
    ],
  };
  type Role = keyof typeof roles;
</script>

<script lang="ts">
  let role = $state<Role>('reviewer');
</script>

<Viewer
  {engine}
  {plugins}
  scope={roles[role]}
  initialDocuments={[{ source: welcome, name: 'welcome.pdf' }]}
>
  <div class="toolbar">
    <label class="label">
      Role
      <select class="select" bind:value={role}>
        <option value="viewer">viewer: read and select</option>
        <option value="reviewer">reviewer: also search and copy</option>
        <option value="owner">owner: also download</option>
      </select>
    </label>
  </div>
  <ReopenOnRoleChange {role} {welcome} />
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">Opening…</p>
    {/snippet}
    <Controls />
    <Stage class="stage">
      <RenderLayer />
      <SearchLayer />
      <SelectionLayer />
    </Stage>
  </DocumentGate>
</Viewer>

One answer per annotation#

Checks that take a ref answer for that one annotation, field or comment. In a shared document, a user may hold annotations:update:self: change their own annotations, and only look at the rest. You don’t handle that yourself. Someone else’s annotation answers canUpdate(ref) === false, and shows the way a locked one does: it can be selected and commented on, but has no handles. Forms work the same: a field the user may not fill shows as read-only.

Calling anyway is safe#

Checks are there to keep your UI honest; the engine doesn’t rely on them. A refused call rejects, the same way in every plugin:

<script lang="ts">
  import { isPluginError } from '@embedpdf/svelte/runtime';
  import { toFieldRef, useForm } from '@embedpdf/svelte/form';

  const form = useForm();

  async function setTotal() {
    try {
      await form.setValue(toFieldRef('total'), { value: '120.00' });
    } catch (error) {
      if (isPluginError(error, 'permission-denied')) {
        console.log(error.permission); // what was missing, such as 'doc.forms.fill'
      }
    }
  }
</script>

<button onclick={setTotal}>Set the total</button>

<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { localEngine } from '@embedpdf/engine';
  import DownloadAnyway from './DownloadAnyway.svelte';

  import '../refused.css';

  const engine = localEngine();
  const plugins = [stagePlugin(), renderPlugin()];

  const welcome = async (): Promise<OpenInput> => {
    const response = await fetch('/pdfs/welcome.pdf');
    return { kind: 'bytes', bytes: new Uint8Array(await response.arrayBuffer()) };
  };

  // Read and select, but no downloading.
  const scope = ['doc.open', 'doc.render', 'doc.text.select'];
</script>

<Viewer {engine} {plugins} {scope} initialDocuments={[{ source: welcome }]}>
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">Opening…</p>
    {/snippet}
    <DownloadAnyway />
    <Stage class="stage">
      <RenderLayer />
    </Stage>
  </DocumentGate>
</Viewer>

The local and the cloud engine refuse the same way, so this one check covers both.

What people do with the mouse fails quietly instead: without permission to create, drawing with a tool paints nothing and saves nothing.

Where the limits come from#

A document gets its permissions when it opens, together with who the user is.

On the local engine you give both. Once on the viewer, for every document it opens, and per document when one needs something else:

<script lang="ts">
  import { Viewer } from '@embedpdf/svelte/runtime';
  import { archive, engine, plugins, report } from './pdf';
</script>

<Viewer
  {engine}
  {plugins}
  identity={{ userId: 'u_381', displayName: 'Dana Smith' }}
  scope={[
    'doc.open',
    'doc.render',
    'doc.text.select',
    'doc.annotate.read',
    'annotations:create:self',
    'annotations:update:self',
    'annotations:delete:self',
  ]}
  initialDocuments={[
    { source: report },
    { source: archive, scope: ['doc.open', 'doc.render'] }, // this one is read-only
  ]}
/>

• A document’s own scope replaces the viewer’s. It’s the whole list for that document, not an addition, so it means exactly what it says. The same goes for identity.
• identity is who the user is. Permissions that say “their own” (:self) or “their group” (:group) are checked against it, so they need one: opening without it fails.
• A document keeps what it opened with. Change the viewer’s scope or identity, and the documents you open after that get the new values.

Code that opens documents itself passes the same options to documents.open(source, { scope, identity }).

Leave scope out and the user may do what the file allows, as in Acrobat: everything, unless the PDF has restrictions of its own, such as no printing. That’s pdf.permissions plus what no PDF flag governs: downloading, importing annotations and form data, running and submitting a form, certifying the document, and putting annotations and fields in any group. Pass the scope your users will really get, so the checks show you the UI they’ll see.

Every check#

Each plugin’s page has a Permissions section with the permission behind each check.

A command’s enabled is where these checks go, so every toolbar button and shortcut follows them.