llms-py 3.0.23__py3-none-any.whl → 3.0.25__py3-none-any.whl

llms/extensions/github_auth/README.md

@@ -0,0 +1,169 @@
+# GitHub Auth Extension
+
+The GitHub Auth extension enables OAuth 2.0 authentication via GitHub for your llms application. When enabled, users must sign in with their GitHub account before accessing the application.
+
+## Features
+
+- **GitHub OAuth 2.0** - Standard OAuth flow with CSRF protection
+- **User Restrictions** - Optionally restrict access to specific GitHub users
+- **Session Management** - Automatic session handling with 24-hour expiry
+- **Environment Variables** - Credentials can use env vars for secure deployment
+
+## Configuration
+
+Create a config file at `~/.llms/users/default/github_auth/config.json`:
+
+```json
+{
+  "enabled": true,
+  "client_id": "$GITHUB_CLIENT_ID",
+  "client_secret": "$GITHUB_CLIENT_SECRET",
+  "redirect_uri": "http://localhost:8000/auth/github/callback",
+  "restrict_to": "$GITHUB_USERS"
+}
+```
+
+| Property        | Description |
+|-----------------|-------------|
+| `client_id`     | GitHub OAuth App client ID |
+| `client_secret` | GitHub OAuth App client secret |
+| `redirect_uri`  | Callback URL registered with GitHub |
+| `restrict_to`   | Optional comma/space-delimited list of allowed GitHub usernames |
+| `enabled`       | Set to `false` to disable the extension |
+
+Values prefixed with `$` are resolved from environment variables.
+
+## Creating a GitHub OAuth App
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Click **New OAuth App**
+3. Fill in the application details:
+   - **Application name**: Your app name
+   - **Homepage URL**: Your app's homepage (e.g., `http://localhost:8000`)
+   - **Authorization callback URL**: Must match your `redirect_uri` (e.g., `http://localhost:8000/auth/github/callback`)
+4. Click **Register application**
+5. Copy the **Client ID** and generate a **Client Secret**
+
+## API Endpoints
+
+The extension registers these routes:
+
+| Method | Endpoint                | Description |
+|--------|-------------------------|-------------|
+| GET    | `/auth`                 | Check authentication status |
+| GET    | `/auth/github`          | Initiate GitHub OAuth flow |
+| GET    | `/auth/github/callback` | OAuth callback handler |
+| GET    | `/auth/session`         | Get current session info |
+| POST   | `/auth/logout`          | End the current session |
+
+### GET /auth
+
+Returns the authenticated user's info or a 401 error:
+
+```json
+{
+  "userId": "12345",
+  "userName": "octocat",
+  "displayName": "The Octocat",
+  "profileUrl": "https://avatars.githubusercontent.com/u/12345",
+  "authProvider": "github"
+}
+```
+
+### GET /auth/session
+
+Returns full session details including the session token:
+
+```json
+{
+  "userId": "12345",
+  "userName": "octocat",
+  "displayName": "The Octocat",
+  "profileUrl": "https://avatars.githubusercontent.com/u/12345",
+  "email": "octocat@github.com",
+  "created": 1706600000.123,
+  "sessionToken": "..."
+}
+```
+
+## OAuth Flow
+
+```
+┌─────────┐          ┌─────────┐          ┌────────┐
+│ Browser │          │  llms   │          │ GitHub │
+└────┬────┘          └────┬────┘          └───┬────┘
+     │                    │                   │
+     │ GET /auth/github   │                   │
+     ├───────────────────►│                   │
+     │                    │                   │
+     │   302 Redirect     │                   │
+     │◄───────────────────┤                   │
+     │                    │                   │
+     │  /login/oauth/authorize?...            │
+     ├────────────────────────────────────────►
+     │                    │                   │
+     │         User grants access             │
+     │◄────────────────────────────────────────
+     │                    │                   │
+     │ GET /auth/github/callback?code=...     │
+     ├───────────────────►│                   │
+     │                    │                   │
+     │                    │ POST /access_token │
+     │                    ├──────────────────►│
+     │                    │                   │
+     │                    │   access_token    │
+     │                    │◄──────────────────┤
+     │                    │                   │
+     │                    │ GET /user         │
+     │                    ├──────────────────►│
+     │                    │                   │
+     │                    │   user info       │
+     │                    │◄──────────────────┤
+     │                    │                   │
+     │  302 /?session=... │                   │
+     │  Set-Cookie: token │                   │
+     │◄───────────────────┤                   │
+     │                    │                   │
+```
+
+1. User clicks "Sign in with GitHub" → redirects to `/auth/github`
+2. Server generates CSRF state token and redirects to GitHub
+3. User authorizes the app on GitHub
+4. GitHub redirects back with authorization code
+5. Server exchanges code for access token
+6. Server fetches user info from GitHub API
+7. Server creates session and sets cookie
+
+## Restricting Access
+
+To limit access to specific GitHub users, set `restrict_to` in your config:
+
+```json
+{
+  "client_id": "...",
+  "client_secret": "...",
+  "redirect_uri": "...",
+  "restrict_to": "alice bob charlie"
+}
+```
+
+Users not in this list receive a `403 Forbidden` response.
+
+## UI Component
+
+The extension provides a custom `SignIn` component that displays a "Sign in with GitHub" button. This component automatically overrides the default sign-in UI when the extension is loaded.
+
+## Session Storage
+
+Sessions are stored in memory with:
+- **Token**: Cryptographically secure random string
+- **User data**: GitHub user ID, username, display name, avatar URL, email
+- **Expiry**: Automatic cleanup after 24 hours
+- **Cookie**: `llms-token` with `httponly` flag for security
+
+## Security Notes
+
+- **CSRF Protection**: OAuth state tokens prevent cross-site request forgery
+- **State Cleanup**: Expired state tokens (>10 min) are automatically removed
+- **Session Cleanup**: Sessions older than 24 hours are pruned
+- **HttpOnly Cookie**: Session token is not accessible via JavaScript

