Skip to main content

Auth Structure Rules (Prompt-Ready)

Dokumen ini adalah standar struktur folder dan boundary untuk context packages/lib/src/auth.

1. Prinsip Utama​

  1. Context auth fokus pada autentikasi token, bukan otorisasi bisnis.
  2. Guard hanya menangani transport concern HTTP (Authorization header + inject request.user).
  3. Query DB untuk verifikasi fallback token statis berada di service token.
  4. Error auth harus konsisten (UnauthorizedException) agar kontrak API stabil.

2. Struktur Folder Standar​

packages/lib/src/auth/
├── auth.module.ts
├── datacore-jwt/
│   ├── datacore-jwt.guard.ts
│   └── datacore-jwt.guard.spec.ts
├── datacore-token/
│   ├── datacore-token.service.ts
│   └── datacore-token.service.spec.ts
├── interfaces/
│   └── decoded-token.interface.ts
└── docs/
    ├── STRUCTURE-RULES.md
    └── auth-system-behavior.md

3. Tanggung Jawab Tiap Layer​

3.1 auth.module.ts​

  1. Registrasi provider auth.
  2. Menentukan export service auth untuk module lain.

3.2 datacore-jwt/*.guard.ts​

  1. Validasi format Authorization header.
  2. Panggil token service untuk verifikasi.
  3. Inject request.user saat valid.
  4. Tidak boleh berisi query DB langsung.

3.3 datacore-token/*.service.ts​

  1. Verifikasi JWT.
  2. Fallback token statis ke tabel user.
  3. Menormalisasi payload hasil verifikasi ke DecodedToken.

3.4 interfaces/*.interface.ts​

  1. Menyimpan kontrak data auth (DecodedToken).
  2. Tidak berisi logic runtime.

4. Aturan Naming​

  1. *.guard.ts untuk auth guard NestJS.
  2. *.service.ts untuk service autentikasi.
  3. *.interface.ts untuk kontrak type.
  4. *.spec.ts untuk unit test colocated.

5. Aturan Boundary (Hitam Putih)​

  1. Guard tidak boleh query DB.
  2. Service tidak boleh menangani concern ack/nak atau transport non-HTTP.
  3. Kontrak DecodedToken harus jadi single source of truth untuk request.user.
  4. Semua perubahan behavior auth wajib update auth-system-behavior.md.

6. Aturan Testing Minimum​

  1. Unit test guard:
  • packages/lib/src/auth/datacore-jwt/datacore-jwt.guard.spec.ts
  1. Unit test token service:
  • packages/lib/src/auth/datacore-token/datacore-token.service.spec.ts
  1. Typecheck minimum:
  • pnpm exec tsc -p packages/lib/tsconfig.json --noEmit

7. Prompt Refactor (Siap Pakai)​

Refactor `packages/lib/src/auth` dengan aturan:
- pertahankan kontrak autentikasi Bearer token
- guard hanya parsing header + inject user
- query fallback token statis tetap di token service
- jangan ubah error contract Unauthorized tanpa kebutuhan eksplisit

Setelah refactor:
1. jalankan unit test guard + token service
2. jalankan typecheck packages/lib
3. update docs `auth-system-behavior.md` jika behavior berubah