feat: sentinel key verification middleware

[Flo4604]

What does this PR do?

• This adds our first sentinel middleware engine (key verifications) with matchers etc what we need ykyk.

• fixes error page.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Chore (refactoring code, technical debt, workflow improvements)
• Enhancement (small improvements)
• 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 should this be tested?

• make dev

• manually add sentinel config cuz no ui

UPDATE environments
SET sentinel_config = CAST('{"policies":[{"id":"keyauth-policy","name":"API Key Auth","enabled":true,"keyauth":{"keySpaceId":"<KEY_AUTH_ID>"}}]}' AS BINARY)
WHERE id = '<ENV_ID>';

replace env_id with the env u wanna deploy and the key auth id with a created api key auth id! NOT THE API ID.

• deploy

• run make tunnel

• curl -H "Authorization: Bearer <REPLACE>" https://local-api-local.unkey.local/ or w/e your local url is

• it should 401 you

• replace with created key and it should not.
  I used https://github.com/Flo4604/mono-repo-test to test it so feel free to use it with the /protected route it dumps out the principal header.

Checklist

Required

• Filled out the "How to test" section in this PR
• Read Contributing Guide
• Self-reviewed my own code
• Commented on my code in hard-to-understand areas
• Ran pnpm build
• Ran pnpm fmt
• Ran make fmt on /go directory
• Checked for warnings, there are none
• Removed all console.logs
• Merged the latest changes from main onto my branch with git pull origin main
• My changes don't cause any responsiveness issues

Appreciated

• If a UI change was made: Added a screen recording or screenshots to this PR
• Updated the Unkey Docs if changes were necessary

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboard	Ready	Preview, Comment	Feb 19, 2026 3:38pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
engineering	Ignored	Preview	Feb 19, 2026 3:38pm

[coderabbitai]

Caution

Review failed

The head commit changed during the review from 03f8584 to 81ef110.

📝 Walkthrough

Walkthrough

This pull request introduces a sentinel middleware evaluation engine for validating API keys and enforcing rate limits, integrates error page rendering capabilities, configures Redis for the sentinel service, and adds path-skipping support to logging middleware. The changes span infrastructure, new packages, and service integrations.

Changes

