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:

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

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

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

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