@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/types/modules/word/reader/drawing-helpers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DOCX Reader - Drawing/Image Helpers
+ *
+ * Shared parsing helpers for DrawingML elements (used by both inline image,
+ * floating image, and drawing shape parsers).
+ */
+import type { XmlElement } from "../../xml/types.js";
+/** Parse `a:xfrm` element for rotation and flip properties. */
+export declare function parseXfrm(spPrEl: XmlElement, target: {
+    rotation?: number;
+    flipHorizontal?: boolean;
+    flipVertical?: boolean;
+}): void;
+/** Parse outline (`a:ln`) element. */
+export declare function parseOutline(spPrEl: XmlElement): {
+    width?: number;
+    color?: string;
+} | undefined;
+/** Parse source rectangle (crop) from `a:blipFill`. */
+export declare function parseSrcRect(blipFillEl: XmlElement): {
+    l?: number;
+    t?: number;
+    r?: number;
+    b?: number;
+} | undefined;
+/** Parse SVG blip reference from `a:extLst` inside `a:blip`. */
+export declare function parseSvgBlip(blipEl: XmlElement): string | undefined;

package/dist/types/modules/word/reader/form-field-parser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DOCX Reader - Form Field Parser
+ *
+ * Standalone parser for `w:ffData` elements (legacy form fields).
+ * Used by the run content parser when encountering form-field-bearing fields.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { FormField } from "../types.js";
+/**
+ * Parse a `w:ffData` element into a `FormField`.
+ *
+ * Supports the three legacy form field types:
+ * - `w:textInput` → text field
+ * - `w:checkBox` → checkbox field
+ * - `w:ddList` → drop-down list field
+ *
+ * Common properties (name, enabled, helpText, statusText) are extracted.
+ *
+ * @returns A `FormField` object, or undefined if no recognized field type was found.
+ */
+export declare function parseFfData(el: XmlElement): FormField | undefined;

package/dist/types/modules/word/reader/image-parsers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DOCX Reader - Image Parsers
+ *
+ * Parsers for inline and floating images (wp:inline / wp:anchor).
+ * These are pure parsers that don't depend on ReaderContext.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { FloatingImage, RunContent } from "../types.js";
+declare function parseDrawingContent(drawingEl: XmlElement, content: RunContent[]): void;
+declare function parseFloatingImage(anchorEl: XmlElement): FloatingImage | undefined;
+export { parseDrawingContent, parseFloatingImage };

package/dist/types/modules/word/reader/math-parser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DOCX Reader - Math Parser
+ *
+ * Parses OMML (Office Math Markup Language) elements (m:* namespace) into
+ * MathContent / MathBlock model objects. Each m:* element is mapped to its
+ * corresponding model interface (MathFraction, MathRadical, MathDelimiter, etc).
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { MathContent, MathBlock } from "../types.js";
+declare function parseMathContent(el: XmlElement): MathContent[];
+declare function parseMathBlock(oMathParaEl: XmlElement): MathBlock;
+export { parseMathContent, parseMathBlock };

package/dist/types/modules/word/reader/metadata-parsers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * DOCX Reader - Misc Metadata Parsers
+ *
+ * Parses small document metadata XML files that don't justify their own files:
+ * - webSettings.xml (WebSettings)
+ * - people.xml (PersonInfo[])
+ *
+ * Theme and settings parsing live in `theme-parser.ts` and `settings-parser.ts`.
+ * Re-exports them for backward compatibility.
+ */
+import type { PersonInfo, WebSettings } from "../types.js";
+export { parseThemeXml } from "./theme-parser.js";
+export { parseSettingsXml } from "./settings-parser.js";
+/** Parse word/webSettings.xml. */
+export declare function parseWebSettings(xmlStr: string): WebSettings;
+/** Parse word/people.xml. */
+export declare function parsePeople(xmlStr: string): PersonInfo[];

package/dist/types/modules/word/reader/numbering-parser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DOCX Reader - Numbering Parser
+ *
+ * Parses `word/numbering.xml`. Splits out from the legacy
+ * `styles-numbering-parsers.ts` to mirror the writer side
+ * (`numbering-writer.ts` is already separate from `styles-writer.ts`).
+ */
+import type { AbstractNumbering, NumberingInstance, NumPicBullet } from "../types.js";
+export declare function parseNumberingXml(xmlStr: string): {
+    abstractNums: AbstractNumbering[];
+    instances: NumberingInstance[];
+    numPicBullets: NumPicBullet[];
+};

