Tundere Ledger 🧐

A tamper-evident auditing ledger with Tsundere philosophy. "It's not like I'm recording this for you or anything!"

Backed by Rust 🦀 for strictness and performance.

Features

• 🔒 Tamper-Evident: Uses SHA-256 chaining (Blockchain-like structure).
• 🚀 High Performance: Core logic runs in native Rust.
• 🐍 Pythonic: Simple @audit_log decorator for easy integration.

Installation

pip install tundere-ledger

Or build from source:

git clone https://github.com/kuruitinoji-sys/tundere_ledger.git
cd tundere_ledger
pip install .

Usage

Basic Example: The "Tsundere" Decorator

Wrap any function to automatically record inputs, outputs, and errors.

from tundere_ledger import audit_log, verify_log

@audit_log(actor_name="Maid_Chan", importance=2.0)
def delete_database(reason):
    print(f"Deleting DB because: {reason}")
    # If this raises an error, it is also recorded immutably.

# Call the function
delete_database("Master spilled coffee")

# Verify log integrity
if verify_log():
    print("Log is clean.")
else:
    print("Log has been TAMPERED with!")

API Reference

@audit_log(actor_name="Unknown", importance=1.0, log_file="tundere_audit.jsonl")

Decorator that automatically records function calls to an audit log.

Parameters:

• actor_name (str): Identifier of who performed the action. Default: "Unknown"
• importance (float): Importance level of the action. Used for weighted audit trails. Default: 1.0
• log_file (str): Path to the audit log file. Must be within the current directory (path traversal protection). Default: "tundere_audit.jsonl"

Recorded Information:

• Function name
• Arguments and keyword arguments (converted to strings)
• Return value (on success)
• Exception details (on error)
• Timestamp (RFC3339 format)
• SHA-256 chain signature

verify_log(log_path="tundere_audit.jsonl") -> bool

Verifies the integrity of an audit log using SHA-256 chaining.

Parameters:

• log_path (str): Path to the audit log file to verify. Default: "tundere_audit.jsonl"

Returns:

• True if the log is intact and unmodified
• False if the log has been tampered with or is corrupted

get_recorder(log_path="tundere_audit.jsonl") -> TundereRecorder

Returns or creates a recorder instance for the specified log file.

Parameters:

• log_path (str): Path to the audit log file. Default: "tundere_audit.jsonl"

Returns:

• A TundereRecorder instance (Rust-backed)

Advanced Usage

Multiple Audit Logs

You can maintain separate audit trails for different components:

from tundere_ledger import audit_log, verify_log

@audit_log(actor_name="system", log_file="payments.jsonl")
def process_payment(amount):
    pass

@audit_log(actor_name="system", log_file="user_access.jsonl")
def access_user_data(user_id):
    pass

# Verify each log independently
if verify_log("payments.jsonl"):
    print("Payment log is clean")

if verify_log("user_access.jsonl"):
    print("Access log is clean")

Custom Recorder Management

from tundere_ledger import get_recorder

# Get or create a recorder
recorder = get_recorder("custom_audit.jsonl")

# Manually record events
recorder.commit_truth("admin", 5.0, '{"action": "user_deleted", "user_id": 42}')

# Verify integrity
if recorder.verify_integrity():
    print("Audit trail is intact")

Security Considerations

• Path Traversal Protection: All log file paths are validated and must reside within the current working directory.
• Immutable Chain: Each entry is hashed with the previous hash, making tampering immediately detectable.
• Actor Identification: Always specify a meaningful actor_name for audit traceability.

License

MIT