kinde-testkit 0.3.0 → 0.4.0

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 CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.0
4
+
5
+ - Add signed webhooks in Kinde's format: a JWT body with `Content-Type: application/jwt` and a `webhook-id` header, decodable with `@kinde/webhooks`.
6
+ - Build payloads for the 16 event types `@kinde/webhooks` defines from seeded users, organizations, roles and permissions. Send billing events, and any other type, with your own `data`.
7
+ - Deliver to endpoints from the seed's `webhooks`, `start --webhook`, `addEndpoint()` or a `to` URL, with event filters, Kinde's rule that only a 200 counts as delivered, fast retries with the same `webhook-id`, timeouts, and a delivery log.
8
+ - Test the hard cases with `duplicate`, and with `invalid` set to `bad-signature`, `unknown-key`, `unsigned` or `stale`.
9
+ - Signing in on the testkit page sends `user.authenticated`, and a first sign-in with an unseeded email sends `user.created`.
10
+ - Add `kinde-testkit webhook`, `kinde.webhooks` in Vitest, `kinde.sendWebhook()` in Playwright, and `/testkit/webhooks` endpoints.
11
+ - The Next.js example adds a webhook route with tests for valid, duplicated, forged and stale events.
12
+
3
13
  ## 0.3.0
4
14
 
5
15
  - Add the `client_credentials` grant with Kinde's machine-to-machine token shape (`gty`, `scope`, `scp`, `v`, no `sub`), seeded `applications` with secrets, scopes, permissions, audiences and organizations, `testkit.m2mToken()`, and `kinde-testkit token --m2m`.
package/README.md CHANGED
@@ -9,7 +9,7 @@ There are two ways to use it:
9
9
  - **API and unit tests:** mint a token for any user, organization and permission set, including expired, tampered and unsigned tokens, and send it to your API.
10
10
  - **Browser tests:** point your app at the testkit, and Playwright signs in as any seeded user through your app's own login route.
11
11
 
12
- It also issues machine-to-machine tokens, makes Kinde's endpoints fail or slow down on demand, and has a `doctor` command that checks your app's Kinde settings before a test run.
12
+ It also issues machine-to-machine tokens, sends signed webhooks, makes Kinde's endpoints fail or slow down on demand, and has a `doctor` command that checks your app's Kinde settings before a test run.
13
13
 
14
14
  ## Why it exists
15
15
 
