Metadata-Version: 2.4
Name: neptls
Version: 0.2.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: Programming Language :: Python :: 3.14
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, compression,
authentication hooks, hashing/encoding utilities, 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())
```

Client requests automatically advertise and decode `gzip` and `deflate`
responses. Use `stream=True` for incremental response reads:

```python
with neptls.get("https://example.com/large-file", stream=True) as response:
    for chunk in response.iter_bytes(64 * 1024):
        process(chunk)
```

Authentication hooks are explicit and reusable:

```python
from neptls import BasicAuth, BearerAuth

client.get(url, auth=BasicAuth("username", "password"))
client.get(url, auth=BearerAuth("token"))
```

Malformed or transient HTTP transport errors are normalized to
`neptls.RequestError`. Set `retries=2` or another value to retry temporary
network failures and 429/5xx responses.

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)
print(TLSFingerprint.from_config(config).ja3_hash)
```

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())
```

For a real, verified TLS handshake against a host:

```python
fingerprint = neptls.probe_tls("example.com")
print(fingerprint.version, fingerprint.cipher, fingerprint.alpn)
print(fingerprint.metadata["source"])
```

`Client.fingerprint()` describes the configured profile. `probe_tls()` reports
properties negotiated with a real endpoint. They are intentionally different:
the standard-library transport does not claim to reproduce a browser's
private ClientHello byte-for-byte.

## 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 catalog includes common desktop and mobile Chrome, Firefox, Edge,
Safari, and bot strings. It 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, benchmark, solve, solve_parallel

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_parallel(Challenge("demo", difficulty=3, algorithm="sha512"), workers=2)
print(benchmark(Challenge("demo", algorithm="sha256"), attempts=1000))
```

The PoW implementation supports hashlib algorithms such as SHA-256, SHA-512,
SHA-1, BLAKE2, and MD5 for legacy protocol research. It is generic and
intentionally not tied to any anti-abuse or security system.

## Hashing and encoding

All helpers use the standard library:

```python
from neptls.crypto import (
    base32decode, base32encode, digest, hash_file, json_decode,
    json_encode, urlsafe_b64decode, urlsafe_b64encode,
)

print(digest("message", "sha3_256"))
print(hash_file("payload.bin", "sha256"))
token = urlsafe_b64encode("hello")
assert urlsafe_b64decode(token) == b"hello"
assert base32decode(base32encode("hello")) == b"hello"
payload = json_decode(json_encode({"ready": True}))
```

`hash_file()` reads incrementally, so large files do not need to fit in memory.

## 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
```

## Compatibility and transport boundaries

NepTLS 0.2.0 provides a reliable, dependency-free HTTP/1.1 transport with
TLS configuration, ALPN advertisement, cookies, redirects, retries,
compression, and diagnostics. It does not pretend that `urllib` can provide
curl-cffi's native HTTP/2/HTTP/3 stack or byte-identical browser TLS
impersonation. Native HTTP/2 and HTTP/3 transports can be added as optional,
tested backends without changing the public API.

Do not use a profile, user-agent, or fingerprint description to misrepresent
identity or evade a security control. Keep use limited to systems you own or
are authorized to test.

## Development

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
python -m compileall -q src
python -m build --sdist --wheel
```

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. The attached Windows troubleshooting results and the latest
automated counts are maintained in `TEST_REPORT.md`.

## License and credits

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