@makefully/adaptfully 5.0.1 → 5.0.3

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.0.3 — 2026-10-05
+
+### Changed
+
+- **Web packager** writes `game-config.js` (and injects the script) for **web** and **pwa** as well as **uwp**, so `window.gameConfig.version` / platform are stamped on every web-family route — matching electron and capacitor. HTTP analytics can then populate batch `appVersion` without a per-game `analyticsAppVersion` override.
+
+## 5.0.2 — 2026-10-05
+
+### Fixed
+
+- Wrapfully chore downloads stream to a temp `.zip` on disk and extract with **yauzl** (lazy file streams) instead of buffering the whole Electron/Steam artifact in RAM via `axios` `arraybuffer` + `unzip-stream` MatcherStream (Node heap OOM despite free system RAM).
+- Encrypted result envelopes decrypt with streamed AES-GCM (`aesDecryptFile`) to a plaintext zip file before extract.
+
 ## 5.0.1 — 2026-09-17
 
 ### Changed

package/README.md

@@ -178,7 +178,7 @@ Each platform entry may set a **`packager`** (`web`, `electron`, or `capacitor`)
 
 | Packager | Prebuild adds |
 |----------|---------------|
-| `web` | `game-config.js` for **`uwp`** platform prebuilds |
+| `web` | `game-config.js` for **web / uwp / pwa** platform prebuilds (version + platform for analytics) |
 | `electron` | `main.js` (Electron shell); `preload.js` when **`steam-auth`** is registered |
 | `capacitor` | `game-config.js`, Capacitor CSP/viewport; `social-login-config.js` when **`social-auth`** is registered |
 

package/lib/node/choreCrypto.js

@@ -2,14 +2,14 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import {Readable, PassThrough} from 'node:stream';
+import {PassThrough} from 'node:stream';
 import {pipeline} from 'node:stream/promises';
 import archiver from 'archiver';
-import unzipper from 'unzip-stream';
 import {
     WRAPFULLY_DEFAULT_KID,
     WRAPFULLY_DEFAULT_PUBLIC_KEY,
 } from './wrapfullyDefaultPublicKey.js';
+import {extractZipFile, zipHasEntries} from './unzip-file.js';
 
 const
     ENVELOPE_DATA = 'wrapfully.enc',
@@ -40,6 +40,38 @@ function aesDecrypt (key, blob) {
     return Buffer.concat([decipher.update(data), decipher.final()]);
 }
 
