chore: Distribute cerbos and cerbosctl via npm

Signed-off-by: Andrew Haines <haines@cerbos.dev>

.github/actions/publish-npm-packages/action.yaml

@@ -0,0 +1,19 @@
+name: Publish npm packages
+
+description: Publish npm packages (assuming binaries have already been copied into the correct locations)
+
+runs:
+  using: composite
+
+  steps:
+    - name: Install Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version-file: .node-version
+
+    - name: Publish npm packages
+      shell: bash
+      working-directory: npm
+      run: corepack npm publish --workspaces --access=public --provenance
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

.github/workflows/manual-npm-publish.yaml

@@ -0,0 +1,12 @@
+name: Publish npm packages from an existing GitHub release
+on: workflow_dispatch
+jobs:
+  publish-npm-packages:
+    - name: Check out code
+      uses: actions/checkout@v4
+
+    - name: Download binaries
+      run: hack/scripts/download-released-binaries-to-npm-packages.sh
+
+    - name: Publish npm packages
+      uses: ./.github/actions/publish-npm-packages

.github/workflows/pr-test.yaml

@@ -12,17 +12,22 @@ jobs:
     outputs:
       code: ${{ steps.filter.outputs.code }}
       docs: ${{ steps.filter.outputs.docs }}
+      npm: ${{ steps.filter.outputs.npm }}
       protos: ${{ steps.filter.outputs.protos }}
     steps:
       - uses: dorny/paths-filter@v3
         id: filter
         with:
           filters: |
             code:
-              - '!(docs/**)'
+              - '!(.node-version|{docs,npm}/**)'
             docs:
               - .github/workflows/pr-test.yaml
               - 'docs/**'
+            npm:
+              - .github/workflows/pr-test.yaml
+              - 'npm/**'
+              - .node-version
             protos:
               - .github/workflows/pr-test.yaml
               - '**/*.proto'
@@ -252,3 +257,75 @@ jobs:
 
       - name: Test Helm chart
         run: ./deploy/charts/validate.sh
+
+  build-npm:
+    needs: changes
+    if: ${{ needs.changes.outputs.npm == 'true' }}
+    name: Build npm packages
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Go and cache dependencies
+        uses: ./.github/actions/setup-go
+        with:
+          cross_compiling: true
+
+      - name: Build binaries
+        uses: goreleaser/goreleaser-action@v5
+        with:
+          version: latest
+          args: build --config=.goreleaser.yml --clean --snapshot
+        env:
+          TELEMETRY_WRITE_KEY: ${{ secrets.TELEMETRY_WRITE_KEY }}
+          TELEMETRY_URL: ${{ secrets.TELEMETRY_URL }}
+
+      - name: Collect npm packages
+        run: tar --create --verbose --file npm.tar npm
+
+      - name: Upload npm packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: npm-packages
+          path: npm.tar
+
+  test-npm:
+    needs: build-npm
+    name: Test npm packages
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on:
+          - macos-latest
+          - ubuntu-latest
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 10
+    steps:
+      - name: Check out .node-version file
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: .node-version
+          sparse-checkout-cone-mode: false
+
+      - name: Download npm packages
+        uses: actions/download-artifact@v4
+        with:
+          name: npm-packages
+
+      - name: Extract npm packages
+        run: tar --extract --verbose --file npm.tar
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          cache: npm
+          cache-dependency-path: npm/test/registry/package-lock.json
+          node-version-file: .node-version
+
+      - name: Test npm packages
+        working-directory: npm
+        run: corepack npm test

.github/workflows/release.yaml

@@ -75,6 +75,9 @@ jobs:
           TELEMETRY_WRITE_KEY: ${{ secrets.TELEMETRY_WRITE_KEY }}
           TELEMETRY_URL: ${{ secrets.TELEMETRY_URL }}
 
+      - name: Publish npm packages
+        uses: ./.github/actions/publish-npm-packages
+
   releaseProtos:
     name: Release Protobufs
     runs-on: ubuntu-latest
@@ -149,7 +152,6 @@ jobs:
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
 
-
   publishHelm:
     name: Publish Helm chart
     runs-on: ubuntu-latest

.gitignore

@@ -6,6 +6,18 @@ cerbos.bin
 hack/dev/tls.crt
 hack/dev/tls.key
 internal/confdocs/
+npm/packages/cerbos-*-*/cerbos-*-*
+npm/packages/cerbosctl-*-*/cerbosctl-*-*
+npm/test/cases/*/.npm/
+npm/test/cases/*/.pnpm/
+npm/test/cases/*/.yarn/
+npm/test/cases/*/.pnp.*
+npm/test/cases/*/package-lock.json
+npm/test/cases/*/pnpm-lock.yaml
+npm/test/cases/*/yarn.lock
+npm/test/registry/node_modules/
+npm/test/registry/storage/
+**/node_modules/
 
 # Local Netlify folder
 .netlify