Cohort / File(s)	Summary
Sentinel Engine Package svc/sentinel/engine/BUILD.bazel, svc/sentinel/engine/engine.go, svc/sentinel/engine/engine_test.go, svc/sentinel/engine/keyauth.go, svc/sentinel/engine/keyextract.go, svc/sentinel/engine/keyextract_test.go, svc/sentinel/engine/match.go, svc/sentinel/engine/match_test.go, svc/sentinel/engine/integration_test.go	New engine package implementing middleware evaluation with key authentication, request matching, policy dispatch, and comprehensive unit and integration tests. Includes key extraction from multiple request locations, regex-based request matching, and rate limit header management.
Sentinel Engine Integration svc/sentinel/BUILD.bazel, svc/sentinel/config.go, svc/sentinel/run.go, svc/sentinel/routes/services.go, svc/sentinel/routes/register.go, svc/sentinel/routes/proxy/handler.go, svc/sentinel/routes/proxy/BUILD.bazel, svc/sentinel/routes/BUILD.bazel	Wires the sentinel engine into the service: adds RedisConfig struct, initializes middleware engine with key service and rate limiters, passes engine to proxy handler for policy evaluation, and skips logging internal paths.
Error Page Rendering svc/frontline/internal/errorpage/BUILD.bazel, svc/frontline/internal/errorpage/doc.go, svc/frontline/internal/errorpage/interface.go, svc/frontline/internal/errorpage/errorpage.go, svc/frontline/internal/errorpage/error.go.tmpl	New errorpage package providing templated HTML error page rendering with support for status codes, titles, error codes, request IDs, and dark/light theme styling.
Frontline Error Page Integration svc/frontline/BUILD.bazel, svc/frontline/middleware/BUILD.bazel, svc/frontline/routes/BUILD.bazel, svc/frontline/services/proxy/BUILD.bazel, svc/frontline/middleware/observability.go, svc/frontline/routes/services.go, svc/frontline/routes/register.go, svc/frontline/run.go, svc/frontline/services/proxy/interface.go, svc/frontline/services/proxy/service.go, svc/frontline/services/proxy/forward.go	Integrates error page renderer into frontline: observability middleware now renders HTML error pages, proxy service rewrites sentinel 4xx errors as HTML responses when Accept header prefers HTML, and error renderer is wired through services and initialization.
Sentinel Error Handling pkg/codes/unkey_sentinel.go, svc/sentinel/middleware/observability.go, svc/sentinel/middleware/error_handling.go	Adds sentinel auth error codes (MissingCredentials, InvalidKey, InsufficientPermissions, RateLimited), integrates them into observability error page resolution and categorization, and adds early-exit behavior for pre-coded errors in proxy error handling.
Infrastructure & Configuration dev/Tiltfile, dev/k8s/manifests/cilium-policies.yaml, dev/k8s/manifests/sentinel.yaml, svc/krane/internal/sentinel/apply.go	Adds Kubernetes rollout restart on image reload, Redis egress policy for sentinel, UNKEY_REDIS_URL secret in sentinel namespace, and deployment configuration for Redis.
Logging & Performance pkg/zen/middleware_logger.go, svc/api/routes/register.go, svc/frontline/routes/register.go, pkg/counter/redis.go	Adds LoggingOption type and SkipPaths function to exclude internal paths from logging, applies path skipping in register endpoints, and introduces aggressive Redis connection timeouts (1s dial, 500ms read/write).

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant ProxyHandler as Proxy Handler
    participant Engine as Sentinel Engine
    participant KeyAuth as KeyAuth Executor
    participant KeyService as Key Service
    participant ProxyBackend as Backend Instance

    Client->>ProxyHandler: HTTP Request + Authorization
    ProxyHandler->>ProxyHandler: Strip X-Unkey-Principal
    ProxyHandler->>Engine: Evaluate(ctx, session, request, middleware)
    Engine->>Engine: Match request against policies
    Engine->>KeyAuth: Execute KeyAuth policy
    KeyAuth->>KeyAuth: Extract API key from request
    KeyAuth->>KeyService: Validate & verify key
    KeyService-->>KeyAuth: Key validation result + rate limits
    KeyAuth->>KeyAuth: Write rate limit headers
    KeyAuth-->>Engine: Principal (authenticated user info)
    Engine-->>ProxyHandler: Result with Principal
    ProxyHandler->>ProxyHandler: Serialize & set X-Unkey-Principal header
    ProxyHandler->>ProxyBackend: Forward request with headers
    ProxyBackend-->>Client: Response

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 32.10% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'feat: sentinel key verification middleware' clearly and concisely describes the main feature addition: implementing key verification middleware for the sentinel system.
Description check	✅ Passed	The PR description covers the main objective (sentinel middleware engine for key verification), includes testing instructions with SQL examples, and completes the required checklist items, though it lacks a linked issue reference as specified in the template.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/key-sentinel-middleware

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Buf (1.65.0)

svc/sentinel/proto/config/v1/config.proto

Failure: no .proto files were targeted. This can occur if no .proto files are found in your input, --path points to files that do not exist, or --exclude-path excludes all files.

svc/sentinel/proto/policies/v1/keyauth.proto

Failure: no .proto files were targeted. This can occur if no .proto files are found in your input, --path points to files that do not exist, or --exclude-path excludes all files.

svc/sentinel/proto/policies/v1/policy.proto

Failure: no .proto files were targeted. This can occur if no .proto files are found in your input, --path points to files that do not exist, or --exclude-path excludes all files.

🔧 golangci-lint (2.5.0)

Command failed

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Flo4604]

• fix error pages #5083
• feat: sentinel key verification middleware #5079 👈 (View in Graphite)
• main

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

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (4)

svc/frontline/services/proxy/forward.go (1)

229-232: Minor: redundant ContentLength assignment.

Both resp.ContentLength (field) and Content-Length header are set. The reverse proxy uses the field, making the header redundant—though harmless.

♻️ Optional simplification

 	resp.Body = io.NopCloser(bytes.NewReader(htmlBody))
 	resp.ContentLength = int64(len(htmlBody))
 	resp.Header.Set("Content-Type", "text/html; charset=utf-8")