+/**
+ * Stream-decrypt an AES-256-GCM blob (iv||tag||ciphertext) from disk to disk.
+ * @param {Buffer} key
+ * @param {string} inPath
+ * @param {string} outPath
+ */
+export async function aesDecryptFile (key, inPath, outPath) {
+    const fh = await fs.promises.open(inPath, 'r');
+    const header = Buffer.alloc(28);
+    let bytesRead = 0;
+
+    try {
+        ({bytesRead} = await fh.read(header, 0, 28, 0));
+    } finally {
+        await fh.close();
+    }
+    if (bytesRead < 28) {
+        throw new Error('Encrypted payload too short for AES-GCM header');
+    }
+
+    const iv = header.subarray(0, 12);
+    const tag = header.subarray(12, 28);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+
+    decipher.setAuthTag(tag);
+    await pipeline(
+        fs.createReadStream(inPath, {start: 28}),
+        decipher,
+        fs.createWriteStream(outPath),
+    );
+}
+
 function wrapKey (aesKey, publicKeyPem) {
     return crypto.publicEncrypt(
         {
@@ -152,32 +184,71 @@ export async function createEnvelopeFromInnerZip (innerZip, {publicKeyPem, kid,
 }
 
 /**
- * Decrypt a completed Yap result envelope into a plaintext zip Buffer.
+ * Decrypt a completed Yap result envelope zip on disk into a plaintext zip file.
+ * Avoids holding the Electron/Steam artifact in RAM.
+ * @param {string} envelopeZipPath
+ * @param {string} resultPrivPem
+ * @param {string} outZipPath
+ * @returns {Promise<'envelope'|'passthrough'>} passthrough when file is already a plain zip
  */
-export async function decryptResultEnvelope (resultZipBuf, resultPrivPem) {
+export async function decryptResultEnvelopeToFile (envelopeZipPath, resultPrivPem, outZipPath) {
     if (!resultPrivPem) {
         throw new Error('Missing resultPriv for encrypted Wrapfully chore download.');
     }
 
+    const isEnvelope = await zipHasEntries(envelopeZipPath, [RESULT_DATA, RESULT_KEY]);
+
+    if (!isEnvelope) {
+        // Not an envelope — copy as-is (streamed); never extract the whole artifact.
+        await pipeline(
+            fs.createReadStream(envelopeZipPath),
+            fs.createWriteStream(outZipPath),
+        );
+
+        return 'passthrough';
+    }
+
     const tmp = path.join(os.tmpdir(), `adaptfully-result-${Date.now().toString(16)}`);
 
     fs.mkdirSync(tmp, {recursive: true});
     try {
-        await pipeline(Readable.from(resultZipBuf), unzipper.Extract({path: tmp}));
-        if (!fs.existsSync(path.join(tmp, RESULT_DATA))) {
-            // Not an envelope — return as-is
-            return resultZipBuf;
-        }
-        const ciphertext = fs.readFileSync(path.join(tmp, RESULT_DATA));
+        // Envelope zips are small (AES blob + wrapped key).
+        await extractZipFile(envelopeZipPath, tmp);
         const wrapped = fs.readFileSync(path.join(tmp, RESULT_KEY));
         const aesKey = unwrapKey(wrapped, resultPrivPem);
 
-        return aesDecrypt(aesKey, ciphertext);
+        await aesDecryptFile(aesKey, path.join(tmp, RESULT_DATA), outZipPath);
+
+        return 'envelope';
     } finally {
         fs.rmSync(tmp, {recursive: true, force: true});
     }
 }
 
+/**
+ * Decrypt a completed Yap result envelope into a plaintext zip Buffer.
+ * Prefer {@link decryptResultEnvelopeToFile} for large Electron artifacts.
+ */
+export async function decryptResultEnvelope (resultZipBuf, resultPrivPem) {
+    if (!resultPrivPem) {
+        throw new Error('Missing resultPriv for encrypted Wrapfully chore download.');
+    }
+
+    const stamp = Date.now().toString(16);
+    const envelopePath = path.join(os.tmpdir(), `adaptfully-env-${stamp}.zip`);
+    const outPath = path.join(os.tmpdir(), `adaptfully-plain-${stamp}.zip`);
+
+    try {
+        fs.writeFileSync(envelopePath, resultZipBuf);
+        await decryptResultEnvelopeToFile(envelopePath, resultPrivPem, outPath);
+
+        return fs.readFileSync(outPath);
+    } finally {
+        fs.rmSync(envelopePath, {force: true});
+        fs.rmSync(outPath, {force: true});
+    }
+}
+
 export function isResultEnvelopeBuffer (buf) {
     // Weak check — PK zip; decryptResultEnvelope falls back if members missing
     return Buffer.isBuffer(buf) && buf.length > 4 && buf[0] === 0x50 && buf[1] === 0x4b;

package/lib/node/deploy.js

@@ -1,19 +1,19 @@
 import axios from 'axios';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import {Readable} from 'node:stream';
 import {pipeline} from 'node:stream/promises';
-import unzipper from 'unzip-stream';
 import {createDeployArchive, createReleaseArchive, createSourceArchive} from './archive.js';
 import {clearStaleBuildExtract} from './artifacts.js';
 import {listHtmlFilesRecursive} from './fs-utils.js';
 import {printBuildReport} from './report.js';
 import {
     createEnvelopeFromInnerZip,
-    decryptResultEnvelope,
+    decryptResultEnvelopeToFile,
     generateResultKeyPair,
     resolveEncryptPublicKey,
 } from './choreCrypto.js';
+import {extractZipFile, fileLooksLikeZip} from './unzip-file.js';
 
 const POLL_MS = 5000;
 
@@ -47,22 +47,28 @@ export function buildWrapfullyJobConfig (stage, family, gameId, platformKey, dep
     return job;
 }
 
-async function streamToBuffer (stream) {
-    const chunks = [];
+async function sleep (ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
 
-    for await (const chunk of stream) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    }
+/**
+ * Stream an axios response body to a file (does not buffer the whole body in RAM).
+ * @param {import('axios').AxiosResponse} response
+ * @param {string} outPath
+ */
+async function streamAxiosResponseToFile (response, outPath) {
+    const body = response.data;
 
-    return Buffer.concat(chunks);
-}
+    if (!body || typeof body.pipe !== 'function') {
+        throw new Error('Expected a streaming HTTP response body');
+    }
 
-async function sleep (ms) {
-    await new Promise((resolve) => setTimeout(resolve, ms));
+    await pipeline(body, fs.createWriteStream(outPath));
 }
 
 /**
- * Submit zip to Showfully Yap, poll until complete, return result zip Buffer.
+ * Submit zip to Showfully Yap, poll until complete, stream result zip to disk.
+ * @returns {Promise<string>} absolute path to the downloaded zip (caller deletes)
  */
 export async function submitWrapfullyChore ({
     server,
@@ -159,22 +165,49 @@ export async function submitWrapfullyChore ({
 
     log(`adaptfully: downloading chore ${choreId}`);
     const downloadUrl = `${base}yap/wrapfully/${encodeURIComponent(choreId)}`;
-    const {data, headers: resHeaders} = await axios.get(downloadUrl, {
-        headers: {Authorization: `Bearer ${accessToken}`},
-        responseType: 'arraybuffer',
-        maxContentLength: Infinity,
-        validateStatus: () => true,
-    });
+    const downloadPath = path.join(
+        os.tmpdir(),
+        `adaptfully-chore-${choreId}-${Date.now().toString(16)}.zip`,
+    );
 
-    const ctype = resHeaders['content-type'] || '';
+    try {
+        const response = await axios.get(downloadUrl, {
+            headers: {Authorization: `Bearer ${accessToken}`},
+            responseType: 'stream',
+            maxContentLength: Infinity,
+            maxBodyLength: Infinity,
+            validateStatus: () => true,
+        });
+        const ctype = response.headers['content-type'] || '';
+
+        if (response.status >= 400 || ctype.includes('application/json')) {
+            const chunks = [];
+
+            for await (const chunk of response.data) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            const text = Buffer.concat(chunks).toString('utf8');
+            let message = 'Chore download failed';
+
+            try {
+                const json = JSON.parse(text);
 
-    if (ctype.includes('application/json')) {
-        const json = JSON.parse(Buffer.from(data).toString('utf8'));
+                message = json.errors?.[0] || message;
+            } catch {
+                if (text.trim()) {
+                    message = text.slice(0, 500);
+                }
+            }
+            throw new Error(message);
+        }
 
-        throw new Error(json.errors?.[0] || 'Chore download returned JSON');
+        await streamAxiosResponseToFile(response, downloadPath);
+    } catch (err) {
+        fs.rmSync(downloadPath, {force: true});
+        throw err;
     }
 
-    return Buffer.from(data);
+    return downloadPath;
 }
 
 /**
@@ -252,29 +285,17 @@ export async function send (
         log(`adaptfully: sending ${htmlFiles.length} HTML file(s) from ${path.resolve(deployFolder)}`);
     }
 
-    // Append wrapfully.json routing into the archive by rebuilding into a buffer.
+    // Append wrapfully.json by extracting the upload archive to disk, then rezipping.
     const job = buildWrapfullyJobConfig(stage, family, gameId, platformKey, options.deploymentKey);
     const innerChunks = [];
-
-    // Re-pack: read archiveStream into zip, add wrapfully.json
-    // Archiver streams aren't easily mutable — collect then use yazl-free approach:
-    // pipe archive to buffer, unzip to tmp, add file, rezip is heavy.
-    // Simpler: createSourceArchive already finalized as stream — append via second archiver
-    // that copies entries is complex. Instead append wrapfully.json by concatenating
-    // a sidecar zip is wrong. Best: write wrapfully.json into deploy folder meta before
-    // archive... but that mutates disk.
-    //
-    // Practical approach matching Dutifully: build archive, buffer it, then use a new
-    // archiver that includes the buffer as... no that's nested.
-    //
-    // Use jszip-like: buffer the created archive by consuming stream, then use
-    // adm-zip equivalent — we have unzipper. Extract to tmp, write wrapfully.json, rezip.
-
-    const tmpRoot = path.join(outputRoot, `.adaptfully-yap-${Date.now().toString(16)}`);
+    const stamp = Date.now().toString(16);
+    const tmpRoot = path.join(outputRoot, `.adaptfully-yap-${stamp}`);
+    const uploadZipPath = path.join(outputRoot, `.adaptfully-upload-${stamp}.zip`);
 
     fs.mkdirSync(tmpRoot, {recursive: true});
     try {
-        await pipeline(archiveStream, unzipper.Extract({path: tmpRoot, concurrency: 1}));
+        await pipeline(archiveStream, fs.createWriteStream(uploadZipPath));
+        await extractZipFile(uploadZipPath, tmpRoot);
         fs.writeFileSync(path.join(tmpRoot, 'wrapfully.json'), JSON.stringify(job, null, 2));
 
         const {default: archiver} = await import('archiver');
@@ -296,6 +317,7 @@ export async function send (
         await done;
     } finally {
         fs.rmSync(tmpRoot, {recursive: true, force: true});
+        fs.rmSync(uploadZipPath, {force: true});
     }
 
     let uploadBuffer = Buffer.concat(innerChunks);
@@ -318,39 +340,58 @@ export async function send (
         log(`adaptfully: encrypting chore with kid "${kid}"`);
     }
 
-    let resultBuffer = await submitWrapfullyChore({
+    const downloadPath = await submitWrapfullyChore({
         server,
         accessToken,
         zipBuffer: uploadBuffer,
         log,
     });
+    const plainZipPath = path.join(
+        os.tmpdir(),
+        `adaptfully-plain-${path.basename(downloadPath)}`,
+    );
+    let resultZipPath = downloadPath;
 
-    if (resultPriv) {
-        try {
-            resultBuffer = await decryptResultEnvelope(resultBuffer, resultPriv);
-        } catch (err) {
-            throw new Error(`Failed to decrypt Wrapfully result envelope: ${err.message || err}`);
+    try {
+        if (resultPriv) {
+            try {
+                await decryptResultEnvelopeToFile(downloadPath, resultPriv, plainZipPath);
+                resultZipPath = plainZipPath;
+            } catch (err) {
+                throw new Error(
+                    `Failed to decrypt Wrapfully result envelope: ${err.message || err}`
+                );
+            }
         }
-    }
-
-    if (!Buffer.isBuffer(resultBuffer) || resultBuffer.length < 4
-        || resultBuffer[0] !== 0x50 || resultBuffer[1] !== 0x4b) {
-        throw new Error('Chore download is not a valid zip (truncated or corrupt response)');
-    }
 
-    const destination = mode === 'extract'
-        ? unzipper.Extract({path: `${extractRoot}/`, concurrency: 1})
-        : fs.createWriteStream(`${extractRoot}/${pkg.name}-${pkg.version}-${stage}-${family}.zip`);
+        if (!fileLooksLikeZip(resultZipPath)) {
+            throw new Error('Chore download is not a valid zip (truncated or corrupt response)');
+        }
 
-    try {
-        await pipeline(Readable.from(resultBuffer), destination);
-    } catch (err) {
-        throw new Error(
-            `Failed to unpack chore result (${resultBuffer.length} bytes): ${err.message || err}`
-        );
-    }
+        if (mode === 'extract') {
+            try {
+                await extractZipFile(resultZipPath, extractRoot);
+            } catch (err) {
+                const size = fs.statSync(resultZipPath).size;
 
-    if (mode === 'extract') {
-        printBuildReport(`${stage}-${family}`, pkg, { extractRoot });
+                throw new Error(
+                    `Failed to unpack chore result (${size} bytes): ${err.message || err}`
+                );
+            }
+            printBuildReport(`${stage}-${family}`, pkg, {extractRoot});
+        } else {
+            const destZip = path.join(
+                extractRoot,
+                `${pkg.name}-${pkg.version}-${stage}-${family}.zip`,
+            );
+
+            await pipeline(
+                fs.createReadStream(resultZipPath),
+                fs.createWriteStream(destZip),
+            );
+        }
+    } finally {
+        fs.rmSync(downloadPath, {force: true});
+        fs.rmSync(plainZipPath, {force: true});
     }
 }

package/lib/node/packagers/web.js

@@ -8,6 +8,8 @@ export class WebPackager extends Packager {
     static defaultPlatforms = ['web', 'uwp', 'pwa'];
 
     needsGameConfig() {
-        return this.platformKey === 'uwp';
+        // Stamp version/platform for all web-family routes (web, uwp, pwa) so
+        // analytics resolveAppVersion() matches electron/capacitor builds.
+        return true;
     }
 }

package/lib/node/unzip-file.js

@@ -0,0 +1,194 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {pipeline} from 'node:stream/promises';
+import yauzl from 'yauzl';
+
+/**
+ * Resolve entry path under destDir; reject zip-slip escapes.
+ * @param {string} destDir
+ * @param {string} fileName
+ */
+function safeEntryPath (destDir, fileName) {
+    const root = path.resolve(destDir);
+    const target = path.resolve(root, fileName);
+
+    if (target !== root && !target.startsWith(root + path.sep)) {
+        throw new Error(`Refusing zip entry outside extract root: ${fileName}`);
+    }
+
+    return target;
+}
+
+/**
+ * Whether a zip on disk contains every listed entry name (forward-slash paths).
+ * @param {string} zipPath
+ * @param {string[]} entryNames
+ * @returns {Promise<boolean>}
+ */
+export function zipHasEntries (zipPath, entryNames) {
+    const needed = new Set(entryNames.map((n) => String(n).replace(/\\/g, '/')));
+
+    return new Promise((resolve, reject) => {
+        yauzl.open(zipPath, {lazyEntries: true, autoClose: true}, (openErr, zipfile) => {
+            if (openErr) {
+                reject(openErr);
+
+                return;
+            }
+
+            let settled = false;
+            const found = new Set();
+            const fail = (err) => {
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            };
+            const finish = (value) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(value);
+                }
+            };
+
+            zipfile.on('error', fail);
+            zipfile.on('end', () => {
+                finish([...needed].every((n) => found.has(n)));
+            });
+            zipfile.readEntry();
+
+            zipfile.on('entry', (entry) => {
+                const name = String(entry.fileName || '').replace(/\\/g, '/');
+
+                if (needed.has(name)) {
+                    found.add(name);
+                    if (found.size === needed.size) {
+                        // Close early once all required members are present.
+                        try {
+                            zipfile.close();
+                        } catch {
+                            // ignore
+                        }
+                        finish(true);
+
+                        return;
+                    }
+                }
+                zipfile.readEntry();
+            });
+        });
+    });
+}
+
+/**
+ * Extract a zip on disk into destDir without holding the archive in RAM.
+ * Uses yauzl lazy entries + per-file streams.
+ * @param {string} zipPath
+ * @param {string} destDir
+ * @returns {Promise<void>}
+ */
+export function extractZipFile (zipPath, destDir) {
+    fs.mkdirSync(destDir, {recursive: true});
+
+    return new Promise((resolve, reject) => {
+        yauzl.open(zipPath, {lazyEntries: true, autoClose: true}, (openErr, zipfile) => {
+            if (openErr) {
+                reject(openErr);
+
+                return;
+            }
+
+            let settled = false;
+            const fail = (err) => {
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            };
+            const done = () => {
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+            };
+
+            zipfile.on('error', fail);
+            zipfile.on('end', done);
+            zipfile.readEntry();
+
+            zipfile.on('entry', (entry) => {
+                const name = String(entry.fileName || '').replace(/\\/g, '/');
+
+                if (!name || name.includes('\0')) {
+                    fail(new Error(`Invalid zip entry name: ${entry.fileName}`));
+
+                    return;
+                }
+
+                let destPath;
+
+                try {
+                    destPath = safeEntryPath(destDir, name);
+                } catch (err) {
+                    fail(err);
+
+                    return;
+                }
+
+                if (/\/$/u.test(name)) {
+                    try {
+                        fs.mkdirSync(destPath, {recursive: true});
+                    } catch (err) {
+                        fail(err);
+
+                        return;
+                    }
+                    zipfile.readEntry();
+
+                    return;
+                }
+
+                try {
+                    fs.mkdirSync(path.dirname(destPath), {recursive: true});
+                } catch (err) {
+                    fail(err);
+
+                    return;
+                }
+
+                zipfile.openReadStream(entry, (streamErr, readStream) => {
+                    if (streamErr) {
+                        fail(streamErr);
+
+                        return;
+                    }
+                    const writeStream = fs.createWriteStream(destPath);
+
+                    pipeline(readStream, writeStream)
+                        .then(() => {
+                            zipfile.readEntry();
+                        })
+                        .catch(fail);
+                });
+            });
+        });
+    });
+}
+
+/**
+ * Peek whether a file starts with the ZIP local-file magic (`PK`).
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function fileLooksLikeZip (filePath) {
+    const fd = fs.openSync(filePath, 'r');
+
+    try {
+        const buf = Buffer.alloc(4);
+        const n = fs.readSync(fd, buf, 0, 4, 0);
+
+        return n >= 2 && buf[0] === 0x50 && buf[1] === 0x4b;
+    } finally {
+        fs.closeSync(fd);
+    }
+}

package/lib/runtime/analytics/_helpers.js

@@ -9,6 +9,7 @@
  *   analyticsEnabled   — when false, track is a no-op (default true when endpoint set)
  *   analyticsPlatform  — optional override; else window.gameConfig.platform
  *   analyticsAppVersion — optional override; else window.gameConfig.version / config.appVersion
+ *                       (web/uwp/pwa/electron/capacitor prebuilds all write game-config.js)
  */
 (function registerAnalyticsHelpers(ns) {
     const OPT_OUT_KEY = 'adaptfully_analytics_opt_out';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/adaptfully",
-    "version": "5.0.1",
+    "version": "5.0.3",
     "description": "Platform abstraction and Wrapfully deploy client for Makefully games",
     "type": "module",
     "main": "./lib/node/index.js",
@@ -58,6 +58,6 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "axios": "^1.7.9",
-        "unzip-stream": "^0.3.4"
+        "yauzl": "^3.4.0"
     }
 }