.goreleaser.yml

@@ -26,6 +26,15 @@ builds:
       - -trimpath
     ldflags:
       - -s -w -X github.com/cerbos/cerbos/internal/util.Version={{.Version}} -X github.com/cerbos/cerbos/internal/util.Commit={{.FullCommit}} -X github.com/cerbos/cerbos/internal/util.BuildDate={{.Date}} -X github.com/cerbos/cerbos/internal/telemetry.WriteKey={{.Env.TELEMETRY_WRITE_KEY}} -X github.com/cerbos/cerbos/internal/telemetry.DataPlaneURL={{.Env.TELEMETRY_URL}}
+    hooks:
+      post:
+        - cmd: hack/scripts/copy-binary-to-npm-package.sh
+          env:
+            - BINARY_NAME=cerbos
+            - BINARY_OS={{ .Os }}
+            - BINARY_ARCH={{ .Arch }}
+            - BINARY_VERSION={{ .Version }}
+            - BINARY_PATH={{ .Path }}
 
   - main: ./cmd/cerbosctl
     binary: cerbosctl
@@ -46,13 +55,24 @@ builds:
       - -trimpath
     ldflags:
       - -s -w -X github.com/cerbos/cerbos/internal/util.Version={{.Version}} -X github.com/cerbos/cerbos/internal/util.Commit={{.FullCommit}} -X github.com/cerbos/cerbos/internal/util.BuildDate={{.Date}} -X github.com/cerbos/cerbos/internal/telemetry.WriteKey={{.Env.TELEMETRY_WRITE_KEY}} -X github.com/cerbos/cerbos/internal/telemetry.DataPlaneURL={{.Env.TELEMETRY_URL}}
+    hooks:
+      post:
+        - cmd: hack/scripts/copy-binary-to-npm-package.sh
+          env:
+            - BINARY_NAME=cerbosctl
+            - BINARY_OS={{ .Os }}
+            - BINARY_ARCH={{ .Arch }}
+            - BINARY_VERSION={{ .Version }}
+            - BINARY_PATH={{ .Path }}
+
 universal_binaries:
   - id: "cerbos"
     replace: false
     name_template: "cerbos"
   - id: "cerbosctl"
     replace: false
     name_template: "cerbosctl"
+
 archives:
   - id: cerbos
     builds:
@@ -63,6 +83,7 @@ archives:
     builds:
       - cerbosctl
     name_template: 'cerbosctl_{{ .Version }}_{{ title .Os }}_{{ if eq .Arch "amd64" }}x86_64{{ else }}{{ .Arch }}{{ end }}{{ if .Arm }}v{{ .Arm }}{{ end }}'
+
 nfpms:
   - id: cerbos
     package_name: cerbos

.node-version

@@ -0,0 +1 @@
+20.11.1

Makefile

@@ -40,7 +40,7 @@ lint-helm:
 	@ deploy/charts/validate.sh
 
 .PHONY: generate
-generate: clean generate-proto-code generate-json-schemas generate-testdata-json-schemas generate-mocks confdocs
+generate: clean generate-proto-code generate-json-schemas generate-testdata-json-schemas generate-mocks generate-npm-packages confdocs
 
 .PHONY: generate-proto-code
 generate-proto-code: $(BUF)
@@ -70,6 +70,10 @@ generate-mocks: $(MOCKERY)
 	@ $(MOCKERY) $(MOCK_QUIET) --srcpkg=./internal/storage/bundle --name=CloudAPIClient --output=$(MOCK_DIR)
 	@ $(MOCKERY) $(MOCK_QUIET) --srcpkg=github.com/cerbos/cloud-api/bundle --name=WatchHandle --output=$(MOCK_DIR)
 
+.PHONY: generate-npm-packages
+generate-npm-packages:
+	@ go run ./hack/tools/generate-npm-packages
+
 .PHONY: generate-notice
 generate-notice: $(GO_LICENCE_DETECTOR)
 	@ go mod download
@@ -109,6 +113,10 @@ test-integration: $(GOTESTSUM) $(TESTSPLIT)
 test-times: $(TESTSPLIT)
 	@ $(TESTSPLIT) combine --kinds=unit,integration --total=$(TESTSPLIT_TOTAL)
 
+.PHONY: test-npm-packages
+test-npm-packages:
+	@ cd npm && corepack npm test
+
 .PHONY: coverage
 coverage:
 	@ hack/scripts/cover.sh

docs/modules/ROOT/pages/installation/binary.adoc

@@ -57,3 +57,17 @@ You can install Cerbos binaries using Homebrew as well.
 brew tap cerbos/tap
 brew install cerbos
 ----