package/dist/types/modules/word/reader/paragraph-section-parsers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DOCX Reader - Paragraph and Section Properties Parsers
+ *
+ * Pure parsers for `w:pPr` (paragraph properties) and `w:sectPr` (section
+ * properties). Both are large and have inter-dependencies (paragraphs may
+ * embed section properties); they're co-located here.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { ParagraphProperties, SectionProperties } from "../types.js";
+declare function parseParagraphProperties(pPrEl: XmlElement): ParagraphProperties;
+declare function parseSectionProperties(sectPrEl: XmlElement): SectionProperties;
+export { parseParagraphProperties, parseSectionProperties };

package/dist/types/modules/word/reader/parse-utils.d.ts

@@ -0,0 +1,91 @@
+/**
+ * DOCX Reader - Shared XML/parsing utilities
+ *
+ * Low-level helpers used across the various reader sub-modules.
+ * Extracted from docx-reader.ts to keep that file focused on
+ * orchestration of the higher-level parsers.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { ParsedRelationship } from "./reader-context.js";
+/** Get an attribute value, trying both `w:name` and bare `name`. */
+export declare function attrVal(el: XmlElement, name: string): string | undefined;
+/** Get an attribute as an integer (returns undefined if missing or non-numeric). */
+export declare function attrInt(el: XmlElement, name: string): number | undefined;
+/**
+ * Like `parseInt(value ?? fallback, 10)` but never returns NaN: any
+ * non-numeric value falls back to `fallback`. Use this when forwarding
+ * raw attribute strings into numeric model fields — round-tripping a
+ * `NaN` back into XML produces literal `"NaN"` and corrupts the
+ * resulting DOCX.
+ */
+export declare function safeParseInt(value: string | undefined, fallback: number): number;
+/** Get the local name from a possibly-prefixed tag (`"w:p"` → `"p"`). */
+export declare function localName(name: string): string;
+/** Find a child element by local name (matches both `w:name` and bare `name`). */
+export declare function findChildNs(el: XmlElement, localName: string): XmlElement | undefined;
+/** Find all child elements with a given local name. */
+export declare function findChildrenNs(el: XmlElement, localName: string): XmlElement[];
+/**
+ * Namespace-agnostic child finder: matches on the **local name** regardless
+ * of the prefix. Useful for namespaces other than `w:` (e.g. `m:`, `c:`,
+ * `cx:`) where the prefix may be inconsistent across producers.
+ */
+export declare function findChildLocal(el: XmlElement, name: string): XmlElement | undefined;
+/** Namespace-agnostic version of {@link findChildrenNs}. */
+export declare function findChildrenLocal(el: XmlElement, name: string): XmlElement[];
+/**
+ * Get an attribute value by **local name**, regardless of prefix.
+ * Useful when the same attribute may appear as `w:val`, `m:val`, etc.
+ */
+export declare function attrLocal(el: XmlElement, name: string): string | undefined;
+/**
+ * Check for a boolean toggle element.
+ *
+ * In OOXML, many properties are represented as toggle elements where:
+ * - Element present = true
+ * - Element with `w:val="0"` or `"false"` = explicit false
+ * - Element absent = undefined (use parent's default)
+ */
+export declare function boolToggle(parent: XmlElement, name: string): boolean | undefined;
+/** Serialize an XmlElement back to an XML string (used for opaque preservation). */
+export declare function serializeElement(el: XmlElement): string;
+/** Extract all `r:xxx` attribute values (relationship IDs) from an element tree. */
+export declare function collectRIds(el: XmlElement, out: Set<string>): void;
+export { getPartRelsPath, getFileName, getFileExt } from "../core/opc-paths.js";
+/**
+ * Resolve an OPC relationship target against its source part.
+ *
+ * - Leading `/` → package root absolute
+ * - `../` / `./` → resolved relative to the source part's directory
+ * - Plain paths → resolved relative to the source part's directory
+ *
+ * Returns an empty string when the resolved path would escape the package
+ * root (i.e. more `..` segments than there are directories above the
+ * source). The previous behaviour silently treated extra `..` as a no-op,
+ * which let a malicious or malformed `Target` value point at an entirely
+ * different part than the directory traversal would suggest.
+ */
+export declare function resolvePartPath(sourcePart: string, target: string): string;
+/**
+ * Find the first relationship of a given type and resolve its target path.
+ * Returns undefined if no matching relationship exists.
+ */
+export declare function resolveRelTarget(rels: ParsedRelationship[], relType: string, sourcePart: string): string | undefined;
+/** Convert OOXML cryptAlgorithmSid to human-readable algorithm name. */
+export declare function sidToHashAlgorithm(sid: string | undefined): string | undefined;
+/**
+ * Common shape returned by {@link parseNoteProperties}.
+ *
+ * `numFmt` is widened to `string` (rather than `NoteNumberFormat`) so the
+ * helper can populate either `FootnoteProperties` or `EndnoteProperties`,
+ * which only differ in `position`'s narrow union. Callers cast at the
+ * assignment site.
+ */
+export interface ParsedNoteProperties {
+    numFmt?: string;
+    numStart?: number;
+    numRestart?: string;
+    position?: string;
+}
+/** Parse footnote/endnote properties element. */
+export declare function parseNoteProperties(el: XmlElement): ParsedNoteProperties | undefined;

