@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.
- package/CHANGELOG.md +27 -0
- package/LICENSE +4 -3
- package/README.md +27 -14
- package/dist/index.cjs +2 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/service.cjs +1 -1
- package/dist/service.cjs.map +1 -1
- package/dist/service.d.cts +3 -3
- package/dist/service.d.ts +3 -3
- package/dist/service.js +1 -1
- package/dist/service.js.map +1 -1
- package/dist/session.cjs +71 -20
- package/dist/session.cjs.map +1 -1
- package/dist/session.d.cts +57 -6
- package/dist/session.d.ts +57 -6
- package/dist/session.js +63 -13
- package/dist/session.js.map +1 -1
- package/dist/{types-Cncksfeo.d.cts → types-JE0OMyoi.d.cts} +1 -1
- package/dist/{types-Cncksfeo.d.ts → types-JE0OMyoi.d.ts} +1 -1
- package/docs/bff-express.md +1314 -0
- package/docs/consumers.md +98 -0
- package/docs/contoh-hitungcuan.md +255 -0
- package/docs/contoh-plaslink.md +244 -0
- package/docs/error.md +613 -0
- package/docs/examples/auth-verify-readme.ts +42 -0
- package/docs/examples/bff-express.ts +370 -0
- package/docs/examples/bff-proxy.ts +335 -0
- package/docs/examples/bff-redis-lock.ts +187 -0
- package/docs/examples/bff-revocation.ts +136 -0
- package/docs/examples/config-error.ts +24 -0
- package/docs/examples/env.ts +150 -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/token-commonjs.cjs +95 -0
- package/docs/examples/token-express.ts +56 -0
- package/docs/examples/token-fetch.ts +24 -0
- package/docs/examples/token-nestjs-jest.ts +77 -0
- package/docs/examples/token-nestjs.ts +127 -0
- package/docs/examples/token-socket.ts +59 -0
- package/docs/examples/token-testing.ts +100 -0
- package/docs/examples/token-verifier.ts +132 -0
- package/docs/examples/user-events.ts +110 -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 +197 -0
- package/docs/login-web.md +650 -0
- package/docs/memulai.md +419 -0
- package/docs/server-ke-server.md +287 -0
- package/docs/verifikasi-token.md +1219 -0
- package/docs/webhook.md +810 -0
- package/package.json +3 -2
package/docs/memulai.md
ADDED
|
@@ -0,0 +1,419 @@
|
|
|
1
|
+
# Memulai
|
|
2
|
+
|
|
3
|
+
Panduan ini untuk tim yang menghubungkan aplikasi server (Node) ke Plasgos. Isinya: paket mana yang dipakai, env apa yang diatur, beda sandbox dan production, dua jenis client beserta scope-nya, dan cara mendapat kredensial.
|
|
4
|
+
|
|
5
|
+
Urutan kerja yang disarankan:
|
|
6
|
+
|
|
7
|
+
1. Tentukan kebutuhan aplikasi di [§1](#1-paket-mana-untuk-kebutuhan-apa).
|
|
8
|
+
2. Minta kredensial ke tim Plasgos ([§6](#6-mendapat-kredensial)).
|
|
9
|
+
3. Install paket ([§2](#2-install)) dan atur env ([§5](#5-env-yang-disarankan)).
|
|
10
|
+
4. Lanjut ke panduan sesuai kebutuhan: [`login-web.md`](login-web.md), [`server-ke-server.md`](server-ke-server.md), [`webhook.md`](webhook.md), atau [`verifikasi-token.md`](verifikasi-token.md).
|
|
11
|
+
|
|
12
|
+
## 1. Paket mana untuk kebutuhan apa
|
|
13
|
+
|
|
14
|
+
| Kebutuhan aplikasi | Import | Fungsi utama | Panduan |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| User login dengan akun Plasgos | `@plasgos/oidc-client` | `createOidcClient` | [`login-web.md`](login-web.md) |
|
|
17
|
+
| Menyimpan sesi login di cookie | `@plasgos/oidc-client/session` | `createSessionStore` | [`login-web.md`](login-web.md) |
|
|
18
|
+
| Server memanggil API Plasgos tanpa user (misalnya payments) | `@plasgos/oidc-client/service` | `createServiceClient` | [`server-ke-server.md`](server-ke-server.md) |
|
|
19
|
+
| Menerima webhook dari Plasgos (payments, event aplikasi, pengiriman Plaslink) | `@plasgos/auth-verify/webhook` | `createWebhookVerifier` | [`webhook.md`](webhook.md) |
|
|
20
|
+
| Memeriksa access token Plasgos di API sendiri | `@plasgos/auth-verify` | `createAccessTokenVerifier` | [`verifikasi-token.md`](verifikasi-token.md) |
|
|
21
|
+
| Sama, sebagai middleware Express | `@plasgos/auth-verify/express` | `requirePlasgosToken` | [`verifikasi-token.md`](verifikasi-token.md#9-express) |
|
|
22
|
+
| Sama, sebagai modul dan guard NestJS | `@plasgos/auth-verify/nestjs` | `PlasgosAuthModule`, `PlasgosAccessTokenGuard` | [`verifikasi-token.md`](verifikasi-token.md#10-nestjs) |
|
|
23
|
+
| BFF Node/Express untuk SPA atau PWA: sesi cookie, lock refresh Redis, proxy ke API sendiri | `@plasgos/oidc-client`, `@plasgos/oidc-client/session` | `createOidcClient`, `createSessionStore`, `readAccessTokenClaims` | [`bff-express.md`](bff-express.md) |
|
|
24
|
+
|
|
25
|
+
Contoh per jenis aplikasi:
|
|
26
|
+
|
|
27
|
+
| Aplikasi | Yang dipakai | Contoh lengkap |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| Aplikasi Plasgos sendiri (accounts, Kirim Paket) | Login + sesi cookie | [`login-web.md`](login-web.md) |
|
|
30
|
+
| Plaslink | Login (seller menghubungkan akun) + payments + webhook | [`contoh-plaslink.md`](contoh-plaslink.md) |
|
|
31
|
+
| HitungCuan | Payments + webhook, tanpa login | [`contoh-hitungcuan.md`](contoh-hitungcuan.md) |
|
|
32
|
+
| API yang dipanggil aplikasi lain dengan token user (misalnya API CRM) | Verifikasi token + webhook event aplikasi + client service (`/service`) | [`verifikasi-token.md`](verifikasi-token.md), [`webhook.md`](webhook.md), [`server-ke-server.md`](server-ke-server.md) |
|
|
33
|
+
|
|
34
|
+
Semua paket hanya untuk server: Node `>=22.22`, tersedia sebagai ESM dan CommonJS. Tidak ada build untuk browser. Secret client tidak boleh sampai ke browser.
|
|
35
|
+
|
|
36
|
+
## 2. Install
|
|
37
|
+
|
|
38
|
+
Paket ada di npmjs.com dan di-install tanpa token, dengan nomor versi persis:
|
|
39
|
+
|
|
40
|
+
- login, sesi, dan server ke server: `pnpm add @plasgos/oidc-client@<versi> --save-exact`;
|
|
41
|
+
- menerima webhook atau memeriksa access token di API sendiri: `pnpm add @plasgos/auth-verify@<versi> --save-exact`. Import-nya `@plasgos/auth-verify` (verifier token), `@plasgos/auth-verify/express` (middleware Express), `@plasgos/auth-verify/nestjs` (modul dan guard NestJS 11), dan `@plasgos/auth-verify/webhook`.
|
|
42
|
+
|
|
43
|
+
Install hanya paket yang dibutuhkan. Aplikasi yang memakai keduanya memasang versi yang sama untuk keduanya. `@plasgos/auth-shared` ikut terpasang sendiri. Aturan versi, Docker, CI, dan lisensi ada di [`consumers.md`](consumers.md).
|
|
44
|
+
|
|
45
|
+
Proyek TypeScript harus memakai `moduleResolution` `node16`, `nodenext`, atau `bundler` di `tsconfig.json`. Dengan `moduleResolution: node` yang lama, import `@plasgos/oidc-client/service` dan `/session` gagal dengan `Cannot find module`, begitu juga `@plasgos/auth-verify/webhook`, `/express`, dan `/nestjs`. File di [folder contoh](examples/) saling meng-import dengan akhiran `.js` (gaya NodeNext); sesuaikan bila proyek Anda memakai gaya lain.
|
|
46
|
+
|
|
47
|
+
## 3. Dua jenis client
|
|
48
|
+
|
|
49
|
+
Satu paket melayani dua jenis client. Keduanya memakai kredensial yang berbeda dan scope yang tidak boleh tertukar.
|
|
50
|
+
|
|
51
|
+
| | Client login | Client service |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| Dipakai untuk | User login lewat browser | Server memanggil API Plasgos tanpa user |
|
|
54
|
+
| Fungsi | `createOidcClient` | `createServiceClient` |
|
|
55
|
+
| Import | `@plasgos/oidc-client` | `@plasgos/oidc-client/service` |
|
|
56
|
+
| Kredensial | Client interaktif | Client service milik app |
|
|
57
|
+
| Scope | Scope user ([§4](#scope-user-client-login)) | Scope service ([§4](#scope-service-client-service)) |
|
|
58
|
+
| Token mewakili | User yang login | App saja, tanpa user |
|
|
59
|
+
| Refresh token | Ada untuk aplikasi Plasgos sendiri; untuk pihak ketiga hanya bila punya `offline_access` | Tidak ada. Token baru diminta lagi saat hampir habis |
|
|
60
|
+
|
|
61
|
+
Bila scope tertukar, aplikasi gagal start dengan `ConfigError` yang menunjuk fungsi yang benar:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
scopes: "payments:write" is a service scope; use createServiceClient from @plasgos/oidc-client/service
|
|
65
|
+
scopes: "openid" is a user scope; use createOidcClient from @plasgos/oidc-client
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Aplikasi yang butuh keduanya (Plaslink) membuat dua client dengan dua pasang kredensial.
|
|
69
|
+
|
|
70
|
+
**Token hanya membawa identitas.** Token Plasgos berisi siapa user-nya (`sub`, `name`, `picture`, `email`), scope yang disetujui, dan id sesi (`sid`). Token tidak pernah membawa role atau tim. Hak akses di dalam aplikasi Anda tetap diatur aplikasi Anda sendiri.
|
|
71
|
+
|
|
72
|
+
`sub` bersifat pairwise: user yang sama mendapat `sub` berbeda di setiap client. Jangan membandingkan `sub` antar client.
|
|
73
|
+
|
|
74
|
+
### Istilah
|
|
75
|
+
|
|
76
|
+
Istilah berikut dipakai di semua panduan:
|
|
77
|
+
|
|
78
|
+
| Istilah | Arti |
|
|
79
|
+
|---|---|
|
|
80
|
+
| Audience | Alamat yang mewakili satu API, misalnya `https://api.plasgos.co.id/crm`. Token diterbitkan untuk satu audience (klaim `aud`), dan API hanya menerima token untuk audience-nya sendiri. Aplikasi yang meminta token menyebut audience itu sebagai `resource` |
|
|
81
|
+
| BFF | Backend-for-frontend: server milik aplikasi yang memegang sesi login user untuk SPA atau PWA, menyimpan token Plasgos di server, dan meneruskan request browser ke API aplikasi dengan token itu. Token tidak pernah sampai ke browser ([`bff-express.md`](bff-express.md)) |
|
|
82
|
+
| `sub` pairwise | Klaim `sub` (id user) yang berbeda untuk setiap client: user yang sama punya `sub` lain di aplikasi lain. Jangan dipakai untuk mengenali user lintas aplikasi |
|
|
83
|
+
| `sid` | Id sesi login user di Plasgos. Satu login di satu browser adalah satu sesi; logout atau pencabutan sesi mengakhirinya |
|
|
84
|
+
| `cv` | Versi kredensial user (credential version). Naik setiap kali kredensial user berubah atau semua sesinya dicabut, misalnya saat ganti password. Token membawa versi saat token diterbitkan, jadi token dengan `cv` lebih kecil dari versi terbaru sudah dicabut |
|
|
85
|
+
| `plasgos_public_id` | Id publik user (`usr-…`), sama di semua aplikasi. Dibawa token hanya bila client meminta scope `plasgos:public_id`. Inilah kunci user di API yang dipanggil lebih dari satu client |
|
|
86
|
+
|
|
87
|
+
## 4. Daftar scope
|
|
88
|
+
|
|
89
|
+
`scopes` selalu berupa daftar string, satu scope per elemen: `["openid", "profile"]`. Jangan menulis satu string berisi beberapa scope (`"openid profile"` atau `"openid,profile"`). String yang memuat spasi ditolak SDK saat start (`scopes contains a value that is not a valid scope token`). Bentuk dengan koma tidak dikenali SDK, diteruskan apa adanya, lalu ditolak Plasgos.
|
|
90
|
+
|
|
91
|
+
Scope yang belum dikenal SDK diteruskan tanpa pemeriksaan. Plasgos yang memutuskan.
|
|
92
|
+
|
|
93
|
+
### Scope service (client service)
|
|
94
|
+
|
|
95
|
+
| Scope | Arti |
|
|
96
|
+
|---|---|
|
|
97
|
+
| `platform:self.read` | `GET /v5/service/me`, untuk cek koneksi |
|
|
98
|
+
| `payments:read` | Melihat payment milik app sendiri dan daftar metode bayar |
|
|
99
|
+
| `payments:write` | Membuat payment, mengganti metode, membatalkan |
|
|
100
|
+
| `payments:refund` | Refund |
|
|
101
|
+
| `users:profile.read` | Profil dan pencarian user yang tertaut ke app Anda. Tersedia setelah Plasgos merilisnya |
|
|
102
|
+
| `users:legacy.read` | Impor tautan dan id user dari sistem lama, sementara. Tersedia setelah Plasgos merilisnya |
|
|
103
|
+
| `packages:service.read` | Origin, layanan, wilayah, slot, quote, dan paket. Tersedia setelah Plasgos merilisnya |
|
|
104
|
+
| `packages:service.write` | Membuat, mengirim, dan membatalkan paket. Tersedia setelah Plasgos merilisnya |
|
|
105
|
+
| `subscriptions:catalog.write` | Mengirim dan membaca katalog modul dan fitur app Anda. Tersedia setelah Plasgos merilisnya |
|
|
106
|
+
| `subscriptions:read` | Membaca entitlement dan grant. Tersedia setelah Plasgos merilisnya |
|
|
107
|
+
| `subscriptions:grants.write` | Mengonfirmasi pengiriman grant. Tersedia setelah Plasgos merilisnya |
|
|
108
|
+
|
|
109
|
+
### Scope user (client login)
|
|
110
|
+
|
|
111
|
+
| Scope | Arti | Siapa yang boleh |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| `openid` | Wajib. Memberi `sub` | Semua |
|
|
114
|
+
| `profile` | `name`, `picture` | Semua |
|
|
115
|
+
| `email` | `email` | Semua |
|
|
116
|
+
| `phone` | `phone_number` dan `phone_number_verified`, hanya bila nomor ponsel akun sudah terverifikasi (tanpa nomor terverifikasi, keduanya tidak dikirim). Pada login dengan `resource`, klaim ada di ID token dan dibaca lewat opsi `extraClaims`. Lihat catatan klaim profil di bawah tabel | Semua |
|
|
117
|
+
| `offline_access` | Refresh token | Semua, bila client didaftarkan dengan scope ini |
|
|
118
|
+
| `plaslink:shipping` | Persetujuan seller untuk pengiriman lewat Plaslink | Client Plaslink |
|
|
119
|
+
| `plasgos:public_id` | Klaim `plasgos_public_id` (`usr-…`) | First-party saja |
|
|
120
|
+
| `account:read`, `account:write` | API akun | First-party saja, wajib `resource` |
|
|
121
|
+
| `packages:read`, `packages:write` | API seller Kirim Paket | First-party saja, wajib `resource` |
|
|
122
|
+
| `crm:access` | API CRM, dengan `resource` berisi audience CRM (`https://api.plasgos.co.id/crm` di production). Tersedia setelah Plasgos merilisnya | First-party saja, wajib `resource` |
|
|
123
|
+
|
|
124
|
+
"First-party" berarti aplikasi milik Plasgos sendiri (`profile: "first-party"`). Aplikasi lain memakai `profile: "third-party"` dan tidak bisa meminta scope first-party.
|
|
125
|
+
|
|
126
|
+
Klaim profil (`name`, `picture`, `email`, `phone_number`) masuk ID token hanya pada login dengan `resource`. Tanpa `resource`, termasuk semua client pihak ketiga, ID token hanya membawa `sub`, dan klaim itu diambil dari endpoint userinfo (`/oidc/me`) dengan access token hasil login. SDK ini belum menyediakan fungsi untuk memanggil userinfo.
|
|
127
|
+
|
|
128
|
+
## 5. Env yang disarankan
|
|
129
|
+
|
|
130
|
+
Nama env bebas, tetapi nama di bawah dipakai di semua contoh panduan ini.
|
|
131
|
+
|
|
132
|
+
| Env | Wajib | Contoh | Arti |
|
|
133
|
+
|---|---|---|---|
|
|
134
|
+
| `PLASGOS_ENV` | Ya | `sandbox` | `sandbox` atau `production`. Tidak punya nilai bawaan |
|
|
135
|
+
| `PLASGOS_ISSUER` | Bila ada login atau panggilan API | `https://accounts.plasgos.co.id` | Host tempat user login dan token diterbitkan (`/oidc/*`) |
|
|
136
|
+
| `PLASGOS_API_URL` | Bila ada login atau panggilan API | `https://api.plasgos.co.id` | Host API Plasgos (`/v5/*`) |
|
|
137
|
+
| `PLASGOS_BACKCHANNEL_URL` | Tidak | `http://plasgos.internal.example:8080` (alamat internal, contoh) | Alamat internal server Plasgos. Hanya untuk aplikasi yang berjalan di jaringan Plasgos |
|
|
138
|
+
| `PLASGOS_LOGIN_CLIENT_ID`, `PLASGOS_LOGIN_CLIENT_SECRET` | Bila ada login | | Kredensial client login |
|
|
139
|
+
| `PLASGOS_SERVICE_CLIENT_ID`, `PLASGOS_SERVICE_CLIENT_SECRET` | Bila ada panggilan server-ke-server | | Kredensial client service |
|
|
140
|
+
| `PLASGOS_AUDIENCE` | Tidak | `https://api.sandbox.plasgos.co.id/platform` | Audience token service. Audience = API yang dituju token (`resource`). Diisi hanya bila tim Plasgos memberi nilai yang berbeda dari bawaan |
|
|
141
|
+
| `PLASGOS_RESOURCE` | First-party saja | `https://api.plasgos.co.id/packages` | Audience API yang dipanggil atas nama user |
|
|
142
|
+
| `PLASGOS_TOKEN_AUDIENCE` | Bila API Anda memverifikasi access token | `https://api.plasgos.co.id/crm` | Audience API Anda sendiri, dari tim Plasgos. `aud` setiap token harus sama persis ([`verifikasi-token.md` §3](verifikasi-token.md#3-env)) |
|
|
143
|
+
| `PLASGOS_ALLOW_INSECURE_BACKCHANNEL` | Tidak | `true` | Hanya untuk verifikasi token di production: menerima `PLASGOS_BACKCHANNEL_URL` `http:` di jaringan privat yang Anda percaya ([`verifikasi-token.md` §13](verifikasi-token.md#13-alamat-internal-backchannelurl)) |
|
|
144
|
+
| `APP_URL` | Bila ada login | `https://app.example.com` | Origin publik aplikasi Anda, dasar `redirectUri` |
|
|
145
|
+
| `APP_API_URL` | Bila memakai BFF | `http://api.internal:8080` (contoh) | Origin API milik aplikasi di belakang BFF ([`bff-express.md` §4](bff-express.md#4-env)). Bukan nilai dari Plasgos |
|
|
146
|
+
| `SESSION_SECRET` | Bila memakai `/session` | | Secret cookie sesi, minimal 32 byte. Saat rotasi: `baru,lama` |
|
|
147
|
+
| `PLASGOS_WEBHOOK_SECRET` | Bila menerima webhook aplikasi | | Secret endpoint webhook aplikasi (`whsec_…`): satu endpoint dan satu secret untuk event payments dan event aplikasi lain (langganan, paket, `user.*`). Saat rotasi: `baru,lama`, bila kedua secret tidak memuat koma dan tidak diawali atau diakhiri spasi; bila memuat, pakai dua env ([`webhook.md` §4](webhook.md#4-membuat-verifier), [§8](webhook.md#8-rotasi-secret)) |
|
|
148
|
+
| `PLASGOS_SHIPPING_WEBHOOK_SECRET` | Bila menerima webhook pengiriman Plaslink | | Secret webhook pengiriman Plaslink. Saat rotasi: `baru,lama`, dengan aturan yang sama |
|
|
149
|
+
|
|
150
|
+
Semua nilai secret (`*_CLIENT_SECRET`, `SESSION_SECRET`, `PLASGOS_WEBHOOK_SECRET`, `PLASGOS_SHIPPING_WEBHOOK_SECRET`) disimpan di secret manager aplikasi. Jangan di-commit, jangan ditulis ke log.
|
|
151
|
+
|
|
152
|
+
Contoh pembacaan env yang gagal dengan jelas bila ada nilai yang kosong. File ini dipakai contoh lain di panduan:
|
|
153
|
+
|
|
154
|
+
<!-- snippet: examples/snippets/env.ts -->
|
|
155
|
+
```ts
|
|
156
|
+
/** Same values as the SDK's `Environment` type. */
|
|
157
|
+
type Environment = "sandbox" | "production";
|
|
158
|
+
|
|
159
|
+
function required(name: string): string {
|
|
160
|
+
const value = process.env[name]?.trim() ?? "";
|
|
161
|
+
if (value === "") throw new Error(`Environment variable ${name} is required`);
|
|
162
|
+
return value;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function optional(name: string): string | undefined {
|
|
166
|
+
const value = process.env[name]?.trim() ?? "";
|
|
167
|
+
return value === "" ? undefined : value;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** PLASGOS_ENV: "sandbox" or "production". There is no default on purpose. */
|
|
171
|
+
export function readEnvironment(): Environment {
|
|
172
|
+
const value = required("PLASGOS_ENV");
|
|
173
|
+
if (value !== "sandbox" && value !== "production") {
|
|
174
|
+
throw new Error('Environment variable PLASGOS_ENV must be "sandbox" or "production"');
|
|
175
|
+
}
|
|
176
|
+
return value;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** What every Plasgos client of this app shares. */
|
|
180
|
+
export interface PlasgosEnv {
|
|
181
|
+
environment: Environment;
|
|
182
|
+
/** PLASGOS_ISSUER: where users log in and tokens are issued. */
|
|
183
|
+
issuer: string;
|
|
184
|
+
/** PLASGOS_API_URL: where /v5/* lives. */
|
|
185
|
+
apiUrl: string;
|
|
186
|
+
/** PLASGOS_BACKCHANNEL_URL: optional internal origin of the Plasgos server, only inside the Plasgos network. */
|
|
187
|
+
backchannelUrl: string | undefined;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
export function readPlasgosEnv(): PlasgosEnv {
|
|
191
|
+
return {
|
|
192
|
+
environment: readEnvironment(),
|
|
193
|
+
issuer: required("PLASGOS_ISSUER"),
|
|
194
|
+
apiUrl: required("PLASGOS_API_URL"),
|
|
195
|
+
backchannelUrl: optional("PLASGOS_BACKCHANNEL_URL"),
|
|
196
|
+
};
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Credentials of the service client (server-to-server). */
|
|
200
|
+
export interface ServiceCredentials {
|
|
201
|
+
clientId: string;
|
|
202
|
+
clientSecret: string;
|
|
203
|
+
/** PLASGOS_AUDIENCE: only when the environment does not use the default platform audience. */
|
|
204
|
+
audience: string | undefined;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
export function readServiceCredentials(): ServiceCredentials {
|
|
208
|
+
return {
|
|
209
|
+
clientId: required("PLASGOS_SERVICE_CLIENT_ID"),
|
|
210
|
+
clientSecret: required("PLASGOS_SERVICE_CLIENT_SECRET"),
|
|
211
|
+
audience: optional("PLASGOS_AUDIENCE"),
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** Credentials of the login client (interactive), and the public origin of this app. */
|
|
216
|
+
export interface LoginCredentials {
|
|
217
|
+
clientId: string;
|
|
218
|
+
clientSecret: string;
|
|
219
|
+
/** APP_URL: public origin of this app, for example https://app.example.com. */
|
|
220
|
+
appUrl: string;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
export function readLoginCredentials(): LoginCredentials {
|
|
224
|
+
return {
|
|
225
|
+
clientId: required("PLASGOS_LOGIN_CLIENT_ID"),
|
|
226
|
+
clientSecret: required("PLASGOS_LOGIN_CLIENT_SECRET"),
|
|
227
|
+
appUrl: required("APP_URL").replace(/\/$/, ""),
|
|
228
|
+
};
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** SESSION_SECRET: one secret, or "new,old" while a rotation is in progress. */
|
|
232
|
+
export function readSessionSecrets(): string[] {
|
|
233
|
+
const secrets = required("SESSION_SECRET")
|
|
234
|
+
.split(",")
|
|
235
|
+
.map((secret) => secret.trim())
|
|
236
|
+
.filter((secret) => secret !== "");
|
|
237
|
+
if (secrets.length > 2) throw new Error("Environment variable SESSION_SECRET holds at most two secrets");
|
|
238
|
+
return secrets;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* A webhook secret: one secret, or "new,old" while a rotation is in progress. Names used in the guides:
|
|
243
|
+
* PLASGOS_WEBHOOK_SECRET (the app webhook endpoint: payments and every other app event, one secret)
|
|
244
|
+
* and PLASGOS_SHIPPING_WEBHOOK_SECRET (Plaslink shipping).
|
|
245
|
+
*/
|
|
246
|
+
export function readWebhookSecrets(name: string): string[] {
|
|
247
|
+
const secrets = required(name)
|
|
248
|
+
.split(",")
|
|
249
|
+
.map((secret) => secret.trim())
|
|
250
|
+
.filter((secret) => secret !== "");
|
|
251
|
+
if (secrets.length > 2) throw new Error(`Environment variable ${name} holds at most two secrets`);
|
|
252
|
+
return secrets;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** What an API that verifies Plasgos access tokens reads. */
|
|
256
|
+
export interface TokenVerifierEnv {
|
|
257
|
+
environment: Environment;
|
|
258
|
+
/** PLASGOS_ISSUER: the token's `iss` must equal it. */
|
|
259
|
+
issuer: string;
|
|
260
|
+
/** PLASGOS_TOKEN_AUDIENCE: the audience of this API, given by the Plasgos team; the token's `aud` must equal it. */
|
|
261
|
+
audience: string;
|
|
262
|
+
/** PLASGOS_BACKCHANNEL_URL: optional internal origin for the key set (JWKS), only inside the Plasgos network. */
|
|
263
|
+
backchannelUrl: string | undefined;
|
|
264
|
+
/** PLASGOS_ALLOW_INSECURE_BACKCHANNEL=true: production only, an http: back channel on a private network you trust. */
|
|
265
|
+
allowInsecureBackchannel: boolean;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
export function readTokenVerifierEnv(): TokenVerifierEnv {
|
|
269
|
+
return {
|
|
270
|
+
environment: readEnvironment(),
|
|
271
|
+
issuer: required("PLASGOS_ISSUER"),
|
|
272
|
+
audience: required("PLASGOS_TOKEN_AUDIENCE"),
|
|
273
|
+
backchannelUrl: optional("PLASGOS_BACKCHANNEL_URL"),
|
|
274
|
+
allowInsecureBackchannel: optional("PLASGOS_ALLOW_INSECURE_BACKCHANNEL") === "true",
|
|
275
|
+
};
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** What a backend-for-frontend (BFF) reads besides its login credentials and its session secret. */
|
|
279
|
+
export interface BffEnv {
|
|
280
|
+
environment: Environment;
|
|
281
|
+
/** PLASGOS_ISSUER: where users log in and tokens are issued. */
|
|
282
|
+
issuer: string;
|
|
283
|
+
/** PLASGOS_BACKCHANNEL_URL: optional internal origin of the Plasgos server, only inside the Plasgos network. */
|
|
284
|
+
backchannelUrl: string | undefined;
|
|
285
|
+
/** PLASGOS_RESOURCE: the audience of the app's own API; every token is requested for it. */
|
|
286
|
+
resource: string;
|
|
287
|
+
/** APP_API_URL: origin of the app's own API behind the BFF (not a Plasgos value). */
|
|
288
|
+
apiOrigin: string;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
export function readBffEnv(): BffEnv {
|
|
292
|
+
return {
|
|
293
|
+
environment: readEnvironment(),
|
|
294
|
+
issuer: required("PLASGOS_ISSUER"),
|
|
295
|
+
backchannelUrl: optional("PLASGOS_BACKCHANNEL_URL"),
|
|
296
|
+
resource: required("PLASGOS_RESOURCE"),
|
|
297
|
+
apiOrigin: required("APP_API_URL").replace(/\/$/, ""),
|
|
298
|
+
};
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
<!-- /snippet -->
|
|
302
|
+
|
|
303
|
+
### Sandbox dan production
|
|
304
|
+
|
|
305
|
+
Kode aplikasi sama di semua lingkungan. Yang berbeda hanya nilai env. Setiap lingkungan punya server, kunci, client, dan secret sendiri. Kredensial sandbox tidak berlaku di production, dan sebaliknya.
|
|
306
|
+
|
|
307
|
+
| | `production` | `sandbox` |
|
|
308
|
+
|---|---|---|
|
|
309
|
+
| `PLASGOS_ISSUER` | `https://accounts.plasgos.co.id` | Host accounts sandbox. Tanyakan tim Plasgos |
|
|
310
|
+
| `PLASGOS_API_URL` | `https://api.plasgos.co.id` | `https://api.sandbox.plasgos.co.id` |
|
|
311
|
+
| Audience | Diawali `https://api.plasgos.co.id/` | Sesuai yang diberikan tim Plasgos |
|
|
312
|
+
|
|
313
|
+
`sandbox` mencakup staging dan development lokal.
|
|
314
|
+
|
|
315
|
+
**`environment` adalah pengaman, bukan pemilih URL.** SDK tidak mengubah URL berdasarkan `environment`. SDK hanya mencocokkan `environment` dengan URL yang Anda berikan, dan menolak start bila tidak cocok:
|
|
316
|
+
|
|
317
|
+
| `environment` | Aturan |
|
|
318
|
+
|---|---|
|
|
319
|
+
| `production` | `issuer` harus persis `https://accounts.plasgos.co.id`. Audience (`resource`) harus diawali `https://api.plasgos.co.id/`. `allowInsecureHttp` ditolak. |
|
|
320
|
+
| `sandbox` | `issuer`, `backchannelUrl`, dan `apiUrl` tidak boleh mengarah ke host production (`accounts.plasgos.co.id`, `api.plasgos.co.id`). `allowInsecureHttp: true` boleh, untuk development lokal dengan `http:`. |
|
|
321
|
+
|
|
322
|
+
Nilai selain `"sandbox"` dan `"production"`, atau kosong, ditolak. Tujuannya supaya aplikasi sandbox tidak pernah mengirim secret atau transaksi ke production karena salah env.
|
|
323
|
+
|
|
324
|
+
`backchannelUrl` adalah alamat internal server Plasgos untuk panggilan server-ke-server milik SDK: token, pencabutan token, dan logout ticket. Boleh `http:` karena berada di jaringan internal. Aplikasi di luar jaringan Plasgos tidak mengisinya. Tanpa `backchannelUrl`, panggilan token memakai `issuer`. Pengecualian: verifier access token mengambil kunci publik Plasgos lewat alamat ini, jadi di production `createAccessTokenVerifier` mewajibkan `https:` kecuali `allowInsecureBackchannel: true` ([`verifikasi-token.md` §13](verifikasi-token.md#13-alamat-internal-backchannelurl)).
|
|
325
|
+
|
|
326
|
+
## 6. Mendapat kredensial
|
|
327
|
+
|
|
328
|
+
Tim Plasgos membuat kredensial untuk aplikasi Anda, sekali untuk setiap lingkungan (sandbox dulu, lalu production). Secret hanya tampil satu kali saat dibuat. Tim Plasgos menyerahkannya kepada Anda lewat kanal secret yang disetujui, tidak lewat chat atau tiket.
|
|
329
|
+
|
|
330
|
+
### Client login (client interaktif)
|
|
331
|
+
|
|
332
|
+
Yang Anda kirim ke tim Plasgos:
|
|
333
|
+
|
|
334
|
+
- nama aplikasi dan lingkungannya;
|
|
335
|
+
- redirect URI yang persis, misalnya `https://app.example.com/auth/callback` (tanpa wildcard dan fragment; wajib `https`, kecuali `http://localhost` untuk development);
|
|
336
|
+
- URL setelah logout bila dipakai, misalnya `https://app.example.com/`;
|
|
337
|
+
- scope yang dibutuhkan.
|
|
338
|
+
|
|
339
|
+
Tim Plasgos mendaftarkan client itu, lalu menyerahkan client id dan client secret kepada Anda.
|
|
340
|
+
|
|
341
|
+
Client first-party hanya untuk aplikasi milik Plasgos. Untuk client ini, tim Plasgos juga menyalakan refresh token, audience (`resource`), dan logout ticket.
|
|
342
|
+
|
|
343
|
+
### Client service
|
|
344
|
+
|
|
345
|
+
Client service terikat ke satu app di katalog aplikasi Plasgos. Yang Anda kirim ke tim Plasgos: nama app Anda (atau kode app, bila sudah ada) dan scope yang dibutuhkan.
|
|
346
|
+
|
|
347
|
+
Tim Plasgos menyiapkan app dan client service-nya, lalu menyerahkan client id dan client secret kepada Anda.
|
|
348
|
+
|
|
349
|
+
### Secret webhook
|
|
350
|
+
|
|
351
|
+
Yang Anda kirim ke tim Plasgos: URL webhook aplikasi Anda (`https`), satu untuk setiap lingkungan. Tim Plasgos mendaftarkan URL itu, lalu menyerahkan secret webhook kepada Anda (`PLASGOS_WEBHOOK_SECRET`). Satu endpoint dengan satu secret menerima semua event aplikasi: payments, langganan, paket, dan `user.*` ([`webhook.md` §6](webhook.md#satu-endpoint-untuk-semua-event-aplikasi)). Webhook pengiriman Plaslink memakai endpoint dan secret sendiri. Rotasinya ada di [`webhook.md` §8](webhook.md#8-rotasi-secret).
|
|
352
|
+
|
|
353
|
+
### Yang Anda terima
|
|
354
|
+
|
|
355
|
+
| Lewat kanal secret | Bukan rahasia |
|
|
356
|
+
|---|---|
|
|
357
|
+
| Client id dan client secret (per client) | Issuer (`PLASGOS_ISSUER`) |
|
|
358
|
+
| Secret webhook aplikasi (`whsec_…`, untuk payments dan event aplikasi), bila menerima webhook | Host API (`PLASGOS_API_URL`) |
|
|
359
|
+
| | Audience, bila berbeda dari bawaan |
|
|
360
|
+
|
|
361
|
+
## 7. Bila konfigurasi salah
|
|
362
|
+
|
|
363
|
+
`createOidcClient`, `createServiceClient`, `createSessionStore`, `createWebhookVerifier`, dan `createAccessTokenVerifier` memeriksa semua opsi saat dipanggil. Bila ada yang salah, semuanya melempar satu `ConfigError` yang memuat **semua** masalah sekaligus. Pesannya hanya menyebut nama opsi, tidak pernah nilainya, jadi aman ditulis ke log.
|
|
364
|
+
|
|
365
|
+
Contoh pesan:
|
|
366
|
+
|
|
367
|
+
```text
|
|
368
|
+
Invalid Plasgos auth configuration:
|
|
369
|
+
- environment is "sandbox" but issuer is a production host
|
|
370
|
+
- clientSecret is required
|
|
371
|
+
- scopes must include "openid"
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Buat client saat aplikasi start, bukan saat request pertama, supaya salah konfigurasi ketahuan saat deploy:
|
|
375
|
+
|
|
376
|
+
<!-- snippet: examples/snippets/config-error.ts -->
|
|
377
|
+
```ts
|
|
378
|
+
/**
|
|
379
|
+
* The problems of a ConfigError, or null when `error` is something else. `instanceof ConfigError`
|
|
380
|
+
* works too when the class is imported from `@plasgos/oidc-client`; checking the name also works
|
|
381
|
+
* when the app loads the SDK through both `import` and `require`.
|
|
382
|
+
*/
|
|
383
|
+
export function configProblems(error: unknown): string[] | null {
|
|
384
|
+
if (!(error instanceof Error) || error.name !== "ConfigError") return null;
|
|
385
|
+
const problems: unknown = "problems" in error ? error.problems : undefined;
|
|
386
|
+
if (!Array.isArray(problems)) return [error.message];
|
|
387
|
+
return problems.filter((problem): problem is string => typeof problem === "string");
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/** Runs `create` at start. A configuration mistake stops the process with every problem printed. */
|
|
391
|
+
export function createOrExit<T>(create: () => T): T {
|
|
392
|
+
try {
|
|
393
|
+
return create();
|
|
394
|
+
} catch (error) {
|
|
395
|
+
const problems = configProblems(error);
|
|
396
|
+
if (problems === null) throw error;
|
|
397
|
+
process.stderr.write("Plasgos configuration is invalid:\n");
|
|
398
|
+
for (const problem of problems) process.stderr.write(`- ${problem}\n`);
|
|
399
|
+
process.exit(1);
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
```
|
|
403
|
+
<!-- /snippet -->
|
|
404
|
+
|
|
405
|
+
Pemakaiannya: `const plasgos = createOrExit(createPlasgosClient);` (`createPlasgosClient` ada di [`server-ke-server.md` §2](server-ke-server.md#2-membuat-client)). Untuk webhook: `const verifier = createOrExit(createPaymentsWebhookVerifier);` ([`webhook.md` §4](webhook.md#4-membuat-verifier)). Untuk verifikasi token: `const verifier = createOrExit(() => createApiTokenVerifier(redis));` ([`verifikasi-token.md` §4](verifikasi-token.md#4-membuat-verifier)).
|
|
406
|
+
|
|
407
|
+
`ConfigError` juga diekspor oleh `@plasgos/oidc-client` (dan `/session`, `/service`) dan oleh `@plasgos/auth-verify` (dan `/webhook`, `/express`, `/nestjs`), semuanya kelas yang sama, jadi `error instanceof ConfigError` bekerja bila kelasnya di-import dari sana. Contoh di atas memeriksa `error.name` supaya juga bekerja di aplikasi yang mencampur `import` dan `require` ([`error.md` §3](error.md#3-instanceof-dan-dua-loader)).
|
|
408
|
+
|
|
409
|
+
Daftar lengkap pesan `ConfigError` dan cara memperbaikinya ada di [`error.md`](error.md).
|
|
410
|
+
|
|
411
|
+
## 8. Langkah berikutnya
|
|
412
|
+
|
|
413
|
+
- Login user di aplikasi web: [`login-web.md`](login-web.md)
|
|
414
|
+
- BFF Node/Express untuk SPA atau PWA (lock Redis, proxy, pencabutan sesi): [`bff-express.md`](bff-express.md)
|
|
415
|
+
- Memanggil API Plasgos dari server: [`server-ke-server.md`](server-ke-server.md)
|
|
416
|
+
- Menerima webhook dari Plasgos: [`webhook.md`](webhook.md)
|
|
417
|
+
- Memeriksa access token Plasgos di API sendiri: [`verifikasi-token.md`](verifikasi-token.md)
|
|
418
|
+
- Arti setiap kegagalan: [`error.md`](error.md)
|
|
419
|
+
- Contoh lengkap: [`contoh-hitungcuan.md`](contoh-hitungcuan.md), [`contoh-plaslink.md`](contoh-plaslink.md)
|