Security & Governance
KDCube governance spans identity, app and surface policy, connected-account consent, economics, event visibility, and isolated execution. These controls sit at different boundaries. There is no single permission check that every request is expected to remember.
Auth Flow
Tenant, User, and Execution Boundaries
One running KDCube deployment is bound to one effective tenant/project. Its Postgres, Redis, and object-storage backends may be dedicated or shared with other deployments; when shared, tenant/project schemas, namespaces, and key prefixes separate their records. Inside that deployment, many users share processor capacity and worker processes, so user identity must remain attached to every request and every runtime hop.
one deployment: tenant + project
many concurrent users
|
+-- authenticated request context
+-- portable cross-runtime context
+-- guarded app / tool / named-service calls
+-- user + conversation scoped logical refs
+-- sparse materialized workspace for generated codeKDCube's ReAct agent operates on logical refs through the shared Agent Harness, not unrestricted platform paths. The agent may request a pull or checkout, but a trusted resolver binds the request to the runtime's tenant, project, user, conversation, and authority. The model cannot replace those values with another user's identity. Only resolver-approved bytes are materialized into the current workspace.
In split execution, the networkless executor receives that selected workspace, artifact output, executor logs, and the supervisor socket. It does not receive platform storage, app storage, deployment descriptors, provider credentials, or another user's workspace. Trusted app and tool code is a separate boundary: it runs through authenticated SDK and surface contracts under the carried request identity. It should not be described as sandboxed merely because generated code is isolated.
Other profiles have different guarantees. Local subprocess is development-time crash containment. Legacy combined Docker shares one container and mount namespace. A Fargate execution uses a filtered, privilege-dropped child inside one remote task/container, not split Docker's separate-container mount boundary. See the canonical trust model for the profile table.
Application backend code is trusted, operator-selected deployment code. The generated-code boundary does not isolate mutually hostile app backends from each other. SimpleIDP is a development/demo authority: every service reads the pinned /config/idp_users.json store, and its browser token is explicit public development config. Production posture depends on the selected authority, secret provider, deployment topology, trusted app set, exposed surfaces, and execution profile together.
Security Features
| Feature | Description |
|---|---|
| Content Filtering | Deployments can scan uploaded files before runtime processing. The enabled scanner and policy are deployment configuration. |
| Outbound Event Policy | event_filter.py can reduce app-emitted data before browser delivery or recording. It is a presentation and disclosure control, not the authorization boundary for required business state or secrets. |
| App and Tool Policy | Declared surface visibility, tool allowlists, user narrowing, and runtime guards control what an authenticated actor may invoke. An operation with no declared visibility is available to authenticated registered users; only declared visibility introduces role requirements. |
| Named-Service Policy | The consumer config limits namespaces and operations. The provider authorizes the carried identity with its own realm rules. Account-backed operations additionally check provider capability and the caller's per-account binding on every call. |
| Connection Hub Authority | External accounts delegated to KDCube and KDCube access delegated to hosted agents, external clients, or automation are separate directions. Provider credentials and delegated grant records remain server-side; bearer tokens are handles, not the authority source. |
| Operation CSRF | An app may opt an individual cookie-authenticated POST operation into a ten-minute, subject/app/operation/method-bound, single-use Redis token exchange. This is separate from bearer authorization. |
| Gateway Controls | Selected ingress and REST routes can apply throttling, backpressure, and health controls before work is admitted. |
| Generated-Code Isolation | In split mode, untrusted code runs in a networkless executor. Trusted tools execute through the supervisor under the carried identity; credentials are not injected into the executor. |
Enforcement Model
Controls run at the boundary they protect. A conversation submission, a synchronous app operation, a named-service call, and an isolated tool call do not all pass through one universal six-step sequence.
- Resolve identity — authenticate the external caller or resolve a platform-controlled delegation edge, then construct the request context.
- Authorize the surface — apply enabled-state, visibility, role, delegated-grant, and app-consumer policy for the requested boundary.
- Admit scheduled work — conversation ingress can apply rate, capacity, health, and economics checks before atomically publishing events and a lane wake.
- Guard paid and side-effecting actions — LLM, search, tool, API, and provider calls enforce their own allowance, consent, and budget checks when attempted.
- Preserve identity across runtimes — the portable context carries authority and routing facts; far-side services rebuild clients and authorize using that identity.
- Account and record — accepted work, spendings, tool outcomes, and delivery failures are attributed to the appropriate user, app, conversation, and turn.
Pre-execution gates stop protected work before the protected call occurs. Output filtering is a separate concern. Generated-code isolation applies only when an app uses the execution runtime; deterministic app code and trusted tools remain governed by their own authenticated contracts.
Runtime records, telemetry, and event logs provide reviewable operational evidence; they are not automatically an immutable compliance audit. A WAF such as ModSecurity with OWASP CRS can contribute a technical control, but does not by itself establish PCI DSS compliance or a SOC 2 attestation.
Tool and Namespace Governance
Authorization and tool traits are separate. Authorization decides whether a call is allowed. A tool's strategy trait describes ordered causality for multi-action governance; its execution trait describes completed-call scheduling and replay.
Tool traits
exploration, exploitation, neutral, and unknown describe ordered causality, not permission or a simple read/write label. Unknown tools remain callable but run alone. The supported early-execution profile applies only to fully validated, detached, exactly-neutral calls.
Namespace allowlists
An app can allow search and schema operations for one namespace while withholding upsert or delete. Catalogs advertise only operations the provider actually serves; configuration can restrict that inventory but cannot expand it.
Provider policies
Gate 1 checks the calling client's delegated namespace grants. Gate 2 lets the provider authorize the bound caller identity for that connection mode and, for connected accounts, the provider claims required by the attempted operation.
See Object Ecosystem & Ontologic Contracts for the provider/consumer flow and KDCube ReAct Agent for the ReAct-side tool lifecycle.
Gateway & Admission Control
The gateway applies capacity, throttling, and health policy to the routes configured for those controls. Conversation ingress uses the full admission path before queueing work. Ordinary REST operations may use session-only authentication or an explicitly configured managed guard; they should not be described as if every route shares one pipeline.
Capacity Configuration
Gateway capacity is driven by GATEWAY_CONFIG_JSON and is component-aware — ingress and processor each declare their own slice:
| Parameter | Scope | Purpose |
|---|---|---|
concurrent_requests_per_process | Per process | How many tasks a single Uvicorn worker can handle simultaneously. |
processes_per_instance | Per service instance | Drives the Uvicorn worker count (ingress) or processor worker count (proc). Changes require a restart. |
avg_processing_time_seconds | Per component | Fallback estimate used by backpressure calculations when live metrics are unavailable. |
The effective gateway policy has a tenant/project-scoped Redis runtime projection. On startup, services use that projection when present and otherwise fall back to GATEWAY_CONFIG_JSON, gateway.yaml, or defaults. POST /admin/gateway/update-config updates the projection and broadcasts it to replicas; this does not make Redis the authority for unrelated app descriptors or secrets.
Throttling Rules
Deployments can configure independent burst and longer-window limits by component and user type. Session-scoped counters are namespaced to the deployment's tenant/project. A rejected rate-limited request receives 429; the concrete limits are deployment policy, not platform constants.
Backpressure Handling
Backpressure is per tenant/project (not per session). It evaluates the global queue depth plus healthy processor capacity derived from heartbeat data. Key thresholds include:
- Pressure thresholds — per-user-type admission points. When queue pressure exceeds a tier's configured threshold, new requests from that tier are rejected with 503.
- Hard limit — a deployment-wide ceiling above which all new scheduled work is rejected.
- Capacity buffer — a headroom percentage reserved so the system never saturates completely.
Backpressure is checked in two places: once in the gateway (BackpressureManager.check_capacity) and again at atomic enqueue (AtomicChatQueueManager.enqueue_chat_task_atomic). The double check prevents race conditions where pressure changes between gate and enqueue.
Circuit Breaker
The circuit breaker provides fail-fast behavior when required dependencies or processor health are degraded. Requests covered by that gate are rejected rather than admitted into a system that cannot process them.
Guarded vs Bypass REST Patterns
Ingress and proc classify REST work differently. For ingress, unmatched endpoints are READ traffic and guarded_rest_patterns promotes matching endpoints to full CHAT_INGRESS admission. Proc already classifies /api/integrations/... as CHAT_INGRESS regardless of that list, so app operation protection is not an optional regex convention.
guarded_rest_patterns— ingress regexes whose matches receive throttling, gate checks, and backpressure asCHAT_INGRESS.bypass_throttling_patterns— applies only to requests already classifiedREADorCONNECT; it bypasses throttling counters, not session resolution, gates, or guarded backpressure.
The operator writes these component-scoped lists in gateway.yaml; the runtime projects the effective policy to GATEWAY_CONFIG_JSON and its tenant/project-scoped cache.
Per-Operation CSRF
Gateway admission and CSRF solve different problems. A POST app operation can declare csrf: true; the browser obtains a token from that operation's GET /csrf endpoint and returns it in X-KDCube-CSRF-Token. The token is scoped to the authenticated subject, tenant/project, app, operation, and method, expires after ten minutes, and is consumed atomically once. The operation fails closed with 503 if Redis cannot enforce one-use semantics.
Relationship to Runtime Enforcement
Gateway admission protects scheduled work before enqueue. Surface authorization protects the requested API or operation. Economics guards protect paid calls. Connected-account and realm guards protect provider actions. Keeping these boundaries explicit avoids the unsafe assumption that one successful gateway check authorizes everything downstream.