# CoSec
Multi-tenant, reactive security for Spring: IAM-style policies and role-based permissions, evaluated
deny-first for every request.
[](https://www.apache.org/licenses/LICENSE-2.0.html)
[](https://github.com/Ahoo-Wang/CoSec/releases)
[](https://central.sonatype.com/artifact/me.ahoo.cosec/cosec-core)
[](https://www.codacy.com/gh/Ahoo-Wang/CoSec/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Ahoo-Wang/CoSec&utm_campaign=Badge_Grade)
[](https://codecov.io/gh/Ahoo-Wang/CoSec)
[](https://github.com/Ahoo-Wang/CoSec)
[](https://github.com/Ahoo-Wang/CoSec/actions/workflows/codeql.yml)
[](https://github.com/KotlinBy/awesome-kotlin)
[](https://deepwiki.com/Ahoo-Wang/CoSec)
> [Documentation](https://cosec.ahoo.me/) | [中文文档](https://cosec.ahoo.me/zh/)
## Why CoSec
- **Policies as data.** JSON policies with path actions and composable conditions (roles, tenants, headers,
IP, expressions). Change them at runtime; every instance sees the change immediately.
- **Rate limits.** Per-IP, per-user or shared quotas on allowed requests, counted cluster-wide in Redis, with
`RateLimit-*` and `Retry-After` headers.
- **Deny wins, everywhere.** Global policies, the principal's own policies and role permissions are combined
deny-first, unmatched requests are denied, and errors deny.
- **Multi-tenant and role-based.** Tenant-aware principals, plus per-application permission catalogs
granted to roles per space.
- **One pipeline, three stacks.** Spring WebFlux, Spring MVC and Spring Cloud Gateway share the same
security pipeline and respond identically.
- **Fast and reactive.** Built on Project Reactor. About 2 µs per decision, with no event-loop blocking.
- **Auditable.** An audit event (log or Kafka) and an OpenTelemetry span for every decision, naming the
policy or permission that decided it.
## How a decision is made
```mermaid
flowchart LR
R([Request + JWT]) --> BL{Blacklisted?}
BL -->|yes| DENY([EXPLICIT_DENY])
BL -->|no| ROOT{"Root principal?
(only if root is enabled)"}
ROOT -->|yes| ALLOW([ALLOW])
ROOT -->|no| L["Global policies
Principal policies
Role permissions"]
L --> D{Any DENY matched?}
D -->|yes| DENY
D -->|no| A{Any ALLOW matched?}
A -->|yes| ALLOW
A -->|no| IMP([IMPLICIT_DENY])
```
Denied anonymous callers get `401`, authenticated callers `403`, and rate-limited requests `429`.
## Quick start
```kotlin
dependencies {
implementation(platform("me.ahoo.cosec:cosec-bom:"))
implementation("me.ahoo.cosec:cosec-spring-boot-starter") {
capabilities { requireCapability("me.ahoo.cosec:webflux-support") } // or webmvc-support / gateway-support
}
implementation("me.ahoo.cosec:cosec-spring-boot-starter") {
capabilities { requireCapability("me.ahoo.cosec:cache-support") } // Redis-backed policy storage
}
}
```
```yaml
cosec:
jwt:
secret: ${COSEC_JWT_SECRET}
authorization:
local-policy:
enabled: true # classpath:cosec-policy/*-policy.json
init-repository: true
```
```json
{
"id": "app", "name": "App", "category": "app", "description": "", "type": "global", "tenantId": "(platform)",
"statements": [
{ "name": "public", "action": ["/auth/login", "/actuator/health"] },
{ "name": "authenticated", "action": "/api/**", "condition": { "authenticated": {} } },
{ "name": "admins-only", "effect": "deny", "action": "/api/admin/**",
"condition": { "inRole": { "value": "admin", "negate": true } } }
]
}
```
Continue with the [Quick Start](https://cosec.ahoo.me/guide/quick-start) to issue tokens, then the
[policy language](https://cosec.ahoo.me/policies/language).
## Modules
The starter brings the core, JWT support and auto-configuration; each integration (WebFlux, MVC, Gateway,
Redis, OAuth, OpenTelemetry, OpenAPI, ip2region, Kafka) is an opt-in Gradle capability. See
[Modules](https://cosec.ahoo.me/guide/introduction#modules) for the full list. A ready-to-run gateway is
published as the container image `ahoowang/cosec-gateway`.
## Documentation
- **Getting started**: [Introduction](https://cosec.ahoo.me/guide/introduction) · [Quick Start](https://cosec.ahoo.me/guide/quick-start) ·
[Concepts](https://cosec.ahoo.me/guide/concepts) · [Security Model](https://cosec.ahoo.me/guide/security-model)
- **Integration**: [Web Integration](https://cosec.ahoo.me/integration/web) · [Authentication](https://cosec.ahoo.me/integration/authentication) ·
[Checks in Code](https://cosec.ahoo.me/integration/checks)
- **Policies**: [Policy Language](https://cosec.ahoo.me/policies/language) · [Role Permissions](https://cosec.ahoo.me/policies/role-permissions) ·
[Rate Limiting](https://cosec.ahoo.me/policies/rate-limiting) · [Testing Policies](https://cosec.ahoo.me/policies/testing)
- **Operations**: [Configuration](https://cosec.ahoo.me/operations/configuration) · [Storage and Caching](https://cosec.ahoo.me/operations/storage) ·
[Upgrading](https://cosec.ahoo.me/operations/upgrading) · [Observability](https://cosec.ahoo.me/operations/observability) ·
[Troubleshooting](https://cosec.ahoo.me/operations/troubleshooting)
- **Architecture**: [Overview](https://cosec.ahoo.me/architecture/overview) · [Extending CoSec](https://cosec.ahoo.me/architecture/extending)
- **Releases**: [GitHub Releases](https://github.com/Ahoo-Wang/CoSec/releases)
## Contributing
Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, quality gates and
release process. This project follows a [Code of Conduct](CODE_OF_CONDUCT.md).
## Security
Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md); do not open public issues for them.
## License
CoSec is released under the [Apache License 2.0](LICENSE). Its policy model is inspired by
[AWS IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).