package/dist/types/modules/word/reader/properties-parsers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DOCX Reader - Properties Parsers
+ *
+ * Pure parsers for OOXML property structures that don't depend on the
+ * main reader context. These are the building blocks used by the higher-level
+ * paragraph/run/table/section parsers.
+ *
+ * Includes:
+ * - `parseRunProperties` (w:rPr)
+ * - `parseShading` (w:shd)
+ * - `parseBorder` (any border element)
+ * - `parseTableWidth` (w:tblW, w:tcW, etc.)
+ * - `parseRevisionInfo` (w:ins/w:del/w:rPrChange/etc. revision metadata)
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { Border, RevisionInfo, RunProperties, Shading, TableWidth } from "../types.js";
+export declare function parseRunProperties(rPrEl: XmlElement): RunProperties;
+export declare function parseShading(el: XmlElement): Shading;
+export declare function parseBorder(el: XmlElement): Border;
+export declare function parseTableWidth(el: XmlElement): TableWidth;
+export declare function parseRevisionInfo(el: XmlElement): RevisionInfo | undefined;

package/dist/types/modules/word/reader/reader-context.d.ts

@@ -0,0 +1,69 @@
+/**
+ * DOCX Reader Context
+ *
+ * Encapsulates per-parse session state so that concurrent readDocx() calls
+ * are safe. Previously this state lived in a module-level `_session` object.
+ */
+import { type WordSecurityPolicy } from "../security/policy.js";
+import type { FormField, RunProperties } from "../types.js";
+/**
+ * A parsed OPC relationship entry (from a .rels part).
+ */
+export interface ParsedRelationship {
+    id: string;
+    type: string;
+    target: string;
+    targetMode?: string;
+}
+/**
+ * State for the OOXML field state machine (`<w:fldChar>`).
+ *
+ * OOXML allows complex fields (TOC, INDEX, SEQ, REF, …) to span multiple
+ * paragraphs: `<w:fldChar fldCharType="begin">` may be in paragraph A while
+ * the matching `end` is in paragraph C. This state therefore lives on the
+ * shared reader context rather than as locals in `parseParagraph`.
+ *
+ * It is intentionally swappable: when entering a self-contained part such as
+ * a header, footer, footnote, endnote or comment we save and reset the field
+ * state so an unterminated field in the body never bleeds into those parts.
+ */
+export interface FieldParseState {
+    state: "none" | "instrText" | "cached";
+    instr: string;
+    cached: string;
+    runProps: RunProperties | undefined;
+    formField: FormField | undefined;
+}
+/**
+ * Per-parse session context. Holds relationship maps and any other state
+ * that needs to be shared across parse functions during a single readDocx()
+ * invocation without relying on module-level mutable state.
+ */
+export interface ReaderContext {
+    /** Relationship map for the current part being parsed (document, header, footer, etc.) */
+    relMap: Map<string, ParsedRelationship>;
+    /** Field state machine; shared across paragraphs to support cross-paragraph fields. */
+    field: FieldParseState;
+    /**
+     * Resolved security policy for this read. Parsers consult specific
+     * fields (e.g. `allowExternalTargets`) to decide whether to keep certain
+     * pieces of information that may be dangerous in untrusted documents.
+     * Defaults to `DEFAULT_SECURITY_POLICY` when not set.
+     */
+    securityPolicy: Required<WordSecurityPolicy>;
+}
+/**
+ * Create a fresh field state in the "none" state.
+ */
+export declare function createFieldState(): FieldParseState;
+/**
+ * Create a fresh reader context for a new parse session.
+ */
+export declare function createReaderContext(securityPolicy?: Required<WordSecurityPolicy>): ReaderContext;
+/**
+ * Parse a `.rels` XML string into an array of `ParsedRelationship` entries.
+ *
+ * Normalizes ISO 29500 Strict relationship types to Transitional equivalents
+ * via `STRICT_TO_TRANSITIONAL_REL`.
+ */
+export declare function parseRelationships(xmlStr: string): ParsedRelationship[];