@@ -147,6 +147,7 @@ test("a consultant switches organization", async ({ page, kinde }) => {
147
147
  | `kinde.signOut()` | Opens your app's logout route |
148
148
  | `kinde.injectFailure(rule)` | Makes a testkit endpoint fail, slow down or hang. Removed when the test ends |
149
149
  | `kinde.clearFailures()` | Removes the failures this test added |
150
+ | `kinde.sendWebhook(event)` | Sends a signed webhook and returns the delivery results |
150
151
 
151
152
  The fixture uses `/api/auth/login` and `/api/auth/logout`, the Next.js SDK's routes. Set `kindeLoginPath` and `kindeLogoutPath` in `use` when your app's routes are different. Each test gets its own browser context, so tests run in parallel without sharing sessions.
152
153
 
@@ -186,6 +187,57 @@ curl -s -X POST http://localhost:4400/oauth2/token \
186
187
 
187
188
  In tests, mint one directly with `testkit.m2mToken({ clientId, organizationCode, scopes, audience })`, or run `kinde-testkit token --m2m --client-id acme_agent --scope read:users`. M2M tokens take the same `invalid` kinds as user tokens. `principalFromClaims()` reads them as `{ type: "machine", subject: <client ID> }`.
188
189
 
190
+ ## Webhooks
191
+
192
+ Kinde sends webhooks as a signed JWT with `Content-Type: application/jwt` and a `webhook-id` header that stays the same across retries. Your endpoint checks the signature with `decodeWebhook()` from `@kinde/webhooks`, which fetches keys from your issuer. kinde-testkit sends webhooks the same way, signed with its own key, so the same handler code works in tests when `KINDE_ISSUER_URL` points at the testkit.
193
+
194
+ Add the endpoints that should receive events to the seed file, or pass `--webhook <url>` to `start`:
195
+
196
+ ```json
197
+ {
198
+ "webhooks": [
199
+ { "url": "http://localhost:3000/api/webhooks/kinde" },
200
+ { "url": "http://localhost:3000/api/webhooks/billing", "events": ["customer.payment_succeeded"] }
201
+ ]
202
+ }
203
+ ```
204
+
205
+ Then send events from a test or the command line:
206
+
207
+ ```ts
208
+ // Vitest
209
+ const [delivery] = await kinde.webhooks.send({ type: "user.created", user: "admin@example.test" });
210
+ expect(delivery.delivered).toBe(true);
211
+
212
+ // Playwright
213
+ await kinde.sendWebhook({ type: "organization.created", organization: "org_acme", duplicate: 3 });
214
+ ```
215
+
216
+ ```bash
217
+ kinde-testkit webhook user.created --user admin@example.test
218
+ kinde-testkit webhook customer.payment_succeeded --data '{"customer_id":"customer_123"}'
219
+ kinde-testkit webhook --deliveries
220
+ ```
221
+
222
+ kinde-testkit builds the payload for the 16 event types that `@kinde/webhooks` defines, such as `user.created`, `organization.updated`, `role.deleted` and `access_request.created`, from your seeded users, organizations, roles and permissions. Kinde does not publish payload shapes for its billing events, such as `customer.plan_assigned`, so for those you pass the `data` object yourself. `kinde-testkit webhook --types` lists both groups.
223
+
224
+ With an endpoint configured, signing in on the testkit page sends `user.authenticated`, and the first sign-in with an email that is not seeded also sends `user.created`, as Kinde does.
225
+
226
+ Delivery follows Kinde's rules. Only a `200` counts as delivered. Anything else, or no answer, is retried with the same `webhook-id`. Kinde retries over 36 hours; the testkit retries after 0, 100 and 500 milliseconds by default, so tests stay fast. Change that with `startKindeTestkit({ webhooks: { retryDelaysMs, timeoutMs } })`.
227
+
228
+ These options test the hard parts of a webhook handler:
229
+
230
+ | Option | What it tests |
231
+ | --- | --- |
232
+ | `duplicate: n` | n copies with the same `webhook-id` and `event_id`. Your handler should process the event once |
233
+ | `invalid: "bad-signature"` | A tampered signature. `decodeWebhook()` returns `null` |
234
+ | `invalid: "unknown-key"` | Signed by a key your issuer never published |
235
+ | `invalid: "unsigned"` | `alg: none` |
236
+ | `invalid: "stale"` | A valid signature on an hour-old `timestamp`, for replay checks |
237
+ | `to: url` | Send to one URL instead of the configured endpoints |
238
+
239
+ `kinde.webhooks.deliveries()`, `kinde-testkit webhook --deliveries` and `GET /testkit/webhooks/deliveries` show every attempt with its status code or error. [`examples/nextjs`](examples/nextjs) has a webhook route and Playwright tests for valid, duplicated, forged and stale events.
240
+
189
241
  ## Testing outages
190
242
 
191
243
  Your app should handle Kinde being slow or down. kinde-testkit can make any endpoint answer with an error, wait before answering, or never answer:
@@ -310,6 +362,9 @@ When `kinde-testkit.json` exists in the current folder, `start` loads it. Pass `
310
362
  ],
311
363
  "applications": [
312
364
  { "clientId": "acme_agent", "organization": "org_acme", "scopes": ["read:users"] }
365
+ ],
366
+ "webhooks": [
367
+ { "url": "http://localhost:3000/api/webhooks/kinde" }
313
368
  ]
314
369
  }
315
370
  ```
@@ -320,7 +375,7 @@ A token for a seeded user takes its roles and permissions from the membership in
320
375
 
321
376
  | Command | What it does |
322
377
  | --- | --- |
323
- | `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--allow-public`, `--json` |
378
+ | `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--allow-public`, `--json` |
324
379
  | `kinde-testkit token` | Print a signed access token. Options: `--user`, `--org`, `--sub`, `--permissions`, `--roles`, `--expires-in`, `--invalid`, `--url`, `--json` |
325
380
  | `kinde-testkit users` | List seeded users |
326
381
  | `kinde-testkit organizations` | List seeded organizations |
@@ -328,7 +383,8 @@ A token for a seeded user takes its roles and permissions from the membership in
328
383
  | `kinde-testkit inspect [token]` | Decode a token and check it. Reads stdin when no token is given. Options: `--url`, `--json` |
329
384
  | `kinde-testkit doctor` | Check your app's Kinde settings against the issuer. Options: `--url`, `--env-file`, `--json` |
330
385
  | `kinde-testkit fail <path>` | Add a failure rule. Options: `--status`, `--delay`, `--hang`, `--times`, `--method`, `--list`, `--clear` |
331
- | `kinde-testkit reset` | Clear sign-in sessions and failure rules |
386
+ | `kinde-testkit reset` | Clear sign-in sessions, failure rules, webhook deliveries and endpoints added at runtime |
387
+ | `kinde-testkit webhook <type>` | Send a signed webhook. Options: `--user`, `--org`, `--role`, `--permission`, `--data`, `--to`, `--duplicate`, `--invalid`, `--types`, `--deliveries` |
332
388
 
333
389
  Every command takes `--json` for CI scripts and coding agents.
334
390
 
@@ -368,13 +424,13 @@ import {
368
424
 
369
425
  - `scenario()` builds a caller: `.user()`, `.organization()`, `.withoutOrganization()`, `.role()`, `.permissions()`, `.claims()`, then `.authenticated()` or `.unauthenticated()`. The result is plain JSON, so you can keep scenarios in a shared file and import them anywhere.
370
426
  - `createKindeUser()` gives a user a stable id derived from the email, so the same email always maps to the same `kp_` id. `createKindeOrganization()` and `createMembership()` cover organizations and per-organization roles.
371
- - `KindeTestkit.create({ issuer, audience, clientId, accessTokenExpiresIn, idTokenExpiresIn })` holds a signing key. Access tokens last 24 hours and ID tokens 1 hour by default, the same as Kinde's defaults. Use `token()`, `tokenFor(scenario)`, `idTokenFor(scenario)`, `m2mToken()`, `headersFor(scenario)`, `principalFor(scenario)` and `jwks()`.
372
- - `startKindeTestkit({ port, seed, audience })` runs the issuer in-process and returns `{ url, issuer, jwksUri, testkit, failures, reset(), close() }`.
427
+ - `KindeTestkit.create({ issuer, audience, clientId, accessTokenExpiresIn, idTokenExpiresIn })` holds a signing key. Access tokens last 24 hours and ID tokens 1 hour by default, the same as Kinde's defaults. Use `token()`, `tokenFor(scenario)`, `idTokenFor(scenario)`, `m2mToken()`, `headersFor(scenario)`, `principalFor(scenario)`, `signPayload()` and `jwks()`.
428
+ - `startKindeTestkit({ port, seed, audience })` runs the issuer in-process and returns `{ url, issuer, jwksUri, testkit, failures, webhooks, reset(), close() }`. Pass `webhooks: { retryDelaysMs, timeoutMs }` to change webhook retries.
373
429
  - `inspectToken(token, { issuerUrl })` and `runDoctor({ url, env })` are the functions behind `inspect` and `doctor`. Both return a list of checks with `pass`, `warn` or `fail`.
374
430
  - `createKindeToken(options)` signs with a shared default testkit whose issuer is `http://localhost:4400`, or `KINDE_TESTKIT_ISSUER` when set.
375
431
  - `principalFromClaims(claims)` turns verified claims into `{ type, subject, issuer, organization, roles, permissions }`. `type` is `"user"`, or `"machine"` for M2M tokens.
376
432
 
377
- From `kinde-testkit/vitest`: `useKindeTestkit()`, which also exposes `failures` and `reset()`, and `kindeTest()`.
433
+ From `kinde-testkit/vitest`: `useKindeTestkit()`, which also exposes `failures`, `webhooks` and `reset()`, and `kindeTest()`.
378
434
 
379
435
  From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, the `KindeTestOptions` type for your config, and `createKindeFixture(page, options)` for building the fixture into your own `test.extend()`.
380
436
 
@@ -392,7 +448,10 @@ From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, t
392
448
  | `POST /testkit/token` | Mints a token directly, used by `kinde-testkit token` |
393
449
  | `GET /testkit/users`, `/testkit/organizations`, `/testkit/memberships`, `/testkit/health` | Seed data and a health check |
394
450
  | `GET`, `POST`, `DELETE /testkit/failures`, `DELETE /testkit/failures/<id>` | List, add and remove failure rules |
395
- | `POST /testkit/reset` | Clear sign-in state and failure rules |
451
+ | `POST /testkit/webhooks` | Send a webhook and return the deliveries |
452
+ | `GET /testkit/webhooks/deliveries`, `/testkit/webhooks/types` | Delivery log and the event types with built-in payloads |
453
+ | `GET`, `POST /testkit/webhooks/endpoints`, `DELETE /testkit/webhooks/endpoints/<id>` | List, add and remove webhook endpoints |
454
+ | `POST /testkit/reset` | Clear sign-in state, failure rules and webhook deliveries |
396
455
 
397
456
  ## Token shape
398
457
 
@@ -440,7 +499,7 @@ ID tokens carry `amr`, `aud` (the client ID), `auth_time`, `email`, `email_verif
440
499
  | Failure injection: error status, delay, hang, by path, method and count | Implemented, tested through the Next.js SDK |
441
500
  | `doctor`, `inspect` and `reset` commands | Implemented |
442
501
  | Management API and Account API | Not implemented |
443
- | Webhooks | Not implemented |
502
+ | Signed webhooks for the 16 event types in `@kinde/webhooks`, billing events with your data, retries, duplicates, forged and stale events | Implemented, tested with `@kinde/webhooks` and a Next.js route |
444
503
 
445
504
  ## Safety
446
505