-
Notifications
You must be signed in to change notification settings - Fork 0
Request lifecycle
This page traces a single request from the moment it arrives at a Kairo application to the moment the response is sent. Understanding this flow is the fastest way to build an accurate mental model of how the framework operates.
The HTTP engine receives the request. Before any application code runs, the Request Membrane processes it.
The membrane computes an entropy score from:
- The shape and content of the payload (field names, nesting, character patterns)
- Timing (inter-request interval for this session, deviation from the time-of-day baseline)
- Header fingerprint (User-Agent consistency, encoding anomalies)
- IP behavioral history from the rolling 15-minute window
- URL structure and query string shape
This score — a float between 0.0 (perfectly normal) and 1.0 (maximally anomalous) — is attached to the request context and flows through every subsequent layer.
Ghost route check: The membrane checks the incoming path against its table of automatically generated ghost routes (.env, /wp-admin, /api/v1/admin/users, etc.). If the path matches a ghost route, a syntactically plausible fake response is generated and returned immediately. A silent alert is written to the security event stream. The session's entropy score is permanently elevated. The real application code is never reached.
For requests originating from other Kairo services, the membrane also verifies the signed payload envelope — a cryptographic HMAC over the payload, timestamp, and originating service identity.
For routes with intent declarations, the Intent Engine validates that the request context is consistent with the route's declared purpose.
For service-to-service calls, the originating service is checked against the Intent Graph — the directed graph of known-good inter-service call relationships built during development. A call that falls outside the graph does not block the request, but raises a flag, logs a security event, and elevates the originating service's entropy score.
The caller's identity is resolved using the developer-provided identity function (a JWT verifier, a session lookup, a Clerk call — whatever the application uses).
The resolved identity is evaluated against the route's declared access requirements. This is a relationship check, not a role check. "Does this user own the requested resource?" "Are they a member of its project?" "Are they an admin?" These checks run against the Trust Lattice relationship definitions.
Temporal token check: The token's risk profile is evaluated against the risk level of this route. If the token has accumulated enough high-risk actions that its effective validity has decayed for this action type, a step-up authentication challenge is issued before proceeding.
Authorization failure: If the caller does not satisfy the route's requirements:
- For a normal-entropy session: a
403 Forbiddenresponse is returned - For a high-entropy session: a plausible fake success response is returned instead, so the attacker learns nothing about the shape of the access control
The developer's route handler runs.
The ctx object passed to the handler is a transparent proxy. Property access and method calls on ctx are intercepted by the framework's security machinery without the developer's knowledge:
- Reading
ctx.body.*orctx.query.*orctx.params.*tags those values as tainted. The developer reads a plain value; the Sentinel records that a user-controlled value was accessed. - Calling
ctx.db.*passes the query through the Data Shield's query analysis layer before it reaches the database. Injection patterns are detected and neutralized. The handler receives an empty result set rather than an error. - Calling
ctx.json(),ctx.send(), or any other response method queues the response for interception before it is written to the socket.
The handler function itself is never modified. The security machinery runs entirely at the boundaries.
Before the response is written to the network socket, the Data Shield intercepts it.
Contextual redaction is applied: any field in the response that is typed as a model instance is inspected, and fields the caller is not permitted to see — based on their Trust Lattice identity — are stripped. The developer returned the full object; the caller receives only the fields they are allowed to see.
This step is completely transparent. The developer does not write filtering logic. They return a full object. Kairo shapes the response.
The Runtime Sentinel performs a final pass before the response is sent:
- It verifies that no tainted data is present in the response in unescaped form. If tainted data has flowed from a user-input source into the response without sanitization, it is intercepted and neutralized here.
- The entropy score for the session is updated based on the behavior observed during this request.
- A security event is emitted if any taint interception, ghost route hit, intent drift, or lattice decision of note occurred.
If Hardening Mode is active (triggered by high aggregate entropy in recent traffic), additional rules are applied:
- Requests from high-entropy sessions may be deflected to ghost responses without reaching the handler at all
- Subsequent requests from this session may be routed to shadow execution — an isolated context with a read-only snapshot of real data, where the attacker receives a realistic response while real data remains untouched
The response is written to the socket.
In production, Kairo automatically scrubs error responses of: stack traces, file paths, database query strings, internal service names, and environment variable names. The developer can return any error object; Kairo controls what the client actually sees.
| Step | Layer | What happens | Blocks? |
|---|---|---|---|
| 1 | Request Membrane | Entropy scoring, ghost route check | Only for ghost route hits |
| 2 | Intent Engine | Behavioral contract check, intent graph | No — alerts only |
| 3 | Trust Lattice | Authorization, step-up check | Yes (or fake success for high-entropy) |
| 4 | Application code | Handler executes, ctx proxy intercepts | Never |
| 5 | Data Shield | Query analysis, response redaction | Neutralizes, does not block |
| 6 | Runtime Sentinel | Taint verification, entropy update | Neutralizes, does not block |
| 7 | Hardening Mode | Shadow execution, deflection | Only for high-entropy sessions |
| 8 | — | Response written, error scrubbing | — |
← Architecture · Trust Lattice →