Checkpoint.AspNet 0.4.0

• .NETFramework 4.6.2

  • Checkpoint.Core (>= 0.4.0)

0.4.0 — Normalize HTTP headers to KYA- convention

All custom response headers renamed from X-Checkpoint-* to KYA-*
per RFC 6648 (deprecated X- prefix) and the KYA-OS rebrand:

 X-Checkpoint-Detected    → KYA-Detected
 X-Checkpoint-Confidence  → KYA-Confidence
 X-Checkpoint-Class       → KYA-Class
 X-Checkpoint-Agent       → KYA-Agent
 X-Checkpoint-Verification→ KYA-Verification
 X-Checkpoint-Session     → KYA-Session

MCP-I instruct response headers also renamed:
 X-MCP-I-Required   → KYA-Auth-Required
 X-MCP-I-Authorize  → KYA-Auth-Url
 X-MCP-I-Project    → KYA-Project
 X-AgentShield-Action→ KYA-Action
 rel="mcp-i-authorize" → rel="kya-authorize"

This is a BREAKING CHANGE for any consumer reading these headers
by name. No functional behavior changes.

0.3.3 — Remove legacy bouncer/sessions fallback + log log-detection failures

The 0.3.2 and earlier releases fell back from POST /api/v1/log-detection to
POST /api/v1/bouncer/sessions whenever the log-detection call returned
non-2xx. That fallback was semantically wrong: bouncer/sessions is the
MCP-I session registration endpoint and requires a real agent DID. The
fallback fabricated a synthetic "did:web:detected:{AgentType ?? unknown}"
DID per detection, which inserted junk rows into bouncer_sessions for
every crawler hit (Googlebot, aranhabot, Applebot, etc.) and emitted a
"[McpiConfigService] agentDid mismatch" warning on every row because the
synthetic DID collided with the project's real configured agentDid in
mcpiServerConfig.identity.

Production evidence from one project on 2026-04-21 showed ~17 junk
sessions/minute over a 70-second window (20 rows, 65% from "aranhabot"),
projecting to ~25k/day of pollution per active .NET middleware project.

Changes:

* CheckpointApiClient.ReportDetectionAsync no longer falls back to
 bouncer/sessions. Non-2xx responses from log-detection are logged at
 Warning with status code, reason phrase, project ID, and a bounded
 512-char prefix of the response body, then dropped. Detection events
 and MCP-I session registrations are distinct concerns and must not
 be conflated.
* TryReportToLegacyAsync and its synthetic-DID payload construction
 are deleted. ICheckpointApiClient.ReportDetectionAsync doc comment
 updated to point at log-detection as the sole endpoint.
* New private helper SafeReadTruncatedBodyAsync reads at most 512 chars
 of the failed response body and never throws, so high-volume failure
 loops do not flood logs or leak large payloads.

No behavioural change when log-detection returns 2xx. Callers that were
relying on the legacy endpoint to persist detections should be on
Checkpoint.* >= 0.2.9 where log-detection is the documented path.

Operational follow-up (not in this release): after deploying 0.3.3,
clean up the existing junk rows with
DELETE FROM bouncer_sessions WHERE agent_did LIKE 'did:web:detected:%';

0.3.2 — Send detectionClass with log-detection payload

Pre-0.3.2 middleware submitted detection events to
POST /api/v1/log-detection without a detectionClass field. The server
falls back to isAgent ? "ai_agent" : "human", which mis-stamped every
Googlebot, GPTBot, ClaudeBot, SemrushBot, etc. hit as an interactive
AI agent. One hardwareworld.com test window produced 325,056 such
mis-classified rows under source="middleware" in 72 hours.

The detector already produces the correct class in
DetectionResult.DetectionClass. The gap was purely transport — the
DetectionEvent DTO and log-detection payload both dropped the field.
This release closes the gap:

* DetectionEvent gains a nullable DetectionClass property
 (Checkpoint.Core). Nullable preserves binary compat for any caller
 that constructs the DTO manually.
* CheckpointApiClient.TryReportToLogDetectionAsync now emits
 detectionClass in the JSON payload via a wire mapping:
 Human -> "human", AiAgent -> "ai_agent", Bot -> "bot",
 IncompleteData/Unknown -> "incomplete_data". Null omits the field so
 the server's UA-pattern fallback still applies for older callers.
* Both middlewares pass result.DetectionClass through to the
 DetectionEvent — CheckpointMiddleware (AspNetCore, net8.0) and
 CheckpointModule (AspNet, net462) share the same wiring.

Covers all four packages — Checkpoint.Core, Checkpoint.AspNet,
Checkpoint.AspNetCore, and the KyaOs.Checkpoint umbrella.

9 new tests:
* Checkpoint.Core.Tests/Api/CheckpointApiClientPayloadTests (7) —
 per-enum wire assertions + null-omitted + endpoint URL.
* Checkpoint.AspNetCore.Tests/Middleware (2) — bot and AI-agent
 DetectionClass pass-through from detector to DetectionEvent.

Follow-up (out of this release): harden the server fallback at
apps/web/app/api/v1/log-detection/route.ts so older clients that still
omit the field are classified via UA pattern instead of defaulted to
ai_agent.

0.3.1 — Block/Instruct response no longer leaks bad McpServerUrl

Follow-up to 0.3.0. The redirect branches in 0.3.0 correctly refused to
302 to a relative or non-http(s) McpServerUrl, but the block-response
body (PlainText "MCP Server: /connect/x" line, JSON "mcp_server" field)
and Instruct response still propagated the bad URL to the agent. An LLM
fetcher would relay the broken instructions to the user verbatim.

Changes:
* WritePlainTextResponseAsync (AspNetCore): McpServerUrl is gated through
 UrlHelpers.IsAbsoluteHttpUrl — relative / non-http values are dropped
 from the body and the agent gets the "contact site owner" fallback.
* WriteJsonResponseAsync (AspNetCore) + WriteBlockedJsonResponse (AspNet):
 the "mcp_server" / "mcpServer" field is omitted (along with the
 "instructions" sentence) when McpServerUrl is not an absolute http(s)
 URL.
* WriteJsonResponseAsync + WriteInstructResponseAsync (AspNetCore):
 switched from WriteAsJsonAsync to JsonSerializer.Serialize +
 response.WriteAsync. The streaming serializer requires the response
 body PipeWriter to implement UnflushedBytes, which TestServer's pipe
 writer doesn't — every JSON-mode test in the AspNetCore suite was
 silently throwing into FailOpen and falling through to the route
 handler. Buffering matches what the AspNet adapter already does, and
 resolves the four pre-existing test failures inherited from earlier
 releases.

7 new tests in CheckpointMiddlewareTests covering Json/PlainText
McpServerUrl omission across path-relative, schemeless, protocol-relative,
javascript:, and ftp:// inputs. AspNetCore suite now 20/20 green
(was 9/13).