Permissio

A standalone, domain-agnostic authorization service combining RBAC, ABAC, and ReBAC into a unified, high-performance evaluation pipeline with a future migration path to a Zanzibar-style relationship graph.

---

Documentation Directory

Detailed technical documentation has been modularized:

Document	Description
High-Level Design (HLD)	System ecosystem architecture with interactive clickable Mermaid diagrams linking to LLD components.
UML Diagrams & Low-Level Design (LLD)	Detailed Mermaid.js specifications (ERD, Filter Chain Sequence, Engine Class Diagram, Decision Tree, SpEL Sandbox).
Client Integration & Setup Guide	Step-by-step client onboarding, 5-step workflow, and multi-language SDK examples (Java, TypeScript, Python, cURL).
Developer API Reference & Contract Spec	Exhaustive endpoint documentation, schemas, security headers, ReBAC matrix, and SpEL policy guides.
Architecture & Authorization Pipeline	Core primitives (Subject, Resource, Relation, Action, Policy), ReBAC hierarchy, and 4-stage decision pipeline.
Engineering Backlog & Roadmap	Complete breakdown of Epics 0 through 12, TDD verification status, and deliverables.
Development & Local Setup Guide	Terminal commands cheat sheet, H2 vs PostgreSQL profile configuration, .env setup, and JaCoCo coverage guide.
Project Structure & Module Directory	Codebase package structure, class responsibilities, filter chain flow, and conventions for new modules.

---

The Core Problem & Solution

In most architectures, authorization is fragmented: hardcoded role checks (hasRole('ADMIN')) are scattered throughout controllers, services, and SQL queries. This makes hierarchical relationships ("Can a Project Lead edit documents in Project #10?") or contextual conditions ("Can a Manager approve expenses during working hours?") difficult to maintain and verify.

How Permissio Solves This:

1. Centralized Decision Engine: Exposes a single high-performance POST /api/v1/authorize endpoint.
2. Domain-Agnostic Primitives: Translates any business entity (users, documents, medical records, financial assets) into universal primitives (Subject, Resource, Relation, Action, Policy).
3. Multi-Model Support: Unifies Role-Based (RBAC), Attribute-Based (ABAC with Sandboxed SpEL), and Relationship-Based (ReBAC) authorization into a single short-circuiting pipeline.
4. Hard Multi-Tenant Isolation: Consuming services are tenants, never code dependencies. Every piece of data is strictly isolated by client_id.
5. Immutable Audit Trail: Append-only audit logging of every decision, reason code, evaluator, and trace ID correlation via GET /api/v1/audit-logs.

---

Quickstart in 60 Seconds

1. Clone & Run (In-Memory Dev Mode)

Permissio boots out of the box with zero external dependencies using an embedded H2 database:

# Clone the repository
git clone https://github.com/PerHac13/permissio.git
cd permissio

# Run local dev server (Windows)
.\mvnw.cmd spring-boot:run

# Run local dev server (Linux / macOS / Git Bash)
./mvnw spring-boot:run

• Base URL: http://localhost:8080
• H2 Web Console: http://localhost:8080/h2-console (JDBC URL: jdbc:h2:mem:permissio, User: sa, Password: blank)
• Health Check: http://localhost:8080/actuator/health

2. Run the Test Suite & Coverage Gate

# Run all unit & integration tests + JaCoCo coverage check (>= 80% required)
./mvnw clean verify -Dspring.profiles.active=test

---

Tech Stack

• Language: Java 21 (LTS) — Records, Pattern Matching, Sealed Types
• Framework: Spring Boot 4.1.0 (latest)
• Persistence: Spring Data JPA + Hibernate 7
• Databases:
  • Dev / Test: H2 In-Memory (PostgreSQL compatibility mode)
  • Production: PostgreSQL 16 (via Docker Compose or Cloud RDS)
