# wc32

A custom Python encoding library with optional salt support for non-deterministic output.

## Installation

```bash
pip install wc32
```

## Usage

### Basic Encoding/Decoding

```python
from wc32 import encode, decode

# Encode with a key (deterministic - same input always produces same output)
encoded = encode("Hello, World!", "my_secret_key")
print(encoded)  # e.g., "kR.TV.rx.r-.yU.mD.Hj"

# Decode with the same key
decoded = decode(encoded, "my_secret_key")
print(decoded)  # "Hello, World!"
```

### Non-Deterministic Encoding (Recommended)

By default, encoding is deterministic (same text + key = same output). For security, you can enable random salt:

```python
# With random salt (recommended for sensitive data)
encoded = encode("Hello", "key", salt=True)
# Each call produces different output:
#   "a1b2c3d4.e5f6.g7h8.i9j0.k1l2"  (first call)
#   "f5e6d7c8.9a0b.1c2d.3e4f.5g6h"  (second call)

# Decode works automatically (salt is embedded in encoded string)
decoded = decode(encoded, "key")  # "Hello"
```

### Custom Salt

You can provide your own salt for reproducible non-deterministic output:

```python
# Custom salt (must be 8-32 hex characters)
encoded = encode("Hello", "key", salt="deadbeef12345678")
decoded = decode(encoded, "key")  # "Hello"
```

## API Reference

### encode(text: str, key: str, salt: Union[bool, str] = False) -> str

Encodes text using a custom base encoding with optional salt.

- **text**: The string to encode
- **key**: Secret key for encoding
- **salt**: 
  - `False` (default): Deterministic encoding
  - `True`: Generate random salt
  - `str`: Use custom hex salt (8-32 characters)

### decode(encoded_text: str, key: str) -> str

Decodes previously encoded text.

- **encoded_text**: The encoded string
- **key**: Must match the key used for encoding

## Error Handling

The library raises descriptive errors for invalid inputs:

```python
from wc32 import encode, decode

# Empty key
encode("text", "")  # ValueError: Key must not be empty

# Wrong key (produces garbage, not an error)
decode(encoded, "wrong_key")  # Returns garbled text

# Invalid characters
decode("invalid!!!", "key")  # ValueError: Invalid character
```

## Security Notes

- This is **not** encryption. It provides obfuscation only.
- Without salt, output is deterministic - don't use for sensitive data without salt.
- With `salt=True`, same text produces different outputs (semantically secure).
- For proper security, use established encryption libraries like `cryptography`.
