kinde-testkit 0.4.0 → 0.6.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,23 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0
4
+
5
+ - Add `kinde-testkit/jest` with the same `useKindeTestkit()` and `kindeTest()` as the Vitest helper, for CommonJS and ESM test files.
6
+ - Add Cypress support: `setupKindeTestkit()` starts the testkit from `setupNodeEvents`, and `kinde-testkit/cypress/support` adds `cy.kindeSignIn()`, `cy.kindeSignOut()`, `cy.kindeToken()`, `cy.kindeInjectFailure()`, `cy.kindeClearFailures()`, `cy.kindeSendWebhook()` and `cy.kindeReset()`.
7
+ - Load seed files in YAML, JavaScript and TypeScript as well as JSON, and replace a running issuer's seed with `kinde-testkit seed <file>`.
8
+ - Add a dashboard at `/dashboard` with the seed, recent tokens, requests, webhook deliveries, failure rules and coverage, plus reset and send forms.
9
+ - Add an authentication coverage report: the testkit records which identity, organization, permission, token, session, M2M, API, webhook and outage cases a run produced. Read it with `kinde-testkit coverage`, and fail CI below a number with `--min`.
10
+ - Add a Dockerfile that runs the issuer as a non-root user with a health check, plus Docker Compose instructions.
11
+ - The Next.js example adds Cypress tests.
12
+
13
+ ## 0.5.0
14
+
15
+ - Add the Management API at `/api/v1`: users, organizations, organization members, member roles and permissions, roles and permissions. It needs an M2M token for `<issuer>/api`, checks the scopes of seeded applications, and writes every change into the testkit's data. Changes send the matching webhooks. Unimplemented routes answer 404 `ROUTE_NOT_FOUND`.
16
+ - Add the Account API at `/account_api/v1`: permissions, roles, feature flags, properties, entitlements and the portal link, for the active organization of the user's token. Kinde's `@kinde/js-utils` helpers work against it.
17
+ - Add HTTPS mode (`https: true`, `start --https`, `kinde-testkit cert`) with a local certificate, so Kinde's official `@kinde/management-api-js` client runs unchanged. CLI commands given an `https://` URL trust the certificate on their own.
18
+ - The seed takes `roles` with permissions, `permissions`, `featureFlags` with organization values, `plans` with entitlements, and user `properties`. A role's permissions are added to the member's token. Feature flags go into access tokens.
19
+ - Suspended users cannot sign in, and `reset()` restores the seed after API changes.
20
+
3
21
  ## 0.4.0
4
22
 
5
23
  - Add signed webhooks in Kinde's format: a JWT body with `Content-Type: application/jwt` and a `webhook-id` header, decodable with `@kinde/webhooks`.
package/README.md CHANGED
@@ -7,9 +7,9 @@ Test apps that use Kinde without a live Kinde environment. kinde-testkit runs a
7
7
  There are two ways to use it:
8
8
 
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
- - **Browser tests:** point your app at the testkit, and Playwright signs in as any seeded user through your app's own login route.
10
+ - **Browser tests:** point your app at the testkit, and Playwright or Cypress signs in as any seeded user through your app's own login route.
11
11
 
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.
12
+ It also issues machine-to-machine tokens, answers the Management API and Account API calls your app makes, sends signed webhooks, and makes Kinde's endpoints fail or slow down on demand. A local dashboard shows what the testkit issued and answered, a coverage report shows which authentication cases your tests reached, and a `doctor` command checks your app's Kinde settings before a test run. It runs with Vitest, Jest, Playwright and Cypress, from the command line, or in Docker.
13
13
 
14
14
  ## Why it exists
15
15
 