llms/extensions/github_auth/__init__.py

@@ -0,0 +1,254 @@
+import json
+import os
+import re
+import secrets
+import time
+from urllib.parse import parse_qs, urlencode
+
+import aiohttp
+from aiohttp import web
+
+
+def install(ctx):
+    g_app = ctx.app
+
+    auth_config_file = os.path.join(ctx.get_user_path(), "github_auth", "config.json")
+
+    auth_config = None
+    if os.path.exists(auth_config_file):
+        try:
+            with open(auth_config_file, encoding="utf-8") as f:
+                auth_config = json.load(f)
+            if "enabled" in auth_config and not auth_config["enabled"]:
+                ctx.log("GitHub Auth is disabled in config")
+                auth_config = None
+        except Exception as e:
+            ctx.err("Failed to load GitHub auth config", e)
+    else:
+        ctx.dbg(f"GitHub Auth config file '{auth_config_file}' not found")
+
+    if not auth_config:
+        # don't load extension if auth_config is not found or is disabled
+        ctx.disabled = True
+        return
+
+    client_id = auth_config.get("client_id", "")
+    client_secret = auth_config.get("client_secret", "")
+    redirect_uri = auth_config.get("redirect_uri", "")
+    restrict_to = auth_config.get("restrict_to", "")
+
+    # Expand environment variables
+    if client_id.startswith("$"):
+        client_id = client_id[1:]
+    if client_secret.startswith("$"):
+        client_secret = client_secret[1:]
+        client_secret = os.getenv(client_secret)
+    if redirect_uri.startswith("$"):
+        redirect_uri = redirect_uri[1:]
+        redirect_uri = os.getenv(redirect_uri)
+    if restrict_to.startswith("$"):
+        restrict_to = restrict_to[1:]
+        restrict_to = os.getenv(restrict_to)
+
+    # check if client_id is set
+    if client_id == "GITHUB_CLIENT_ID":
+        client_id = os.getenv(client_id)
+    if client_secret == "GITHUB_CLIENT_SECRET":
+        client_secret = os.getenv(client_secret)
+    if restrict_to == "GITHUB_USERS":
+        restrict_to = os.getenv(restrict_to)
+
+    if not client_id or not redirect_uri or not client_secret:
+        ctx.disabled = True
+        ctx.log("GitHub OAuth client_id, client_secret and redirect_uri are not configured")
+        return
+
+    from llms.main import AuthProvider
+
+    class GitHubAuthProvider(AuthProvider):
+        def __init__(self, app):
+            super().__init__(app)
+
+    # Adding an Auth Provider forces Authentication to be enabled
+    auth_provider = GitHubAuthProvider(g_app)
+    g_app.auth_providers.append(auth_provider)
+
+    # OAuth handlers
+    async def github_auth_handler(request):
+        # Generate CSRF state token
+        state = secrets.token_urlsafe(32)
+        ctx.oauth_states[state] = {"created": time.time(), "redirect_uri": redirect_uri}
+
+        # Clean up old states (older than 10 minutes)
+        current_time = time.time()
+        expired_states = [s for s, data in ctx.oauth_states.items() if current_time - data["created"] > 600]
+        for s in expired_states:
+            del ctx.oauth_states[s]
+
+        # Build GitHub authorization URL
+        params = {
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "state": state,
+            "scope": "read:user user:email",
+        }
+        auth_url = f"https://github.com/login/oauth/authorize?{urlencode(params)}"
+
+        return web.HTTPFound(auth_url)
+
+    def validate_user(github_username):
+        # If restrict_to is configured, validate the user
+        if restrict_to:
+            # Parse allowed users (comma or space delimited)
+            allowed_users = [u.strip() for u in re.split(r"[,\s]+", restrict_to) if u.strip()]
+
+            # Check if user is in the allowed list
+            if not github_username or github_username not in allowed_users:
+                ctx.log(f"Access denied for user: {github_username}. Not in allowed list: {allowed_users}")
+                return web.Response(
+                    text=f"Access denied. User '{github_username}' is not authorized to access this application.",
+                    status=403,
+                )
+        return None
+
+    async def github_callback_handler(request):
+        """Handle GitHub OAuth callback"""
+        code = request.query.get("code")
+        state = request.query.get("state")
+
+        # Handle malformed URLs where query params are appended with & instead of ?
+        if not code and "tail" in request.match_info:
+            tail = request.match_info["tail"]
+            if tail.startswith("&"):
+                params = parse_qs(tail[1:])
+                code = params.get("code", [None])[0]
+                state = params.get("state", [None])[0]
+
+        if not code or not state:
+            return web.Response(text="Missing code or state parameter", status=400)
+
+        # Verify state token (CSRF protection)
+        if state not in ctx.oauth_states:
+            return web.Response(text="Invalid state parameter", status=400)
+
+        ctx.oauth_states.pop(state)
+
+        # Exchange code for access token
+        async with aiohttp.ClientSession() as session:
+            token_url = "https://github.com/login/oauth/access_token"
+            token_data = {
+                "client_id": client_id,
+                "client_secret": client_secret,
+                "code": code,
+                "redirect_uri": redirect_uri,
+            }
+            headers = {"Accept": "application/json"}
+
+            async with session.post(token_url, data=token_data, headers=headers) as resp:
+                token_response = await resp.json()
+                access_token = token_response.get("access_token")
+
+                if not access_token:
+                    error = token_response.get("error_description", "Failed to get access token")
+                    return web.json_response(ctx.create_error_response(f"OAuth error: {error}"), status=400)
+
+            # Fetch user info
+            user_url = "https://api.github.com/user"
+            headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/json"}
+
+            async with session.get(user_url, headers=headers) as resp:
+                user_data = await resp.json()
+
+            # Validate user
+            error_response = validate_user(user_data.get("login", ""))
+            if error_response:
+                return error_response
+
+        # Create session
+        session_token = secrets.token_urlsafe(32)
+        ctx.sessions[session_token] = {
+            "userId": str(user_data.get("id", "")),
+            "userName": user_data.get("login", ""),
+            "displayName": user_data.get("name", ""),
+            "profileUrl": user_data.get("avatar_url", ""),
+            "email": user_data.get("email", ""),
+            "created": time.time(),
+        }
+
+        # Redirect to UI with session token
+        response = web.HTTPFound(f"/?session={session_token}")
+        response.set_cookie("llms-token", session_token, httponly=True, path="/", max_age=86400)
+        return response
+
+    async def session_handler(request):
+        """Validate and return session info"""
+        session_token = auth_provider.get_session_token(request)
+
+        if not session_token or session_token not in ctx.sessions:
+            return web.json_response(ctx.create_error_response("Invalid or expired session"), status=401)
+
+        session_data = ctx.sessions[session_token]
+
+        # Clean up old sessions (older than 24 hours)
+        current_time = time.time()
+        expired_sessions = [token for token, data in ctx.sessions.items() if current_time - data["created"] > 86400]
+        for token in expired_sessions:
+            del ctx.sessions[token]
+
+        return web.json_response({**session_data, "sessionToken": session_token})
+
+    async def logout_handler(request):
+        """End OAuth session"""
+        session_token = auth_provider.get_session_token(request)
+
+        if session_token and session_token in g_app.sessions:
+            del g_app.sessions[session_token]
+
+        response = web.json_response({"success": True})
+        response.del_cookie("llms-token")
+        return response
+
+    async def auth_handler(request):
+        """Check authentication status and return user info"""
+        # Check for OAuth session token
+        session_token = auth_provider.get_session_token(request)
+
+        if session_token and session_token in g_app.sessions:
+            session_data = g_app.sessions[session_token]
+            return web.json_response(
+                {
+                    "userId": session_data.get("userId", ""),
+                    "userName": session_data.get("userName", ""),
+                    "displayName": session_data.get("displayName", ""),
+                    "profileUrl": session_data.get("profileUrl", ""),
+                    "authProvider": "github",
+                }
+            )
+
+        # Check for API key in Authorization header
+        # auth_header = request.headers.get('Authorization', '')
+        # if auth_header.startswith('Bearer '):
+        #     # For API key auth, return a basic response
+        #     # You can customize this based on your API key validation logic
+        #     api_key = auth_header[7:]
+        #     if api_key:  # Add your API key validation logic here
+        #         return web.json_response({
+        #             "userId": "1",
+        #             "userName": "apiuser",
+        #             "displayName": "API User",
+        #             "profileUrl": "",
+        #             "authProvider": "apikey"
+        #         })
+
+        # Not authenticated - return error in expected format
+        return web.json_response(g_app.error_auth_required, status=401)
+
+    ctx.add_get("/auth", auth_handler)
+    ctx.add_get("/auth/github", github_auth_handler)
+    ctx.add_get("/auth/github/callback", github_callback_handler)
+    ctx.add_get("/auth/github/callback{tail:.*}", github_callback_handler)
+    ctx.add_get("/auth/session", session_handler)
+    ctx.add_post("/auth/logout", logout_handler)
+
+
+__install__ = install

