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 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 gives you test users and organizations, access tokens that look like Kinde's and are signed with a local key, and a small issuer on localhost that publishes the matching JWKS. Your app checks those tokens with the same JWT verification code it runs in production.
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. Signing in through the SDK's login route needs the authorization code flow, which this release does not include yet.
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 through the library |
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, one token per organization |
243
- | Vitest helper | Implemented |
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
- | Authorization code flow and login page | Not implemented. `/oauth2/auth` and `/oauth2/token` return 501 |
246
- | Refresh tokens and logout | Not implemented |
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