feat(protect-ffi): vendor the package and run its own checks

.changeset/brave-hounds-monitor.md

@@ -0,0 +1,18 @@
+---
+'stash': patch
+---
+
+Correct the Dependabot section of the bundled `stash-supply-chain-security`
+skill. It described two monitored ecosystems (`npm`, `github-actions`); there
+are now three, because the in-tree Rust workspace at `packages/protect-ffi`
+brought a `Cargo.lock` that nothing proposed updates for. The skill now names
+the `cargo` entry, its non-root `directory`, its monthly cadence, and the
+exact-pinned CipherStash crates it ignores.
+
+Two things the section previously got wrong are also fixed. Major bumps do not
+"stay un-grouped — one PR each": every entry ignores
+`version-update:semver-major`, so Dependabot proposes no major bumps at all and
+they are applied by hand. And `ignore` conditions suppress Dependabot *security*
+PRs as well as version updates — the skill now says so, and points at
+`osv-scanner.yml` (which scans every lockfile in the tree, `Cargo.lock`
+included) as the compensating control.

.changeset/config.json

@@ -10,6 +10,15 @@
       "@cipherstash/stack-supabase",
       "@cipherstash/stack-prisma",
       "@cipherstash/wizard"
+    ],
+    [
+      "@cipherstash/protect-ffi",
+      "@cipherstash/protect-ffi-darwin-x64",
+      "@cipherstash/protect-ffi-darwin-arm64",
+      "@cipherstash/protect-ffi-win32-x64-msvc",
+      "@cipherstash/protect-ffi-linux-x64-gnu",
+      "@cipherstash/protect-ffi-linux-arm64-gnu",
+      "@cipherstash/protect-ffi-linux-x64-musl"
     ]
   ],
   "linked": [],

.changeset/protect-ffi-lazy-load.md.deferred

@@ -0,0 +1,7 @@
+---
+'@cipherstash/protect-ffi': minor
+---
+
+The native binding now loads lazily. Importing the package no longer resolves the platform binary: the CJS entry pulls in `./load.cjs` with `import native = require(...)`, which emits a plain `require` and leaves the `@neon-rs/load` proxy untouched, where the previous `import * as native from` compiled to an `__importStar` that enumerated the module and forced resolution at module-evaluation time. `require('@cipherstash/protect-ffi')` therefore succeeds with no binding installed, and the same `MODULE_NOT_FOUND` — identical `code` and `message` — is raised on first use instead of at import.
+
+Adds `assertNativeBindingAvailable()`: a diagnostic entry point that resolves the platform binary and throws the loader's error unwrapped if it is missing, without constructing a client, reading credentials or touching the network. It exists because laziness removed the implicit probe that importing the package used to be, and there is no consumer-side replacement — `lib/load.cjs` is not an exported path (`ERR_PACKAGE_PATH_NOT_EXPORTED`), reading one of this module's own exports never reaches the proxy, and forcing it through a real wrapper means picking one whose argument validation does not reject first.

.changeset/quiet-moons-repair.md

@@ -0,0 +1,5 @@
+---
+'stash': patch
+---
+
+Document the Dependabot major-version policy in `skills/stash-supply-chain-security`: no entry configures a `semver-major-days` cooldown, because every entry ignores `version-update:semver-major` and cooldown applies to version updates only. The supply-chain e2e suite now pins both halves of that relationship.

.github/actions/build-ffi-binding/action.yml

