@plasgos/auth-verify 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 +13 -0
- package/LICENSE +15 -0
- package/README.md +86 -2
- package/dist/webhook.cjs +294 -0
- package/dist/webhook.cjs.map +1 -0
- package/dist/webhook.d.cts +190 -0
- package/dist/webhook.d.ts +190 -0
- package/dist/webhook.js +263 -0
- package/dist/webhook.js.map +1 -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 +45 -3
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Contoh: Plaslink (login seller, payments, webhook)
|
|
2
|
+
|
|
3
|
+
Plaslink memakai tiga hal dari Plasgos. Masing-masing punya kredensial sendiri dan bagian SDK sendiri:
|
|
4
|
+
|
|
5
|
+
| Kebutuhan | Kredensial | Bagian SDK | Status |
|
|
6
|
+
|---|---|---|---|
|
|
7
|
+
| Seller menghubungkan akun Plasgos ("Hubungkan Plasgos") | Client login (interaktif, pihak ketiga) | `createOidcClient` dari `@plasgos/oidc-client` | Panduan ini |
|
|
8
|
+
| Membuat payment | Client service app `plaslink` | `createServiceClient` dari `@plasgos/oidc-client/service` | Panduan ini |
|
|
9
|
+
| Menerima webhook payments dan pengiriman | Dua secret webhook | `createWebhookVerifier` dari `@plasgos/auth-verify/webhook` | Panduan ini |
|
|
10
|
+
|
|
11
|
+
Client login dan client service **bukan** client yang sama. Client id dan secret-nya berbeda, dan scope-nya tidak boleh tertukar ([`memulai.md` §3](memulai.md#3-dua-jenis-client)).
|
|
12
|
+
|
|
13
|
+
## 1. Env
|
|
14
|
+
|
|
15
|
+
```dotenv
|
|
16
|
+
PLASGOS_ENV=sandbox
|
|
17
|
+
PLASGOS_ISSUER=https://<host accounts sandbox>
|
|
18
|
+
PLASGOS_API_URL=https://api.sandbox.plasgos.co.id
|
|
19
|
+
APP_URL=https://<host plaslink>
|
|
20
|
+
|
|
21
|
+
# Client login (seller connect)
|
|
22
|
+
PLASGOS_LOGIN_CLIENT_ID=<client id login>
|
|
23
|
+
PLASGOS_LOGIN_CLIENT_SECRET=<client secret login>
|
|
24
|
+
|
|
25
|
+
# Client service (payments)
|
|
26
|
+
PLASGOS_SERVICE_CLIENT_ID=<client id service>
|
|
27
|
+
PLASGOS_SERVICE_CLIENT_SECRET=<client secret service>
|
|
28
|
+
|
|
29
|
+
# Cookie transaksi login
|
|
30
|
+
SESSION_SECRET=<acak, minimal 32 byte>
|
|
31
|
+
|
|
32
|
+
# Webhook: secret payments dan secret pengiriman berbeda
|
|
33
|
+
PLASGOS_WEBHOOK_SECRET=<secret webhook payments>
|
|
34
|
+
PLASGOS_SHIPPING_WEBHOOK_SECRET=<secret webhook pengiriman>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Di production: `PLASGOS_ENV=production`, `PLASGOS_ISSUER=https://accounts.plasgos.co.id`, `PLASGOS_API_URL=https://api.plasgos.co.id`, dan kredensial production.
|
|
38
|
+
|
|
39
|
+
Redirect URI yang didaftarkan di Plasgos harus persis `<APP_URL>/auth/callback` (atau path lain yang Anda pilih, asalkan sama persis dengan `redirectUri`).
|
|
40
|
+
|
|
41
|
+
## 2. Seller menghubungkan akun
|
|
42
|
+
|
|
43
|
+
### Client login pihak ketiga
|
|
44
|
+
|
|
45
|
+
<!-- snippet: examples/snippets/login-client.ts#third-party -->
|
|
46
|
+
```ts
|
|
47
|
+
/** An app outside Plasgos: identity only. No resource, no logout ticket. */
|
|
48
|
+
export function createThirdPartyClient(): OidcClient {
|
|
49
|
+
const env = readPlasgosEnv();
|
|
50
|
+
const credentials = readLoginCredentials();
|
|
51
|
+
return createOidcClient({
|
|
52
|
+
environment: env.environment,
|
|
53
|
+
issuer: env.issuer,
|
|
54
|
+
clientId: credentials.clientId,
|
|
55
|
+
clientSecret: credentials.clientSecret,
|
|
56
|
+
redirectUri: `${credentials.appUrl}/auth/callback`,
|
|
57
|
+
postLogoutRedirectUri: `${credentials.appUrl}/`,
|
|
58
|
+
scopes: ["openid", "profile", "email", "plaslink:shipping"],
|
|
59
|
+
profile: "third-party",
|
|
60
|
+
onFailure: logFailure,
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
<!-- /snippet -->
|
|
65
|
+
|
|
66
|
+
Yang berbeda dari aplikasi Plasgos sendiri (`profile: "first-party"`):
|
|
67
|
+
|
|
68
|
+
| Hal | Client pihak ketiga |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `resource` | Tidak boleh diisi. `ConfigError` bila diisi |
|
|
71
|
+
| Scope | `openid`, `profile`, `email`, `plaslink:shipping`. Scope first-party (`account:*`, `packages:*`, `plasgos:public_id`) ditolak saat start |
|
|
72
|
+
| Persetujuan | Seller selalu melihat halaman persetujuan Plasgos |
|
|
73
|
+
| Refresh token | Tidak ada, karena client tidak punya `offline_access` |
|
|
74
|
+
| Logout ticket | Tidak ada (`logoutTicket` tidak boleh `true`) |
|
|
75
|
+
| `backchannelUrl` | Tidak diisi. Plaslink berada di luar jaringan Plasgos |
|
|
76
|
+
|
|
77
|
+
`plaslink:shipping` adalah persetujuan seller agar Plaslink membuat pengiriman atas namanya.
|
|
78
|
+
|
|
79
|
+
### Alurnya
|
|
80
|
+
|
|
81
|
+
Menghubungkan akun selalu berupa redirect satu halaman penuh ke Plasgos, lalu kembali ke Plaslink. Tidak ada popup atau iframe.
|
|
82
|
+
|
|
83
|
+
1. Seller menekan "Hubungkan Plasgos". Plaslink memanggil `startLogin` dan menyimpan transaksi di cookie.
|
|
84
|
+
2. Seller login dan menyetujui di Plasgos.
|
|
85
|
+
3. Plasgos mengembalikan browser ke `/auth/callback`. Plaslink memanggil `handleCallback` dan mendapat identitas seller.
|
|
86
|
+
|
|
87
|
+
<!-- snippet: examples/snippets/plaslink-connect.ts#start -->
|
|
88
|
+
```ts
|
|
89
|
+
/** GET /plasgos/connect: sends the seller to Plasgos to approve the connection. */
|
|
90
|
+
export function startConnect(client: OidcClient, store: SessionStore<AppSession>): Response {
|
|
91
|
+
const { location, transaction } = client.startLogin({ returnTo: "/settings/plasgos" });
|
|
92
|
+
return new Response(null, {
|
|
93
|
+
status: 302,
|
|
94
|
+
headers: {
|
|
95
|
+
Location: location,
|
|
96
|
+
"Set-Cookie": store.commitTransaction(transaction),
|
|
97
|
+
"Cache-Control": "no-store",
|
|
98
|
+
},
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
<!-- /snippet -->
|
|
103
|
+
|
|
104
|
+
<!-- snippet: examples/snippets/plaslink-connect.ts#callback -->
|
|
105
|
+
```ts
|
|
106
|
+
/** The Plasgos account a seller connected. `subject` is stable for this client and differs per client. */
|
|
107
|
+
export interface ConnectedSeller {
|
|
108
|
+
subject: string;
|
|
109
|
+
name: string | null;
|
|
110
|
+
email: string | null;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* GET /auth/callback: returns the connected seller, or null when the connection failed.
|
|
115
|
+
* Append `setCookie` to the response either way: it clears the single-use transaction cookie.
|
|
116
|
+
*/
|
|
117
|
+
export async function finishConnect(
|
|
118
|
+
client: OidcClient,
|
|
119
|
+
store: SessionStore<AppSession>,
|
|
120
|
+
request: Request,
|
|
121
|
+
): Promise<{ seller: ConnectedSeller | null; setCookie: string }> {
|
|
122
|
+
const setCookie = store.clearTransaction();
|
|
123
|
+
try {
|
|
124
|
+
const { claims } = await client.handleCallback(request.url, store.readTransaction(request));
|
|
125
|
+
return { seller: { subject: claims.sub, name: claims.name ?? null, email: claims.email ?? null }, setCookie };
|
|
126
|
+
} catch (error) {
|
|
127
|
+
if (!(error instanceof OidcError)) throw error;
|
|
128
|
+
return { seller: null, setCookie };
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
<!-- /snippet -->
|
|
133
|
+
|
|
134
|
+
`store` adalah session store dari `@plasgos/oidc-client/session`. Di sini ia hanya dipakai untuk cookie transaksi (berumur 10 menit). Cara membuatnya ada di [`login-web.md`](login-web.md). File lengkap contoh ini: [`plaslink-connect.ts`](examples/plaslink-connect.ts).
|
|
135
|
+
|
|
136
|
+
### Yang disimpan Plaslink
|
|
137
|
+
|
|
138
|
+
Simpan `seller.subject` di data seller Plaslink. Itulah identitas akun Plasgos yang terhubung.
|
|
139
|
+
|
|
140
|
+
- `subject` adalah `sub` pairwise: tetap sama untuk seller itu di client Plaslink, dan berbeda dari `sub` seller yang sama di aplikasi lain. Bila seller memutus lalu menghubungkan lagi, `sub`-nya tetap sama.
|
|
141
|
+
- Plaslink tidak perlu menyimpan access token Plasgos. Sesi login Plaslink tetap milik Plaslink.
|
|
142
|
+
- Token Plasgos tidak membawa role atau tim. Hak akses di Plaslink diatur Plaslink.
|
|
143
|
+
|
|
144
|
+
Untuk memanggil API pengiriman (`/v5/plaslink/*`), Plaslink mengirim `sub` itu di header `X-Plasgos-Subject`, dengan Basic auth memakai kredensial client login. Panggilan itu di luar cakupan SDK ini. Kontraknya ada di dokumentasi API Plaslink shipping milik Plasgos.
|
|
145
|
+
|
|
146
|
+
Bila `finishConnect` mengembalikan `seller: null`, tampilkan pesan gagal dan tawarkan untuk mencoba lagi. Penyebabnya tercatat lewat `onFailure`. Arti setiap `reason` ada di [`error.md`](error.md).
|
|
147
|
+
|
|
148
|
+
## 3. Payments
|
|
149
|
+
|
|
150
|
+
Payments memakai client service app `plaslink`, sama persis dengan [`server-ke-server.md`](server-ke-server.md):
|
|
151
|
+
|
|
152
|
+
<!-- snippet: examples/snippets/service-client.ts#create -->
|
|
153
|
+
```ts
|
|
154
|
+
/** Create it once at start and reuse it: the token cache lives in the client. */
|
|
155
|
+
export function createPlasgosClient(): ServiceClient {
|
|
156
|
+
const env = readPlasgosEnv();
|
|
157
|
+
const credentials = readServiceCredentials();
|
|
158
|
+
return createServiceClient({
|
|
159
|
+
environment: env.environment,
|
|
160
|
+
issuer: env.issuer,
|
|
161
|
+
apiUrl: env.apiUrl,
|
|
162
|
+
backchannelUrl: env.backchannelUrl,
|
|
163
|
+
clientId: credentials.clientId,
|
|
164
|
+
clientSecret: credentials.clientSecret,
|
|
165
|
+
scopes: ["platform:self.read", "payments:read", "payments:write"],
|
|
166
|
+
resource: credentials.audience,
|
|
167
|
+
onFailure: logFailure,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
<!-- /snippet -->
|
|
172
|
+
|
|
173
|
+
Sesuaikan `scopes` dengan yang dimiliki client service Plaslink. Tambahkan `payments:refund` bila Plaslink melakukan refund lewat API.
|
|
174
|
+
|
|
175
|
+
Membuat payment, cek koneksi, refund, dan penanganan kegagalan: lihat [`server-ke-server.md` §4–§7](server-ke-server.md#4-fetch-memanggil-api).
|
|
176
|
+
|
|
177
|
+
## 4. Webhook
|
|
178
|
+
|
|
179
|
+
Plaslink menerima dua jenis webhook: event payments dan event pengiriman. Masing-masing punya header dan secret sendiri, jadi Plaslink memakai dua verifier. Aturan lengkapnya ada di [`webhook.md`](webhook.md).
|
|
180
|
+
|
|
181
|
+
Install `@plasgos/auth-verify` di samping `@plasgos/oidc-client`, dengan nomor versi persis yang sama (`pnpm add @plasgos/auth-verify@<versi> --save-exact`). Salin `webhook-verifier.ts` dari [folder contoh](examples/).
|
|
182
|
+
|
|
183
|
+
| Jenis | Preset | Secret (env) | Header tanda tangan |
|
|
184
|
+
|---|---|---|---|
|
|
185
|
+
| Payments | `presets.payments` | `PLASGOS_WEBHOOK_SECRET` | `X-Signature` |
|
|
186
|
+
| Pengiriman | `presets.plaslinkShipping` | `PLASGOS_SHIPPING_WEBHOOK_SECRET` | `X-Plasgos-Signature` |
|
|
187
|
+
|
|
188
|
+
### Dua verifier
|
|
189
|
+
|
|
190
|
+
Buat keduanya saat start:
|
|
191
|
+
|
|
192
|
+
<!-- snippet: examples/snippets/webhook-verifier.ts#create -->
|
|
193
|
+
```ts
|
|
194
|
+
/** Payments webhooks. Create it once at start: a wrong option throws one ConfigError there. */
|
|
195
|
+
export function createPaymentsWebhookVerifier(): WebhookVerifier {
|
|
196
|
+
return createWebhookVerifier({
|
|
197
|
+
environment: readEnvironment(),
|
|
198
|
+
secrets: readWebhookSecrets("PLASGOS_WEBHOOK_SECRET"),
|
|
199
|
+
preset: presets.payments,
|
|
200
|
+
});
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
<!-- /snippet -->
|
|
204
|
+
|
|
205
|
+
<!-- snippet: examples/snippets/webhook-verifier.ts#create-shipping -->
|
|
206
|
+
```ts
|
|
207
|
+
/** Plaslink shipping webhooks: other header names and a secret of their own. */
|
|
208
|
+
export function createShippingWebhookVerifier(): WebhookVerifier {
|
|
209
|
+
return createWebhookVerifier({
|
|
210
|
+
environment: readEnvironment(),
|
|
211
|
+
secrets: readWebhookSecrets("PLASGOS_SHIPPING_WEBHOOK_SECRET"),
|
|
212
|
+
preset: presets.plaslinkShipping,
|
|
213
|
+
});
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
<!-- /snippet -->
|
|
217
|
+
|
|
218
|
+
Di file start aplikasi: `const paymentsVerifier = createOrExit(createPaymentsWebhookVerifier);` dan `const shippingVerifier = createOrExit(createShippingWebhookVerifier);`.
|
|
219
|
+
|
|
220
|
+
### Route
|
|
221
|
+
|
|
222
|
+
Paling sederhana: dua route, satu per jenis, misalnya `/webhooks/plasgos/payments` dengan `paymentsVerifier` dan `/webhooks/plasgos/shipping` dengan `shippingVerifier`. Setiap route menerima body mentah dan memanggil `handleWebhook` ([`webhook.md` §5](webhook.md#5-body-mentah-per-framework) dan [§6](webhook.md#6-menangani-kiriman)).
|
|
223
|
+
|
|
224
|
+
Bila hanya ada satu URL, pilih verifier dari keluarga header: kiriman pengiriman membawa `X-Plasgos-Signature`, kiriman payments membawa `X-Signature`. Verifier yang salah menolak kiriman dengan `missing_header`.
|
|
225
|
+
|
|
226
|
+
### Dedup
|
|
227
|
+
|
|
228
|
+
`saveOnce(tx, event)` berjalan di transaksi database yang sama dengan efek event. Jawab `2xx` hanya setelah commit. Bila apa pun gagal, rollback dan jawab `5xx`, jadi Plasgos mengirim ulang dan event diproses saat itu ([`webhook.md` §7](webhook.md#7-dedup-di-transaksi-yang-sama)).
|
|
229
|
+
|
|
230
|
+
**Event pengiriman yang tampil degraded.** Plaslink juga membaca event pengiriman lewat endpoint fakta (`GET /v5/plaslink/shipping/shipments/{plaslink_order_id}/events`). Di sana sebuah event bisa tampil degraded (`data: null`, `render_error: true`), dan Plaslink menandainya dilewati. Bila webhook untuk id event yang sama datang belakangan, event itu **bukan** duplikat: proses seperti biasa. Karena itu:
|
|
231
|
+
|
|
232
|
+
- pakai tabel dedup webhook yang terpisah dari catatan endpoint fakta, atau
|
|
233
|
+
- anggap baris yang degraded sebagai belum tersimpan, sehingga `saveOnce` mengembalikan `true` untuk webhook-nya.
|
|
234
|
+
|
|
235
|
+
Event payments dan event pengiriman memakai id yang berbeda. Satu tabel dedup untuk keduanya boleh, asalkan aturan degraded di atas tetap berlaku.
|
|
236
|
+
|
|
237
|
+
### Rotasi secret
|
|
238
|
+
|
|
239
|
+
- **Payments:** saat tim Plasgos menyerahkan secret baru, segera pasang `PLASGOS_WEBHOOK_SECRET=baru,lama` dan deploy. Secret lama otomatis berhenti dipakai Plasgos 24 jam setelah rotasi, jadi Plaslink harus sudah memakai secret baru sebelum itu.
|
|
240
|
+
- **Pengiriman:** pasang `PLASGOS_SHIPPING_WEBHOOK_SECRET=baru,lama`, deploy, lalu konfirmasi ke tim Plasgos. Tim Plasgos baru menghentikan secret lama setelah konfirmasi Plaslink.
|
|
241
|
+
|
|
242
|
+
Setelah secret lama berhenti, hapus dari env. Rinciannya ada di [`webhook.md` §8](webhook.md#8-rotasi-secret).
|
|
243
|
+
|
|
244
|
+
Bila kiriman ditolak, arti setiap `reason` ada di [`error.md` §7](error.md#7-webhookverifyerror). Secret yang salah membuat setiap kiriman dijawab `401` dan menahan event berikutnya untuk payment atau pengiriman yang sama. Setelah secret diperbaiki, minta tim Plasgos mengirim ulang.
|