@plasgos/oidc-client 0.0.0-stage → 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 (47) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/LICENSE +15 -0
  3. package/README.md +145 -2
  4. package/dist/index.cjs +884 -0
  5. package/dist/index.cjs.map +1 -0
  6. package/dist/index.d.cts +33 -0
  7. package/dist/index.d.ts +33 -0
  8. package/dist/index.js +860 -0
  9. package/dist/index.js.map +1 -0
  10. package/dist/service.cjs +432 -0
  11. package/dist/service.cjs.map +1 -0
  12. package/dist/service.d.cts +88 -0
  13. package/dist/service.d.ts +88 -0
  14. package/dist/service.js +419 -0
  15. package/dist/service.js.map +1 -0
  16. package/dist/session.cjs +601 -0
  17. package/dist/session.cjs.map +1 -0
  18. package/dist/session.d.cts +289 -0
  19. package/dist/session.d.ts +289 -0
  20. package/dist/session.js +568 -0
  21. package/dist/session.js.map +1 -0
  22. package/dist/types-JE0OMyoi.d.cts +375 -0
  23. package/dist/types-JE0OMyoi.d.ts +375 -0
  24. package/docs/consumers.md +90 -0
  25. package/docs/contoh-hitungcuan.md +255 -0
  26. package/docs/contoh-plaslink.md +244 -0
  27. package/docs/error.md +428 -0
  28. package/docs/examples/auth-verify-readme.ts +18 -0
  29. package/docs/examples/config-error.ts +24 -0
  30. package/docs/examples/env.ts +99 -0
  31. package/docs/examples/failure-log.ts +18 -0
  32. package/docs/examples/login-client.ts +46 -0
  33. package/docs/examples/login-flow.ts +186 -0
  34. package/docs/examples/plaslink-connect.ts +48 -0
  35. package/docs/examples/readme.ts +60 -0
  36. package/docs/examples/service-client.ts +105 -0
  37. package/docs/examples/session-store.ts +53 -0
  38. package/docs/examples/webhook-express.ts +46 -0
  39. package/docs/examples/webhook-fetch.ts +60 -0
  40. package/docs/examples/webhook-nestjs.ts +59 -0
  41. package/docs/examples/webhook-testing.ts +60 -0
  42. package/docs/examples/webhook-verifier.ts +143 -0
  43. package/docs/login-web.md +618 -0
  44. package/docs/memulai.md +339 -0
  45. package/docs/server-ke-server.md +275 -0
  46. package/docs/webhook.md +625 -0
  47. package/package.json +67 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # @plasgos/oidc-client
