security

type JwtResponse struct {
	Token   string `json:"token"`
	Expires int    `json:"expires"`
}

type ResourceAccessValidation[T goservectx.Principal] interface {

	// HasResourceAccess wraps the given HTTP handler to enforce resource access control.
	//
	// This middleware checks if the request is accessing a public path or if the user has the required roles
	// for the requested resource. If access is granted, the request proceeds to the next handler. Otherwise,
	// it returns access denied response.
	//
	// Parameters:
	//   - next: The next http.Handler in the chain to call if access is granted.
	//
	// Returns:
	//   - http.Handler: A handler that wraps the provided handler with access control
	HasResourceAccess(next http.Handler) http.Handler

	// HasResourceAccessRight checks if the user has the necessary roles to access the requested resource.
	// It compares the roles assigned to the user with those required for the resource's path.
	// If the path does not require any roles, the function returns true.
	//
	// Parameters:
	//
	//	ctx - The API request context containing user roles and request metadata.
	//
	// Returns:
	//
	//	bool - True if the user has the required roles or if the path does not require roles, false otherwise.
	HasResourceAccessRight(ctx goservectx.Request[T]) bool
}

type Service[T goservectx.Principal] interface {
	jwt.Service[T]
	ResourceAccessValidation[T]

	// AuthorizationHandler
	// This method is invoked to handle API requests and manage security validation processes.
	// It determines whether the request can proceed further (doNext) based on:
	// 1. Whether the request is made to a public path.
	// 2. The success of the JWT token validation process, which involves:
	//   - Principal extraction.
	//   - Validation of token claims.
	//   - Ensuring proper API authorization.
	//
	// Parameters:
	// - ctx: The Request containing the context information for the API request.
	//
	// Returns:
	// - `true` (doNext) if the request is allowed to continue processing.
	// - `false` if the request fails validation or is unauthorized.
	//
	// Notes:
	// - This function leverages methods like Validation and IsPublicPath to make security decisions.
	// - Ensure that all sensitive operations and data are securely processed.
	// - Public paths bypass validation by default, so it's critical to properly define such paths to avoid security issues.
	AuthorizationHandler(ctx *goservectx.Request[T]) (doNext bool)
}