Common Contracts | Contexa Docs

핵심 어노테이션

@EnableAISecurity는 Spring Boot 애플리케이션에서 런타임 제어 플레인을 활성화하고, @Protectable은 Contexa 보호 대상 요청 핸들러를 표시합니다.

Java

@EnableAISecurity
@SpringBootApplication
public class Application { }

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

보안 모드

SecurityMode는 현재 FULL과 SANDBOX를 제공합니다. @EnableAISecurity의 기본값은 SANDBOX입니다.

어노테이션 속성

`@EnableAISecurity`

패키지: io.contexa.contexacommon.annotation. @Import(AiSecurityImportSelector.class)로 메타 어노테이션되어 있습니다.

속성	타입	기본값	설명
`mode`	`SecurityMode`	`SANDBOX`	런타임 모드. `SANDBOX`는 호스트 애플리케이션의 기존 인증을 유지하고, `FULL`은 Contexa가 로그인 흐름을 소유합니다.
`authObjectLocation`	`AuthObjectLocation`	`AUTO`	SANDBOX 모드에서 인증 객체 위치 힌트. Enum 값: `AUTO`, `SESSION`, `REQUEST_ATTRIBUTE`, `HEADER`.
`authObjectAttribute`	`String`	`""`	호스트 앱이 Spring Security 외부에 인증 객체를 저장할 때 사용할 세션/요청 속성명.
`authObjectType`	`Class<?>`	`Object.class`	리플렉션 추출을 위한 타입 힌트(선택).

`@Protectable`

패키지: io.contexa.contexacommon.annotation. 메서드 레벨 마커로 AuthorizationManagerMethodInterceptor와 ProtectableMethodAuthorizationManager가 평가합니다.

속성	타입	기본값	설명
`ownerField`	`String`	`""`	소유권 기반 인가에 사용되는 반환 타입의 필드명.
`sync`	`boolean`	`false`	`true`일 때 `SynchronousProtectableDecisionService`가 `SecurityPlaneAgent`를 인라인으로 호출하여 메서드 반환 전 `ZeroTrustAction`을 생성합니다. `false`일 때는 `ZeroTrustSpringEvent`가 발행되고 평가가 비동기로 수행됩니다.

브리지와 공통 계약

common 모듈에는 런타임 보안 체인에서 사용하는 브리지 계약과 공통 타입이 포함됩니다. 이 계약 덕분에 자동 구성과 모듈 와이어링이 구현 모듈과 느슨하게 결합됩니다.

AiSecurityImportSelector가 FQCN으로 io.contexa.autoconfigure.ai.AiSecurityConfiguration을 import합니다.
SecurityMode(FULL, SANDBOX)와 AuthObjectLocation(AUTO, SESSION, REQUEST_ATTRIBUTE, HEADER)은 io.contexa.contexacommon.security.bridge에 정의됩니다.
ZeroTrustAction(io.contexa.contexacommon.enums)은 5개 런타임 결과(ALLOW, BLOCK, CHALLENGE, ESCALATE, PENDING_ANALYSIS)의 HTTP 상태·TTL·부여 권한을 중앙화합니다.
공통 계약은 autoconfigure, identity, iam, core 런타임 서비스가 함께 사용합니다.