@plasgos/oidc-client 0.1.0-next.1 → 0.1.0-next.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/LICENSE +4 -3
  3. package/README.md +27 -14
  4. package/dist/index.cjs +2 -2
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +2 -2
  7. package/dist/index.d.ts +2 -2
  8. package/dist/index.js +2 -2
  9. package/dist/index.js.map +1 -1
  10. package/dist/service.cjs +1 -1
  11. package/dist/service.cjs.map +1 -1
  12. package/dist/service.d.cts +3 -3
  13. package/dist/service.d.ts +3 -3
  14. package/dist/service.js +1 -1
  15. package/dist/service.js.map +1 -1
  16. package/dist/session.cjs +71 -20
  17. package/dist/session.cjs.map +1 -1
  18. package/dist/session.d.cts +57 -6
  19. package/dist/session.d.ts +57 -6
  20. package/dist/session.js +63 -13
  21. package/dist/session.js.map +1 -1
  22. package/dist/{types-Cncksfeo.d.cts → types-JE0OMyoi.d.cts} +1 -1
  23. package/dist/{types-Cncksfeo.d.ts → types-JE0OMyoi.d.ts} +1 -1
  24. package/docs/bff-express.md +1314 -0
  25. package/docs/consumers.md +98 -0
  26. package/docs/contoh-hitungcuan.md +255 -0
  27. package/docs/contoh-plaslink.md +244 -0
  28. package/docs/error.md +613 -0
  29. package/docs/examples/auth-verify-readme.ts +42 -0
  30. package/docs/examples/bff-express.ts +370 -0
  31. package/docs/examples/bff-proxy.ts +335 -0
  32. package/docs/examples/bff-redis-lock.ts +187 -0
  33. package/docs/examples/bff-revocation.ts +136 -0
  34. package/docs/examples/config-error.ts +24 -0
  35. package/docs/examples/env.ts +150 -0
  36. package/docs/examples/failure-log.ts +18 -0
  37. package/docs/examples/login-client.ts +46 -0
  38. package/docs/examples/login-flow.ts +186 -0
  39. package/docs/examples/plaslink-connect.ts +48 -0
  40. package/docs/examples/readme.ts +60 -0
  41. package/docs/examples/service-client.ts +105 -0
  42. package/docs/examples/session-store.ts +53 -0
  43. package/docs/examples/token-commonjs.cjs +95 -0
  44. package/docs/examples/token-express.ts +56 -0
  45. package/docs/examples/token-fetch.ts +24 -0
  46. package/docs/examples/token-nestjs-jest.ts +77 -0
  47. package/docs/examples/token-nestjs.ts +127 -0
  48. package/docs/examples/token-socket.ts +59 -0
  49. package/docs/examples/token-testing.ts +100 -0
  50. package/docs/examples/token-verifier.ts +132 -0
  51. package/docs/examples/user-events.ts +110 -0
  52. package/docs/examples/webhook-express.ts +46 -0
  53. package/docs/examples/webhook-fetch.ts +60 -0
  54. package/docs/examples/webhook-nestjs.ts +59 -0
  55. package/docs/examples/webhook-testing.ts +60 -0
  56. package/docs/examples/webhook-verifier.ts +197 -0
  57. package/docs/login-web.md +650 -0
  58. package/docs/memulai.md +419 -0
  59. package/docs/server-ke-server.md +287 -0
  60. package/docs/verifikasi-token.md +1219 -0
  61. package/docs/webhook.md +810 -0
  62. package/package.json +3 -2
