@zola_do/docx 0.3.6 → 0.3.7

package/README.md

@@ -15,6 +15,27 @@ DOCX template processing for NestJS using docx-templates.
 - **Handlebars Syntax** — Supports loops, conditionals, images
 - **Buffer Output** — Returns generated DOCX as Buffer
 
+## Security
+
+`docx-templates` evaluates template commands in a JavaScript VM. **Only use trusted, version-controlled templates** (stored in your repo or admin-only object storage). Do not accept user-uploaded `.docx` files for server-side rendering.
+
+By default, `@zola_do/docx`:
+
+- Rejects templates containing `EXEC` commands (`allowExec: true` only for fully trusted templates).
+- Keeps VM sandbox enabled (`noSandbox: false`); `allowUnsafeJs` is required to disable it or supply custom `runJs`.
+- Uses `secureCreateReport()` internally from `DocxService.generateDocx()`.
+
+```typescript
+import { secureCreateReport } from '@zola_do/docx';
+
+// Optional escape hatch for trusted internal templates only:
+await secureCreateReport({
+  template,
+  data,
+  allowExec: true,
+});
+```
+
 ## Installation
 
 ```bash

package/dist/docx-template-security.helper.d.ts

@@ -0,0 +1,13 @@
+import { createReport } from 'docx-templates';
+export type SecureDocxTemplateOptions = {
+    cmdDelimiter?: string | [string, string];
+    allowExec?: boolean;
+    allowUnsafeJs?: boolean;
+};
+type CreateReportOptions = Parameters<typeof createReport>[0];
+export declare const DOCX_TRUSTED_TEMPLATES_ONLY = "DOCX templates must be trusted and version-controlled. User-uploaded templates are not supported. EXEC commands are rejected by default.";
+export declare function resolveCmdDelimiter(delimiter?: string | [string, string]): [string, string];
+export declare function assertTrustedDocxTemplate(template: Buffer | Uint8Array, options?: SecureDocxTemplateOptions): Promise<void>;
+export declare function buildSecureCreateReportOptions(options?: SecureDocxTemplateOptions & Partial<Pick<CreateReportOptions, 'cmdDelimiter' | 'additionalJsContext' | 'failFast' | 'noSandbox' | 'runJs'>>): Partial<CreateReportOptions>;
+export declare function secureCreateReport(options: CreateReportOptions & SecureDocxTemplateOptions): Promise<Uint8Array>;
+export {};

package/dist/docx-template-security.helper.js

@@ -0,0 +1,73 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCX_TRUSTED_TEMPLATES_ONLY = void 0;
+exports.resolveCmdDelimiter = resolveCmdDelimiter;
+exports.assertTrustedDocxTemplate = assertTrustedDocxTemplate;
+exports.buildSecureCreateReportOptions = buildSecureCreateReportOptions;
+exports.secureCreateReport = secureCreateReport;
+const common_1 = require("@nestjs/common");
+const docx_templates_1 = require("docx-templates");
+exports.DOCX_TRUSTED_TEMPLATES_ONLY = 'DOCX templates must be trusted and version-controlled. User-uploaded templates are not supported. EXEC commands are rejected by default.';
+const DEFAULT_CMD_DELIMITER = ['+++', '+++'];
+function resolveCmdDelimiter(delimiter) {
+    if (!delimiter) {
+        return DEFAULT_CMD_DELIMITER;
+    }
+    if (Array.isArray(delimiter)) {
+        return delimiter;
+    }
+    return [delimiter, delimiter];
+}
+async function assertTrustedDocxTemplate(template, options = {}) {
+    if (options.allowExec) {
+        return;
+    }
+    const commands = await (0, docx_templates_1.listCommands)(new Uint8Array(template), resolveCmdDelimiter(options.cmdDelimiter));
+    const execCommands = commands.filter((command) => command.type === 'EXEC');
+    if (execCommands.length > 0) {
+        throw new common_1.BadRequestException(`${exports.DOCX_TRUSTED_TEMPLATES_ONLY} Rejected EXEC command(s): ${execCommands
+            .map((command) => command.raw)
+            .join(', ')}`);
+    }
+}
+function buildSecureCreateReportOptions(options = {}) {
+    var _a, _b;
+    if (options.noSandbox === true && !options.allowUnsafeJs) {
+        throw new common_1.BadRequestException(`${exports.DOCX_TRUSTED_TEMPLATES_ONLY} noSandbox is not allowed.`);
+    }
+    if (options.runJs && !options.allowUnsafeJs) {
+        throw new common_1.BadRequestException(`${exports.DOCX_TRUSTED_TEMPLATES_ONLY} Custom runJs is not allowed.`);
+    }
+    return {
+        cmdDelimiter: options.cmdDelimiter,
+        additionalJsContext: options.additionalJsContext,
+        failFast: (_a = options.failFast) !== null && _a !== void 0 ? _a : true,
+        noSandbox: options.allowUnsafeJs ? (_b = options.noSandbox) !== null && _b !== void 0 ? _b : false : false,
+        runJs: options.allowUnsafeJs ? options.runJs : undefined,
+    };
+}
+async function secureCreateReport(options) {
+    await assertTrustedDocxTemplate(options.template, options);
+    const { allowExec, allowUnsafeJs } = options, createOptions = __rest(options, ["allowExec", "allowUnsafeJs"]);
+    return (0, docx_templates_1.createReport)(Object.assign(Object.assign({}, createOptions), buildSecureCreateReportOptions({
+        allowExec,
+        allowUnsafeJs,
+        cmdDelimiter: createOptions.cmdDelimiter,
+        additionalJsContext: createOptions.additionalJsContext,
+        failFast: createOptions.failFast,
+        noSandbox: createOptions.noSandbox,
+        runJs: createOptions.runJs,
+    })));
+}
+//# sourceMappingURL=docx-template-security.helper.js.map

package/dist/docx-template-security.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docx-template-security.helper.js","sourceRoot":"","sources":["../src/docx-template-security.helper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA,2CAAqD;AACrD,mDAA4D;AAY/C,QAAA,2BAA2B,GACtC,0IAA0I,CAAC;AAE7I,MAAM,qBAAqB,GAAqB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE/D,6BACE,SAAqC;IAErC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAChC,CAAC;AAEM,KAAK,oCACV,QAA6B,EAC7B,OAAO,GAA8B,EAAE;IAEvC,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,IAAA,6BAAY,EACjC,IAAI,UAAU,CAAC,QAAQ,CAAQ,EAC/B,mBAAmB,CAAC,OAAO,CAAC,YAAY,CAAC,CAC1C,CAAC;IAEF,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IAC3E,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,4BAAmB,CAC3B,GAAG,QAAA,2BAA2B,8BAA8B,YAAY;aACrE,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;aAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,CAChB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,wCACE,OAAO,GAUD,EAAE;;IAER,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;QACzD,MAAM,IAAI,4BAAmB,CAC3B,GAAG,QAAA,2BAA2B,4BAA4B,CAC3D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;QAC5C,MAAM,IAAI,4BAAmB,CAC3B,GAAG,QAAA,2BAA2B,+BAA+B,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,QAAQ,QAAE,OAAO,CAAC,QAAQ,mCAAI,IAAI;QAClC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,OAAC,OAAO,CAAC,SAAS,mCAAI,KAAK,CAAC,CAAC,CAAC,KAAK;QACrE,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;KACzD,CAAC;AACJ,CAAC;AAEM,KAAK,6BACV,OAAwD;IAExD,MAAM,yBAAyB,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAE3D,MAAM,EAAE,SAAS,EAAE,aAAa,KAAuB,OAAO,EAAzB,aAAa,UAAK,OAAO,EAAxD,8BAA8C,CAAU,CAAC;IAE/D,OAAO,IAAA,6BAAY,kCACd,aAAa,GACb,8BAA8B,CAAC;QAChC,SAAS;QACT,aAAa;QACb,YAAY,EAAE,aAAa,CAAC,YAAY;QACxC,mBAAmB,EAAE,aAAa,CAAC,mBAAmB;QACtD,QAAQ,EAAE,aAAa,CAAC,QAAQ;QAChC,SAAS,EAAE,aAAa,CAAC,SAAS;QAClC,KAAK,EAAE,aAAa,CAAC,KAAK;KAC3B,CAAC,EACF,CAAC;AACL,CAAC"}

package/dist/docx.service.d.ts

@@ -1,4 +1,5 @@
+import { type SecureDocxTemplateOptions } from './docx-template-security.helper';
 export declare class DocxService {
-    validateDocument(template: Buffer, requiredProperties: string[]): Promise<string[]>;
-    generateDocx(template: Buffer, data: any): Promise<Buffer<ArrayBuffer>>;
+    validateDocument(template: Buffer, requiredProperties: string[], options?: SecureDocxTemplateOptions): Promise<string[]>;
+    generateDocx(template: Buffer, data: any, options?: SecureDocxTemplateOptions): Promise<Buffer<ArrayBuffer>>;
 }

package/dist/docx.service.js

@@ -9,10 +9,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocxService = void 0;
 const common_1 = require("@nestjs/common");
 const docx_templates_1 = require("docx-templates");
+const docx_template_security_helper_1 = require("./docx-template-security.helper");
 let DocxService = class DocxService {
-    async validateDocument(template, requiredProperties) {
+    async validateDocument(template, requiredProperties, options = {}) {
+        var _a;
         try {
-            const providedValues = await (0, docx_templates_1.listCommands)(new Uint8Array(template), ['{', '}']);
+            const cmdDelimiter = (_a = options.cmdDelimiter) !== null && _a !== void 0 ? _a : ['{', '}'];
+            const providedValues = await (0, docx_templates_1.listCommands)(new Uint8Array(template), cmdDelimiter);
+            await (0, docx_template_security_helper_1.assertTrustedDocxTemplate)(template, Object.assign(Object.assign({}, options), { cmdDelimiter }));
             const result = requiredProperties.filter((r) => !providedValues.find((p) => p.code == r));
             return result;
         }
@@ -20,10 +24,13 @@ let DocxService = class DocxService {
             throw error;
         }
     }
-    async generateDocx(template, data) {
-        const buffer = await (0, docx_templates_1.createReport)({
+    async generateDocx(template, data, options = {}) {
+        const buffer = await (0, docx_template_security_helper_1.secureCreateReport)({
             template: template,
             data,
+            cmdDelimiter: options.cmdDelimiter,
+            allowExec: options.allowExec,
+            allowUnsafeJs: options.allowUnsafeJs,
         });
         return Buffer.from(buffer);
     }

package/dist/docx.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"docx.service.js","sourceRoot":"","sources":["../src/docx.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAC5C,mDAA4D;AAGrD,IAAM,WAAW,GAAjB,MAAM,WAAW;IACtB,KAAK,CAAC,gBAAgB,CAAC,QAAgB,EAAE,kBAA4B;QACnE,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,MAAM,IAAA,6BAAY,EACvC,IAAI,UAAU,CAAC,QAAQ,CAAQ,EAC/B,CAAC,GAAG,EAAE,GAAG,CAAC,CACX,CAAC;YACF,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAChD,CAAC;YACF,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,IAAS;QAC5C,MAAM,MAAM,GAAG,MAAM,IAAA,6BAAY,EAAC;YAChC,QAAQ,EAAE,QAAe;YACzB,IAAI;SACL,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACF,CAAA;;sBAvBY,WAAW;IADvB,IAAA,mBAAU,GAAE;GACA,WAAW,CAuBvB"}
+{"version":3,"file":"docx.service.js","sourceRoot":"","sources":["../src/docx.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAC5C,mDAA8C;AAC9C,mFAIyC;AAGlC,IAAM,WAAW,GAAjB,MAAM,WAAW;IACtB,KAAK,CAAC,gBAAgB,CACpB,QAAgB,EAChB,kBAA4B,EAC5B,OAAO,GAA8B,EAAE;;QAEvC,IAAI,CAAC;YACH,MAAM,YAAY,SAAG,OAAO,CAAC,YAAY,mCAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACxD,MAAM,cAAc,GAAG,MAAM,IAAA,6BAAY,EACvC,IAAI,UAAU,CAAC,QAAQ,CAAQ,EAC/B,YAAY,CACb,CAAC;YACF,MAAM,IAAA,yDAAyB,EAAC,QAAQ,kCACnC,OAAO,KACV,YAAY,IACZ,CAAC;YACH,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAChD,CAAC;YACF,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,QAAgB,EAChB,IAAS,EACT,OAAO,GAA8B,EAAE;QAEvC,MAAM,MAAM,GAAG,MAAM,IAAA,kDAAkB,EAAC;YACtC,QAAQ,EAAE,QAAe;YACzB,IAAI;YACJ,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,aAAa,EAAE,OAAO,CAAC,aAAa;SACrC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACF,CAAA;;sBAvCY,WAAW;IADvB,IAAA,mBAAU,GAAE;GACA,WAAW,CAuCvB"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './docx.module';
 export * from './docx.service';
+export * from './docx-template-security.helper';

package/dist/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./docx.module"), exports);
 __exportStar(require("./docx.service"), exports);
+__exportStar(require("./docx-template-security.helper"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,iDAA+B;AAC/B,kEAAgD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/docx",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "DOCX template processing for NestJS",
   "author": "zolaDO",
   "license": "ISC",