A system that allows only authorized autonomous agents to pass verification challenges. Agents are authenticated through a combination of strong identity binding, reasoning challenges, autonomy attestation, replay protection, and verifiable work.

Quick Start • Architecture • Security • API • Production • Contributing

Agent-Only Access Gate (AOG) is an open-source access control layer designed for environments where you must distinguish trusted, autonomous software agents from interactive humans and generic clients.

AOG enforces a strict request flow:

1. A trusted agent proves identity (mTLS or trusted proxy forwarding).
2. The server issues a one-time verification challenge (reasoning-based or computational).
3. The agent solves the challenge and provides autonomy attestation.
4. The server verifies the solution, autonomy claims, timing, identity binding, and consumes the nonce to prevent replay.

The design prioritizes reasoning verification, autonomy attestation, replay resistance, and operational readiness.

• Reasoning-based challenges requiring semantic understanding and problem-solving capabilities.
• Autonomy attestation validation to verify continuous autonomous operation.
• Client identity binding via mutual TLS (mTLS) or trusted proxy header forwarding.
• Redis-backed nonce lifecycle, replay protection, and rate limiting.
• Constant-time comparison for submitted results.
• Prometheus metrics endpoint for monitoring and alerting.
• Modular structure (server, client, infra).
• Test suite covering unit, integration, and stress scenarios.
• Backward compatibility with legacy computational challenges.

• server/
  FastAPI backend, validation, Redis-backed state, and Prometheus metrics.

• client/
  Reference agent client showing mTLS usage, challenge solving, and submission flow.

• infra/
  Nginx configuration, Dockerfiles, and docker-compose for local or staged deployments.

• scripts/
  Development utilities such as certificate generation.

• tests/
  Unit, integration, and stress tests.

• docs/
  Architecture and operational guidance, hardening notes, and design references.

• Docker and Docker Compose (recommended for local evaluation)
• OpenSSL (for generating a development HMAC secret and dev certificates)

git clone https://github.com/ferasshita/AOG.git
cd AOG

cd scripts
chmod +x gen_certs.sh
./gen_certs.sh
cd ..

cd infra
HEADER_HMAC_SECRET="$(openssl rand -hex 32)" docker-compose up --build

Notes:

• Nginx listens on host port 8443 (HTTPS + mTLS, depending on configuration).
• The backend connects to Redis and exposes Prometheus metrics at /metrics.

pytest -q

• Issues one-time challenges (reasoning or computational)
• Validates and consumes submissions
• Verifies autonomy attestation claims
• Stores ephemeral and replay-prevention state in Redis
• Exposes Prometheus metrics

• Authenticates via client certificates (mTLS)
• Requests challenges
• Solves reasoning challenges using semantic analysis and problem-solving
• Generates autonomy attestation with operation tracking
• Submits result with runtime metadata and attestation token

• Nginx (or a cloud load balancer) terminates TLS/mTLS
• For deployments that forward client identity via headers, a signing mechanism is used to authenticate forwarded values

AOG implements a multi-layered verification approach combining cryptographic identity, reasoning challenges, and autonomy attestation to authenticate autonomous agents.

AOG supports:

• Mutual TLS (recommended where possible)
• Trusted proxy header forwarding, with authenticity protection (HMAC-signed forwarding) when mTLS terminates upstream

• Semantic analysis of code patterns and design principles
• Logic reasoning and problem-solving tasks
• Context understanding and system design questions
• Requires AI-specific capabilities for solving

• Continuous operation time tracking
• Autonomous action logging
• Decision chain evidence
• System behavior validation

• Computational challenges for backward compatibility
• Deterministic iterative hashing
• Maintained for transition support

Challenges are bound to:

• A server-issued nonce
• A strict deadline
• A client identity/fingerprint
• Challenge-specific parameters (question, seed, etc.)

• Challenges are stored in Redis with TTL.
• Nonces are consumed atomically and marked as used.
• Replay attempts are rejected deterministically.

• The server validates reasoning answers using constant-time comparison
• Autonomy attestation is verified for completeness and validity
• Result verification uses cryptographic techniques to reduce timing side channels

• Distributed rate limiting can be enforced via Redis, protecting against brute force and excessive challenge issuance.

AOG can accept an agent-provided attestation token (for example, a JWT) and includes integration hooks for:

• Agent key-based signatures
• Hardware attestation (TPM, SGX) or cloud attestation services

Issues a one-time verification challenge.

• Requires trusted client identity (mTLS or verified forwarded identity)
• Query parameters:
  • challenge_type: "reasoning" (default) or "legacy"
• Returns JSON:
  • nonce
  • challenge_type
  • question (for reasoning challenges)
  • seed (for all challenges)
  • iterations (for legacy challenges)
  • deadline_ts
  • issued_at

Submits a solved challenge.

• Body fields:
  • nonce
  • challenge_type
  • answer (for reasoning challenges)
  • result_hash (for legacy challenges)
  • runtime_ms
  • client_fingerprint
  • autonomy_attestation (for reasoning challenges)
  • trace_hash (optional)
  • attestation (optional)

Validation includes:

• Challenge existence and freshness
• Client binding and identity checks
• Deadline enforcement
• Answer verification (reasoning) or hash verification (legacy)
• Autonomy attestation validation (reasoning)
• Runtime bounds checks (policy dependent)
• Optional JWT attestation verification
• Atomic nonce consumption

Prometheus exposition endpoint.

• Use scripts/gen_certs.sh to generate local development certificates.
• Development certificates are for local testing only.

Do not use development certificates in production.

Recommended practices:

• Use an enterprise PKI (Vault PKI, step-ca, or managed CA)
• Prefer short-lived certificates with automated rotation
• Enforce certificate revocation (CRL/OCSP) where applicable
• Store secrets (for example HEADER_HMAC_SECRET) in a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager, etc.)

• Prometheus metrics are exposed via /metrics.
• Integrate with Grafana dashboards and alerting policies.
• Ensure logs are structured and redact sensitive values (nonces, seeds, private keys, credentials).

• Use a secure PKI and rotate keys regularly.
• Enforce mTLS end-to-end or ensure forwarded identity headers are cryptographically authenticated.
• Run Redis in a highly-available configuration where required.
• Enforce strict TLS configuration at the edge (modern ciphers, TLS 1.2+ or TLS 1.3, HSTS where applicable).
• Add certificate revocation handling (CRL/OCSP) and operational processes.
• Implement robust rate limiting and anomaly detection.
• Perform adversarial testing and load/stress testing before deployment.
• Separate duties and secure CI/CD secrets and signing keys.

pip install -r requirements.txt

• Unit tests:

pytest tests/unit

• Integration tests:

pytest tests/integration

• Stress tests:

pytest tests/stress

Contributions are welcome.

Suggested workflow:

1. Fork the repository and create a feature branch.
2. Add tests for functional changes.
3. Ensure all tests pass locally.
4. Submit a pull request with a clear description and rationale.

If you are proposing security-sensitive changes, include a short threat analysis and expected operational impact.

This project is licensed under the MIT License. See the LICENSE file for details.

For design questions, threat modeling or open an issue or start a discussion in the repository.

Repository owner:

• GitHub: https://github.com/ferasshita