API Spec - Identity & Authorization API (Bahasa Indonesia)

Ringkasan
--------
Spesifikasi berikut disesuaikan dengan controller aktual pada aplikasi: modul Auth (OIDC + internal JWT), modul Identity (Users, Roles, Permissions) dan mekanisme otorisasi berbasis permission.

Base URL
--------
- https://api.example.com

Header Umum & Auth
------------------
- Content-Type: application/json
- Accept: application/json
- Otentikasi dapat diberikan dalam dua cara:
  1) Cookie internal (default flow):
     - raylab_jwt    (internal JWT, httpOnly cookie)
     - raylab_refresh (internal refresh token, httpOnly cookie)
  2) Authorization header: Bearer <internal_jwt>
- Banyak endpoint melindungi akses dengan JWT dan permission checks. Respons sukses dari controller umumnya dibungkus sebagai:
  { "success": true, "data": ..., "meta": { ... } }

Auth (modul /auth)
-------------------
1) GET /auth/login
- Deskripsi: Mulai flow Authorization Code + PKCE. Redirect (302) ke Identity Provider.
- Query params:
  - returnTo (optional) - URL tujuan setelah login
- Response: 302 Redirect

2) GET /auth/callback
- Deskripsi: Endpoint callback OIDC. Menukarkan code/state, membuat internal JWT & refresh token, dan menyetel cookie httpOnly.
- Response: 302 Redirect ke returnTo atau '/'
- Cookie yang disetel:
  - raylab_jwt (internal JWT, maxAge sesuai expiresIn)
  - raylab_refresh (refresh token)

3) POST /auth/logout
- Deskripsi: Invalidate internal refresh token (opsional) dan redirect ke logout identity provider.
- Body (optional): { "refreshToken": "..." }
- Response: 302 Redirect

4) POST /auth/refresh
- Deskripsi: Tukar refresh token menjadi internal JWT baru.
- Input: refresh token di cookie raylab_refresh atau di body { "refreshToken": "..." }
- Response 200: { "success": true, "data": { "accessToken": "...", "expiresIn": 3600, ... } }

5) GET /auth/me
- Deskripsi: Ambil data user saat ini dari internal JWT (cookie atau Authorization header).
- Response 200: { "success": true, "data": { /* user object */ } }

Catatan: tidak ada endpoint "/auth/register" atau POST /auth/login berbasis email/password pada controller saat ini — login terjadi via OIDC dan internal session cookies.

Users (modul /users)
--------------------
Semua endpoint Users dijalankan di bawah guards: JwtAuthGuard, CurrentUserGuard dan PermissionGuard. Respons mengikuti format { success, data, meta }.

1) GET /users
- Permission: PermissionType.USER_READ
- Deskripsi: List pengguna (paged)
- Query params umum: page, per_page, sort, q
- Response 200:
  { "success": true, "data": [ /* user list (toResponse) */ ], "meta": { "total": 123 } }

2) GET /users/me
- Deskripsi: Ambil profil user saat ini (token harus ada di cookie atau header)
- Response 200: { "success": true, "data": { /* current user */ }, "meta": {} }

3) GET /users/:id
- Permission: PermissionType.USER_READ
- Deskripsi: Ambil user berdasarkan id
- Response 200: { "success": true, "data": { /* user */ }, "meta": {} }
- 404 jika tidak ditemukan

4) PATCH /users/:id/enable
- Permission: PermissionType.USER_UPDATE
- Deskripsi: Enable user
- Response 200: { "success": true, "data": { /* updated user */ }, "meta": {} }

5) PATCH /users/:id/disable
- Permission: PermissionType.USER_UPDATE
- Deskripsi: Disable user
- Response 200

6) PATCH /users/:id
- Permission: PermissionType.USER_UPDATE
- Deskripsi: Update profil user (body berisi fields yang diperbolehkan)
- Body contoh: { "name": "Nama Baru", "email": "baru@example.com" }
- Response 200: { "success": true, "data": { /* updated user */ }, "meta": {} }

7) DELETE /users/:id
- Permission: PermissionType.USER_DELETE
- Deskripsi: Soft delete user
- Response 200: { "success": true, "data": null, "meta": {} }

