Oprava chyby bitwarden cli commonjs

Už som napísal aktualizačný príspevok o bitwarden zálohe. Po mesiacoch bezproblémového behu môj automatizovaný GitHub Action na zálohu Bitwardenu zrazu začal zlyhávať. Chybová správa bola záhadná:

Error [ERR_REQUIRE_ESM]: require() of ES Module /Users/peterbabic/backups/bitwarden/node_modules/open/index.js
from /Users/peterbabic/backups/bitwarden/node_modules/@bitwarden/cli/build/bw.js not supported.

Okrem toho som videl varovania o kompatibilite enginu Node.js:

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@koa/[email protected]',
npm warn EBADENGINE   required: { node: '>= 20' },
npm warn EBADENGINE   current: { node: 'v18.20.8', npm: '10.8.2' }
npm warn EBADENGINE }

Pochopenie príčin #

V skutočnosti išlo o dva samostatné problémy:

Problém 1: Kompatibilita CommonJS vs ESM #

Npm balíček @bitwarden/cli závisí od balíčka open. Nedávno bol balíček open aktualizovaný na verziu 10.x, ktorá je len pre ESM. Bitwarden CLI je však postavený na CommonJS a na import používa require(), čo spôsobuje chybu ERR_REQUIRE_ESM.

Balíček open sa stal len ESM od verzie 9.0.0. Poslednou verziou kompatibilnou s CommonJS bola 8.4.2.

Problém 2: Požiadavky na verziu Node.js #

Niekoľko závislostí @bitwarden/cli bolo nedávno aktualizovaných na požadovanú verziu Node.js 20+:

• @koa/[email protected] vyžaduje Node >= 20
• [email protected] vyžaduje Node >= 20

Môj workflow GitHub Actions používal actions/setup-node@v4 bez zadania verzie, čo predvolene nastavilo Node 18.x.

Riešenie 1: Rýchla oprava (npm overrides) #

Prvým riešením bolo použiť funkciu npm overrides na vynútenie staršej, s CommonJS kompatibilnej verzie balíčka open.

Aktualizoval som package.json:

{
  "dependencies": {
    "@bitwarden/cli": "^2025.10.0"
  },
  "overrides": {
    "open": "8.4.2"
  }
}

A zadal Node 20 vo workflowe:

- uses: actions/setup-node@v4
  with:
    node-version: "20"

Po spustení npm install bol override aplikovaný:

└─┬ @bitwarden/[email protected]
  └── [email protected] overridden

Tým sa oba problémy vyriešili a workflow začal opäť fungovať.

Riešenie 2: Lepšia oprava (použitie oficiálneho binárneho súboru) #

Hoci prístup s override fungoval, pôsobil ako hack. Čistejším riešením je použiť oficiálny binárny súbor Bitwarden CLI namiesto jeho inštalácie cez npm. Je to vlastne odporúčaný prístup pre CI/CD prostredia.

Kompletne som prepísal workflow na stiahnutie oficiálneho binárneho súboru:

  steps:
    - uses: actions/checkout@v4
-   - uses: actions/setup-node@v4
-     with:
-       node-version: '20'

-   - run: |
-      npm install
-      ./node_modules/@bitwarden/cli/build/bw.js login --apikey
-      ./node_modules/@bitwarden/cli/build/bw.js export --format json --session $(./node_modules/@bitwarden/cli/build/bw.js unlock --passwordenv BW_PASSWORD --raw) --raw | openssl aes-256-cbc -a -salt -pbkdf2 -k $BW_PASSWORD -out personal.json.enc
-      ./node_modules/@bitwarden/cli/build/bw.js export --format json --session $(./node_modules/@bitwarden/cli/build/bw.js unlock --passwordenv BW_PASSWORD --raw) --raw  --organizationid "$BW_ORGANIZATION_ID" | openssl aes-256-cbc -a -salt -pbkdf2 -k "$BW_PASSWORD" -out organization.json.enc
-      ./node_modules/@bitwarden/cli/build/bw.js lock
-      ./node_modules/@bitwarden/cli/build/bw.js logout
+
+   - name: Install Bitwarden CLI
+     run: |
+       curl -L "https://vault.bitwarden.com/download/?app=cli&platform=linux" -o bw.zip
+       unzip bw.zip
+       chmod +x bw
+       sudo mv bw /usr/local/bin/
+
+   - name: Backup Bitwarden
+     run: |
+      bw login --apikey
+      bw export --format json --session $(bw unlock --passwordenv BW_PASSWORD --raw) --raw | openssl aes-256-cbc -a -salt -pbkdf2 -k $BW_PASSWORD -out personal.json.enc
+      bw export --format json --session $(bw unlock --passwordenv BW_PASSWORD --raw) --raw  --organizationid "$BW_ORGANIZATION_ID" | openssl aes-256-cbc -a -salt -pbkdf2 -k "$BW_PASSWORD" -out organization.json.enc
+      bw lock
+      bw logout

