Add macOS (hvf) and aarch64 support

.cargo/config.toml

@@ -0,0 +1,6 @@
+# Hypervisor.framework requires the com.apple.security.hypervisor entitlement,
+# so run macOS host binaries through a wrapper that ad-hoc signs them first.
+# Cargo resolves this path relative to this file, not the working directory,
+# so it also applies to the recipes that cd into src/hyperlight-js.
+[target.'cfg(target_os = "macos")']
+runner = "dev/macos-sign-and-run.sh"

.github/workflows/CreateRelease.yml

@@ -82,6 +82,7 @@ jobs:
   publish-npm-packages:
     needs: [build, benchmarks, set-version]
     uses: ./.github/workflows/npm-publish.yml
+    secrets: inherit
     with:
       version: ${{ needs.set-version.outputs.version }}
       dry_run: ${{ needs.set-version.outputs.dry_run != 'false' }}

.github/workflows/dep_build.yml

@@ -19,35 +19,65 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        build: [windows-2025-debug, linux-kvm-debug, linux-hyperv3-debug, windows-2025-release, linux-kvm-release, linux-hyperv3-release]
+        build: [windows-2025-debug, linux-kvm-debug, linux-kvm-arm64-debug, linux-hyperv3-debug, macos-hvf-debug, windows-2025-release, linux-kvm-release, linux-kvm-arm64-release, linux-hyperv3-release, macos-hvf-release]
         include:
           - build: windows-2025-debug
             os: [self-hosted, Windows, X64, "1ES.Pool=hld-win2025-amd"]
             hypervisor: whp
+            arch: X64
             config: debug
           - build: linux-kvm-debug
             os: [self-hosted, Linux, X64, "1ES.Pool=hld-kvm-amd"]
             hypervisor: kvm
+            arch: X64
+            config: debug
+          - build: linux-kvm-arm64-debug
+            os: [self-hosted, Linux, arm64, kvm]
+            hypervisor: kvm
+            arch: arm64
             config: debug
           - build: linux-hyperv3-debug
             os: [self-hosted, Linux, X64, "1ES.Pool=hld-azlinux3-mshv-amd"]
             hypervisor: hyperv3
+            arch: X64
+            config: debug
+          - build: macos-hvf-debug
+            os: [self-hosted, macos, arm64, hvf]
+            hypervisor: hvf
+            arch: arm64
             config: debug
           - build: windows-2025-release
             os: [self-hosted, Windows, X64, "1ES.Pool=hld-win2025-amd"]
             hypervisor: whp
+            arch: X64
             config: release
           - build: linux-kvm-release
             os: [self-hosted, Linux, X64, "1ES.Pool=hld-kvm-amd"]
             hypervisor: kvm
+            arch: X64
+            config: release
+          - build: linux-kvm-arm64-release
+            os: [self-hosted, Linux, arm64, kvm]
+            hypervisor: kvm
+            arch: arm64
             config: release
           - build: linux-hyperv3-release
             os: [self-hosted, Linux, X64, "1ES.Pool=hld-azlinux3-mshv-amd"]
             hypervisor: hyperv3
+            arch: X64
             config: release