@@ -85,6 +85,25 @@ describe("projects API", () => {
85
85
 
86
86
  `useKindeTestkit()` starts the issuer on a free port before the tests and stops it after. Point your app's issuer setting at `kinde.issuer` for the test run, so its middleware fetches keys from the testkit instead of Kinde.
87
87
 
88
+ ### Jest
89
+
90
+ `kinde-testkit/jest` has the same `useKindeTestkit()` and `kindeTest()`. It works with CommonJS and ESM test files:
91
+
92
+ ```js
93
+ const { scenario } = require("kinde-testkit");
94
+ const { useKindeTestkit } = require("kinde-testkit/jest");
95
+
96
+ const kinde = useKindeTestkit({ seed: "kinde-testkit.yaml" });
97
+
98
+ test("a viewer cannot delete a project", async () => {
99
+ const { headers } = await kinde.auth(scenario().user({ email: "viewer@example.test" }).organization("org_acme").authenticated());
100
+ const res = await request(app).delete("/projects/p1").set(headers);
101
+ expect(res.status).toBe(403);
102
+ });
103
+ ```
104
+
105
+ It uses Jest's global `beforeAll` and `afterAll`. If you turn off `injectGlobals`, pass them from `@jest/globals`: `useKindeTestkit(options, { beforeAll, afterAll })`.
106
+
88
107
  ## Browser tests with Playwright
89
108
 
90
109
  Start the testkit and your app from `playwright.config.ts`, with the app's Kinde settings pointed at the testkit:
@@ -155,6 +174,52 @@ A user with more than one organization needs `{ org }`, otherwise the fixture st
155
174
 
156
175
  [`examples/nextjs`](examples/nextjs) is a working Next.js app on `@kinde-oss/kinde-auth-nextjs` with these tests.
157
176
 
177
+ ## Browser tests with Cypress
178
+
179
+ Start the testkit from `setupNodeEvents`, and import the commands in your support file:
180
+
181
+ ```ts
182
+ // cypress.config.ts
183
+ import { defineConfig } from "cypress";
184
+ import { setupKindeTestkit } from "kinde-testkit/cypress";
185
+
186
+ export default defineConfig({
187
+ e2e: {
188
+ baseUrl: "http://localhost:3000",
189
+ setupNodeEvents(on, config) {
190
+ return setupKindeTestkit(on, config, { start: { seed: "kinde-testkit.json" } });
191
+ },
192
+ },
193
+ });
194
+ ```
195
+
196
+ ```ts
197
+ // cypress/support/e2e.ts
198
+ import "kinde-testkit/cypress/support";
199
+ ```
200
+
201
+ This starts the testkit on port 4400 for the run, so start your app with `KINDE_ISSUER_URL=http://localhost:4400`. If you already run `kinde-testkit start`, leave out `start`, and the commands use `KINDE_ISSUER_URL` or `http://localhost:4400`.
202
+
203
+ ```ts
204
+ it("a viewer cannot delete projects", () => {
205
+ cy.kindeSignIn("viewer@example.test");
206
+ cy.visit("/projects");
207
+ cy.contains("button", /Delete/).should("not.exist");
208
+ });
209
+ ```
210
+
211
+ | Command | What it does |
212
+ | --- | --- |
213
+ | `cy.kindeSignIn(email, { org, loginPath })` | Signs in through your app's login route with requests, then opens the app's callback. Fast, and needs no `cy.origin()` |
214
+ | `cy.kindeSignOut({ logoutPath })` | Opens your app's logout route |
215
+ | `cy.kindeToken(options)` | Yields an access token, with the same options as `POST /testkit/token` |
216
+ | `cy.kindeInjectFailure(rule)` | Makes a testkit endpoint fail, slow down or hang. Removed when the test ends |
217
+ | `cy.kindeClearFailures()` | Removes the failures this test added |
218
+ | `cy.kindeSendWebhook(event)` | Sends a signed webhook and yields the delivery results |
219
+ | `cy.kindeReset()` | Clears sessions, failure rules, deliveries and Management API changes |
220
+
221
+ `cy.kindeSignIn()` skips the sign-in page but runs everything else your app does: its login route, its state cookie and its callback, where the app exchanges the code for tokens. To test the sign-in page itself, visit your login route and use `cy.origin("http://localhost:4400", ...)`. The example app's `cypress/e2e/auth.cy.ts` does both.
222
+
158
223
  ### The sign-in page
159
224
 
160
225
  The page at `/oauth2/auth` lists the seeded users. You can also type any email address: a user that is not in the seed file signs in without an organization. A user with more than one organization picks one on the next screen, unless the app sent `org_code`.
@@ -238,6 +303,49 @@ These options test the hard parts of a webhook handler:
238
303
 
239
304
  `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
305
 
306
+ ## Management API and Account API
307
+
308
+ Many apps call Kinde's APIs as well as signing users in. An admin page creates organizations and adds members, a signup flow creates users, and the front end asks the Account API for the current user's permissions and feature flags. kinde-testkit answers these calls from the seed, so the test checks what your code does with the result.
309
+
310
+ The Management API is at `/api/v1`. Like Kinde, it needs a machine-to-machine token for the audience `<issuer>/api`. When a seeded application has scopes, the token gets those scopes and each route checks for its own, such as `read:users` or `create:organizations`. These routes work:
311
+
312
+ | Area | Routes |
313
+ | --- | --- |
314
+ | Users | List, filter by ID or email, get, create, update (including `is_suspended`), delete |
315
+ | Organizations | List, get, create, update, delete |
316
+ | Members | List, add with roles, remove |
317
+ | Member roles and permissions | List, grant, remove |
318
+ | Roles and permissions | List, get, create, delete, and list a role's permissions |
319
+
320
+ Every change goes into the testkit's data. A user you create can sign in, a member you add gets the role's permissions in their next token, and a suspended user sees an error on the sign-in page. Each change also sends the matching webhook, such as `organization.created` or `user.deleted`, to your configured endpoints. `reset()` puts the seed back. A route the testkit does not implement answers 404 with the code `ROUTE_NOT_FOUND`, so a test never passes against an empty answer.
321
+
322
+ Kinde's official client, `@kinde/management-api-js`, forces `https://`. Start the testkit with HTTPS and run your code with the certificate it prints:
323
+
324
+ ```ts
325
+ const kinde = useKindeTestkit({ seed, https: true });
326
+ ```
327
+
328
+ ```bash
329
+ npx kinde-testkit start --https
330
+ NODE_EXTRA_CA_CERTS=.kinde-testkit/localhost-cert.pem npm test
331
+ ```
332
+
333
+ The first start writes a self-signed certificate for `localhost` and `127.0.0.1` to `.kinde-testkit/` and reuses it after that. The test suite runs the official client against the testkit without changes.
334
+
335
+ The Account API is at `/account_api/v1`. It reads the user's access token and answers for the token's active organization: `permissions`, `permission/<key>`, `roles`, `feature_flags`, `properties`, `entitlements`, `entitlement/<key>` and `portal_link`. Kinde's `@kinde/js-utils` helpers, such as `getPermissions({ forceApi: true })`, `getFlag()` and `getEntitlements()`, work against it. Add the data it returns to the seed:
336
+
337
+ ```json
338
+ {
339
+ "users": [{ "id": "kp_admin", "email": "admin@example.test", "properties": { "team": "platform" } }],
340
+ "roles": [{ "key": "admin", "name": "Admin", "permissions": ["projects:read", "projects:delete"] }],
341
+ "memberships": [{ "user": "kp_admin", "organization": "org_acme", "roles": ["admin"] }],
342
+ "featureFlags": [{ "key": "new_editor", "value": false, "organizations": { "org_acme": true } }],
343
+ "plans": [{ "key": "pro", "subscribers": ["org_acme"], "entitlements": [{ "featureKey": "seats", "limitMax": 10 }] }]
344
+ }
345
+ ```
346
+
347
+ A role's permissions are added to the member's own permissions, in tokens and in both APIs. Feature flags also go into access tokens as `feature_flags`, with the organization's value when it has one.
348
+
241
349
  ## Testing outages
242
350
 
243
351
  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:
@@ -331,6 +439,7 @@ Issuer: http://localhost:4400
331
439
  Discovery: http://localhost:4400/.well-known/openid-configuration
332
440
  JWKS: http://localhost:4400/.well-known/jwks
333
441
  Token: POST http://localhost:4400/testkit/token
442
+ Dashboard: http://localhost:4400/dashboard
334
443
  ```
335
444
 
336
445
  Then mint a token from another terminal:
@@ -342,7 +451,23 @@ curl -H "Authorization: Bearer $(npx kinde-testkit token --user admin@example.te
342
451
 
343
452
  ### Seed file
344
453
 
345
- When `kinde-testkit.json` exists in the current folder, `start` loads it. Pass `--seed <file>` to use another path.
454
+ `start` loads the first of `kinde-testkit.json`, `.yaml`, `.yml`, `.ts`, `.mts`, `.js` and `.mjs` in the current folder. Pass `--seed <file>` to use another path. In code, `seed` takes an object or a file path. The same seed in YAML:
455
+
456
+ ```yaml
457
+ users:
458
+ - id: kp_admin
459
+ email: admin@example.test
460
+ organizations:
461
+ - code: org_acme
462
+ name: Acme Inc.
463
+ memberships:
464
+ - user: kp_admin
465
+ organization: org_acme
466
+ roles: [admin]
467
+ permissions: [projects:read, projects:delete]
468
+ ```
469
+
470
+ A JavaScript or TypeScript seed exports the object as its default export or as `seed`. TypeScript seeds need Node 22.18 or later, which runs TypeScript files directly. The JSON version, with every section:
346
471
 
347
472
  ```json
348
473
  {
@@ -371,19 +496,100 @@ When `kinde-testkit.json` exists in the current folder, `start` loads it. Pass `
371
496
 
372
497
  A token for a seeded user takes its roles and permissions from the membership in the active organization. A user with two memberships must name the organization. The issuer refuses a token for an organization the user does not belong to, because Kinde would not issue one. The issuer checks the whole seed when it starts and lists every problem at once.
373
498
 
499
+ `kinde-testkit seed <file>` replaces the seed of a running issuer, and `reset` returns to that seed after that. The issuer, audience and signing key stay the same, so apps that cached the keys keep working. `kinde-testkit stop` stops a running issuer.
500
+
501
+ ## Dashboard
502
+
503
+ Open `http://localhost:4400/dashboard` while the testkit runs. It shows:
504
+
505
+ - users, organizations and memberships, with the permissions each member's token gets
506
+ - the latest tokens the testkit issued, with their claims
507
+ - the latest requests to Kinde's endpoints, with status and time taken. Codes, secrets and refresh tokens are hidden
508
+ - webhook deliveries, and a form to send an event
509
+ - failure rules, and a form to add one
510
+ - the coverage report
511
+
512
+ It has buttons to reset the testkit and to clear coverage. **Live updates** reloads the page every 3 seconds. The dashboard only adds a view: everything on it is also in the CLI and the HTTP endpoints. It only accepts actions from its own page, so another site you have open cannot reset or change the testkit.
513
+
514
+ ## Authentication coverage
515
+
516
+ Most suites test that a user can sign in. Authorization bugs hide in the other cases: a token from another organization, an expired token, a user with no permissions. The testkit records which of these cases it produced during a run, grouped the way the bugs happen:
517
+
518
+ ```bash
519
+ npx kinde-testkit coverage
520
+ ```
521
+
522
+ ```
523
+ Kinde authentication coverage
524
+
525
+ Identity 6/6
526
+ Organizations 4/5
527
+ Permissions 5/5
528
+ Token validation 3/8
529
+ Sessions 4/5
530
+ Machine-to-machine 0/4
531
+ Kinde APIs 2/4
532
+ Webhooks 5/5
533
+ Outages 2/4
534
+
535
+ Overall: 31/46
536
+
537
+ Not covered:
538
+ Organizations: Organization claim missing. Mint a token with invalid: "missing-organization".
539
+ Token validation: Wrong issuer. Mint a token with invalid: "wrong-issuer".
540
+ ...
541
+ ```
542
+
543
+ Turn it on with `useKindeTestkit({ coverage: true })` in Vitest or Jest, `setupKindeTestkit(on, config, { start: { coverage: true } })` in Cypress, or `kinde-testkit start --coverage`. Each test file writes its result to `.kinde-testkit/coverage/` when it ends, and `kinde-testkit coverage` adds them up. Clear the folder before a run with `kinde-testkit coverage --clear`, and fail CI below a number with `--min 30`. For a running issuer, `kinde-testkit coverage --url http://localhost:4400` reads it directly, and the dashboard shows the same report.
544
+
545
+ Coverage counts what the testkit produced, such as an expired token or a 503 from the token endpoint. It does not know what your test checked after that. A covered item means your suite sent that case to your app. Your assertions decide whether the app handled it.
546
+
547
+ ## Docker
548
+
549
+ The repository has a Dockerfile. Build it straight from GitHub, then mount the folder with your seed file:
550
+
551
+ ```bash
552
+ docker build -t kinde-testkit https://github.com/sholajegede/kinde-testkit.git
553
+ docker run --rm -p 4400:4400 -v "$PWD:/work" kinde-testkit
554
+ ```
555
+
556
+ The container runs `kinde-testkit start` as a non-root user, loads the seed file from `/work`, and has a health check on `/testkit/health`. Its issuer is `http://localhost:4400`, which is right when your app and browser run on the host. In Docker Compose, where the app reaches the testkit by service name, set the issuer to the address your app uses:
557
+
558
+ ```yaml
559
+ services:
560
+ kinde:
561
+ build: https://github.com/sholajegede/kinde-testkit.git
562
+ command: ["start", "--host", "0.0.0.0", "--port", "4400", "--allow-public", "--issuer", "http://kinde:4400"]
563
+ volumes: ["./:/work"]
564
+ app:
565
+ build: .
566
+ environment:
567
+ KINDE_ISSUER_URL: http://kinde:4400
568
+ depends_on:
569
+ kinde:
570
+ condition: service_healthy
571
+ ```
572
+
573
+ The browser must reach the same issuer address as the app, because the issuer in the token has to match. Run browser tests on the host with the `localhost` setup, or run the browser in the same Compose network.
574
+
374
575
  ### Commands
375
576
 
376
577
  | Command | What it does |
377
578
  | --- | --- |
378
- | `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--allow-public`, `--json` |
579
+ | `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--https`, `--cert-dir`, `--coverage`, `--allow-public`, `--json` |
580
+ | `kinde-testkit stop` | Stop a running issuer. Options: `--url` |
581
+ | `kinde-testkit seed <file>` | Replace a running issuer's seed with a JSON, YAML, JavaScript or TypeScript file. Options: `--url`, `--json` |
582
+ | `kinde-testkit cert` | Write the local HTTPS certificate and print the `NODE_EXTRA_CA_CERTS` line. Options: `--dir` |
379
583
  | `kinde-testkit token` | Print a signed access token. Options: `--user`, `--org`, `--sub`, `--permissions`, `--roles`, `--expires-in`, `--invalid`, `--url`, `--json` |
380
584
  | `kinde-testkit users` | List seeded users |
381
585
  | `kinde-testkit organizations` | List seeded organizations |
382
586
  | `kinde-testkit token --m2m` | Print a machine-to-machine token. Options: `--client-id`, `--scope`, `--org`, `--permissions`, `--expires-in`, `--invalid` |
383
587
  | `kinde-testkit inspect [token]` | Decode a token and check it. Reads stdin when no token is given. Options: `--url`, `--json` |
588
+ | `kinde-testkit inspect --requests` | List the latest requests the issuer answered. `--tokens` lists the latest tokens it issued |
589
+ | `kinde-testkit coverage` | Show which authentication cases your tests covered. Options: `--url`, `--dir`, `--min`, `--clear`, `--json` |
384
590
  | `kinde-testkit doctor` | Check your app's Kinde settings against the issuer. Options: `--url`, `--env-file`, `--json` |
385
591
  | `kinde-testkit fail <path>` | Add a failure rule. Options: `--status`, `--delay`, `--hang`, `--times`, `--method`, `--list`, `--clear` |
386
- | `kinde-testkit reset` | Clear sign-in sessions, failure rules, webhook deliveries and endpoints added at runtime |
592
+ | `kinde-testkit reset` | Clear sign-in sessions, failure rules, webhook deliveries, endpoints added at runtime and Management API changes |
387
593
  | `kinde-testkit webhook <type>` | Send a signed webhook. Options: `--user`, `--org`, `--role`, `--permission`, `--data`, `--to`, `--duplicate`, `--invalid`, `--types`, `--deliveries` |
388
594
 
389
595
  Every command takes `--json` for CI scripts and coding agents.
@@ -425,12 +631,16 @@ import {
425
631
  - `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.
426
632
  - `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.
427
633
  - `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.
634
+ - `startKindeTestkit({ port, seed, audience, https, coverage })` runs the issuer in-process and returns `{ url, issuer, jwksUri, testkit, failures, webhooks, directory, coverage, activity, loadSeed(), reset(), close() }`. `seed` is an object or a file path. Pass `webhooks: { retryDelaysMs, timeoutMs }` to change webhook retries.
635
+ - `loadSeedFile(path)` reads a JSON, YAML, JavaScript or TypeScript seed. `readCoverageDirectory()`, `formatCoverageReport()` and `CoverageRecorder` are the functions behind `kinde-testkit coverage`.
636
+ - `appLoginUrl()`, `readSignInRequest()`, `signInForm()` and `resolveLocation()` are the steps `cy.kindeSignIn()` takes, for signing in with requests from another test runner.
429
637
  - `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`.
430
638
  - `createKindeToken(options)` signs with a shared default testkit whose issuer is `http://localhost:4400`, or `KINDE_TESTKIT_ISSUER` when set.
431
639
  - `principalFromClaims(claims)` turns verified claims into `{ type, subject, issuer, organization, roles, permissions }`. `type` is `"user"`, or `"machine"` for M2M tokens.
432
640
 
433
- From `kinde-testkit/vitest`: `useKindeTestkit()`, which also exposes `failures`, `webhooks` and `reset()`, and `kindeTest()`.
641
+ From `kinde-testkit/vitest` and `kinde-testkit/jest`: `useKindeTestkit()`, which also exposes `failures`, `webhooks`, `directory`, `coverage`, `activity`, `loadSeed()` and `reset()`, and `kindeTest()`.
642
+
643
+ From `kinde-testkit/cypress`: `setupKindeTestkit(on, config, { start, url })`. From `kinde-testkit/cypress/support`: the `cy.kinde*` commands and their types.
434
644
 
435
645
  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()`.
436
646
 
@@ -445,13 +655,20 @@ From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, t
445
655
  | `GET /oauth2/v2/user_profile` | Profile for the Bearer token's user |
446
656
  | `POST /oauth2/revoke` | Revokes a refresh token |
447
657
  | `GET /logout?redirect=<url>` | Signs out and redirects |
658
+ | `/api/v1/...` | Management API: users, organizations, members, roles and permissions |
659
+ | `GET /account_api/v1/...` | Account API: permissions, roles, feature flags, properties and entitlements for the token's user |
448
660
  | `POST /testkit/token` | Mints a token directly, used by `kinde-testkit token` |
449
661
  | `GET /testkit/users`, `/testkit/organizations`, `/testkit/memberships`, `/testkit/health` | Seed data and a health check |
450
662
  | `GET`, `POST`, `DELETE /testkit/failures`, `DELETE /testkit/failures/<id>` | List, add and remove failure rules |
451
663
  | `POST /testkit/webhooks` | Send a webhook and return the deliveries |
452
664
  | `GET /testkit/webhooks/deliveries`, `/testkit/webhooks/types` | Delivery log and the event types with built-in payloads |
453
665
  | `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 |
666
+ | `POST /testkit/reset` | Clear sign-in state, failure rules, webhook deliveries and Management API changes |
667
+ | `POST /testkit/seed` | Replace the seed with the JSON body |
668
+ | `POST /testkit/stop` | Stop the issuer |
669
+ | `GET`, `DELETE /testkit/coverage` | Read or clear the coverage report |
670
+ | `GET /testkit/requests`, `/testkit/tokens` | The latest requests answered and tokens issued |
671
+ | `GET /dashboard` | The dashboard |
455
672
 
456
673
  ## Token shape
457
674
 
@@ -492,20 +709,27 @@ ID tokens carry `amr`, `aud` (the client ID), `auth_time`, `email`, `email_verif
492
709
  | Switching the active organization | Implemented through `org_code` or the organization picker |
493
710
  | Authorization code flow with sign-in page, PKCE and `state` | Implemented |
494
711
  | Refresh tokens with rotation, revocation, logout and user profile | Implemented |
495
- | Vitest helper and Playwright fixture | Implemented |
712
+ | Vitest and Jest helpers, Playwright fixture, Cypress commands | Implemented. Jest runs in the test suite. Cypress's sign-in steps are tested against the Next.js SDK |
496
713
  | Accepted by `@kinde/jwt-validator` and the Next.js SDK's `validateToken` | Tested |
497
714
  | Sign-in, organization switching and sign-out through `@kinde-oss/kinde-auth-nextjs` | Tested in Chrome with Playwright |
498
715
  | Client credentials grant with Kinde's M2M token shape, seeded and org-scoped apps | Implemented |
499
716
  | Failure injection: error status, delay, hang, by path, method and count | Implemented, tested through the Next.js SDK |
500
717
  | `doctor`, `inspect` and `reset` commands | Implemented |
501
- | Management API and Account API | Not implemented |
718
+ | Management API: users, organizations, members, roles and permissions | Implemented, tested with `@kinde/management-api-js` |
719
+ | Account API: permissions, roles, feature flags, properties and entitlements | Implemented, tested with `@kinde/js-utils` |
720
+ | Seed files in JSON, YAML, JavaScript and TypeScript, replaced at runtime | Implemented |
721
+ | Dashboard, request and token log | Implemented |
722
+ | Authentication coverage report | Implemented |
723
+ | Docker image | Dockerfile in the repository |
724
+ | Passwords, MFA, social sign-in and SAML | Not emulated. The sign-in page signs in any seeded user or email directly |
725
+ | Kinde's hosted pages, such as the self-serve portal | Not emulated. `portal_link` returns a placeholder page |
502
726
  | 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 |
503
727
 
504
728
  ## Safety
505
729
 
506
730
  kinde-testkit signs a token for any identity you ask for, so it keeps to localhost:
507
731
 
508
- - The issuer binds to `127.0.0.1` and refuses any other interface unless you pass `--allow-public`.
732
+ - The issuer binds to `127.0.0.1` and refuses any other interface unless you pass `--allow-public`. The Docker image passes it, because the container's own network is where it listens. Publish the port to your machine only, as `-p 4400:4400` does.
509
733
  - It makes a new signing key every time it starts. Two running issuers never share a key.
510
734
  - It accepts any client ID, client secret and redirect URI, so it never needs your real app settings. That is only safe because it stays on localhost.
511
735
  - Codes, refresh tokens and users who sign in with an unseeded email live in memory and are gone when it stops.