Metadata-Version: 2.4
Name: km-keybind
Version: 1.0.0
Summary: Stateless encrypted identity-bound token library
Author: Pravanjan Roy
Project-URL: Homepage, https://github.com/kingmon6996/keybind
Project-URL: Repository, https://github.com/kingmon6996/keybind
Project-URL: Issues, https://github.com/kingmon6996/keybind/issues
Keywords: km-keybind,keybind,encrypted-token,identity-bound,stateless-token,cryptography
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography
Requires-Dist: PyNaCl
Requires-Dist: zstandard
Requires-Dist: blake3
Requires-Dist: orjson
Requires-Dist: typing-extensions
Dynamic: license-file

# Keybind

Keybind is a Python library for turning JSON-compatible data and files into compact, encrypted, identity-bound tokens. It is useful when you want to send or store structured data or file payloads in a self-contained form without keeping server-side state.

## What Keybind is for

You can use Keybind when you need to:

- create a compact token from a dictionary or other JSON-compatible object
- bind that token to a specific user or application context
- keep the payload encrypted and self-contained
- safely pass the token across systems or store it for later use

Typical use cases include:

- temporary session payloads
- encrypted user profile fragments
- backend-to-backend message transport
- short-lived access tokens with embedded data
- compact state handoff between services

## The master key

The master key is the secret value that unlocks and protects the token. It is supplied when you create a Keybind instance:

```python
from keybind import Keybind

chain = Keybind(b"master-key")
```

In real projects, use a strong secret instead of a sample string. A good master key should be:

- long enough to be unpredictable
- stored securely
- kept private
- reused consistently for the same application context

### How to generate a master key

A simple and safe approach is to generate a random 32-byte key:

```python
import os

master_key = os.urandom(32)
chain = Keybind(master_key)
```

You can also store it in an environment variable:

```python
import os

master_key = os.environ["KEYBIND_MASTER_KEY"].encode("utf-8")
chain = Keybind(master_key)
```

### Why the master key matters

- It is the root secret used to derive the encryption key.
- The same key must be used later when decoding the token.
- If the master key changes, the token cannot be decrypted correctly.

## Identities

Keybind also takes two identity values during encoding and decoding:

```python
from keybind.keybind import DICT

token = chain.encode("user123", "app", DICT, {"hello": "world"})
chain.decode("user123", "app", token)
```

These identities bind the token to a specific context. In practice:

- the first identity is often a user, account, or subject
- the second identity is often an app, service, or environment

This means the token is not only encrypted, but also tied to the identities used when it was created.

## Full example

Here is a complete example from start to finish:

```python
from keybind import Keybind
from keybind.keybind import DICT

master_key = b"example-master-key"
chain = Keybind(master_key)

payload = {
    "user": "alice",
    "role": "admin",
    "permissions": ["read", "write"],
    "active": True,
}

token = chain.encode("alice", "dashboard", DICT, payload)
print("Token:", token)

decoded, decoded_type = chain.decode("alice", "dashboard", token)
print("Decoded:", decoded)
print("Decoded type:", decoded_type)
```

### What happens in this example

1. A Keybind instance is created with a master key.
2. A JSON-compatible payload is prepared.
3. The payload is turned into an encrypted token.
4. The token is later decoded back into the original object.

## How the library works internally

Keybind now supports file payloads via the `FILE` payload type. When you encode a file path, the raw file contents are encrypted and later decoded to a saved file path under `decoded_files/`, preserving the original filename.

```python
from keybind import Keybind
from keybind.keybind import FILE

chain = Keybind(b"example-master-key")

token = chain.encode("alice", "dashboard", FILE, "summary.txt")
file_path, decoded_type = chain.decode("alice", "dashboard", token)
print("Decoded file saved to:", file_path)
print("Decoded type:", decoded_type)
```

When you call encode, Keybind performs these steps:

1. Normalizes the two identities.
2. Serializes the payload into bytes.
3. Applies optional compression.
4. Derives an encryption key from the master key and identities.
5. Encrypts the payload.
6. Produces a compact token string.

When you call decode, it reverses this process:

1. Validates the token format.
2. Re-derives the key using the same master key and identities.
3. Decrypts the payload.
4. Reconstructs the original JSON-compatible object.

## Example use cases

### 1. Temporary user session payload

```python
import os
from keybind import Keybind
from keybind.keybind import DICT

chain = Keybind(os.urandom(32))

session_data = {"user_id": 42, "plan": "pro", "expires_in": 3600}
token = chain.encode("42", "web-app", DICT, session_data)
```

### 2. Cross-service message transport

```python
from keybind import Keybind
from keybind.keybind import DICT

chain = Keybind(b"shared-secret")

message = {"event": "user.created", "id": 101}
token = chain.encode("service-a", "service-b", DICT, message)
```

### 3. Compact state handoff

```python
from keybind import Keybind
from keybind.keybind import DICT

chain = Keybind(b"state-secret")

state = {"step": 3, "status": "pending", "retry": False}
token = chain.encode("job-17", "worker", DICT, state)
```

## Important security notes

- Keep the master key secret.
- Do not hard-code production secrets in source files.
- Use a secure secret store or environment variable in production.
- Reuse the same master key consistently for the same application context.
- Keep the identities meaningful and consistent with your system design.

## Installation

Install the package from PyPI with:

```bash
pip install km-keybind
```

Install it directly from GitHub as a package with:

```bash
pip install git+https://github.com/kingmon6996/keybind.git
```

## Summary

Keybind gives you a simple way to turn JSON-compatible data into a compact, encrypted, identity-bound token. The core idea is straightforward:

- provide a master key
- provide two identities
- encode data into a token
- decode later with the same key and identities

Thank you for using Keybind.
