docs(i18n): middleware (es)

Author: vishr

site/src/content/docs/es/middleware/basic-auth.md

@@ -0,0 +1,74 @@
+---
+title: Basic Auth
+description: Middleware de autenticación HTTP Basic que valida credenciales de username y password.
+sidebar:
+  order: 1
+---
+
+El middleware Basic Auth proporciona autenticación HTTP basic.
+
+- Para credenciales válidas llama al siguiente handler.
+- Para credenciales ausentes o inválidas, envía una response `401 Unauthorized`.
+
+## Uso
+
+```go
+e.Use(middleware.BasicAuth(func(c *echo.Context, username, password string) (bool, error) {
+	// Use a constant time comparison to prevent timing attacks.
+	if subtle.ConstantTimeCompare([]byte(username), []byte("joe")) == 1 &&
+		subtle.ConstantTimeCompare([]byte(password), []byte("secret")) == 1 {
+		return true, nil
+	}
+	return false, nil
+}))
+```
+
+## Configuración personalizada
+
+```go
+e.Use(middleware.BasicAuthWithConfig(middleware.BasicAuthConfig{}))
+```
+
+## Configuración
+
+```go
+type BasicAuthConfig struct {
+	// Skipper defines a function to skip middleware.
+	Skipper Skipper
+
+	// Validator validates the credentials. If the request contains multiple basic
+	// auth headers, it is called once for each header until the first valid result.
+	// Required.
+	Validator BasicAuthValidator
+
+	// Realm is the realm attribute of the WWW-Authenticate header.
+	// Default value "Restricted".
+	Realm string
+
+	// AllowedCheckLimit sets how many headers are allowed to be checked. This is
+	// useful in environments such as corporate test setups with application proxies
+	// restricting access with their own auth scheme.
+	// Default value 1.
+	AllowedCheckLimit uint
+}
+```
+
+`Validator` tiene esta firma:
+
+```go
+type BasicAuthValidator func(c *echo.Context, user string, password string) (bool, error)
+```
+
+### Configuración por defecto
+
+```go
+// Effective defaults applied when fields are left unset.
+BasicAuthConfig{
+	Skipper: DefaultSkipper,
+	Realm:   "Restricted",
+}
+```
+
+:::caution[Seguridad]
+Compara siempre las credenciales con `subtle.ConstantTimeCompare` para prevenir timing attacks.
+:::

site/src/content/docs/es/middleware/body-dump.md

@@ -0,0 +1,72 @@
+---
+title: Body Dump
+description: Captura payloads de request y response y pásalos a un handler para logging o debugging.
+sidebar:
+  order: 2
+---
+
+El middleware Body Dump captura los payloads de request y response y los pasa a un
+handler registrado. Generalmente se usa para debugging o logging.
+
+:::caution
+Evita Body Dump para payloads grandes, como uploads o downloads de archivos. Si debes usarlo
+en esas rutas, agrega una excepción en la función skipper.
+:::
+
+## Uso
+
+```go
+e := echo.New()
+e.Use(middleware.BodyDump(func(c *echo.Context, reqBody, resBody []byte, err error) {
+	// Handle the request and response bodies.
+}))
+```
+
+## Configuración personalizada
+
+```go
+e := echo.New()
+e.Use(middleware.BodyDumpWithConfig(middleware.BodyDumpConfig{}))
+```
+
+## Configuración
+
+```go
+type BodyDumpConfig struct {
+	// Skipper defines a function to skip middleware.
+	Skipper Skipper
+
+	// Handler receives the request and response payloads and the handler error, if any.
+	// Required.
+	Handler BodyDumpHandler
+
+	// MaxRequestBytes limits how much of the request body to dump. If the request body
+	// exceeds this limit, only the first MaxRequestBytes are dumped and the handler
+	// receives truncated data.
+	// Default: 5 * MB (5,242,880 bytes). Set to -1 to disable limits (not recommended).
+	MaxRequestBytes int64
+
+	// MaxResponseBytes limits how much of the response body to dump. If the response body
+	// exceeds this limit, only the first MaxResponseBytes are dumped and the handler
+	// receives truncated data.
+	// Default: 5 * MB (5,242,880 bytes). Set to -1 to disable limits (not recommended).
+	MaxResponseBytes int64
+}
+```
+
+`Handler` tiene esta firma:
+
+```go
+type BodyDumpHandler func(c *echo.Context, reqBody []byte, resBody []byte, err error)
+```
+
+### Configuración por defecto
+
+```go
+// Effective defaults applied when fields are left unset (Handler is required).
+BodyDumpConfig{
+	Skipper:          DefaultSkipper,
+	MaxRequestBytes:  5 * MB,
+	MaxResponseBytes: 5 * MB,
+}
+```

