Authentication

Authentication functions and credential management for Chisel CLI

Chisel CLI uses secure authentication to connect to the Herdora backend. Authentication is handled automatically when you first use the chisel command, but you can also manage credentials programmatically.

Authentication Functions

is_authenticated()

Check if the user is currently authenticated with valid credentials.

from chisel.auth import is_authenticated

if is_authenticated():
    print("✅ Ready to use Chisel")
else:
    print("❌ Authentication required")

return · boolean

Returns True if valid credentials exist and are accessible, False otherwise.

Usage Examples:

Basic Check

from chisel.auth import is_authenticated

def check_auth_status():
    if is_authenticated():
        return "authenticated"
    else:
        return "not_authenticated"

status = check_auth_status()
print(f"Auth status: {status}")

authenticate()

Manually trigger the authentication flow. Opens browser for user authentication.

from chisel.auth import authenticate

api_key = authenticate(backend_url="http://localhost:8000")

backend_url · string · default: "http://localhost:8000"

The backend URL to authenticate against. Defaults to local development server.

return · string

Returns the API key on successful authentication, raises RuntimeError on failure.

Usage Examples:

Manual Authentication

from chisel.auth import authenticate

try:
    api_key = authenticate()
    print("✅ Authentication successful")
except RuntimeError as e:
    print(f"❌ Authentication failed: {e}")

clear_credentials()

Remove stored authentication credentials. Useful for logout or credential reset.

from chisel.auth import clear_credentials

clear_credentials()
print("🔓 Credentials cleared")

return · None

No return value. Credentials are removed from storage.

Usage Examples:

Simple Logout

from chisel.auth import clear_credentials, is_authenticated

def logout():
    if is_authenticated():
        clear_credentials()
        print("🔓 Successfully logged out")
    else:
        print("ℹ️  Already logged out")

logout()

Credential Storage

Storage Location

Credentials are stored securely in the user’s home directory:

~/.chisel/credentials.json

The credentials file has restricted permissions (600) for security.

File Structure

The credentials file contains:

{
  "api_key": "your_encrypted_api_key_here",
  "backend_url": "http://localhost:8000",
  "expires_at": "2024-12-31T23:59:59Z"
}

Never manually edit the credentials file. Use the provided authentication functions instead.

Security Features

File Permissions

• Credentials file has 600 permissions (read/write for owner only)
• Directory has 700 permissions (access for owner only)
• Other users cannot read your credentials

Encryption

• API keys are encrypted before storage
• Uses secure local encryption methods
• Keys are never stored in plain text

Expiration

• Credentials have expiration timestamps
• Automatic refresh when approaching expiration
• Invalid credentials are automatically cleared

Authentication Flow

1. Initial Authentication

   When you first run chisel:

   1. Checks for existing valid credentials
   2. If none found, opens browser for authentication
   3. User logs in or creates Herdora account
   4. API key is generated and stored securely
   5. Future chisel commands use stored credentials

   # First time usage
   chisel python my_script.py
   # → Opens browser for authentication
   # → Credentials stored
   # → Script executes on GPU
   

2. Automatic Authentication

   For subsequent uses:

   1. Checks stored credentials
   2. Validates expiration and authenticity
   3. Uses existing credentials if valid
   4. Refreshes credentials if near expiration
   5. Prompts for re-authentication if invalid

   # Subsequent usage
   chisel python my_script.py
   # → Uses stored credentials
   # → Script executes immediately
   

3. Re-authentication

   When credentials expire or become invalid:

   1. Detects authentication failure
   2. Clears invalid credentials
   3. Initiates new authentication flow
   4. Updates stored credentials
   5. Retries original request

   # When credentials expire
   chisel python my_script.py
   # → Detects expired credentials
   # → Opens browser for re-authentication
   # → Updates credentials
   # → Script executes
   

Environment Variables

Authentication can be influenced by environment variables:

CHISEL_BACKEND_URL · string

Override the default backend URL for authentication.

CHISEL_API_KEY · string

Directly provide API key (bypasses file-based credentials).

Examples:

Custom Backend

export CHISEL_BACKEND_URL="https://api.herdora.com"
chisel python my_script.py

Error Handling

Common authentication errors and solutions:

RuntimeError: Authentication failed

Cause: Browser authentication was cancelled or failed

Solutions:

from chisel.auth import clear_credentials, authenticate

# Clear potentially corrupted credentials
clear_credentials()

# Retry authentication
try:
    authenticate()
except RuntimeError:
    print("Please complete authentication in browser")

FileNotFoundError: Credentials not found

Cause: Credentials file doesn’t exist or was deleted

Solution:

from chisel.auth import authenticate

# Simply authenticate again
authenticate()  # Will create new credentials file

PermissionError: Cannot access credentials

Cause: Incorrect file permissions on credentials

Solution:

# Fix permissions manually
chmod 600 ~/.chisel/credentials.json
chmod 700 ~/.chisel/

Integration Examples

With ChiselApp

from chisel import ChiselApp, GPUType
from chisel.auth import is_authenticated, authenticate

def create_authenticated_app(name, gpu_type):
    """Create ChiselApp with authentication check."""
    if not is_authenticated():
        print("🔐 Authentication required...")
        try:
            authenticate()
        except RuntimeError as e:
            print(f"❌ Authentication failed: {e}")
            return None
    
    return ChiselApp(name, gpu=gpu_type)

# Usage
app = create_authenticated_app("my-app", GPUType.A100_80GB_2)
if app:
    @app.capture_trace(trace_name="secure_operation")
    def secure_gpu_function(data):
        # Your GPU code here
        return result

Script Template

#!/usr/bin/env python3
"""
Secure Chisel script template with authentication handling.
"""

import sys
from chisel import ChiselApp, GPUType
from chisel.auth import is_authenticated, authenticate, clear_credentials

def main():
    # Check authentication status
    if not is_authenticated():
        print("🔐 Chisel authentication required")
        try:
            authenticate()
            print("✅ Authentication successful")
        except RuntimeError as e:
            print(f"❌ Authentication failed: {e}")
            print("💡 Please ensure you can access the browser for authentication")
            sys.exit(1)
    
    # Create app with authentication verified
    app = ChiselApp("secure-app", gpu=GPUType.A100_80GB_1)
    
    @app.capture_trace(trace_name="main_processing")
    def process_data(data):
        import torch
        device = "cuda" if torch.cuda.is_available() else "cpu"
        # Your processing logic
        return result
    
    # Your main logic here
    result = process_data(your_data)
    print(f"Processing complete: {result}")

if __name__ == "__main__":
    main()

Related Documentation

ChiselApp

Main application class that uses authentication

CLI Commands

Command-line interface and authentication flow

Troubleshooting

Authentication troubleshooting guide

Configuration

Authentication configuration options