fix: document FIPS v5 reseed suppression and genkey privilege requirement

[MarkAtwood]

Summary

Two comment/documentation fixes:

Fix 1: FIPS v5 reseed suppression (kernel-src/wolfcrypt_glue.c)

In wc_linuxkm_drbg_generate(), the #if defined(HAVE_FIPS) && FIPS_VERSION_LT(6,0) block silently discards the src/slen entropy input with bare (void) suppressors. This is correct behavior — FIPS v5 does not expose an external reseed API — but it was unexplained, making the code appear to be a stub or oversight.

Added a concise comment explaining:

• FIPS v5 does not expose an API to externally reseed the DRBG
• The entropy input is therefore discarded
• The DRBG output remains safe because it was properly seeded at initialization

Fix 2: wg genkey requires CAP_NET_ADMIN when kernel module is loaded

When wolfguard.ko is loaded, wg genkey / wg-fips genkey offloads key generation to the kernel module via Generic Netlink (WG_CMD_GEN_PRIVKEY). That operation is gated by GENL_UNS_ADMIN_PERM, which requires CAP_NET_ADMIN. This surprised users who expected genkey to be an unprivileged operation (as it is in upstream WireGuard).

Part A (kernel-src/netlink.c): Added a comment on the WG_CMD_GEN_PRIVKEY ops entry explaining the privilege requirement and the available remedies (sudo/root, NO_IPC_LLCRYPTO=1 build, or setcap cap_net_admin+ep).

Part B (README.md): Added a note in both the non-FIPS and FIPS build/install procedures, immediately after the wg-fips genkey | wg-fips pubkey smoke-test lines, explaining the CAP_NET_ADMIN requirement and the three remedies.

No code changes

This PR is comments and documentation only. No logic, no API, no behavior was changed.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Documents two previously non-obvious behaviors: (1) why external entropy is ignored for DRBG generation under FIPS v5, and (2) why wg genkey requires CAP_NET_ADMIN when keygen is offloaded to the kernel module via Generic Netlink.

Changes:

• Add an explanatory comment for FIPS v5 DRBG “reseed suppression” behavior in wc_linuxkm_drbg_generate().
• Document CAP_NET_ADMIN requirement for kernel-offloaded genkey in both netlink ops and build/install README instructions.
• Add Beads/Dolt + Claude/agent integration files and broaden .gitignore patterns.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
kernel-src/wolfcrypt_glue.c	Adds comment explaining why src/slen are discarded under FIPS v5.
kernel-src/netlink.c	Adds comment documenting CAP_NET_ADMIN requirement for kernel keygen op.
README.md	Adds user-facing note about CAP_NET_ADMIN requirement and workarounds.
CLAUDE.md	Adds AI agent workflow guidance (Beads integration).
AGENTS.md	Adds agent instructions and duplicates Beads integration guidance.
.gitignore	Adds ignores for Dolt/Beads artifacts (notably *.db).
.claude/settings.json	Adds Claude hooks to run bd prime automatically.
.beads/metadata.json	Adds Beads project metadata for Dolt backend.
.beads/config.yaml	Adds Beads configuration template.
.beads/README.md	Adds Beads documentation for repo-local issue tracking.
.beads/.gitignore	Adds Beads internal ignore rules.
.beads/hooks/prepare-commit-msg	Adds Beads-managed git hook wrapper.
.beads/hooks/pre-push	Adds Beads-managed git hook wrapper.
.beads/hooks/pre-commit	Adds Beads-managed git hook wrapper.
.beads/hooks/post-merge	Adds Beads-managed git hook wrapper.
.beads/hooks/post-checkout	Adds Beads-managed git hook wrapper.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PR description states this is limited to two comment/documentation fixes and “No code changes”, but this PR also adds Beads/Dolt integration files (including git hooks), Claude settings, and agent instruction docs. Please either (a) split the Beads/Claude/agent scaffolding into a separate PR, or (b) update the PR title/description to accurately reflect these additional changes, since they materially affect repo tooling and contributor workflows.

[Copilot]

