.github/workflows/add-to-project.yml

@@ -21,7 +21,7 @@ jobs:
           creds: ${{ secrets.ECOSYSTEM_ISSUE_TRIAGE_GH_APP_CREDS }}
           org: electron
       - name: Add to Project
-        uses: dsanders11/project-actions/add-item@eb760c48894b5702398529cbb8f6e98378e315d0 # v1.3.0
+        uses: dsanders11/project-actions/add-item@9c80cd31f58599941c64f74636bea95ba5d46090 # v1.5.1
         with:
           field: Opened
           field-value: ${{ github.event.pull_request.created_at || github.event.issue.created_at }}

.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: test
+    environment: npm
+    permissions:
+      id-token: write # for CFA and npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+        with:
+          node-version: 20.x
+          cache: 'yarn'
+      - name: Install
+        run: yarn install --frozen-lockfile
+      - uses: continuousauth/action@4e8a2573eeb706f6d7300d6a9f3ca6322740b72d # v1.0.5
+        with:
+          project-id: ${{ secrets.CFA_PROJECT_ID }}
+          secret: ${{ secrets.CFA_SECRET }}
+          npm-token: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Test
+
+on:
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: '0 22 * * 3'
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - '20.10'
+          - '18.18'
+          - '16.20'
+        os:
+          - macos-latest
+          - ubuntu-22.04
+          - windows-latest
+    runs-on: "${{ matrix.os }}"
+    steps:
+      - name: Install Linux Dependencies
+        if: ${{ matrix.os == 'ubuntu-22.04' }}
+        run: sudo apt-get update && sudo apt-get install --no-install-recommends -y libasound2 libgtk-3-0 libnss3 libxss1 libxtst6 xvfb libgbm-dev
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Setup Node.js
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+        with:
+          node-version: "${{ matrix.node-version }}"
+          cache: 'yarn'
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test
+        run: yarn test

.mocharc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  'watch-files': ['test/**/*.js', 'lib/**/*.js'],
+  recursive: true,
+  file: './test/mocha.setup.js', // setup file before everything else loads
+  'forbid-only': process.env.CI ?? false, // make sure no `test.only` is merged into `main`
+  reporter: 'spec',
+};

README.md

@@ -1,6 +1,6 @@
 # @electron/asar - Electron Archive
 