-	resp.Header.Set("Content-Length", fmt.Sprintf("%d", len(htmlBody)))

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@svc/frontline/services/proxy/forward.go` around lines 229 - 232, The code
redundantly sets both resp.ContentLength and the "Content-Length" header on the
proxied response; remove the redundant header-setting to avoid duplication. In
forward.go where you set resp.Body, resp.ContentLength and then
resp.Header.Set("Content-Length", ...), delete the
resp.Header.Set("Content-Length", fmt.Sprintf(...)) call (keep
resp.ContentLength and the Content-Type header) so the reverse proxy relies on
the ContentLength field only.

svc/sentinel/engine/engine_test.go (1)

12-41: Consider grouping ParseMiddleware tests using t.Run.

Per coding guidelines, use t.Run() for scenarios. The ParseMiddleware tests cover related scenarios and could be consolidated:

♻️ Optional refactor with t.Run

-func TestParseMiddleware_Nil(t *testing.T) {
-	t.Parallel()
-	assert.Nil(t, ParseMiddleware(nil))
-}
-
-func TestParseMiddleware_Empty(t *testing.T) {
-	t.Parallel()
-	assert.Nil(t, ParseMiddleware([]byte{}))
-}
-
-func TestParseMiddleware_EmptyJSON(t *testing.T) {
-	t.Parallel()
-	assert.Nil(t, ParseMiddleware([]byte("{}")))
-}
-
-func TestParseMiddleware_InvalidProto(t *testing.T) {
-	t.Parallel()
-	assert.Nil(t, ParseMiddleware([]byte("not a valid protobuf")))
-}
+func TestParseMiddleware(t *testing.T) {
+	t.Parallel()
+	t.Run("nil input", func(t *testing.T) {
+		assert.Nil(t, ParseMiddleware(nil))
+	})
+	t.Run("empty input", func(t *testing.T) {
+		assert.Nil(t, ParseMiddleware([]byte{}))
+	})
+	t.Run("empty JSON", func(t *testing.T) {
+		assert.Nil(t, ParseMiddleware([]byte("{}")))
+	})
+	t.Run("invalid proto", func(t *testing.T) {
+		assert.Nil(t, ParseMiddleware([]byte("not a valid protobuf")))
+	})
+	// ... remaining subtests
+}

As per coding guidelines: "Organize tests using t.Run() for scenarios".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@svc/sentinel/engine/engine_test.go` around lines 12 - 41, Combine the
separate TestParseMiddleware_* functions into a single TestParseMiddleware that
uses t.Run subtests for each scenario (Nil, Empty, EmptyJSON, InvalidProto,
NoPolicies), calling ParseMiddleware in each subtest; keep t.Parallel where
appropriate (call t.Parallel() inside individual subtests) and reuse
sentinelv1.Middleware and protojson.Marshal for the NoPolicies case to produce
the raw input. Ensure each subtest uses assert/require as before and preserves
error handling and nolint comments.

svc/frontline/internal/errorpage/error.go.tmpl (1)

164-166: Consider parameterizing the support email.

The support email support@unkey.com is hardcoded. If this varies by deployment or needs updates, extracting it as a template variable would improve maintainability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@svc/frontline/internal/errorpage/error.go.tmpl` around lines 164 - 166,
Replace the hardcoded support email in the template with a template variable
(e.g. "{{.SupportEmail}}") so the footer uses a parameter instead of
"support@unkey.com"; update the data struct or map used when executing the
template (e.g. the ErrorPageData or the code that renders error.go.tmpl) to
provide SupportEmail and optionally supply a default value ("support@unkey.com")
when none is provided.

svc/sentinel/routes/proxy/handler.go (1)

81-88: Serialize principal before setting header or propagate error if serialization fails.

SerializePrincipal can fail (wraps protojson.Marshal), and when it does, the X-Unkey-Principal header is silently omitted from the request forwarded to the backend service. Either propagate the serialization error to fail fast, or explicitly document that backend services must tolerate a missing principal header.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@svc/sentinel/routes/proxy/handler.go` around lines 81 - 88, The current
handler silently drops the principal header when engine.SerializePrincipal
fails; locate the block that checks result.Principal and calls
engine.SerializePrincipal and change the error path to fail fast: if serErr !=
nil return or propagate an error from the handler (instead of only logger.Error)
so the request is not forwarded without engine.PrincipalHeader; ensure the
handler's signature (or its caller chain) is updated to accept/propagate the
error and keep the existing success path that calls
req.Header.Set(engine.PrincipalHeader, principalJSON).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@svc/sentinel/engine/BUILD.bazel`:
- Around line 27-55: Replace all usages of testify/assert with testify/require
across engine_test.go, integration_test.go, keyextract_test.go, and
match_test.go: update import lines to remove
"github.com/stretchr/testify/assert" and import
"github.com/stretchr/testify/require" instead, then change all assert.X calls to
require.X (adjusting tests where behavior differs because require fails the test
immediately). After updating code, remove the
`@com_github_stretchr_testify//assert` dependency from the BUILD.bazel go_test
deps and ensure `@com_github_stretchr_testify//require` remains referenced.

