⚔️ Vorpal Identity Engine

The sharpest SCIM 2.0 implementation for the modern cloud. Built with Go, Fiber, PostgreSQL, and go-dsl.

---

🌍 English

What is Vorpal?

Vorpal is a high-performance, open-source SCIM 2.0 (System for Cross-domain Identity Management) server.

It is the spiritual successor to goscim, but re-engineered from the ground up with a specific philosophy: Simplicity and Database Power.

While goscim focused on being a generic framework using ANTLR for parsing, Vorpal is opinionated:

1. PostgreSQL is King: We leverage JSONB columns to store SCIM resources dynamically. No complex ORM mapping—just pure, indexable JSON.
2. No Heavy Parsers: We replaced the heavy ANTLR runtime with go-dsl, a lightweight, Go-native parser builder.
3. Performance First: Built on top of Fiber, the fastest HTTP engine for Go.

🚀 Key Features

• Native SCIM Filtering: Converts SCIM filters (e.g., emails[type eq "work"]) directly into optimized PostgreSQL SQL queries using go-dsl.
• Embedded Database: Comes with an embedded PostgreSQL instance for zero-setup development (recommended for dev or small workloads).
• External Database: Fully configurable via config.toml to connect to external PostgreSQL clusters for production.
• Full SCIM Support: Includes implementation for PATCH, PUT, POST, GET, and DELETE.
• Schema Driven: Fully configurable via JSON schemas (User, Group, EnterpriseUser, etc.).
• Viral Speed: Designed to handle high-throughput identity requests with minimal latency.

Feature	Status	RFC Spec
Core Schema (User/Group)	✅ Supported	RFC 7643
Enterprise Extension	✅ Supported	RFC 7643
Custom Extensions	✅ Supported	Dynamic
Sorting (sortBy)	✅ Supported	Full
Filtering (filter)	✅ Supported	Advanced (Nested)
Patching (PATCH)	✅ Supported	Add/Remove/Replace
Pagination	✅ Supported	startIndex/count
Bulk Operations	🚧 Roadmap	-

🛠️ Architecture: The "go-dsl" Advantage

Parsing SCIM filters is notoriously hard. Most implementations use regex (fragile) or ANTLR (heavy/complex).

Vorpal uses go-dsl to define the SCIM grammar in pure Go. This allows us to:

• Compile filters directly to SQL WHERE clauses safely.
• Handle complex nesting and logical operators without the overhead of a generated parser.
• Keep the binary small and fast.

graph LR
    Client[SCIM Client] -- HTTP/JSON --> Fiber[Fiber Web Server]
    Fiber -- SCIM Query --> Parser[go-dsl Parser]
    Parser -- SQL Fragment --> Builder[SQL Builder]
    Builder -- Optimized Query --> DB[(PostgreSQL JSONB)]
    DB -- Result --> Fiber

Loading

⚡ Quick Start

1. Clone the repo

   git clone https://github.com/arturoeanton/go-vorpal-scim.git
   cd vorpal

2. Run it (Embedded DB mode)

   go run main.go

   Vorpal will automatically spin up a local Postgres instance in ./data/db.

3. Test it

   curl http://localhost:3000/ServiceProviderConfig

# config.toml example
[server]
port = ":3000"
app_name = "Vorpal Identity"

[database]
use_embedded = true  # Set false for production
host = "localhost"
user = "vorpal"
password = "secure_password"

🐳 Docker y Docker Compose

Vorpal includes a docker-compose.yml file to run the entire stack (App + PostgreSQL + PGAdmin) easily.

1. Start the stack

   docker-compose up --build -d

2. Access the services

   • Vorpal API: http://localhost:3000
   • PGAdmin: http://localhost:5050 (Login: [email protected] / admin)
   • PostgreSQL: localhost:5432 (Usuario: vorpal, Pass: secret_password, DB: vorpal_db)

3. Stop the stack

   docker-compose down

🤝 Contributing

We want Vorpal to be the de facto standard for SCIM in Go. We need help with:

• Adding OAuth2/OIDC middleware.
• Improving test coverage.
• Writing documentation.

Found a bug? Have an idea? Open an issue or submit a PR! Let's build the future of Identity together.

---

🇪🇸 Español

¿Qué es Vorpal?

Vorpal es un servidor SCIM 2.0 de alto rendimiento y código abierto.