site/src/content/docs/es/middleware/body-limit.md

@@ -0,0 +1,47 @@
+---
+title: Body Limit
+description: Rechaza requests cuyo body supera un tamaño máximo configurado.
+sidebar:
+  order: 3
+---
+
+El middleware Body Limit establece el tamaño máximo permitido para un body de request. Si el tamaño
+supera el límite configurado, envía una response `413 Request Entity Too Large`.
+
+El límite se aplica tanto al header de request `Content-Length` como al contenido real leído,
+lo que lo hace resistente a headers falsificados. El límite se especifica en bytes.
+
+## Uso
+
+```go
+e := echo.New()
+e.Use(middleware.BodyLimit(2_097_152)) // 2 MB
+```
+
+## Configuración personalizada
+
+```go
+e := echo.New()
+e.Use(middleware.BodyLimitWithConfig(middleware.BodyLimitConfig{}))
+```
+
+## Configuración
+
+```go
+type BodyLimitConfig struct {
+	// Skipper defines a function to skip middleware.
+	Skipper Skipper
+
+	// LimitBytes is the maximum allowed size in bytes for a request body.
+	LimitBytes int64
+}
+```
+
+### Configuración por defecto
+
+```go
+// Effective defaults applied when fields are left unset (Limit is required).
+BodyLimitConfig{
+	Skipper: DefaultSkipper,
+}
+```

site/src/content/docs/es/middleware/casbin-auth.md

