/** * Worksheet protection — lock a sheet so users can only perform the actions you allow. * * Call {@link Worksheet.protect} with optional password and {@link SheetProtectionOptions}. * Each public flag is **allow** polarity (`true` means the user may do that action). * Use {@link Worksheet.unprotect} to turn protection off (password required when one was set). * * Cell-level lock and formula-hide settings live on cell style {@link Protection}, not here. * Allow-edit ranges use {@link Worksheet.protectedRanges}. * * Citations: * - ECMA-376-1 §18.3.1.85 (`sheetProtection`) * - transitional sml.xsd `CT_SheetProtection` (~L2887–2910) * - `CT_Worksheet` sequence: after `sheetCalcPr`, before `protectedRanges` * - MS-OE376 iterative password hash (SHA-512, spinCount 100000) * - docs/specs/sheet-protection.md; docs/ooxml-mapping/sheet-protection.md */ /** Default spin count for modern worksheet password hash (MS-OE376 / Excel). */ export declare const SHEET_PROTECTION_DEFAULT_SPIN_COUNT = 100000; /** Algorithm name authored on new protect (MS-OE376 table). */ export declare const SHEET_PROTECTION_ALGORITHM = "SHA-512"; /** * Options for {@link Worksheet.protect}. * * Every flag means **allow** that action while the sheet is protected * (`true` = the user may do it; `false` = blocked). Defaults match typical Excel * “Protect Sheet” behavior (select cells yes; most edits no). */ export interface SheetProtectionOptions { /** Allow users to change cell formatting. Default `false`. */ allowsFormatCells?: boolean; /** Allow users to change column formatting (width, hide, and so on). Default `false`. */ allowsFormatColumns?: boolean; /** Allow users to change row formatting (height, hide, and so on). Default `false`. */ allowsFormatRows?: boolean; /** Allow users to insert columns. Default `false`. */ allowsInsertColumns?: boolean; /** Allow users to insert rows. Default `false`. */ allowsInsertRows?: boolean; /** Allow users to insert hyperlinks. Default `false`. */ allowsInsertHyperlinks?: boolean; /** Allow users to delete columns. Default `false`. */ allowsDeleteColumns?: boolean; /** Allow users to delete rows. Default `false`. */ allowsDeleteRows?: boolean; /** * Allow selecting cells that are locked. Default `true`. */ allowsSelectLockedCells?: boolean; /** * Allow selecting cells that are unlocked. Default `true`. */ allowsSelectUnlockedCells?: boolean; /** Allow sorting. Default `false`. */ allowsSort?: boolean; /** Allow using AutoFilter. Default `false`. */ allowsAutoFilter?: boolean; /** Allow working with pivot tables. Default `false`. */ allowsPivotTables?: boolean; /** * Allow editing drawing objects (shapes, charts, and similar). Default `true`. */ allowsEditObjects?: boolean; /** * Allow editing what-if scenarios. Default `true`. */ allowsEditScenarios?: boolean; } /** * Read-only view of the sheet’s current protection settings. * * Returned by {@link Worksheet.sheetProtection} when the sheet is protected; * otherwise that property is `undefined`. */ export interface SheetProtectionInfo { readonly isProtected: true; /** `true` when unprotecting requires a password. */ readonly hasPassword: boolean; /** Effective allow-flags after defaults are applied. */ readonly options: Readonly>; /** * Modern OOXML `algorithmName` when present (e.g. `SHA-512`). * Undefined for password-less protection or legacy-only `password`. */ readonly algorithmName: string | undefined; /** * Modern OOXML `hashValue` (base64) when present. * Read-only snapshot of wire material; not a cleartext password. */ readonly hashValue: string | undefined; /** * Modern OOXML `saltValue` (base64) when present. */ readonly saltValue: string | undefined; /** * Modern OOXML `spinCount` when present. */ readonly spinCount: number | undefined; } /** * Wire model for `sheetProtection` (empty element, attributes only). * @private */ export interface SheetProtectionModel { /** Whether a `sheetProtection` element is present / authored. */ readonly present: boolean; /** * `sheet` attribute — protection gate. XSD default `false`. * `protect()` always sets this `true`. */ readonly sheet: boolean; /** Public allow flags (already converted from wire polarity). */ readonly options: Required; /** Modern `algorithmName` when present. */ readonly algorithmName: string | undefined; /** Modern `hashValue` (base64) when present. */ readonly hashValue: string | undefined; /** Modern `saltValue` (base64) when present. */ readonly saltValue: string | undefined; /** Modern `spinCount` when present. */ readonly spinCount: number | undefined; /** * Legacy `password` ST_UnsignedShortHex when present (preserve-only; * never authored by `protect()`). */ readonly legacyPassword: string | undefined; /** Unknown attributes preserved as XML fragment. */ readonly extraAttrsXml: string; } /** * Host notifications for protection mutations. * @private */ export interface SheetProtectionHost { markDirty(): void; } /** * Excel-compatible public defaults when calling `protect()` without options. * @private */ export declare const DEFAULT_PROTECT_OPTIONS: Readonly>; /** * CT_Worksheet local names that appear **before** `sheetProtection` after sheetData. * Citation: transitional sml.xsd `CT_Worksheet`. */ export declare const SHEET_PROTECTION_PREDECESSORS_AFTER_SHEET_DATA: ReadonlyArray; /** * CT_Worksheet local names that appear **after** `sheetProtection`. * Citation: transitional sml.xsd `CT_Worksheet`. */ export declare const SHEET_PROTECTION_SUCCESSORS: ReadonlyArray; /** * Index at which to insert serialized `sheetProtection` among after-sheetData siblings. */ export declare function findSheetProtectionInsertIndex(afterSheetDataLocals: ReadonlyArray): number; /** * Mutable sheet-protection store bound to a worksheet. * @private */ export declare class SheetProtectionImpl { private model; private host; constructor(initial?: SheetProtectionModel); /** @private */ bindHost(host: SheetProtectionHost): void; /** @private */ replaceFromParse(model: SheetProtectionModel): void; /** @private */ toModel(): SheetProtectionModel; /** True when the sheet protection gate (`sheet`) is on. */ readonly isProtected: boolean; /** * Snapshot when protected; `undefined` when not. */ readonly sheetProtection: SheetProtectionInfo | undefined; /** * Enable or replace worksheet protection. * * @param password Optional password; non-empty authors modern SHA-512 hash. * @param options Allow flags merged over Excel-compatible defaults. */ protect(password?: string, options?: SheetProtectionOptions): void; /** * Remove worksheet protection. * * @param password Required when the sheet has a password (modern or legacy). * @throws InvalidProtectionError when password is required/wrong/unsupported. */ unprotect(password?: string): void; } /** * Parse a `sheetProtection` element into a model. * @private */ export declare function parseSheetProtectionXml(xml: string): SheetProtectionModel; /** * Serialize model to a `sheetProtection` element, or `undefined` when absent. * Omits attributes that equal XSD defaults to keep markup lean. * @private */ export declare function serializeSheetProtectionXml(model: SheetProtectionModel): string | undefined; interface ModernHash { readonly algorithmName: typeof SHEET_PROTECTION_ALGORITHM; readonly hashValue: string; readonly saltValue: string; readonly spinCount: number; } /** * MS-OE376 / ECMA AG_Password iterative hash (Excel-compatible): * H₀ = SHA-512(salt binary ‖ password UTF-16LE); * for i = 0 .. spinCount-1: H = SHA-512(H ‖ uint32le(i)). * * Salt is **prepended** (ECMA-376-1 §17.15.1.29 `saltValue`; * MS-OFFCRYPTO H0 = H(salt + password); Apache POI / PhpSpreadsheet). */ export declare function hashPasswordModern(password: string, spinCount?: number, salt?: Uint8Array): ModernHash; /** * Verify a candidate password against modern salt/hash/spin material. * Used by sheet and workbook protection unprotect paths. * @private */ export declare function verifyPasswordModern(password: string, saltValueB64: string, hashValueB64: string, spinCount: number): boolean; export {};