+
+[id="npm"]
+== npm
+
+You can install Cerbos binaries from the npm registry. This removes a separate setup step for JavaScript projects and allows you to lock Cerbos to a specific version to ensure a consistent development environment.
+
+link:https://www.npmjs.com/package/cerbos[cerbos] and link:https://www.npmjs.com/package/cerbosctl[cerbosctl] are available as separate packages.
+
+[source,sh]
+----
+npm install --save-dev cerbos cerbosctl
+----
+
+Note that the npm packages rely on platform-specific optional dependencies, so make sure you don't omit these when installing dependencies (for example, don't pass the `--no-optional` flag to `npm`).

docs/modules/cli/pages/cerbosctl.adoc

@@ -3,7 +3,7 @@ include::ROOT:partial$attributes.adoc[]
 = `cerbosctl`
 :page-aliases: ctl.adoc
 
-This utility can be downloaded as a separate container or a tar archive. It is automatically installed when installing Cerbos through xref:ROOT:installation/binary.adoc#linux-packages[Linux packages or the Homebrew tap].
+This utility can be downloaded as a separate container, tar archive, or link:https://www.npmjs.com/package/cerbosctl[npm package]. It is automatically installed when installing Cerbos through xref:ROOT:installation/binary.adoc#linux-packages[Linux packages or the Homebrew tap].
 
 
 .Run from the container

go.work

@@ -3,6 +3,7 @@ go 1.22
 use (
 	.
 	./api/genpb
+	./hack/tools/generate-npm-packages
 	./hack/tools/testsplit
 	./tools
 )

hack/scripts/copy-binary-to-npm-package.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# Copyright 2021-2024 Zenauth Ltd.
+
+set -euo pipefail
+
+project_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../" && pwd)"
+
+if [[ "${BINARY_ARCH}" = "amd64" ]]; then
+  BINARY_ARCH="x64"
+fi
+
+package_name="${BINARY_NAME}-${BINARY_OS}-${BINARY_ARCH}"
+package_dir="${project_dir}/npm/packages/${package_name}"
+
+package_version=$(jq --raw-output .version < "${package_dir}/package.json")
+
+if [[ "${package_version}" != "${BINARY_VERSION}" ]]; then
+  printf "The binary version (%s) does not match the npm package version (%s)\n" "${BINARY_VERSION}" "${package_version}" >&2
+  exit 1
+fi
+
+cp "${BINARY_PATH}" "${package_dir}/${package_name}"

hack/scripts/download-released-binaries-to-npm-packages.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+#
+# Copyright 2021-2024 Zenauth Ltd.
+
+set -euo pipefail
+
+download_artifact() {
+  local filename="$1"
+  curl --fail --silent --show-error --location --output "${filename}" "https://github.com/cerbos/cerbos/releases/download/v${version}/${filename}"
+}
+
+extract_binary() {
+  local archive="$1"
+  local binary="${archive%%_*}"
+
+  local os
+  case "${archive}" in
+    *Darwin*)
+      os=darwin
+      ;;
+
+    *Linux*)
+      os=linux
+      ;;
+  esac
+
+  local arch
+  case "${archive}" in
+    *arm64*)
+      arch=arm64
+      ;;
+
+    *x86_64*)
+      arch=x64
+      ;;
+  esac
+
+  tar --extract --file "${archive}" "${binary}"
+  mv "${binary}" "${project_dir}/npm/packages/${binary}-${os}-${arch}/${binary}-${os}-${arch}"
+}
+
+project_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../" && pwd)"
+
+version=$(jq --raw-output .version < "${project_dir}/npm/packages/cerbos/package.json")
+
+tmp_dir=$(mktemp -d)
+trap "rm -rf ${tmp_dir}" EXIT
+cd "${tmp_dir}"
+
+archives=(
+  "cerbos_${version}_Darwin_arm64.tar.gz"
+  "cerbos_${version}_Darwin_x86_64.tar.gz"
+  "cerbos_${version}_Linux_arm64.tar.gz"
+  "cerbos_${version}_Linux_x86_64.tar.gz"
+  "cerbosctl_${version}_Darwin_arm64.tar.gz"
+  "cerbosctl_${version}_Darwin_x86_64.tar.gz"
+  "cerbosctl_${version}_Linux_arm64.tar.gz"
+  "cerbosctl_${version}_Linux_x86_64.tar.gz"
+)
+
+for archive in "${archives[@]}"; do
+  download_artifact "${archive}"
+done
+
+download_artifact checksums.txt
+sha256sum --check --ignore-missing --quiet checksums.txt
+
+for archive in "${archives[@]}"; do
+  extract_binary "${archive}"
+done