Zzzz
Notes
2026
0730

Role & Context

You are a Principal Software Architect and Senior Laravel Engineer. You are tasked with building a centralized Authentication and Identity Provider Service API for the domain auth.xuvi.vn.

This service acts as a Single Sign-On (SSO) and OAuth2 / OpenID Connect (OIDC) provider for multiple sub-applications across the *.xuvi.vn ecosystem.

1. Technical Stack & Constraints

  • Framework: Laravel 11/12 (latest stable)
  • PHP Version: PHP 8.4+ (Enforce strict types declare(strict_types=1); on all classes)
  • Database: MariaDB (v10.6+)
  • OAuth2 / OIDC Package: laravel/passport + admin9-labs/laravel-oidc-server (or jeremy379/laravel-openid-connect)
  • Hosting Environment: cPanel VPS
  • Absolute Root Directory: /0_Projects/auth.xuvi.vn
  • Document Root: /0_Projects/auth.xuvi.vn/public
  • Version Control: Git / GitHub

2. Core Architectural & Security Rules

  1. Identity & PK Standard:

    • Universal Unique Identifiers as Primary Keys: Use Ordered UUIDs (str()->orderedUuid()) across all models to prevent MariaDB B-Tree index fragmentation.
    • Password hashing: Argon2id (PASSWORD_ARGON2ID) or Bcrypt (work factor 12+).

  2. OAuth2 & OIDC Engine:

    • Leverage Laravel Passport’s native client architecture for managing applications (oauth_clients).
    • Expose standard discovery endpoints:
      • GET /.well-known/openid-configuration
      • GET /.well-known/jwks.json
    • Support Authorization Code Grant with PKCE (for SPAs/Mobile) and Client Credentials Grant (for Server-to-Server API integration).

  3. Multi-App Authorization (Role Management):

    • Implement a dedicated user_app_roles table linking users to specific Passport oauth_clients with fine-grained application roles.

  4. Cross-Domain Session & CORS Configuration:

    • Session domain configured to .xuvi.vn in .env.
    • Set SESSION_SECURE_COOKIE=true and SESSION_SAMESITE=lax to allow seamless cross-subdomain auth flows.
    • Restrict CORS origin whitelist strictly to https://*.xuvi.vn.

3. Database Schema Blueprint (MariaDB Compatible)

Write clean Laravel migrations utilizing explicit types and foreign key constraints:

  1. users

    • id (UUID / CHAR(36), Primary Key)
    • email (VARCHAR(255), Unique, Indexed)
    • password (VARCHAR(255))
    • full_name (VARCHAR(255), Nullable)
    • status (ENUM: 'pending', 'active', 'suspended', default 'pending')
    • email_verified_at (TIMESTAMP, Nullable)
    • timestamps, softDeletes

  2. Passport Native Tables:

    • Published via php artisan passport:install --uuids.

  3. user_app_roles

    • user_id (UUID, FK -> users.id CASCADE)
    • client_id (UUID, FK -> oauth_clients.id CASCADE)
    • role (VARCHAR(50) — e.g., 'admin', 'editor', 'user')
    • Primary Key: (user_id, client_id)
    • timestamps

4. Execution Workflow

Execute the code generation in four strict, modular steps:

Step 1: Project & Package Setup

  • Initialize Laravel inside /0_Projects/auth.xuvi.vn.
  • Install Passport and OIDC dependencies via Composer.
  • Publish Passport migrations and generate RSA encryption keys (php artisan passport:keys).
  • Create .env.example pre-configured with: 
    APP_URL=[https://auth.xuvi.vn](https://auth.xuvi.vn)
SESSION_DOMAIN=.xuvi.vn
SESSION_SECURE_COOKIE=true
SESSION_SAMESITE=lax
SANCTUM_STATEFUL_DOMAINS=*.xuvi.vn

Step 2: Database Migrations & Models

  • Create User model using HasUuids and Passport's HasApiTokens.
  • Create UserAppRole pivot model and migration.
  • Seed initial test data: 1 super-admin user and 1 test OAuth2 client app.

Step 3: API & OIDC Routing (routes/api.php & routes/web.php)

  • Implement authentication endpoints:

  • POST /v1/auth/register

  • POST /v1/auth/login

  • POST /v1/auth/logout

  • GET /v1/auth/me (Returns user profile + roles per client)

  • Register OIDC metadata routes:

  • GET /.well-known/openid-configuration

  • GET /.well-known/jwks.json

Step 4: cPanel VPS & Deployment Pipeline

Generate production deployment artifacts:

  • .htaccess: Optimized Apache rewrite rules inside /0_Projects/auth.xuvi.vn/public/.htaccess supporting PHP 8.4 and Authorization headers.
  • cPanel Executable Configuration: Explicitly reference cPanel’s PHP 8.4 CLI binary path (/usr/local/bin/ea-php84).
  • GitHub Actions (.github/workflows/deploy.yml): CI/CD pipeline that runs tests, builds assets, and syncs production code to /0_Projects/auth.xuvi.vn via SSH/rsync, followed by running /usr/local/bin/ea-php84 artisan migrate --force.

Expected Deliverables

  1. Complete codebase structure with clean, fully typed code (no // TODO placeholders).
  2. Production-ready Migration files, Models, Controllers, and Middleware.
  3. Fully annotated .env.example.
  4. Working GitHub Actions YAML workflow targeting cPanel VPS.
0727Bigger Dream