Es el sucesor espiritual de goscim, pero rediseñado desde cero con una filosofía clara: Simplicidad y Potencia de Base de Datos.

Mientras que goscim se enfocaba en ser un framework genérico usando ANTLR, Vorpal se enfoca en:

1. PostgreSQL es el Rey: Aprovechamos las columnas JSONB para almacenar recursos SCIM dinámicamente. Sin mapeos ORM complejos, solo JSON puro e indexable.
2. Adiós Parsers Pesados: Reemplazamos el runtime de ANTLR con go-dsl, un constructor de parsers ligero y nativo de Go.
3. Rendimiento Primero: Construido sobre Fiber, el motor HTTP más rápido para Go.

🚀 Características Principales

• Filtrado SCIM Nativo: Convierte filtros SCIM (ej: emails[type eq "work"]) directamente en consultas SQL optimizadas para PostgreSQL usando go-dsl.
• Base de Datos Embebida: Incluye una instancia de PostgreSQL embebida (recomendada para desarrollo o proyectos pequeños).
• Base de Datos Externa: Configurable vía config.toml para conectar a clusters PostgreSQL externos en producción.
• Soporte SCIM Completo: Incluye implementación de PATCH, PUT, POST, GET y DELETE.
• Basado en Esquemas: Totalmente configurable vía esquemas JSON (User, Group, EnterpriseUser, etc.).
• Velocidad Viral: Diseñado para manejar altas cargas de peticiones de identidad con latencia mínima.

Funcionalidad	Estado	Especificación RFC
Core Schema (User/Group)	✅ Soportado	RFC 7643
Enterprise Extension	✅ Soportado	RFC 7643
Extensiones Personalizadas	✅ Soportado	Dinámico
Ordenamiento (sortBy)	✅ Soportado	Completo
Filtrado (filter)	✅ Soportado	Avanzado (Anidado)
Patching (PATCH)	✅ Soportado	Add/Remove/Replace
Paginación	✅ Soportado	startIndex/count
Operaciones Masivas	🚧 Roadmap	-

🛠️ Arquitectura: La Ventaja "go-dsl"

Parsear filtros SCIM es difícil. La mayoría de implementaciones usan regex (frágil) o ANTLR (pesado/complejo).

Vorpal usa go-dsl para definir la gramática SCIM en Go puro. Esto nos permite:

• Compilar filtros directamente a cláusulas SQL WHERE de forma segura.
• Manejar anidamiento complejo y operadores lógicos sin la sobrecarga de un parser generado.
• Mantener el binario pequeño y rápido.

graph LR
    Client[Cliente SCIM] -- HTTP/JSON --> Fiber[Servidor Web Fiber]
    Fiber -- Consulta SCIM --> Parser[Parser go-dsl]
    Parser -- Fragmento SQL --> Builder[Constructor SQL]
    Builder -- Consulta Optimizada --> DB[(PostgreSQL JSONB)]
    DB -- Resultado --> Fiber

Loading

⚡ Inicio Rápido

1. Clona el repo

   git clone https://github.com/arturoeanton/go-vorpal-scim.git
   cd vorpal

2. Ejecútalo (Modo DB Embebida)

   go run main.go

   Vorpal levantará automáticamente una instancia local de Postgres en ./data/db.

# config.toml example
[server]
port = ":3000"
app_name = "Vorpal Identity"

[database]
use_embedded = true  # Set false for production
host = "localhost"
user = "vorpal"
password = "secure_password"

🐳 Docker y Docker Compose

Vorpal incluye un archivo docker-compose.yml para ejecutar todo el stack (App PostgreSQL PGAdmin) fácilmente.

1. Iniciar el stack

   docker-compose up --build -d

2. Acceder a los servicios

   • Vorpal API: http://localhost:3000
   • PGAdmin: http://localhost:5050 (Login: [email protected] / admin)
   • PostgreSQL: localhost:5432 (Usuario: vorpal, Pass: secret_password, DB: vorpal_db)

3. Detener el stack

   docker-compose down

🤝 Contribuyendo

Queremos que Vorpal sea el estándar de facto para SCIM en Go. Necesitamos ayuda con:

• Añadir middleware OAuth2/OIDC.
• Mejorar la cobertura de tests.
• Escribir documentación.

¿Encontraste un bug? ¿Tienes una idea? ¡Abre un issue o envía un PR! Construyamos juntos el futuro de la Identidad.