In `@svc/sentinel/engine/integration_test.go`:
- Around line 286-317: Update the TestKeyAuth_ValidKey test to follow test
guidelines by wrapping the scenario in t.Run (e.g., t.Run("valid key", func(t
*testing.T) { ... })) and replace all assert.* calls in that test with require.*
(for example change assert.Equal to require.Equal). Ensure the same replacement
(assert -> require) is applied consistently across other tests in this file;
keep test setup (newTestHarness, h.seed, newSession, h.engine.Evaluate)
unchanged but move their usage inside the t.Run closure so the subtest uses
require for assertions.

In `@svc/sentinel/engine/keyextract_test.go`:
- Around line 8-9: Replace the testify/assert import with testify/require in
svc/sentinel/engine/keyextract_test.go and update every assert.* call to
require.* for the assertions referenced (occurrences at lines 19, 29, 37, 52,
69, 89, 109, 128, 151, 174) so the tests fail fast; ensure the import block uses
"github.com/stretchr/testify/require" and each assertion call (e.g., assert.Nil,
assert.Equal, assert.NoError, etc.) is renamed to the corresponding
require.Nil/Equal/NoError variant in the test file.

In `@svc/sentinel/engine/match_test.go`:
- Around line 8-10: Remove the "github.com/stretchr/testify/assert" import and
replace every use of assert.* with require.* in this test file so all assertions
become fatal (require) calls; update the import block to include
"github.com/stretchr/testify/require" (remove the assert import), change the 18
occurrences of assert.* to require.* (e.g., assert.Equal -> require.Equal,
assert.NoError -> require.NoError, etc.) across the test functions in
match_test.go, and run the tests to ensure there are no unused import errors.

In `@svc/sentinel/engine/match.go`:
- Around line 60-72: evalMatchExpr currently calls expr.GetExpr() without
guarding for a nil expr which can panic; add a defensive nil check at the top of
evalMatchExpr (similar to the nil-guard used in evalPathMatch) and return false,
nil when expr is nil so the switch below (using expr.GetExpr()) is safe; update
the function handling for expr (and keep the existing switch on expr.GetExpr()
with cases for MatchExpr_Path, MatchExpr_Method, MatchExpr_Header,
MatchExpr_QueryParam) to rely on that early return.

---

