kinde-testkit 0.4.0 → 0.5.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,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.0
4
+
5
+ - 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`.
6
+ - 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.
7
+ - 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.
8
+ - 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.
9
+ - Suspended users cannot sign in, and `reset()` restores the seed after API changes.
10
+
3
11
  ## 0.4.0
4
12
 
5
13
  - 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
@@ -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, 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, 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
 
@@ -238,6 +238,49 @@ These options test the hard parts of a webhook handler:
238
238
 
239
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
240
 
241
+ ## Management API and Account API
242
+
243
+ 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.
244
+
245
+ 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:
246
+
247
+ | Area | Routes |
248
+ | --- | --- |
249
+ | Users | List, filter by ID or email, get, create, update (including `is_suspended`), delete |
250
+ | Organizations | List, get, create, update, delete |
251
+ | Members | List, add with roles, remove |
252
+ | Member roles and permissions | List, grant, remove |
253
+ | Roles and permissions | List, get, create, delete, and list a role's permissions |
254
+
255
+ 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.
256
+
257
+ Kinde's official client, `@kinde/management-api-js`, forces `https://`. Start the testkit with HTTPS and run your code with the certificate it prints:
258
+
259
+ ```ts
260
+ const kinde = useKindeTestkit({ seed, https: true });
261
+ ```
262
+
263
+ ```bash
264
+ npx kinde-testkit start --https
265
+ NODE_EXTRA_CA_CERTS=.kinde-testkit/localhost-cert.pem npm test
266
+ ```
267
+
268
+ 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.
269
+
270
+ 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:
271
+
272
+ ```json
273
+ {
274
+ "users": [{ "id": "kp_admin", "email": "admin@example.test", "properties": { "team": "platform" } }],
275
+ "roles": [{ "key": "admin", "name": "Admin", "permissions": ["projects:read", "projects:delete"] }],
276
+ "memberships": [{ "user": "kp_admin", "organization": "org_acme", "roles": ["admin"] }],
277
+ "featureFlags": [{ "key": "new_editor", "value": false, "organizations": { "org_acme": true } }],
278
+ "plans": [{ "key": "pro", "subscribers": ["org_acme"], "entitlements": [{ "featureKey": "seats", "limitMax": 10 }] }]
279
+ }
280
+ ```
281
+
282
+ 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.
283
+
241
284
  ## Testing outages
242
285
 
243
286
  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:
@@ -375,7 +418,8 @@ A token for a seeded user takes its roles and permissions from the membership in
375
418
 
376
419
  | Command | What it does |
377
420
  | --- | --- |
378
- | `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--allow-public`, `--json` |
421
+ | `kinde-testkit start` | Start the issuer. Options: `--port`, `--host`, `--issuer`, `--audience`, `--client-id`, `--seed`, `--webhook`, `--https`, `--cert-dir`, `--allow-public`, `--json` |
422
+ | `kinde-testkit cert` | Write the local HTTPS certificate and print the `NODE_EXTRA_CA_CERTS` line. Options: `--dir` |
379
423
  | `kinde-testkit token` | Print a signed access token. Options: `--user`, `--org`, `--sub`, `--permissions`, `--roles`, `--expires-in`, `--invalid`, `--url`, `--json` |
380
424
  | `kinde-testkit users` | List seeded users |
381
425
  | `kinde-testkit organizations` | List seeded organizations |
@@ -445,6 +489,8 @@ From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, t
445
489
  | `GET /oauth2/v2/user_profile` | Profile for the Bearer token's user |
446
490
  | `POST /oauth2/revoke` | Revokes a refresh token |
447
491
  | `GET /logout?redirect=<url>` | Signs out and redirects |
492
+ | `/api/v1/...` | Management API: users, organizations, members, roles and permissions |
493
+ | `GET /account_api/v1/...` | Account API: permissions, roles, feature flags, properties and entitlements for the token's user |
448
494
  | `POST /testkit/token` | Mints a token directly, used by `kinde-testkit token` |
449
495
  | `GET /testkit/users`, `/testkit/organizations`, `/testkit/memberships`, `/testkit/health` | Seed data and a health check |
450
496
  | `GET`, `POST`, `DELETE /testkit/failures`, `DELETE /testkit/failures/<id>` | List, add and remove failure rules |