2
+
3
+ ## 0.1.0-next.2
4
+
5
+ ### Patch Changes
6
+
7
+ - 08750ea: Rilis awal `@plasgos/auth-verify` dengan `@plasgos/auth-verify/webhook`: `createWebhookVerifier` dan `verifyWebhook` untuk webhook payments (`presets.payments`) dan pengiriman Plaslink (`presets.plaslinkShipping`), rotasi secret, batas waktu 300 detik, dan batas ukuran. `WebhookVerifyError` ada di `@plasgos/auth-shared`. Panduan baru `docs/webhook.md`; `contoh-hitungcuan.md`, `contoh-plaslink.md`, `error.md`, dan `memulai.md` diperbarui, dan panduan yang terbit di `@plasgos/oidc-client` ikut berubah. Panduan kini juga ikut di paket `@plasgos/auth-verify`. `LICENSE` di ketiga paket kini menyebut setiap paket (`@plasgos/oidc-client`, `@plasgos/auth-verify`, dan `@plasgos/auth-shared`) dan webhook Plasgos. Pesan `ConfigError` `logoutTicket requires backchannelUrl` di `@plasgos/oidc-client` kini menyebut alamat internal server Plasgos (`the internal Plasgos server URL`).
8
+ - 1bbdbc4: Panduan pemakaian kini ikut di paket `@plasgos/oidc-client`, di folder `docs/` (`memulai.md`, `login-web.md`, `server-ke-server.md`, `error.md`, `contoh-hitungcuan.md`, `contoh-plaslink.md`, `consumers.md`, dan file contoh di `docs/examples/`). Panduan bisa dibaca di tab Code halaman paket di npmjs.com atau di `node_modules/@plasgos/oidc-client/docs/`. Tidak ada perubahan kode.
9
+ - Updated dependencies [08750ea]
10
+ - Updated dependencies [1bbdbc4]
11
+ - @plasgos/auth-shared@0.1.0-next.2
12
+
13
+ ## 0.1.0-next.1
14
+
15
+ ### Patch Changes
16
+
17
+ - e6cc65b: Paket dipublish ke npmjs.com sebagai paket publik dengan lisensi Plasgos (`SEE LICENSE IN LICENSE`), tidak lagi di GitHub Packages. Install tidak butuh token: `pnpm add @plasgos/oidc-client@<versi> --save-exact`. Versi `0.1.0-next.0` hanya pernah terbit di GitHub Packages; rilis npmjs dimulai dari versi ini.
18
+ - Updated dependencies [e6cc65b]
19
+ - @plasgos/auth-shared@0.1.0-next.1
20
+
21
+ ## 0.1.0-next.0
22
+
23
+ ### Minor Changes
24
+
25
+ - 725d338: Rilis awal `@plasgos/oidc-client`: `createOidcClient` (login, callback, refresh, `ensureFresh`, logout), `/session` (cookie tersegel yang kompatibel dengan shipping-v2 dan accounts-v2), dan `/service` (`client_credentials` dengan cache). Panduan: `docs/guides/memulai.md`, `login-web.md`, `server-ke-server.md`, `error.md`, `contoh-hitungcuan.md`, `contoh-plaslink.md`.
26
+
27
+ ### Patch Changes
28
+
29
+ - Updated dependencies [251d392]
30
+ - Updated dependencies [725d338]
31
+ - @plasgos/auth-shared@0.1.0-next.0
package/LICENSE ADDED
@@ -0,0 +1,15 @@
1
+ Hak Cipta (c) 2026 Plasgos. Seluruh hak dilindungi.
2
+
3
+ Perangkat lunak ini (paket npm @plasgos/oidc-client, @plasgos/auth-verify, dan @plasgos/auth-shared beserta
4
+ dokumentasinya) adalah milik Plasgos dan disediakan HANYA untuk menghubungkan aplikasi ke layanan Plasgos
5
+ (login Plasgos, API Plasgos, dan webhook Plasgos) oleh pihak yang memiliki kredensial client resmi dari
6
+ Plasgos, sesuai ketentuan layanan Plasgos.
7
+
8
+ Pemegang kredensial tersebut dan pengembang yang bekerja untuk mereka boleh memasang dan memanggil perangkat
9
+ lunak ini di aplikasi mereka untuk keperluan itu. Selain itu, tanpa izin tertulis Plasgos, dilarang menyalin,
10
+ mengubah, menggabungkan, menerbitkan ulang, mendistribusikan, mensublisensikan, menjual, atau membuat karya
11
+ turunan dari perangkat lunak ini, seluruhnya maupun sebagian.
12
+
13
+ PERANGKAT LUNAK INI DISEDIAKAN "SEBAGAIMANA ADANYA", TANPA JAMINAN APA PUN. DALAM KEADAAN APA PUN PLASGOS
14
+ TIDAK BERTANGGUNG JAWAB ATAS KLAIM, KERUSAKAN, ATAU KEWAJIBAN LAIN YANG TIMBUL DARI ATAU BERKAITAN DENGAN
15
+ PERANGKAT LUNAK INI ATAU PEMAKAIANNYA, KECUALI DIATUR LAIN DALAM PERJANJIAN LAYANAN.
package/README.md CHANGED
@@ -1,3 +1,146 @@
1
- # Temporary Holding Version
1
+ # @plasgos/oidc-client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Client OIDC Plasgos untuk server Node. Paket ini untuk aplikasi yang **meminta** token ke Plasgos:
4
+
5
+ - login user lewat browser (authorization code + PKCE);
6
+ - sesi login di cookie terenkripsi;
7
+ - token server-ke-server (`client_credentials`) untuk memanggil API Plasgos tanpa user.
8
+
9
+ Hanya untuk server (Node `>=22.22`), tersedia sebagai ESM dan CommonJS. Tidak ada dependensi runtime selain `@plasgos/auth-shared`, yang ikut terpasang dengan versi yang sama.
10
+
11
+ ## Install
12
+
13
+ Paket ini ada di npmjs.com dan di-install tanpa token. Pakai nomor versi persis, karena versi yang terbit masih pre-release:
14
+
15
+ ```bash
16
+ pnpm add @plasgos/oidc-client@<versi> --save-exact
17
+ ```
18
+
19
+ Aturan versi, Docker, dan CI ada di [`docs/consumers.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/consumers.md).
20
+
21
+ ## Lisensi
22
+
23
+ Bukan open source. Paket ini milik Plasgos dan hanya boleh dipakai untuk menghubungkan aplikasi ke layanan Plasgos oleh pemegang kredensial client resmi dari Plasgos. Lihat file `LICENSE` di paket ini.
24
+
25
+ ## Isi paket
26
+
27
+ | Import | Untuk | Panduan |
28
+ |---|---|---|
29
+ | `@plasgos/oidc-client` | Login user: `createOidcClient` | [`login-web.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/login-web.md) |
30
+ | `@plasgos/oidc-client/session` | Cookie sesi tersegel: `createSessionStore` | [`login-web.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/login-web.md) |
31
+ | `@plasgos/oidc-client/service` | Server ke server: `createServiceClient` | [`server-ke-server.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/server-ke-server.md) |
32
+
33
+ Mulai dari [`docs/memulai.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/memulai.md): paket mana yang dipakai, env, sandbox dan production, scope, dan cara mendapat kredensial. Daftar semua panduan ada di [Panduan](#panduan).
34
+
35
+ ## Contoh
36
+
37
+ Setiap fungsi `create…` wajib menerima `environment: "sandbox" | "production"`. Nilai ini pengaman, bukan pemilih URL: aplikasi menolak start bila `environment` tidak cocok dengan URL yang diberikan.
38
+
39
+ ### `@plasgos/oidc-client`: login user
40
+
41
+ <!-- snippet: examples/snippets/readme.ts#login -->
42
+ ```ts
43
+ export function createClient(): OidcClient {
44
+ return createOidcClient({
45
+ environment: "production",
46
+ issuer: "https://accounts.plasgos.co.id",
47
+ clientId: process.env.PLASGOS_LOGIN_CLIENT_ID ?? "",
48
+ clientSecret: process.env.PLASGOS_LOGIN_CLIENT_SECRET ?? "",
49
+ redirectUri: "https://app.example.com/auth/callback",
50
+ scopes: ["openid", "profile", "email"],
51
+ profile: "third-party",
52
+ });
53
+ }
54
+
55
+ /** GET /login: redirects the browser to Plasgos. */
56
+ export function login(client: OidcClient, store: SessionStore<object>): Response {
57
+ const { location, transaction } = client.startLogin({ returnTo: "/" });
58
+ const headers = { Location: location, "Set-Cookie": store.commitTransaction(transaction) };
59
+ return new Response(null, { status: 302, headers });
60
+ }
61
+ ```
62
+ <!-- /snippet -->
63
+
64
+ Client mengembalikan `startLogin`, `handleCallback`, `refresh`, `ensureFresh`, dan `logout`. Route callback dan logout yang lengkap ada di [`login-web.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/login-web.md).
65
+
66
+ ### `@plasgos/oidc-client/session`: cookie sesi
67
+
68
+ <!-- snippet: examples/snippets/readme.ts#session -->
69
+ ```ts
70
+ export function createStore(): SessionStore<object> {
71
+ return createSessionStore<object>({
72
+ environment: "production",
73
+ secrets: [process.env.SESSION_SECRET ?? ""],
74
+ hkdfSalt: "app-example",
75
+ cookies: { app: "ax", auth: "ax-auth", idToken: "ax-idt", transaction: "ax-oidc" },
76
+ authMaxAgeSeconds: 2_592_000,
77
+ // This app keeps no data of its own in the session, only the SDK's auth.
78
+ appSchema: { parse: () => ({}) },
79
+ });
80
+ }
81
+
82
+ /** The signed-in user of a request, or null. */
83
+ export function currentUser(store: SessionStore<object>, request: Request): SessionUser | null {
84
+ return store.read(request).data.auth?.user ?? null;
85
+ }
86
+ ```
87
+ <!-- /snippet -->
88
+
89
+ Sesi disegel dengan AES-256-GCM (kunci HKDF per cookie, nama cookie terikat sebagai AAD). Cookie yang rusak atau tidak bisa dibuka dianggap tidak ada, tidak pernah menjadi error. Format cookie kompatibel dengan cookie aplikasi Plasgos (Kirim Paket dan accounts) yang sudah beredar.
90
+
91
+ ### `@plasgos/oidc-client/service`: server ke server
92
+
93
+ <!-- snippet: examples/snippets/readme.ts#service -->
94
+ ```ts
95
+ export async function whoAmI(): Promise<unknown> {
96
+ const plasgos = createServiceClient({
97
+ environment: "production",
98
+ issuer: "https://accounts.plasgos.co.id",
99
+ apiUrl: "https://api.plasgos.co.id",
100
+ clientId: process.env.PLASGOS_SERVICE_CLIENT_ID ?? "",
101
+ clientSecret: process.env.PLASGOS_SERVICE_CLIENT_SECRET ?? "",
102
+ scopes: ["platform:self.read"],
103
+ });
104
+ const res = await plasgos.fetch("/v5/service/me");
105
+ return res.json();
106
+ }
107
+ ```
108
+ <!-- /snippet -->
109
+
110
+ Token disimpan di memori dan diminta lagi saat hampir habis. `fetch` mengulang satu kali bila API menjawab `401 invalid_token`, dan tidak mengikuti redirect.
111
+
112
+ ## Daftar export
113
+
114
+ | Import | Fungsi dan nilai | Type |
115
+ |---|---|---|
116
+ | `@plasgos/oidc-client` | `createOidcClient`, `accessTokenExpiry`, `memoryLockStore`, `OidcError`, `ConfigError` | `OidcClient`, `OidcClientOptions`, `StartLoginInput`, `StartLoginResult`, `HandleCallbackOptions`, `CallbackResult`, `VerifiedIdTokenClaims`, `EnsureFreshOptions`, `EnsureFreshResult`, `RefreshableAuth`, `LogoutInput`, `LogoutResult`, `OidcTransaction`, `OidcFetch`, `RefreshLockStore`, `OidcFailureEvent`, `OidcOperation`, `OidcErrorReason`, `OidcUpstream`, `ClientProfile`, `Environment`, `IdTokenClaims`, `TokenSet`, `UserScope` |
117
+ | `@plasgos/oidc-client/session` | `createSessionStore`, `SessionTooLargeError`, `memoryLockStore`, `deriveKeyRing`, `sealCookie`, `openCookie`, `ConfigError` | `SessionStore`, `SessionStoreOptions`, `SessionHandle`, `SessionData`, `SessionSchema`, `SessionFailureEvent`, `AuthState`, `SessionUser`, `OidcTransaction`, `RefreshLockStore`, `KeyRing` |
118
+ | `@plasgos/oidc-client/service` | `createServiceClient`, `OidcError`, `ConfigError` | `ServiceClient`, `ServiceClientOptions`, `ServiceScope`, `OidcFailureEvent`, `OidcOperation`, `OidcFetch`, `OidcErrorReason`, `OidcUpstream`, `Environment` |
119
+
120
+ Setiap export punya JSDoc dengan contoh.
121
+
122
+ ## Kegagalan
123
+
124
+ - Opsi yang salah: `ConfigError` saat `create…` dipanggil, memuat semua masalah sekaligus. `ConfigError` diekspor oleh ketiga entry, jadi `error instanceof ConfigError` bekerja bila kelasnya di-import dari `@plasgos/oidc-client`. Aplikasi yang mencampur `import` dan `require` memeriksa `error.name`.
125
+ - Kegagalan saat berjalan: `OidcError` dengan `reason`.
126
+ - Paket tidak pernah menulis log. Setiap kegagalan diserahkan ke hook `onFailure` milik aplikasi.
127
+ - Pesan error dan event tidak pernah memuat token, code, secret, atau isi cookie.
128
+
129
+ Arti setiap `reason`, penyebab umum, dan penanganannya ada di [`error.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/error.md).
130
+
131
+ ## Panduan
132
+
133
+ Panduan pemakaian (Bahasa Indonesia) ikut di paket ini, di folder `docs/`. Link di bawah membuka pre-release terbaru secara online (jsDelivr, tag `next`). Untuk versi yang Anda pasang, bacanya di `node_modules/@plasgos/oidc-client/docs/`, atau di tab **Code** halaman paket di npmjs.com.
134
+
135
+ | Panduan | Untuk apa |
136
+ |---|---|
137
+ | [`memulai.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/memulai.md) | Mulai dari sini: paket mana untuk kebutuhan apa, env, sandbox dan production, scope, cara mendapat kredensial |
138
+ | [`login-web.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/login-web.md) | Login user di aplikasi web: route login, callback, logout, sesi cookie, refresh |
139
+ | [`server-ke-server.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/server-ke-server.md) | Memanggil API Plasgos dari server tanpa user (`client_credentials`), contoh payments |
140
+ | [`webhook.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/webhook.md) | Menerima webhook dari Plasgos dengan `@plasgos/auth-verify/webhook` |
141
+ | [`error.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/error.md) | Semua error dan `reason`: arti, penyebab umum, penanganan |
142
+ | [`contoh-hitungcuan.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/contoh-hitungcuan.md) | Contoh lengkap aplikasi yang hanya memakai payments |
143
+ | [`contoh-plaslink.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/contoh-plaslink.md) | Contoh lengkap login seller dan payments |
144
+ | [`consumers.md`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/consumers.md) | Install, Docker, CI, aturan versi, lisensi |
145
+
146
+ File contoh yang dikutip panduan ada di [`docs/examples/`](https://cdn.jsdelivr.net/npm/@plasgos/oidc-client@next/docs/examples/). Semuanya lolos typecheck terhadap versi paket ini.