• Migrations: Flyway (V1 through V6)
• Security: Spring Security + JJWT (RS256 RSA Asymmetric) + Salted SHA-256 (API Keys) + BCrypt
• Policy Engine: Sandboxed Spring Expression Language (SpEL) with SimpleEvaluationContext (RCE-safe)
• JSON Engine: Jackson 3 (tools.jackson.core:jackson-databind)
• Testing: JUnit 5, Mockito, AssertJ, Spring Test, JaCoCo (≥ 80% line coverage enforcement)

---

Roadmap & Milestone Progress

• Epic 0 — Project Bootstrap & Infrastructure
  • Spring Boot 4.1.0 + Java 21 setup
  • Multi-profile configuration (H2 dev/test, PostgreSQL prod)
  • Flyway migrations baseline (V1__init_clients_table.sql)
  • CI pipeline with JaCoCo coverage enforcement
• Epic 1 — Multi-Tenant & Client Module (client)
  • Client entity and ClientRepository
  • TenantContext ThreadLocal tenant scope management
  • Salted ApiKeyHasher (keys never stored in plaintext)
  • ApiKeyAuthenticationFilter with automatic tenant scoping
• Epic 2 — Authentication & JWT Module (authentication, security)
  • Subject JPA entity and Flyway migration (V2__init_subjects_table.sql)
  • BCrypt password hashing & RS256 JwtTokenProvider
  • JwtAuthenticationFilter with Bearer token validation
  • Registration & login endpoints (/api/v1/auth/register, /api/v1/auth/login)
• Epic 3 — Subject Module (Tenant-Scoped CRUD & Attributes)
  • SubjectService — tenant-scoped create, get, list, update attributes, delete
  • SubjectController — 6 REST endpoints under /api/v1/subjects
  • DTOs: SubjectResponse, CreateSubjectRequest, UpdateSubjectAttributesRequest
  • Cross-tenant isolation: subjects invisible across tenants (returns 404, never leaks existence)
• Epic 4 — Resource Module (Tenant-Scoped CRUD & Attribute Management)
  • Resource JPA entity and Flyway migration (V3__init_resources_table.sql)
  • Compound uniqueness on (client_id, resource_type, external_id)
  • ResourceService — tenant-scoped create, get, list/filter by type, update attributes, delete
  • ResourceController — 6 REST endpoints under /api/v1/resources
  • Dynamic Jackson JSON attributes serialization/deserialization
  • Hard cross-tenant isolation (returns 404, never leaks existence across boundaries)
• Epic 5 — Relationship Module (ReBAC Foundation: Roles, Hierarchy & Tenant-Scoped Tuples)
  • Relation enum with explicit rank ordering (OWNER > MANAGER > LEAD > MEMBER)
  • Universal Action enum (CREATE, READ, UPDATE, DELETE, APPROVE, REJECT)
  • Deterministic RelationHierarchy 4×6 permission matrix
  • Relationship JPA entity and Flyway migration (V4__init_relationships_table.sql)
  • Compound uniqueness on (client_id, subject_id, resource_id, relation)
  • RelationshipService — tenant-scoped create, get by ID, filter by subject/resource, delete
  • RelationshipController — REST endpoints under /api/v1/relationships
  • Hard cross-tenant relational integrity (cannot link subjects/resources from other tenants)
• Epic 6 — Authorization Engine Core (POST /api/v1/authorize)
  • Decision and AuthorizationContext domain records
  • PolicyEvaluator plugin interface with @Order chain execution
  • RebacEvaluator (priority 1) resolving highest relationship rank and matrix permissions
  • AuthorizationContextBuilder scoped to TenantContext with 404 non-existence safety
  • AuthorizationEngine orchestrator with fast short-circuiting on denial
  • AuthorizationController (POST /api/v1/authorize)
