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

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 (45) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/LICENSE +4 -3
  3. package/README.md +22 -13
  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.map +1 -1
  17. package/dist/session.d.cts +2 -2
  18. package/dist/session.d.ts +2 -2
  19. package/dist/session.js.map +1 -1
  20. package/dist/{types-Cncksfeo.d.cts → types-JE0OMyoi.d.cts} +1 -1
  21. package/dist/{types-Cncksfeo.d.ts → types-JE0OMyoi.d.ts} +1 -1
  22. package/docs/consumers.md +90 -0
  23. package/docs/contoh-hitungcuan.md +255 -0
  24. package/docs/contoh-plaslink.md +244 -0
  25. package/docs/error.md +428 -0
  26. package/docs/examples/auth-verify-readme.ts +18 -0
  27. package/docs/examples/config-error.ts +24 -0
  28. package/docs/examples/env.ts +99 -0
  29. package/docs/examples/failure-log.ts +18 -0
  30. package/docs/examples/login-client.ts +46 -0
  31. package/docs/examples/login-flow.ts +186 -0
  32. package/docs/examples/plaslink-connect.ts +48 -0
  33. package/docs/examples/readme.ts +60 -0
  34. package/docs/examples/service-client.ts +105 -0
  35. package/docs/examples/session-store.ts +53 -0
  36. package/docs/examples/webhook-express.ts +46 -0
  37. package/docs/examples/webhook-fetch.ts +60 -0
  38. package/docs/examples/webhook-nestjs.ts +59 -0
  39. package/docs/examples/webhook-testing.ts +60 -0
  40. package/docs/examples/webhook-verifier.ts +143 -0
  41. package/docs/login-web.md +618 -0
  42. package/docs/memulai.md +339 -0
  43. package/docs/server-ke-server.md +275 -0
  44. package/docs/webhook.md +625 -0
  45. package/package.json +3 -2
