Auth Connect Skill

Metadata

Purpose

JWT-based authentication and authorization system for the Physical AI Educational Book FastAPI backend. Provides secure user authentication, session management, and role-based access control.

Features

• JWT token generation and verification
• Password hashing with bcrypt
• Role-based access control (RBAC)
• Session management
• API key generation
• Token refresh mechanism
• Secure middleware for FastAPI

Requirements

• Python 3.9+
• FastAPI backend
• Neon Postgres database
• Environment variables configured

Installation

# Install dependencies
pip install -r requirements.txt

# Initialize auth tables (requires DATABASE_URL)
.claude/skills/auth-connect/scripts/setup.sh --init

# Generate JWT secret
.claude/skills/auth-connect/scripts/setup.sh --generate-secret

Usage

CLI Commands

# Initialize auth system
./scripts/setup.sh --init

# Generate new JWT secret
./scripts/setup.sh --generate-secret

# Create a new user
./scripts/setup.sh --create-user --email user@example.com --role student

# List all roles
./scripts/setup.sh --list-roles

# Verify a token
./scripts/setup.sh --verify-token <token>

# Generate API key
./scripts/setup.sh --generate-api-key --name "My App"

# Show configuration
./scripts/setup.sh --show-config

# Run health check
./scripts/setup.sh --health

Python Integration

from auth import AuthManager, TokenPayload, verify_password, hash_password

# Initialize
auth = AuthManager()

# Hash password
hashed = hash_password("my_secure_password")

# Verify password
is_valid = verify_password("my_secure_password", hashed)

# Create access token
token = auth.create_access_token(
    user_id="user123",
    email="user@example.com",
    role="student"
)

# Verify token
payload = auth.verify_token(token)
if payload:
    print(f"User: {payload.user_id}, Role: {payload.role}")

# Create refresh token
refresh_token = auth.create_refresh_token(user_id="user123")

# Refresh access token
new_token = auth.refresh_access_token(refresh_token)

FastAPI Middleware

from fastapi import FastAPI, Depends, HTTPException
from auth import AuthManager, get_current_user, require_role

app = FastAPI()
auth = AuthManager()

# Protect endpoint with authentication
@app.get("/api/profile")
async def get_profile(user: TokenPayload = Depends(get_current_user)):
    return {"user_id": user.user_id, "email": user.email}

# Require specific role
@app.get("/api/admin")
async def admin_only(user: TokenPayload = Depends(require_role("admin"))):
    return {"message": "Welcome, admin!"}

# Multiple roles allowed
@app.put("/api/content")
async def edit_content(user: TokenPayload = Depends(require_role(["admin", "instructor"]))):
    return {"message": "Content updated"}

Configuration

Environment Variables

# Required
JWT_SECRET=your-256-bit-secret-key
DATABASE_URL=postgresql://user:pass@host/db

# Optional
JWT_ALGORITHM=HS256           # Default: HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30 # Default: 30
REFRESH_TOKEN_EXPIRE_DAYS=7    # Default: 7

auth_config.json

{
  "jwt": {
    "algorithm": "HS256",
    "access_token_expire_minutes": 30,
    "refresh_token_expire_days": 7
  },
  "password": {
    "min_length": 8,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_digit": true,
    "require_special": false
  },
  "session": {
    "max_sessions_per_user": 5,
    "session_timeout_minutes": 60
  }
}

roles.json

{
  "roles": {
    "admin": {
      "description": "Full system access",
      "permissions": ["read", "write", "delete", "manage_users", "manage_content"]
    },
    "instructor": {
      "description": "Content creator and manager",
      "permissions": ["read", "write", "manage_content"]
    },
    "student": {
      "description": "Standard learner access",
      "permissions": ["read", "chat", "save_progress"]
    },
    "guest": {
      "description": "Limited read-only access",
      "permissions": ["read"]
    }
  }
}

Database Schema

-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(50) DEFAULT 'student',
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Sessions table
CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    refresh_token VARCHAR(500) NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    ip_address VARCHAR(45),
    user_agent TEXT
);

-- API Keys table
CREATE TABLE api_keys (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(100) NOT NULL,
    key_hash VARCHAR(255) NOT NULL,
    prefix VARCHAR(10) NOT NULL,
    permissions JSONB DEFAULT '["read"]',
    is_active BOOLEAN DEFAULT true,
    last_used_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    expires_at TIMESTAMP
);

-- Indexes
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_sessions_user_id ON sessions(user_id);
CREATE INDEX idx_sessions_refresh_token ON sessions(refresh_token);
CREATE INDEX idx_api_keys_prefix ON api_keys(prefix);

Security Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Client Request                            │
│                    (with Authorization header)                   │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FastAPI Middleware                           │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                  Auth Middleware                           │  │
│  │  1. Extract token from Authorization header               │  │
│  │  2. Verify JWT signature                                  │  │
│  │  3. Check token expiration                                │  │
│  │  4. Validate user role/permissions                        │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────────┘
                          │
            ┌─────────────┴─────────────┐
            │                           │
            ▼                           ▼
┌───────────────────────┐   ┌───────────────────────┐
│   Valid Token         │   │   Invalid Token       │
│   → Process Request   │   │   → 401 Unauthorized  │
└───────────────────────┘   └───────────────────────┘

API Endpoints

/api/auth/register

/api/auth/login

/api/auth/logout

/api/auth/refresh

/api/auth/me

/api/auth/change-password

Error Codes

INVALID_TOKEN

TOKEN_EXPIRED

INVALID_CREDENTIALS

INSUFFICIENT_PERMISSIONS

USER_EXISTS

WEAK_PASSWORD

Testing

# Run all tests
./scripts/test.sh

# Run Python unit tests only
python scripts/test_auth.py

Files

auth-connect/
├── SKILL.md              # This documentation
├── requirements.txt      # Python dependencies
├── assets/
│   ├── auth_config.json  # Auth configuration
│   └── roles.json        # Role definitions
└── scripts/
    ├── setup.sh          # CLI entry point
    ├── auth.py           # Main auth module
    ├── test.sh           # Bash test runner
    └── test_auth.py      # Python unit tests

Changelog

v1.0.0 (2026-01-02)

• Initial release
• JWT authentication
• Password hashing with bcrypt
• Role-based access control
• Session management
• API key generation
• FastAPI middleware integration