> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# API

## BuildPXConfig()

A function that accepts a configuration in the form of a map and returns a `PxConfig` struct.

```go
func BuildPXConfig(config map[string]interface{}) (*PxConfig, error)
```

* Parameters
  * `map[string]interface{}` - A map representing the desired enforcer configuration
* Returns
  * `*PxConfig` - A pointer to a HUMAN Security configuration struct required for initializing the enforcer
  * `error` - An error that occurred, if any, when building the `PxConfig` struct

## GetPxConfigFromJson()

A function that accepts a string representing the path to a JSON file that contains the enforcer configuration and returns a `PxConfig` struct.

```go
func GetPxConfigFromJson(fileName string) (*PxConfig, error)
```

* Parameters
  * `string` - The path to the configuration JSON file
* Returns
  * `*PxConfig` - A pointer to a HUMAN Security configuration struct required for initializing the enforcer
  * `error` - An error that occurred, if any, when building the `PxConfig` struct

## NewPXConfigBuilder()

A function that returns a new `PXConfigBuilder` that can be used to build a new `PxConfig` struct. Once all the desired configurations are set, call `Build()` to return a pointer to the created `PxConfig` struct.

```go
func NewPXConfigBuilder(configFile map[string]interface{}) *PXConfigBuilder
```

* Parameters
  * `map[string]interface{}` - A map containing only the `px_app_id`, `px_auth_token`, and `px_cookie_secret` required to initialize the `PXConfigBuilder`
* Returns
  * `*PXConfigBuilder` - A pointer to a struct with dedicated setter functions for each configuration value and a `Build()` function that returns the `PxConfig` struct

## CreateDefaultHumanSecurityMiddleware()

A function that returns a middleware that can be applied to route handlers. The returned function should be used as a wrapper for HTTP handler functions, applying the HUMAN enforcement logic prior to invoking the handler.

```go
func CreateDefaultHumanSecurityMiddleware(pxConfig *PxConfig, runtime Runtime) func (http.HandlerFunc) http.HandlerFunc
```

* Parameters
  * `*PxConfig` - A HUMAN Security configuration struct required for initializing the enforcer
  * `Runtime` - An implementation of the Runtime interface
* Returns
  * `func (http.HandlerFunc) http.HandlerFunc` - A middleware function that accepts a handler function and returns the same handler function with HUMAN enforcement applied to it

## NewHumanSecurityEnforcer()

Creates a new instance of the HumanSecurityEnforcer struct with the provided configuration.

```go
func NewHumanSecurityEnforcer(config *PxConfig, runtime Runtime) *HumanSecurityEnforcer
```

* Parameters
  * `*PxConfig` - A pointer to a HUMAN Security configuration struct required for initializing the enforcer
  * `Runtime` - An implementation of the Runtime interface
* Returns
  * `*HumanSecurityEnforcer` - A pointer to a HUMAN Security enforcer struct required for performing enforcement

## HumanSecurityEnforcer

The entity responsible for performing HUMAN enforcement.

### Enforce()

Executes the enforcement functionality. It returns a response, a context, and an error, which dictate how to handle the request.

```go
func (humanSecurityEnforcer *HumanSecurityEnforcer) Enforce(req *http.Request, runtime Runtime) (*http.Response, *PxContext, error)
```

* Parameters
  * `*http.Request` - A pointer to the incoming HTTP request to be evaluated
  * `Runtime` - An implementation of the Runtime interface
* Returns
  * `*http.Response` - A pointer to an HTTP response that should be returned to the client (may be either a first-party or a block response)
  * `*PxContext` - A pointer to a context struct that contains metadata pertaining to the request and the HUMAN decision (e.g., `Score`, `DataEnrichment`, etc.)
  * `error` - An error that occurred, if any, while performing HUMAN enforcement

### PostEnforce()

> **This function is required only for the Credential Intelligence product.**

Parses the response to identify if the login request was successful or not, and sends the `additional_s2s` activity to HUMAN.

```go
func (humanSecurityEnforcer *HumanSecurityEnforcer) PostEnforce(response ResponseWriterWrapper, context *PxContext, runtime Runtime)
```

* Parameters
  * `ResponseWriterWrapper` - A wrapper for the `http.ResponseWriter` that saves the response body in memory for parsing
  * `*PxContext` - A pointer to a context struct that contains metadata pertaining to the request and the HUMAN decision (e.g., `Score`, `DataEnrichment`, etc.)
  * `Runtime` - An implementation of the Runtime interface
* Returns nothing

## ShouldSetPxhd()

A utility function that indicates whether or not the PXHD cookie should be set on the response.

```go
func ShouldSetPxhd(context *PxContext) bool
```

* Parameters
  * `*PxContext` - A pointer to a context struct that contains metadata pertaining to the request and the HUMAN decision (e.g., `Score`, `DataEnrichment`, etc.)
* Returns
  * `bool` - Whether the PXHD cookie should be added as a `Set-Cookie` header on the HTTP response

## GetPxhdCookie()

Returns the PXHD cookie that should be added to the HTTP response. Should only be called if `ShouldSetPxhd()` returns `true`.

```go
func GetPxhdCookie(context *PxContext) http.Cookie
```

* Parameters
  * `*PxContext` - A pointer to a context struct that contains metadata pertaining to the request and the HUMAN decision (e.g., `Score`, `DataEnrichment`, etc.)
* Returns
  * `http.Cookie` - The PXHD cookie as an `http.Cookie` struct

## NewResponseWriterWrapper()

Wraps the provided `http.ResponseWriter` in a struct that stores the response data in-memory so it can be queried by the `PostEnforce()` function after the response has been returned to the client.

```go
func NewResponseWriterWrapper(w http.ResponseWriter) ResponseWriterWrapper
```

* Parameters
  * `http.ResponseWriter` - The entity used by the HTTP handler to construct a response
* Returns
  * `ResponseWriterWrapper` - A struct that implements the `http.ResponseWriter` interface and preserves the response data