@@ -0,0 +1,618 @@
1
+ # Login user di aplikasi web
2
+
3
+ Panduan ini untuk aplikasi web yang punya server sendiri (pola BFF) dan ingin user login dengan akun Plasgos. Server aplikasi yang berbicara dengan Plasgos dan menyimpan token di cookie terenkripsi. JavaScript di browser tidak pernah memegang token.
4
+
5
+ Sebelum mulai, baca [`memulai.md`](memulai.md) untuk env dan cara mendapat kredensial client login.
6
+
7
+ Isi panduan:
8
+
9
+ 1. [Cara kerja](#1-cara-kerja)
10
+ 2. [Client login](#2-client-login-createoidcclient)
11
+ 3. [Session store](#3-session-store-createsessionstore)
12
+ 4. [Tiga route: login, callback, logout](#4-tiga-route)
13
+ 5. [Menjaga sesi tetap segar](#5-menjaga-sesi-tetap-segar-ensurefresh)
14
+ 6. [Cookie](#6-cookie)
15
+ 7. [Rotasi secret sesi](#7-rotasi-secret-sesi)
16
+ 8. [Aplikasi yang sudah punya cookie sesi (migrasi)](#8-aplikasi-yang-sudah-punya-cookie-sesi-migrasi)
17
+ 9. [PWA](#9-pwa)
18
+ 10. [Login ulang untuk aksi sensitif](#10-login-ulang-untuk-aksi-sensitif)
19
+ 11. [React Router](#11-react-router)
20
+
21
+ ## 1. Cara kerja
22
+
23
+ Login selalu berupa **redirect satu halaman penuh** ke Plasgos (`accounts`), lalu kembali ke aplikasi. Tidak ada popup dan tidak ada iframe.
24
+
25
+ ```text
26
+ Browser Aplikasi Anda Plasgos
27
+ │ GET /login │ │
28
+ │───────────────────>│ startLogin() │
29
+ │ 302 + cookie transaksi │
30
+ │<───────────────────│ │
31
+ │ halaman login dan persetujuan │
32
+ │────────────────────────────────────────────────────────>│
33
+ │ 302 ke /auth/callback?code=…&state=… │
34
+ │<────────────────────────────────────────────────────────│
35
+ │ GET /auth/callback│ │
36
+ │───────────────────>│ handleCallback() ── tukar code ───>│
37
+ │ │<──────────── token ────────────────│
38
+ │ 302 + cookie sesi │ │
39
+ │<───────────────────│ │
40
+ ```
41
+
42
+ Yang Anda tulis: tiga route (`/login`, `/auth/callback`, `/logout`) dan satu pemanggilan `ensureFresh` sebelum memakai access token. SDK mengurus PKCE, `state`, `nonce`, pemeriksaan ID token, enkripsi cookie, dan refresh token.
43
+
44
+ Semua contoh memakai `Request` dan `Response` standar Web, jadi bisa dipakai di framework apa pun. File lengkapnya, dengan import, ada di [folder contoh](examples/): `env.ts`, `failure-log.ts`, `config-error.ts`, `login-client.ts`, `session-store.ts`, `login-flow.ts`. Salin file-file itu ke aplikasi Anda.
45
+
46
+ ## 2. Client login (`createOidcClient`)
47
+
48
+ Buat satu client saat aplikasi start.
49
+
50
+ Aplikasi Plasgos sendiri (first-party):
51
+
52
+ <!-- snippet: examples/snippets/login-client.ts#first-party -->
53
+ ```ts
54
+ /** A Plasgos app (BFF): tokens for one Plasgos API, refresh token, logout without a confirmation page. */
55
+ export function createFirstPartyClient(): OidcClient {
56
+ const env = readPlasgosEnv();
57
+ const credentials = readLoginCredentials();
58
+ return createOidcClient({
59
+ environment: env.environment,
60
+ issuer: env.issuer,
61
+ backchannelUrl: env.backchannelUrl,
62
+ clientId: credentials.clientId,
63
+ clientSecret: credentials.clientSecret,
64
+ redirectUri: `${credentials.appUrl}/auth/callback`,
65
+ postLogoutRedirectUri: `${credentials.appUrl}/`,
66
+ scopes: ["openid", "profile", "email", "packages:read", "packages:write"],
67
+ profile: "first-party",
68
+ // The audience of the API this app calls. Required by the packages:* scopes.
69
+ resource: process.env.PLASGOS_RESOURCE,
70
+ onFailure: logFailure,
71
+ });
72
+ }
73
+ ```
74
+ <!-- /snippet -->
75
+
76
+ Aplikasi di luar Plasgos (pihak ketiga):
77
+
78
+ <!-- snippet: examples/snippets/login-client.ts#third-party -->
79
+ ```ts
80
+ /** An app outside Plasgos: identity only. No resource, no logout ticket. */
81
+ export function createThirdPartyClient(): OidcClient {
82
+ const env = readPlasgosEnv();
83
+ const credentials = readLoginCredentials();
84
+ return createOidcClient({
85
+ environment: env.environment,
86
+ issuer: env.issuer,
87
+ clientId: credentials.clientId,
88
+ clientSecret: credentials.clientSecret,
89
+ redirectUri: `${credentials.appUrl}/auth/callback`,
90
+ postLogoutRedirectUri: `${credentials.appUrl}/`,
91
+ scopes: ["openid", "profile", "email", "plaslink:shipping"],
92
+ profile: "third-party",
93
+ onFailure: logFailure,
94
+ });
95
+ }
96
+ ```
97
+ <!-- /snippet -->
98
+
99
+ ### Opsi `createOidcClient`
100
+
101
+ | Opsi | Wajib | Bawaan | Arti |
102
+ |---|---|---|---|
103
+ | `environment` | Ya | — | `"sandbox"` atau `"production"`. Pengaman, bukan pemilih URL ([`memulai.md` §5](memulai.md#sandbox-dan-production)) |
104
+ | `issuer` | Ya | — | Origin issuer, tanpa path. Browser diarahkan ke sini, dan nilai `iss` token harus sama persis |
105
+ | `backchannelUrl` | Tidak | `issuer` | Alamat internal server Plasgos untuk panggilan token, pencabutan token, dan logout ticket. Hanya untuk aplikasi di jaringan Plasgos. Boleh `http:` |
106
+ | `clientId` | Ya | — | Client id client login |
107
+ | `clientSecret` | Ya | — | Client secret. Hanya dikirim sebagai Basic auth ke Plasgos |
108
+ | `redirectUri` | Ya | — | URL callback, sama persis dengan yang didaftarkan. Boleh memuat query. Wajib `https`, kecuali `allowInsecureHttp` |
109
+ | `postLogoutRedirectUri` | Tidak | — | URL tujuan setelah logout, sama persis dengan yang didaftarkan. Tanpa ini, Plasgos menampilkan halaman "sudah keluar" miliknya |
110
+ | `scopes` | Ya | — | Daftar scope user. Wajib memuat `"openid"` ([`memulai.md` §4](memulai.md#4-daftar-scope)) |
111
+ | `profile` | Ya | — | `"first-party"` (aplikasi Plasgos) atau `"third-party"` |
112
+ | `resource` | Bila memakai scope `account:*` / `packages:*` | — | Audience API yang dipanggil atas nama user. Tidak boleh untuk `"third-party"` |
113
+ | `logoutTicket` | Tidak | Lihat di bawah | Menukar ID token dengan tiket sekali pakai saat logout, supaya Plasgos tidak menampilkan halaman konfirmasi |
114
+ | `endSession` | Tidak | `"redirect"` | `"redirect"`: logout berupa URL. `"form-post"`: hanya untuk aplikasi yang berada di origin issuer sendiri (accounts). Di production, `redirectUri` di origin lain adalah `ConfigError`. Di sandbox SDK menerimanya (aplikasi dan issuer lokal berjalan di dua port), tetapi Plasgos menjawab form `POST` dari origin lain dengan `403` |
115
+ | `extraClaims` | Tidak | `[]` | Nama klaim ID token tambahan yang dikembalikan di `claims.extra`, misalnya `["plasgos_public_id"]` |
116
+ | `allowInsecureHttp` | Tidak | `false` | Hanya sandbox: mengizinkan `http:` untuk `issuer`, `redirectUri`, dan `postLogoutRedirectUri` |
117
+ | `timeouts.tokenMs` | Tidak | `10000` | Batas waktu panggilan token, 1–60000 ms |
118
+ | `timeouts.logoutMs` | Tidak | `3000` | Batas waktu setiap panggilan saat logout, 1–60000 ms |
119
+ | `fetch` | Tidak | `fetch` global | Pengganti `fetch`, untuk test |
120
+ | `refreshLock` | Tidak | `memoryLockStore()` | Tempat menyimpan refresh yang sedang berjalan ([§5](#lebih-dari-satu-instance)) |
121
+ | `onFailure` | Tidak | — | Dipanggil sekali untuk setiap kegagalan, termasuk yang tidak dilempar. Aman ditulis ke log ([`error.md`](error.md#2-oidcfailureevent)) |
122
+
123
+ **Bawaan `logoutTicket`.** Tiket diminta lewat alamat internal Plasgos, jadi butuh `backchannelUrl`. Nilai bawaannya `true` hanya bila ketiganya terpenuhi: `profile: "first-party"`, `endSession: "redirect"`, dan `backchannelUrl` diisi. Selain itu `false`. Menulis `logoutTicket: true` tanpa `backchannelUrl` adalah `ConfigError`.
124
+
125
+ **`redirectUri` dan `postLogoutRedirectUri`** ditolak bila memuat wildcard (`*`), fragment (`#`), kredensial (`user:pass@`), spasi, atau backslash, dan bila bukan `https` tanpa `allowInsecureHttp`.
126
+
127
+ **Nilai kosong.** Opsi string yang tidak wajib (`postLogoutRedirectUri`, `backchannelUrl`, `resource`) dianggap tidak diisi bila kosong atau hanya berisi spasi, jadi nilai env yang disetel kosong (`NAMA_ENV=` tanpa nilai) aman diteruskan apa adanya. Opsi wajib yang kosong, termasuk `clientId` dan `clientSecret` yang hanya berisi spasi, ditolak dengan `<opsi> is required`. Scope yang ditulis dua kali hanya dikirim sekali.
128
+
129
+ ### Yang dikembalikan
130
+
131
+ | Anggota | Arti |
132
+ |---|---|
133
+ | `environment`, `issuer`, `clientId` | Nilai konfigurasi (hanya baca) |
134
+ | `startLogin(input)` | Membuat URL login dan transaksinya ([§4](#login)) |
135
+ | `handleCallback(url, transaction)` | Memeriksa callback, menukar code, memeriksa ID token ([§4](#callback)) |
136
+ | `refresh(refreshToken)` | Satu kali refresh. Biasanya cukup memakai `ensureFresh` |
137
+ | `ensureFresh(auth, options?)` | Refresh bila access token hampir habis ([§5](#5-menjaga-sesi-tetap-segar-ensurefresh)) |
138
+ | `logout(input)` | Mencabut refresh token dan membuat langkah logout di Plasgos ([§4](#logout)) |
139
+
140
+ ## 3. Session store (`createSessionStore`)
141
+
142
+ Session store menyegel sesi ke dalam cookie (AES-256-GCM). Tidak ada penyimpanan di server.
143
+
144
+ Data milik aplikasi Anda (misalnya pesan flash) divalidasi oleh `appSchema` yang Anda tulis. Data login (`auth`) dimiliki dan divalidasi SDK.
145
+
146
+ <!-- snippet: examples/snippets/session-store.ts#app-schema -->
147
+ ```ts
148
+ /** What this app keeps in its own cookie, next to the SDK's auth. Every field is optional. */
149
+ export interface AppSession {
150
+ flash?: string | undefined;
151
+ }
152
+
153
+ /** Returns the app data, or null when the cookie does not hold what this app wrote. */
154
+ export const appSchema: SessionSchema<AppSession> = {
155
+ parse(input) {
156
+ if (typeof input !== "object" || input === null) return null;
157
+ const flash: unknown = "flash" in input ? input.flash : undefined;
158
+ if (flash === undefined) return {};
159
+ return typeof flash === "string" && flash.length <= 200 ? { flash } : null;
160
+ },
161
+ };
162
+ ```
163
+ <!-- /snippet -->
164
+
165
+ <!-- snippet: examples/snippets/session-store.ts#store -->
166
+ ```ts
167
+ /** Create it once at start. */
168
+ export function createAppSessionStore(): SessionStore<AppSession> {
169
+ return createSessionStore<AppSession>({
170
+ environment: readEnvironment(),
171
+ secrets: readSessionSecrets(),
172
+ // Never change the salt or the names after the first release: the cookie keys are derived from them.
173
+ hkdfSalt: "contoh-app",
174
+ cookies: { app: "ca", auth: "ca-auth", idToken: "ca-idt", transaction: "ca-oidc" },
175
+ authMaxAgeSeconds: 2_592_000,
176
+ appSchema,
177
+ });
178
+ }
179
+ ```
180
+ <!-- /snippet -->
181
+
182
+ Bila aplikasi sudah memakai zod, bungkus skemanya. SDK sendiri tidak bergantung pada zod.
183
+
184
+ <!-- snippet: examples/snippets/session-store.ts#zod-adapter -->
185
+ ```ts
186
+ /** The part of a zod schema the adapter uses. */
187
+ interface SafeParser<T> {
188
+ safeParse(input: unknown): { success: true; data: T } | { success: false };
189
+ }
190
+
191
+ /** Wraps a zod object schema: `appSchema: fromZod(z.object({ flash: z.string().max(200).optional() }))`. */
192
+ export function fromZod<T>(schema: SafeParser<T>): SessionSchema<T> {
193
+ return {
194
+ parse(input) {
195
+ const result = schema.safeParse(input);
196
+ return result.success ? result.data : null;
197
+ },
198
+ };
199
+ }
200
+ ```
201
+ <!-- /snippet -->
202
+
203
+ ### Opsi `createSessionStore`
204
+
205
+ | Opsi | Wajib | Bawaan | Arti |
206
+ |---|---|---|---|
207
+ | `environment` | Ya | — | Nilai yang sama dengan `environment` client. `"production"` menolak `hostPrefix: false` |
208
+ | `secrets` | Ya | — | Satu atau dua secret, masing-masing minimal 32 byte. Yang pertama menyegel, semuanya bisa membuka ([§7](#7-rotasi-secret-sesi)) |
209
+ | `hkdfSalt` | Ya | — | Salt turunan kunci, misalnya nama aplikasi. Jangan diubah setelah rilis |
210
+ | `cookies` | Ya | — | Nama empat cookie: `app`, `auth`, `idToken`, `transaction`. Huruf kecil, angka, dan `-`, 1–32 karakter, harus berbeda satu sama lain. Jangan diubah setelah rilis |
211
+ | `hostPrefix` | Tidak | `true` | `true`: nama cookie diawali `__Host-` dan memakai `Secure`. `false` hanya untuk development lokal dengan `http:` |
212
+ | `authMaxAgeSeconds` | Ya | — | Umur cookie `auth` dan `idToken` dalam detik. Bilangan bulat positif, atau fungsi `(auth) => number` |
213
+ | `appSchema` | Ya | — | `{ parse(input) }` yang mengembalikan data aplikasi atau `null`. Semua field aplikasi harus opsional |
214
+ | `compactKeys` | Tidak | — | Tabel nama kunci ringkas untuk memperkecil cookie. Aplikasi baru tidak perlu mengisinya ([§8](#8-aplikasi-yang-sudah-punya-cookie-sesi-migrasi)) |
215
+ | `onFailure` | Tidak | — | Dipanggil saat `commit()` membuang cookie yang terlalu besar. Hanya berisi nama cookie dan ukurannya |
216
+
217
+ `createSessionStore` menerima `environment` yang sama dengan client, dan `production` menolak `hostPrefix: false`.
218
+
219
+ Mengubah `hkdfSalt` atau nama cookie membuat semua cookie lama tidak terbaca, sehingga semua user harus login ulang.
220
+
221
+ ### Yang dikembalikan
222
+
223
+ | Anggota | Arti |
224
+ |---|---|
225
+ | `read(request)` | Membuka cookie sesi sebuah request. Tidak pernah melempar. Cookie yang rusak dianggap tidak ada |
226
+ | `commit(session)` | Semua nilai `Set-Cookie` yang perlu dikirim (kosong bila sesi tidak berubah) |
227
+ | `fits(auth)` | Apakah cookie `auth` dan `idToken` muat, diperiksa sebelum login disimpan |
228
+ | `readTransaction(request)` | Transaksi login, atau `null` bila tidak ada, rusak, atau lebih tua dari 10 menit |
229
+ | `commitTransaction(tx)`, `clearTransaction()` | `Set-Cookie` untuk menyimpan dan menghapus transaksi login |
230
+ | `commitApp`, `commitAuth`, `commitIdToken` | Satu cookie saja. Melempar `SessionTooLargeError` bila tidak muat. Biasanya cukup `commit` |
231
+ | `cookieNames` | Nama cookie yang benar-benar dikirim (dengan `__Host-` bila `hostPrefix`) |
232
+
233
+ `read` mengembalikan pegangan sesi untuk satu request:
234
+
235
+ | Anggota | Arti |
236
+ |---|---|
237
+ | `data` | Isi sesi: field aplikasi dan `auth` (bila login) |
238
+ | `update(patch)` | Mengubah field. Nilai `undefined` menghapus field itu |
239
+ | `unset(key)` | Menghapus satu field |
240
+ | `destroy()` | Mengosongkan sesi |
241
+ | `dirty`, `authDirty`, `restDirty` | Apakah sesi berubah (keseluruhan, bagian `auth`, bagian aplikasi) |
242
+
243
+ Pola pakainya selalu sama: `read` di awal request, ubah lewat `update`, lalu kirim hasil `commit` sebagai header `Set-Cookie` di akhir.
244
+
245
+ ## 4. Tiga route
246
+
247
+ Persiapan yang dipakai ketiga route:
248
+
249
+ <!-- snippet: examples/snippets/login-flow.ts#setup -->
250
+ ```ts
251
+ /** Everything the handlers need. Create it once at start and pass it to every handler. */
252
+ export interface AuthContext {
253
+ client: OidcClient;
254
+ store: SessionStore<AppSession>;
255
+ /** Public origin of this app, for the Origin check of the logout. */
256
+ appOrigin: string;
257
+ /** Where /v5/* lives. */
258
+ apiUrl: string;
259
+ }
260
+
261
+ export function createAuthContext(): AuthContext {
262
+ return {
263
+ client: createFirstPartyClient(),
264
+ store: createAppSessionStore(),
265
+ appOrigin: readLoginCredentials().appUrl,
266
+ apiUrl: readPlasgosEnv().apiUrl,
267
+ };
268
+ }
269
+
270
+ /** Only a path of this app is accepted as the place to return to after login. */
271
+ function safeReturnTo(value: string | null): string {
272
+ if (value === null || value.length > 512) return "/";
273
+ if (!value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\")) return "/";
274
+ return value;
275
+ }
276
+
277
+ function redirect(location: string, headers: Headers, status = 302): Response {
278
+ headers.set("Location", location);
279
+ headers.set("Cache-Control", "no-store");
280
+ return new Response(null, { status, headers });
281
+ }
282
+ ```
283
+ <!-- /snippet -->
284
+
285
+ `safeReturnTo` penting: `returnTo` datang dari URL, jadi hanya path milik aplikasi sendiri yang boleh diterima. SDK menolak `returnTo` yang tidak diawali tepat satu `/`, tetapi pemeriksaan tujuan tetap tugas aplikasi.
286
+
287
+ ### Login
288
+
289
+ <!-- snippet: examples/snippets/login-flow.ts#login -->
290
+ ```ts
291
+ /** GET /login?returnTo=/path: a full-page redirect to Plasgos. */
292
+ export function handleLogin(context: AuthContext, request: Request): Response {
293
+ const returnTo = safeReturnTo(new URL(request.url).searchParams.get("returnTo"));
294
+ const { location, transaction } = context.client.startLogin({ returnTo });
295
+ const headers = new Headers();
296
+ headers.append("Set-Cookie", context.store.commitTransaction(transaction));
297
+ return redirect(location, headers);
298
+ }
299
+ ```
300
+ <!-- /snippet -->
301
+
302
+ `startLogin` tidak memanggil Plasgos. Ia hanya membuat URL dan transaksi (`state`, `nonce`, `code_verifier`). Transaksi disimpan di cookie transaksi yang berumur 10 menit.
303
+
304
+ Opsi `startLogin`:
305
+
306
+ | Opsi | Wajib | Bawaan | Arti |
307
+ |---|---|---|---|
308
+ | `returnTo` | Ya | — | Path tujuan setelah login. Diawali tepat satu `/`, paling panjang 512 karakter |
309
+ | `prompt` | Tidak | — | `"login"` (paksa login ulang), `"consent"`, atau `"none"` |
310
+ | `maxAge` | Tidak | — | Detik. Plasgos meminta login ulang bila login terakhir lebih lama dari ini |
311
+ | `loginHint` | Tidak | — | Petunjuk akun untuk halaman login, paling panjang 512 karakter |
312
+ | `reauth` | Tidak | `false` | Menandai login ulang ([§10](#10-login-ulang-untuk-aksi-sensitif)) |
313
+
314
+ Input yang salah melempar `TypeError` (ini bug di kode pemanggil, bukan kegagalan login).
315
+
316
+ ### Callback
317
+
318
+ <!-- snippet: examples/snippets/login-flow.ts#callback -->
319
+ ```ts
320
+ function loginFailed(headers: Headers, status: number): Response {
321
+ headers.set("Cache-Control", "no-store");
322
+ headers.set("Content-Type", "text/plain; charset=utf-8");
323
+ return new Response("Login gagal. Silakan coba lagi.", { status, headers });
324
+ }
325
+
326
+ /** GET /auth/callback: Plasgos sends the browser back here with `code` and `state`. */
327
+ export async function handleCallback(context: AuthContext, request: Request): Promise<Response> {
328
+ const { client, store } = context;
329
+ const headers = new Headers();
330
+ // The transaction is single use: its cookie is cleared whatever happens next.
331
+ headers.append("Set-Cookie", store.clearTransaction());
332
+ try {
333
+ const { tokens, claims, transaction } = await client.handleCallback(request.url, store.readTransaction(request));
334
+ const auth: AuthState = {
335
+ access_token: tokens.access_token,
336
+ refresh_token: tokens.refresh_token,
337
+ expires_at: accessTokenExpiry(tokens, Date.now()),
338
+ user: {
339
+ id: claims.sub,
340
+ name: claims.name ?? "",
341
+ email: claims.email ?? null,
342
+ avatar_url: claims.picture ?? null,
343
+ },
344
+ id_token: tokens.id_token,
345
+ auth_time: claims.auth_time,
346
+ };
347
+ const fits = store.fits(auth);
348
+ if (!fits.auth) return loginFailed(headers, 500);
349
+ const session = store.read(request);
350
+ // Without the ID token the session still works; only the logout then asks the user to confirm.
351
+ session.update({ auth: fits.idToken ? auth : { ...auth, id_token: undefined } });
352
+ for (const cookie of store.commit(session)) headers.append("Set-Cookie", cookie);
353
+ return redirect(safeReturnTo(transaction.return_to), headers);
354
+ } catch (error) {
355
+ if (!(error instanceof OidcError)) throw error;
356
+ return loginFailed(headers, error.reason === "unavailable" ? 503 : 400);
357
+ }
358
+ }
359
+ ```
360
+ <!-- /snippet -->
361
+
362
+ Urutannya:
363
+
364
+ 1. **Hapus cookie transaksi di semua jalur**, berhasil atau gagal. Transaksi hanya boleh dipakai sekali.
365
+ 2. `readTransaction` lalu `handleCallback`. SDK memeriksa `state`, menukar `code` dengan token, dan memeriksa ID token. Kegagalan dilempar sebagai `OidcError` ([`error.md`](error.md)).
366
+ 3. Susun `auth`: token, waktu habis (`accessTokenExpiry`), dan data user dari `claims`.
367
+ 4. `fits(auth)`: pastikan cookie muat sebelum disimpan.
368
+ 5. `session.update({ auth })`, lalu kirim semua `Set-Cookie` dari `commit`.
369
+ 6. Redirect ke `transaction.return_to`.
370
+
371
+ `handleCallback` mengembalikan:
372
+
373
+ | Field | Isi |
374
+ |---|---|
375
+ | `tokens` | `access_token`, `refresh_token` (bila ada), `id_token`, `expires_in`, `scope` |
376
+ | `claims` | Klaim ID token yang sudah diperiksa: `sub`, `name`, `picture`, `email`, `auth_time`, dan `extra` (klaim dari `extraClaims`) |
377
+ | `transaction` | Transaksi yang dipakai: `return_to`, `reauth`, `max_age` |
378
+
379
+ `claims.sub` adalah identitas user untuk client Anda. Nilainya berbeda untuk setiap client (pairwise). Token tidak membawa role atau tim.
380
+
381
+ Tampilkan halaman "login gagal" yang menawarkan mencoba lagi. Jangan menampilkan `reason` mentah ke user. Catat lewat `onFailure`.
382
+
383
+ ### Logout
384
+
385
+ <!-- snippet: examples/snippets/login-flow.ts#logout -->
386
+ ```ts
387
+ /** POST /logout, from a form of this app. */
388
+ export async function handleLogout(context: AuthContext, request: Request): Promise<Response> {
389
+ const { client, store } = context;
390
+ if (request.method !== "POST") return new Response(null, { status: 405, headers: { Allow: "POST" } });
391
+ // Another site must not be able to log the user out.
392
+ if (request.headers.get("Origin") !== context.appOrigin) return new Response(null, { status: 403 });
393
+
394
+ const session = store.read(request);
395
+ const auth = session.data.auth;
396
+ // Never rejects: a failed call to Plasgos is reported through onFailure and the logout goes on.
397
+ const result = await client.logout({
398
+ refreshToken: auth?.refresh_token,
399
+ idToken: auth?.id_token,
400
+ // clientIp: the address your reverse proxy vouches for, or null.
401
+ browser: { clientIp: null, userAgent: request.headers.get("User-Agent") },
402
+ });
403
+
404
+ session.destroy();
405
+ const headers = new Headers();
406
+ for (const cookie of store.commit(session)) headers.append("Set-Cookie", cookie);
407
+ if (result.kind !== "redirect") throw new Error('This app uses endSession "redirect"');
408
+ return redirect(result.location, headers, 303);
409
+ }
410
+ ```
411
+ <!-- /snippet -->
412
+
413
+ - **Hanya `POST`, dengan pemeriksaan `Origin`.** Logout lewat `GET` bisa dipicu situs lain (misalnya lewat tag gambar).
414
+ - `logout()` **tidak pernah melempar**. Ia mencabut refresh token dan (bila `logoutTicket` aktif) meminta tiket, keduanya bersamaan dan masing-masing dibatasi `timeouts.logoutMs`. Panggilan yang gagal hanya menjadi satu event `onFailure`.
415
+ - `session.destroy()` lalu `commit` menghapus ketiga cookie sesi. Lakukan ini apa pun hasil `logout()`.
416
+ - Token tidak pernah ditaruh di URL.
417
+
418
+ Hasil `logout()`:
419
+
420
+ | `kind` | Isi | Yang dilakukan |
421
+ |---|---|---|
422
+ | `"redirect"` | `location`, `ticket` | Redirect `303` ke `location`. `ticket: true` berarti Plasgos langsung mengakhiri sesinya. `ticket: false` berarti Plasgos menampilkan halaman konfirmasi keluar |
423
+ | `"form"` | `action`, `fields` | Hanya untuk `endSession: "form-post"`: kirim form `POST` ke `action` dengan `fields` sebagai input tersembunyi |
424
+
425
+ ## 5. Menjaga sesi tetap segar (`ensureFresh`)
426
+
427
+ Access token berumur pendek. Panggil `ensureFresh` setiap kali akan memakai access token. Ia me-refresh hanya bila perlu.
428
+
429
+ <!-- snippet: examples/snippets/login-flow.ts#fresh -->
430
+ ```ts
431
+ /** The access token to use now, renewed when it is about to expire; null when nobody is signed in. */
432
+ async function freshAccessToken(
433
+ context: AuthContext,
434
+ session: SessionHandle<AppSession>,
435
+ force = false,
436
+ ): Promise<string | null> {
437
+ const current = session.data.auth;
438
+ if (current === undefined) return null;
439
+ const { auth, changed } = await context.client.ensureFresh(current, { force });
440
+ // Store a renewed auth at once: its refresh token replaced the old one at Plasgos.
441
+ if (changed) session.update({ auth });
442
+ return auth.access_token;
443
+ }
444
+
445
+ const isInvalidToken = (res: Response): boolean =>
446
+ res.status === 401 && (res.headers.get("WWW-Authenticate") ?? "").includes("invalid_token");
447
+
448
+ /** Calls a Plasgos API for the signed-in user and answers with its body. */
449
+ export async function callApi(context: AuthContext, request: Request, path: string): Promise<Response> {
450
+ const session = context.store.read(request);
451
+ /** Every answer carries the session cookies that changed, also an error answer. */
452
+ const respond = (body: ReadableStream<Uint8Array> | string | null, status: number, headers = new Headers()): Response => {
453
+ for (const cookie of context.store.commit(session)) headers.append("Set-Cookie", cookie);
454
+ headers.set("Cache-Control", "no-store");
455
+ return new Response(body, { status, headers });
456
+ };
457
+ const toLogin = (): Response => {
458
+ const { pathname, search } = new URL(request.url);
459
+ return respond(null, 302, new Headers({ Location: `/login?returnTo=${encodeURIComponent(pathname + search)}` }));
460
+ };
461
+ const call = (token: string): Promise<Response> =>
462
+ fetch(`${context.apiUrl}${path}`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } });
463
+
464
+ try {
465
+ let token = await freshAccessToken(context, session);
466
+ if (token === null) return toLogin();
467
+ let res = await call(token);
468
+ if (isInvalidToken(res)) {
469
+ // The API refused a token that looked valid: refresh once and try once more.
470
+ token = await freshAccessToken(context, session, true);
471
+ if (token === null) return toLogin();
472
+ res = await call(token);
473
+ }
474
+ return respond(res.body, res.status, new Headers({ "Content-Type": res.headers.get("Content-Type") ?? "application/json" }));
475
+ } catch (error) {
476
+ if (!(error instanceof OidcError)) throw error;
477
+ switch (error.reason) {
478
+ // The session is over at Plasgos: clear it here and send the user to login.
479
+ case "invalid_grant":
480
+ case "invalid_target":
481
+ case "missing":
482
+ session.update({ auth: undefined });
483
+ return toLogin();
484
+ // Plasgos did not answer and the access token has run out. The session is kept.
485
+ case "unavailable":
486
+ return respond("Layanan sedang tidak tersedia. Coba lagi sebentar.", 503);
487
+ // config_invalid and anything else: a bug to fix. The session is kept.
488
+ default:
489
+ return respond("Terjadi kesalahan.", 500);
490
+ }
491
+ }
492
+ }
493
+ ```
494
+ <!-- /snippet -->
495
+
496
+ Perilaku `ensureFresh(auth, options)`:
497
+
498
+ | Keadaan | Hasil |
499
+ |---|---|
500
+ | Access token masih berlaku lebih dari `skewSeconds` | `{ auth, changed: false }`, tanpa panggilan ke Plasgos |
501
+ | Hampir habis atau sudah habis, refresh berhasil | `{ auth: <baru>, changed: true }`. **Simpan `auth` baru ke sesi** |
502
+ | Refresh gagal dengan `invalid_grant` atau `invalid_target` | Selalu dilempar. Sesi berakhir |
503
+ | Refresh gagal dengan alasan lain, access token masih berlaku | `{ auth, changed: false }`. Kegagalan dilaporkan lewat `onFailure` |
504
+ | Refresh gagal dengan alasan lain, access token sudah habis | Dilempar |
505
+ | Tidak ada refresh token, access token masih berlaku | `{ auth, changed: false }` |
506
+ | Tidak ada refresh token, access token sudah habis | Dilempar dengan `reason: "missing"` |
507
+ | `force: true` dan refresh gagal, atau tidak ada refresh token | Selalu dilempar, walaupun access token tampak masih berlaku |
508
+
509
+ Opsi `ensureFresh`:
510
+
511
+ | Opsi | Wajib | Bawaan | Arti |
512
+ |---|---|---|---|
513
+ | `skewSeconds` | Tidak | `60` | Refresh bila access token habis dalam sekian detik |
514
+ | `force` | Tidak | `false` | Refresh walaupun token tampak masih berlaku. Pakai setelah API menjawab `401 invalid_token` |
515
+
516
+ `ensureFresh` tidak pernah mengubah objek `auth` yang diberikan. Bila `changed: true`, **segera** simpan `auth` baru ke sesi dan kirim cookie-nya, juga bila langkah berikutnya gagal. Refresh token lama sudah tidak berlaku di Plasgos.
517
+
518
+ ### Yang dilakukan untuk setiap `reason`
519
+
520
+ | `reason` | Arti | Yang dilakukan |
521
+ |---|---|---|
522
+ | `invalid_grant`, `invalid_target` | Sesi sudah berakhir di Plasgos | Hapus `auth` dari sesi, arahkan user ke login |
523
+ | `missing` | Access token habis dan tidak ada refresh token | Hapus `auth` dari sesi, arahkan user ke login |
524
+ | `unavailable` | Plasgos tidak menjawab, dan access token sudah habis | Jawab `503`. **Sesi tidak dihapus.** User mencoba lagi sebentar lagi |
525
+ | `config_invalid` | Plasgos menolak konfigurasi client (secret salah, client dinonaktifkan, scope tidak terdaftar) | Ini bug konfigurasi, bukan akhir sesi user. Pasang alert di `onFailure`. Selama access token masih berlaku, `ensureFresh` tetap mengembalikan sesi. Setelah habis, request gagal dengan `500` **tanpa menghapus sesi** |
526
+ | `provider_error` | Jawaban Plasgos tidak terduga | Jawab `500`. Sesi tidak dihapus |
527
+
528
+ Hanya `invalid_grant` dan `invalid_target` (dan `missing`) yang mengakhiri sesi. Jangan menghapus sesi untuk alasan lain: gangguan sebentar di Plasgos tidak boleh membuat semua user keluar.
529
+
530
+ ### Lebih dari satu instance
531
+
532
+ Plasgos mengganti refresh token setiap kali dipakai. Refresh kedua dengan token yang sama dianggap pencurian token, dan Plasgos mencabut seluruh sesi. Karena itu SDK menjalankan refresh satu per satu untuk setiap refresh token (`refreshLock`), dan hasilnya dipakai ulang selama 30 detik untuk request yang masih membawa token lama.
533
+
534
+ Bawaannya `memoryLockStore()`: kunci di memori satu proses. Bila aplikasi berjalan di beberapa instance, dua instance bisa me-refresh token yang sama bersamaan. Untuk itu, berikan `refreshLock` buatan sendiri di atas penyimpanan bersama (misalnya Redis) yang memenuhi interface `RefreshLockStore`:
535
+
536
+ | Anggota | Arti |
537
+ |---|---|
538
+ | `run(key, refresh, reuseMs)` | Menjalankan `refresh` paling banyak sekali untuk setiap `key` di antara semua pemanggil, dan memberi semuanya hasil yang sama. Hasil yang berhasil dipakai ulang selama `reuseMs`. Kegagalan tidak disimpan |
539
+
540
+ `key` adalah SHA-256 dari refresh token, bukan token itu sendiri.
541
+
542
+ ## 6. Cookie
543
+
544
+ Sesi dibagi menjadi empat cookie:
545
+
546
+ | Cookie | Isi | Umur |
547
+ |---|---|---|
548
+ | `app` | Data aplikasi (semua selain `auth`) | Cookie sesi browser |
549
+ | `auth` | Access token, refresh token, data user | `authMaxAgeSeconds` |
550
+ | `idToken` | ID token saja, untuk logout | `authMaxAgeSeconds` |
551
+ | `transaction` | Transaksi login yang sedang berjalan | 10 menit |
552
+
553
+ - Atribut semua cookie: `Path=/`, `HttpOnly`, `SameSite=Lax`, dan `Secure` (kecuali `hostPrefix: false`). Tidak ada `Domain`.
554
+ - Dengan `hostPrefix: true`, nama yang dikirim adalah `__Host-<nama>`. Browser hanya menerima cookie `__Host-` lewat `https`.
555
+ - Batas ukuran satu `Set-Cookie` adalah 4000 karakter. Browser membuang cookie yang lebih besar.
556
+ - `commit()` menangani cookie yang terlalu besar sendiri: cookie itu dihapus, datanya dibuang dari sesi, dan `onFailure` milik store dipanggil dengan nama cookie dan ukurannya. Bila yang terlalu besar hanya `idToken`, login tetap jalan, tetapi logout akan menampilkan halaman konfirmasi Plasgos.
557
+ - Pakai `fits(auth)` di callback supaya login yang tidak muat ditolak dengan jelas, bukan hilang diam-diam.
558
+ - Simpan data seperlunya di cookie `app`. Data besar tempatnya di database.
559
+
560
+ Development lokal dengan `http://localhost`: pakai `environment: "sandbox"`, `allowInsecureHttp: true` di client, dan `hostPrefix: false` di store. Contoh di atas tidak menyetel keduanya; tambahkan sendiri.
561
+
562
+ ## 7. Rotasi secret sesi
563
+
564
+ `secrets` menerima satu atau dua nilai. Yang pertama dipakai menyegel. Semuanya dipakai membuka.
565
+
566
+ 1. Buat secret baru (acak, minimal 32 byte).
567
+ 2. Taruh secret baru **di depan**: `SESSION_SECRET=<baru>,<lama>`. Deploy.
568
+ 3. Cookie `app` yang masih disegel secret lama disegel ulang saat request berikutnya. Cookie `auth` disegel ulang saat token di-refresh.
569
+ 4. Simpan secret lama minimal selama umur cookie `auth` terpanjang (`authMaxAgeSeconds`). Contoh: accounts 90 hari, Kirim Paket 30 hari.
570
+ 5. Setelah itu hapus secret lama: `SESSION_SECRET=<baru>`. Deploy.
571
+
572
+ Menghapus secret lama terlalu cepat membuat user yang cookie-nya belum disegel ulang harus login lagi. Bila secret bocor, langsung ganti tanpa menyimpan yang lama. Semua user akan login ulang.
573
+
574
+ ## 8. Aplikasi yang sudah punya cookie sesi (migrasi)
575
+
576
+ Bagian ini untuk aplikasi yang pindah dari kode OIDC sendiri (Kirim Paket, accounts) ke SDK tanpa membuat user login ulang.
577
+
578
+ Tiga nilai harus **sama persis** dengan yang dipakai kode lama:
579
+
580
+ - `hkdfSalt`;
581
+ - nama cookie di `cookies`;
582
+ - tabel `compactKeys`.
583
+
584
+ `compactKeys` memetakan nama kunci panjang ke nama ringkas di dalam cookie. Tabel inti untuk `auth` (`auth`, `access_token`, `user`, dan seterusnya) sudah ada di SDK dan digabung dengan tabel aplikasi. Aturannya:
585
+
586
+ - Nama kunci (panjang dan ringkas) hanya huruf, angka, dan `_`, 1–32 karakter.
587
+ - Bila `compactKeys` diisi, kunci yang tidak ada di tabel **dibuang** saat disimpan dan saat dibaca. Daftarkan semua nama field aplikasi, di semua tingkat.
588
+ - Bila `compactKeys` tidak diisi, tidak ada kunci yang diganti. Ini pilihan untuk aplikasi baru.
589
+
590
+ **Aturan selama build lama masih bisa membaca cookie.** Selama rolling deploy, dan selama rollback masih mungkin, build lama (sebelum SDK) membaca cookie yang disegel build baru. Skema build lama lebih ketat dari skema SDK:
591
+
592
+ - Aplikasi seperti Kirim Paket **wajib selalu menyimpan `user.email`**. Isi `null` bila tidak diketahui. Jangan dihilangkan.
593
+ - Aplikasi seperti accounts **wajib selalu menyimpan `remember`**.
594
+
595
+ Bila field itu tidak ada, build lama menganggap sesi tidak valid dan user keluar di tengah deploy.
596
+
597
+ Panduan migrasi lengkap per aplikasi menyusul.
598
+
599
+ ## 9. PWA
600
+
601
+ Login dengan redirect tetap bekerja di PWA yang terpasang. Yang perlu diperhatikan:
602
+
603
+ - **`scope` di manifest harus mencakup `/auth/callback`.** Bila callback berada di luar scope, browser membukanya di luar jendela PWA.
604
+ - **Service worker tidak boleh meng-cache atau mencegat `/login`, `/auth/callback`, dan `/logout`.** Ketiganya harus selalu sampai ke server. Kecualikan dari precache dan dari handler `fetch`.
605
+ - Halaman login Plasgos berada di luar scope PWA. Chrome menampilkannya dengan bilah alamat kecil di dalam jendela PWA, lalu kembali ke tampilan PWA dengan sendirinya setelah redirect ke `/auth/callback`. Itu perilaku normal.
606
+ - **Di iOS, PWA yang terpasang punya penyimpanan cookie sendiri**, terpisah dari Safari. User yang sudah login di Safari tetap harus login sekali lagi di dalam PWA.
607
+
608
+ ## 10. Login ulang untuk aksi sensitif
609
+
610
+ Untuk meminta user membuktikan identitasnya lagi sebelum aksi sensitif:
611
+
612
+ 1. Panggil `startLogin({ returnTo, prompt: "login", maxAge: 0, reauth: true })`.
613
+ 2. Di callback, `transaction.reauth` bernilai `true`. Bandingkan `claims.sub` dengan `session.data.auth.user.id`. Bila berbeda, user login dengan akun lain: tolak aksi itu.
614
+ 3. Bila `maxAge` dikirim, SDK mewajibkan klaim `auth_time` dan menolak ID token yang login-nya lebih tua dari `maxAge` (ditambah toleransi 60 detik) dengan `id_token_invalid`.
615
+
616
+ ## 11. React Router
617
+
618
+ Helper loader dan action untuk React Router (`@plasgos/oidc-client/react-router`) belum tersedia dan menyusul di rilis berikutnya. Sampai saat itu, panggil handler di [§4](#4-tiga-route) dari loader dan action Anda sendiri. Keduanya sudah menerima `Request` dan mengembalikan `Response`.