@hahnpro/flow-sdk 2026.7.8 → 2026.7.10

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @hahnpro/flow-sdk
 
+## 2026.7.9
+
+- Added `extractZip(zipPath, dir)` for extracting a ZIP archive into an absolute target directory. Replaces the unmaintained `extract-zip` package, which stalls mid-entry on Node 26 and leaves the returned promise pending forever
+
 ## 2026.6.1
 
 - Fixed sdk api type in FlowApplication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hahnpro/flow-sdk",
-  "version": "2026.7.8",
+  "version": "2026.7.10",
   "description": "SDK for building Flow Modules",
   "license": "MIT",
   "author": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@hahnpro/hpc-api": "2026.7.8",
+    "@hahnpro/hpc-api": "2026.7.10",
     "@nats-io/jetstream": "3.4.0",
     "@nats-io/nats-core": "3.4.0",
     "@nats-io/transport-node": "3.4.0",
@@ -29,11 +29,12 @@
     "python-shell": "5.0.0",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2",
-    "string-interp": "0.3.6"
+    "string-interp": "0.3.6",
+    "yauzl": "3.4.0"
   },
   "devDependencies": {
     "@types/lodash": "4.17.24",
-    "@types/node": "25.9.5",
+    "@types/node": "24.13.3",
     "class-validator-jsonschema": "5.1.0",
     "typescript": "6.0.3"
   },

package/src/index.d.ts

@@ -1,6 +1,7 @@
 export * from '@hahnpro/hpc-api';
 export { LifecycleEvent, type ClassType, type DeploymentMessage, type Flow, type FlowContext, type FlowElementContext, type StreamOptions, } from './lib/flow.interface';
 export * from './lib/utils';
+export { extractZip } from './lib/archive';
 export * from './lib/FlowApplication';
 export { FlowDashboard, FlowElement, FlowFunction, FlowResource, FlowTask, FlowTrigger, InputStream } from './lib/FlowElement';
 export * from './lib/FlowEvent';

package/src/index.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IncompatableWith = exports.FlowModule = exports.InputStream = exports.FlowTrigger = exports.FlowTask = exports.FlowResource = exports.FlowFunction = exports.FlowElement = exports.FlowDashboard = exports.LifecycleEvent = void 0;
+exports.IncompatableWith = exports.FlowModule = exports.InputStream = exports.FlowTrigger = exports.FlowTask = exports.FlowResource = exports.FlowFunction = exports.FlowElement = exports.FlowDashboard = exports.extractZip = exports.LifecycleEvent = void 0;
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("@hahnpro/hpc-api"), exports);
 var flow_interface_1 = require("./lib/flow.interface");
 Object.defineProperty(exports, "LifecycleEvent", { enumerable: true, get: function () { return flow_interface_1.LifecycleEvent; } });
 tslib_1.__exportStar(require("./lib/utils"), exports);
+var archive_1 = require("./lib/archive");
+Object.defineProperty(exports, "extractZip", { enumerable: true, get: function () { return archive_1.extractZip; } });
 tslib_1.__exportStar(require("./lib/FlowApplication"), exports);
 var FlowElement_1 = require("./lib/FlowElement");
 Object.defineProperty(exports, "FlowDashboard", { enumerable: true, get: function () { return FlowElement_1.FlowDashboard; } });

package/src/lib/archive.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Extracts a ZIP archive into an absolute target directory
+ */
+export declare function extractZip(zipPath: string, dir: string): Promise<void>;

