Main Modules of the CoSec Framework: Complete Architecture Guide

The CoSec framework comprises 15+ Gradle sub-projects including cosec-api, cosec-core, cosec-jwt, cosec-webmvc, cosec-webflux, and cosec-gateway, delivering a reactive, multi-tenant, policy-driven security solution for JVM applications.

CoSec is an open-source security framework designed for reactive, multi-tenant applications. Understanding the main modules of the CoSec framework is essential for architects integrating policy-based access control into Spring Boot or Spring Cloud Gateway applications. The project is organized as a multi-module Gradle build where each sub-project addresses a specific cross-cutting concern, from core policy evaluation to OpenTelemetry instrumentation.

Core Foundation Modules

cosec-api

The cosec-api module defines the public contracts, data classes, and interfaces that all other modules depend upon. It establishes the foundational abstractions for policies, principals, and security contexts without imposing implementation details.

Key file: cosec-api/src/main/kotlin/me/ahoo/cosec/api/CoSec.kt

cosec-core

The cosec-core module contains the engine that drives the framework. It implements policy loading, evaluation logic, condition and action matching, tenant isolation, token handling, and security context management. The DefaultPolicyEvaluator class serves as the primary entry point for policy decisions.

Key file: cosec-core/src/main/kotlin/me/ahoo/cosec/policy/DefaultPolicyEvaluator.kt

Authentication and Identity Modules

cosec-jwt

The cosec-jwt module provides JWT-based authentication support, handling token generation, parsing, and verification. This module is essential for stateless security architectures.

cosec-social

The cosec-social module integrates third-party identity providers via OAuth2, managing token exchange and social login flows.

Web Framework Adapters

cosec-webmvc

For traditional servlet-based applications, the cosec-webmvc module provides Spring WebMVC integrations including HandlerInterceptor and Filter implementations that enforce policies on incoming requests.

cosec-webflux

The cosec-webflux module offers reactive support for Spring WebFlux applications, implementing WebFilter to handle non-blocking security checks.

cosec-gateway

Designed for API gateway architectures, the cosec-gateway module implements a Spring Cloud Gateway filter that enforces policies at the edge. The AuthorizationGatewayFilter class processes each exchange against configured policies.

Key file: cosec-gateway/src/main/kotlin/me/ahoo/cosec/gateway/AuthorizationGatewayFilter.kt

Infrastructure and Utility Modules

cosec-cocache

The cosec-cocache module provides caching abstractions for policies and application-role permissions, including a Redis-backed implementation via RedisPolicyRepository.

Key file: cosec-cocache/src/main/kotlin/me/ahoo/cosec/cache/RedisPolicyRepository.kt

cosec-ip2region

Supporting geo-location-based access control, the cosec-ip2region module provides IP-to-region lookup capabilities used by the built-in IpRegion condition matcher.

Key file: cosec-ip2region/src/main/kotlin/me/ahoo/cosec/ip2region/IpRegionResolver.kt

cosec-opentelemetry

For observability, the cosec-opentelemetry module instruments security decisions with OpenTelemetry, extracting identity attributes for distributed tracing via CoSecAttributesExtractor.

Key file: cosec-opentelemetry/src/main/kotlin/me/ahoo/cosec/opentelemetry/CoSecAttributesExtractor.kt

cosec-openapi

The cosec-openapi module generates OpenAPI (Swagger) documentation that embeds CoSec policy information, bridging security configuration with API documentation.

Spring Boot Integration and Dependency Management

cosec-spring-boot-starter

