kinde-testkit 0.2.2 → 0.3.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 +8 -0
- package/README.md +118 -5
- package/dist/cli.js +601 -11
- package/dist/index.cjs +417 -11
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +95 -2
- package/dist/index.d.ts +95 -2
- package/dist/index.js +412 -11
- package/dist/index.js.map +1 -1
- package/dist/playwright.d.ts +27 -1
- package/dist/playwright.js +32 -7
- package/dist/playwright.js.map +1 -1
- package/dist/vitest.d.ts +54 -0
- package/dist/vitest.js +242 -11
- package/dist/vitest.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
- 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`.
|
|
6
|
+
- Add failure injection: make any endpoint answer with an error status, wait, or hang, matched by path, prefix, method and count. Use it from Vitest (`kinde.failures`), Playwright (`kinde.injectFailure()`), the CLI (`kinde-testkit fail`) or HTTP (`/testkit/failures`).
|
|
7
|
+
- Add `kinde-testkit doctor`, which checks an app's Kinde settings against the running issuer, `kinde-testkit inspect`, which decodes a token and explains what is wrong with it, and `kinde-testkit reset`.
|
|
8
|
+
- `principalFromClaims()` now returns `type`, which is `"machine"` for M2M tokens, with the client ID as `subject`.
|
|
9
|
+
- The Next.js example adds outage tests that run through the real SDK.
|
|
10
|
+
|
|
3
11
|
## 0.2.2
|
|
4
12
|
|
|
5
13
|
- Show the README diagrams as images, so they display on npm as well as GitHub.
|
package/README.md
CHANGED
|
@@ -9,6 +9,8 @@ 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.
|
|
13
|
+
|
|
12
14
|
## Why it exists
|
|
13
15
|
|
|
14
16
|
Kinde's testing guides start with a test environment, a test user with a password, and a client ID and secret in `.env`. Every test then goes through a real sign-in. That works for a few smoke tests. It gets slow and hard to run in CI once you want to test what your app does with each kind of user, such as:
|
|
@@ -143,6 +145,8 @@ test("a consultant switches organization", async ({ page, kinde }) => {
|
|
|
143
145
|
| `kinde.signInAs(email, { org })` | Opens your app's login route, signs in on the testkit page and waits until the app has the session |
|
|
144
146
|
| `kinde.switchOrganization(code)` | Signs the same user in again with another active organization |
|
|
145
147
|
| `kinde.signOut()` | Opens your app's logout route |
|
|
148
|
+
| `kinde.injectFailure(rule)` | Makes a testkit endpoint fail, slow down or hang. Removed when the test ends |
|
|
149
|
+
| `kinde.clearFailures()` | Removes the failures this test added |
|
|
146
150
|
|
|
147
151
|
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.
|
|
148
152
|
|
|
@@ -154,6 +158,100 @@ A user with more than one organization needs `{ org }`, otherwise the fixture st
|
|
|
154
158
|
|
|
155
159
|
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`.
|
|
156
160
|
|
|
161
|
+
## Machine-to-machine tokens
|
|
162
|
+
|
|
163
|
+
Backend services and AI agents authenticate with Kinde through the client credentials grant. kinde-testkit answers it at `/oauth2/token` with tokens in Kinde's M2M shape: `gty: ["client_credentials"]`, `azp` set to the client ID, `scope`, `scp` and `v: "2"`, and no `sub`. Org-scoped apps also get `org_code`.
|
|
164
|
+
|
|
165
|
+
Seed the apps your services use:
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"organizations": [{ "code": "org_acme" }],
|
|
170
|
+
"applications": [
|
|
171
|
+
{ "clientId": "billing_worker", "clientSecret": "billing_secret", "scopes": ["read:invoices", "write:invoices"] },
|
|
172
|
+
{ "clientId": "acme_agent", "organization": "org_acme", "permissions": ["read:users"], "audience": "https://api.example.test" }
|
|
173
|
+
]
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
A seeded app with a `clientSecret` must send that secret. A seeded app with `scopes` is granted only the requested scopes it has, so `scope` holds what was granted and `scp` holds what was asked for, as in Kinde. A client ID that is not seeded gets a token with whatever it asks for.
|
|
178
|
+
|
|
179
|
+
Your service fetches a token the same way it does from Kinde:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
curl -s -X POST http://localhost:4400/oauth2/token \
|
|
183
|
+
-d grant_type=client_credentials -d client_id=acme_agent -d client_secret=x \
|
|
184
|
+
-d audience=https://api.example.test -d scope=read:users
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
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
|
+
## Testing outages
|
|
190
|
+
|
|
191
|
+
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:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
// Vitest, in the same process
|
|
195
|
+
kinde.failures.add({ path: "/oauth2/token", status: 503, times: 1 });
|
|
196
|
+
|
|
197
|
+
// Playwright, removed again when the test ends
|
|
198
|
+
await kinde.injectFailure({ path: "/.well-known/jwks.json", delayMs: 3000 });
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
kinde-testkit fail /oauth2/token --status 429 --times 3
|
|
203
|
+
kinde-testkit fail --list
|
|
204
|
+
kinde-testkit fail --clear
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
| Rule field | What it does |
|
|
208
|
+
| --- | --- |
|
|
209
|
+
| `path` | An exact path such as `/oauth2/token`, or a prefix such as `/oauth2/*` |
|
|
210
|
+
| `method` | Only match this HTTP method |
|
|
211
|
+
| `status` | Answer with this status. 429 and 503 also send `Retry-After` |
|
|
212
|
+
| `delayMs` | Wait this long first, up to 60 seconds |
|
|
213
|
+
| `hang` | Never answer, so the client hits its own timeout |
|
|
214
|
+
| `times` | Apply to the next n matching requests, then remove the rule |
|
|
215
|
+
|
|
216
|
+
Failure rules apply to the whole issuer, so every test using it sees them. In Playwright, put outage tests in their own project that runs after the others. [`examples/nextjs`](examples/nextjs) has an `outage` project that takes the token endpoint down during sign-in, then slows it down. `/testkit/` control endpoints never fail.
|
|
217
|
+
|
|
218
|
+
`kinde-testkit reset` (or `POST /testkit/reset`, or `kinde.reset()` in Vitest) clears sign-in codes, refresh tokens, users who signed in with an unseeded email, and failure rules.
|
|
219
|
+
|
|
220
|
+
## Check your setup
|
|
221
|
+
|
|
222
|
+
`kinde-testkit doctor` reads `.env`, `.env.local`, `.env.test` and `.env.test.local`, plus any `KINDE_` variables in your shell, and checks them against the running issuer:
|
|
223
|
+
|
|
224
|
+
```
|
|
225
|
+
✓ Issuer running http://localhost:4400 answers, issuer http://localhost:4400.
|
|
226
|
+
✓ Discovery The discovery document names the same issuer.
|
|
227
|
+
✓ JWKS 1 RS256 signing key at /.well-known/jwks.json.
|
|
228
|
+
✓ Seed 3 seeded users.
|
|
229
|
+
✗ KINDE_ISSUER_URL https://acme.kinde.com is a real Kinde domain. Tests would sign in against Kinde, not the testkit.
|
|
230
|
+
✓ KINDE_CLIENT_ID Set. The testkit accepts any client ID.
|
|
231
|
+
✗ KINDE_CLIENT_SECRET The Next.js SDK only accepts 40 to 60 letters and digits.
|
|
232
|
+
✓ KINDE_SITE_URL http://localhost:3000.
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
It exits with code 1 when a check fails, so it can run before your test suite in CI.
|
|
236
|
+
|
|
237
|
+
`kinde-testkit inspect <token>` decodes any Kinde or testkit token and says what is wrong with it. Pipe a token in, or paste one. With `--url`, it also checks the issuer and verifies the signature:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
kinde-testkit token --user admin@example.test --invalid expired | kinde-testkit inspect --url http://localhost:4400
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
```
|
|
244
|
+
Access token
|
|
245
|
+
|
|
246
|
+
Subject kp_admin
|
|
247
|
+
Organization org_acme
|
|
248
|
+
Permissions ["projects:read"]
|
|
249
|
+
|
|
250
|
+
✓ Algorithm RS256, the algorithm Kinde signs with.
|
|
251
|
+
✗ Expiry Expired 1h 0m ago.
|
|
252
|
+
✓ Signature Verified against http://localhost:4400/.well-known/jwks.json.
|
|
253
|
+
```
|
|
254
|
+
|
|
157
255
|
## With Kinde's SDKs
|
|
158
256
|
|
|
159
257
|
Kinde's JavaScript SDKs check tokens with `@kinde/jwt-validator`, which fetches keys from `<issuer>/.well-known/jwks.json` and then compares `iss` with the issuer you configured. kinde-testkit serves the same path, and its test suite runs that validator against every token kind.
|
|
@@ -209,6 +307,9 @@ When `kinde-testkit.json` exists in the current folder, `start` loads it. Pass `
|
|
|
209
307
|
{ "user": "kp_admin", "organization": "org_acme", "roles": ["admin"], "permissions": ["projects:read", "projects:delete"] },
|
|
210
308
|
{ "user": "kp_consultant", "organization": "org_acme", "roles": ["viewer"], "permissions": ["projects:read"] },
|
|
211
309
|
{ "user": "kp_consultant", "organization": "org_globex", "roles": ["admin"], "permissions": ["projects:delete"] }
|
|
310
|
+
],
|
|
311
|
+
"applications": [
|
|
312
|
+
{ "clientId": "acme_agent", "organization": "org_acme", "scopes": ["read:users"] }
|
|
212
313
|
]
|
|
213
314
|
}
|
|
214
315
|
```
|
|
@@ -223,6 +324,11 @@ A token for a seeded user takes its roles and permissions from the membership in
|
|
|
223
324
|
| `kinde-testkit token` | Print a signed access token. Options: `--user`, `--org`, `--sub`, `--permissions`, `--roles`, `--expires-in`, `--invalid`, `--url`, `--json` |
|
|
224
325
|
| `kinde-testkit users` | List seeded users |
|
|
225
326
|
| `kinde-testkit organizations` | List seeded organizations |
|
|
327
|
+
| `kinde-testkit token --m2m` | Print a machine-to-machine token. Options: `--client-id`, `--scope`, `--org`, `--permissions`, `--expires-in`, `--invalid` |
|
|
328
|
+
| `kinde-testkit inspect [token]` | Decode a token and check it. Reads stdin when no token is given. Options: `--url`, `--json` |
|
|
329
|
+
| `kinde-testkit doctor` | Check your app's Kinde settings against the issuer. Options: `--url`, `--env-file`, `--json` |
|
|
330
|
+
| `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 |
|
|
226
332
|
|
|
227
333
|
Every command takes `--json` for CI scripts and coding agents.
|
|
228
334
|
|
|
@@ -262,10 +368,13 @@ import {
|
|
|
262
368
|
|
|
263
369
|
- `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.
|
|
264
370
|
- `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.
|
|
265
|
-
- `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)`, `headersFor(scenario)`, `principalFor(scenario)` and `jwks()`.
|
|
266
|
-
- `startKindeTestkit({ port, seed, audience })` runs the issuer in-process and returns `{ url, issuer, jwksUri, testkit, close() }`.
|
|
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() }`.
|
|
373
|
+
- `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`.
|
|
267
374
|
- `createKindeToken(options)` signs with a shared default testkit whose issuer is `http://localhost:4400`, or `KINDE_TESTKIT_ISSUER` when set.
|
|
268
|
-
- `principalFromClaims(claims)` turns verified claims into `{ subject, issuer, organization, roles, permissions }`.
|
|
375
|
+
- `principalFromClaims(claims)` turns verified claims into `{ type, subject, issuer, organization, roles, permissions }`. `type` is `"user"`, or `"machine"` for M2M tokens.
|
|
376
|
+
|
|
377
|
+
From `kinde-testkit/vitest`: `useKindeTestkit()`, which also exposes `failures` and `reset()`, and `kindeTest()`.
|
|
269
378
|
|
|
270
379
|
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()`.
|
|
271
380
|
|
|
@@ -276,12 +385,14 @@ From `kinde-testkit/playwright`: `test` and `expect` with the `kinde` fixture, t
|
|
|
276
385
|
| `GET /.well-known/openid-configuration` | OIDC discovery |
|
|
277
386
|
| `GET /.well-known/jwks`, `/.well-known/jwks.json` | Public signing key |
|
|
278
387
|
| `GET /oauth2/auth` | Sign-in page. Takes `client_id`, `redirect_uri`, `response_type=code`, `state`, `scope`, `nonce`, `audience`, `org_code`, `login_hint`, `prompt=none` and PKCE |
|
|
279
|
-
| `POST /oauth2/token` | `authorization_code` and `
|
|
388
|
+
| `POST /oauth2/token` | `authorization_code`, `refresh_token` and `client_credentials` grants. Client credentials in the body or with HTTP Basic. Refresh tokens rotate on every use |
|
|
280
389
|
| `GET /oauth2/v2/user_profile` | Profile for the Bearer token's user |
|
|
281
390
|
| `POST /oauth2/revoke` | Revokes a refresh token |
|
|
282
391
|
| `GET /logout?redirect=<url>` | Signs out and redirects |
|
|
283
392
|
| `POST /testkit/token` | Mints a token directly, used by `kinde-testkit token` |
|
|
284
393
|
| `GET /testkit/users`, `/testkit/organizations`, `/testkit/memberships`, `/testkit/health` | Seed data and a health check |
|
|
394
|
+
| `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 |
|
|
285
396
|
|
|
286
397
|
## Token shape
|
|
287
398
|
|
|
@@ -325,7 +436,9 @@ ID tokens carry `amr`, `aud` (the client ID), `auth_time`, `email`, `email_verif
|
|
|
325
436
|
| Vitest helper and Playwright fixture | Implemented |
|
|
326
437
|
| Accepted by `@kinde/jwt-validator` and the Next.js SDK's `validateToken` | Tested |
|
|
327
438
|
| Sign-in, organization switching and sign-out through `@kinde-oss/kinde-auth-nextjs` | Tested in Chrome with Playwright |
|
|
328
|
-
| Client credentials
|
|
439
|
+
| Client credentials grant with Kinde's M2M token shape, seeded and org-scoped apps | Implemented |
|
|
440
|
+
| Failure injection: error status, delay, hang, by path, method and count | Implemented, tested through the Next.js SDK |
|
|
441
|
+
| `doctor`, `inspect` and `reset` commands | Implemented |
|
|
329
442
|
| Management API and Account API | Not implemented |
|
|
330
443
|
| Webhooks | Not implemented |
|
|
331
444
|
|