• Epic 7 — ABAC & Business Rule Evaluators
  • Flyway migration V5__init_policies_table.sql for tenant policies
  • Sandboxed SpEL engine (PolicyEvaluationEngine) using SimpleEvaluationContext.forReadOnlyDataBinding() (RCE-safe)
  • Policy JPA entity and PolicyRepository
  • AbacEvaluator (priority 2) matching subject/resource attributes
  • BusinessRuleEvaluator (priority 3) evaluating environmental conditions and time windows
  • Policy CRUD endpoints under /api/v1/policies
• Epic 8 — Audit Logging Module
  • Flyway migration V6__init_audit_logs_table.sql with trace_id column
  • AuditLog JPA entity and AuditLogRepository
  • AuditService capturing every decision (allow/deny), evaluator name, reason code, and MDC trace ID
  • Audit query API (GET /api/v1/audit-logs) with pagination and filtering
• Epic 9 — Observability & OpenTelemetry
  • Config-driven YAML observability (permissio.observability.otel & logging)
  • Option in YAML config to toggle emitting logs to OpenTelemetry OTLP exporter
  • Active console logging with optional structured JSON formatting
  • TraceContextFilter injecting trace_id, span_id, clientId into MDC and X-Trace-Id response header
  • OpenTelemetry manual spans around AuthorizationEngine and PolicyEvaluators via AuthorizationTracer
  • Custom metrics: authz_requests_total, authz_decision_duration_seconds, authz_denials_total via AuthorizationMetrics
• Epic 10 — Security Hardening & RS256 JWT
  • Asymmetric RS256 JWT signing with automatic transient key-pair generator in dev/test (RsaKeyProvider)
  • Algorithm confusion protection (HS256 rejection test)
  • Exhaustive Bean Validation integration test suite across all request DTOs (BeanValidationIntegrationTest)
  • Global exception handler completeness (GlobalExceptionHandler + ForbiddenException)
  • API key log sanitization test (ApiKeyLogSanitizationTest)
• Epic 11 — Tenant Isolation Contract Suite
  • Two-client isolation test for Subjects (SubjectIsolationTest)
  • Two-client isolation test for Resources (ResourceIsolationTest)
  • Two-client isolation test for Relationships (RelationshipIsolationTest)
  • Crafted-ID attack test with 404 existence leakage protection (CraftedIdAttackTest)
  • Full end-to-end Independence Acceptance test with zero external dependencies (IndependenceAcceptanceTest)
• Epic 12 — Documentation & Contract Stability
  • OpenAPI 3 + Swagger UI integration (springdoc-openapi-starter-webmvc-ui + OpenApiSmokeTest)
  • /authorize request/response JSON contract locking test (AuthorizeContractTest)
  • Complete Developer API Reference & Technical Specification (docs/API_REFERENCE.md)
  • High-Level Design (HLD) & Low-Level Design (LLD) specifications (docs/HLD_DESIGN.md, docs/UML_LLD_DESIGN.md)

---

Performance Benchmarking & Large-Scale Mock Data

Permissio includes an enterprise benchmarking suite and synthetic data seeder:

1. Seed Enterprise Multi-Tenant Dataset

# Seed 5 enterprise tenants with realistic subjects, resources, and ReBAC hierarchies:
./scripts/seed-large-dataset.sh --file=perf/large-mock-dataset.sql

# Or dynamically generate 1,000+ synthetic entities:
./scripts/seed-large-dataset.sh --count=1000

2. Run Multi-Tier Latency Benchmarks (100 -> 10,000 requests)

# Run sequential multi-tier matrix (100, 500, 1k, 2k, 5k, 10k requests)
./scripts/run-perf-test.sh --all-tiers

# Or benchmark a specific tier
./scripts/run-perf-test.sh --requests=1000

3. Run Concurrent k6 Load Tests

# Baseline smoke test
k6 run perf/load-test.js

# Sustained load test (50 Virtual Users)
k6 run perf/load-test.js --env SCENARIO=load

# Spike stress test (250 Virtual Users)
k6 run perf/load-test.js --env SCENARIO=spike

---

License

This project is licensed under the Apache 2.0 License.