Common Contracts | Contexa Docs

Key Annotations

@EnableAISecurity enables the runtime control plane from a Spring Boot application, and @Protectable marks request handlers for Contexa protection.

Java

@EnableAISecurity
@SpringBootApplication
public class Application { }

@Protectable
@GetMapping("/api/customers")
public List<Customer> list() { ... }

Security Mode

SecurityMode currently exposes FULL and SANDBOX. The default on @EnableAISecurity is SANDBOX.

Annotation Attributes

`@EnableAISecurity`

Package: io.contexa.contexacommon.annotation. Meta-annotated with @Import(AiSecurityImportSelector.class).

Attribute	Type	Default	Description
`mode`	`SecurityMode`	`SANDBOX`	Runtime mode. `SANDBOX` preserves the host application's existing authentication; `FULL` lets Contexa own the login flows.
`authObjectLocation`	`AuthObjectLocation`	`AUTO`	Hint for locating the authenticated object in SANDBOX mode. Enum values: `AUTO`, `SESSION`, `REQUEST_ATTRIBUTE`, `HEADER`.
`authObjectAttribute`	`String`	`""`	Session or request attribute name used when the host app stores the authenticated object outside Spring Security.
`authObjectType`	`Class<?>`	`Object.class`	Optional type hint for reflective extraction of the authenticated object.

`@Protectable`

Package: io.contexa.contexacommon.annotation. Method-level marker consumed by AuthorizationManagerMethodInterceptor and ProtectableMethodAuthorizationManager.

Attribute	Type	Default	Description
`ownerField`	`String`	`""`	Field name on the return type used to identify the resource owner for ownership-based authorization.
`sync`	`boolean`	`false`	When `true`, `SynchronousProtectableDecisionService` invokes `SecurityPlaneAgent` inline and produces the `ZeroTrustAction` before the method returns; when `false`, a `ZeroTrustSpringEvent` is published and evaluation is asynchronous.

Bridge and Shared Contracts

The common module also carries shared bridge contracts and types used by the runtime security chain. These contracts let autoconfiguration and module wiring stay decoupled from implementation modules.

AiSecurityImportSelector imports io.contexa.autoconfigure.ai.AiSecurityConfiguration by fully qualified class name.
SecurityMode (FULL, SANDBOX) and AuthObjectLocation (AUTO, SESSION, REQUEST_ATTRIBUTE, HEADER) live in io.contexa.contexacommon.security.bridge.
ZeroTrustAction (io.contexa.contexacommon.enums) centralizes HTTP status, TTL, and granted authority for the five runtime outcomes (ALLOW, BLOCK, CHALLENGE, ESCALATE, PENDING_ANALYSIS).
Shared contracts are consumed by autoconfigure, identity, iam, and core runtime services.