@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.
- package/CHANGELOG.md +31 -0
- package/LICENSE +15 -0
- package/README.md +145 -2
- package/dist/index.cjs +884 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +33 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.js +860 -0
- package/dist/index.js.map +1 -0
- package/dist/service.cjs +432 -0
- package/dist/service.cjs.map +1 -0
- package/dist/service.d.cts +88 -0
- package/dist/service.d.ts +88 -0
- package/dist/service.js +419 -0
- package/dist/service.js.map +1 -0
- package/dist/session.cjs +601 -0
- package/dist/session.cjs.map +1 -0
- package/dist/session.d.cts +289 -0
- package/dist/session.d.ts +289 -0
- package/dist/session.js +568 -0
- package/dist/session.js.map +1 -0
- package/dist/types-JE0OMyoi.d.cts +375 -0
- package/dist/types-JE0OMyoi.d.ts +375 -0
- package/docs/consumers.md +90 -0
- package/docs/contoh-hitungcuan.md +255 -0
- package/docs/contoh-plaslink.md +244 -0
- package/docs/error.md +428 -0
- package/docs/examples/auth-verify-readme.ts +18 -0
- package/docs/examples/config-error.ts +24 -0
- package/docs/examples/env.ts +99 -0
- package/docs/examples/failure-log.ts +18 -0
- package/docs/examples/login-client.ts +46 -0
- package/docs/examples/login-flow.ts +186 -0
- package/docs/examples/plaslink-connect.ts +48 -0
- package/docs/examples/readme.ts +60 -0
- package/docs/examples/service-client.ts +105 -0
- package/docs/examples/session-store.ts +53 -0
- package/docs/examples/webhook-express.ts +46 -0
- package/docs/examples/webhook-fetch.ts +60 -0
- package/docs/examples/webhook-nestjs.ts +59 -0
- package/docs/examples/webhook-testing.ts +60 -0
- package/docs/examples/webhook-verifier.ts +143 -0
- package/docs/login-web.md +618 -0
- package/docs/memulai.md +339 -0
- package/docs/server-ke-server.md +275 -0
- package/docs/webhook.md +625 -0
- 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
|
-
#
|
|
1
|
+
# @plasgos/oidc-client
|
|
2
2
|
|
|
3
|
-
|
|
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.
|