Metadata-Version: 2.4
Name: kshell
Version: 1.2.1
Summary: Pure Python SSH Server & Client Framework with Cloudflare Tunnel Support by Niranjan
Author: Niranjan Kumar K
License-Expression: MIT
Keywords: ssh,paramiko,terminal,remote,shell,cloudflare,tunnel
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko>=3.5.0
Dynamic: license-file

# KShell

**Version 1.2.1**

KShell is a complete, pure-Python SSH server and client framework. It provides secure remote shells, command execution, SFTP file transfer, and built-in automatic Cloudflare Tunnel public access support through a simple, unified API.

## About

- **Developer**   : Niranjan Kumar K
- **Organization** : KNI (K programming / KNI OS)
- **Role**         : Father of K programming and KNI OS
- **Version**      : 1.2.1
- **Language**     : Python

KShell is the flagship SSH framework of the KNI ecosystem, created and maintained by Niranjan Kumar K. It provides a complete, pure-Python SSH server and client implementation that enables secure remote shells, command execution, SFTP file transfer, and zero-configuration public tunneling with a simple, consistent API.

KNI is the organization behind the K programming language and the KNI operating system. As the father of K programming and KNI OS, Niranjan Kumar K leads the design and development of the K language runtime, the KNI OS kernel, and the KShell remote access tool.

KShell integrates with KNI OS as its default remote access layer, giving administrators and developers a unified, secure way to manage KNI systems locally or over public Cloudflare tunnels.

## Core Modules & Features

- **Server Module**      : Multi-threaded SSH server with RSA host keys supporting local mode (`mode="local"`) and automated Cloudflare public tunnel mode (`mode="public"`).
- **Client Module**      : SSH client with a unified `connect()` method that automatically auto-detects local IPs vs public tunnel URLs, featuring exec, shell, and SFTP support.
- **Auto-Cloudflared**  : Automatic cross-platform resolution and binary download for Cloudflare Tunnel (`cloudflared`) on Windows, Linux, and macOS.
- **Session Layer**      : Per-connection ClientSession with queued I/O.
- **Error System**       : Typed exception hierarchy (KShellError and subtypes).
- **Cross-Platform**     : Native PTY support on POSIX and ConPTY on Windows.

## Installation

Install the required dependency:

```bash
pip install kshell
```

## Quick Start

### Show Help and About

```python
import kshell

kshell.help('about')
kshell.help('version')
kshell.help('server')
kshell.help('client')
```

### Local SSH Server Example

```python
import kshell

# Start server in local mode (default)
server = kshell.Server(port=1514, username='admin', password='1234', mode='local')
server.start()

# Check server status
print(server.status())
```

**Startup Dashboard Display (Local Mode):**

```
====================================================================
  KSHELL SERVER RUNNING
====================================================================
Mode:           LOCAL
Local:          0.0.0.0:1514
Public:         N/A
Authentication: username/password
Tunnel:         None
Status:         ACTIVE
====================================================================
```

### Public SSH Server Example (Cloudflare Tunnel)

```python
import kshell

# Start server in public mode (automatically manages Cloudflare tunnel)
server = kshell.Server(port=1514, username='admin', password='1234', mode='public')
server.start()

# Retrieve public URL and server status programmatically
status = server.status()
print('Public URL:', status['tunnel_url'])
```

**Startup Dashboard Display (Public Mode):**

```
====================================================================
  KSHELL SERVER RUNNING
====================================================================
Mode:           PUBLIC
Local:          localhost:1514
Public:         https://xxxx-xxxx-xxxx.trycloudflare.com
Authentication: username/password
Tunnel:         Cloudflare
Status:         ACTIVE
====================================================================
```

### Unified Client Connection Example

The `client.connect()` method automatically detects whether a local IP/port or a public tunnel URL is provided:

```python
import kshell

client = kshell.Client()
try:
    # 1. Connect to local SSH server
    client.connect('127.0.0.1', 1514, 'admin', '1234')

    # 2. Or connect to a public Cloudflare tunnel URL automatically
    # client.connect('https://xxxx-xxxx-xxxx.trycloudflare.com', username='admin', password='1234')

    stdout, stderr, exit_code = client.execute('whoami')
    print('Result:', stdout.strip())
except kshell.KShellError as e:
    print(f'Connection failed: {e}')
finally:
    client.disconnect()
```

## Available Help Topics

- `kshell.help('about')`    : Developer, organization, and project info
- `kshell.help('server')`   : Server options, local/public modes, lifecycle & status()
- `kshell.help('client')`   : Client usage, connect() (supports local & public URLs), shell & SFTP
- `kshell.help('errors')`   : Custom exception classes and error handling
- `kshell.help('examples')` : Copy-pasteable workflow code snippets
- `kshell.help('version')`  : Version information

## Custom Error Classes

Standard Python and SSH exceptions are caught and raised as custom KShell errors:

- `kshell.KShellError`         : Base class for all kshell exceptions.
- `kshell.AuthenticationError` : Raised on invalid username or password.
- `kshell.ConnectionError`     : Raised when network or socket fails.
- `kshell.ServerError`         : Server startup, binding, tunnel creation, or thread failure.
- `kshell.ClientError`         : Shell, channel, tunnel URL, or disconnected client errors.
- `kshell.SFTPError`           : File transfer failure (permissions, path).

### Handling Example

```python
import kshell

try:
    client.connect('127.0.0.1', 1514, 'user', 'wrong_pass')
except kshell.AuthenticationError as e:
    print(f'Auth Failed: {e}')
except kshell.KShellError as e:
    print(f'General KShell Exception: {e}')
```

## License

KShell is licensed under the **MIT License**.

```
MIT License

Copyright (c) Niranjan Kumar K / KNI

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