feat(test): add Go fuzz targets and CI workflow (OpenSSF Phase 4)

Closes the OpenSSF Scorecard Fuzzing check by adding native Go fuzz
targets on the two highest-value untrusted-input surfaces in the
project, plus tooling to exercise them locally and in CI.

Fuzz targets:

* internal/repository.FuzzDiskRepositoryGetState
  Fuzzes JSON state-file loading. State files can be persisted to disk
  or S3 and re-loaded later, so they are the primary untrusted-input
  surface in the project. A malformed file must never panic, OOM, or
  hang the reconciliation loop -- only return a typed error.

* internal/model.FuzzGroupsResultUnmarshalBinary
  Fuzzes gob deserialization. The decoder loops `Items` times calling
  dec.Decode, so an attacker who controls the encoded blob can request
  an enormous number of items and force aggressive allocation. The
  fuzzer surfaces panics, hangs, or unbounded allocation here.

Tooling:

* New `make fuzz` target. Go's -fuzz only accepts one target per
  invocation, so the recipe iterates over every Fuzz* function found
  by `go test -list`. FUZZ_TIME (default 60s) is per-target.

* New .github/workflows/fuzz.yml:
  - pull_request -> 60s/target  (won't block merges)
  - schedule weekly Wed 06:00Z -> 10m/target  (actually finds bugs)
  - workflow_dispatch lets a maintainer override the duration

Smoke-tested both targets locally for 5s each: ~92-112k execs/sec, no
crashes, 16-88 new interesting inputs discovered. `make test` still
passes -- fuzz files compile as normal Go tests, the seed corpus runs
as part of the unit-test pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: christiangda

.github/workflows/fuzz.yml

@@ -0,0 +1,41 @@
+name: "Fuzz"
+
+on:
+  pull_request:
+    branches:
+      - main
+  schedule:
+    # Weekly long-running fuzz pass on Wednesdays at 06:00 UTC.
+    - cron: "0 6 * * 3"
+  workflow_dispatch:
+    inputs:
+      fuzz_time:
+        description: "Per-target fuzz duration (e.g. 60s, 5m, 1h)"
+        required: false
+        default: "60s"
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz:
+    name: Run Go fuzz targets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      # PR runs use a short budget so they don't block merges.
+      # The scheduled weekly run gets a longer budget to actually find bugs.
+      # workflow_dispatch lets a maintainer pick any duration.
+      FUZZ_TIME: ${{ inputs.fuzz_time || (github.event_name == 'schedule' && '10m' || '60s') }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Set up Go 1.x
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c  # v6.4.0
+        with:
+          go-version-file: ./go.mod
+
+      - name: make fuzz
+        run: make fuzz

Makefile

@@ -167,6 +167,27 @@ test: $(PROJECT_COVERAGE_FILE) go-mod-tidy go-fmt go-vet go-generate ## Run test
 		./... \
 	)
 
+# Default duration each individual fuzz target runs for. Override on the
+# command line, e.g. `FUZZ_TIME=5m make fuzz`. Go's -fuzz flag only accepts
+# one target per invocation, so the loop below iterates over every Fuzz*
+# function discovered by `go test -list`.
+FUZZ_TIME ?= 60s
+
+.PHONY: fuzz
+fuzz: ## Run every Go fuzz target for $$FUZZ_TIME each (default 60s)
+	@printf "👉 Running fuzz tests (FUZZ_TIME=$(FUZZ_TIME))...\n"
+	@set -e; \
+	any=0; \
+	for pkg in $$(go list ./... | grep -v /mocks/); do \
+	  fuzzes=$$(go test -list '^Fuzz' $$pkg 2>/dev/null | grep -E '^Fuzz' || true); \
+	  for fz in $$fuzzes; do \
+	    any=1; \
+	    printf "  🤞 %s :: %s for %s\n" $$pkg $$fz $(FUZZ_TIME); \
+	    go test -run='^$$' -fuzz="^$$fz$$" -fuzztime=$(FUZZ_TIME) $$pkg; \
+	  done; \
+	done; \
+	if [ $$any -eq 0 ]; then printf "  ⚠️  no fuzz targets found\n"; fi
+
 ###############################################################################
 ##@ Build commands
 .PHONY: build

docs/Whats-New.md

@@ -4,6 +4,25 @@ This document tracks notable changes, new features, and bug fixes across release
 
 ## Unreleased
 
+### OpenSSF Scorecard Hardening (Phase 4) — Fuzzing
+
+Closes the **Fuzzing** Scorecard check by adding native Go fuzz targets and a CI workflow that exercises them.
+
+**Targets added:**
+
+* `internal/repository.FuzzDiskRepositoryGetState` — fuzzes JSON state-file loading, the primary untrusted-input surface in the project (state files can be persisted to disk or S3 and re-read).
+* `internal/model.FuzzGroupsResultUnmarshalBinary` — fuzzes gob deserialization, which loops `Items` times calling `dec.Decode`. An attacker who controls the encoded blob can request an enormous number of items; the fuzzer ensures this fails safely rather than panicking or hanging.
+
+**Tooling:**
+
+* New `make fuzz` target enumerates every `Fuzz*` function via `go test -list` and runs each one for `FUZZ_TIME` (default `60s`, override per-invocation).
+* New `.github/workflows/fuzz.yml`:
+  * Runs every PR with a **60s budget per target** (fast enough to not block merges).
+  * Runs weekly on Wednesdays at 06:00 UTC with a **10-minute budget per target** to actually find bugs.
+  * `workflow_dispatch` lets a maintainer pick any duration on demand.
+
+When a fuzz target finds a crashing input, Go saves it under `testdata/fuzz/<FuzzName>/<hash>`. Commit those files: they become permanent regression tests that run as part of `go test ./...`.
+
 ### OpenSSF Scorecard Hardening (Phase 3) — Signed releases + SLSA provenance
 
 Closes the **Signed-Releases** Scorecard check (0/10 → 10/10) by adopting two complementary supply-chain primitives:

internal/model/group_fuzz_test.go

@@ -0,0 +1,32 @@
+package model
+
+import (
+	"testing"
+)
+
+// FuzzGroupsResultUnmarshalBinary fuzzes the gob deserialization of a
+// GroupsResult. The decoder loops `Items` times calling dec.Decode, so an
+// attacker who controls the encoded blob can ask for an enormous number of
+// items and force the process to allocate aggressively before failing. The
+// fuzzer should surface panics, hangs, or unbounded allocations.
+func FuzzGroupsResultUnmarshalBinary(f *testing.F) {
+	// Seed with a valid round-tripped encoding.
+	seed := GroupsResult{
+		Items: 2,
+		Resources: []*Group{
+			{IPID: "1", Name: "a", Email: "a@example.com"},
+			{IPID: "2", Name: "b", Email: "b@example.com"},
+		},
+	}
+	if data, err := seed.MarshalBinary(); err == nil {
+		f.Add(data)
+	}
+	f.Add([]byte{})
+	f.Add([]byte{0x00})
+	f.Add([]byte{0xff, 0xff, 0xff, 0xff})
+
+	f.Fuzz(func(t *testing.T, data []byte) {
+		var gr GroupsResult
+		_ = gr.UnmarshalBinary(data)
+	})
+}

internal/repository/disk_fuzz_test.go

@@ -0,0 +1,34 @@
+package repository
+
+import (
+	"bytes"
+	"context"
+	"testing"
+)
+
+// FuzzDiskRepositoryGetState fuzzes the state-file loading path.
+//
+// The state file is the primary untrusted-input surface in this project:
+// users can persist it to disk, S3, or another external store and re-load
+// it later. A malformed state file must never crash, panic, or hang the
+// reconciliation loop — at worst it should return a typed error.
+func FuzzDiskRepositoryGetState(f *testing.F) {
+	// Seed with well-formed and adversarial inputs so the fuzzer has
+	// useful starting points to mutate from.
+	f.Add([]byte(`{}`))
+	f.Add([]byte(`{"schemaVersion":"1.0.0","codeVersion":"v0.0.0","hashCode":"abc","resources":{"groups":{},"users":{},"groupsMembers":{}}}`))
+	f.Add([]byte(``))
+	f.Add([]byte(`{"resources":{`))
+	f.Add([]byte(`{"resources":{"groups":{"items":2147483647,"resources":null}}}`))
+	f.Add([]byte("\x00\x01\x02\x03"))
+
+	f.Fuzz(func(t *testing.T, data []byte) {
+		buf := bytes.NewBuffer(data)
+		dr, err := NewDiskRepository(buf)
+		if err != nil {
+			return
+		}
+		// Errors are acceptable; panics, OOMs, and hangs are not.
+		_, _ = dr.GetState(context.Background())
+	})
+}