neptls 0.1.0__tar.gz

neptls-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diwas Khatri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neptls-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+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`.

neptls-0.1.0/README.md

@@ -0,0 +1,155 @@
+# 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`.

neptls-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neptls"
+version = "0.1.0"
+description = "A dependency-light HTTP client and TLS research toolkit for authorized testing."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Diwas Khatri", email = "diwaskhatri07@users.noreply.github.com" }]
+keywords = ["http", "tls", "networking", "diagnostics", "fingerprinting"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/diwaskhatri07/neptls"
+Repository = "https://github.com/diwaskhatri07/neptls"
+Issues = "https://github.com/diwaskhatri07/neptls/issues"
+
+[project.scripts]
+neptls = "neptls.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+neptls = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

neptls-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neptls-0.1.0/src/neptls/__init__.py

@@ -0,0 +1,52 @@
+"""NepTLS: an HTTP client and TLS research toolkit.
+
+Developed by Diwas Khatri (@diwaskhatri07).
+"""
+
+from .async_client import AsyncClient
+from .client import Client, delete, get, head, options, patch, post, put, request
+from .diagnostics import diagnose, inspect
+from .exceptions import HTTPStatusError, NepTLSError, RequestError, TimeoutError
+from .fingerprints import ClientFingerprint
+from .models import RequestTiming, Response
+from .profiles import BrowserProfile, PROFILES, get_profile
+from .proxy import Proxy
+from .tls import TLSConfig, TLSFingerprint
+from . import crypto, fingerprints as fingerprint, profiles, pow, user_agents
+from .user_agents import ua
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncClient",
+    "BrowserProfile",
+    "Client",
+    "ClientFingerprint",
+    "HTTPStatusError",
+    "NepTLSError",
+    "PROFILES",
+    "Proxy",
+    "RequestError",
+    "RequestTiming",
+    "Response",
+    "TLSConfig",
+    "TLSFingerprint",
+    "TimeoutError",
+    "crypto",
+    "delete",
+    "diagnose",
+    "fingerprint",
+    "get",
+    "get_profile",
+    "head",
+    "inspect",
+    "options",
+    "patch",
+    "post",
+    "pow",
+    "profiles",
+    "put",
+    "request",
+    "ua",
+    "user_agents",
+]

neptls-0.1.0/src/neptls/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

neptls-0.1.0/src/neptls/async_client.py

@@ -0,0 +1,52 @@
+"""Async API backed by the same tested synchronous transport."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .client import Client
+from .models import Response
+
+
+class AsyncClient:
+    """An asyncio-friendly client with a persistent cookie/profile session."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._client = Client(**kwargs)
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> Response:
+        return await asyncio.to_thread(self._client.request, method, url, **kwargs)
+
+    async def get(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("GET", url, **kwargs)
+
+    async def post(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("POST", url, **kwargs)
+
+    async def put(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("PUT", url, **kwargs)
+
+    async def patch(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("PATCH", url, **kwargs)
+
+    async def delete(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("DELETE", url, **kwargs)
+
+    async def head(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("HEAD", url, **kwargs)
+
+    async def options(self, url: str, **kwargs: Any) -> Response:
+        return await self.request("OPTIONS", url, **kwargs)
+
+    def fingerprint(self):
+        return self._client.fingerprint()
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self._client.close)
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

neptls-0.1.0/src/neptls/cli.py

@@ -0,0 +1,76 @@
+"""Command-line interface for NepTLS."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from . import __version__, get, profiles, ua
+from .crypto import blake2, md5, sha256, sha512
+from .diagnostics import inspect
+from .pow import Challenge, solve
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="neptls", description="NepTLS networking research toolkit")
+    sub = parser.add_subparsers(dest="command")
+    for method in ("get", "post", "put", "patch", "delete", "head", "options"):
+        command = sub.add_parser(method, help=f"perform an HTTP {method.upper()} request")
+        command.add_argument("url")
+        command.add_argument("--json", dest="json_body", help="JSON request body")
+        command.add_argument("--header", action="append", default=[], metavar="NAME:VALUE")
+    for name in ("inspect", "diagnose"):
+        command = sub.add_parser(name, help="inspect DNS, TCP, TLS, and HTTP")
+        command.add_argument("url")
+        command.add_argument("--json", action="store_true", dest="as_json")
+    sub.add_parser("version")
+    profile_command = sub.add_parser("profile", help="list browser profiles")
+    profile_command.add_argument("name", nargs="?")
+    ua_command = sub.add_parser("ua", help="query the user-agent catalog")
+    ua_command.add_argument("kind", nargs="?", default="random", choices=("random", "chrome", "firefox", "mobile"))
+    hash_command = sub.add_parser("hash", help="hash text")
+    hash_command.add_argument("value")
+    hash_command.add_argument("--algorithm", choices=("sha256", "sha512", "blake2", "md5"), default="sha256")
+    pow_command = sub.add_parser("pow", help="solve a generic proof-of-work challenge")
+    pow_command.add_argument("payload")
+    pow_command.add_argument("--difficulty", type=int, default=4)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "version":
+        print(__version__)
+        return 0
+    if args.command in {"get", "post", "put", "patch", "delete", "head", "options"}:
+        headers = dict(item.split(":", 1) for item in args.header if ":" in item)
+        body = json.loads(args.json_body) if args.json_body else None
+        response = getattr(__import__("neptls"), args.command)(args.url, headers=headers, json=body)
+        print(response.text)
+        return 0 if response.ok else 1
+    if args.command in {"inspect", "diagnose"}:
+        print(json.dumps(inspect(args.url), indent=2, default=str))
+        return 0
+    if args.command == "profile":
+        value = profiles.PROFILES if not args.name else profiles.get_profile(args.name).to_dict()
+        print(json.dumps(value, indent=2, default=str))
+        return 0
+    if args.command == "ua":
+        print(getattr(ua, args.kind)())
+        return 0
+    if args.command == "hash":
+        function = {"sha256": sha256, "sha512": sha512, "blake2": blake2, "md5": md5}[args.algorithm]
+        print(function(args.value))
+        return 0
+    if args.command == "pow":
+        result = solve(Challenge(args.payload, difficulty=args.difficulty))
+        print(json.dumps(asdict(result), default=str))
+        return 0
+    _parser().print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())