---
title: "Utilities"
description: "Functions for validating policies, checking permissions and exporting readable content."
canonical_url: "https://tiptap.dev/docs/composable-docs/content-protection/api-reference/utilities"
---

# Utilities

Functions for validating policies, checking permissions and exporting readable content.

Import these functions from `@tiptap-pro/extension-content-protection`. Each accepts one options object. Pass policy JSON directly; standalone utilities validate it against the document or transaction's schema and throw `ProtectionConfigurationError` for invalid policies.

`Editor` comes from `@tiptap/core`; `Node` and `Schema` from `@tiptap/pm/model`; `Transaction` from `@tiptap/pm/state`.

## `validateContentProtectionPolicy`

Validates policy syntax and, when a schema is supplied, referenced types and attributes.

### Parameters

- `policy` (`unknown`): The value to validate.
- `schema?` (`Schema`): Schema for name checks. Omit to check syntax only.

### Returns (`{ valid: boolean; issues: PolicyIssue[] }`)

- `valid` (`boolean`): Whether validation passed.
- `issues` (`PolicyIssue[]`): Configuration errors; empty when valid.

## `checkProtectedTransaction`

Checks a transaction against an editor's active policy without applying it or emitting events. Requires `ContentProtection` in the editor.

### Parameters

- `editor` (`Editor`): The editor holding the active policy.
- `transaction` (`Transaction`): A transaction created from the editor's current state.

### Returns (`ProtectionCheck`)

Permission result, violations and current revisions. Throws `ProtectionInputError` for missing extension or mismatched starting document. Dispatch checks permissions again.

## `checkContentProtectionTransaction`

Checks a transaction without an editor.

### Parameters

- `policy` (`ContentProtectionPolicy`): The policy to evaluate.
- `transaction` (`Transaction`): The proposed transaction.

### Returns (`ProtectionCheck`)

Permission result and violations. Both revisions are `null`. Throws `ProtectionInputError` for incompatible input.

## `getProtection`

Summarizes read and edit permissions in an editor. Requires `ContentProtection`.

### Parameters

- `editor` (`Editor`): The editor to inspect.
- `range?` (`{ from: number; to: number }`): Range to summarize. Default: current selection.

### Returns (`PermissionSummary`)

Aggregate permissions and matching rule identifiers. A collapsed range checks text insertion at the caret; use a transaction check for a specific edit.

## `summarizeContentProtection`

Summarizes permissions without an editor.

### Parameters

- `policy` (`ContentProtectionPolicy`): The policy to evaluate.
- `document` (`Node`): The document to inspect.
- `range` (`{ from: number; to: number }`): Range to summarize.

### Returns (`PermissionSummary`)

Aggregate read and edit permissions. Throws `ProtectionInputError` for invalid input.

## `explainProtection`

Explains permissions for one existing target in an editor. Requires `ContentProtection`.

### Parameters

- `editor` (`Editor`): The editor to inspect.
- `subject` (`ProtectionSubject`): The Node, attribute or marked range to inspect.

### Returns (`ProtectionExplanation`)

Read/edit decisions and enclosing concealment rules. Throws `ProtectionInputError` for invalid targets or missing extension.

## `explainContentProtection`

Explains permissions without an editor.

### Parameters

- `policy` (`ContentProtectionPolicy`): The policy to evaluate.
- `document` (`Node`): The document to inspect.
- `subject` (`ProtectionSubject`): The existing target to inspect.

### Returns (`ProtectionExplanation`)

Read/edit decisions and enclosing concealment rules. Throws `ProtectionInputError` for invalid input.

## `getReadableContent`

Creates a presentation tree and plain text with redacted regions replaced by placeholders.

### Parameters

- `document` (`Node`): The document to inspect.
- `policy` (`ContentProtectionPolicy`): The policy to evaluate.
- `range?` (`{ from: number; to: number }`): Content to include. Default: the entire document.
- `redactionText?` (`string`): Replacement text. Default: `'[Hidden content]'`. Editor options are not read automatically.

### Returns (`ReadableContent`)

- `content` (`ReadableNode[]`): Visible content and redacted regions. This is not Tiptap JSON and must not be passed to `setContent`.
- `text` (`string`): Visible text with newlines between textblocks and for hard breaks. Non-text leaves use `U+FFFC`; hidden regions use `redactionText`. No trailing newline is added.

Throws `ProtectionInputError` for invalid input. Does not change the document, resolve external values, generate HTML or call `renderRedaction`.

See [result types](https://tiptap.dev/docs/composable-docs/content-protection/api-reference/types.md) and [policy types](https://tiptap.dev/docs/composable-docs/content-protection/api-reference/policy.md).