llms/extensions/github_auth/ui/index.mjs

@@ -0,0 +1,66 @@
+import { ref } from "vue"
+
+const SignIn = {
+    template: `
+    <div class="min-h-full -mt-36 flex flex-col justify-center sm:px-6 lg:px-8">
+        <div class="sm:mx-auto sm:w-full sm:max-w-md text-center">
+            <Welcome />
+        </div>
+        <div class="sm:mx-auto sm:w-full sm:max-w-md">
+            <div v-if="errorMessage" class="mb-3 bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 text-red-800 dark:text-red-200 rounded-lg px-4 py-3">
+                <div class="flex items-start space-x-2">
+                    <div class="flex-1">
+                        <div class="text-base font-medium">{{ errorMessage }}</div>
+                    </div>
+                    <button type="button"
+                        @click="errorMessage = null"
+                        class="text-red-400 dark:text-red-300 hover:text-red-600 dark:hover:text-red-100 flex-shrink-0"
+                    >
+                        <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
+                            <path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"></path>
+                        </svg>
+                    </button>
+                </div>
+            </div>
+            <div class="py-8 px-4 sm:px-10">
+                <div class="space-y-4">
+                    <button
+                        type="button"
+                        @click="signInWithGitHub"
+                        class="w-full inline-flex items-center justify-center px-4 py-3 border border-gray-300 dark:border-gray-600 rounded-md shadow-sm text-base font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-800 hover:bg-gray-50 dark:hover:bg-gray-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-gray-500 transition-colors"
+                    >
+                        <svg class="w-6 h-6 mr-3" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                            <path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clip-rule="evenodd" />
+                        </svg>
+                        Sign in with GitHub
+                    </button>
+                </div>
+            </div>
+        </div>
+    </div>     
+    `,
+    emits: ['done'],
+    setup(props, { emit }) {
+        const errorMessage = ref(null)
+
+        function signInWithGitHub() {
+            // Redirect to GitHub OAuth endpoint
+            window.location.href = '/auth/github'
+        }
+
+        return {
+            signInWithGitHub,
+            errorMessage,
+        }
+    }
+}
+
+
+export default {
+    install(ctx) {
+        // Override SignIn component
+        ctx.components({
+            SignIn,
+        })
+    }
+}