The cosec-spring-boot-starter module provides auto-configuration that wires together the core modules, web adapters, and cache implementations. It parses cosec-policy/*.json files and registers the security filter chain automatically.

Key file: cosec-spring-boot-starter/src/main/kotlin/me/ahoo/cosec/spring/boot/starter/CoSecAutoConfiguration.kt

cosec-bom and cosec-dependencies

These modules provide Bill of Materials (BOM) and dependency management coordinates, allowing consumers to import a single versioned platform definition rather than managing individual module versions.

Complete Module Enumeration

The root settings.gradle.kts confirms the full module structure:

include(":cosec-bom")
include(":cosec-dependencies")
include(":cosec-api")
include(":cosec-core")
include(":cosec-jwt")
include(":cosec-cocache")
include(":cosec-social")
include(":cosec-webmvc")
include(":cosec-webflux")
include(":cosec-spring-boot-starter")
include(":cosec-gateway")
include(":cosec-gateway-server")
include(":cosec-opentelemetry")
include(":cosec-ip2region")
include(":code-coverage-report")
include(":cosec-openapi")

Practical Integration Examples

Spring Boot Application Setup

Add the starter dependency to your build.gradle.kts:

dependencies {
    implementation("me.ahoo.cosec:cosec-spring-boot-starter:2.2.0")
}

Configure policy locations in application.yml:

cosec:
  policy:
    locations:
      - classpath:/cosec-policy/*.json

Access the security context in a controller:

@RestController
class UserController {
    @GetMapping("/user/{id}")
    fun getUser(@PathVariable id: String, request: ServerHttpRequest): String {
        val ctx = request.getSecurityContext()
        return "Current principal = ${ctx.principal?.id}"
    }
}

Framework-Agnostic Core Usage

For non-Spring applications, use the core API directly:

val configuration = Configuration()
val policyLoader = LocalPolicyLoader(configuration)
val policy = policyLoader.load("classpath:/my-policy.json")

val evaluator = DefaultPolicyEvaluator(configuration)
val request = Request.builder()
    .path("/order/ship")
    .principal(SimplePrincipal("bob"))
    .build()

val result = evaluator.evaluate(request, policy)
println("Allowed? ${result.isAllowed}")

Summary

• CoSec is organized as a multi-module Gradle project with over 15 sub-projects.
• cosec-api and cosec-core provide the foundational contracts and policy evaluation engine.
• cosec-jwt and cosec-social handle authentication via tokens and OAuth2.
• cosec-webmvc, cosec-webflux, and cosec-gateway adapt the framework to specific runtime environments.
• cosec-spring-boot-starter automates configuration for Spring Boot applications.
• Supporting modules like cosec-cocache, cosec-ip2region, cosec-opentelemetry, and cosec-openapi provide caching, geo-location, observability, and documentation capabilities.

Frequently Asked Questions

What is the minimum set of CoSec modules required for a Spring Boot application?

For a standard Spring Boot web application, you only need the cosec-spring-boot-starter module. This starter transitively pulls in cosec-api, cosec-core, and the appropriate web adapter (cosec-webmvc or cosec-webflux) based on your classpath. You can add cosec-jwt or cosec-cocache as needed for token handling or distributed caching.

How does CoSec support reactive programming models?

CoSec provides dedicated adapters for reactive stacks. The cosec-webflux module implements WebFilter for Spring WebFlux applications, while cosec-gateway provides a GatewayFilter for Spring Cloud Gateway. Both adapters use the same cosec-core evaluation engine, ensuring consistent policy enforcement across blocking and non-blocking architectures.

Can CoSec be used without Spring Framework?

Yes. The cosec-api and cosec-core modules are framework-agnostic Kotlin libraries. You can instantiate DefaultPolicyEvaluator and LocalPolicyLoader directly, load JSON policy files, and evaluate requests programmatically. The Spring-specific modules (webmvc, webflux, starter) are optional adapters that simplify integration for Spring ecosystems.

Where are policy definitions stored in a CoSec application?

By default, policies are loaded from JSON files located in classpath:/cosec-policy/. The cosec-spring-boot-starter automatically scans this location. For distributed deployments, the cosec-cocache module provides a RedisPolicyRepository that stores policies in Redis, enabling centralized policy management across multiple service instances.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}