This note states both wg genkey and wg-fips genkey are affected, but the remedies are wg-fips-specific (build wg-fips..., setcap ... wg-fips). To avoid confusing non-FIPS users, consider either (1) making the text consistently apply to both binaries (and show both setcap examples), or (2) clearly stating which binary names are present/expected in each install path. Also, setcap typically requires sudo; documenting that helps users avoid a second “permission denied” surprise.

Suggested change

	**Note:** When the `wolfguard.ko` kernel module is loaded, `wg genkey` (and
	`wg-fips genkey`) offloads key generation to the kernel module via netlink and
	therefore requires `CAP_NET_ADMIN`. Non-root users will receive a permission
	error. To resolve this, either run as root or via `sudo`, or build `wg-fips`
	with `NO_IPC_LLCRYPTO=1` (which selects the userspace key generation path), or
	grant the `wg-fips` binary the `cap_net_admin` file capability
	(`setcap cap_net_admin+ep wg-fips`).
	**Note:** When the `wolfguard.ko` kernel module is loaded, `wg genkey` and
	`wg-fips genkey` offload key generation to the kernel module via netlink and
	therefore require `CAP_NET_ADMIN`. Non-root users will receive a permission
	error. To resolve this, either run as root or via `sudo`, build the binary
	you are using with `NO_IPC_LLCRYPTO=1` (which selects the userspace key
	generation path), or grant that binary the `cap_net_admin` file capability,
	for example `sudo setcap cap_net_admin+ep wg-fips` or, if your install exposes
	the tool as `wg`, `sudo setcap cap_net_admin+ep wg`.

[Copilot]

The comment is attached to a kernel netlink op (WG_CMD_GEN_PRIVKEY) and says “ensure the wg-fips binary has…” even though the same op may be invoked by wg as well (as described in the README note). Consider rewording to refer generically to the userspace client binary (e.g., “wg/wg-fips”) so the kernel-side comment stays accurate regardless of which frontend is used.

Suggested change

	* generation path, or ensure the wg-fips binary has the
	* appropriate file capabilities set (e.g. cap_net_admin+ep).
	* generation path, or ensure the userspace client binary
	* (e.g. wg/wg-fips) has the appropriate file capabilities
	* set (e.g. cap_net_admin+ep).

[Copilot]

These hooks run bd prime unconditionally on Claude lifecycle events. If bd isn’t installed/configured for a contributor, this may cause persistent tool errors or delays. If you want to keep this, consider adding a guard/soft-fail approach (where supported by the Claude hooks configuration) or documenting the required tooling expectation in the main README so the dependency is explicit.

[Copilot]

The Beads integration block appears to be duplicated across CLAUDE.md and AGENTS.md. Duplicated process docs tend to drift over time; consider consolidating the canonical workflow into a single file and having the other file link to it (or include it via tooling) to reduce future maintenance burden.

Suggested change

	This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
	### Quick Reference
	```bash
	bd ready # Find available work
	bd show <id> # View issue details
	bd update <id> --claim # Claim work
	bd close <id> # Complete work
	```
	### Rules
	- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
	- Run `bd prime` for detailed command reference and session close protocol
	- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
	## Session Completion
	**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
	**MANDATORY WORKFLOW:**
	1. **File issues for remaining work** - Create issues for anything that needs follow-up
	2. **Run quality gates** (if code changed) - Tests, linters, builds
	3. **Update issue status** - Close finished work, update in-progress items
	4. **PUSH TO REMOTE** - This is MANDATORY:
	```bash
	git pull --rebase
	bd dolt push
	git push
	git status # MUST show "up to date with origin"
	```
	5. **Clean up** - Clear stashes, prune remote branches
	6. **Verify** - All changes committed AND pushed
	7. **Hand off** - Provide context for next session
	**CRITICAL RULES:**
	- Work is NOT complete until `git push` succeeds
	- NEVER stop before pushing - that leaves work stranded locally
	- NEVER say "ready to push when you are" - YOU must push
	- If push fails, resolve and retry until it succeeds
	The canonical Beads workflow, rules, and session completion checklist live in `CLAUDE.md`.
	Refer to that file for the full process, and run `bd prime` for current command and workflow guidance.