Duplicate comments:
In `@svc/sentinel/engine/integration_test.go`:
- Around line 494-519: This test (TestEvaluate_DisabledPoliciesSkipped) is a
duplicate of an existing case — locate the other equivalent test and either
remove this duplicate or merge it as a subtest using t.Run to avoid repetition;
when merging, keep the same assertions that call h.engine.Evaluate(ctx, sess,
req, mw) and the check require.NoError(t, err) followed by assert.Nil(t,
result.Principal) so behavior is preserved. Ensure the unique identifiers
(TestEvaluate_DisabledPoliciesSkipped, h.engine.Evaluate, mw policy with Id
"disabled") are consolidated and do not appear twice in the test suite.
- Around line 352-380: This test is a duplicate; consolidate it with the
existing KeyAuth tests by removing the redundant TestKeyAuth_MissingKey_Reject
or converting it into a subtest via t.Run inside the primary KeyAuth test suite:
move the body (newTestHarness, s := h.seed, building mw with
sentinelv1.Middleware and sentinelv1.Policy_Keyauth, calling h.engine.Evaluate
and the assertions) into a t.Run("MissingKey", func(t *testing.T){ ... }) block
in the existing test, ensure you use the same assertion style (require/assert)
as the parent tests, and delete the duplicate standalone
TestKeyAuth_MissingKey_Reject function to avoid repeated coverage of the same
case.
- Around line 319-350: This test duplicates behavior covered elsewhere; refactor
TestKeyAuth_ValidKey_WithIdentity by either removing the duplicate test or
converting it into a subtest with t.Run and reusing setup helpers
(newTestHarness, seed, seedKeyWithIdentity) so assertions aren't repeated;
ensure you use require for fatal checks (e.g., require.NoError, require.NotNil)
before non-fatal asserts and eliminate redundant assertions on Subject/Claims to
avoid the duplicate coverage flagged in the comment.
- Around line 382-410: This test appears to be a duplicate of an existing case;
remove or consolidate it so there's a single canonical test for the "missing key
with AllowAnonymous" scenario—locate the duplicate by searching for the test
name TestKeyAuth_MissingKey_AllowAnonymous (or an equivalent subtest) and either
delete this redundant function or merge it into the existing t.Run variant; if
merging, ensure you call newTestHarness, newSession, and engine.Evaluate
(h.engine.Evaluate) under a single test body and keep the require.NoError /
assert.Nil assertions intact for the Principal and the
sentinelv1.Middleware/KeyAuth config.
- Around line 465-490: This test (TestKeyAuth_WrongKeySpace) is a
duplicate—remove this standalone test and instead add it as a subtest (t.Run)
under the existing KeyAuth tests or merge its assertions into the existing test
harness flow; locate the TestKeyAuth_WrongKeySpace function and either delete it
or move its body into an existing TestKeyAuth t.Run block, keeping the same
setup (newTestHarness, h.seed, newSession) and assertions (require.Error +
assert.Contains) so behavior remains covered without duplicated cases.
- Around line 438-463: This test is a duplicate as noted by the "t.Run" comment;
remove or consolidate TestKeyAuth_InvalidKey_Disabled so it isn't redundant:
locate the TestKeyAuth_InvalidKey_Disabled function and either delete it or move
its assertions into the existing t.Run subtest that covers the same scenario,
ensuring you reuse h.seed, h.seedDisabledKey, the constructed middleware (Policy
with KeyAuth/KeySpaceId), the request using disabled.RawKey, and the call to
h.engine.Evaluate to preserve behavior and avoid duplicate test cases.
- Around line 412-436: This test is a duplicate per the t.Run pattern note;
remove or consolidate it so we don't have two identical cases. Locate the
TestKeyAuth_InvalidKey_NotFound function in integration_test.go and either
delete it or merge its assertions into the existing t.Run subtest for key-auth
invalid-key cases (keeping the same session/request setup and the middleware
construction using sentinelv1.Middleware and KeyAuth with s.KeySpaceID) so
behavior is covered only once.
- Around line 521-552: This test (TestEvaluate_MatchFiltering) is a duplicate;
remove the standalone duplicate and instead place its logic as a subtest under
the existing TestEvaluate test (using t.Run) or merge it into the original test
body so we don't have two identical cases; locate the block using
TestEvaluate_MatchFiltering, h.seed, newSession, and h.engine.Evaluate and
either delete this duplicate function or move its assertions into the original
TestEvaluate t.Run, preserving the same assertions (require.NoError and
assert.Nil on result.Principal).

---

Nitpick comments:
In `@svc/frontline/internal/errorpage/error.go.tmpl`:
- Around line 164-166: Replace the hardcoded support email in the template with
a template variable (e.g. "{{.SupportEmail}}") so the footer uses a parameter
instead of "support@unkey.com"; update the data struct or map used when
executing the template (e.g. the ErrorPageData or the code that renders
error.go.tmpl) to provide SupportEmail and optionally supply a default value
("support@unkey.com") when none is provided.

In `@svc/frontline/services/proxy/forward.go`:
- Around line 229-232: The code redundantly sets both resp.ContentLength and the
"Content-Length" header on the proxied response; remove the redundant
header-setting to avoid duplication. In forward.go where you set resp.Body,
resp.ContentLength and then resp.Header.Set("Content-Length", ...), delete the
resp.Header.Set("Content-Length", fmt.Sprintf(...)) call (keep
resp.ContentLength and the Content-Type header) so the reverse proxy relies on
the ContentLength field only.

In `@svc/sentinel/engine/engine_test.go`:
- Around line 12-41: Combine the separate TestParseMiddleware_* functions into a
single TestParseMiddleware that uses t.Run subtests for each scenario (Nil,
Empty, EmptyJSON, InvalidProto, NoPolicies), calling ParseMiddleware in each
subtest; keep t.Parallel where appropriate (call t.Parallel() inside individual
subtests) and reuse sentinelv1.Middleware and protojson.Marshal for the
NoPolicies case to produce the raw input. Ensure each subtest uses
assert/require as before and preserves error handling and nolint comments.

In `@svc/sentinel/routes/proxy/handler.go`:
- Around line 81-88: The current handler silently drops the principal header
when engine.SerializePrincipal fails; locate the block that checks
result.Principal and calls engine.SerializePrincipal and change the error path
to fail fast: if serErr != nil return or propagate an error from the handler
(instead of only logger.Error) so the request is not forwarded without
engine.PrincipalHeader; ensure the handler's signature (or its caller chain) is
updated to accept/propagate the error and keep the existing success path that
calls req.Header.Set(engine.PrincipalHeader, principalJSON).