Následne som úplne odstránil súbory súvisiace s npm:

rm package.json package-lock.json

Tu je výsledný kompletný workflow súbor:

name: Bitwarden.com backup

on:
  workflow_dispatch:
  schedule:
    - cron: "30 0 * * 0"

jobs:
  backup:
    runs-on: ubuntu-22.04
    env:
      BW_CLIENTID: ${{ secrets.BW_CLIENTID }}
      BW_CLIENTSECRET: ${{ secrets.BW_CLIENTSECRET }}
      BW_PASSWORD: ${{ secrets.BW_PASSWORD }}
      BW_ORGANIZATION_ID: ${{ secrets.BW_ORGANIZATION_ID }}
    steps:
      - uses: actions/checkout@v4

      - name: Install Bitwarden CLI
        run: |
          curl -L "https://vault.bitwarden.com/download/?app=cli&platform=linux" -o bw.zip
          unzip bw.zip
          chmod +x bw
          sudo mv bw /usr/local/bin/

      - name: Backup Bitwarden
        run: |
          bw login --apikey
          bw export --format json --session $(bw unlock --passwordenv BW_PASSWORD --raw) --raw | openssl aes-256-cbc -a -salt -pbkdf2 -k $BW_PASSWORD -out personal.json.enc
          bw export --format json --session $(bw unlock --passwordenv BW_PASSWORD --raw) --raw  --organizationid "$BW_ORGANIZATION_ID" | openssl aes-256-cbc -a -salt -pbkdf2 -k "$BW_PASSWORD" -out organization.json.enc
          bw lock
          bw logout

      - if: ${{ !env.ACT }}
        uses: stefanzweifel/git-auto-commit-action@v5

Výhody použitia oficiálneho binárneho súboru #

1. Žiadna správa závislostí: Žiadne npm balíčky na správu ani konflikty verzií
2. Žiadne problémy s CommonJS/ESM: Binárny súbor nemá žiadne problémy s tranzitívnymi závislosťami
3. Žiadne obmedzenia verzie Node.js: Node.js vôbec nepotrebujete inštalovať
4. Rýchlejšie CI behy: Stiahnutie a rozbalenie binárneho súboru je rýchlejšie ako npm install
5. Jednoduchšie príkazy: Iba bw namiesto ./node_modules/@bitwarden/cli/build/bw.js
6. Spoľahlivejšie: Oficiálny binárny súbor je odporúčaný prístup od Bitwardenu

Lokálne testovanie s act #

Ak používate act na lokálne testovanie GitHub Actions, môžete workflow otestovať pomocou:

act workflow_dispatch

Poznámka: Na správne lokálne spustenie musí byť poskytnutý súbor .secrets so skutočnými tajomstvami. Uchovávanie tohto súboru lokálne však predstavuje pomerne veľké bezpečnostné riziko, takže je lepšie testovať iba na GitHub, kde je prostredie o niečo bezpečnejšie.

Záver #

Keď závislosti začínajú spôsobovať problémy s kompatibilitou, niekedy je najlepším riešením urobiť krok späť a opýtať sa: “Potrebujem vôbec tieto závislosti?” V tomto prípade prechod z npm balíčka na oficiálny binárny súbor eliminoval všetky problémy a výsledkom bolo čistejšie, ľahšie udržiavateľné riešenie.

Ak používate Bitwarden CLI vo svojich CI/CD pipeline, dôrazne odporúčam použiť oficiálny binárny súbor namiesto npm balíčka, aby ste sa vyhli podobným problémom v budúcnosti. Enjoy!

Odkazy #

• Bitwarden CLI Downloads
• Bitwarden CLI Documentation
• npm overrides documentation