-    runs-on: ${{ fromJson(
-      format('["self-hosted", "{0}", "X64", "1ES.Pool=hld-{1}-amd", "JobId=build-{2}-{3}-{4}-{5}"]',
+          - build: macos-hvf-release
+            os: [self-hosted, macos, arm64, hvf]
+            hypervisor: hvf
+            arch: arm64
+            config: release
+    runs-on: ${{ fromJson(matrix.hypervisor == 'hvf'
+      && '["self-hosted", "macos", "arm64", "hvf"]'
+      || matrix.arch == 'arm64'
+      && '["self-hosted", "Linux", "arm64", "kvm"]'
+      || format('["self-hosted", "{0}", "{1}", "1ES.Pool=hld-{2}-amd", "JobId=build-{3}-{4}-{5}-{6}"]',
         matrix.hypervisor == 'whp' && 'Windows' || 'Linux',
+        matrix.arch,
         matrix.hypervisor == 'whp' && 'win2025' || matrix.hypervisor == 'hyperv3' && 'azlinux3-mshv' || 'kvm',
         matrix.build,
         github.run_id,
@@ -64,13 +94,69 @@ jobs:
           rust-toolchain: "1.90"
           just-version: "1.51"
 
+    # Unlike upstream hyperlight, which builds its guests once per architecture
+    # and ships them to the test jobs as artifacts, hyperlight-js builds the JS
+    # guest runtime from build.rs during every `cargo build`. That makes a
+    # bare-metal ELF toolchain a hard requirement on macOS too.
+    #
+    # macOS's system archiver cannot produce ELF archives. cargo-hyperlight
+    # prefers llvm-ar on macOS for exactly that reason, but silently falls back
+    # to /usr/bin/ar when llvm-ar is missing from PATH, which yields a guest
+    # link with every QuickJS and libc symbol undefined. Prefer a provisioned
+    # llvm-ar when the runner image supplies one; otherwise use the active Rust
+    # toolchain's llvm-tools component, installing it if necessary.
+    - name: Set up LLVM guest toolchain (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        set -euo pipefail
+        if command -v llvm-ar >/dev/null 2>&1; then
+          echo "Using provisioned llvm-ar from PATH"
+          llvm-ar --version
+        else
+          llvm_bin="$(rustc --print sysroot)/lib/rustlib/$(rustc -vV | sed -n 's/^host: //p')/bin"
+          for attempt in 1 2 3; do
+            if [ -x "$llvm_bin/llvm-ar" ]; then
+              break
+            fi
+            echo "Installing llvm-tools (attempt $attempt)"
+            if ! rustup component add llvm-tools; then
+              echo "llvm-tools installation attempt $attempt failed" >&2
+            fi
+            [ -x "$llvm_bin/llvm-ar" ] || sleep $((attempt * 10))
+          done
+          if [ ! -x "$llvm_bin/llvm-ar" ]; then
+            echo "llvm-ar not found on PATH or in $llvm_bin" >&2
+            exit 1
+          fi
+          echo "$llvm_bin" >> "$GITHUB_PATH"
+          "$llvm_bin/llvm-ar" --version
+        fi
+
     - name: install nodejs
       uses: actions/setup-node@v7
       with:
         node-version: '22'
         cache: 'npm'
         cache-dependency-path: 'src/js-host-api/package-lock.json'
 
+    # The cargo runner in .cargo/config.toml only signs binaries cargo itself
+    # launches, so the js-host-api tests -- which run under node via vitest --
+    # still hit HV_DENIED. Sign a private copy rather than the shared tool
+    # cache: these runners are not ephemeral.
+    - name: Sign node for Hypervisor.framework (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        set -euo pipefail
+        signed_bin="$RUNNER_TEMP/node-signed"
+        mkdir -p "$signed_bin"
+        cp "$(command -v node)" "$signed_bin/node"
+        codesign -f -s - --entitlements dev/macos-entitlements.plist "$signed_bin/node"
+        codesign -d --entitlements - "$signed_bin/node"
+        echo "$signed_bin" >> "$GITHUB_PATH"
+        "$signed_bin/node" --version
+
     - name: fmt
       run: just fmt-check
 

.github/workflows/npm-publish.yml

@@ -30,6 +30,9 @@ on:
         required: false
         type: boolean
         default: false
+    secrets:
+      NPM_TOKEN:
+        required: false
 
 permissions:
   contents: read
@@ -41,6 +44,10 @@ concurrency:
 
 env:
   WORKING_DIR: src/js-host-api
+  # Comma-delimited npm package names that have not yet been published and
+  # therefore cannot have a trusted publisher configured. Remove each package
+  # in a follow-up PR after its first release and trusted-publisher setup.
+  FIRST_TIME_PACKAGES: ",@hyperlight-dev/js-host-api-darwin-arm64,"
 
 jobs:
   build:
@@ -57,6 +64,9 @@ jobs:
           - target: x86_64-pc-windows-msvc
             os: [self-hosted, Windows, X64, "1ES.Pool=hld-win2025-amd"]
             build_name: win32-x64-msvc
+          - target: aarch64-apple-darwin
+            os: macos-15
+            build_name: darwin-arm64
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v7
@@ -76,6 +86,40 @@ jobs:
           cache: 'npm'
           cache-dependency-path: 'src/js-host-api/package-lock.json'
 
+      # Building js-host-api runs hyperlight-js's build.rs, which builds the JS
+      # guest runtime for a bare-metal ELF target. macOS's system archiver
+      # cannot produce ELF archives, and cargo-hyperlight silently falls back to
+      # it when llvm-ar is absent from PATH, leaving every QuickJS and libc
+      # symbol undefined at the guest link. Prefer a provisioned llvm-ar and
+      # fall back to the active Rust toolchain's llvm-tools component.
+      - name: Set up LLVM guest toolchain (macOS)
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          set -euo pipefail
+          if command -v llvm-ar >/dev/null 2>&1; then
+            echo "Using provisioned llvm-ar from PATH"
+            llvm-ar --version
+          else
+            llvm_bin="$(rustc --print sysroot)/lib/rustlib/$(rustc -vV | sed -n 's/^host: //p')/bin"
+            for attempt in 1 2 3; do
+              if [ -x "$llvm_bin/llvm-ar" ]; then
+                break
+              fi
+              echo "Installing llvm-tools (attempt $attempt)"
+              if ! rustup component add llvm-tools; then
+                echo "llvm-tools installation attempt $attempt failed" >&2
+              fi
+              [ -x "$llvm_bin/llvm-ar" ] || sleep $((attempt * 10))
+            done
+            if [ ! -x "$llvm_bin/llvm-ar" ]; then
+              echo "llvm-ar not found on PATH or in $llvm_bin" >&2
+              exit 1
+            fi
+            echo "$llvm_bin" >> "$GITHUB_PATH"
+            "$llvm_bin/llvm-ar" --version
+          fi
+
       - name: Install dependencies
         working-directory: ${{ env.WORKING_DIR }}
         run: npm ci --ignore-scripts --omit=optional
@@ -173,6 +217,12 @@ jobs:
           name: bindings-win32-x64-msvc
           path: ${{ env.WORKING_DIR }}/artifacts/win32-x64-msvc
 
+      - name: Download macOS arm64 artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: bindings-darwin-arm64
+          path: ${{ env.WORKING_DIR }}/artifacts/darwin-arm64
+
       - name: Download JS bindings
         uses: actions/download-artifact@v8
         with:
@@ -189,9 +239,11 @@ jobs:
           mv artifacts/linux-x64-gnu/*.node npm/linux-x64-gnu/js-host-api.linux-x64-gnu.node
           mv artifacts/linux-x64-musl/*.node npm/linux-x64-musl/js-host-api.linux-x64-musl.node
           mv artifacts/win32-x64-msvc/*.node npm/win32-x64-msvc/js-host-api.win32-x64-msvc.node
+          mv artifacts/darwin-arm64/*.node npm/darwin-arm64/js-host-api.darwin-arm64.node
           ls -la npm/linux-x64-gnu/
           ls -la npm/linux-x64-musl/
           ls -la npm/win32-x64-msvc/
+          ls -la npm/darwin-arm64/
 
       - name: Set package versions
         working-directory: ${{ env.WORKING_DIR }}
@@ -203,6 +255,7 @@ jobs:
           cd npm/linux-x64-gnu && npm version "$VERSION" --no-git-tag-version --allow-same-version
           cd ../linux-x64-musl && npm version "$VERSION" --no-git-tag-version --allow-same-version
           cd ../win32-x64-msvc && npm version "$VERSION" --no-git-tag-version --allow-same-version
+          cd ../darwin-arm64 && npm version "$VERSION" --no-git-tag-version --allow-same-version
         env:
           VERSION: ${{ inputs.version }}
 
@@ -237,68 +290,58 @@ jobs:
       - name: Validate packages
         working-directory: ${{ env.WORKING_DIR }}
         run: ./test-pack.sh
+        env:
+          REQUIRE_MACOS_PACKAGE: "1"
 
       # ── Authentication strategy ────────────────────────────────────
-      # Production releases via CreateRelease.yml use trusted publishing
-      # (OIDC) — npm auto-detects the id-token and exchanges it for a
-      # short-lived publish credential. Provenance attestations are
-      # generated automatically. The --provenance flag is added explicitly
-      # so the build fails loudly if OIDC is misconfigured.
-      #
-      # Manual workflow_dispatch requires an NPM_TOKEN repo secret because
-      # trusted publishing is configured for CreateRelease.yml only.
-      # Provenance is NOT available for token-based publishing.
-      # You should almost never need to publish manually — if you do,
-      # see docs/release.md for the full (deliberately painful) steps.
-      - name: Validate NPM_TOKEN for manual dispatch
-        if: ${{ github.event_name == 'workflow_dispatch' && !inputs.dry_run }}
+      # Established packages use trusted publishing (OIDC). Packages listed
+      # in FIRST_TIME_PACKAGES use NPM_TOKEN for this release only because
+      # npm has no trusted-publisher configuration until the package exists.
+      - name: Validate NPM_TOKEN for token-published packages
+        if: ${{ !inputs.dry_run && (github.event_name == 'workflow_dispatch' || env.FIRST_TIME_PACKAGES != '') }}
         run: |
           if [ -z "$NPM_TOKEN" ]; then
-            echo "::error::NPM_TOKEN repo secret is required for manual workflow_dispatch publishing."
-            echo "::error::See docs/release.md 'Manual npm publishing (emergency only)' for instructions."
+            echo "::error::NPM_TOKEN repo secret is required for manual publishing or first-time packages."
+            echo "::error::See docs/release.md for the first-time package bootstrap procedure."
             exit 1
           fi
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # Set provenance flag once — OIDC path gets --provenance (fails loud
-      # if misconfigured), token path skips it (not supported).
-      - name: Set publish flags
-        id: publish-flags
-        run: |
-          if [ "${{ github.event_name }}" != "workflow_dispatch" ]; then
-            echo "provenance=--provenance" >> "$GITHUB_OUTPUT"
-          else
-            echo "provenance=" >> "$GITHUB_OUTPUT"
-          fi
-
       - name: Publish Linux GNU package
         if: ${{ !inputs.dry_run }}
         working-directory: ${{ env.WORKING_DIR }}/npm/linux-x64-gnu
-        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
+        run: npm publish --access public --ignore-scripts --provenance
         env:
-          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
+          NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-linux-x64-gnu,')) && secrets.NPM_TOKEN || '' }}
 
       - name: Publish Linux musl package
         if: ${{ !inputs.dry_run }}
         working-directory: ${{ env.WORKING_DIR }}/npm/linux-x64-musl
-        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
+        run: npm publish --access public --ignore-scripts --provenance
         env:
-          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
+          NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-linux-x64-musl,')) && secrets.NPM_TOKEN || '' }}
 
       - name: Publish Windows package
         if: ${{ !inputs.dry_run }}
         working-directory: ${{ env.WORKING_DIR }}/npm/win32-x64-msvc
-        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
+        run: npm publish --access public --ignore-scripts --provenance
         env:
-          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
+          NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-win32-x64-msvc,')) && secrets.NPM_TOKEN || '' }}
+
+      - name: Publish macOS arm64 package
+        if: ${{ !inputs.dry_run }}
+        working-directory: ${{ env.WORKING_DIR }}/npm/darwin-arm64
+        run: npm publish --access public --ignore-scripts --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-darwin-arm64,')) && secrets.NPM_TOKEN || '' }}
 
       - name: Publish main package
         if: ${{ !inputs.dry_run }}
         working-directory: ${{ env.WORKING_DIR }}
-        run: npm publish --access public --ignore-scripts ${{ steps.publish-flags.outputs.provenance }}
+        run: npm publish --access public --ignore-scripts --provenance
         env:
-          NODE_AUTH_TOKEN: ${{ github.event_name == 'workflow_dispatch' && secrets.NPM_TOKEN || '' }}
+          NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api,')) && secrets.NPM_TOKEN || '' }}
 
       - name: Verify all packages published
         if: ${{ !inputs.dry_run }}
@@ -309,7 +352,8 @@ jobs:
           for pkg in "@hyperlight-dev/js-host-api" \
                      "@hyperlight-dev/js-host-api-linux-x64-gnu" \
                      "@hyperlight-dev/js-host-api-linux-x64-musl" \
-                     "@hyperlight-dev/js-host-api-win32-x64-msvc"; do
+                     "@hyperlight-dev/js-host-api-win32-x64-msvc" \
+                     "@hyperlight-dev/js-host-api-darwin-arm64"; do
             if npm view "$pkg@$VERSION" version > /dev/null 2>&1; then
               echo "✅ $pkg@$VERSION published"
             else
@@ -339,5 +383,8 @@ jobs:
           echo "--- @hyperlight-dev/js-host-api-win32-x64-msvc ---"
           npm pack ./npm/win32-x64-msvc --dry-run
           echo ""
+          echo "--- @hyperlight-dev/js-host-api-darwin-arm64 ---"
+          npm pack ./npm/darwin-arm64 --dry-run
+          echo ""
           echo "--- @hyperlight-dev/js-host-api ---"
           npm pack --dry-run