⛰️ ValleyDam

ValleyDam is a lightweight, open protocol for verifying the identity of automated HTTP clients — including AI agents and web scrapers — using DNS-backed cryptographic proof.

It enables a website to verify that a request actually came from bot.openai.com (or your startup’s domain) without API keys, IP allowlists, or complex authentication handshakes.

Today, websites have no reliable way to identify automated clients.

• User-Agent strings are lies
  Anyone can send User-Agent: Googlebot.

• IP blocking is messy
  Legitimate bots often run on shared cloud infrastructure (AWS, GCP).

• API keys don’t scale
  You can’t safely issue and manage API keys for every website on the internet.

The Solution

ValleyDam uses Ed25519 digital signatures anchored in DNS TXT records to create a verifiable, spoof-resistant identity for bots.

How it works

1. The bot signs each request using a private Ed25519 key.
2. The server retrieves the public key from the bot’s DNS record
   (e.g. _agent.yourwebsite.com).
3. The signature is verified. If it matches, the bot’s identity is cryptographically proven.

No central authority. No shared secrets. No API keys.

📦 Installation

pip install valleydam

🚀 Usage

For Web Scrapper or Agent Developers (The Client)

If you are building a scraper or AI agent, use ValleyDamSession to automatically sign outgoing HTTP requests.

1. Generate Your Identity

Run the CLI to generate a private key and receive your DNS TXT record value:

valleydam-gen

Follow the printed instructions to add the TXT record to your domain’s DNS.

2. Use ValleyDam in Your Code

ValleyDam behaves just like the standard Python requests library.

from valleydam import ValleyDamSession

# Initialize your authenticated session
agent = ValleyDamSession(
    domain="yourwebsite.com",                       # Your verified domain
    private_key_path="yourwebsite_com_private.pem"  # Generated in step 1
)

# Make requests as normal — they are now cryptographically signed
response = agent.get("https://protected-website.com/api/data")

print(response.text)

For Website Owners (The Server)

Use theGuide

ValleyDam verifies incoming automated traffic and prevents agent impersonation by validating request signatures against DNS-published public keys.

It runs as middleware and works with Flask, Django, FastAPI, and similar frameworks.

🔒 Hard Validation (Block)

Reject invalid or spoofed requests. Best for protected or agent-only APIs.

from flask import Flask, request, jsonify
from valleydam import verify_request

app = Flask(__name__)

@app.route('/agent-api', methods=['POST'])
def protected_route():
    try:
        verify_request(request)
        identity = request.headers.get('X-ValleyDam-KeyID')
        return jsonify({
            "status": "Welcome",
            "verified_user": identity
        })
    except ValueError as e:
        return jsonify({
            "error": "Access Denied",
            "reason": str(e)
        }), 403

if __name__ == "__main__":
    app.run(port=5000)

📄 Soft Validation (Log Only)

Attempt verification, log results, but allow all traffic.

import logging
from flask import Flask, request, jsonify
from valleydam import verify_request

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

@app.route('/public-api', methods=['GET', 'POST'])
def public_route():
    identity = "Unverified (Anonymous)"

    try:
        verify_request(request)
        identity = request.headers.get('X-ValleyDam-KeyID')
        logging.info(f"Verified request from: {identity}")
    except ValueError as e:
        logging.warning(f"Verification failed: {e}")

    return jsonify({
        "data": "This is public data",
        "your_status": identity
    })

if __name__ == "__main__":
    app.run(port=5000)