package/dist/types/modules/word/reader/sdt-helpers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DOCX Reader - SDT Helper Parsers
+ *
+ * Standalone parsers for SDT-related elements that don't depend on
+ * the main reader context (parseParagraph etc.):
+ * - `parseCheckBox` — w14:checkbox SDT specialization
+ * - `parseTocInstruction` — TOC field instruction string parser
+ */
+import type { XmlElement } from "../../xml/types.js";
+import { type Mutable } from "../core/internal-utils.js";
+import type { CheckBox, TableOfContents } from "../types.js";
+/**
+ * Parse a w14:checkbox SDT element.
+ *
+ * Handles `w14:checked`, `w14:checkedState`, `w14:uncheckedState`.
+ */
+export declare function parseCheckBox(checkBoxEl: XmlElement): CheckBox;
+/**
+ * Parse a TOC field instruction string and populate the given TableOfContents object.
+ *
+ * Recognizes common TOC switches:
+ * - `\o "1-3"` — heading style range
+ * - `\h` — hyperlinks
+ * - `\c "label"` — caption label (table of figures)
+ * - `\s "id"` — sequence field identifier
+ * - `\p "."`/`"-"`/`"_"` — leader character
+ * - `\t "Style,Level;..."` — custom styles with levels
+ */
+export declare function parseTocInstruction(instr: string, toc: Mutable<TableOfContents>): void;

package/dist/types/modules/word/reader/settings-parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DOCX Reader - Settings Parser
+ *
+ * Parses `word/settings.xml` (DocumentSettings).
+ * Extracted from the original `metadata-parsers.ts`.
+ */
+import type { DocumentSettings } from "../types.js";
+export declare function parseSettingsXml(xmlStr: string): DocumentSettings;

package/dist/types/modules/word/reader/styles-parser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DOCX Reader - Styles Parser
+ *
+ * Parses `word/styles.xml` (`DocDefaults` + `StyleDef[]`). Splits out from
+ * the legacy `styles-numbering-parsers.ts` to mirror the writer side
+ * (`styles-writer.ts` and `numbering-writer.ts` are already separate).
+ */
+import type { DocDefaults, StyleDef } from "../types.js";
+export declare function parseStyles(xmlStr: string): {
+    docDefaults?: DocDefaults;
+    styles: StyleDef[];
+};

package/dist/types/modules/word/reader/table-properties-parsers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DOCX Reader - Table Properties Parsers
+ *
+ * Pure parsers for `w:tblPr`, `w:tblBorders`, `w:tcMar` (cell margins).
+ * Used by both the inline table parser and the styles parser.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { TableBorders, TableCellMargins, TableProperties } from "../types.js";
+declare function parseTableBorders(el: XmlElement): TableBorders;
+declare function parseTableCellMargins(el: XmlElement): TableCellMargins;
+declare function parseTableProperties(el: XmlElement): TableProperties;
+export { parseTableBorders, parseTableCellMargins, parseTableProperties };

package/dist/types/modules/word/reader/theme-parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DOCX Reader - Theme Parser
+ *
+ * Parses `word/theme/theme1.xml` (`DocumentTheme`).
+ * Extracted from the original `metadata-parsers.ts`.
+ */
+import type { DocumentTheme } from "../types.js";
+export declare function parseThemeXml(xmlStr: string): DocumentTheme;

