pico-auth 0.1.0__tar.gz

pico_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pico_auth-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include LICENSE
+include application.yaml
+
+recursive-include pico_auth *.py
+
+recursive-include tests *.py
+
+exclude .gitignore
+exclude Dockerfile*
+exclude docker-compose*.yml
+exclude Makefile
+
+prune build
+prune dist
+prune .tox
+prune .pytest_cache
+prune __pycache__

pico_auth-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: pico-auth
+Version: 0.1.0
+Summary: Minimal JWT auth server for the pico ecosystem
+Author: David Perez
+License: MIT
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-auth
+Project-URL: Documentation, https://dperezcabrera.github.io/pico-auth/
+Project-URL: Repository, https://github.com/dperezcabrera/pico-auth
+Project-URL: Issues, https://github.com/dperezcabrera/pico-auth/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pico-ioc>=2.1.0
+Requires-Dist: pico-boot>=0.1.0
+Requires-Dist: pico-fastapi>=0.1.0
+Requires-Dist: pico-sqlalchemy>=0.1.0
+Requires-Dist: pico-client-auth>=0.1.0
+Requires-Dist: python-jose[cryptography]>=3.3
+Requires-Dist: bcrypt>=4.0
+Requires-Dist: aiosqlite>=0.19
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Requires-Dist: mkdocs-minify-plugin; extra == "docs"
+Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == "docs"
+Dynamic: license-file
+
+# Pico-Auth
+
+[![PyPI](https://img.shields.io/pypi/v/pico-auth.svg)](https://pypi.org/project/pico-auth/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-auth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-auth/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-auth/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-auth)
+[![Docs](https://img.shields.io/badge/Docs-pico--auth-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-auth/)
+
+**Minimal JWT auth server for the Pico ecosystem.**
+
+Pico-Auth is a ready-to-run authentication server built on top of the [pico-framework](https://github.com/dperezcabrera/pico-ioc) stack. It provides:
+
+- **RS256 JWT tokens** with auto-generated RSA key pairs
+- **Refresh token rotation** with SHA-256 hashed storage
+- **RBAC** with four built-in roles: `superadmin`, `org_admin`, `operator`, `viewer`
+- **OIDC discovery** endpoints (`.well-known/openid-configuration`, JWKS)
+- **Bcrypt password hashing** (72-byte input limit enforced)
+- **Zero-config startup** with auto-created admin user
+
+> Requires Python 3.11+
+
+---
+
+## Architecture
+
+Pico-Auth uses the full Pico stack with dependency injection:
+
+| Layer | Component | Decorator |
+|-------|-----------|-----------|
+| Config | `AuthSettings` | `@configured(prefix="auth")` |
+| Models | `User`, `RefreshToken` | SQLAlchemy `AppBase` |
+| Repository | `UserRepository`, `RefreshTokenRepository` | `@component` |
+| Service | `AuthService` | `@component` |
+| Security | `JWTProvider`, `PasswordService`, `LocalJWKSProvider` | `@component` |
+| Routes | `AuthController`, `OIDCController` | `@controller` |
+
+---
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### 1. Run the Server
+
+```bash
+python -m pico_auth.main
+```
+
+The server starts on `http://localhost:8100` with:
+- An auto-created admin user (`admin@pico.local` / `admin`)
+- SQLite database at `auth.db`
+- RSA keys at `~/.pico-auth/`
+
+### 2. Register a User
+
+```bash
+curl -X POST http://localhost:8100/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email": "alice@example.com", "password": "secret123", "display_name": "Alice"}'
+```
+
+### 3. Login
+
+```bash
+curl -X POST http://localhost:8100/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "alice@example.com", "password": "secret123"}'
+```
+
+Returns:
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIs...",
+  "refresh_token": "a1b2c3d4...",
+  "token_type": "Bearer",
+  "expires_in": 900
+}
+```
+
+### 4. Access Protected Endpoint
+
+```bash
+curl http://localhost:8100/api/v1/auth/me \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
+```
+
+---
+
+## API Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/api/v1/auth/register` | No | Register a new user |
+| POST | `/api/v1/auth/login` | No | Login and get tokens |
+| POST | `/api/v1/auth/refresh` | No | Refresh access token |
+| GET | `/api/v1/auth/me` | Bearer | Get current user profile |
+| POST | `/api/v1/auth/me/password` | Bearer | Change password |
+| GET | `/api/v1/auth/users` | Admin | List all users |
+| PUT | `/api/v1/auth/users/{id}/role` | Admin | Update user role |
+| GET | `/api/v1/auth/jwks` | No | JSON Web Key Set |
+| GET | `/.well-known/openid-configuration` | No | OIDC discovery |
+
+---
+
+## Configuration
+
+All settings are loaded from `application.yaml` and can be overridden with environment variables:
+
+```yaml
+auth:
+  data_dir: "~/.pico-auth"              # RSA key storage
+  access_token_expire_minutes: 15        # JWT lifetime
+  refresh_token_expire_days: 7           # Refresh token lifetime
+  issuer: "http://localhost:8100"        # JWT issuer claim
+  audience: "pico-bot"                   # JWT audience claim
+  auto_create_admin: true                # Create admin on startup
+  admin_email: "admin@pico.local"        # Default admin email
+  admin_password: "admin"                # Default admin password
+
+database:
+  url: "sqlite+aiosqlite:///auth.db"     # Database URL
+  echo: false                            # SQL logging
+
+auth_client:
+  enabled: true                          # Enable auth middleware
+  issuer: "http://localhost:8100"        # Must match auth.issuer
+  audience: "pico-bot"                   # Must match auth.audience
+
+fastapi:
+  title: "Pico Auth API"
+  version: "0.1.0"
+```
+
+Environment variable override example:
+```bash
+AUTH_ISSUER=https://auth.myapp.com AUTH_ADMIN_PASSWORD=strong-password python -m pico_auth.main
+```
+
+---
+
+## JWT Token Claims
+
+Access tokens include:
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID |
+| `email` | User email |
+| `role` | User role (`superadmin`, `org_admin`, `operator`, `viewer`) |
+| `org_id` | Organization ID |
+| `iss` | Issuer URL |
+| `aud` | Audience |
+| `iat` | Issued at (Unix timestamp) |
+| `exp` | Expiration (Unix timestamp) |
+| `jti` | Unique token ID |
+
+---
+
+## Ecosystem
+
+Pico-Auth is built on:
+
+| Package | Role |
+|---------|------|
+| [pico-ioc](https://github.com/dperezcabrera/pico-ioc) | Dependency injection container |
+| [pico-boot](https://github.com/dperezcabrera/pico-boot) | Bootstrap and plugin discovery |
+| [pico-fastapi](https://github.com/dperezcabrera/pico-fastapi) | FastAPI integration with `@controller` |
+| [pico-sqlalchemy](https://github.com/dperezcabrera/pico-sqlalchemy) | Async SQLAlchemy with `SessionManager` |
+| [pico-client-auth](https://github.com/dperezcabrera/pico-client-auth) | JWT auth middleware with `SecurityContext` |
+
+---
+
+## Development
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest --cov=pico_auth --cov-report=term-missing tests/
+
+# Full test matrix
+tox
+
+# Lint
+ruff check pico_auth/ tests/
+```
+
+---
+
+## License
+
+MIT - [LICENSE](./LICENSE)

pico_auth-0.1.0/README.md

@@ -0,0 +1,203 @@
+# Pico-Auth
+
+[![PyPI](https://img.shields.io/pypi/v/pico-auth.svg)](https://pypi.org/project/pico-auth/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-auth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-auth/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-auth/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-auth)
+[![Docs](https://img.shields.io/badge/Docs-pico--auth-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-auth/)
+
+**Minimal JWT auth server for the Pico ecosystem.**
+
+Pico-Auth is a ready-to-run authentication server built on top of the [pico-framework](https://github.com/dperezcabrera/pico-ioc) stack. It provides:
+
+- **RS256 JWT tokens** with auto-generated RSA key pairs
+- **Refresh token rotation** with SHA-256 hashed storage
+- **RBAC** with four built-in roles: `superadmin`, `org_admin`, `operator`, `viewer`
+- **OIDC discovery** endpoints (`.well-known/openid-configuration`, JWKS)
+- **Bcrypt password hashing** (72-byte input limit enforced)
+- **Zero-config startup** with auto-created admin user
+
+> Requires Python 3.11+
+
+---
+
+## Architecture
+
+Pico-Auth uses the full Pico stack with dependency injection:
+
+| Layer | Component | Decorator |
+|-------|-----------|-----------|
+| Config | `AuthSettings` | `@configured(prefix="auth")` |
+| Models | `User`, `RefreshToken` | SQLAlchemy `AppBase` |
+| Repository | `UserRepository`, `RefreshTokenRepository` | `@component` |
+| Service | `AuthService` | `@component` |
+| Security | `JWTProvider`, `PasswordService`, `LocalJWKSProvider` | `@component` |
+| Routes | `AuthController`, `OIDCController` | `@controller` |
+
+---
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### 1. Run the Server
+
+```bash
+python -m pico_auth.main
+```
+
+The server starts on `http://localhost:8100` with:
+- An auto-created admin user (`admin@pico.local` / `admin`)
+- SQLite database at `auth.db`
+- RSA keys at `~/.pico-auth/`
+
+### 2. Register a User
+
+```bash
+curl -X POST http://localhost:8100/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email": "alice@example.com", "password": "secret123", "display_name": "Alice"}'
+```
+
+### 3. Login
+
+```bash
+curl -X POST http://localhost:8100/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "alice@example.com", "password": "secret123"}'
+```
+
+Returns:
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIs...",
+  "refresh_token": "a1b2c3d4...",
+  "token_type": "Bearer",
+  "expires_in": 900
+}
+```
+
+### 4. Access Protected Endpoint
+
+```bash
+curl http://localhost:8100/api/v1/auth/me \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
+```
+
+---
+
+## API Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/api/v1/auth/register` | No | Register a new user |
+| POST | `/api/v1/auth/login` | No | Login and get tokens |
+| POST | `/api/v1/auth/refresh` | No | Refresh access token |
+| GET | `/api/v1/auth/me` | Bearer | Get current user profile |
+| POST | `/api/v1/auth/me/password` | Bearer | Change password |
+| GET | `/api/v1/auth/users` | Admin | List all users |
+| PUT | `/api/v1/auth/users/{id}/role` | Admin | Update user role |
+| GET | `/api/v1/auth/jwks` | No | JSON Web Key Set |
+| GET | `/.well-known/openid-configuration` | No | OIDC discovery |
+
+---
+
+## Configuration
+
+All settings are loaded from `application.yaml` and can be overridden with environment variables:
+
+```yaml
+auth:
+  data_dir: "~/.pico-auth"              # RSA key storage
+  access_token_expire_minutes: 15        # JWT lifetime
+  refresh_token_expire_days: 7           # Refresh token lifetime
+  issuer: "http://localhost:8100"        # JWT issuer claim
+  audience: "pico-bot"                   # JWT audience claim
+  auto_create_admin: true                # Create admin on startup
+  admin_email: "admin@pico.local"        # Default admin email
+  admin_password: "admin"                # Default admin password
+
+database:
+  url: "sqlite+aiosqlite:///auth.db"     # Database URL
+  echo: false                            # SQL logging
+
+auth_client:
+  enabled: true                          # Enable auth middleware
+  issuer: "http://localhost:8100"        # Must match auth.issuer
+  audience: "pico-bot"                   # Must match auth.audience
+
+fastapi:
+  title: "Pico Auth API"
+  version: "0.1.0"
+```
+
+Environment variable override example:
+```bash
+AUTH_ISSUER=https://auth.myapp.com AUTH_ADMIN_PASSWORD=strong-password python -m pico_auth.main
+```
+
+---
+
+## JWT Token Claims
+
+Access tokens include:
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID |
+| `email` | User email |
+| `role` | User role (`superadmin`, `org_admin`, `operator`, `viewer`) |
+| `org_id` | Organization ID |
+| `iss` | Issuer URL |
+| `aud` | Audience |
+| `iat` | Issued at (Unix timestamp) |
+| `exp` | Expiration (Unix timestamp) |
+| `jti` | Unique token ID |
+
+---
+
+## Ecosystem
+
+Pico-Auth is built on:
+
+| Package | Role |
+|---------|------|
+| [pico-ioc](https://github.com/dperezcabrera/pico-ioc) | Dependency injection container |
+| [pico-boot](https://github.com/dperezcabrera/pico-boot) | Bootstrap and plugin discovery |
+| [pico-fastapi](https://github.com/dperezcabrera/pico-fastapi) | FastAPI integration with `@controller` |
+| [pico-sqlalchemy](https://github.com/dperezcabrera/pico-sqlalchemy) | Async SQLAlchemy with `SessionManager` |
+| [pico-client-auth](https://github.com/dperezcabrera/pico-client-auth) | JWT auth middleware with `SecurityContext` |
+
+---
+
+## Development
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest --cov=pico_auth --cov-report=term-missing tests/
+
+# Full test matrix
+tox
+
+# Lint
+ruff check pico_auth/ tests/
+```
+
+---
+
+## License
+
+MIT - [LICENSE](./LICENSE)

pico_auth-0.1.0/application.yaml

@@ -0,0 +1,22 @@
+auth:
+  data_dir: "~/.pico-auth"
+  access_token_expire_minutes: 15
+  refresh_token_expire_days: 7
+  issuer: "http://localhost:8100"
+  audience: "pico-bot"
+  auto_create_admin: true
+  admin_email: "admin@pico.local"
+  admin_password: "admin"
+
+database:
+  url: "sqlite+aiosqlite:///auth.db"
+  echo: false
+
+auth_client:
+  enabled: true
+  issuer: "http://localhost:8100"
+  audience: "pico-bot"
+
+fastapi:
+  title: "Pico Auth API"
+  version: "0.1.0"

pico_auth-0.1.0/pico_auth/__init__.py

@@ -0,0 +1,29 @@
+"""pico-auth -- minimal JWT auth server for the pico ecosystem."""
+
+import pico_auth.local_auth_configurer as local_auth_configurer  # noqa: F401 — patches AuthFastapiConfigurer
+from pico_auth.config import AuthSettings
+from pico_auth.errors import AuthError
+from pico_auth.jwt_provider import JWTProvider
+from pico_auth.local_jwks_provider import LocalJWKSProvider
+from pico_auth.models import RefreshToken, User
+from pico_auth.passwords import PasswordService
+from pico_auth.repository import RefreshTokenRepository, UserRepository
+from pico_auth.routes import AuthController, OIDCController
+from pico_auth.schema import create_tables
+from pico_auth.service import AuthService
+
+__all__ = [
+    "AuthController",
+    "AuthError",
+    "AuthSettings",
+    "AuthService",
+    "JWTProvider",
+    "LocalJWKSProvider",
+    "OIDCController",
+    "PasswordService",
+    "RefreshToken",
+    "RefreshTokenRepository",
+    "User",
+    "UserRepository",
+    "create_tables",
+]

pico_auth-0.1.0/pico_auth/config.py

@@ -0,0 +1,33 @@
+"""Auth server configuration using pico-ioc @configured."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from pico_ioc import configured
+
+
+@configured(target="self", prefix="auth", mapping="tree")
+@dataclass
+class AuthSettings:
+    """Auth server settings from application.yaml / env vars."""
+
+    data_dir: str = "~/.pico-auth"
+    access_token_expire_minutes: int = 15
+    refresh_token_expire_days: int = 7
+    issuer: str = "http://localhost:8100"
+    audience: str = "pico-bot"
+    auto_create_admin: bool = True
+    admin_email: str = "admin@pico.local"
+    admin_password: str = "admin"
+
+    @property
+    def data_path(self) -> Path:
+        return Path(self.data_dir).expanduser()
+
+    @property
+    def private_key_path(self) -> Path:
+        return self.data_path / "private.pem"
+
+    @property
+    def public_key_path(self) -> Path:
+        return self.data_path / "public.pem"

pico_auth-0.1.0/pico_auth/errors.py

@@ -0,0 +1,42 @@
+"""Auth error hierarchy."""
+
+
+class AuthError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
+class UserExistsError(AuthError):
+    def __init__(self, email: str):
+        super().__init__(f"User already exists: {email}")
+
+
+class InvalidCredentialsError(AuthError):
+    def __init__(self):
+        super().__init__("Invalid email or password")
+
+
+class TokenExpiredError(AuthError):
+    def __init__(self):
+        super().__init__("Token has expired")
+
+
+class TokenInvalidError(AuthError):
+    def __init__(self):
+        super().__init__("Invalid token")
+
+
+class UserNotFoundError(AuthError):
+    def __init__(self, user_id: str):
+        super().__init__(f"User not found: {user_id}")
+
+
+class InsufficientPermissionsError(AuthError):
+    def __init__(self):
+        super().__init__("Insufficient permissions")
+
+
+class UserSuspendedError(AuthError):
+    def __init__(self):
+        super().__init__("User account is suspended")