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. Unless contexa.bridge.ownership is set, SANDBOX runs as HOST_OWNED and FULL as CONTEXA_OWNED; an explicitly configured value always wins. In HOST_OWNED, Contexa does not build an authentication SecurityFilterChain, so the host application must declare its own Spring Security configuration to keep its existing behavior. Without one, Spring Boot's default security applies (every request requires authentication, with a generated form login and HTTP Basic login).

Annotation Attributes

`@EnableAISecurity`

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

Attribute	Type	Default	Description
`mode`	`SecurityMode`	`SANDBOX`	Runtime mode. `SANDBOX` (default ownership `HOST_OWNED`) leaves authentication to the host application's Spring Security configuration; `FULL` (default ownership `CONTEXA_OWNED`) 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. This object is read as authorization and delegation evidence and does not by itself become authentication evidence (authentication evidence comes from the Spring `Authentication`).
`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. A Spring Authentication is required at invocation time; without one, or with an anonymous one, the call is rejected.

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.

💡 For the complete annotation attributes specification (such as resourceId, resourceUrl, criticality) and practical usage examples, please refer to the Protectable Detailed Guide.

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.