8) POST /users/:id/restore
- Permission: PermissionType.USER_UPDATE
- Deskripsi: Restore user yang di-soft-delete
- Response 200: { "success": true, "data": { /* restored user */ }, "meta": {} }

Roles (modul /roles)
--------------------
Semua route dilindungi oleh JwtAuthGuard, CurrentUserGuard dan PermissionGuard.

1) GET /roles
- Permission: PermissionType.ROLE_READ
- Deskripsi: List roles
- Query params: page, per_page, q
- Response 200: { "success": true, "data": [ /* roles */ ], "meta": { "total": 10 } }

2) GET /roles/:id
- Permission: PermissionType.ROLE_READ
- Deskripsi: Ambil role
- Response 200

3) POST /roles
- Permission: PermissionType.ROLE_CREATE
- Deskripsi: Buat role baru
- Body contoh: { "name": "editor", "description": "..." }
- Response 200: { "success": true, "data": { /* created role */ }, "meta": {} }

4) PATCH /roles/:id
- Permission: PermissionType.ROLE_UPDATE
- Deskripsi: Update role
- Response 200

5) DELETE /roles/:id
- Permission: PermissionType.ROLE_DELETE
- Deskripsi: Hapus role
- Response 200: { "success": true, "data": null, "meta": {} }

6) POST /roles/:id/permissions
- Permission: PermissionType.ROLE_UPDATE
- Deskripsi: Assign permission ke role
- Body: { "permissionId": "..." }
- Response 200: { "success": true, "data": { /* updated role */ }, "meta": {} }

7) DELETE /roles/:id/permissions/:permissionId
- Permission: PermissionType.ROLE_UPDATE
- Deskripsi: Remove permission dari role
- Response 200

Permissions (modul /permissions)
-------------------------------
Semua route dilindungi oleh JwtAuthGuard, CurrentUserGuard dan PermissionGuard.

1) GET /permissions
- Permission: PermissionType.PERMISSION_READ
- Deskripsi: List permissions
- Response 200: { "success": true, "data": [ /* permissions */ ], "meta": { "total": 20 } }

2) GET /permissions/:id
- Permission: PermissionType.PERMISSION_READ
- Deskripsi: Ambil permission
- Response 200

3) POST /permissions
- Permission: PermissionType.PERMISSION_CREATE
- Deskripsi: Buat permission baru
- Body contoh: { "name": "user:create", "description": "..." }
- Response 200: { "success": true, "data": { /* created */ }, "meta": {} }

4) PATCH /permissions/:id
- Permission: PermissionType.PERMISSION_UPDATE
- Deskripsi: Update permission
- Response 200

5) DELETE /permissions/:id
- Permission: PermissionType.PERMISSION_DELETE
- Deskripsi: Delete permission
- Response 200: { "success": true, "data": null, "meta": {} }

Format Tanggal dan Numerik
--------------------------
- Tanggal/waktu: ISO 8601 (UTC), contoh: "2024-08-01T12:34:56Z"
- Desimal: titik sebagai pemisah desimal, misal 125000.50

Pagination
----------
- Gunakan page & per_page
- Meta object pada controller ini biasanya minimal: { total }

Response Error Umum
-------------------
- 400 Bad Request - payload tidak valid
  {
    "success": false,
    "error": "invalid_request",
    "message": "Deskripsi kesalahan",
    "details": { "field": ["pesan validasi"] }
  }
- 401 Unauthorized - token tidak ada/invalid/expired
- 403 Forbidden - tidak cukup izin
- 404 Not Found
- 429 Too Many Requests - rate limit
- 500 Internal Server Error

Keamanan dan Persyaratan
------------------------
- Semua permintaan harus lewat HTTPS (TLS 1.2+)
- Gunakan cookie httpOnly (raylab_jwt / raylab_refresh) untuk flow internal atau header Authorization: Bearer <token>
- Validasi input di server (length, tipe, range)
- Sanitasi data untuk mencegah injection

Catatan Akhir
------------
- Spesifikasi ini disesuaikan dengan controller yang ada: /auth, /users, /roles, /permissions dan mekanisme otorisasi berbasis PermissionType.
- Perhatikan bahwa detail field respons (mis. bentuk toResponse pada entitas) dapat berbeda antar resource. Untuk integrasi, gunakan endpoint /auth/me dan /users/me untuk memvalidasi data user yang tersedia.