@@ -0,0 +1,229 @@
+name: Build the protect-ffi binding
+description: >-
+  Compile `packages/protect-ffi` into the artifacts its JS consumers load at
+  runtime — `lib/` (tsc), `index.node` (cargo), and optionally `dist/wasm/**`
+  (wasm-pack) — then prove they load.
+
+  WHY THIS EXISTS: until the monorepo absorption, `@cipherstash/protect-ffi`
+  was installed from npm and all three arrived prebuilt inside the tarball. As
+  a workspace package it ships source only, so every job that encrypts,
+  decrypts, or typechecks against it has to build them first — and nothing else
+  in CI does. Without this action the credentialed suites fail with
+  `Cannot find module '.../protect-ffi-linux-x64-gnu/index.node'`, the Deno
+  smoke test with `Module not found ".../dist/wasm/protect_ffi_inline.js"`, and
+  stack's type tests with four unresolved-declaration errors.
+
+  DO NOT USE FROM A PUBLISHING WORKFLOW. It restores the GitHub Actions cache,
+  which `scripts/lint-no-workflow-caching.mjs` forbids anywhere an artifact
+  gets published. Release builds go through the target-explicit matrix instead,
+  which compiles every platform from scratch.
+
+inputs:
+  wasm:
+    description: >-
+      Also build `dist/wasm/**`. Only jobs that exercise
+      `@cipherstash/stack/wasm-inline` need it — the Deno smoke test and the
+      `integration/wasm/**` suites — and it costs a wasm-pack install plus a
+      second cargo build against wasm32, so it is off by default.
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    # `index.node` is a pure function of the Rust inputs, so it caches on a
+    # content hash of them rather than on a lockfile alone — a crates/ edit
+    # must miss. The path is one gitignored file, so unlike the WASM step
+    # below there is nothing tracked for a restore to overwrite, and the key
+    # needs nothing beyond the Rust inputs. Caching the 13MB output, NOT
+    # cargo's `target/`: a release
+    # build of the cipherstash-client graph leaves gigabytes there, which is
+    # slower to save and restore than the compile it saves.
+    #
+    # GitHub scopes a PR's cache writes to its own ref, so the payoff arrives
+    # once this lands on main and PR runs can read main's entry. Until then
+    # each PR pays one cold build and reuses it across re-runs.
+    - name: Restore the compiled binding
+      id: cache-native
+      uses: actions/cache@v4
+      with:
+        path: packages/protect-ffi/index.node
+        # package.json and mise.toml are in the key because they are build
+        # INPUTS, not just metadata: `build:native` is `cargo-build` plus a
+        # `postcargo-build` hook (`neon dist < cargo.log`), both defined in
+        # package.json, and mise.toml pins the toolchain that compiles it.
+        # Edit either and the Rust hash is unchanged, so the cache hit skips
+        # the build step below and the job proceeds on a stale index.node.
+        key: >-
+          ffi-native-${{ runner.os }}-${{ runner.arch }}-${{
+          hashFiles('packages/protect-ffi/crates/**',
+          'packages/protect-ffi/Cargo.toml',
+          'packages/protect-ffi/Cargo.lock',
+          'packages/protect-ffi/package.json',
+          'packages/protect-ffi/mise.toml') }}
+
+    # Always, hit or miss: `lib/` is `tsc` over `src/`, which is seconds, and
+    # it tracks a different input set than the cached binary.
+    - name: Build lib/ (the package `main`, and what tsc consumers resolve)
+      shell: bash
+      run: pnpm --filter @cipherstash/protect-ffi run build
+
+    # `build:native` is `tsc && cargo build --release`, then a `postcargo-build`
+    # hook running `neon dist < cargo.log`. That bare `neon dist` writes
+    # `index.node` at the PACKAGE ROOT, which is what `src/load.cts` registers
+    # as its `debug:` fallback — so the loader finds it without any platform
+    # package being populated. Release packaging needs `neon dist -o` to place
+    # a binary inside `platforms/<p>/`; testing deliberately does not.
+    - name: Build index.node (cargo)
+      if: steps.cache-native.outputs.cache-hit != 'true'
+      shell: bash
+      run: pnpm --filter @cipherstash/protect-ffi run build:native
+
+    # Unlike index.node, this path is NOT purely generated. `dist/wasm` holds
+    # wasm-pack's output alongside three declaration files that are tracked in
+    # git — see packages/protect-ffi/.gitignore for why they have to be. A
+    # restore untars over the checkout, so with a key hashed from the Rust
+    # inputs alone, an entry saved before a `.d.ts` edit silently reverts that
+    # edit: no diff, no log line, and the next `tsc` against wasm-inline
+    # typechecks the old declarations.
+    #
+    # So the `.d.ts` are hashed into the key too. Any edit to one now misses,
+    # and any entry that *does* hit was necessarily saved from a checkout whose
+    # declarations were byte-identical — which makes the overwrite a no-op by
+    # construction rather than by luck. The glob is load-bearing: it covers a
+    # fourth declaration file the day someone tracks one, where three literal
+    # paths would quietly stop covering the set they were written for.
+    #
+    # The alternative — keeping them out of the archive with a `!` exclusion —
+    # does not work, and reads as though it does. `actions/cache` resolves
+    # `path:` with `implicitDescendants: false` and hands the result to
+    # `tar --files-from`; a bare directory therefore resolves to one entry and
+    # tar recurses into it itself, so an exclusion aimed at files underneath
+    # never matches anything. Narrowing to explicit file globs would work, but
+    # trades a no-op overwrite for a worse failure: a file wasm-pack starts
+    # emitting is then silently absent on every cache hit.
+    #
+    # No key prefix bump is needed for the changed hash inputs — and none would
+    # be needed had `path:` changed either, since `getCacheVersion` hashes the
+    # path list into the entry's version.
+    - name: Restore the compiled WASM output
+      if: inputs.wasm == 'true'
+      id: cache-wasm
+      uses: actions/cache@v4
+      with:
+        path: packages/protect-ffi/dist/wasm
+        # The last five are the same build-input argument as on the native key,
+        # and `build:wasm` is the longer pipeline of the two: wasm-pack, then
+        # `tsc -p tsconfig.wasm-errors.json`, then a `postbuild:wasm` hook
+        # running scripts/inline-wasm.mjs — which is what emits the
+        # protect_ffi_inline.js that stack's wasm-inline entry imports. An edit
+        # to the inliner with no Rust change is the likely one here, and it is
+        # exactly the edit a Rust-only hash cannot see.
+        #
+        # src/errors.ts is that tsc step's only input (`files:` in the tsconfig
+        # names it alone), and hashing the EMITTED dist/wasm/*.d.ts does not
+        # stand in for it. Rewriting the body of `isProtectErrorCode` leaves
+        # errors.d.ts byte-identical while changing errors.js — so the key hits,
+        # this step is skipped, and the restored errors.js is the old one.
+        # Nothing tracked forces a miss: errors.js is gitignored. It is not
+        # inert output either — scripts/inline-wasm.mjs re-exports it from both
+        # the ./wasm and ./wasm-inline entries, so the WASM integration suites
+        # would run an implementation the release build does not ship.
+        #
+        # It is the one source file here for the same reason the whole of src/**
+        # is NOT in this key: a wasm miss costs a wasm-pack install and a cargo
+        # wasm32 build of the cipherstash-client graph, and 104 of the 122 files
+        # under src/ are the eql-v3-types declarations, which that tsconfig
+        # never reads. ffi-binding-action.test.mjs walks the tsconfig's imports
+        # and fails if this stops being the complete input set.
+        key: >-
+          ffi-wasm-${{ runner.os }}-${{
+          hashFiles('packages/protect-ffi/crates/**',
+          'packages/protect-ffi/Cargo.toml',
+          'packages/protect-ffi/Cargo.lock',
+          'packages/protect-ffi/dist/wasm/*.d.ts',
+          'packages/protect-ffi/src/errors.ts',
+          'packages/protect-ffi/package.json',
+          'packages/protect-ffi/mise.toml',
+          'packages/protect-ffi/tsconfig.wasm-errors.json',
+          'packages/protect-ffi/scripts/inline-wasm.mjs') }}
+
+    # mise carries the pinned wasm-pack (see packages/protect-ffi/mise.toml)
+    # and, run from that directory, trusts the nested config — a bare `mise`
+    # call elsewhere refuses it with "Config files are not trusted", which
+    # reads as a toolchain problem rather than a trust one.
+    #
+    # `install_args` narrows this to wasm-pack alone. A bare `mise install`
+    # would also build `cargo:cargo-zigbuild` from source, which this job has
+    # no use for — zigbuild is the release matrix's glibc-pinning path.
+    #
+    # The argument is the full backend id, matching mise.toml. The short name
+    # is not in mise's registry: `mise install wasm-pack` exits non-zero with
+    # "not found in mise tool registry" and a did-you-mean list.
+    #
+    # SHA-pinned, per the convention the deposited upstream workflows already
+    # use for third-party actions. mise-action is a trust dependency this repo
+    # did not have before the absorption, and it runs in jobs holding live
+    # CipherStash credentials — a mutable `@v3` lets the code executing there
+    # change with no commit here. Dependabot moves the pin and the comment
+    # together (.github/dependabot.yml covers github-actions).
+    - name: Install wasm-pack
+      if: inputs.wasm == 'true' && steps.cache-wasm.outputs.cache-hit != 'true'
+      uses: jdx/mise-action@5228313ee0372e111a38da051671ca30fc5a96db # v3.6.3
+      with:
+        install: true
+        install_args: aqua:wasm-bindgen/wasm-pack
+        working_directory: packages/protect-ffi
+
+    # `--all-targets` in the Rust lint means all target KINDS, not platforms;
+    # wasm32 has to be installed explicitly before anything can build for it.
+    - name: Add the wasm32 target
+      if: inputs.wasm == 'true' && steps.cache-wasm.outputs.cache-hit != 'true'
+      shell: bash
+      run: rustup target add wasm32-unknown-unknown
+
+    - name: Build dist/wasm (wasm-pack)
+      if: inputs.wasm == 'true' && steps.cache-wasm.outputs.cache-hit != 'true'
+      shell: bash
+      run: pnpm --filter @cipherstash/protect-ffi run build:wasm
+
+    # Always, and the reason this action is not just three `run:` lines inline.
+    # A cache that restores nothing, or a build whose output lands somewhere
+    # unexpected, otherwise surfaces as dozens of unrelated encryption failures
+    # deep in a credentialed suite. Fail here instead, naming the artifact.
+    - name: Verify the binding loads
+      shell: bash
+      working-directory: packages/protect-ffi
+      env:
+        WANT_WASM: ${{ inputs.wasm }}
+      run: |
+        set -euo pipefail
+
+        test -s index.node || {
+          echo "::error::index.node was neither restored from cache nor built"
+          exit 1
+        }
+
+        # Exercises the real loader, including the platform-package-then-debug
+        # fallback in src/load.cts. `require` alone proves nothing since the
+        # laziness change — the binding resolves on first use, not on import.
+        node -e "require('./lib/index.cjs').assertNativeBindingAvailable()"
+        echo "index.node loads"
+
+        if [ "$WANT_WASM" = "true" ]; then
+          for f in dist/wasm/protect_ffi.js \
+                   dist/wasm/protect_ffi_inline.js \
+                   dist/wasm/protect_ffi_bg.wasm ; do
+            test -s "$f" || {
+              echo "::error::$f missing — the WASM build did not produce it"
+              exit 1
+            }
+          done
+          node --input-type=module -e "
+            const m = await import('./dist/wasm/protect_ffi_inline.js')
+            if (typeof m.newClient !== 'function') {
+              throw new Error('wasm-inline resolved but exports no newClient')
+            }
+          "
+          echo "dist/wasm loads"
+        fi