@@ -0,0 +1,203 @@
+---
+title: Casbin Auth
+description: Autoriza requests con la biblioteca de control de acceso Casbin usando un middleware personalizado pequeño.
+sidebar:
+  order: 4
+---
+
+[Casbin](https://github.com/casbin/casbin) es una biblioteca de control de acceso open-source
+potente y eficiente para Go. Soporta aplicar autorización en muchos modelos:
+
+- ACL (Access Control List)
+- ACL con superuser
+- ACL sin usuarios, útil para sistemas sin autenticación o log-ins de usuario
+- ACL sin recursos: apunta a un tipo de recurso (por ejemplo `write-article`, `read-log`) en lugar de a uno individual
+- RBAC (Role-Based Access Control)
+- RBAC con roles de recursos: tanto usuarios como recursos pueden tener roles
+- RBAC con dominios/tenants: los usuarios pueden tener conjuntos de roles distintos por dominio/tenant
+- ABAC (Attribute-Based Access Control)
+- RESTful
+- Deny-override: se soportan reglas allow y deny; deny sobrescribe allow
+
+Consulta el [resumen de API](https://casbin.org/docs/api-overview) y la
+[documentación de Casbin](https://casbin.org/docs/) para más detalles.
+
+## Dependencias
+
+```bash
+go get github.com/casbin/casbin/v3
+```
+
+```go
+import (
+	"github.com/casbin/casbin/v3"
+)
+```
+
+## Implementación
+
+Echo no incluye un middleware Casbin; la integración es un wrapper pequeño alrededor del
+enforcer de Casbin:
+
+```go
+// NewCasbinMiddleware returns middleware for Casbin (https://casbin.org/).
+func NewCasbinMiddleware(enforcer *casbin.Enforcer, userGetter func(*echo.Context) (string, error)) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c *echo.Context) error {
+			username, err := userGetter(c)
+			if err != nil {
+				return echo.ErrUnauthorized.Wrap(err)
+			}
+			if pass, err := enforcer.Enforce(username, c.Request().URL.Path, c.Request().Method); err != nil {
+				return echo.ErrInternalServerError.Wrap(err)
+			} else if !pass {
+				return echo.NewHTTPError(http.StatusForbidden, "access denied")
+			}
+			return next(c)
+		}
+	}
+}
+```
+
+## Ejemplo
+
+Crea un archivo de modelo Casbin `auth_model.conf`:
+
+```ini
+[request_definition]
+r = sub, obj, act
+
+[policy_definition]
+p = sub, obj, act
+
+[role_definition]
+g = _, _
+
+[policy_effect]
+e = some(where (p.eft == allow))
+
+[matchers]
+m = g(r.sub, p.sub) && keyMatch(r.obj, p.obj) && (r.act == p.act || p.act == "*")
+```
+
+Crea un archivo de policy Casbin `auth_policy.csv`:
+
+```csv
+p, 1234567890, /dataset1/*, GET
+p, alice, /dataset1/*, GET
+p, alice, /dataset1/resource1, POST
+p, bob, /dataset2/resource1, *
+p, bob, /dataset2/resource2, GET
+p, bob, /dataset2/folder1/*, POST
+p, dataset1_admin, /dataset1/*, *
+g, cathy, dataset1_admin
+```
+
+La autenticación y la autorización son responsabilidades separadas. Autentica al usuario con
+otro middleware (como JWT o Basic Auth), y luego proporciona un `userGetter` para que Casbin
+pueda autorizar el request.
+
+### Con JWT
+
+```go
+e.Use(echojwt.JWT([]byte("secret")))               // JWT middleware does authentication
+jwtUser := func(c *echo.Context) (string, error) { // JWT user getter for Casbin authorization
+	token, err := echo.ContextGet[*jwt.Token](c, "user")
+	if err != nil {
+		return "", err
+	}
+	return token.Claims.GetSubject()
+}
+e.Use(NewCasbinMiddleware(ce, jwtUser)) // Casbin does authorization
+```
+
+Pruébalo con:
+
+```bash
+curl -v "http://localhost:8080/dataset1/any" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"
+```
+
+### Con Basic Auth
+
+```go
+// BasicAuth middleware does authentication
+e.Use(middleware.BasicAuth(func(c *echo.Context, user, password string) (bool, error) {
+	return subtle.ConstantTimeCompare([]byte(user), []byte("alice")) == 1 &&
+		subtle.ConstantTimeCompare([]byte(password), []byte("password")) == 1, nil
+}))
+basicAuthUser := func(c *echo.Context) (string, error) { // Basic auth user getter for Casbin authorization
+	username, _, _ := c.Request().BasicAuth() // password is verified by the BasicAuth middleware above
+	return username, nil
+}
+e.Use(NewCasbinMiddleware(ce, basicAuthUser)) // Casbin does authorization
+```
+
+Pruébalo con:
+
+```bash
+# should pass
+curl -v -u "alice:password" http://localhost:8080/dataset1/any
+# should fail
+curl -v -u "alice:password" http://localhost:8080/dataset2/resource2
+```
+
+### Ejemplo completo de Casbin + JWT
+
+```go
+package main
+
+import (
+	"log/slog"
+	"net/http"
+
+	"github.com/casbin/casbin/v3"
+	"github.com/golang-jwt/jwt/v5"
+	echojwt "github.com/labstack/echo-jwt/v5"
+	"github.com/labstack/echo/v5"
+)
+
+// NewCasbinMiddleware returns middleware for Casbin (https://casbin.org/).
+func NewCasbinMiddleware(enforcer *casbin.Enforcer, userGetter func(*echo.Context) (string, error)) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c *echo.Context) error {
+			username, err := userGetter(c)
+			if err != nil {
+				return echo.ErrUnauthorized.Wrap(err)
+			}
+			if pass, err := enforcer.Enforce(username, c.Request().URL.Path, c.Request().Method); err != nil {
+				return echo.ErrInternalServerError.Wrap(err)
+			} else if !pass {
+				return echo.NewHTTPError(http.StatusForbidden, "access denied")
+			}
+			return next(c)
+		}
+	}
+}
+
+func main() {
+	e := echo.New()
+
+	ce, err := casbin.NewEnforcer("auth_model.conf", "auth_policy.csv")
+	if err != nil {
+		slog.Error("failed to initialize Casbin enforcer", "error", err)
+	}
+
+	e.Use(echojwt.JWT([]byte("secret")))               // JWT middleware does authentication
+	jwtUser := func(c *echo.Context) (string, error) { // JWT user getter for Casbin authorization
+		token, err := echo.ContextGet[*jwt.Token](c, "user")
+		if err != nil {
+			return "", err
+		}
+		return token.Claims.GetSubject()
+	}
+	e.Use(NewCasbinMiddleware(ce, jwtUser)) // Casbin does authorization
+
+	e.GET("/*", func(c *echo.Context) error {
+		return c.String(http.StatusOK, "Hello, World!")
+	})
+
+	if err := e.Start(":8080"); err != nil {
+		e.Logger.Error("failed to start server", "error", err)
+	}
+}
+```