chore(rivetkit): impl inspector token

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(rivetkit-core): gate startup until runtime is ready #4736 : 2 dependent PRs (#4737 , #4739 )
• fix(rivetkit-sqlite): preserve text with embedded nul bytes #4735
• chore(rivetkit): add child spans for logging #4734
• fix(rivetkit-core): orphan engine process and detect crashes #4733
• fix(rivetkit-core): return None for empty inspector state to avoid frontend CBOR decode error #4732
• fix(rivetkit-core): don't install tokio::signal::ctrl_c() handler inside serve_with_config #4731
• refactor(rivetkit-core): use subtle::ConstantTimeEq for inspector token verify #4730
• fix(rivetkit): drop is_read_only_sql classifier, surface RETURNING rows #4728
• docs: require close-code rejection for websocket auth/policy failures #4727
• fix(rivetkit): inspector reports actual config state + real queue messages #4726
• fix(rivetkit-napi): plumb ctx through serializeState TSF and stop panicking on runtime_state Ref drop #4725
• chore(rivetkit): remove legacy metrics & prometheus auth #4724
• chore(rivetkit): remove legacy metrics #4723
• chore(rivetkit): impl inspector token #4722 👈 (View in Graphite)
• chore: disable auth on serverless #4721
• chore: fix cors for envoys #4720
• chore: fix serverless in rivetkit-core #4719
• chore(rivetkit): impl follow up review #4711
• chore: rivetkit core/napi/typescript follow up review #4702
• chore: fix remaining issues with rivetkit-core #4701
• chore: sqlite v1 to v2 data migration #4692 : 1 other dependent PR (#4640 )
• chore: move rivetkit to task model #4680
• chore: rivetkit to rust #4679
• feat(rivetkit): sqlite vfs v2 #4673
• chore: rename sandbox -> kitchen sink #4671 : 1 other dependent PR (#4672 )
• chore: configure TLS trust roots for rustls clients #4667
• fix(rivetkit): update config to match envoys & remove manager references #4663
• chore(publish): pin docker base image refs #4652
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR #4722 Review: chore(rivetkit): impl inspector token

Summary: This PR implements inspector token initialization for the Rust rivetkit-core actor startup path. It generates a cryptographically random 32-byte URL-safe base64 token, persists it to KV key [3] (matching the TypeScript KEYS.INSPECTOR_TOKEN layout), and skips generation when the RIVET_INSPECTOR_TOKEN env var override is already set.

---

Critical Bug: Tests No Longer Cover the Real Code Path

The test changes in tests/modules/inspector.rs swap RIVET_INSPECTOR_TOKEN for _RIVET_TEST_INSPECTOR_TOKEN in the env lock/set/remove calls, but InspectorAuth::verify and init_inspector_token in auth.rs still read RIVET_INSPECTOR_TOKEN (the INSPECTOR_TOKEN_ENV constant). After this change, the three auth tests that set _RIVET_TEST_INSPECTOR_TOKEN can never influence code that reads RIVET_INSPECTOR_TOKEN, so the env-token priority branch and the env-token guard in init_inspector_token are effectively untested.

The intent appears to be isolating tests from the real env var, but the constant used in the source code was not updated to match. Either the tests should keep using RIVET_INSPECTOR_TOKEN (and accept that running in an environment with that var set could affect results), or the source constant should be updated to _RIVET_TEST_INSPECTOR_TOKEN with a #[cfg(test)] alias. The current state breaks the test invariant silently.

Recommendation: Revert the env var name change in the tests so they match INSPECTOR_TOKEN_ENV = RIVET_INSPECTOR_TOKEN, or add a #[cfg(test)] override constant in auth.rs and update both the constant and tests together.

---

Security: rand::thread_rng() Should Be OsRng for Security-Sensitive Tokens

rand::thread_rng() is seeded from the OS but may buffer entropy and has historically had subtle seeding issues across fork boundaries. For a security-sensitive secret like an inspector auth token, the preferred choice is rand::rngs::OsRng directly, which reads from the OS CSPRNG on every call with no internal state:

use rand::RngCore;
use rand::rngs::OsRng;

fn generate_inspector_token() -> String {
    let mut bytes = [0u8; INSPECTOR_TOKEN_BYTES];
    OsRng.fill_bytes(&mut bytes);
    URL_SAFE_NO_PAD.encode(bytes)
}

The codebase already uses getrandom directly in rivetkit-sqlite for security-sensitive RNG, which is consistent precedent.

---

Performance: Token Init Not Batched With Startup Preload

The new call is placed between persist_state and restore_hibernatable_connections_with_preload in start_actor. This runs on every actor wake, meaning the KV read in init_inspector_token is an extra round-trip on every wake. The TypeScript implementation avoids this by batching the inspector token KV get into the preload map and the write into a WriteCollector flushed in a single batch. The Rust path currently does two individual KV operations (get + conditional put) on every actor wake with no batching. Not a correctness issue, but worth tracking as a follow-up.

---

Minor Issues

• Comment typo (registry/inspector.rs): // TODO: Impelment when ready - Impelment should be Implement. Per CLAUDE.md style, comments should be complete sentences: // TODO: Implement traces endpoint when ready.
• Visibility: init_inspector_token is exported as pub from crate::inspector. Since it is only called from actor::task, consider pub(crate) to limit surface area.
• Missing startup perf log: The TypeScript implementation wraps initializeInspectorToken in startup timing. The Rust path adds no corresponding tracing span. Consider adding a tracing::debug! span consistent with other startup phases.

---

Summary

Severity	Issue
Critical	Test env var renamed to _RIVET_TEST_INSPECTOR_TOKEN but source still reads RIVET_INSPECTOR_TOKEN - auth tests no longer cover the env-token code path
Security	Use OsRng instead of thread_rng() for the inspector token
Performance	KV get+put not batched with startup preload; extra round-trip on every actor wake
Minor	Typo in TODO comment: Impelment
Minor	init_inspector_token could be pub(crate)
Minor	Missing startup perf log for new init phase

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4722

All packages published as 0.0.0-pr.4722.75d4644 with tag pr-4722.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-75d4644
docker pull rivetdev/engine:full-75d4644

Individual packages

npm install rivetkit@pr-4722
npm install @rivetkit/react@pr-4722
npm install @rivetkit/rivetkit-napi@pr-4722
npm install @rivetkit/workflow-engine@pr-4722

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.