Metadata-Version: 2.4
Name: anph-auth
Version: 0.1.0
Summary: Internal auth package — PASETO v4.public + RBAC + Redis revocation
Project-URL: Homepage, https://git.anph.io.vn/package/auth
Author-email: An <admin@anph.io.vn>
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: fastapi>=0.100
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: redis>=5.0
Provides-Extra: dev
Requires-Dist: anyio>=4.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# anph-auth — Hybrid Authorization System (SQL + PASETO + Redis)

Hệ thống kết hợp giữa quản trị dữ liệu chặt chẽ và thực thi quyền hạn tốc độ cao, hỗ trợ PASETO v4.public, RBAC (Role-Based Access Control) và thu hồi token tức thì qua Redis.

---

## 1. Triết lý hệ thống (Philosophy)

- **Management (PostgreSQL):** Quản lý quan hệ n-n qua 7 bảng chuẩn hóa để đảm bảo tính toàn vẹn dữ liệu.
- **Execution (PASETO):** "Phẳng hóa" (Flatten) quyền thành mảng string trong Token để kiểm tra quyền với độ trễ gần như bằng 0 (O(1) trong RAM).
- **Scaling (Microservices):** Hoàn toàn Stateless, giảm tải tối đa cho Database trung tâm nhờ cơ chế Verification tại Edge/Gateway.

---

## 2. Cấu trúc & Luồng vận hành

### Mô hình dữ liệu 7 bảng (Database Schema)
1. **users**: Người dùng.
2. **groups**: Nhóm/Phòng ban.
3. **roles**: Vai trò.
4. **permissions**: Quyền nguyên tử (Slug: `user.edit`, `file.upload`).
5. **user_groups**, **group_roles**, **role_permissions**: Các bảng trung gian thiết lập quan hệ.

### Luồng vận hành kỹ thuật
1. **Login & Flattening:** Auth Service JOIN 7 bảng -> Lấy tập hợp quyền -> Chuyển thành mảng String (`perms[]`) -> Ký PASETO.
2. **Verification & Authorization:**
   - **Gateway:** Kiểm tra chữ ký bằng Public Key.
   - **Microservice:** Giải mã Token, kiểm tra quyền trực tiếp từ mảng `perms` trong Payload.

---

## 3. Cài đặt & Cấu hình

### Cài đặt package
```bash
pip install anph-auth
```

### Yêu cầu hệ thống
- **Python:** 3.11+
- **Redis:** 6.0+ (Dùng cho Blacklist)
- **PostgreSQL:** 14+ (Chỉ dùng tại Auth Service để quản lý RBAC)

### Cấu hình môi trường (.env.local)
```dotenv
# Redis — JTI Blacklist
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=2

# PASETO v4.public keys (Base64-encoded PEM)
PASETO_PRIVATE_KEY=<base64_private_key>
PASETO_PUBLIC_KEY=<base64_public_key>
```

---

## 4. Sinh Key & Khởi tạo

**Bước bắt buộc trước khi chạy production:**

```bash
# Sinh key và ghi thẳng vào .env.local
auth-keygen --env

# Hoặc sinh file PEM riêng (cho K8s/Vault)
auth-keygen --pem
```

**Phân phối key:**
- **Auth Service (Ký):** Cần cả Private & Public Key.
- **Microservices (Verify):** Chỉ cần Public Key.

---

## 5. Hướng dẫn sử dụng

### 5.1 Ký & Xác thực Token
```python
from auth_core import sign_token, verify_token, settings

# Ký (tại Auth Service)
keypair = settings.load_keypair()
token = sign_token({"sub": "user-123", "perms": ["user.read", "config.*"]}, keypair.private_key)

# Xác thực (tại Gateway/Service)
public_key = settings.load_public_key_obj()
payload = verify_token(token, public_key)
```

### 5.2 Kiểm tra quyền (Wildcard support)
```python
from auth_core import PermissionChecker

checker = PermissionChecker(["user.read", "config.*"])
checker.has("user.read")    # True
checker.has("config.write") # True (khớp wildcard)
```

### 5.3 Tích hợp FastAPI
```python
from fastapi import FastAPI, Depends
from auth_core import AuthDependency, settings

auth = AuthDependency(
    public_key_pem=settings.load_public_key_bytes(),
    revocation_store=settings.build_revocation_store()
)

app = FastAPI()

@app.get("/users")
async def list_users(payload = Depends(auth.require("user.read"))):
    return {"data": "..."}
```

---

## 6. Chiến lược Thu hồi (Revocation)

Sử dụng Redis để tước quyền ngay lập tức mà không cần đợi Token hết hạn:
- **Access Token:** Hạn ngắn (5-15 phút).
- **Active Revocation:** ID của Token (`jti`) bị đưa vào Blacklist trên Redis. Middleware sẽ kiểm tra danh sách này cho mỗi request.

---

## 7. Tham chiếu API & Testing

### API Chính
- `sign_token(...)`: Ký payload thành PASETO v4.
- `verify_token(...)`: Xác thực chữ ký và thời gian.
- `PermissionChecker`: Thuật toán kiểm tra quyền O(1) exact và O(k) wildcard.

### Chạy Unit Test
```bash
PYTHONPATH=src pytest tests/ -v
```

---
*Tài liệu được cập nhật bởi An - Friday, April 24th, 2026*