package/docs/error.md ADDED
@@ -0,0 +1,613 @@
1
+ # Error dan kegagalan
2
+
3
+ Acuan untuk semua kegagalan yang bisa datang dari `@plasgos/oidc-client` dan `@plasgos/auth-verify`: artinya, penyebab umum, dan yang harus dilakukan.
4
+
5
+ | Error | Kapan | Bagian |
6
+ |---|---|---|
7
+ | `ConfigError` | Saat start: opsi salah | [§4](#4-configerror), untuk webhook [§7](#configerror-dari-createwebhookverifier), untuk verifikasi token [§8](#configerror-dari-createaccesstokenverifier) |
8
+ | `OidcError` | Saat berjalan: login, refresh, atau token service gagal | [§1](#1-oidcerror) |
9
+ | `SessionTooLargeError` | Cookie sesi tidak muat | [§5](#5-sessiontoolargeerror) |
10
+ | `TypeError` | Argumen fungsi salah (bug di kode pemanggil) | [§6](#6-typeerror) |
11
+ | `WebhookVerifyError` | Kiriman webhook ditolak (`@plasgos/auth-verify/webhook`) | [§7](#7-webhookverifyerror) |
12
+ | `AuthVerifyError` | Access token ditolak (`@plasgos/auth-verify`, `/express`, `/nestjs`) | [§8](#8-authverifyerror) |
13
+
14
+ Aturan yang berlaku untuk semuanya: pesan error dan event **tidak pernah** memuat token, klaim token, code, secret, isi cookie, isi jawaban Plasgos, tanda tangan webhook, nilai header, atau isi body webhook. Semuanya aman ditulis ke log.
15
+
16
+ ## 1. `OidcError`
17
+
18
+ | Properti | Isi |
19
+ |---|---|
20
+ | `name` | `"OidcError"` |
21
+ | `reason` | Kode alasan (tabel di bawah) |
22
+ | `message` | `"OIDC <reason>"`, tidak lebih |
23
+ | `upstream` | `{ method, path, status, requestId }` dari panggilan ke Plasgos yang gagal, atau `null` bila kegagalan terjadi sebelum ada panggilan |
24
+
25
+ Dari mana `OidcError` bisa datang:
26
+
27
+ | Fungsi | Melempar `OidcError`? |
28
+ |---|---|
29
+ | `client.handleCallback` | Ya |
30
+ | `client.refresh`, `client.ensureFresh` | Ya |
31
+ | `serviceClient.getToken`, `serviceClient.fetch` | Ya |
32
+ | `client.logout` | **Tidak pernah.** Kegagalannya hanya dilaporkan lewat `onFailure` |
33
+ | `client.startLogin` | Tidak. Ia tidak memanggil Plasgos |
34
+
35
+ ### Semua `reason`
36
+
37
+ | `reason` | Arti | Datang dari |
38
+ |---|---|---|
39
+ | [`state_mismatch`](#state_mismatch) | `state` di callback tidak cocok dengan transaksi | `handleCallback` |
40
+ | [`expired`](#expired) | Transaksi login lebih tua dari 10 menit | `handleCallback` |
41
+ | [`missing`](#missing) | Ada yang seharusnya ada tetapi tidak ada: transaksi, `code`, atau refresh token | `handleCallback`, `refresh`, `ensureFresh` |
42
+ | [`provider_error`](#provider_error) | Plasgos menolak atau menjawab di luar dugaan | Semua |
43
+ | [`invalid_grant`](#invalid_grant) | `code` atau refresh token ditolak | `handleCallback`, `refresh`, `ensureFresh` |
44
+ | [`invalid_target`](#invalid_target) | `resource` (audience) ditolak | Semua |
45
+ | [`id_token_invalid`](#id_token_invalid) | ID token tidak lolos pemeriksaan | `handleCallback` |
46
+ | [`unavailable`](#unavailable) | Plasgos tidak bisa dihubungi atau sedang gangguan | Semua |
47
+ | [`config_invalid`](#config_invalid) | Plasgos menolak konfigurasi client ini | `handleCallback`, `refresh`, `ensureFresh`, `getToken`, `fetch` |
48
+
49
+ "Semua" berarti `handleCallback`, `refresh`, `ensureFresh`, `getToken`, dan `fetch` milik client service.
50
+
51
+ ### `state_mismatch`
52
+
53
+ - **Arti:** parameter `state` di URL callback tidak ada, atau tidak sama dengan yang disimpan di cookie transaksi.
54
+ - **Penyebab umum:** user membuka dua tab login dan menyelesaikan yang lebih lama; URL callback lama dibuka lagi dari riwayat atau bookmark; percobaan menyisipkan callback dari situs lain.
55
+ - **Yang dilakukan:** tampilkan halaman "login gagal" dengan tombol coba lagi. Jangan dilanjutkan. Hapus cookie transaksi.
56
+
57
+ ### `expired`
58
+
59
+ - **Arti:** transaksi login dibuat lebih dari 10 menit lalu, atau waktunya berada lebih dari 5 detik di masa depan.
60
+ - **Penyebab umum:** user terlalu lama di halaman login; jam server antar instance tidak sama.
61
+ - **Yang dilakukan:** mulai login lagi. Bila sering terjadi, periksa sinkronisasi jam server.
62
+
63
+ ### `missing`
64
+
65
+ - **Arti di `handleCallback`:** cookie transaksi tidak ada atau tidak terbaca, URL callback tidak bisa diurai, atau URL tidak memuat tepat satu `code`.
66
+ - **Penyebab umum:** cookie diblokir browser; callback dibuka di browser lain dari tempat login dimulai (termasuk PWA iOS yang cookie-nya terpisah); callback dimuat ulang setelah cookie transaksi dihapus; `SESSION_SECRET` berbeda antar instance.
67
+ - **Arti di `refresh` / `ensureFresh`:** access token sudah habis (atau `force`) dan sesi tidak punya refresh token.
68
+ - **Penyebab umum:** client pihak ketiga tanpa `offline_access`, jadi memang tidak ada refresh token.
69
+ - **Yang dilakukan:** di callback, mulai login lagi. Di refresh, hapus `auth` dari sesi dan arahkan user ke login.
70
+
71
+ ### `provider_error`
72
+
73
+ - **Arti:** Plasgos menolak dengan alasan yang tidak punya kode khusus di SDK, atau jawabannya tidak sesuai bentuk yang diharapkan.
74
+ - **Penyebab umum:**
75
+ - callback membawa `error=…`, misalnya `access_denied` karena user menolak persetujuan (`providerError` di event berisi kodenya);
76
+ - `iss` di callback bukan issuer yang dikonfigurasi;
77
+ - jawaban endpoint token bukan JSON token yang benar, lebih besar dari 16 KiB, atau berupa redirect (`3xx`; SDK tidak pernah mengikuti redirect);
78
+ - client first-party tidak menerima refresh token.
79
+ - **Yang dilakukan:** di callback, tampilkan "login gagal" dan tawarkan coba lagi. Di tempat lain, jangan hapus sesi. Bila berulang, laporkan ke tim Plasgos dengan `requestId`.
80
+
81
+ ### `invalid_grant`
82
+
83
+ - **Arti:** `code` atau refresh token tidak diterima Plasgos.
84
+ - **Penyebab umum:** `code` dipakai dua kali atau sudah kedaluwarsa (callback dimuat ulang); refresh token sudah diganti, dicabut, atau sesi user di Plasgos sudah berakhir (misalnya logout di tempat lain, atau akses aplikasi dicabut); refresh token yang sama dipakai dua kali oleh dua instance tanpa `refreshLock` bersama.
85
+ - **Yang dilakukan:** di callback, mulai login lagi. Di `refresh` / `ensureFresh`, **sesi berakhir**: hapus `auth` dari sesi dan arahkan user ke login.
86
+
87
+ ### `invalid_target`
88
+
89
+ - **Arti:** Plasgos menolak `resource` (audience) yang diminta.
90
+ - **Penyebab umum:** `resource` bukan audience lingkungan itu (misalnya audience production di sandbox yang memakai audience sendiri); client tidak diizinkan memakai audience itu.
91
+ - **Yang dilakukan:** ini bug konfigurasi. Perbaiki `resource`. Di `refresh` / `ensureFresh`, sesi berakhir (refresh token sudah terpakai): hapus `auth` dan arahkan user ke login. Di client service, isi `resource` dengan audience yang diberikan tim Plasgos.
92
+
93
+ ### `id_token_invalid`
94
+
95
+ - **Arti:** ID token dari Plasgos tidak ada, atau tidak lolos salah satu pemeriksaan: `alg`, `iss`, `aud`, `azp`, `exp`, `iat`, `nonce`, atau `auth_time` saat `maxAge` diminta. Error sengaja tidak menyebut pemeriksaan yang gagal.
96
+ - **Penyebab umum:** jam server meleset lebih dari 60 detik; `issuer` di konfigurasi tidak sama persis dengan issuer Plasgos lingkungan itu; `clientId` salah.
97
+ - **Yang dilakukan:** periksa jam server (NTP) dan nilai `issuer`. User mencoba login lagi.
98
+
99
+ ### `unavailable`
100
+
101
+ - **Arti:** tidak ada jawaban yang bisa dipakai dari Plasgos.
102
+ - **Penyebab umum:** jaringan putus, DNS, timeout (`timeouts`), jawaban `5xx`, atau `429`.
103
+ - **Yang dilakukan:** boleh diulang dengan jeda. Di callback, tampilkan "coba lagi sebentar" (`503`). Di `ensureFresh`: selama access token masih berlaku, kegagalan ini ditelan dan sesi tetap dipakai; setelah token habis, jawab `503` **tanpa menghapus sesi**. Di client service, ulangi nanti.
104
+
105
+ ### `config_invalid`
106
+
107
+ - **Arti:** endpoint token Plasgos menjawab bahwa konfigurasi client ini sendiri yang salah: `invalid_client`, `unauthorized_client`, `invalid_scope`, atau `unsupported_grant_type`. Kode aslinya ada di `providerError` pada event.
108
+ - **Penyebab umum:** client secret salah atau sudah dirotasi; client dinonaktifkan atau dicabut; scope yang diminta tidak terdaftar pada client; beberapa scope digabung dengan koma dalam satu string.
109
+ - **Ini bug konfigurasi, bukan akhir sesi user.**
110
+ - Pasang alert untuk `reason === "config_invalid"` di `onFailure`. Kegagalan ini tidak sembuh sendiri.
111
+ - **Jangan hapus sesi user.** `ensureFresh` tetap mengembalikan sesi selama access token masih berlaku. Setelah token habis, request gagal (`500`) tanpa menghapus sesi. Begitu konfigurasi diperbaiki, user lanjut tanpa login ulang.
112
+ - Jangan diulang otomatis.
113
+ - **Bedanya dengan `ConfigError`:** `ConfigError` dilempar SDK saat start, sebelum ada panggilan ke Plasgos, untuk opsi yang bentuknya salah. `config_invalid` datang dari Plasgos saat berjalan, untuk opsi yang bentuknya benar tetapi nilainya ditolak.
114
+
115
+ ## 2. `OidcFailureEvent`
116
+
117
+ SDK tidak pernah menulis log. Setiap kegagalan, yang dilempar maupun yang ditelan (logout, refresh yang ditoleransi), diserahkan ke hook `onFailure` sebagai satu event:
118
+
119
+ | Field | Isi |
120
+ |---|---|
121
+ | `environment` | `"sandbox"` atau `"production"` |
122
+ | `operation` | Langkah yang gagal: `callback`, `token`, `refresh`, `revocation`, `logout_ticket`, `service_token`, `service_request` |
123
+ | `reason` | `reason` yang sama dengan `OidcError` |
124
+ | `method` | Method HTTP panggilan yang gagal, atau `null` |
125
+ | `path` | Path panggilan yang gagal, tanpa query, atau `null` |
126
+ | `status` | Status HTTP jawaban Plasgos, atau `null` bila tidak ada jawaban |
127
+ | `requestId` | `x-request-id` dari jawaban Plasgos, atau `null`. Sertakan saat melapor ke tim Plasgos |
128
+ | `providerError` | Kode `error` dari Plasgos (misalnya `invalid_client`, `access_denied`), atau `null` |
129
+
130
+ Arti `operation`:
131
+
132
+ | `operation` | Langkah |
133
+ |---|---|
134
+ | `callback` | Pemeriksaan URL callback dan ID token |
135
+ | `token` | Menukar `code` dengan token |
136
+ | `refresh` | Refresh token |
137
+ | `revocation` | Mencabut refresh token saat logout |
138
+ | `logout_ticket` | Meminta logout ticket saat logout |
139
+ | `service_token` | Permintaan token client service |
140
+ | `service_request` | Panggilan `fetch` client service yang tidak sampai |
141
+
142
+ Contoh hook yang menulis satu baris per kegagalan dan memberi tanda untuk alert:
143
+
144
+ <!-- snippet: examples/snippets/failure-log.ts -->
145
+ ```ts
146
+ import type { OidcFailureEvent } from "@plasgos/oidc-client";
147
+
148
+ /** One line per failure. The event never holds a token, a secret or a response body, so it is safe to log. */
149
+ export function logFailure(event: OidcFailureEvent): void {
150
+ const line = [
151
+ "plasgos auth failed:",
152
+ `env=${event.environment}`,
153
+ `operation=${event.operation}`,
154
+ `reason=${event.reason}`,
155
+ `call=${event.method ?? "-"} ${event.path ?? "-"}`,
156
+ `status=${event.status === null ? "-" : String(event.status)}`,
157
+ `request_id=${event.requestId ?? "-"}`,
158
+ `provider_error=${event.providerError ?? "-"}`,
159
+ ].join(" ");
160
+ process.stderr.write(`${line}\n`);
161
+ // A wrong secret, scope or grant is a bug in this app's configuration: page someone.
162
+ if (event.reason === "config_invalid") process.stderr.write("ALERT plasgos client configuration refused\n");
163
+ }
164
+ ```
165
+ <!-- /snippet -->
166
+
167
+ Exception yang dilempar hook diabaikan SDK. Hook tidak bisa mengubah hasil operasi.
168
+
169
+ ## 3. `instanceof` dan dua loader
170
+
171
+ Setiap paket tersedia sebagai ESM dan CommonJS. Keduanya adalah dua salinan modul yang berbeda, jadi kelas `OidcError` dari `import` bukan kelas yang sama dengan `OidcError` dari `require`. Hal yang sama berlaku untuk `WebhookVerifyError`, `AuthVerifyError`, dan `ConfigError`.
172
+
173
+ - Aplikasi yang hanya memakai satu cara (semua `import`, atau semua `require`): `error instanceof OidcError` dan `error instanceof WebhookVerifyError` bekerja.
174
+ - Aplikasi yang mencampur keduanya (misalnya kode ESM dan sebuah dependensi CommonJS yang sama-sama memuat SDK): periksa nama dan `reason`, bukan `instanceof`:
175
+
176
+ ```text
177
+ error.name === "OidcError" lalu baca error.reason
178
+ error.name === "WebhookVerifyError" lalu baca error.reason dan error.header
179
+ error.name === "AuthVerifyError" lalu baca error.reason, error.status, error.errorCode, error.wwwAuthenticate
180
+ error.name === "ConfigError" lalu baca error.problems
181
+ ```
182
+
183
+ `ConfigError` diekspor oleh `@plasgos/oidc-client`, `/session`, dan `/service`, dan ketiganya adalah kelas yang sama. Bila kelasnya di-import dari `@plasgos/oidc-client`, `error instanceof ConfigError` bekerja dengan aturan yang sama seperti `OidcError` di atas. Contoh di [`memulai.md` §7](memulai.md#7-bila-konfigurasi-salah) tetap memeriksa `error.name`, supaya juga bekerja di aplikasi yang mencampur `import` dan `require`.
184
+
185
+ `ConfigError` yang diekspor `@plasgos/auth-verify`, `/webhook`, `/express`, dan `/nestjs` adalah kelas yang sama dengan `ConfigError` dari `@plasgos/oidc-client`, karena semuanya berasal dari `@plasgos/auth-shared`. `WebhookVerifyError` dan `AuthVerifyError` juga berasal dari sana: `AuthVerifyError` dari `@plasgos/auth-verify`, `/express`, dan `/nestjs` adalah satu kelas. Aturan dua loader di atas tetap berlaku. Middleware Express, guard NestJS, dan `authErrorResponse` sudah mengenali `AuthVerifyError` dari kedua loader.
186
+
187
+ ## 4. `ConfigError`
188
+
189
+ Dilempar oleh `createOidcClient`, `createServiceClient`, `createSessionStore`, `createWebhookVerifier`, dan `createAccessTokenVerifier` saat dipanggil. Pesan khusus webhook ada di [§7](#configerror-dari-createwebhookverifier), dan pesan khusus verifikasi token di [§8](#configerror-dari-createaccesstokenverifier).
190
+
191
+ | Properti | Isi |
192
+ |---|---|
193
+ | `name` | `"ConfigError"` |
194
+ | `problems` | Daftar semua masalah, satu string per masalah |
195
+ | `message` | `"Invalid Plasgos auth configuration:"` diikuti daftar yang sama |
196
+
197
+ Semua masalah dilaporkan sekaligus. Pesan hanya menyebut nama opsi, tidak pernah nilainya. Nama scope disebut hanya bila scope itu dikenal SDK.
198
+
199
+ Di tabel berikut, `<opsi>` adalah nama opsi dan `<scope>` adalah nama scope.
200
+
201
+ ### Lingkungan (`environment`)
202
+
203
+ Berlaku untuk `createOidcClient` dan `createServiceClient`. Baris pertama juga berlaku untuk `createSessionStore`.
204
+
205
+ | Pesan | Perbaikan |
206
+ |---|---|
207
+ | `environment must be "sandbox" or "production"` | Isi `environment` (env `PLASGOS_ENV`) dengan salah satu dari dua nilai itu. Tidak ada nilai bawaan |
208
+ | `environment is "production" but issuer is not the production issuer` | Di production, `issuer` harus persis `https://accounts.plasgos.co.id` |
209
+ | `environment is "production" but resource is not a production audience` | Di production, `resource` harus diawali `https://api.plasgos.co.id/` |
210
+ | `allowInsecureHttp is not allowed when environment is "production"` | Hapus `allowInsecureHttp` di production |
211
+ | `environment is "sandbox" but issuer is a production host` | Kredensial sandbox tidak boleh diarahkan ke production. Pakai issuer sandbox, atau ganti `environment` dan kredensialnya ke production |
212
+ | `environment is "sandbox" but backchannelUrl is a production host` | Sama, untuk `backchannelUrl` |
213
+ | `environment is "sandbox" but apiUrl is a production host` | Sama, untuk `apiUrl` |
214
+
215
+ ### URL
216
+
217
+ | Pesan | Berlaku untuk | Perbaikan |
218
+ |---|---|---|
219
+ | `<opsi> is required` | `issuer`, `apiUrl`, `redirectUri`, `clientId`, `clientSecret` | Isi opsi itu. Biasanya env-nya kosong; nilai yang hanya berisi spasi juga dianggap kosong. Opsi tidak wajib yang kosong (`postLogoutRedirectUri`, `backchannelUrl`, `resource`) dianggap tidak diisi |
220
+ | `<opsi> must be a string` | Semua opsi teks | Nilainya bukan string (misalnya objek `URL` atau angka) |
221
+ | `<opsi> must be an absolute URL` | Semua URL | Tulis URL lengkap dengan skema: `https://…` |
222
+ | `<opsi> must use https` | `issuer`, `resource`, `redirectUri`, `postLogoutRedirectUri` | Pakai `https`. Untuk development lokal: `environment: "sandbox"` dan `allowInsecureHttp: true` |
223
+ | `<opsi> must be an origin without a path` | `issuer`, `backchannelUrl`, `apiUrl` | Hapus path. Benar: `https://accounts.plasgos.co.id`. Salah: `https://accounts.plasgos.co.id/oidc` |
224
+ | `<opsi> must be a canonical origin (lower-case scheme and host, no default port)` | `issuer`, `backchannelUrl`, `apiUrl` | Tulis dengan huruf kecil dan tanpa port bawaan (`:443`, `:80`) |
225
+ | `<opsi> must not contain a query` | `issuer`, `backchannelUrl`, `apiUrl`, `resource` | Hapus `?…` |
226
+ | `<opsi> must not contain a fragment` | Semua URL | Hapus `#…` |
227
+ | `<opsi> must not contain credentials` | Semua URL | Hapus `user:pass@` dari URL |
228
+ | `<opsi> must not contain whitespace, control characters or a backslash` | `resource`, `redirectUri`, `postLogoutRedirectUri` | Periksa spasi atau karakter tersembunyi di nilai env |
229
+ | `<opsi> must not contain a wildcard` | `redirectUri`, `postLogoutRedirectUri` | Tulis URL yang persis, tanpa `*` |
230
+
231
+ `redirectUri` dan `postLogoutRedirectUri` boleh memuat query, selama sama persis dengan yang didaftarkan di Plasgos.
232
+
233
+ ### Scope
234
+
235
+ | Pesan | Perbaikan |
236
+ |---|---|
237
+ | `scopes must be a non-empty list` | `scopes` harus array berisi minimal satu string |
238
+ | `scopes contains a value that is not a valid scope token` | Ada elemen yang bukan string, kosong, atau memuat spasi. Tulis satu scope per elemen |
239
+ | `scopes must include "openid"` | Client login wajib meminta `openid` |
240
+ | `scopes: "<scope>" is a service scope; use createServiceClient from @plasgos/oidc-client/service` | Scope service diberikan ke `createOidcClient`. Pakai `createServiceClient` dengan kredensial client service |
241
+ | `scopes: "<scope>" is a user scope; use createOidcClient from @plasgos/oidc-client` | Scope user diberikan ke `createServiceClient`. Pakai `createOidcClient` dengan kredensial client login |
242
+ | `scopes: "<scope>" is for first-party clients only` | Client `third-party` meminta scope khusus aplikasi Plasgos. Hapus scope itu |
243
+ | `scopes: "<scope>" requires the resource option` | Scope `account:*` / `packages:*` butuh `resource` |
244
+
245
+ ### `createOidcClient`
246
+
247
+ | Pesan | Perbaikan |
248
+ |---|---|
249
+ | `options must be an object` | Argumen bukan objek |
250
+ | `profile must be "first-party" or "third-party"` | Isi `profile` |
251
+ | `resource is not allowed for profile "third-party"` | Client pihak ketiga tidak memakai `resource`. Hapus |
252
+ | `logoutTicket must be a boolean` | Pakai `true` atau `false`, bukan string |
253
+ | `logoutTicket is not allowed for profile "third-party"` | Hanya first-party yang boleh. Hapus |
254
+ | `logoutTicket is not used with endSession "form-post"` | Pilih salah satu |
255
+ | `logoutTicket requires backchannelUrl (the internal Plasgos server URL)` | Isi `backchannelUrl`, atau hapus `logoutTicket: true` |
256
+ | `endSession must be "redirect" or "form-post"` | Perbaiki nilainya |
257
+ | `endSession "form-post" requires redirectUri on the issuer origin` | Hanya di production. `"form-post"` hanya untuk aplikasi di origin issuer. Aplikasi lain memakai `"redirect"` |
258
+ | `extraClaims contains an invalid claim name` | `extraClaims` harus array nama klaim (huruf, angka, `_ : . -`, 1–64 karakter). Klaim standar (`sub`, `email`, …) tidak boleh didaftarkan: nama itu ditolak dengan pesan yang sama. `null` juga ditolak; tanpa klaim tambahan, hapus opsinya |
259
+ | `allowInsecureHttp must be a boolean` | Pakai `true` atau `false`. String `"true"` dari env ditolak |
260
+ | `timeouts must be an object` | Bentuknya `{ tokenMs, logoutMs }` |
261
+ | `timeouts.<nama> must be an integer from 1 to 60000` | Bilangan bulat dalam milidetik |
262
+ | `fetch must be a function`, `onFailure must be a function` | Perbaiki tipe nilainya |
263
+ | `refreshLock must have a run function` | `refreshLock` harus memenuhi `RefreshLockStore` |
264
+
265
+ ### `createServiceClient`
266
+
267
+ Pesan lingkungan, URL, dan scope di atas, ditambah `options must be an object`, `allowInsecureHttp must be a boolean`, `timeouts must be an object`, `timeouts.<nama> must be an integer from 1 to 60000` (`tokenMs`, `requestMs`), `fetch must be a function`, dan `onFailure must be a function`.
268
+
269
+ ### `createSessionStore`
270
+
271
+ | Pesan | Perbaikan |
272
+ |---|---|
273
+ | `options must be an object` | Argumen bukan objek |
274
+ | `environment must be "sandbox" or "production"` | Beri nilai yang sama dengan client |
275
+ | `hostPrefix must be a boolean` | Pakai `true` atau `false` |
276
+ | `hostPrefix: false is not allowed when environment is "production"` | Production selalu memakai awalan (`__Host-`, atau `__Secure-` dengan `path` lain) dan `Secure`. Hapus `hostPrefix: false` |
277
+ | `path must be a string` | `path` bukan string. Hapus, atau tulis seperti `"/crm/"` |
278
+ | `path must start and end with "/" and contain only printable ASCII without ";", ",", "%", ".." or "//"` | `path` harus diawali dan diakhiri `/`, tanpa spasi, karakter kontrol, huruf non-ASCII, `;`, `,`, `%`, `..`, atau `//`. Contoh: `"/crm/"` ([`login-web.md` §6](login-web.md#aplikasi-di-bawah-sub-path)) |
279
+ | `hkdfSalt is required`, `hkdfSalt must be a string` | Isi `hkdfSalt` dengan string tetap |
280
+ | `secrets must hold one or two values` | `secrets` harus array berisi satu atau dua string. Periksa `SESSION_SECRET` |
281
+ | `secrets values must each be at least 32 bytes` | Buat secret yang lebih panjang |
282
+ | `cookies.<peran> must match /^[a-z0-9-]{1,32}$/` | Nama cookie `app`, `auth`, `idToken`, `transaction` wajib ada: huruf kecil, angka, `-` |
283
+ | `cookies names must be distinct` | Keempat nama harus berbeda |
284
+ | `authMaxAgeSeconds must be a positive integer or a function` | Isi dengan detik (bilangan bulat positif) atau fungsi |
285
+ | `authMaxAgeSeconds must return a positive integer` | Dilempar saat cookie ditulis: fungsi `authMaxAgeSeconds` mengembalikan nilai yang salah |
286
+ | `appSchema must have a parse function` | Beri `{ parse(input) }` |
287
+ | `compactKeys must be an object` | Beri objek `{ panjang: "ringkas" }`, atau hapus |
288
+ | `compactKeys: keys must match /^[A-Za-z0-9_]{1,32}$/ and must not be a reserved name` | Perbaiki nama kunci |
289
+ | `compactKeys: "<kunci>" must map to "<ringkas>"` | Kunci itu ada di tabel inti SDK dan harus memakai nama ringkas yang sama |
290
+ | `compactKeys: short key "<ringkas>" is used twice` | Dua kunci panjang memakai nama ringkas yang sama |
291
+ | `compactKeys: short key "<ringkas>" is also a long key` | Nama ringkas tidak boleh sama dengan nama panjang lain |
292
+ | `onFailure must be a function` | Perbaiki tipe nilainya |
293
+
294
+ ## 5. `SessionTooLargeError`
295
+
296
+ Diekspor dari `@plasgos/oidc-client/session`.
297
+
298
+ - **Arti:** satu `Set-Cookie` akan lebih besar dari 4000 karakter, batas yang masih diterima browser.
299
+ - **Dilempar oleh:** `commitApp`, `commitAuth`, `commitIdToken`. `commit()` **tidak** melemparnya: ia menghapus cookie yang tidak muat, membuang datanya dari sesi, dan memanggil `onFailure` milik store dengan `{ kind: "session_too_large", cookie, size }`.
300
+ - **Isi:** `name` (`"SessionTooLargeError"`), `size`, dan pesan `Session cookie too large: <size> chars (limit 4000)`. Tidak pernah isi cookie.
301
+ - **Penyebab umum:** terlalu banyak data di cookie `app`; token yang sangat panjang.
302
+ - **Yang dilakukan:** simpan lebih sedikit di cookie `app` (data besar ke database). Di callback, panggil `store.fits(auth)` sebelum menyimpan login ([`login-web.md` §4](login-web.md#callback)).
303
+
304
+ ## 6. `TypeError`
305
+
306
+ `TypeError` berarti kode pemanggil memberi argumen yang salah. Ini bug di aplikasi, bukan kegagalan Plasgos, dan tidak dilaporkan lewat `onFailure`.
307
+
308
+ | Pesan | Penyebab |
309
+ |---|---|
310
+ | `startLogin: returnTo must start with exactly one "/" and be at most 512 characters` | `returnTo` belum disanitasi |
311
+ | `startLogin: prompt must be "login", "consent" or "none"` | Nilai `prompt` salah |
312
+ | `startLogin: maxAge must be a non-negative integer` | `maxAge` bukan bilangan bulat ≥ 0 |
313
+ | `startLogin: loginHint must be a string of at most 512 characters` | `loginHint` terlalu panjang atau bukan string |
314
+ | `startLogin: reauth must be a boolean`, `startLogin: input must be an object`, `startLogin: now must be a finite number` | Tipe argumen salah |
315
+ | `skewSeconds must be a non-negative integer` | Opsi `ensureFresh` salah |
316
+ | `serviceClient.fetch: path must start with a single /` | `path` berupa URL lengkap, diawali `//`, atau tidak diawali `/` |
317
+ | `serviceClient.fetch: init must be an object` | Argumen kedua `fetch` bukan objek |
318
+
319
+ Selain itu, `serviceClient.fetch` meneruskan pembatalan dari `init.signal` milik pemanggil apa adanya (alasan `abort` yang Anda berikan).
320
+
321
+ `TypeError` dari verifikasi webhook ada di [§7](#typeerror-dari-verify), dan dari verifikasi token di [§8](#typeerror-dan-error-dari-verifikasi-token).
322
+
323
+ ## 7. `WebhookVerifyError`
324
+
325
+ Dilempar oleh `verifier.verify` dan `verifyWebhook` dari `@plasgos/auth-verify/webhook` bila sebuah kiriman webhook ditolak. Cara menanganinya ada di [`webhook.md` §6](webhook.md#6-menangani-kiriman).
326
+
327
+ | Properti | Isi |
328
+ |---|---|
329
+ | `name` | `"WebhookVerifyError"` |
330
+ | `reason` | Kode alasan (tabel di bawah) |
331
+ | `header` | Header yang bermasalah: `"id"`, `"type"`, `"timestamp"`, atau `"signature"`. Hanya untuk `missing_header`, `malformed_header`, dan `header_mismatch`; selain itu `null` |
332
+ | `message` | `"Webhook <reason>"`, tidak lebih |
333
+
334
+ `header` menyebut peran header, bukan namanya. Untuk `presets.payments`, `"signature"` berarti `X-Signature`; untuk `presets.plaslinkShipping`, `X-Plasgos-Signature`. Pesan dan properti tidak pernah memuat secret, tanda tangan, nilai header, atau isi body.
335
+
336
+ ### Semua `reason`
337
+
338
+ Diperiksa dengan urutan berikut. Kegagalan pertama yang ditemukan yang dilaporkan.
339
+
340
+ | `reason` | Arti | Jawaban HTTP |
341
+ |---|---|---|
342
+ | [`missing_header`](#missing_header) | Salah satu dari empat header tidak ada | `400` |
343
+ | [`malformed_header`](#malformed_header) | Header ada, tetapi bentuknya salah | `400` |
344
+ | [`body_too_large`](#body_too_large) | Body lebih besar dari `maxBodyBytes` | `400` |
345
+ | [`stale_timestamp`](#stale_timestamp) | Waktu kirim di luar `toleranceSeconds` | `401` |
346
+ | [`signature_mismatch`](#signature_mismatch) | Tidak ada tanda tangan `v1` yang cocok dengan secret | `401` |
347
+ | [`invalid_body`](#invalid_body) | Body yang ditandatangani bukan objek JSON dengan `id` dan `type` berupa string | `400` |
348
+ | [`header_mismatch`](#header_mismatch) | `id` atau `type` di body berbeda dari header | `400` |
349
+
350
+ Plasgos mengulang setiap jawaban selain `2xx` ([`webhook.md` §2](webhook.md#2-aturan-pengiriman)). Kiriman yang ditolak karena kesalahan di sisi Anda (secret salah, jam server meleset) terus diulang sampai batasnya (bawaannya 15 percobaan, sekitar 6,4 jam, untuk payments dan 20 percobaan, sekitar 11,4 jam, untuk pengiriman Plaslink), lalu menahan event berikutnya untuk payment atau pengiriman yang sama sampai tim Plasgos mengirim ulang atau melewatinya. Event yang dilewati membuat `sequence` melompat ([`webhook.md` §1](webhook.md#1-apa-itu-webhook-plasgos)). Perbaiki penyebabnya, lalu minta tim Plasgos mengirim ulang atau melewatinya.
351
+
352
+ ### `missing_header`
353
+
354
+ - **Arti:** salah satu header id, type, waktu kirim, atau tanda tangan tidak ada. `header` menyebut yang mana.
355
+ - **Penyebab umum:** request bukan dari Plasgos (pemindai, panggilan manual); proxy membuang header; preset salah, misalnya kiriman pengiriman Plaslink diperiksa dengan `presets.payments`.
356
+ - **Yang dilakukan:** jawab `400`. Bila semua kiriman asli gagal dengan alasan ini, periksa preset dan konfigurasi proxy.
357
+
358
+ ### `malformed_header`
359
+
360
+ - **Arti:** header ada, tetapi isinya tidak sesuai format. Id dan type: huruf, angka, `_ . : -`, paling panjang 200 karakter. Waktu kirim: angka saja (detik epoch), tanpa nol di depan, paling panjang 15 digit. Tanda tangan: paling panjang 1024 karakter, paling banyak 10 nilai dipisah koma, minimal satu `v1=` diikuti tepat 64 karakter hex. Juga dilaporkan bila objek header memuat nama yang sama dua kali dengan huruf besar dan kecil berbeda, atau nilai yang bukan string.
361
+ - **Penyebab umum:** request bukan dari Plasgos; proxy menggabungkan atau mengulang header; kode test yang menyusun header sendiri.
362
+ - **Yang dilakukan:** jawab `400`. Pada test, bandingkan dengan `signTestDelivery` di [`webhook.md` §10](webhook.md#10-menguji-penerima).
363
+
364
+ ### `body_too_large`
365
+
366
+ - **Arti:** body mentah lebih besar dari `maxBodyBytes` (bawaan 1 MiB). Diperiksa sebelum tanda tangan dihitung.
367
+ - **Penyebab umum:** request bukan dari Plasgos; `maxBodyBytes` diatur terlalu kecil.
368
+ - **Yang dilakukan:** jawab `400`. Batas body di framework tetap wajib, karena `maxBodyBytes` hanya menolak body yang sudah terbaca ([`webhook.md` §5](webhook.md#5-body-mentah-per-framework)).
369
+
370
+ ### `stale_timestamp`
371
+
372
+ - **Arti:** waktu kirim berbeda lebih dari `toleranceSeconds` (bawaan 300 detik) dari jam server, ke masa lalu atau ke masa depan.
373
+ - **Penyebab umum:** jam server meleset; kiriman lama yang diputar ulang; request tertahan lama di antrean atau proxy sebelum sampai ke `verify`.
374
+ - **Yang dilakukan:** jawab `401`. Periksa sinkronisasi jam server (NTP). Jangan menaikkan `toleranceSeconds` untuk menutupi jam yang salah.
375
+
376
+ ### `signature_mismatch`
377
+
378
+ - **Arti:** tidak ada nilai `v1=` di header tanda tangan yang cocok dengan salah satu secret di `secrets`.
379
+ - **Penyebab umum:**
380
+ - secret salah: secret sandbox di production, secret lama setelah rotasi selesai, atau secret jenis lain (secret payments untuk pengiriman Plaslink);
381
+ - body berubah sebelum diverifikasi: JSON di-parse lalu di-`JSON.stringify` lagi, body parser global berjalan lebih dulu, atau proxy mengubah body;
382
+ - request palsu.
383
+ - **Yang dilakukan:** jawab `401`. Bila semua kiriman asli gagal dengan alasan ini, periksa secret dan pastikan body mentah yang diberikan ke `verify`. Pasang alert: alasan ini yang berulang biasanya berarti secret salah, dan antrean akan tertahan.
384
+
385
+ ### `invalid_body`
386
+
387
+ - **Arti:** tanda tangan cocok, tetapi body bukan UTF-8 yang sah, bukan JSON, bukan objek, atau tidak punya `id` dan `type` berupa string.
388
+ - **Penyebab umum:** tidak terjadi pada kiriman Plasgos. Biasanya kode test yang menandatangani body yang salah.
389
+ - **Yang dilakukan:** jawab `400`. Bila terjadi pada kiriman asli, laporkan ke tim Plasgos dengan waktu kirim dan header id event-nya.
390
+
391
+ ### `header_mismatch`
392
+
393
+ - **Arti:** tanda tangan cocok, tetapi `id` atau `type` di body berbeda dari header id atau type. `header` menyebut yang mana.
394
+ - **Penyebab umum:** header diubah di jalan, misalnya kiriman lama diputar ulang dengan id baru supaya lolos dedup. Header id dan type tidak ikut ditandatangani, jadi SDK memakai nilai dari body.
395
+ - **Yang dilakukan:** jawab `400`. Jangan proses.
396
+
397
+ ### `ConfigError` dari `createWebhookVerifier`
398
+
399
+ `createWebhookVerifier` (dan `verifyWebhook`, di setiap panggilan) melempar satu `ConfigError` berisi semua masalah. Bentuk `ConfigError` sama dengan [§4](#4-configerror).
400
+
401
+ | Pesan | Perbaikan |
402
+ |---|---|
403
+ | `options must be an object` | Argumen bukan objek |
404
+ | `environment must be "sandbox" or "production"` | Isi `environment` (env `PLASGOS_ENV`) dengan salah satu dari dua nilai itu |
405
+ | `secrets must hold one or two values` | `secrets` harus array berisi satu atau dua string setelah nilai kosong dibuang. Biasanya env secret kosong, atau berisi lebih dari dua nilai |
406
+ | `secrets values must each be at least 32 bytes` | Secret terlalu pendek. Periksa bahwa env berisi secret utuh dari tim Plasgos |
407
+ | `preset is required` | Isi `preset` dengan `presets.payments`, `presets.appEvents`, atau `presets.plaslinkShipping` |
408
+ | `preset must be one of presets or an object with name and headers` | `preset` berupa string atau bentuknya salah. Pakai `presets.payments`, bukan `"payments"` |
409
+ | `preset.name must match /^[A-Za-z0-9_-]{1,64}$/` | Preset sendiri: perbaiki `name` |
410
+ | `preset.headers.<peran> must be an HTTP header name of at most 64 characters` | Preset sendiri: nama header untuk `id`, `type`, `timestamp`, atau `signature` salah |
411
+ | `preset.headers must name four distinct headers` | Preset sendiri: dua peran memakai header yang sama |
412
+ | `toleranceSeconds must be an integer from 1 to 900` | Pakai bilangan bulat detik, bukan string |
413
+ | `toleranceSeconds above 300 is not allowed when environment is "production"` | Di production, paling besar 300 |
414
+ | `maxBodyBytes must be an integer from 1024 to 16777216` | Pakai bilangan bulat byte |
415
+
416
+ ### `TypeError` dari `verify`
417
+
418
+ Argumen `verify` yang salah adalah bug di kode pemanggil, bukan kiriman yang ditolak.
419
+
420
+ | Pesan | Penyebab |
421
+ |---|---|
422
+ | `verifyWebhook: input must be an object with headers and rawBody` | Argumen bukan objek |
423
+ | `verifyWebhook: headers must be a Headers or a plain object of header values` | `headers` bukan `Headers` dan bukan objek |
424
+ | `verifyWebhook: rawBody must be the raw request body as a string or Uint8Array, before JSON parsing` | Body yang diberikan sudah di-parse (objek), kosong (`undefined`), atau tipe lain. Berikan body mentah ([`webhook.md` §5](webhook.md#5-body-mentah-per-framework)) |
425
+ | `verifyWebhook: now must be a finite number of epoch milliseconds` | `now` bukan angka milidetik |
426
+
427
+ Pesan yang sama dipakai oleh `verifier.verify` dan `verifyWebhook`.
428
+
429
+ ## 8. `AuthVerifyError`
430
+
431
+ Ditolak (reject) oleh `verifier.verifyAuthorization` dan `verifier.verifyRequest` dari `@plasgos/auth-verify` bila sebuah access token tidak diterima. Middleware Express (`requirePlasgosToken`), guard NestJS (`PlasgosAccessTokenGuard`), dan `authErrorResponse` menjawabnya untuk Anda. Cara memasangnya ada di [`verifikasi-token.md`](verifikasi-token.md).
432
+
433
+ | Properti | Isi |
434
+ |---|---|
435
+ | `name` | `"AuthVerifyError"` |
436
+ | `reason` | Kode alasan (tabel di bawah). Daftar lengkapnya juga diekspor sebagai `AUTH_VERIFY_REASONS` |
437
+ | `status` | Status HTTP jawaban: `401`, `403` (`insufficient_scope`), atau `503` (`unavailable`) |
438
+ | `errorCode` | Nilai `error` di body JSON: `invalid_token`, `insufficient_scope`, `insufficient_user_authentication`, atau `temporarily_unavailable` |
439
+ | `wwwAuthenticate` | Nilai header `WWW-Authenticate`, atau `null` bila tidak ada header yang dikirim |
440
+ | `message` | `"Access token <reason>"`, tidak lebih |
441
+
442
+ Pesan dan properti tidak pernah memuat token, klaim, atau nilai header. `scope="…"` dan `max_age=` di `wwwAuthenticate` berasal dari persyaratan route Anda, bukan dari token.
443
+
444
+ ### Semua `reason` dari verifikasi token
445
+
446
+ Diperiksa dengan urutan berikut. Kegagalan pertama yang ditemukan yang dilaporkan.
447
+
448
+ | `reason` | Arti | Status | `WWW-Authenticate` |
449
+ |---|---|---|---|
450
+ | [`missing_token`](#missing_token) | Tidak ada header `Authorization: Bearer …` | `401` | `Bearer` |
451
+ | [`malformed_token`](#malformed_token) | Isinya bukan JWT yang sah | `401` | `Bearer error="invalid_token"` |
452
+ | [`unknown_key`](#unknown_key) | `alg` bukan `RS256`, `kid` tidak ada, atau kuncinya tidak dikenal | `401` | `Bearer error="invalid_token"` |
453
+ | [`expired_token`](#expired_token) | `exp` lewat atau `nbf` belum tiba | `401` | `Bearer error="invalid_token"` |
454
+ | [`invalid_token`](#invalid_token) | Tanda tangan, `iss`, atau `aud` salah | `401` | `Bearer error="invalid_token"` |
455
+ | [`invalid_claims`](#invalid_claims) | `typ` salah, bentuk klaim salah, atau klaim wajib kurang | `401` | `Bearer error="invalid_token"` |
456
+ | [`revoked`](#revoked) | `isRevoked` mengembalikan `true` | `401` | `Bearer error="invalid_token"` |
457
+ | [`insufficient_scope`](#insufficient_scope) | Token tidak punya semua scope route | `403` | `Bearer error="insufficient_scope", scope="<scope route>"` |
458
+ | [`stale_auth`](#stale_auth) | Login user lebih lama dari `maxAuthAge` | `401` | `Bearer error="insufficient_user_authentication", max_age=<detik>` |
459
+ | [`unavailable`](#unavailable-access-token) | Kunci Plasgos (JWKS) tidak bisa dibaca | `503` | Tidak ada |
460
+
461
+ Body jawaban selalu `{"error":"<errorCode>"}`: `insufficient_scope` untuk `insufficient_scope`, `insufficient_user_authentication` untuk `stale_auth`, `temporarily_unavailable` untuk `unavailable`, dan `invalid_token` untuk yang lain.
462
+
463
+ ### `missing_token`
464
+
465
+ - **Arti:** header `Authorization` tidak ada, bukan string, atau tidak diawali `Bearer `.
466
+ - **Penyebab umum:** pemanggil belum login; proxy membuang header `Authorization`; token dikirim di cookie atau query.
467
+ - **Yang dilakukan:** jawab `401` dengan `WWW-Authenticate: Bearer`. Pemanggil mengirim access token di header `Authorization`.
468
+
469
+ ### `malformed_token`
470
+
471
+ - **Arti:** isi header bukan `Bearer` diikuti satu JWT (tiga bagian base64url), lebih panjang dari 8 KiB, atau header atau payload JWT bukan objek JSON.
472
+ - **Penyebab umum:** token terpotong; yang dikirim bukan access token (misalnya isi cookie atau id acak); token dikutip dua kali.
473
+ - **Yang dilakukan:** jawab `401`. Bug di pemanggil.
474
+
475
+ ### `unknown_key`
476
+
477
+ - **Arti:** header JWT memakai `alg` selain `RS256` (termasuk `none` dan `HS256`), tidak punya `kid`, atau `kid`-nya tidak ada di JWKS Plasgos setelah satu kali ambil ulang.
478
+ - **Penyebab umum:** token dari lingkungan lain (sandbox ke production atau sebaliknya); `backchannelUrl` mengarah ke server Plasgos lingkungan lain; token buatan sendiri.
479
+ - **Yang dilakukan:** jawab `401`. Bila semua token gagal dengan alasan ini, samakan lingkungan token, `issuer`, dan `backchannelUrl`. Rotasi kunci Plasgos tidak menyebabkan alasan ini: kunci baru diambil sendiri.
480
+
481
+ ### `expired_token`
482
+
483
+ - **Arti:** `exp` sudah lewat, atau `nbf` belum tiba, setelah toleransi `clockToleranceSeconds` (bawaan 30 detik). `exp` eksklusif: token yang `exp`-nya tepat sebesar toleransi di masa lalu sudah ditolak.
484
+ - **Penyebab umum:** pemanggil tidak me-refresh token; jam server API atau pemanggil meleset.
485
+ - **Yang dilakukan:** jawab `401`. Pemanggil me-refresh token (`ensureFresh`) lalu mengulang sekali. Bila token yang baru pun ditolak, periksa jam server (NTP).
486
+
487
+ ### `invalid_token`
488
+
489
+ - **Arti:** tanda tangan tidak cocok dengan kunci, `iss` tidak sama persis dengan `issuer`, atau `aud` tidak sama persis dengan `audience`. Juga untuk header atau klaim yang ditolak pustaka JWT tanpa alasan khusus (misalnya `crit` yang tidak dikenal).
490
+ - **Penyebab umum:** token untuk API lain (pemanggil meminta token tanpa `resource` atau dengan audience lain); `audience` berbeda satu karakter, termasuk `/` di akhir; issuer lingkungan lain.
491
+ - **Yang dilakukan:** jawab `401`. Pemanggil me-refresh sekali. Bila semua token gagal, samakan `audience` dan `issuer` dengan nilai dari tim Plasgos.
492
+
493
+ ### `invalid_claims`
494
+
495
+ - **Arti:** salah satu:
496
+ - `typ` bukan `at+jwt` (misalnya ID token yang dikirim sebagai access token);
497
+ - `aud` berupa array, `sub` atau `client_id` kosong, `scope` bukan string;
498
+ - token user dengan `sid` kosong, `auth_time` yang bukan bilangan bulat ≥ 0, `cv` yang bukan bilangan bulat, atau `plasgos_public_id` kosong atau lebih dari 128 karakter;
499
+ - `exp` tidak ada;
500
+ - klaim di `requireClaims` (verifier atau route) tidak ada, `null`, atau string kosong; untuk audience `/crm`, token user tanpa `cv`;
501
+ - token tanpa `sid` (token service) tanpa `allowServiceTokens`, atau token tanpa `sid` yang `sub`-nya berbeda dari `client_id`.
502
+ - **Penyebab umum:** ID token dikirim di tempat access token; `requireClaims` memuat klaim yang tidak dibawa token untuk audience Anda; API dipanggil dengan token service padahal `allowServiceTokens` belum dinyalakan.
503
+ - **Yang dilakukan:** jawab `401`. Bila semua token gagal, cocokkan `requireClaims` dan `allowServiceTokens` dengan token yang diterbitkan untuk API Anda.
504
+
505
+ ### `revoked`
506
+
507
+ - **Arti:** hook `isRevoked` mengembalikan `true`.
508
+ - **Penyebab umum:** sesi user dicabut, user diblokir, atau kredensial user berubah setelah token diterbitkan.
509
+ - **Yang dilakukan:** jawab `401`. Pemanggil mengakhiri sesinya dan mengarahkan user ke login.
510
+
511
+ ### `insufficient_scope`
512
+
513
+ - **Arti:** token tidak punya semua scope yang diminta route. `WWW-Authenticate` menyebut scope yang diminta.
514
+ - **Penyebab umum:** pemanggil tidak meminta scope itu saat login; client pihak ketiga meminta scope khusus first-party.
515
+ - **Yang dilakukan:** jawab `403`. Jangan diulang dengan token yang sama.
516
+
517
+ ### `stale_auth`
518
+
519
+ - **Arti:** user login lebih lama dari `maxAuthAge` route (`now − auth_time`). Untuk token service selalu, karena token service tidak punya `auth_time`.
520
+ - **Penyebab umum:** aksi sensitif yang meminta login baru.
521
+ - **Yang dilakukan:** jawab `401` dengan `max_age=<detik>`. Pemanggil memulai login ulang dengan `maxAge` itu ([`login-web.md` §10](login-web.md#10-login-ulang-untuk-aksi-sensitif)), lalu mengulang aksinya.
522
+
523
+ ### `unavailable` (access token)
524
+
525
+ - **Arti:** JWKS Plasgos tidak bisa dibaca: jaringan, DNS, timeout (`timeouts.jwksMs`), jawaban selain `200`, redirect, body lebih dari 64 KiB, atau JSON yang bukan key set. Bukan masalah token.
526
+ - **Penyebab umum:** `backchannelUrl` salah; firewall; gangguan di Plasgos.
527
+ - **Yang dilakukan:** jawab `503` tanpa `WWW-Authenticate`. Pemanggil mencoba lagi sebentar dan **tidak** mengakhiri sesi. Pasang alert.
528
+
529
+ ### `onReject` (`AuthRejectEvent`)
530
+
531
+ SDK tidak pernah menulis log. Setiap token yang ditolak diserahkan ke hook `onReject` milik verifier sebagai satu event:
532
+
533
+ | Field | Isi |
534
+ |---|---|
535
+ | `environment` | `"sandbox"` atau `"production"` |
536
+ | `reason` | `reason` yang sama dengan `AuthVerifyError` |
537
+ | `clientId` | `client_id` token, hanya setelah tanda tangannya lolos dan hanya bila berupa id biasa (huruf, angka, `_ . : -`, paling panjang 128); selain itu `null` |
538
+ | `requestId` | Header `X-Request-Id` request (adapter dan `verifyRequest` membacanya) atau `options.requestId`, dengan aturan yang sama; selain itu `null` |
539
+
540
+ Contoh hook:
541
+
542
+ <!-- snippet: examples/snippets/token-verifier.ts#on-reject -->
543
+ ```ts
544
+ /** One line per refused token. The event never holds the token or a claim value, so it is safe to log. */
545
+ export function logReject(event: AuthRejectEvent): void {
546
+ const line = [
547
+ "plasgos token refused:",
548
+ `env=${event.environment}`,
549
+ `reason=${event.reason}`,
550
+ `client_id=${event.clientId ?? "-"}`,
551
+ `request_id=${event.requestId ?? "-"}`,
552
+ ].join(" ");
553
+ process.stderr.write(`${line}\n`);
554
+ // The key set of Plasgos cannot be read: every request answers 503 until it recovers.
555
+ if (event.reason === "unavailable") process.stderr.write("ALERT plasgos key set unavailable\n");
556
+ }
557
+ ```
558
+ <!-- /snippet -->
559
+
560
+ Exception atau promise yang ditolak dari hook diabaikan SDK. Hook tidak bisa mengubah hasil verifikasi. Error dari `isRevoked` tidak memanggil `onReject`, karena itu bukan penolakan token.
561
+
562
+ ### `ConfigError` dari `createAccessTokenVerifier`
563
+
564
+ `createAccessTokenVerifier` (juga lewat `PlasgosAuthModule.forRoot` dan `forRootAsync`) melempar satu `ConfigError` berisi semua masalah. Bentuknya sama dengan [§4](#4-configerror). `issuer` dan `backchannelUrl` mengikuti aturan URL `issuer` di §4, dan `audience` mengikuti aturan `resource`.
565
+
566
+ | Pesan | Perbaikan |
567
+ |---|---|
568
+ | `options must be an object` | Argumen bukan objek |
569
+ | `environment must be "sandbox" or "production"` | Isi `environment` (env `PLASGOS_ENV`) |
570
+ | `environment is "production" but issuer is not the production issuer` | Di production, `issuer` harus `https://accounts.plasgos.co.id` |
571
+ | `environment is "production" but audience is not a production audience` | Di production, `audience` harus diawali `https://api.plasgos.co.id/` |
572
+ | `environment is "sandbox" but issuer is a production host`, `… backchannelUrl is a production host` | Sandbox tidak boleh mengarah ke host production |
573
+ | `allowInsecureHttp is not allowed when environment is "production"` | Hapus `allowInsecureHttp` di production |
574
+ | `issuer is required`, `audience is required` | Isi opsinya. Biasanya env-nya kosong |
575
+ | `backchannelUrl must use https: when environment is "production" unless allowInsecureBackchannel is true` | Pakai `https:`, atau `allowInsecureBackchannel: true` hanya untuk jaringan privat yang Anda percaya ([`verifikasi-token.md` §13](verifikasi-token.md#13-alamat-internal-backchannelurl)) |
576
+ | `allowInsecureBackchannel must be a boolean`, `allowServiceTokens must be a boolean`, `allowInsecureHttp must be a boolean` | Pakai `true` atau `false`. String `"true"` dari env ditolak |
577
+ | `requireClaims must be a list of at most 16 claim names` | Array berisi paling banyak 16 nama klaim: huruf, angka, atau `_`, 1–64 karakter |
578
+ | `clockToleranceSeconds must be an integer from 0 to 60` | Bilangan bulat detik |
579
+ | `timeouts must be an object`, `timeouts.jwksMs must be an integer from 1 to 60000` | Bentuknya `{ jwksMs }`, dalam milidetik |
580
+ | `jwks must be a JSON Web Key Set` | `{ keys: [ … ] }` dengan minimal satu kunci |
581
+ | `jwks is only allowed when environment is "sandbox"` | `jwks` hanya untuk test. Hapus di production |
582
+ | `fetch must be a function`, `isRevoked must be a function`, `onReject must be a function` | Perbaiki tipe nilainya |
583
+ | `isRevoked is required for a crm audience` | Audience dengan path `/crm` wajib punya `isRevoked` ([`verifikasi-token.md` §8](verifikasi-token.md#8-pencabutan-sesi-isrevoked)) |
584
+
585
+ ### `TypeError` dan `Error` dari verifikasi token
586
+
587
+ Bug di kode pemanggil, bukan token yang ditolak. Tidak dilaporkan lewat `onReject`.
588
+
589
+ | Pesan | Penyebab |
590
+ |---|---|
591
+ | `verify: options must be an object` | Argumen kedua `verifyAuthorization` atau `verifyRequest` bukan objek |
592
+ | `verify: scopes must be a list of scope tokens` | `scopes` bukan array scope (string tanpa spasi, `"`, atau `\`) |
593
+ | `verify: requireClaims must be a list of at most 16 claim names` | `requireClaims` salah bentuk |
594
+ | `verify: maxAuthAge must be a positive safe integer` | `maxAuthAge` bukan bilangan bulat positif detik |
595
+ | `verify: requestId must be a string` | `requestId` bukan string atau `null` |
596
+ | `verify: now must be a finite number` | `now` bukan angka milidetik |
597
+ | `verifyRequest: request must be a Web Request` | Argumen `verifyRequest` bukan `Request`. Untuk `req` Express, pakai middleware atau `verifyAuthorization(req.headers.authorization)` |
598
+ | `isRevoked must return a boolean` | Hook `isRevoked` mengembalikan nilai selain `true` atau `false` |
599
+ | `requirePlasgosToken: verifier must come from createAccessTokenVerifier` | Argumen pertama bukan verifier |
600
+ | `requirePlasgosToken: options must be an object`, `requirePlasgosToken: scopes must be a list of scope tokens`, `requirePlasgosToken: requireClaims must be a list of at most 16 claim names`, `requirePlasgosToken: maxAuthAge must be a positive safe integer` | Persyaratan route salah. Dilempar saat middleware dibuat |
601
+ | `RequireScopes: give at least one scope`, `RequireScopes: scopes must be a list of scope tokens` | Decorator tanpa scope atau dengan scope yang tidak sah. Dilempar saat class dimuat |
602
+ | `RequireRecentAuth: maxAgeSeconds must be a positive safe integer` | Argumen decorator salah |
603
+ | `authErrorResponse: error must be an AuthVerifyError` | `authErrorResponse` diberi error lain. Lempar ulang error seperti itu |
604
+ | `AuthVerifyError: …` | `new AuthVerifyError(…)` dibuat sendiri dengan argumen yang salah |
605
+
606
+ Dua `Error` (bukan `TypeError`) menandai bug wiring dan dijawab `500`:
607
+
608
+ | Pesan | Penyebab |
609
+ |---|---|
610
+ | `principalOf: requirePlasgosToken did not run for this request` | `principalOf(req)` di route tanpa `requirePlasgosToken` |
611
+ | `PlasgosPrincipal: PlasgosAccessTokenGuard did not run for this request` | `@PlasgosPrincipal()` di route tanpa `PlasgosAccessTokenGuard` |
612
+
613
+ Error yang dilempar hook `isRevoked` milik Anda diteruskan apa adanya, tidak dibungkus SDK. Jawab dengan `503` ([`verifikasi-token.md` §8](verifikasi-token.md#8-pencabutan-sesi-isrevoked)).