> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verity.usher.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

The Verity Prover is a proxy server that enables you to generate cryptographic proofs for API interactions. It acts as a middleware between your application and target APIs, allowing you to prove specific aspects of the request/response cycle while selectively redacting sensitive information.

# Key Concepts

## Request ID

Every proof generation requires a unique Request ID (UUID) to track and retrieve the proof. You can generate one using:

```bash theme={null}
uuidgen
```

## Proof Subscription

Proofs are delivered asynchronously via Server-Sent Events (SSE). You'll need to establish a connection to receive proofs as they're generated.

## Core Endpoints

### Proxy Endpoint (`/proxy`)

This endpoint forwards your requests to target APIs while generating proofs.
You can use any HTTP method to call this endpoint, such as GET, POST, PUT, DELETE, etc.

#### Required Headers:

* `T-PROXY-URL`: The target API URL you want to call
* `T-REQUEST-ID`: Your generated UUID for tracking the proof
* `T-REDACTED` (optional): Comma-separated list of fields to redact
* `T-PROVE-FAILED-REQ` (optional): If set to true, the proof will be generated even if the request fails

#### Redaction Syntax:

The `T-REDACTED` header allows you to specify which parts of the request and response should be redacted from the generated proofs. Understanding the syntax is crucial for effectively protecting sensitive information while maintaining the integrity of your proofs. Below is a detailed explanation of each redaction pattern you can use:

* **`req:body:fieldName`**\
  *Redact a specific field in the request body.*\
  Replace `fieldName` with the exact name of the field you want to redact.\
  **Example:**\
  `req:body:password`\
  This will redact the `password` field from the request body.

* **`req:header:headerName`**\
  *Redact a specific header in the request.*\
  Replace `headerName` with the name of the header you wish to redact.\
  **Example:**\
  `req:header:Authorization`\
  This will redact the `Authorization` header from the request.

* **`res:body:fieldName`**\
  *Redact a specific field in the response body.*\
  Replace `fieldName` with the name of the field you want to redact.\
  **Example:**\
  `res:body:creditCardNumber`\
  This will redact the `creditCardNumber` field from the response body.

* **`res:header:headerName`**\
  *Redact a specific header in the response.*\
  Replace `headerName` with the name of the header you wish to redact.\
  **Example:**\
  `res:header:Set-Cookie`\
  This will redact the `Set-Cookie` header from the response.

* **`res:query:queryName`**\
  *Redact a specific query parameter in the response URL.*\
  Replace `queryName` with the name of the query parameter you want to redact.\
  **Example:**\
  `res:query:userId`\
  This will redact the `userId` query parameter from the response URL.

* **`res:path:PathIndex`**\
  *Redact a specific segment of the response URL path based on its position.*\
  Replace `PathIndex` with the numerical position of the path segment you wish to redact, starting from 1.\
  **Example:**\
  `res:path:2`\
  If the response URL is `https://api.example.com/users/12345/profile`,\
  `res:path:2` will redact `12345` from the path.

* **`search:substring`**\
  *Redact all occurrences of a specific substring within the response.*\
  Replace `substring` with the exact phrase or word you want to redact.\
  **Example:**\
  `search:secret`\
  This will redact every instance of the word "secret" in the response content.

**Usage Tips:**

* **Combining Multiple Redactions:** You can specify multiple redaction patterns by separating them with commas.\
  **Example:**\
  `res:body:id,req:header:Authorization,search:password`

* **Order Matters:** The redactions are applied in the order they are specified. Ensure that more general redactions (like `search`) do not inadvertently redact intended data.

* **Testing Redactions:** Before deploying, test your redaction patterns to ensure they effectively hide the desired information without affecting other parts of the data.

### Proof Subscription (`/proof/{requestId}`)

Subscribe to receive proofs for a specific request ID via SSE.

#### Basic POST Request

```bash theme={null}
curl http://localhost:8080/proxy -X POST \
-H "T-PROXY-URL: https://jsonplaceholder.typicode.com/posts?search=john_dohn&type=agent&userId=1224" \
-H "T-REDACTED: res:body:id,req:body:userId,res:query:userId,search:title,req:header:x-api-key,res:path:1" \
-H "T-REQUEST-ID: <your-uuid>" \
-H "Content-Type: application/json" \
-d '{"title": "Example", "userId": 1}'
```

#### Simple GET Request

```bash theme={null}
curl http://localhost:8080/proxy -X GET \
-H "T-PROXY-URL: https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd" \
-H "T-REQUEST-ID: <your-uuid>" \
-H "Content-Type: application/json"
```

#### Subscribing to Proofs

```bash theme={null}
curl -N http://localhost:8080/proof/<your-uuid>
```

## Best Practices

1. **Always Generate Fresh UUIDs**: Use a new UUID for each proof request to avoid collisions.
2. **Subscribe First**: Set up your SSE connection before making the proxy request.
3. **Handle Timeouts**: Implement appropriate timeout handling for both proxy requests and SSE connections.
4. **Redact Sensitive Data**: Use the `T-REDACTED` header to protect sensitive information from TLS proofs while maintaining proof validity.
5. **Error Handling**: The API uses standard HTTP status codes:
   * 200: Successful request
   * 400: Bad request (invalid headers or body)
   * 404: Target API not found
   * 500: Server error