anph-auth 0.1.0

Internal auth package — PASETO v4.public + RBAC + Redis revocation

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

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)

# 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:

# 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

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)

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

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

PYTHONPATH=src pytest tests/ -v

---

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