@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/{browser/modules/word → types/modules/word/security}/encryption.d.ts

@@ -9,9 +9,12 @@
  * - Password-based encryption/decryption of DOCX content
  * - EncryptionInfo XML generation/parsing
  *
- * Note: A full implementation requires a CFB container reader/writer for the
- * outer compound document format. For now, we expose primitives that can be
- * combined with an external CFB library if needed.
+ * All AES and SHA primitives are delegated to `@utils/crypto`, which uses
+ * synchronous `node:crypto` APIs in Node and Web Crypto in the browser.
+ * The KDF inner loop runs ~100,000 hashes per derived key; on Node we go
+ * through the synchronous fast path so a round-trip completes in well
+ * under a second instead of the multi-second microtask churn that the
+ * old `await crypto.subtle.digest()` loop produced.
  *
  * References:
  *   - MS-OFFCRYPTO: Office Document Cryptography Structure
@@ -88,9 +91,13 @@ export declare function verifyPassword(password: string, info: AgileEncryptionIn
  * @param encryptedPackage - The EncryptedPackage stream from CFB.
  * @param info - Agile encryption parameters.
  * @param password - The user password.
+ * @param maxDecryptedSize - Optional upper bound on the decrypted size; if the
+ *   `totalSize` header claims a larger value, throw rather than allocate.
+ *   Defaults to 512 MiB so adversarial files cannot trigger arbitrary-size
+ *   allocations before security policy is applied at the unzip layer.
  * @returns The decrypted (unencrypted) package bytes.
  */
-export declare function decryptPackage(encryptedPackage: Uint8Array, info: AgileEncryptionInfo, password: string): Promise<Uint8Array>;
+export declare function decryptPackage(encryptedPackage: Uint8Array, info: AgileEncryptionInfo, password: string, maxDecryptedSize?: number): Promise<Uint8Array>;
 /**
  * Parse an EncryptionInfo XML stream from a CFB-wrapped encrypted DOCX.
  *
@@ -100,3 +107,43 @@ export declare function decryptPackage(encryptedPackage: Uint8Array, info: Agile
  * @returns Parsed agile encryption info.
  */
 export declare function parseEncryptionInfoXml(xmlStr: string): AgileEncryptionInfo;
+/**
+ * Read an encrypted DOCX file by providing a password.
+ *
+ * Handles the full pipeline:
+ * 1. Parse CFB container
+ * 2. Extract EncryptionInfo and EncryptedPackage streams
+ * 3. Verify password and decrypt
+ * 4. Return the decrypted DOCX ZIP bytes
+ *
+ * @param buffer - The encrypted DOCX file (CFB format).
+ * @param password - The password to decrypt with.
+ * @param maxDecryptedSize - Optional cap on the decrypted size (defaults to 512 MiB).
+ * @returns The decrypted DOCX ZIP bytes (can be passed to readDocx).
+ * @throws Error if the file is not encrypted, password is wrong, or decryption fails.
+ */
+export declare function decryptDocx(buffer: Uint8Array, password: string, maxDecryptedSize?: number): Promise<Uint8Array>;
+/** Options for DOCX encryption. */
+export interface EncryptOptions {
+    /** Key length in bits. Default: 256. */
+    readonly keyBits?: 128 | 192 | 256;
+    /** Hash algorithm. Default: SHA512. */
+    readonly hashAlgorithm?: "SHA1" | "SHA256" | "SHA384" | "SHA512";
+    /** Number of KDF iterations (spin count). Default: 100000. */
+    readonly spinCount?: number;
+}
+/**
+ * Encrypt a DOCX ZIP file with a password using Agile Encryption (MS-OFFCRYPTO).
+ *
+ * Produces a CFB (OLE2 Compound File) containing:
+ *   - EncryptionInfo stream (Agile encryption XML)
+ *   - EncryptedPackage stream (segment-encrypted ZIP data)
+ *
+ * The output can be opened by Microsoft Word with the given password.
+ *
+ * @param zipBytes - The unencrypted DOCX content (ZIP format).
+ * @param password - The password to encrypt with.
+ * @param options - Encryption options (key length, hash algorithm, spin count).
+ * @returns The encrypted DOCX as a CFB-formatted Uint8Array.
+ */
+export declare function encryptDocx(zipBytes: Uint8Array, password: string, options?: EncryptOptions): Promise<Uint8Array>;

package/dist/types/modules/word/security/policy.d.ts

@@ -0,0 +1,80 @@
+/**
+ * DOCX Module - Security Policy
+ *
+ * Defines configurable security policies that control how potentially
+ * dangerous content (VBA, OLE, external targets, etc.) is handled
+ * during document reading and writing.
+ *
+ * **Implementation status of each field (read this before relying on
+ * the strict preset for security guarantees):**
+ *
+ * - `preserveVbaProject` — IMPLEMENTED on the read path. When `false`
+ *   the macro binary is dropped from the returned model.
+ * - `preserveAltChunks` — IMPLEMENTED on the read path. When `false`
+ *   altChunk body items are removed before the document is returned.
+ * - `allowExternalTargets` — IMPLEMENTED on the read path. When `false`
+ *   `Hyperlink.url` is left undefined; only anchor-based hyperlinks
+ *   survive. The link wrapper and its inner runs remain.
+ * - `maxPackageSize`, `maxPartSize`, `maxPartCount`, `maxXmlDepth` —
+ *   IMPLEMENTED. Enforced during ZIP parsing / XML parsing; oversize
+ *   inputs raise `DocxLimitExceededError` instead of being processed.
+ * - `dropSignaturesOnModify` — IMPLEMENTED. Both writers skip any opaque
+ *   parts under `_xmlsignatures/` when `true` (the default). The
+ *   `_rels/.rels` file is rebuilt from scratch by the packager, so any
+ *   sigOrigin relationship pointing at the now-absent signatures is also
+ *   removed automatically. Set `false` to keep the parts; in that case
+ *   downstream verifiers will treat the signatures as broken because the
+ *   document body has been re-emitted.
+ * - `preserveOleObjects` — IMPLEMENTED. On the read path, OLE embedding
+ *   binaries (word/embeddings/*.bin and similar) are excluded from
+ *   `opaqueParts` when `false`. On the write path (both buffered and
+ *   streaming) the same paths are skipped when emitting opaqueParts. The
+ *   relationships that referenced the binary remain in the owning part's
+ *   .rels — strip those manually if you need a fully clean document.
+ * - `rawXmlPolicy` — IMPLEMENTED on the write path. `"preserve"` (default)
+ *   writes opaque rawXml verbatim; `"strip"` skips the offending fragments
+ *   while keeping the surrounding element well-formed; `"reject"` throws
+ *   `DocxRawXmlPolicyError` so the caller can sanitise the model first.
+ *   Sites covered: opaqueRun, opaqueParagraphChild, opaqueDrawing,
+ *   drawingShape rawXml/_advancedFillXml/_advancedEffectsXml,
+ *   settings.mailMergeRawXml, theme.formatScheme.rawXml, theme.extLstXml,
+ *   webSettings.rawXml, numPicBullet.rawVmlXml.
+ *
+ * Pull requests welcome for the not-yet-enforced fields. Until they
+ * arrive, callers needing those guarantees should sanitise the input
+ * model themselves before serialisation.
+ */
+export interface WordSecurityPolicy {
+    /** Whether to preserve VBA project binary on read/write. Default: true (preserve but don't execute). */
+    readonly preserveVbaProject?: boolean;
+    /** Whether to preserve OLE embedded objects. Default: true. */
+    readonly preserveOleObjects?: boolean;
+    /** Whether to preserve altChunk parts (embedded HTML/RTF). Default: true. */
+    readonly preserveAltChunks?: boolean;
+    /** Whether to drop digital signatures when document is modified. Default: true. */
+    readonly dropSignaturesOnModify?: boolean;
+    /** Maximum total package size in bytes. Default: 500MB. */
+    readonly maxPackageSize?: number;
+    /** Maximum single part size in bytes. Default: 100MB. */
+    readonly maxPartSize?: number;
+    /** Maximum ZIP entry count. Default: 10000. */
+    readonly maxPartCount?: number;
+    /** Maximum nesting depth for XML parsing. Default: 256. */
+    readonly maxXmlDepth?: number;
+    /** Raw XML policy for opaque/preserved content. */
+    readonly rawXmlPolicy?: "preserve" | "strip" | "reject";
+    /** Whether to allow external relationship targets (URLs). Default: true. */
+    readonly allowExternalTargets?: boolean;
+}
+/** Default security policy: preserve everything, generous limits. */
+export declare const DEFAULT_SECURITY_POLICY: Required<WordSecurityPolicy>;
+/** Strict security policy: strip dangerous content, tight limits. */
+export declare const STRICT_SECURITY_POLICY: Required<WordSecurityPolicy>;
+/**
+ * Merge a partial security policy with the defaults.
+ * Any unset fields fall back to DEFAULT_SECURITY_POLICY values.
+ *
+ * @param policy - Partial policy overrides (or undefined for full defaults).
+ * @returns A fully resolved security policy.
+ */
+export declare function resolveSecurityPolicy(policy?: Partial<WordSecurityPolicy>): Required<WordSecurityPolicy>;

package/dist/types/modules/word/template/template-chart.d.ts

@@ -0,0 +1,56 @@
+/**
+ * DOCX Module - Template Chart Data Binding
+ *
+ * Extends the template engine with chart data binding support.
+ * Allows replacing series data, categories, and titles in chart
+ * definitions within a DocxDocument.
+ *
+ * @stability experimental
+ */
+import type { DocxDocument } from "../types.js";
+/** Data for a single chart series to bind. */
+export interface ChartSeriesData {
+    /** Series name (legend label). */
+    readonly name: string;
+    /** Numeric data values. */
+    readonly values: number[];
+    /** Optional series color (6-digit hex RGB). */
+    readonly color?: string;
+}
+/** Binding specification mapping a chart reference to new data. */
+export interface ChartBinding {
+    /** Chart index (0-based) or chart name. */
+    readonly chartRef: number | string;
+    /** New series data. */
+    readonly series: ChartSeriesData[];
+    /** New category labels (X-axis). */
+    readonly categories?: string[];
+    /** Chart title override. */
+    readonly title?: string;
+}
+/** Aggregate template data for chart bindings. */
+export interface ChartTemplateData {
+    /** Array of chart bindings to apply. */
+    readonly charts: ChartBinding[];
+}
+/**
+ * Replace chart data in a DocxDocument according to the provided bindings.
+ *
+ * Iterates through the document body, locates `ChartContent` blocks, and
+ * replaces their series data, categories, and titles with the values
+ * specified in each binding.
+ *
+ * Charts are matched by either:
+ * - Numeric index (0-based position among all ChartContent blocks in body)
+ * - String name (matched against `ChartContent.name`)
+ *
+ * Only basic chart types (bar, column, line, pie and their variants) are
+ * supported. Bindings that reference unsupported chart types are skipped.
+ *
+ * @param doc - The DocxDocument to modify.
+ * @param chartBindings - Array of chart bindings to apply.
+ * @returns A new DocxDocument with chart data replaced.
+ *
+ * @stability experimental
+ */
+export declare function bindChartData(doc: DocxDocument, chartBindings: ChartBinding[]): DocxDocument;

package/dist/types/modules/word/template/template-datasource.d.ts

@@ -0,0 +1,154 @@
+/**
+ * DOCX Module - Template Data Source
+ *
+ * An abstraction layer for providing data to the template engine from
+ * various sources (JSON, XML, CSV) with composition support.
+ *
+ * @stability experimental
+ */
+import type { DocxDocument } from "../types.js";
+import type { TemplateOptions } from "./template-engine.js";
+/**
+ * Abstract data provider for the template engine.
+ *
+ * Implementations transform various data formats into the flat
+ * `Record<string, unknown>` structure consumed by `fillTemplate`.
+ */
+export interface DataSource {
+    /** Retrieve all data as a flat record. */
+    readonly getData: () => Record<string, unknown>;
+    /** Retrieve an array value by key. Returns empty array if not found or not an array. */
+    readonly getArray: (key: string) => unknown[];
+    /** Retrieve a single value by dot-separated path. Returns undefined if not found. */
+    readonly getValue: (path: string) => unknown;
+}
+/** Options for `fillTemplateFromSource`. */
+export interface FillFromSourceOptions extends TemplateOptions {
+    /** If true, merge arrays with the same key across composite sources (default: false). */
+    readonly mergeArrays?: boolean;
+}
+/**
+ * Data source that reads from a JSON string or object.
+ *
+ * @stability experimental
+ */
+export declare class JsonDataSource implements DataSource {
+    private readonly data;
+    /**
+     * @param input - A JSON string or an existing object.
+     */
+    constructor(input: string | Record<string, unknown>);
+    getData(): Record<string, unknown>;
+    getArray(key: string): unknown[];
+    getValue(path: string): unknown;
+    private resolvePath;
+}
+/**
+ * Data source that reads from an XML string.
+ *
+ * Flattens the XML structure into dot-separated key-value pairs.
+ * Repeated elements with the same tag are collected into arrays.
+ *
+ * Example XML:
+ * ```xml
+ * <root>
+ *   <name>John</name>
+ *   <address><city>NY</city></address>
+ *   <item>A</item>
+ *   <item>B</item>
+ * </root>
+ * ```
+ * Produces: `{ name: "John", "address.city": "NY", address: { city: "NY" }, item: ["A", "B"] }`
+ *
+ * @stability experimental
+ */
+export declare class XmlDataSource implements DataSource {
+    private readonly data;
+    /**
+     * @param xml - An XML string to parse.
+     * @param rootTag - Optional root element name to skip. If not provided, the first element is used.
+     */
+    constructor(xml: string, rootTag?: string);
+    getData(): Record<string, unknown>;
+    getArray(key: string): unknown[];
+    getValue(path: string): unknown;
+    private resolvePath;
+}
+/**
+ * Data source that reads from a CSV string.
+ *
+ * The first row is treated as headers (column names become keys).
+ * Each subsequent row becomes an object. The entire dataset is available
+ * as an array under the `rows` key (or a custom key).
+ *
+ * Individual columns are also available as arrays under their header name.
+ *
+ * Example CSV:
+ * ```
+ * name,age
+ * Alice,30
+ * Bob,25
+ * ```
+ * Produces:
+ * ```
+ * {
+ *   rows: [{ name: "Alice", age: "30" }, { name: "Bob", age: "25" }],
+ *   name: ["Alice", "Bob"],
+ *   age: ["30", "25"]
+ * }
+ * ```
+ *
+ * @stability experimental
+ */
+export declare class CsvDataSource implements DataSource {
+    private readonly data;
+    /**
+     * @param csv - A CSV string.
+     * @param options - Optional parsing configuration.
+     */
+    constructor(csv: string, options?: {
+        /** Delimiter character (default: ","). */
+        readonly delimiter?: string;
+        /** Key for the rows array (default: "rows"). */
+        readonly rowsKey?: string;
+    });
+    getData(): Record<string, unknown>;
+    getArray(key: string): unknown[];
+    getValue(path: string): unknown;
+}
+/**
+ * Combines multiple data sources into one.
+ *
+ * Sources added later take precedence over earlier ones for conflicting keys.
+ * Arrays can optionally be merged instead of overwritten.
+ *
+ * @stability experimental
+ */
+export declare class CompositeDataSource implements DataSource {
+    private readonly sources;
+    private readonly mergeArrays;
+    /**
+     * @param sources - Data sources to combine (later sources take precedence).
+     * @param options - Configuration options.
+     */
+    constructor(sources: readonly DataSource[], options?: {
+        readonly mergeArrays?: boolean;
+    });
+    getData(): Record<string, unknown>;
+    getArray(key: string): unknown[];
+    getValue(path: string): unknown;
+}
+/**
+ * Fill a DOCX template using a DataSource instead of a raw data record.
+ *
+ * This is a convenience function that extracts data from the source and
+ * delegates to the core `fillTemplate` function.
+ *
+ * @param doc - The parsed DocxDocument model.
+ * @param source - A DataSource implementation.
+ * @param options - Optional template settings.
+ * @returns The same DocxDocument with placeholders resolved.
+ *
+ * @stability experimental
+ */
+export declare function fillTemplateFromSource(doc: DocxDocument, source: DataSource, options?: FillFromSourceOptions): DocxDocument;

package/dist/types/modules/word/template/template-engine.d.ts

@@ -0,0 +1,121 @@
+/**
+ * DOCX Module - Template Engine
+ *
+ * A template engine for DOCX documents supporting:
+ * - Variable interpolation: {{name}}, {{user.name}}
+ * - Conditionals: {{#if cond}}...{{/if}}, {{#if cond}}...{{else}}...{{/if}}
+ * - Loops: {{#each items}}...{{/each}} with {{.}}, {{.prop}}, {{@index}}
+ * - Table row loops: auto-duplicates table rows when {{#each}} is in a row
+ * - Table column loops: {{#cols items}}...{{/cols}} duplicates columns
+ * - Image placeholders: {{%image}} resolves to an inline image
+ * - RichText placeholders: {{&richText}} resolves to paragraph children
+ * - Sub-document insertion: {{>subDoc}} resolves to body content blocks
+ * - Chart placeholders: {{^chart}} resolves to chart content
+ *
+ * Handles cross-run placeholders (Word often splits {{name}} across runs).
+ */
+import type { BaseErrorOptions } from "../../../utils/errors.js";
+import { DocxError } from "../errors.js";
+import type { DocxDocument, BodyContent, Run, ImageDef, Chart } from "../types.js";
+/** Options for the template engine. */
+export interface TemplateOptions {
+    /** Custom delimiters (default: ["{{", "}}"]). */
+    readonly delimiters?: readonly [string, string];
+    /**
+     * If true (default), throw `TemplateError` when a placeholder cannot be
+     * resolved. If false, unresolved variables render as the empty string and
+     * unresolved control directives are skipped silently.
+     */
+    readonly strict?: boolean;
+}
+/** An image value to be inserted by the template engine. */
+export interface TemplateImage {
+    /** Image definition (data, fileName, mediaType). */
+    readonly image: ImageDef;
+    /** Width in EMU. */
+    readonly width: number;
+    /** Height in EMU. */
+    readonly height: number;
+    /** Optional alt text. */
+    readonly altText?: string;
+}
+/** Rich text value: an array of runs to insert. */
+export type TemplateRichText = readonly Run[];
+/** Sub-document content: body blocks to insert. */
+export type TemplateSubDocument = readonly BodyContent[];
+/** Chart value to be inserted by the template engine. */
+export interface TemplateChart {
+    readonly chart: Chart;
+    readonly altText?: string;
+    readonly name?: string;
+}
+/** HTML chunk value to be inserted as an altChunk body content. */
+export interface TemplateHtmlChunk {
+    /** HTML content string. */
+    readonly html: string;
+    /** Optional content type (default: "text/html"). */
+    readonly contentType?: string;
+}
+/** Information about a template tag found in the document. */
+export interface TemplateTag {
+    /** The raw tag expression (e.g. "name", "#each items", "%image"). */
+    readonly expression: string;
+    /** Tag type. */
+    readonly type: "variable" | "image" | "richText" | "subDocument" | "chart" | "htmlChunk" | "ifOpen" | "ifClose" | "else" | "eachOpen" | "eachClose" | "colsOpen" | "colsClose";
+    /** Location hint (e.g. "body paragraph 3", "header"). */
+    readonly location: string;
+}
+/** Error thrown when template processing fails. */
+export declare class TemplateError extends DocxError {
+    readonly name = "TemplateError";
+    /** The placeholder that caused the error. */
+    readonly placeholder: string;
+    /** Location hint (e.g. "body paragraph 3", "header"). */
+    readonly location: string;
+    /** The tag name/expression that caused the error. */
+    readonly tagName?: string;
+    /** The paragraph index within the current block where the error occurred. */
+    readonly paragraphIndex?: number;
+    /** The section path (e.g. "body", "header:default", "footer:first"). */
+    readonly sectionPath?: string;
+    constructor(message: string, placeholder: string, location: string, options?: BaseErrorOptions & {
+        tagName?: string;
+        paragraphIndex?: number;
+        sectionPath?: string;
+    });
+}
+/**
+ * Fill a DOCX template document with data.
+ *
+ * Processes all body content, headers, footers, footnotes, and endnotes.
+ * Operates on the document model in-place and returns it.
+ *
+ * @param doc - The parsed DocxDocument model.
+ * @param data - Data to fill into the template.
+ * @param options - Optional template settings.
+ * @returns The same DocxDocument with placeholders resolved.
+ */
+export declare function fillTemplate(doc: DocxDocument, data: Record<string, unknown>, options?: TemplateOptions): DocxDocument;
+/**
+ * List all template tags found in a document.
+ *
+ * Scans body, headers, footers, footnotes, and endnotes for template
+ * placeholders. Useful for validating data objects against templates.
+ *
+ * @param doc - The parsed DocxDocument model.
+ * @param options - Optional settings (custom delimiters).
+ * @returns Array of all discovered template tags.
+ */
+export declare function listTemplateTags(doc: DocxDocument, options?: Pick<TemplateOptions, "delimiters">): TemplateTag[];
+export declare function isTemplateChart(v: unknown): v is TemplateChart;
+/**
+ * Enhanced fillTemplate that supports image (%img), richText (&rt),
+ * subDocument (>sub), and chart (^chart) placeholders in addition to the
+ * standard variable, conditional, and loop directives.
+ *
+ * Image placeholder: {{%imagePath}} — value must be a TemplateImage object.
+ * RichText placeholder: {{&richPath}} — value must be TemplateRichText (Run[]).
+ * SubDocument placeholder: {{>subPath}} — value must be TemplateSubDocument (BodyContent[]).
+ * Chart placeholder: {{^chartPath}} — value must be a TemplateChart object.
+ */
+export declare function fillTemplateEnhanced(doc: DocxDocument, data: Record<string, unknown>, options?: TemplateOptions): DocxDocument;