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입니다. contexa.bridge.ownership을 따로 설정하지 않으면 SANDBOX는 HOST_OWNED, FULL은 CONTEXA_OWNED로 동작하며, 명시적으로 설정한 값이 항상 우선합니다. HOST_OWNED에서는 Contexa가 인증 SecurityFilterChain을 만들지 않으므로, 호스트 애플리케이션이 자신의 Spring Security 설정을 선언해야 기존 동작이 유지됩니다. 설정이 없으면 Spring Boot 기본 보안(모든 요청 인증 필요, 기본 폼 로그인과 HTTP Basic 로그인)이 적용됩니다.

어노테이션 속성

`@EnableAISecurity`

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

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

`@Protectable`

패키지: io.contexa.contexacommon.annotation. 메서드 레벨 마커로 AuthorizationManagerMethodInterceptor와 ProtectableMethodAuthorizationManager가 평가합니다. 호출 시점에 Spring Authentication이 필요하며, 없거나 익명이면 호출이 거부됩니다.

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

💡 resourceId, resourceUrl, criticality 등 전체 어노테이션 속성 스펙 및 실전 활용 예제는 Protectable 상세 가이드를 참고하십시오.

브리지와 공통 계약

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 런타임 서비스가 함께 사용합니다.