llms/extensions/skills/README.md

@@ -33,14 +33,21 @@ Access the skills panel by clicking the **Skills** icon in the top toolbar. The
 
 ### Skill Groups
 
-Skills are organized into groups based on their source:
+Skills are organized into groups based on their source location. Skills are discovered from these directories in order:
 
-| Group | Description | Editable |
-|-------|-------------|----------|
-| `~/.llms/.agents` | Your personal skills collection | ✓ Yes |
-| Built-in | Skills bundled with the extension | ✗ No |
+| Group | Location | Description | Editable |
+|-------|----------|-------------|----------|
+| Project (Agent) | `.agent/skills/` | Skills local to the current project | ✓ Yes |
+| Project (Claude) | `.claude/skills/` | Claude-format skills in the current project | ✓ Yes |
+| User (Agent) | `~/.llms/.agents/skills/` | Your personal skills collection | ✓ Yes |
+| User (Claude) | `~/.claude/skills/` | Claude-format skills in your home directory | ✓ Yes |
+| Built-in | Extension directory | Skills bundled with the extension | ✗ No |
 
-Your personal skills (`~/.llms/.agents`) are fully editable. Built-in skills provide reference implementations you can learn from.
+**Project-level skills** (`.agent/` and `.claude/`) are specific to the workspace you're working in. They're ideal for project-specific workflows, coding standards, or team conventions.
+
+**User-level skills** (`~/.llms/.agents/` and `~/.claude/`) are available across all projects. Use these for personal workflows and preferences.
+
+Both `.agent` and `.claude` directory formats are supported for compatibility with different tooling conventions.
 
 ### Selecting Skills for a Conversation
 

