Metadata-Version: 2.4
Name: neptls
Version: 0.1.0
Summary: A dependency-light HTTP client and TLS research toolkit for authorized testing.
Author-email: Diwas Khatri <diwaskhatri07@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/diwaskhatri07/neptls
Project-URL: Repository, https://github.com/diwaskhatri07/neptls
Project-URL: Issues, https://github.com/diwaskhatri07/neptls/issues
Keywords: http,tls,networking,diagnostics,fingerprinting
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# NepTLS

NepTLS is a dependency-light Python HTTP client and TLS research toolkit. It
combines a requests-style API with structured TLS configuration, browser
network profiles, local fingerprint analysis, diagnostics, pools, and a
generic proof-of-work framework.

**Developed by Diwas Khatri (@diwaskhatri07).**

## Security boundary

NepTLS is for networking research, browser compatibility, API testing,
protocol interoperability, performance testing, debugging, authorized
automation, and defensive security research. It is not designed to bypass
CAPTCHAs, authentication, payment security, access controls, or anti-abuse
systems, and it does not include session theft or credential attack features.
Fingerprint objects describe and compare configurations; they do not spoof
browser security signals.

## Installation

```bash
python -m pip install neptls
```

NepTLS has no runtime dependencies and supports Python 3.10+.

## Quick start

```python
import neptls

response = neptls.get("https://example.com", timeout=10)
response.raise_for_status()
print(response.status_code)
print(response.text[:80])
```

Reusable clients retain cookies and configuration:

```python
client = neptls.Client(
    profile="chrome",
    headers={"X-Research-Client": "neptls"},
    retries=2,
)

response = client.post("https://httpbin.org/post", json={"hello": "world"})
print(response.json())
```

Async calls use the same public API:

```python
import asyncio
from neptls import AsyncClient

async def main():
    async with AsyncClient(timeout=10) as client:
        response = await client.get("https://example.com")
        print(response.status_code)

asyncio.run(main())
```

## TLS and profiles

`TLSConfig` creates standard-library `ssl.SSLContext` objects and can be
serialized for experiments:

```python
from neptls import TLSConfig, TLSFingerprint

config = TLSConfig(minimum_version="TLSv1.2", alpn_protocols=("h2", "http/1.1"))
print(config.to_json())
print(TLSFingerprint.from_config(config).digest)
```

Profiles are structured metadata, not browser impersonation:

```python
client = neptls.Client(profile="firefox")
print(client.fingerprint().to_dict())
print(neptls.profiles.get_profile("chrome").to_json())
```

## Fingerprints and user agents

```python
profile = neptls.fingerprint.generate(browser="chrome", platform="windows", seed=7)
print(profile.validate().to_json())
print(neptls.ua.chrome())
print(neptls.user_agents.parse(neptls.ua.random()))
```

The built-in user-agent catalog is intentionally curated. Load a properly
licensed dataset into `UserAgentDatabase` when your application needs a
larger pool; NepTLS does not bundle a copied 40,000-entry third-party list.

## Diagnostics

`inspect()` performs read-only DNS, TCP, TLS, and HTTP observations:

```python
report = neptls.inspect("https://example.com")
print(report["tls"]["version"])
```

## Pools, proxies, hashing, and generic PoW

```python
from neptls import Proxy
from neptls.crypto import sha256
from neptls.pools import Pool
from neptls.pow import Challenge, solve

pool = Pool(["profile-a", "profile-b"])
print(pool.next())
client = neptls.Client(proxy="http://127.0.0.1:8080")
print(sha256("protocol message"))
result = solve(Challenge("demo", difficulty=3))
```

The PoW implementation is generic and intentionally not tied to any
anti-abuse or security system.

## CLI

```bash
neptls version
neptls get https://example.com
neptls inspect https://example.com
neptls profile chrome
neptls ua mobile
neptls hash "protocol message" --algorithm sha256
neptls pow demo --difficulty 3
```

## Development

```bash
python -m unittest discover -s tests -v
python -m compileall -q src
python -m build
```

The project is organized into focused modules for HTTP transport, TLS models,
profiles, fingerprints, user agents, pools, proxy data, diagnostics, crypto,
PoW, and the CLI. Features that depend on native HTTP/2 or HTTP/3 stacks are
kept out of the initial dependency-free release until their transport and
platform behavior can be tested reliably.

## License and credits

NepTLS is released under the MIT License. See `LICENSE`.
