usr 0.1.2

Universal Systems Runtime — experimental C core with Python bindings

usr — Universal Systems Runtime (pre‑release)

⚠️ Pre‑release / Experimental

This project is an early, curiosity‑driven build created to explore low‑level systems programming, binary processing, and cryptography.

It is NOT recommended for production use. This is the first real release after placeholders, published mainly for learning, experimentation, and architectural exploration.

---

✨ Overview

usr (Universal Systems Runtime) is a low‑level systems library written in C, with optional Python bindings, designed to experiment with:

• Binary & byte manipulation
• UTF‑8 / UTF‑16 handling
• Cryptographic primitives (SHA‑256, AES‑256‑IGE)
• Telegram‑style text entities & formatting
• Markdown ⇄ HTML ⇄ Entity round‑tripping
• Performance‑oriented, minimal abstractions

This project exists to understand how real systems libraries are built, not to replace existing production‑grade tools.

---

🧠 Project Philosophy

• Written from scratch in C

• Clear separation between core logic and language bindings

• Focus on determinism, memory ownership, and correctness

• Minimal abstractions, explicit APIs

• Inspired by projects such as:

  • cryptg
  • tgcrypto
  • Telegram MTProto internals

The goal is understanding systems internals, not shipping a black-box dependency.

---

🚧 Current Status

• ✔ Core C library: stable for experimentation
• ✔ Extensive internal tests (round‑trip, fuzz, stress)
• ✔ Python wrapper available (experimental)
• ❌ Not production‑ready
• ❌ Android / Termux has known limitations (documented)

---

📦 Installation

Supported environments

• Linux (native C / Python)
• macOS (native C / Python)
• Android / Termux (C‑only recommended)

Python (experimental)

pip install usr

The wheel bundles a native libusr.so for convenience.

From source (C library)

git clone https://github.com/ankit-chaubey/usr
cd usr
mkdir build && cd build
cmake ..
make

---

🧪 Example Usage (Python)

Below are basic, safe examples intended for learning and experimentation.

1️⃣ Text ⇄ Binary

from usr import from_text, to_text

raw = from_text("Hello usr 🚀")
print(raw)              # b"Hello usr 🚀"

text = to_text(raw)
print(text)             # Hello usr 🚀

This API demonstrates:

• UTF-8 safety
• Binary ownership handling
• Round-trip correctness

---

2️⃣ Hashing (SHA-256)

from usr import sha256

digest = sha256(b"test")
print(digest.hex())

Use this to:

• Verify integrity
• Compare against Python's hashlib

---

3️⃣ AES-256-IGE (Experimental)

from usr import aes256_ige_encrypt, aes256_ige_decrypt

key = b"" * 32
iv  = b""" * 32
msg = b"0123456789ABCDEF0123456789ABCDEF"

enc = aes256_ige_encrypt(msg, key, iv)
dec = aes256_ige_decrypt(enc, key, iv)

print(dec)

⚠️ Important:

• AES via ctypes may abort on Android / Termux
• Works correctly on Linux/macOS
• Prefer pure C or NDK/JNI on Android

---

🗂️ Project Structure

usr/
├── src/                 # C core implementation
│   ├── binary/          # text ⇄ binary
│   ├── bytes/           # buffer utilities
│   ├── crypto/          # SHA256, AES‑256‑IGE
│   ├── entities/        # Telegram‑style entities
│   ├── html/            # HTML ⇄ entity
│   ├── markdown/        # Markdown parser
│   └── utf8/            # UTF‑8 utilities
│
├── include/usr/          # Public C headers
├── python/usr/           # Python bindings (ctypes)
├── tests/                # Round‑trip & fuzz tests
├── examples/             # Usage examples
└── CMakeLists.txt        # Build configuration

---

🧩 Available APIs

🔤 Binary / Text

• from_text(str) -> bytes
• to_text(bytes) -> str

🔐 Cryptography

• sha256(data: bytes) -> bytes
• aes256_ige_encrypt(data, key, iv) (experimental)
• aes256_ige_decrypt(data, key, iv) (experimental)

📝 Text Processing (C‑side)

• UTF‑8 decoding
• Markdown parsing (Telegram‑style)
• HTML ⇄ Entity conversion
• Entity normalization & round‑trip validation

---

📱 Android / Termux Note (Important)

On Android (Termux):

• ❌ ctypes + native crypto may abort due to Bionic tagged‑pointer protection
• ✔ Binary/text APIs work in pure C
• ✔ SHA‑256 works internally

This is a platform limitation, not a logic bug.

Recommended approaches on Android:

• Use pure‑Python fallbacks
• Or integrate the C core via NDK / JNI

This is how mature projects responsibly handle Android.

---

🧪 Testing

This project includes multiple layers of testing designed to validate correctness, not formal security guarantees.

Included tests

• Round-trip tests Validate Markdown → HTML → Entity → HTML stability

• Fuzz tests Randomized Telegram-style inputs with constrained grammar

• Stress tests Allocation, deallocation, and repeated API usage

Running tests (C core)

cd build
ctest

Running Python tests (manual)

python - << 'EOF'
from usr import from_text, to_text, sha256
print(to_text(from_text("test")))
print(sha256(b"test").hex())
EOF

Tests are intentionally conservative and focus on learning behavior rather than adversarial security.

---

👤 Author & Credits

Author: Ankit Chaubey GitHub: https://github.com/ankit-chaubey

This project is:

• Built with curiosity, patience, and care
• Not affiliated with Telegram or any organization

Special thanks to the open-source community and projects like cryptg and tgcrypto for architectural inspiration and reference material.

---

🔗 Repository

This repository is the single source of truth for development, issues, experiments, and documentation.

👉 https://github.com/ankit-chaubey/usr

This repository contains:

• Full source code
• Build scripts
• Tests & experiments
• Documentation and notes

---

🧭 Final Note

This repository represents a learning milestone, not a finished product.

It documents real engineering trade‑offs: ABI boundaries, memory ownership, platform limitations, and performance considerations.

If you are reading this, you are looking at a hands‑on exploration of systems programming, not a polished framework.

Feedback, discussion, and curiosity are always welcome 🤝

This repository represents a learning milestone, not a finished product.

It is intentionally transparent about limitations and trade-offs. If you are reading this, you are looking at a hands-on exploration of systems engineering.

Feedback, discussion, and curiosity are always welcome 🤝