-[![CircleCI build status](https://circleci.com/gh/electron/asar/tree/main.svg?style=shield)](https://circleci.com/gh/electron/asar/tree/main)
+[![Test](https://github.com/electron/asar/actions/workflows/test.yml/badge.svg)](https://github.com/electron/asar/actions/workflows/test.yml)
 [![npm version](http://img.shields.io/npm/v/@electron/asar.svg)](https://npmjs.org/package/@electron/asar)
 
 Asar is a simple extensive archive format, it works like `tar` that concatenates
@@ -116,10 +116,6 @@ await asar.createPackageWithOptions(src, dest, { transform: transform });
 console.log('done.');
 ```
 
-## Using with grunt
-
-There is also an unofficial grunt plugin to generate asar archives at [bwin/grunt-asar][grunt-asar].
-
 ## Format
 
 Asar uses [Pickle][pickle] to safely serialize binary value to file.
@@ -210,4 +206,3 @@ convert `Number` to UINT64.
 * A integer value `blockSize` representing the size in bytes of each block in the `blocks` hashes above
 
 [pickle]: https://chromium.googlesource.com/chromium/src/+/main/base/pickle.h
-[grunt-asar]: https://github.com/bwin/grunt-asar

package.json

@@ -23,12 +23,17 @@
   "bugs": {
     "url": "https://github.com/electron/asar/issues"
   },
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "build": "tsc",
-    "mocha": "xvfb-maybe electron-mocha --reporter spec && mocha --reporter spec",
+    "mocha": "xvfb-maybe electron-mocha && mocha",
+    "mocha:update": "mocha --update",
+    "mocha:watch": "mocha --watch",
     "test": "yarn lint && yarn mocha",
     "lint": "yarn prettier:check",
-    "prettier": "prettier \"src/**/*.ts\" \"test/**/*.ts\" \"test/**/*.js\"",
+    "prettier": "prettier \"src/**/*.ts\" \"test/**/*.js\" \"*.js\"",
     "prettier:check": "yarn prettier --check",
     "prettier:write": "yarn prettier --write",
     "prepare": "tsc"
@@ -41,10 +46,12 @@
   "devDependencies": {
     "@types/minimatch": "^3.0.5",
     "@types/node": "^12.0.0",
+    "chai": "^4.5.0",
     "electron": "^22.0.0",
-    "electron-mocha": "^11.0.2",
+    "electron-mocha": "^13.0.1",
     "lodash": "^4.17.15",
     "mocha": "^10.1.0",
+    "mocha-chai-jest-snapshot": "^1.1.6",
     "prettier": "^3.3.3",
     "rimraf": "^3.0.2",
     "typescript": "^5.5.4",

src/asar.ts

@@ -26,7 +26,10 @@ function isUnpackedDir(dirPath: string, pattern: string, unpackDirs: string[]) {
     }
     return true;
   } else {
-    return unpackDirs.some((unpackDir) => dirPath.startsWith(unpackDir));
+    return unpackDirs.some(
+      (unpackDir) =>
+        dirPath.startsWith(unpackDir) && !path.relative(unpackDir, dirPath).startsWith('..'),
+    );
   }
 }
 
@@ -37,6 +40,13 @@ export async function createPackage(src: string, dest: string) {
 export type CreateOptions = {
   dot?: boolean;
   globOptions?: IOptions;
+  /**
+   * Path to a file containing the list of relative filepaths relative to `src` and the specific order they should be inserted into the asar.
+   * Formats allowed below:
+   *   filepath
+   *   : filepath
+   *   <anything>:filepath
+   */
   ordering?: string;
   pattern?: string;
   transform?: (filePath: string) => NodeJS.ReadWriteStream | void;
@@ -77,7 +87,8 @@ export async function createPackageFromFiles(
   });
 
   const filesystem = new Filesystem(src);
-  const files: { filename: string; unpack: boolean }[] = [];
+  const files: disk.BasicFilesArray = [];
+  const links: disk.BasicFilesArray = [];
   const unpackDirs: string[] = [];
 
   let filenamesSorted: string[] = [];
@@ -137,37 +148,51 @@ export async function createPackageFromFiles(
     }
     const file = metadata[filename];
 
+    const shouldUnpackPath = function (
+      relativePath: string,
+      unpack: string | undefined,
+      unpackDir: string | undefined,
+    ) {
+      let shouldUnpack = false;
+      if (unpack) {
+        shouldUnpack = minimatch(filename, unpack, { matchBase: true });
+      }
+      if (!shouldUnpack && unpackDir) {
+        shouldUnpack = isUnpackedDir(relativePath, unpackDir, unpackDirs);
+      }
+      return shouldUnpack;
+    };
+
     let shouldUnpack: boolean;
     switch (file.type) {
       case 'directory':
-        if (options.unpackDir) {
-          shouldUnpack = isUnpackedDir(path.relative(src, filename), options.unpackDir, unpackDirs);
-        } else {
-          shouldUnpack = false;
-        }
+        shouldUnpack = shouldUnpackPath(path.relative(src, filename), undefined, options.unpackDir);
         filesystem.insertDirectory(filename, shouldUnpack);
         break;
       case 'file':
-        shouldUnpack = false;
-        if (options.unpack) {
-          shouldUnpack = minimatch(filename, options.unpack, { matchBase: true });
-        }
-        if (!shouldUnpack && options.unpackDir) {
-          const dirName = path.relative(src, path.dirname(filename));
-          shouldUnpack = isUnpackedDir(dirName, options.unpackDir, unpackDirs);
-        }
-        files.push({ filename: filename, unpack: shouldUnpack });
+        shouldUnpack = shouldUnpackPath(
+          path.relative(src, path.dirname(filename)),
+          options.unpack,
+          options.unpackDir,
+        );
+        files.push({ filename, unpack: shouldUnpack });
         return filesystem.insertFile(filename, shouldUnpack, file, options);
       case 'link':
-        filesystem.insertLink(filename);
+        shouldUnpack = shouldUnpackPath(
+          path.relative(src, filename),
+          options.unpack,
+          options.unpackDir,
+        );
+        links.push({ filename, unpack: shouldUnpack });
+        filesystem.insertLink(filename, shouldUnpack);
         break;
     }
     return Promise.resolve();
   };
 
   const insertsDone = async function () {
     await fs.mkdirp(path.dirname(dest));
-    return disk.writeFilesystem(dest, filesystem, files, metadata);
+    return disk.writeFilesystem(dest, filesystem, { files, links }, metadata);
   };
 
   const names = filenamesSorted.slice();

src/crawlfs.ts

@@ -3,6 +3,7 @@ import { glob as _glob } from 'glob';
 
 import fs from './wrapped-fs';
 import { Stats } from 'fs';
+import * as path from 'path';
 import { IOptions } from './types/glob';
 
 const glob = promisify(_glob);
@@ -48,8 +49,13 @@ export async function crawl(dir: string, options: IOptions) {
       // those appearing in archives we need to manually exclude theme here
       const exactLinkIndex = links.findIndex((link) => filename === link);
       return links.every((link, index) => {
-        if (index === exactLinkIndex) return true;
-        return !filename.startsWith(link);
+        if (index === exactLinkIndex) {
+          return true;
+        }
+        const isFileWithinSymlinkDir = filename.startsWith(link);
+        // symlink may point outside the directory: https://github.com/electron/asar/issues/303
+        const relativePath = path.relative(link, path.dirname(filename));
+        return !isFileWithinSymlinkDir || relativePath.startsWith('..');
       });
     });
   return [filenames, metadata] as const;

src/disk.ts

@@ -37,14 +37,17 @@ export type InputMetadata = {
 
 export type BasicFilesArray = { filename: string; unpack: boolean }[];
 
+export type FilesystemFilesAndLinks = { files: BasicFilesArray; links: BasicFilesArray };
+
 const writeFileListToStream = async function (
   dest: string,
   filesystem: Filesystem,
   out: NodeJS.WritableStream,
-  fileList: BasicFilesArray,
+  lists: FilesystemFilesAndLinks,
   metadata: InputMetadata,
 ) {
-  for (const file of fileList) {
+  const { files, links } = lists;
+  for (const file of files) {
     if (file.unpack) {
       // the file should not be packed into archive
       const filename = path.relative(filesystem.getRootPath(), file.filename);
@@ -53,13 +56,30 @@ const writeFileListToStream = async function (
       await streamTransformedFile(file.filename, out, metadata[file.filename].transformed);
     }
   }
+  const unpackedSymlinks = links.filter((f) => f.unpack);
+  for (const file of unpackedSymlinks) {
+    // the symlink needs to be recreated outside in .unpacked
+    const filename = path.relative(filesystem.getRootPath(), file.filename);
+    const link = await fs.readlink(file.filename);
+    // if symlink is within subdirectories, then we need to recreate dir structure
+    await fs.mkdirp(path.join(`${dest}.unpacked`, path.dirname(filename)));
+    // create symlink within unpacked dir
+    await fs.symlink(link, path.join(`${dest}.unpacked`, filename)).catch(async (error) => {
+      if (error.code === 'EPERM' && error.syscall === 'symlink') {
+        throw new Error(
+          'Could not create symlinks for unpacked assets. On Windows, consider activating Developer Mode to allow non-admin users to create symlinks by following the instructions at https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development.',
+        );
+      }
+      throw error;
+    });
+  }
   return out.end();
 };
 
 export async function writeFilesystem(
   dest: string,
   filesystem: Filesystem,
-  fileList: BasicFilesArray,
+  lists: FilesystemFilesAndLinks,
   metadata: InputMetadata,
 ) {
   const headerPickle = Pickle.createEmpty();
@@ -76,7 +96,7 @@ export async function writeFilesystem(
     out.write(sizeBuf);
     return out.write(headerBuf, () => resolve());
   });
-  return writeFileListToStream(dest, filesystem, out, fileList, metadata);
+  return writeFileListToStream(dest, filesystem, out, lists, metadata);
 }
 
 export interface FileRecord extends FilesystemFileEntry {