kinde-testkit 0.1.0 → 0.2.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 +14 -0
- package/README.md +119 -8
- package/dist/cli.js +501 -37
- package/dist/index.cjs +497 -35
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +15 -8
- package/dist/index.d.ts +15 -8
- package/dist/index.js +499 -36
- package/dist/index.js.map +1 -1
- package/dist/playwright.d.ts +30 -0
- package/dist/playwright.js +68 -0
- package/dist/playwright.js.map +1 -0
- package/dist/vitest.d.ts +14 -7
- package/dist/vitest.js +499 -36
- package/dist/vitest.js.map +1 -1
- package/package.json +19 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
- Add the authorization code flow: a sign-in page at `/oauth2/auth` with seeded users, an organization picker, `org_code`, `login_hint`, `nonce`, `audience`, PKCE and `prompt=none`.
|
|
6
|
+
- Add `/oauth2/token` with the `authorization_code` and `refresh_token` grants. Refresh tokens rotate on every use.
|
|
7
|
+
- Add `/oauth2/v2/user_profile`, `/oauth2/revoke` and `/logout`.
|
|
8
|
+
- Add the `kinde-testkit/playwright` fixture with `signInAs`, `switchOrganization` and `signOut`.
|
|
9
|
+
- Add `examples/nextjs`, a Next.js app on `@kinde-oss/kinde-auth-nextjs` with Playwright tests that sign in through the testkit.
|
|
10
|
+
- Tokens issued through sign-in carry the requesting app's client ID in `azp` and the ID token's `aud`.
|
|
11
|
+
|
|
12
|
+
## 0.1.0
|
|
13
|
+
|
|
14
|
+
- First release: factories, the `scenario()` builder, Kinde-shaped access and ID tokens, 10 invalid token kinds, a local issuer with discovery and JWKS, seed files, the CLI and the Vitest helper.
|
package/README.md
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
# kinde-testkit
|
|
2
2
|
|
|
3
|
-
Test apps that use Kinde without a live Kinde environment. kinde-testkit
|
|
3
|
+
Test apps that use Kinde without a live Kinde environment. kinde-testkit runs a small issuer on localhost that does what your app needs from Kinde during a test: a sign-in page with test users, the OAuth endpoints Kinde's SDKs call, and access tokens that look like Kinde's, signed with a local key. Your app runs its real Kinde SDK and its real JWT checks against it.
|
|
4
|
+
|
|
5
|
+
There are two ways to use it:
|
|
6
|
+
|
|
7
|
+
- **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.
|
|
8
|
+
- **Browser tests:** point your app at the testkit, and Playwright signs in as any seeded user through your app's own login route.
|
|
4
9
|
|
|
5
10
|
## Why it exists
|
|
6
11
|
|
|
@@ -42,6 +47,22 @@ flowchart LR
|
|
|
42
47
|
|
|
43
48
|
Nothing is mocked inside your app. If the middleware forgets to check the audience, or a route forgets to check a permission, a test fails.
|
|
44
49
|
|
|
50
|
+
Browser sign-in follows the same flow your app uses with Kinde:
|
|
51
|
+
|
|
52
|
+
```mermaid
|
|
53
|
+
sequenceDiagram
|
|
54
|
+
participant T as Playwright test
|
|
55
|
+
participant A as Your app (Kinde SDK)
|
|
56
|
+
participant K as kinde-testkit
|
|
57
|
+
T->>A: open /api/auth/login
|
|
58
|
+
A->>K: redirect to /oauth2/auth
|
|
59
|
+
T->>K: pick admin@example.test
|
|
60
|
+
K->>A: redirect to callback with a code
|
|
61
|
+
A->>K: POST /oauth2/token (code)
|
|
62
|
+
K->>A: access, ID and refresh tokens
|
|
63
|
+
A->>T: signed-in page
|
|
64
|
+
```
|
|
65
|
+
|
|
45
66
|
## Install
|
|
46
67
|
|
|
47
68
|
```bash
|
|
@@ -90,6 +111,77 @@ describe("projects API", () => {
|
|
|
90
111
|
|
|
91
112
|
`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.
|
|
92
113
|
|
|
114
|
+
## Browser tests with Playwright
|
|
115
|
+
|
|
116
|
+
Start the testkit and your app from `playwright.config.ts`, with the app's Kinde settings pointed at the testkit:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { defineConfig } from "@playwright/test";
|
|
120
|
+
import type { KindeTestOptions } from "kinde-testkit/playwright";
|
|
121
|
+
|
|
122
|
+
export default defineConfig<KindeTestOptions>({
|
|
123
|
+
use: {
|
|
124
|
+
baseURL: "http://localhost:3000",
|
|
125
|
+
kindeIssuer: "http://localhost:4400",
|
|
126
|
+
},
|
|
127
|
+
webServer: [
|
|
128
|
+
{
|
|
129
|
+
command: "npx kinde-testkit start --port 4400",
|
|
130
|
+
url: "http://localhost:4400/testkit/health",
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
command: "npm run dev",
|
|
134
|
+
url: "http://localhost:3000",
|
|
135
|
+
env: {
|
|
136
|
+
KINDE_ISSUER_URL: "http://localhost:4400",
|
|
137
|
+
KINDE_CLIENT_ID: "kinde_testkit_example",
|
|
138
|
+
KINDE_CLIENT_SECRET: "testkitexampleclientsecret0000000000000000",
|
|
139
|
+
KINDE_SITE_URL: "http://localhost:3000",
|
|
140
|
+
KINDE_POST_LOGIN_REDIRECT_URL: "http://localhost:3000",
|
|
141
|
+
KINDE_POST_LOGOUT_REDIRECT_URL: "http://localhost:3000",
|
|
142
|
+
},
|
|
143
|
+
},
|
|
144
|
+
],
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`kinde-testkit start` loads `kinde-testkit.json` from the folder it runs in, so the seeded users are ready before the first test. The testkit accepts any client ID and secret. Kinde's Next.js SDK checks the secret's format, so use 40 to 60 letters and digits.
|
|
149
|
+
|
|
150
|
+
Then write tests with the `kinde` fixture:
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
import { expect, test } from "kinde-testkit/playwright";
|
|
154
|
+
|
|
155
|
+
test("a viewer cannot delete projects", async ({ page, kinde }) => {
|
|
156
|
+
await kinde.signInAs("viewer@example.test");
|
|
157
|
+
await page.goto("/projects");
|
|
158
|
+
await expect(page.getByRole("button", { name: /Delete/ })).toHaveCount(0);
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
test("a consultant switches organization", async ({ page, kinde }) => {
|
|
162
|
+
await kinde.signInAs("consultant@example.test", { org: "org_acme" });
|
|
163
|
+
await kinde.switchOrganization("org_globex");
|
|
164
|
+
await page.goto("/projects");
|
|
165
|
+
await expect(page.getByRole("heading", { name: "org_globex projects" })).toBeVisible();
|
|
166
|
+
});
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
| Fixture method | What it does |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `kinde.signInAs(email, { org })` | Opens your app's login route, signs in on the testkit page and waits until the app has the session |
|
|
172
|
+
| `kinde.switchOrganization(code)` | Signs the same user in again with another active organization |
|
|
173
|
+
| `kinde.signOut()` | Opens your app's logout route |
|
|
174
|
+
|
|
175
|
+
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.
|
|
176
|
+
|
|
177
|
+
A user with more than one organization needs `{ org }`, otherwise the fixture stops with an error that names the user. Signing in to an organization the user does not belong to also fails, the same way Kinde refuses it.
|
|
178
|
+
|
|
179
|
+
[`examples/nextjs`](examples/nextjs) is a working Next.js app on `@kinde-oss/kinde-auth-nextjs` with these tests.
|
|
180
|
+
|
|
181
|
+
### The sign-in page
|
|
182
|
+
|
|
183
|
+
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`.
|
|
184
|
+
|
|
93
185
|
## With Kinde's SDKs
|
|
94
186
|
|
|
95
187
|
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.
|
|
@@ -100,7 +192,7 @@ For the Next.js SDK, set the issuer to the testkit during tests:
|
|
|
100
192
|
KINDE_ISSUER_URL=http://localhost:4400
|
|
101
193
|
```
|
|
102
194
|
|
|
103
|
-
The SDK accepts a plain `http://localhost` issuer. Its `validateToken` accepts kinde-testkit tokens and rejects the wrong-issuer, tampered, unknown-key and unsigned kinds. It does not reject expired tokens, because the SDK handles expiry by refreshing the session.
|
|
195
|
+
The SDK accepts a plain `http://localhost` issuer. Its login, callback, refresh, logout and session-ending routes all work against the testkit. Its `validateToken` accepts kinde-testkit tokens and rejects the wrong-issuer, tampered, unknown-key and unsigned kinds. It does not reject expired tokens, because the SDK handles expiry by refreshing the session.
|
|
104
196
|
|
|
105
197
|
## Run the issuer from the command line
|
|
106
198
|
|
|
@@ -203,6 +295,22 @@ import {
|
|
|
203
295
|
- `createKindeToken(options)` signs with a shared default testkit whose issuer is `http://localhost:4400`, or `KINDE_TESTKIT_ISSUER` when set.
|
|
204
296
|
- `principalFromClaims(claims)` turns verified claims into `{ subject, issuer, organization, roles, permissions }`.
|
|
205
297
|
|
|
298
|
+
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()`.
|
|
299
|
+
|
|
300
|
+
## Endpoints
|
|
301
|
+
|
|
302
|
+
| Endpoint | What it does |
|
|
303
|
+
| --- | --- |
|
|
304
|
+
| `GET /.well-known/openid-configuration` | OIDC discovery |
|
|
305
|
+
| `GET /.well-known/jwks`, `/.well-known/jwks.json` | Public signing key |
|
|
306
|
+
| `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 |
|
|
307
|
+
| `POST /oauth2/token` | `authorization_code` and `refresh_token` grants. Client credentials in the body or with HTTP Basic. Refresh tokens rotate on every use |
|
|
308
|
+
| `GET /oauth2/v2/user_profile` | Profile for the Bearer token's user |
|
|
309
|
+
| `POST /oauth2/revoke` | Revokes a refresh token |
|
|
310
|
+
| `GET /logout?redirect=<url>` | Signs out and redirects |
|
|
311
|
+
| `POST /testkit/token` | Mints a token directly, used by `kinde-testkit token` |
|
|
312
|
+
| `GET /testkit/users`, `/testkit/organizations`, `/testkit/memberships`, `/testkit/health` | Seed data and a health check |
|
|
313
|
+
|
|
206
314
|
## Token shape
|
|
207
315
|
|
|
208
316
|
Access tokens use the same claims as a real Kinde access token:
|
|
@@ -236,17 +344,18 @@ ID tokens carry `amr`, `aud` (the client ID), `auth_time`, `email`, `email_verif
|
|
|
236
344
|
| OIDC discovery document | Implemented |
|
|
237
345
|
| JWKS with one RS256 key, at `/.well-known/jwks` and `/.well-known/jwks.json` | Implemented |
|
|
238
346
|
| Access tokens with `org_code`, `permissions`, `roles`, `scp` | Implemented |
|
|
239
|
-
| ID tokens | Implemented
|
|
347
|
+
| ID tokens, with `nonce` | Implemented |
|
|
240
348
|
| Invalid token kinds | Implemented, 10 kinds |
|
|
241
349
|
| Seeded users, organizations and memberships | Implemented |
|
|
242
|
-
| Switching the active organization | Implemented
|
|
243
|
-
|
|
|
350
|
+
| Switching the active organization | Implemented through `org_code` or the organization picker |
|
|
351
|
+
| Authorization code flow with sign-in page, PKCE and `state` | Implemented |
|
|
352
|
+
| Refresh tokens with rotation, revocation, logout and user profile | Implemented |
|
|
353
|
+
| Vitest helper and Playwright fixture | Implemented |
|
|
244
354
|
| Accepted by `@kinde/jwt-validator` and the Next.js SDK's `validateToken` | Tested |
|
|
245
|
-
|
|
|
246
|
-
|
|
|
355
|
+
| Sign-in, organization switching and sign-out through `@kinde-oss/kinde-auth-nextjs` | Tested in Chrome with Playwright |
|
|
356
|
+
| Client credentials (machine-to-machine) grant | Not implemented |
|
|
247
357
|
| Management API and Account API | Not implemented |
|
|
248
358
|
| Webhooks | Not implemented |
|
|
249
|
-
| Playwright fixtures | Not implemented |
|
|
250
359
|
|
|
251
360
|
## Safety
|
|
252
361
|
|
|
@@ -254,6 +363,8 @@ kinde-testkit signs a token for any identity you ask for, so it keeps to localho
|
|
|
254
363
|
|
|
255
364
|
- The issuer binds to `127.0.0.1` and refuses any other interface unless you pass `--allow-public`.
|
|
256
365
|
- It makes a new signing key every time it starts. Two running issuers never share a key.
|
|
366
|
+
- 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.
|
|
367
|
+
- Codes, refresh tokens and users who sign in with an unseeded email live in memory and are gone when it stops.
|
|
257
368
|
- It never reads Kinde credentials, and its tokens can never pass verification against Kinde's real JWKS.
|
|
258
369
|
- If you set the issuer to an `https://*.kinde.com` address, it prints a warning, because that is almost always a mistake.
|
|
259
370
|
|