llms/extensions/skills/__init__.py

@@ -21,6 +21,9 @@ g_home_skills = None
 # }
 g_available_skills = []
 
+LLMS_HOME_SKILLS = "~/.llms/.agent/skills"
+LLMS_LOCAL_SKILLS = ".agent/skills"
+
 
 def is_safe_path(base_path: str, requested_path: str) -> bool:
     """Check if the requested path is safely within the base path."""
@@ -132,10 +135,12 @@ def install(ctx):
     if os.path.exists(os.path.join(".claude", "skills")):
         skill_roots[".claude/skills"] = os.path.join(".claude", "skills")
 
-    skill_roots["~/.llms/.agents"] = home_skills
+    skill_roots[LLMS_HOME_SKILLS] = home_skills
 
-    if os.path.exists(os.path.join(".agent", "skills")):
-        skill_roots[".agents"] = os.path.join(".agent", "skills")
+    local_skills = os.path.join(".agent", "skills")
+    if os.path.exists(local_skills):
+        local_skills = str(Path(local_skills).resolve())
+        skill_roots[LLMS_LOCAL_SKILLS] = local_skills
 
     g_skills = {}
     for group, root in skill_roots.items():
@@ -237,7 +242,7 @@ def install(ctx):
                 skill_props = props.to_dict()
                 skill_props.update(
                     {
-                        "group": "~/.llms/.agents",
+                        "group": LLMS_HOME_SKILLS,
                         "location": str(skill_dir),
                         "files": files,
                     }
@@ -303,9 +308,9 @@ def install(ctx):
 
         location = skill_info.get("location")
 
-        # Only allow modifications to skills in home directory
-        if not is_safe_path(home_skills, location):
-            raise Exception("Cannot modify skills outside of home directory")
+        # Only allow modifications to skills in home or local .agent directory
+        if not is_safe_path(home_skills, location) and not (local_skills and is_safe_path(local_skills, location)):
+            raise Exception("Cannot modify skills outside of allowed directories")
 
         full_path = os.path.join(location, file_path)
 
@@ -319,7 +324,7 @@ def install(ctx):
                 f.write(content)
 
             # Reload skill metadata
-            group = skill_info.get("group", "~/.llms/.agents")
+            group = skill_info.get("group", LLMS_HOME_SKILLS)
             updated_skill = reload_skill(name, location, group)
 
             return aiohttp.web.json_response({"path": file_path, "skill": updated_skill})
@@ -342,9 +347,9 @@ def install(ctx):
 
         location = skill_info.get("location")
 
-        # Only allow modifications to skills in home directory
-        if not is_safe_path(home_skills, location):
-            raise Exception("Cannot modify skills outside of home directory")
+        # Only allow modifications to skills in home or local .agent directory
+        if not is_safe_path(home_skills, location) and not (local_skills and is_safe_path(local_skills, location)):
+            raise Exception("Cannot modify skills outside of allowed directories")
 
         full_path = os.path.join(location, file_path)
 
@@ -371,7 +376,7 @@ def install(ctx):
                     break
 
             # Reload skill metadata
-            group = skill_info.get("group", "~/.llms/.agents")
+            group = skill_info.get("group", LLMS_HOME_SKILLS)
             updated_skill = reload_skill(name, location, group)
 
             return aiohttp.web.json_response({"path": file_path, "skill": updated_skill})
@@ -433,7 +438,7 @@ def install(ctx):
                 skill_props = props.to_dict()
                 skill_props.update(
                     {
-                        "group": "~/.llms/.agents",
+                        "group": LLMS_HOME_SKILLS,
                         "location": str(skill_dir_path),
                         "files": files,
                     }
@@ -467,9 +472,9 @@ def install(ctx):
             else:
                 raise Exception(f"Skill '{name}' not found")
 
-        # Only allow deletion of skills in home directory
-        if not is_safe_path(home_skills, location):
-            raise Exception("Cannot delete skills outside of home directory")
+        # Only allow deletion of skills in home or local .agent directory
+        if not is_safe_path(home_skills, location) and not (local_skills and is_safe_path(local_skills, location)):
+            raise Exception("Cannot delete skills outside of allowed directories")
 
         try:
             if os.path.exists(location):