package/src/lib/archive.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractZip = extractZip;
+const tslib_1 = require("tslib");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:stream/promises");
+const yauzl_1 = tslib_1.__importDefault(require("yauzl"));
+const S_IFMT = 0o170000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+const DEFAULT_DIR_MODE = 0o755;
+const DEFAULT_FILE_MODE = 0o644;
+const WRITE_FLAGS = node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_CREAT | node_fs_1.constants.O_TRUNC | (node_fs_1.constants.O_NOFOLLOW ?? 0);
+const openZip = (zipPath) => new Promise((resolve, reject) => {
+    yauzl_1.default.open(zipPath, { lazyEntries: true }, (err, zipfile) => (err ? reject(err) : resolve(zipfile)));
+});
+const openReadStream = (zipfile, entry) => new Promise((resolve, reject) => {
+    zipfile.openReadStream(entry, (err, stream) => (err ? reject(err) : resolve(stream)));
+});
+const readAll = async (stream) => {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+};
+const isDirectoryEntry = (entry, mode) => {
+    if ((mode & S_IFMT) === S_IFDIR) {
+        return true;
+    }
+    if (entry.fileName.endsWith('/')) {
+        return true;
+    }
+    return entry.versionMadeBy >> 8 === 0 && entry.externalFileAttributes === 16;
+};
+const outOfBounds = (path, fileName) => new Error(`Out of bound path "${path}" found while processing file ${fileName}`);
+/** Resolves an entry against the target directory, rejecting names that point outside it. */
+const resolveEntryPath = (targetDir, fileName) => {
+    const dest = (0, node_path_1.join)(targetDir, fileName);
+    const rel = (0, node_path_1.relative)(targetDir, dest);
+    if (rel !== '' && (rel.split(node_path_1.sep).includes('..') || (0, node_path_1.isAbsolute)(rel))) {
+        throw outOfBounds(dest, fileName);
+    }
+    return dest;
+};
+/**
+ * Creates the missing components of `dir` one level at a time, refusing to descend through
+ * a symlink. A recursive mkdir would instead follow a symlink planted by an earlier entry
+ * and create directories outside the target before any check could reject the path.
+ */
+const mkdirContained = async (targetDir, dir, fileName, mode) => {
+    const rel = (0, node_path_1.relative)(targetDir, dir);
+    if (rel === '') {
+        return;
+    }
+    let current = targetDir;
+    for (const segment of rel.split(node_path_1.sep)) {
+        current = (0, node_path_1.join)(current, segment);
+        const stats = await node_fs_1.promises.lstat(current).catch(() => null);
+        if (stats === null) {
+            await node_fs_1.promises.mkdir(current, mode === undefined ? undefined : { mode }).catch((err) => {
+                if (err.code !== 'EEXIST') {
+                    throw err;
+                }
+            });
+            continue;
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw outOfBounds(current, fileName);
+        }
+    }
+};
+const extractEntry = async (zipfile, entry, targetDir, dest) => {
+    const mode = (entry.externalFileAttributes >>> 16) & 0xffff;
+    const isDir = isDirectoryEntry(entry, mode);
+    const isSymlink = (mode & S_IFMT) === S_IFLNK;
+    const effectiveMode = mode === 0 ? (isDir ? DEFAULT_DIR_MODE : DEFAULT_FILE_MODE) : mode;
+    const procMode = effectiveMode & 0o777;
+    if (isDir) {
+        await mkdirContained(targetDir, dest, entry.fileName, procMode);
+        return;
+    }
+    const readStream = await openReadStream(zipfile, entry);
+    if (isSymlink) {
+        await node_fs_1.promises.symlink(await readAll(readStream), dest);
+    }
+    else {
+        const handle = await node_fs_1.promises.open(dest, WRITE_FLAGS, procMode);
+        await (0, promises_1.pipeline)(readStream, handle.createWriteStream());
+    }
+};
+/**
+ * Extracts a ZIP archive into an absolute target directory
+ */
+async function extractZip(zipPath, dir) {
+    if (!(0, node_path_1.isAbsolute)(dir)) {
+        throw new Error('Target directory is expected to be absolute');
+    }
+    await node_fs_1.promises.mkdir(dir, { recursive: true });
+    const targetDir = await node_fs_1.promises.realpath(dir);
+    const zipfile = await openZip(zipPath);
+    return new Promise((resolve, reject) => {
+        let canceled = false;
+        const fail = (err) => {
+            if (canceled) {
+                return;
+            }
+            canceled = true;
+            zipfile.close();
+            reject(err);
+        };
+        zipfile.on('error', (err) => {
+            canceled = true;
+            reject(err);
+        });
+        zipfile.on('close', () => {
+            if (!canceled) {
+                resolve();
+            }
+        });
+        zipfile.on('entry', (entry) => {
+            if (canceled) {
+                return;
+            }
+            if (entry.fileName.startsWith('__MACOSX/')) {
+                zipfile.readEntry();
+                return;
+            }
+            void (async () => {
+                try {
+                    const dest = resolveEntryPath(targetDir, entry.fileName);
+                    await mkdirContained(targetDir, (0, node_path_1.dirname)(dest), entry.fileName);
+                    await extractEntry(zipfile, entry, targetDir, dest);
+                    zipfile.readEntry();
+                }
+                catch (err) {
+                    fail(err);
+                }
+            })();
+        });
+        zipfile.readEntry();
+    });
+}