package/dist/types/modules/word/reader/watermark-parser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * DOCX reader — header watermark detection.
+ *
+ * Watermarks are stored as a VML shape inside the first `<w:p>` of a header
+ * part. We detect them by walking the header XML tree looking for a shape
+ * whose id contains "WaterMark"; the surrounding header content is parsed
+ * by the regular header-content parser.
+ *
+ * Self-contained — no dependency on the body parser, so it lives in its
+ * own file to keep `docx-reader.ts` focused on package orchestration.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { Watermark } from "../types.js";
+/** Detect a watermark shape inside a header XML root, if present. */
+export declare function detectWatermarkFromRoot(root: XmlElement): Watermark | undefined;

package/dist/types/modules/word/security/cfb-reader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DOCX Module - CFB (Compound File Binary) Reader
+ *
+ * Minimal reader for OLE2/CFB format used by encrypted Office documents.
+ * Implements enough of MS-CFB to extract named streams (EncryptionInfo, EncryptedPackage).
+ *
+ * References:
+ *   - MS-CFB: Compound File Binary File Format
+ *   - https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb
+ */
+/** A stream entry extracted from/written to a CFB file. */
+export interface CfbEntry {
+    /** Stream name (UTF-16LE decoded). */
+    readonly name: string;
+    /** Stream data. */
+    readonly data: Uint8Array;
+}
+/**
+ * Read a CFB (OLE2 Compound File) and extract all stream entries.
+ *
+ * Only reads v3 and v4 CFB files (sector sizes 512 and 4096).
+ *
+ * @param buffer - The CFB file data.
+ * @returns Array of named stream entries.
+ */
+export declare function readCfb(buffer: Uint8Array): CfbEntry[];
+/**
+ * Write a set of named stream entries into a CFB (OLE2 Compound File) container.
+ *
+ * Produces a minimal v3 CFB with 512-byte sectors. Does not use mini-streams
+ * (all data is stored in regular sectors). This is suitable for encrypted Office
+ * documents where every stream exceeds 4096 bytes.
+ *
+ * @param entries - Named stream entries to include.
+ * @returns The CFB file as a Uint8Array.
+ */
+export declare function writeCfb(entries: readonly CfbEntry[]): Uint8Array;

package/dist/types/modules/word/{digital-signatures.d.ts → security/digital-signatures.d.ts}

@@ -13,12 +13,12 @@
  * - Detection and extraction of signature metadata
  * - Preservation of signatures through round-trip (via opaqueParts)
  *
- * Note: Creating new signatures requires X.509 certificate handling and
- * is outside the scope of this module. Consider using a dedicated signing
- * tool for the actual signing step.
+ * Note: This module does NOT validate signature integrity (would require
+ * full XMLDSig + Canonical XML implementation). Signatures are preserved
+ * verbatim but become invalid if the package contents change.
  *
  * References:
- *   - OPC: Open Packaging Conventions (ECMA-376 Part 2)
+ *   - MS-OFFCRYPTO §3.2.6 Digital Signatures
  *   - XMLDSig: https://www.w3.org/TR/xmldsig-core/
  */
 /** Parsed digital signature metadata. */
