@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,625 @@
1
+ # Webhook
2
+
3
+ Panduan ini untuk server yang menerima webhook dari Plasgos. `@plasgos/auth-verify/webhook` memeriksa bahwa sebuah kiriman benar dari Plasgos, tidak diubah di jalan, dan tidak terlalu lama. Setelah itu aplikasi Anda memproses event-nya.
4
+
5
+ Sebelum mulai, baca [`memulai.md`](memulai.md) untuk env dan cara mendapat secret webhook.
6
+
7
+ ## 1. Apa itu webhook Plasgos
8
+
9
+ Plasgos memberi tahu aplikasi Anda tentang sebuah kejadian dengan `POST` JSON ke URL webhook yang Anda daftarkan. Ada dua jenis:
10
+
11
+ | Jenis | Untuk | Contoh `type` | Preset |
12
+ |---|---|---|---|
13
+ | Payments | Aplikasi yang membuat payment lewat Plasgos | `payment.paid`, `payment.expired` | `presets.payments` |
14
+ | Pengiriman Plaslink | Plaslink, untuk pengiriman seller | event pengiriman | `presets.plaslinkShipping` |
15
+
16
+ Setiap jenis punya secret sendiri. Aplikasi yang menerima keduanya (Plaslink) memakai dua secret dan dua verifier.
17
+
18
+ Hal yang selalu berlaku:
19
+
20
+ - **Paling sedikit sekali.** Event yang sama bisa datang lebih dari sekali. Simpan `id` event dan jangan proses dua kali ([§7](#7-dedup-di-transaksi-yang-sama)).
21
+ - **Berurutan per payment atau per pengiriman.** Event berikutnya untuk payment (atau pengiriman) yang sama baru dikirim setelah event sebelumnya diterima, atau dilewati oleh tim Plasgos. `sequence` naik untuk setiap event milik payment atau pengiriman itu. Bila sebuah event dilewati, `sequence` melompat. Baca keadaan terbarunya dengan `GET /v5/service/payments/{pay_id}` (payments) atau `GET /v5/plaslink/shipping/shipments/{plaslink_order_id}/events` (pengiriman Plaslink).
22
+ - **Body adalah sebuah objek JSON** dengan `id` dan `type`, sama dengan header kiriman.
23
+
24
+ Body event payments:
25
+
26
+ ```json
27
+ {
28
+ "id": "whd_…",
29
+ "type": "payment.paid",
30
+ "sequence": 3,
31
+ "occurred_at": "2026-11-15T03:00:00.000Z",
32
+ "subject": { "type": "payment", "id": "pay_…", "external_ref": "INV-0001" },
33
+ "data": {}
34
+ }
35
+ ```
36
+
37
+ Body event pengiriman Plaslink memakai `shipment` (`id`, `plaslink_order_id`, `package_id`) di tempat `subject`. Isi `data` berbeda untuk setiap `type`. Rinciannya ada di dokumentasi API payments dan API Plaslink shipping milik Plasgos. Bila belum punya dokumentasi itu, mintalah ke tim Plasgos.
38
+
39
+ ## 2. Aturan pengiriman
40
+
41
+ Plasgos menganggap sebuah kiriman berhasil hanya bila aplikasi Anda menjawab `2xx`.
42
+
43
+ - Setiap jawaban selain `2xx` dihitung sebagai percobaan gagal, termasuk `400`, `401`, dan redirect. Redirect tidak diikuti.
44
+ - Percobaan yang gagal diulang dengan jeda yang makin panjang: setelah percobaan ke-n, jedanya min(10 detik × 2^(n−1), 1 jam). Bawaannya, webhook payments dicoba paling banyak 15 kali (sekitar 6,4 jam sejak percobaan pertama), dan webhook pengiriman Plaslink 20 kali (sekitar 11,4 jam).
45
+ - Jawab dalam sekitar 10 detik. Jawaban yang lebih lama dihitung gagal.
46
+ - Setelah batas percobaan habis, event itu berhenti dikirim. Event berikutnya untuk payment atau pengiriman yang sama ikut tertahan sampai tim Plasgos mengirim ulang atau melewatinya.
47
+
48
+ Akibatnya:
49
+
50
+ - Simpan event, jawab `2xx`, lalu kerjakan proses yang berat belakangan.
51
+ - Secret yang salah membuat setiap percobaan gagal (`401`) dan memblokir antrean payment atau pengiriman itu. Setelah secret diperbaiki, minta tim Plasgos mengirim ulang.
52
+
53
+ ## 3. Header dan tanda tangan
54
+
55
+ Setiap kiriman membawa empat header. Nama header-nya berbeda per jenis:
56
+
57
+ | Isi | `presets.payments` | `presets.plaslinkShipping` |
58
+ |---|---|---|
59
+ | Id event | `X-Event-Id` | `X-Plasgos-Event-Id` |
60
+ | Type event | `X-Event-Type` | `X-Plasgos-Event-Type` |
61
+ | Waktu kirim (detik epoch) | `X-Timestamp` | `X-Plasgos-Timestamp` |
62
+ | Tanda tangan | `X-Signature` | `X-Plasgos-Signature` |
63
+
64
+ Format tanda tangan:
65
+
66
+ ```text
67
+ X-Signature: v1=<hex>
68
+ <hex> = HMAC-SHA256(secret, "<timestamp>.<body mentah>"), huruf kecil
69
+ ```
70
+
71
+ - `<timestamp>` adalah nilai header waktu kirim. `<body mentah>` adalah byte body persis seperti yang diterima.
72
+ - Saat rotasi secret, header bisa memuat beberapa nilai: `v1=<hex baru>,v1=<hex lama>`. Kiriman diterima bila salah satunya cocok dengan salah satu secret Anda.
73
+ - Skema selain `v1=` (misalnya `v2=`) diabaikan, supaya versi tanda tangan berikutnya tidak memutus aplikasi Anda.
74
+ - Waktu kirim yang berbeda lebih dari `toleranceSeconds` (bawaan 300 detik) dari jam server Anda ditolak, ke dua arah. Pastikan jam server sinkron (NTP).
75
+
76
+ **Id dan type diambil dari body.** Tanda tangan hanya mencakup waktu kirim dan body. Header id dan type tidak ikut ditandatangani, jadi bisa diganti di jalan. Karena itu SDK mengambil `id` dan `type` dari body yang sudah lolos tanda tangan, dan menolak kiriman bila keduanya berbeda dari header (`header_mismatch`). Dedup selalu memakai `event.id` dari hasil verifikasi, bukan header.
77
+
78
+ ## 4. Membuat verifier
79
+
80
+ Buat verifier sekali saat aplikasi start. Opsinya diperiksa saat itu juga. Bila ada yang salah, `createWebhookVerifier` melempar satu `ConfigError` berisi semua masalah, sebelum ada kiriman pertama.
81
+
82
+ <!-- snippet: examples/snippets/webhook-verifier.ts#create -->
83
+ ```ts
84
+ /** Payments webhooks. Create it once at start: a wrong option throws one ConfigError there. */
85
+ export function createPaymentsWebhookVerifier(): WebhookVerifier {
86
+ return createWebhookVerifier({
87
+ environment: readEnvironment(),
88
+ secrets: readWebhookSecrets("PLASGOS_WEBHOOK_SECRET"),
89
+ preset: presets.payments,
90
+ });
91
+ }
92
+ ```
93
+ <!-- /snippet -->
94
+
95
+ Untuk pengiriman Plaslink, buat verifier kedua dengan preset dan secret-nya sendiri:
96
+
97
+ <!-- snippet: examples/snippets/webhook-verifier.ts#create-shipping -->
98
+ ```ts
99
+ /** Plaslink shipping webhooks: other header names and a secret of their own. */
100
+ export function createShippingWebhookVerifier(): WebhookVerifier {
101
+ return createWebhookVerifier({
102
+ environment: readEnvironment(),
103
+ secrets: readWebhookSecrets("PLASGOS_SHIPPING_WEBHOOK_SECRET"),
104
+ preset: presets.plaslinkShipping,
105
+ });
106
+ }
107
+ ```
108
+ <!-- /snippet -->
109
+
110
+ `readEnvironment` dan `readWebhookSecrets` ada di `env.ts` ([`memulai.md` §5](memulai.md#5-env-yang-disarankan)). `readWebhookSecrets` membaca satu secret, atau `baru,lama` saat rotasi:
111
+
112
+ <!-- snippet: examples/snippets/env.ts#webhook-secrets -->
113
+ ```ts
114
+ /**
115
+ * A webhook secret: one secret, or "new,old" while a rotation is in progress. Names used in the guides:
116
+ * PLASGOS_WEBHOOK_SECRET (payments) and PLASGOS_SHIPPING_WEBHOOK_SECRET (Plaslink shipping).
117
+ */
118
+ export function readWebhookSecrets(name: string): string[] {
119
+ const secrets = required(name)
120
+ .split(",")
121
+ .map((secret) => secret.trim())
122
+ .filter((secret) => secret !== "");
123
+ if (secrets.length > 2) throw new Error(`Environment variable ${name} holds at most two secrets`);
124
+ return secrets;
125
+ }
126
+ ```
127
+ <!-- /snippet -->
128
+
129
+ Bentuk `baru,lama` hanya untuk secret yang tidak memuat koma dan tidak diawali atau diakhiri spasi, karena `readWebhookSecrets` memisah di koma dan membuang spasi di tepi setiap nilai. Untuk secret lain, atau bila Anda lebih suka dua env terpisah (misalnya `PLASGOS_WEBHOOK_SECRET` dan `PLASGOS_WEBHOOK_SECRET_PREVIOUS`), berikan keduanya apa adanya: `secrets: [process.env.PLASGOS_WEBHOOK_SECRET, process.env.PLASGOS_WEBHOOK_SECRET_PREVIOUS]`. Nilai yang tidak diisi atau kosong dibuang.
130
+
131
+ Bila opsinya salah, aplikasi berhenti saat start. Pola `createOrExit` di [`memulai.md` §7](memulai.md#7-bila-konfigurasi-salah) juga berlaku di sini: `const verifier = createOrExit(createPaymentsWebhookVerifier);`.
132
+
133
+ Potongan kode di panduan ini berasal dari file yang lolos typecheck, lengkap dengan import-nya: [`webhook-verifier.ts`](examples/webhook-verifier.ts), [`webhook-express.ts`](examples/webhook-express.ts), [`webhook-nestjs.ts`](examples/webhook-nestjs.ts), [`webhook-fetch.ts`](examples/webhook-fetch.ts), dan [`webhook-testing.ts`](examples/webhook-testing.ts). Semua import SDK berasal dari `@plasgos/auth-verify/webhook`.
134
+
135
+ ### Opsi `createWebhookVerifier`
136
+
137
+ | Opsi | Wajib | Bawaan | Arti |
138
+ |---|---|---|---|
139
+ | `environment` | Ya | — | `"sandbox"` atau `"production"`. Ikut tercatat di setiap hasil. `"production"` menolak `toleranceSeconds` di atas 300 |
140
+ | `secrets` | Ya | — | Satu atau dua secret webhook, masing-masing minimal 32 byte. `undefined` dan nilai kosong dibuang lebih dulu, nilai yang sama dipakai sekali. Saat rotasi: `[baru, lama]`, urutannya bebas ([§8](#8-rotasi-secret)) |
141
+ | `preset` | Ya | — | `presets.payments`, `presets.plaslinkShipping`, atau preset sendiri dengan bentuk yang sama |
142
+ | `toleranceSeconds` | Tidak | `300` | Selisih terbesar antara waktu kirim dan jam server, dalam detik. Bilangan bulat 1–900, paling besar 300 di production |
143
+ | `maxBodyBytes` | Tidak | `1048576` | Body mentah terbesar yang diterima, dalam byte. Bilangan bulat 1024–16777216 |
144
+
145
+ Preset sendiri hanya untuk penerima di belakang proxy yang mengganti nama header: `{ name, headers: { id, type, timestamp, signature } }`. `name` berisi huruf, angka, `_`, atau `-` (1–64 karakter). Keempat nama header harus nama header HTTP yang sah (paling panjang 64 karakter) dan berbeda satu sama lain (tanpa membedakan huruf besar dan kecil).
146
+
147
+ ### `createWebhookVerifier` atau `verifyWebhook`
148
+
149
+ | | `createWebhookVerifier` | `verifyWebhook` |
150
+ |---|---|---|
151
+ | Bentuk | `createWebhookVerifier(opsi)` sekali, lalu `verifier.verify({ headers, rawBody })` per kiriman | `verifyWebhook({ ...opsi, headers, rawBody })` per kiriman |
152
+ | Opsi diperiksa | Sekali, saat start | Di setiap panggilan |
153
+ | Salah konfigurasi ketahuan | Saat deploy | Saat kiriman pertama datang, yang lalu dijawab `5xx` |
154
+
155
+ Pakai `createWebhookVerifier`. `verifyWebhook` hanya untuk skrip atau test sekali jalan.
156
+
157
+ ### Input `verify`
158
+
159
+ | Field | Isi |
160
+ |---|---|
161
+ | `headers` | Header request: `Headers` dari Web `Request`, atau objek biasa seperti `req.headers` di Node. Nama header dicari tanpa membedakan huruf besar dan kecil |
162
+ | `rawBody` | Body mentah sebagai `string` atau `Uint8Array` (`Buffer` juga boleh), **sebelum** di-parse sebagai JSON |
163
+ | `now` | Tidak wajib. Waktu sekarang dalam milidetik epoch, untuk test. Bawaan `Date.now()` |
164
+
165
+ ## 5. Body mentah per framework
166
+
167
+ Tanda tangan dihitung atas byte body yang persis. Body yang sudah di-parse lalu diubah kembali menjadi JSON (`JSON.stringify(req.body)`) hampir selalu berbeda byte-nya, jadi tanda tangannya tidak cocok. Berikan body mentah ke `verify`, lalu pakai `event.body`, yaitu JSON yang sudah di-parse dan lolos verifikasi.
168
+
169
+ Memori dilindungi oleh batas body di framework Anda, bukan oleh `maxBodyBytes`. `maxBodyBytes` hanya menolak body yang sudah terbaca. Batas framework menolak body yang terlalu besar sebelum seluruhnya masuk memori:
170
+
171
+ | Framework | Batas body |
172
+ |---|---|
173
+ | Express | `express.raw({ limit: "1mb" })` di route webhook |
174
+ | NestJS | Batas body parser NestJS (untuk Express, bawaannya 100 KB) |
175
+ | React Router dan server berbasis `Request` | `readRawBody` di bawah: `413` di atas 1 MiB, dengan hitungan byte yang berjalan |
176
+
177
+ ### Express
178
+
179
+ Pasang `express.raw` hanya di route webhook, sebelum `express.json()` global. `req.body` lalu berupa `Buffer`, dan `req.headers` diberikan apa adanya.
180
+
181
+ <!-- snippet: examples/snippets/webhook-express.ts#route -->
182
+ ```ts
183
+ /**
184
+ * Errors of the webhook route as JSON without a stack trace: 413 for a body over the `limit` of
185
+ * express.raw, 500 for anything else.
186
+ */
187
+ function webhookErrors(error: unknown, _req: Request, res: Response, next: NextFunction): void {
188
+ if (res.headersSent) {
189
+ next(error);
190
+ return;
191
+ }
192
+ const tooLarge = typeof error === "object" && error !== null && "type" in error && error.type === "entity.too.large";
193
+ if (tooLarge) res.status(413).json({ error: "payload_too_large" });
194
+ else res.status(500).json({ error: "processing_failed" });
195
+ }
196
+
197
+ export function createApp(verifier: WebhookVerifier, withTransaction: WithTransaction, apply: ApplyEvent): Express {
198
+ const app = express();
199
+
200
+ // The raw body on this route only, registered before the global express.json() below.
201
+ // `limit` protects memory: a larger body is answered 413 before it is held in full.
202
+ const rawJson = express.raw({ type: "application/json", limit: "1mb" });
203
+ app.post("/webhooks/plasgos", rawJson, (req, res, next) => {
204
+ const rawBody: unknown = req.body;
205
+ if (!Buffer.isBuffer(rawBody)) {
206
+ res.status(415).json({ error: "unsupported_media_type" });
207
+ return;
208
+ }
209
+ handleWebhook(verifier, withTransaction, apply, { headers: req.headers, rawBody })
210
+ .then((answer) => res.status(answer.status).json(answer.body))
211
+ .catch(next);
212
+ });
213
+ // Registered after the route and before express.json(): errors of the webhook route end here.
214
+ app.use("/webhooks/plasgos", webhookErrors);
215
+
216
+ app.use(express.json());
217
+ // ... the other routes of the app
218
+ return app;
219
+ }
220
+ ```
221
+ <!-- /snippet -->
222
+
223
+ Body di atas `limit` dijawab `413` oleh `express.raw` sebelum sampai ke handler. Handler error bawaan Express menulis stack trace ke log dan, bila `NODE_ENV` bukan `production`, juga ke jawaban. Karena itu contoh ini memasang error handler sendiri di route webhook: `413` untuk body yang terlalu besar, `500` untuk error lain, keduanya berupa JSON tanpa stack trace.
224
+
225
+ `handleWebhook` ada di [§6](#6-menangani-kiriman).
226
+
227
+ ### NestJS
228
+
229
+ Nyalakan `rawBody: true` saat membuat aplikasi. NestJS lalu menyimpan byte mentah di `req.rawBody`, di samping body yang sudah di-parse. Contoh ini memakai `@nestjs/platform-express`; type `Request`/`Response` berasal dari `@types/express`.
230
+
231
+ <!-- snippet: examples/snippets/webhook-nestjs.ts#bootstrap -->
232
+ ```ts
233
+ export async function bootstrap(appModule: Type, port: number): Promise<void> {
234
+ // rawBody: true keeps the raw bytes in req.rawBody, next to the parsed body.
235
+ const app = await NestFactory.create(appModule, { rawBody: true });
236
+ await app.listen(port);
237
+ }
238
+ ```
239
+ <!-- /snippet -->
240
+
241
+ Controller membaca `req.rawBody` dan `req.headers`:
242
+
243
+ <!-- snippet: examples/snippets/webhook-nestjs.ts#controller -->
244
+ ```ts
245
+ export const PLASGOS_WEBHOOK = "PLASGOS_WEBHOOK";
246
+
247
+ export interface WebhookDeps {
248
+ verifier: WebhookVerifier;
249
+ withTransaction: WithTransaction;
250
+ apply: ApplyEvent;
251
+ }
252
+
253
+ @Controller("webhooks")
254
+ export class PlasgosWebhookController {
255
+ constructor(@Inject(PLASGOS_WEBHOOK) private readonly deps: WebhookDeps) {}
256
+
257
+ @Post("plasgos")
258
+ async receive(
259
+ @Req() req: RawBodyRequest<Request>,
260
+ @Res({ passthrough: true }) res: Response,
261
+ ): Promise<WebhookAnswer["body"]> {
262
+ if (req.rawBody === undefined) {
263
+ res.status(415);
264
+ return { error: "unsupported_media_type" };
265
+ }
266
+ const { verifier, withTransaction, apply } = this.deps;
267
+ const answer = await handleWebhook(verifier, withTransaction, apply, { headers: req.headers, rawBody: req.rawBody });
268
+ res.status(answer.status);
269
+ return answer.body;
270
+ }
271
+ }
272
+
273
+ @Module({})
274
+ export class PlasgosWebhookModule {
275
+ /** `withTransaction` and `apply` come from the app's database layer. */
276
+ static register(deps: Omit<WebhookDeps, "verifier">): DynamicModule {
277
+ return {
278
+ module: PlasgosWebhookModule,
279
+ controllers: [PlasgosWebhookController],
280
+ // The verifier is created at bootstrap: a wrong option stops the app with one ConfigError.
281
+ providers: [{ provide: PLASGOS_WEBHOOK, useFactory: (): WebhookDeps => ({ ...deps, verifier: createPaymentsWebhookVerifier() }) }],
282
+ };
283
+ }
284
+ }
285
+ ```
286
+ <!-- /snippet -->
287
+
288
+ Di modul aplikasi: `PlasgosWebhookModule.register({ withTransaction, apply })`. Verifier dibuat saat bootstrap, jadi opsi yang salah menghentikan aplikasi saat start. Contoh ini memakai token injeksi string dan `@Inject`, jadi tidak butuh `emitDecoratorMetadata`.
289
+
290
+ ### React Router dan server berbasis `Request`
291
+
292
+ Untuk server yang memakai Web `Request` dan `Response` (React Router, Hono, Next.js route handler, dan sejenisnya). Body dibaca sebagai byte dengan batas 1 MiB. `content-length` yang lebih besar langsung dijawab `413`. Tanpa `content-length`, atau bila nilainya salah, pembacaan berhenti begitu jumlah byte melewati batas. Jangan memakai `request.arrayBuffer()` tanpa batas.
293
+
294
+ <!-- snippet: examples/snippets/webhook-fetch.ts#read-body -->
295
+ ```ts
296
+ /** 1 MiB. Plasgos webhooks are far smaller. */
297
+ const MAX_BODY_BYTES = 1_048_576;
298
+
299
+ /**
300
+ * The raw body as bytes, or null when it is larger than `maxBytes`. Reads chunk by chunk and stops as
301
+ * soon as the count passes the cap, so a missing or false content-length never fills memory.
302
+ */
303
+ export async function readRawBody(request: Request, maxBytes = MAX_BODY_BYTES): Promise<Uint8Array | null> {
304
+ if (Number(request.headers.get("content-length") ?? "0") > maxBytes) return null;
305
+ if (request.body === null) return new Uint8Array(0);
306
+
307
+ const reader = request.body.getReader();
308
+ const chunks: Uint8Array[] = [];
309
+ let total = 0;
310
+ for (;;) {
311
+ const result: { done: boolean; value?: unknown } = await reader.read();
312
+ if (result.done) break;
313
+ const chunk = result.value;
314
+ if (!(chunk instanceof Uint8Array)) {
315
+ await reader.cancel();
316
+ throw new TypeError("request body must be a byte stream");
317
+ }
318
+ total += chunk.byteLength;
319
+ if (total > maxBytes) {
320
+ await reader.cancel();
321
+ return null;
322
+ }
323
+ chunks.push(chunk);
324
+ }
325
+
326
+ const body = new Uint8Array(total);
327
+ let offset = 0;
328
+ for (const chunk of chunks) {
329
+ body.set(chunk, offset);
330
+ offset += chunk.byteLength;
331
+ }
332
+ return body;
333
+ }
334
+ ```
335
+ <!-- /snippet -->
336
+
337
+ <!-- snippet: examples/snippets/webhook-fetch.ts#route -->
338
+ ```ts
339
+ /** POST /webhooks/plasgos. A React Router `action({ request })` can return it as is. */
340
+ export async function webhookRoute(
341
+ request: Request,
342
+ verifier: WebhookVerifier,
343
+ withTransaction: WithTransaction,
344
+ apply: ApplyEvent,
345
+ ): Promise<Response> {
346
+ const rawBody = await readRawBody(request);
347
+ if (rawBody === null) return Response.json({ error: "payload_too_large" }, { status: 413 });
348
+ const answer = await handleWebhook(verifier, withTransaction, apply, { headers: request.headers, rawBody });
349
+ return Response.json(answer.body, { status: answer.status });
350
+ }
351
+ ```
352
+ <!-- /snippet -->
353
+
354
+ ## 6. Menangani kiriman
355
+
356
+ Urutannya: verifikasi, buka transaksi database, catat `id` event, terapkan efeknya di transaksi yang sama, commit, baru jawab `2xx`.
357
+
358
+ <!-- snippet: examples/snippets/webhook-verifier.ts#handle -->
359
+ ```ts
360
+ /** What the route answers. Each framework example turns it into its own response. */
361
+ export interface WebhookAnswer {
362
+ status: number;
363
+ body: { ok: true } | { error: string };
364
+ }
365
+
366
+ /** The business effect of one event. Runs in the same transaction as `saveOnce`. */
367
+ export type ApplyEvent = (tx: Tx, event: VerifiedWebhook) => Promise<void>;
368
+
369
+ /**
370
+ * One delivery. Plasgos counts every answer other than 2xx (400, 401 and redirects too) as a failed
371
+ * attempt and sends it again later. Answer within about 10 seconds: heavy work goes to an inbox
372
+ * table that a worker processes later.
373
+ */
374
+ export async function handleWebhook(
375
+ verifier: WebhookVerifier,
376
+ withTransaction: WithTransaction,
377
+ apply: ApplyEvent,
378
+ input: WebhookVerifyInput,
379
+ ): Promise<WebhookAnswer> {
380
+ let event: VerifiedWebhook;
381
+ try {
382
+ event = verifier.verify(input);
383
+ } catch (error) {
384
+ if (!(error instanceof WebhookVerifyError)) throw error;
385
+ // reason and header never hold a secret, a signature or a header value: safe to log.
386
+ const header = error.header ?? "-";
387
+ process.stderr.write(`plasgos webhook refused: preset=${verifier.preset} reason=${error.reason} header=${header}\n`);
388
+ const status = error.reason === "signature_mismatch" || error.reason === "stale_timestamp" ? 401 : 400;
389
+ return { status, body: { error: error.reason } };
390
+ }
391
+
392
+ try {
393
+ await withTransaction(async (tx) => {
394
+ // false: a redelivery of an event that is already processed. Commit and do nothing else.
395
+ if (!(await dedup.saveOnce(tx, event))) return;
396
+ await apply(tx, event);
397
+ });
398
+ } catch {
399
+ // Rolled back, the event id too: Plasgos sends the event again and it is processed then.
400
+ process.stderr.write(`plasgos webhook failed: preset=${verifier.preset} id=${event.id} type=${event.type}\n`);
401
+ return { status: 500, body: { error: "processing_failed" } };
402
+ }
403
+ // Committed: only now answer 2xx.
404
+ return { status: 200, body: { ok: true } };
405
+ }
406
+ ```
407
+ <!-- /snippet -->
408
+
409
+ Jawaban yang disarankan:
410
+
411
+ | Hasil | Jawaban |
412
+ |---|---|
413
+ | Lolos verifikasi dan sudah di-commit | `200` |
414
+ | Kiriman ulang (`saveOnce` mengembalikan `false`) | `200`, tanpa memproses lagi |
415
+ | `signature_mismatch`, `stale_timestamp` | `401` |
416
+ | `WebhookVerifyError` lain | `400` |
417
+ | Proses gagal, transaksi di-rollback | `500`, supaya Plasgos mengirim ulang |
418
+
419
+ Semua jawaban selain `2xx` diulang Plasgos ([§2](#2-aturan-pengiriman)). Arti setiap `reason` ada di [`error.md` §7](error.md#7-webhookverifyerror).
420
+
421
+ ### Hasil verifikasi
422
+
423
+ `verify` mengembalikan `VerifiedWebhook`:
424
+
425
+ | Field | Isi |
426
+ |---|---|
427
+ | `id` | Id event dari body yang ditandatangani. Dedup dengan nilai ini |
428
+ | `type` | Type event dari body yang ditandatangani, misalnya `payment.paid` |
429
+ | `timestamp` | Waktu kirim percobaan ini, dalam detik epoch. Untuk event yang dikirim ulang, nilai ini berbeda di setiap percobaan |
430
+ | `body` | Seluruh body sebagai objek JSON yang dibekukan (tidak bisa diubah) |
431
+ | `environment` | `environment` milik verifier |
432
+ | `preset` | Nama preset yang memverifikasi: `payments` atau `plaslinkShipping` |
433
+
434
+ ## 7. Dedup di transaksi yang sama
435
+
436
+ Simpan `id` event di transaksi database yang sama dengan efek bisnisnya. Id dan efek harus commit bersama:
437
+
438
+ - Bila id disimpan di transaksi sendiri lalu efeknya gagal, kiriman ulang terlihat seperti duplikat, dan event itu hilang.
439
+ - Bila efek berhasil tetapi id tidak tersimpan, kiriman ulang diproses dua kali.
440
+
441
+ SDK tidak menyimpan apa pun. `WebhookDedupStore<Tx>` hanya type: `saveOnce(tx, event)` dipanggil di dalam transaksi `tx`, menyimpan `event.id` bila baru, dan mengembalikan `true` bila baru disimpan atau `false` untuk kiriman ulang. Contoh dengan unique key:
442
+
443
+ <!-- snippet: examples/snippets/webhook-verifier.ts#dedup -->
444
+ ```ts
445
+ /** The part of a database transaction this example needs. Your driver's transaction object fits it. */
446
+ export interface Tx {
447
+ query(sql: string, params: readonly unknown[]): Promise<{ rowCount: number | null }>;
448
+ }
449
+
450
+ /** Runs `fn` in one transaction: commits when it resolves, rolls back when it throws. */
451
+ export type WithTransaction = <T>(fn: (tx: Tx) => Promise<T>) => Promise<T>;
452
+
453
+ /** Keeps the event id in the same transaction that applies the event's effect. */
454
+ export const dedup: WebhookDedupStore<Tx> = {
455
+ async saveOnce(tx, event) {
456
+ const result = await tx.query(
457
+ "INSERT INTO plasgos_webhook_events (event_id, event_type) VALUES ($1, $2) ON CONFLICT (event_id) DO NOTHING",
458
+ [event.id, event.type],
459
+ );
460
+ return result.rowCount === 1;
461
+ },
462
+ };
463
+ ```
464
+ <!-- /snippet -->
465
+
466
+ Tabelnya:
467
+
468
+ ```sql
469
+ CREATE TABLE plasgos_webhook_events (
470
+ event_id text PRIMARY KEY,
471
+ event_type text NOT NULL,
472
+ received_at timestamptz NOT NULL DEFAULT now()
473
+ );
474
+ ```
475
+
476
+ Aturannya:
477
+
478
+ - `saveOnce(tx, event)` dan efek event berjalan di transaksi yang sama.
479
+ - Bila apa pun gagal, rollback dan jawab `5xx`. Id ikut batal, jadi kiriman ulang diproses saat itu.
480
+ - Jawab `2xx` hanya setelah commit.
481
+
482
+ **Pekerjaan berat lewat inbox.** Bila efeknya lama (memanggil API lain, mengirim email, menghitung ulang banyak data), jangan kerjakan di dalam request. Simpan seluruh event sebagai baris inbox di `saveOnce` (`INSERT … ON CONFLICT (event_id) DO NOTHING` dengan `body` event). Penyimpanan itu adalah seluruh efeknya: commit, lalu jawab `2xx`. Sebuah worker memproses baris inbox belakangan, dengan pengulangannya sendiri. Dengan cara ini aplikasi selalu menjawab dalam 10 detik.
483
+
484
+ **`withTransaction` dari pool koneksi.** `handleWebhook` menerima `withTransaction` dari lapisan database aplikasi. Contoh di atas pool koneksi, dengan satu koneksi per transaksi:
485
+
486
+ <!-- snippet: examples/snippets/webhook-verifier.ts#with-transaction -->
487
+ ```ts
488
+ /** A connection pool that hands out one connection per transaction. node-postgres' `Pool` fits it. */
489
+ export interface TxPool {
490
+ connect(): Promise<Tx & { release(): void }>;
491
+ }
492
+
493
+ /** `WithTransaction` over a pool: BEGIN, then COMMIT when `fn` resolves or ROLLBACK when it throws. */
494
+ export function transactions(pool: TxPool): WithTransaction {
495
+ return async (fn) => {
496
+ const client = await pool.connect();
497
+ try {
498
+ await client.query("BEGIN", []);
499
+ const result = await fn(client);
500
+ await client.query("COMMIT", []);
501
+ return result;
502
+ } catch (error) {
503
+ await client.query("ROLLBACK", []);
504
+ throw error;
505
+ } finally {
506
+ client.release();
507
+ }
508
+ };
509
+ }
510
+ ```
511
+ <!-- /snippet -->
512
+
513
+ Dengan node-postgres: `const withTransaction = transactions(new pg.Pool());`.
514
+
515
+ ## 8. Rotasi secret
516
+
517
+ Secret webhook diganti lewat tim Plasgos. Selama rotasi, `secrets` berisi dua nilai, `[baru, lama]`. Urutannya bebas.
518
+
519
+ **Payments:**
520
+
521
+ 1. Tim Plasgos membuat secret baru dan menyerahkannya kepada Anda. Sejak saat itu Plasgos menandatangani setiap kiriman dengan kedua secret.
522
+ 2. Segera pasang `secrets: [baru, lama]` (env `PLASGOS_WEBHOOK_SECRET=baru,lama`) dan deploy.
523
+ 3. Secret lama otomatis berhenti dipakai Plasgos 24 jam setelah rotasi. Aplikasi harus sudah memakai secret baru sebelum itu. Bila belum, setiap kiriman gagal dan antreannya tertahan.
524
+ 4. Setelah 24 jam, hapus secret lama: `secrets: [baru]`.
525
+
526
+ Jangan rotasi lagi sebelum secret baru terpasang di aplikasi. Rotasi kedua dalam 24 jam langsung menghentikan secret yang asli, jadi aplikasi yang belum memasang secret dari rotasi pertama menolak setiap kiriman.
527
+
528
+ **Pengiriman Plaslink:**
529
+
530
+ 1. Tim Plasgos menyerahkan secret baru kepada Anda. Plasgos menandatangani dengan kedua secret.
531
+ 2. Pasang `secrets: [baru, lama]` (env `PLASGOS_SHIPPING_WEBHOOK_SECRET=baru,lama`), deploy, lalu konfirmasi ke tim Plasgos bahwa secret baru sudah terpasang.
532
+ 3. Tim Plasgos baru menghentikan secret lama setelah konfirmasi Anda.
533
+ 4. Setelah itu, hapus secret lama dari `secrets`.
534
+
535
+ ## 9. Error dan jawaban HTTP
536
+
537
+ | Error | Kapan | Yang dilakukan |
538
+ |---|---|---|
539
+ | `ConfigError` | `createWebhookVerifier` saat start: opsi salah | Perbaiki opsi. Semua masalah tercantum di `problems` |
540
+ | `WebhookVerifyError` | `verify`: kiriman ditolak | Jawab `401` atau `400` ([§6](#6-menangani-kiriman)), catat `reason` dan `header` |
541
+ | `TypeError` | `verify`: argumen salah, misalnya body yang sudah di-parse | Bug di kode Anda. Berikan body mentah |
542
+
543
+ Pesan error tidak pernah memuat secret, tanda tangan, nilai header, atau isi body, jadi aman ditulis ke log. Daftar lengkapnya ada di [`error.md` §7](error.md#7-webhookverifyerror).
544
+
545
+ ## 10. Menguji penerima
546
+
547
+ Untuk test, tandatangani kiriman sendiri dengan cara yang sama seperti Plasgos. Pakai secret khusus test (minimal 32 byte) yang juga dibaca aplikasi Anda saat test, bukan secret asli.
548
+
549
+ <!-- snippet: examples/snippets/webhook-testing.ts#sign -->
550
+ ```ts
551
+ /** An event body as Plasgos sends it. `id` and `type` also go into the headers. */
552
+ export interface TestEvent {
553
+ id: string;
554
+ type: string;
555
+ [field: string]: unknown;
556
+ }
557
+
558
+ /**
559
+ * A delivery signed the way Plasgos signs one: `v1=` + hex HMAC-SHA256 of "<timestamp>.<raw body>".
560
+ * Use a test secret that your app under test also reads from its env, never a real one.
561
+ */
562
+ export function signTestDelivery(
563
+ secret: string,
564
+ event: TestEvent,
565
+ preset: WebhookPreset = presets.payments,
566
+ nowMs: number = Date.now(),
567
+ ): { headers: Record<string, string>; body: string } {
568
+ const body = JSON.stringify(event);
569
+ const timestamp = String(Math.floor(nowMs / 1000));
570
+ const signature = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
571
+ return {
572
+ body,
573
+ headers: {
574
+ "content-type": "application/json",
575
+ [preset.headers.id]: event.id,
576
+ [preset.headers.type]: event.type,
577
+ [preset.headers.timestamp]: timestamp,
578
+ [preset.headers.signature]: `v1=${signature}`,
579
+ },
580
+ };
581
+ }
582
+ ```
583
+ <!-- /snippet -->
584
+
585
+ Lalu kirim ke route Anda yang sedang berjalan: kiriman yang ditandatangani harus dijawab `200`, dan kiriman yang body-nya diubah harus dijawab `401`.
586
+
587
+ <!-- snippet: examples/snippets/webhook-testing.ts#route-test -->
588
+ ```ts
589
+ /** Your running route accepts a signed delivery and refuses the same delivery with a changed body. */
590
+ export async function checkWebhookRoute(url: string, secret: string): Promise<void> {
591
+ const event: TestEvent = {
592
+ id: "whd_test_1",
593
+ type: "payment.paid",
594
+ sequence: 1,
595
+ occurred_at: new Date().toISOString(),
596
+ subject: { type: "payment", id: "pay_test_1" },
597
+ data: {},
598
+ };
599
+ const signed = signTestDelivery(secret, event);
600
+
601
+ const accepted = await fetch(url, { method: "POST", headers: signed.headers, body: signed.body });
602
+ if (accepted.status !== 200) throw new Error(`signed delivery answered ${String(accepted.status)}`);
603
+
604
+ const tampered = signed.body.replace("pay_test_1", "pay_test_2");
605
+ const refused = await fetch(url, { method: "POST", headers: signed.headers, body: tampered });
606
+ if (refused.status !== 401) throw new Error(`tampered delivery answered ${String(refused.status)}`);
607
+ }
608
+ ```
609
+ <!-- /snippet -->
610
+
611
+ Id event di test harus memakai huruf, angka, `_`, `.`, `:`, atau `-`, seperti id asli (`whd_…`). Untuk menguji `stale_timestamp`, beri `nowMs` yang lebih dari 300 detik di masa lalu.
612
+
613
+ ## 11. Sebelum production
614
+
615
+ - [ ] Route webhook menerima body mentah (`express.raw`, `rawBody: true`, atau `readRawBody`) dan memberikannya ke `verify` sebelum JSON di-parse.
616
+ - [ ] Batas body framework terpasang di route webhook.
617
+ - [ ] Verifier dibuat saat start, dan `ConfigError` menghentikan aplikasi.
618
+ - [ ] `environment` sesuai lingkungan, dan secret production berbeda dari sandbox.
619
+ - [ ] `saveOnce` berjalan di transaksi yang sama dengan efek event, dengan unique key pada `event_id`.
620
+ - [ ] `2xx` hanya setelah commit; `5xx` bila apa pun gagal.
621
+ - [ ] Route menjawab dalam 10 detik. Pekerjaan berat lewat inbox.
622
+ - [ ] Jam server sinkron (NTP).
623
+ - [ ] Log mencatat `reason` dan `header` dari `WebhookVerifyError`, dan ada alert untuk `signature_mismatch` yang berulang (biasanya secret salah).
624
+ - [ ] Langkah rotasi secret ([§8](#8-rotasi-secret)) sudah dipahami tim yang men-deploy.
625
+ - [ ] Test mengirim kiriman bertanda tangan dan kiriman yang diubah ke route Anda ([§10](#10-menguji-penerima)).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plasgos/oidc-client",
3
- "version": "0.1.0-next.1",
3
+ "version": "0.1.0-next.2",
4
4
  "description": "Plasgos OIDC client for Node servers: user login (code + PKCE), sealed session cookies and client_credentials.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -21,6 +21,7 @@
21
21
  },
22
22
  "files": [
23
23
  "dist",
24
+ "docs",
24
25
  "README.md",
25
26
  "CHANGELOG.md",
26
27
  "LICENSE"
@@ -61,7 +62,7 @@
61
62
  "main": "./dist/index.cjs",
62
63
  "types": "./dist/index.d.cts",
63
64
  "dependencies": {
64
- "@plasgos/auth-shared": "0.1.0-next.1"
65
+ "@plasgos/auth-shared": "0.1.0-next.2"
65
66
  },
66
67
  "scripts": {
67
68
  "build": "tsup"