feat(prf): derive canonical equality terms from Value

.cargo-crap.toml

@@ -53,17 +53,15 @@ exclude = ["tests/**", "src/test_support.rs"]
 #
 #   * The `vitaminc-aead-napi` conversion functions and their JS-boundary
 #     helpers (`own_enumerable_keys`, `get_property_unknown`,
-#     `ensure_plain_object`): each takes a live `napi_env`/`Unknown`/`Object`,
-#     which only exists inside a running V8 isolate. `cargo test` has no Node
-#     host (the `napi/noop` dev-dependency stubs the symbols so the crate
-#     *links*, it does not make the calls work), so these cannot be reached
-#     from a Rust unit test at any coverage level. They are named individually
+#     `ensure_plain_object`, `wrapper_text`, `wrapper_to_js`): each takes a live `napi_env`/`Unknown`/`Object`,
+#     which only exists inside a running V8 isolate. The Node suites run by
+#     `tests/node.rs` do exercise them, but inside a separately built test
+#     addon loaded by `node`, which llvm-cov does not instrument; the
+#     `napi/noop` dev-dependency only lets the crate itself *link* for unit
+#     tests. So llvm-cov always reads them as 0%. They are named individually
 #     rather than by file so the rest of those modules — `forbidden_key`,
-#     `eager_capacity` and friends — stays scored.
-#
-#     NOTE: this is a deferral, not a dismissal. The conversion layer still
-#     needs JS-level tests driving a built addon; see the tracking note in
-#     packages/aead-napi/README.md.
+#     `eager_capacity` and friends — stays scored. The mutation gate does not
+#     exempt them: it rebuilds that addon from the mutated source.
 allow = [
     "**/random-derives/**",
     "**/protected-derive/**",
@@ -72,7 +70,8 @@ allow = [
     "node_to_js",
     "node_from_js",
     "own_enumerable_keys",
-    "define_own_property",
     "get_property_unknown",
     "ensure_plain_object",
+    "wrapper_text",
+    "wrapper_to_js",
 ]

.cargo/mutants.toml

@@ -37,26 +37,15 @@ exclude_globs = [
     "packages/protected/src/locked/proofs.rs",
 ]
 
-# Skip mutants inside the `vitaminc-aead-napi` conversion functions and their
-# JS-boundary helpers (`own_enumerable_keys`, `get_property_unknown`,
-# `ensure_plain_object`). Each takes a live `napi_env`/`Unknown`/`Object`,
-# which only exists inside a running V8 isolate, so no Rust unit test can reach
-# them: every mutant there survives because the function is unreachable from
-# `cargo test`, not because a test is missing. Matched by name (regex against
-# `cargo mutants --list`) rather than by file, so the testable parts of those
-# modules — `forbidden_key`, `eager_capacity` and friends — stay gated.
-#
-# NOTE: a deferral, not a dismissal. This layer needs JS-level tests driving a
-# built addon; see the tracking note in packages/aead-napi/README.md.
 exclude_re = [
-    "js_to_value",
-    "value_to_js",
-    "node_to_js",
-    "node_from_js",
-    "own_enumerable_keys",
-    "define_own_property",
-    "get_property_unknown",
-    "ensure_plain_object",
+    # Equivalent mutants, not missing tests: `widen_f32` (vitaminc-aead-value
+    # canonical.rs) assembles an f64 by OR-ing bit fields that are disjoint by
+    # construction — complementary masks, or fields shifted into separate bit
+    # ranges — and for operands with no common set bit `a | b == a ^ b`, so no
+    # input can tell the two apart. Only that one operator swap in that one
+    # function is skipped; its other mutants (including `mantissa | 1`, where
+    # the operands do overlap) stay gated.
+    "replace \\| with \\^ in widen_f32",
 ]
 
 # Property tests (quickcheck) and AEAD round-trips run slower under mutation than

.github/workflows/crap.yml

@@ -73,6 +73,10 @@ jobs:
           # llvm-tools-preview is required by cargo-llvm-cov to produce coverage.
           components: llvm-tools-preview
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
       - name: Start LocalStack
         # Mirrors the test.yml gate: vitaminc-kms' tests call a KMS endpoint on
         # localhost:4566, so coverage of that crate needs LocalStack running too.

.github/workflows/fuzz.yml

@@ -0,0 +1,109 @@
+name: "Fuzz"
+on:
+  # PR CI runs the fuzz targets over their seed corpora only (go.yml). This
+  # job spends real time mutating inputs, off the PR path so a slow or
+  # unlucky run never blocks a merge.
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+    inputs:
+      fuzztime:
+        description: "Time per fuzz target (Go duration)"
+        default: "5m"
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+permissions:
+  contents: read
+
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    name: "🐹 Go codec fuzzing"
+    strategy:
+      fail-fast: false
+      matrix:
+        # `go test -fuzz` runs one target per invocation. The differential
+        # targets compare vcffi against the Rust decoder in the wasm guest,
+        # so they live with the guest in vcencrypt.
+        include:
+          - { target: FuzzUnmarshal, dir: bindings/go/vcffi }
+          - { target: FuzzUnmarshalCipherText, dir: bindings/go/vcffi }
+          - { target: FuzzDifferentialValue, dir: bindings/go/vcencrypt }
+          - { target: FuzzDifferentialCipherText, dir: bindings/go/vcencrypt }
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # The committed guest binary is rebuilt by hand, so it can lag the
+      # Rust it was built from. A differential run must compare Go against
+      # the Rust on this commit, so rebuild it in place first.
+      - name: setup rust stable
+        if: matrix.dir == 'bindings/go/vcencrypt'
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-wasip1
+
+      - name: rebuild the wasm guest
+        if: matrix.dir == 'bindings/go/vcencrypt'
+        working-directory: bindings/go/vcencrypt/guest
+        run: |
+          cargo build --release --target wasm32-wasip1
+          cp target/wasm32-wasip1/release/vitaminc_wasi_guest.wasm ../wasm/vitaminc_guest.wasm
+
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: bindings/go/vcencrypt/go.mod
+          cache-dependency-path: |
+            bindings/go/vcencrypt/go.sum
+            bindings/go/vcencrypt/examples/go.sum
+
+      - name: fuzz ${{ matrix.target }}
+        working-directory: ${{ matrix.dir }}
+        env:
+          FUZZTIME: ${{ inputs.fuzztime || '5m' }}
+        run: CGO_ENABLED=0 go test -run='^$' -fuzz="^${{ matrix.target }}\$" -fuzztime="$FUZZTIME" .
+
+      - name: upload failing input
+        # A failure writes the minimized input under testdata/fuzz. Commit it
+        # there to keep it as a regression seed for every PR run.
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: fuzz-${{ matrix.target }}
+          path: ${{ matrix.dir }}/testdata/fuzz
+
+  report:
+    # A scheduled run has no PR to turn red, so a failure would otherwise sit
+    # unseen in the Actions tab. Record it on one standing issue instead: it
+    # notifies repository watchers and stays visible until someone closes it.
+    # Manual runs skip this; whoever started one is already watching it.
+    needs: go
+    if: failure() && github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    name: "📣 Report fuzz failure"
+    permissions:
+      issues: write
+    steps:
+      - name: open or update the fuzz failure issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          gh label create fuzz --color B60205 \
+            --description "Failure found by the nightly fuzz workflow" --force
+          body="The nightly fuzz run failed: $RUN_URL
+
+          The failing input is attached to that run as a \`fuzz-<target>\`
+          artifact. Commit it under that target's \`testdata/fuzz\` (in
+          \`bindings/go/vcffi\` or \`bindings/go/vcencrypt\`) so every PR run
+          replays it, fix the bug, then close this issue."
+          issue=$(gh issue list --label fuzz --state open --limit 1 --json number --jq '.[0].number')
+          if [ -n "$issue" ]; then
+            gh issue comment "$issue" --body "$body"
+          else
+            gh issue create --title "Nightly fuzzing found a failure" --label fuzz --body "$body"
+          fi

.github/workflows/go.yml

@@ -38,6 +38,21 @@ jobs:
           out=$(gofmt -l bindings/go) &&
           if [ -n "$out" ]; then echo "gofmt needed:"; echo "$out"; exit 1; fi
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: setup Rust for Node addon
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.96.0
+
+      - name: Node value conformance
+        run: |
+          cargo build --locked --manifest-path packages/aead-napi/tests/addon/Cargo.toml &&
+          cp packages/aead-napi/tests/addon/target/debug/libvitaminc_napi_test_addon.so packages/aead-napi/tests/addon/addon.node &&
+          node packages/aead-napi/tests/value-conformance.cjs packages/aead-napi/tests/addon/addon.node
+
       - name: vet (vcvalue)
         working-directory: bindings/go/vcvalue
         run: go vet ./...

.github/workflows/mutants.yml

@@ -72,6 +72,10 @@ jobs:
       - name: setup rust stable
         uses: dtolnay/rust-toolchain@stable
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
       - name: Start LocalStack
         # The unmutated baseline runs the whole test suite, and vitaminc-kms'
         # tests call a KMS endpoint on localhost:4566 — same as the test.yml and

.github/workflows/test.yml

@@ -43,6 +43,10 @@ jobs:
           components: clippy, rustfmt
           targets: wasm32-unknown-unknown
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
       - name: Start LocalStack
         uses: LocalStack/setup-localstack@v0.3.2
         with:
@@ -96,6 +100,16 @@ jobs:
           cargo test -p vitaminc-aead-value --features rust_decimal &&
           cargo test -p vitaminc-aead-value --all-features
 
+      - name: test (canonical equality features)
+        # The workspace run unifies hmac's dev-dependency features, so test
+        # prf alone without `value` as well as with each optional feature.
+        run: |
+          cargo test -p vitaminc-prf &&
+          cargo test -p vitaminc-prf --features chrono &&
+          cargo test -p vitaminc-prf --features rust_decimal &&
+          cargo test -p vitaminc-prf --all-features &&
+          cargo test -p vitaminc-hmac --test value_equality
+
       - name: test (vitaminc-encrypt, RustCrypto backend on native)
         # Forces the RustCrypto path that wasm32 uses, so the same property
         # tests run against both backends in CI.

bindings/go/vcencrypt/README.md

@@ -216,6 +216,40 @@ cargo run --example gen_fixture   # only if the fixture value/codec changed
 cd .. && CGO_ENABLED=0 go test ./...
 ```
 
+## Differential fuzzing
+
+`differential_fuzz_test.go` feeds the same bytes to Go's decoder (`vcffi`)
+and to the Rust decoder inside this guest, and fails when they disagree.
+Each side's own fuzz targets already prove it round-trips its own input;
+these find inputs where both are self-consistent but differ from each other.
+
+- **`FuzzDifferentialValue`** checks that both sides accept or reject the
+  same value bytes. When both accept, it checks that Rust re-encodes the
+  input exactly and that Go's re-encoding matches, allowing only Go's
+  `undefined` to `null` projection.
+- **`FuzzDifferentialCipherText`** checks that both sides accept or reject
+  the same ciphertext bytes. Fuzzed seals never authenticate, so there is no
+  plaintext to compare.
+
+The guest has no decode-only export, and adding a test-only one would ship it
+in the production module. The targets rely on how the existing exports
+behave instead:
+
+- `vc_encrypt` and `vc_decrypt` decode their input before they look up the
+  cipher handle. Called with a handle that was never issued, they return
+  `ErrEncoding` when Rust rejects the bytes and `ErrBadHandle` when it
+  accepts them, with no AES work. `TestUnissuedHandleReportsDecoding` pins
+  that order.
+- Rust's re-encoding comes from decrypting a ciphertext that is a single
+  passthrough node carrying the input. That path involves no AES and none of
+  the cipher's rules about what may be sealed. Encrypting would not work
+  here: for example, the cipher refuses a container whose children are all
+  passthrough values.
+
+PR CI runs both targets over their seeds against the committed guest. The
+nightly fuzz workflow (`.github/workflows/fuzz.yml`) rebuilds the guest from
+source first, so it always compares Go with the Rust on the same commit.
+
 ## Trade-offs (accepted for the spike)
 
 - On wasm32 `vitaminc-encrypt` uses its pure-Rust RustCrypto backend: no