@@ -43,8 +43,15 @@ export interface DigitalSignatureInfo {
     readonly certificateSerialNumber?: string;
     /** Hash of the signature (base64). */
     readonly signatureValue?: string;
-    /** Whether signature is valid (requires verification). */
-    readonly valid?: boolean;
+    /**
+     * Cryptographic verification status.
+     *
+     * `"not-verified"` is the only value this module ever produces — full
+     * verification requires a complete XMLDSig + Canonical XML implementation
+     * which is intentionally out of scope. The field is exposed so callers
+     * are not tempted to interpret a missing value as "valid".
+     */
+    readonly cryptographicStatus: "not-verified";
     /** Raw XML for preservation. */
     readonly rawXml: string;
     /** Signature file name (e.g. "sig1.xml"). */
@@ -76,12 +83,13 @@ export declare function extractSignatures(opaqueParts: readonly {
     data: Uint8Array;
 }[] | undefined): DigitalSignatureInfo[];
 /**
- * Verify that a digital signature's structural integrity is intact.
+ * Check that a parsed signature has the structural elements XMLDSig
+ * requires (`Signature`, `SignedInfo`, `SignatureValue`, `KeyInfo`).
  *
- * Note: This does NOT verify the cryptographic signature — that requires
- * access to the signer's public key and a full XMLDSig implementation.
- * Use a dedicated XMLDSig library for cryptographic verification.
+ * This is **not** a cryptographic check — see `cryptographicStatus`. It is
+ * also tolerant of namespace prefixes (`<ds:Signature>` etc.) which the
+ * previous implementation missed.
  *
- * @returns True if the signature structure is well-formed.
+ * @returns True if the signature XML carries the required elements.
  */
 export declare function isWellFormedSignature(info: DigitalSignatureInfo): boolean;

package/dist/types/modules/word/security/document-protection.d.ts

@@ -0,0 +1,93 @@
+/**
+ * DOCX Module - Document Protection
+ *
+ * Provides APIs for setting document protection passwords and restrictions.
+ * Supports all protection types defined in OOXML:
+ * - Read-only (no modifications allowed)
+ * - Comments only (only add comments)
+ * - Forms only (only fill form fields)
+ * - Tracked changes (all changes are tracked)
+ * - Sections (specific sections editable)
+ *
+ * Password hashing follows the ECMA-376 specification using
+ * iterative SHA-based hashing with salt.
+ */
+import type { DocxDocument } from "../types.js";
+/** Document protection type (edit restriction). */
+export type ProtectionEditType = "none" | "readOnly" | "comments" | "trackedChanges" | "forms";
+/** Hash algorithm for protection password. */
+export type ProtectionHashAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
+/** Options for setting document protection. */
+export interface DocumentProtectionOptions {
+    /** Type of edit restriction. */
+    readonly edit: ProtectionEditType;
+    /** Password to protect the document (will be hashed). */
+    readonly password?: string;
+    /** Hash algorithm. Default: "SHA-256". */
+    readonly hashAlgorithm?: ProtectionHashAlgorithm;
+    /** Number of hash iterations (spin count). Default: 100000. */
+    readonly spinCount?: number;
+    /** Whether protection is enforced. Default: true. */
+    readonly enforcement?: boolean;
+    /** Formatting restriction (prevent style changes). */
+    readonly formatting?: boolean;
+}
+/** Protection state as stored in settings. */
+export interface ProtectionState {
+    /** Edit restriction type. */
+    readonly edit: ProtectionEditType;
+    /** Whether protection is enforced. */
+    readonly enforcement: boolean;
+    /** Hash algorithm used. */
+    readonly hashAlgorithm?: string;
+    /** Computed hash value (base64). */
+    readonly hashValue?: string;
+    /** Salt (base64). */
+    readonly saltValue?: string;
+    /** Spin count (iterations). */
+    readonly spinCount?: number;
+    /** Formatting restriction. */
+    readonly formatting?: boolean;
+}
+/**
+ * Set document protection on a DocxDocument.
+ * Returns a new document with protection settings applied.
+ *
+ * @param doc - The document to protect.
+ * @param options - Protection options.
+ * @returns A new document with protection settings.
+ *
+ * @example
+ * ```ts
+ * const protected = await protectDocument(doc, {
+ *   edit: "readOnly",
+ *   password: "secret123",
+ *   hashAlgorithm: "SHA-256"
+ * });
+ * ```
+ */
+export declare function protectDocument(doc: DocxDocument, options: DocumentProtectionOptions): Promise<DocxDocument>;
+/**
+ * Remove document protection.
+ *
+ * @param doc - The protected document.
+ * @returns A new document without protection.
+ */
+export declare function unprotectDocument(doc: DocxDocument): DocxDocument;
+/**
+ * Check if a document is protected.
+ */
+export declare function isDocumentProtected(doc: DocxDocument): boolean;
+/**
+ * Get the protection state of a document.
+ */
+export declare function getProtectionState(doc: DocxDocument): ProtectionState | undefined;
+/**
+ * Verify a password against the document's protection hash.
+ * Returns true if the password matches, false otherwise.
+ *
+ * @param doc - The protected document.
+ * @param password - The password to verify.
+ * @returns Whether the password is correct.
+ */
+export declare function verifyProtectionPassword(doc: DocxDocument, password: string): Promise<boolean>;