kinde-testkit 0.5.0 → 0.6.1

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.
@@ -0,0 +1,397 @@
1
+ import { JWTPayload, JWK } from 'jose';
2
+
3
+ interface KindeUser {
4
+ id: string;
5
+ email: string | null;
6
+ emailVerified: boolean;
7
+ givenName: string | null;
8
+ familyName: string | null;
9
+ picture: string | null;
10
+ claims: Record<string, unknown>;
11
+ }
12
+ interface KindeOrganization {
13
+ code: string;
14
+ name: string;
15
+ metadata: Record<string, unknown>;
16
+ }
17
+ interface KindeRole {
18
+ id: string;
19
+ key: string;
20
+ name: string;
21
+ }
22
+ interface KindeApplication {
23
+ clientId: string;
24
+ clientSecret: string | null;
25
+ name: string;
26
+ organizationCode: string | null;
27
+ scopes: string[] | null;
28
+ permissions: string[] | null;
29
+ audience: string[] | null;
30
+ }
31
+ interface KindeMembership {
32
+ userId: string;
33
+ organizationCode: string;
34
+ roles: string[];
35
+ permissions: string[];
36
+ }
37
+ interface AuthenticatedScenario {
38
+ kind: "authenticated";
39
+ user: KindeUser;
40
+ organization: KindeOrganization | null;
41
+ roles: string[];
42
+ permissions: string[];
43
+ claims: Record<string, unknown>;
44
+ }
45
+ interface UnauthenticatedScenario {
46
+ kind: "unauthenticated";
47
+ }
48
+ type Scenario = AuthenticatedScenario | UnauthenticatedScenario;
49
+ interface KindePrincipal {
50
+ type: "user" | "machine";
51
+ subject: string;
52
+ issuer: string;
53
+ organization: {
54
+ code: string;
55
+ } | null;
56
+ roles: string[];
57
+ permissions: string[];
58
+ claims: Record<string, unknown>;
59
+ }
60
+ type InvalidTokenKind = "expired" | "wrong-issuer" | "wrong-audience" | "missing-subject" | "missing-organization" | "missing-permissions" | "future-iat" | "bad-signature" | "unknown-key" | "unsigned";
61
+ type Duration = number | `${number}${"s" | "m" | "h" | "d"}`;
62
+ interface KindeTokenOptions {
63
+ subject?: string;
64
+ organizationCode?: string | null;
65
+ permissions?: string[];
66
+ roles?: Array<string | KindeRole>;
67
+ scopes?: string[];
68
+ featureFlags?: Record<string, {
69
+ t: "b" | "s" | "i";
70
+ v: boolean | string | number;
71
+ }>;
72
+ claims?: Record<string, unknown>;
73
+ authMethods?: string[];
74
+ authTime?: number;
75
+ clientId?: string;
76
+ audience?: string[];
77
+ expiresIn?: Duration;
78
+ invalid?: InvalidTokenKind;
79
+ }
80
+
81
+ declare const DEFAULT_ISSUER = "http://localhost:4400";
82
+ declare const DEFAULT_CLIENT_ID = "kinde_testkit_client";
83
+ declare const DEFAULT_M2M_CLIENT_ID = "kinde_testkit_m2m";
84
+ declare const DEFAULT_SCOPES: string[];
85
+ declare const DEFAULT_AUTH_METHODS: string[];
86
+ declare const INVALID_TOKEN_KINDS: readonly InvalidTokenKind[];
87
+ interface KindeTestkitOptions {
88
+ issuer?: string;
89
+ audience?: string | string[];
90
+ clientId?: string;
91
+ accessTokenExpiresIn?: Duration;
92
+ idTokenExpiresIn?: Duration;
93
+ now?: () => number;
94
+ }
95
+ type ScenarioTokenOverrides = Pick<KindeTokenOptions, "expiresIn" | "invalid" | "scopes" | "featureFlags" | "claims" | "authMethods" | "authTime" | "clientId" | "audience">;
96
+ interface M2MTokenOptions {
97
+ clientId?: string;
98
+ organizationCode?: string | null;
99
+ scopes?: string[];
100
+ grantedScopes?: string[];
101
+ audience?: string[];
102
+ permissions?: string[];
103
+ claims?: Record<string, unknown>;
104
+ expiresIn?: Duration;
105
+ invalid?: InvalidTokenKind;
106
+ }
107
+ interface IdTokenOptions {
108
+ expiresIn?: Duration;
109
+ authMethods?: string[];
110
+ authTime?: number;
111
+ clientId?: string;
112
+ nonce?: string;
113
+ }
114
+ /** Receives every token the testkit signs, for coverage and the dashboard. */
115
+ interface TokenObserver {
116
+ accessToken?(payload: Record<string, unknown>, invalid: InvalidTokenKind | undefined, token: string): void;
117
+ idToken?(payload: Record<string, unknown>, token: string): void;
118
+ anonymous?(): void;
119
+ }
120
+ declare class KindeTestkit {
121
+ private observers;
122
+ /** Calls the observer for every token signed from now on. Returns a function that stops it. */
123
+ observe(observer: TokenObserver): () => void;
124
+ private signAccess;
125
+ readonly issuer: string;
126
+ readonly audience: string[];
127
+ readonly clientId: string;
128
+ private readonly accessTokenExpiresIn;
129
+ private readonly idTokenExpiresIn;
130
+ private readonly clock;
131
+ private readonly signingKey;
132
+ private strangerKey;
133
+ static create(options?: KindeTestkitOptions): Promise<KindeTestkit>;
134
+ private constructor();
135
+ get jwksUri(): string;
136
+ get keyId(): string;
137
+ get accessTokenLifetime(): number;
138
+ verify(token: string): Promise<JWTPayload>;
139
+ jwks(): {
140
+ keys: JWK[];
141
+ };
142
+ token(options?: KindeTokenOptions): Promise<string>;
143
+ m2mToken(options?: M2MTokenOptions): Promise<string>;
144
+ tokenFor(scenario: Scenario, overrides?: ScenarioTokenOverrides): Promise<string | null>;
145
+ idTokenFor(scenario: Scenario, options?: IdTokenOptions): Promise<string | null>;
146
+ headersFor(scenario: Scenario, overrides?: ScenarioTokenOverrides): Promise<Record<string, string>>;
147
+ principalFor(scenario: Scenario): KindePrincipal | null;
148
+ signPayload(payload: Record<string, unknown>, invalid?: "bad-signature" | "unknown-key" | "unsigned"): Promise<string>;
149
+ private sign;
150
+ private stranger;
151
+ }
152
+ declare function principalFromClaims(claims: Record<string, unknown>): KindePrincipal;
153
+ declare function getDefaultTestkit(): Promise<KindeTestkit>;
154
+ declare function createKindeToken(options?: KindeTokenOptions): Promise<string>;
155
+
156
+ interface TestkitSeed {
157
+ issuer?: string;
158
+ audience?: string | string[];
159
+ clientId?: string;
160
+ users?: Array<{
161
+ id: string;
162
+ email?: string | null;
163
+ emailVerified?: boolean;
164
+ givenName?: string | null;
165
+ familyName?: string | null;
166
+ picture?: string | null;
167
+ claims?: Record<string, unknown>;
168
+ properties?: Record<string, string | number | boolean>;
169
+ }>;
170
+ organizations?: Array<{
171
+ code: string;
172
+ name?: string;
173
+ metadata?: Record<string, unknown>;
174
+ }>;
175
+ memberships?: Array<{
176
+ user: string;
177
+ organization: string;
178
+ roles?: string[];
179
+ permissions?: string[];
180
+ }>;
181
+ webhooks?: Array<{
182
+ url: string;
183
+ events?: string[];
184
+ }>;
185
+ roles?: Array<{
186
+ key: string;
187
+ name?: string;
188
+ description?: string;
189
+ permissions?: string[];
190
+ isDefault?: boolean;
191
+ }>;
192
+ featureFlags?: Array<{
193
+ key: string;
194
+ name?: string;
195
+ type?: "boolean" | "string" | "integer";
196
+ value: boolean | string | number;
197
+ organizations?: Record<string, boolean | string | number>;
198
+ }>;
199
+ plans?: Array<{
200
+ key: string;
201
+ name?: string;
202
+ subscribers?: string[];
203
+ entitlements?: Array<{
204
+ featureKey: string;
205
+ featureName?: string;
206
+ priceName?: string;
207
+ fixedCharge?: number | null;
208
+ unitAmount?: number | null;
209
+ limitMax?: number | null;
210
+ limitMin?: number | null;
211
+ }>;
212
+ }>;
213
+ permissions?: Array<{
214
+ key: string;
215
+ name?: string;
216
+ description?: string;
217
+ }>;
218
+ applications?: Array<{
219
+ clientId: string;
220
+ clientSecret?: string;
221
+ name?: string;
222
+ organization?: string;
223
+ scopes?: string[];
224
+ permissions?: string[];
225
+ audience?: string | string[];
226
+ }>;
227
+ }
228
+ interface ResolvedSeed {
229
+ users: KindeUser[];
230
+ organizations: KindeOrganization[];
231
+ memberships: KindeMembership[];
232
+ applications: KindeApplication[];
233
+ webhooks: Array<{
234
+ url: string;
235
+ events?: string[];
236
+ }>;
237
+ roles: SeedRole[];
238
+ permissions: SeedPermission[];
239
+ featureFlags: SeedFeatureFlag[];
240
+ plans: SeedPlan[];
241
+ userProperties: Record<string, Record<string, string | number | boolean>>;
242
+ }
243
+ interface SeedFeatureFlag {
244
+ id: string;
245
+ key: string;
246
+ name: string;
247
+ type: "boolean" | "string" | "integer";
248
+ value: boolean | string | number;
249
+ organizations: Record<string, boolean | string | number>;
250
+ }
251
+ interface SeedPlan {
252
+ key: string;
253
+ name: string;
254
+ subscribers: string[];
255
+ subscribedOn: string;
256
+ entitlements: Array<{
257
+ id: string;
258
+ featureKey: string;
259
+ featureName: string;
260
+ priceName: string;
261
+ fixedCharge: number | null;
262
+ unitAmount: number | null;
263
+ limitMax: number | null;
264
+ limitMin: number | null;
265
+ }>;
266
+ }
267
+ interface SeedRole {
268
+ id: string;
269
+ key: string;
270
+ name: string;
271
+ description: string | null;
272
+ isDefault: boolean;
273
+ permissions: string[];
274
+ }
275
+ interface SeedPermission {
276
+ id: string;
277
+ key: string;
278
+ name: string;
279
+ description: string | null;
280
+ }
281
+ declare function resolveSeed(input: unknown): ResolvedSeed;
282
+ declare function seedScenario(seed: ResolvedSeed, ref: {
283
+ user: string;
284
+ organization?: string | null;
285
+ }): AuthenticatedScenario;
286
+
287
+ interface FailureRule {
288
+ path: string;
289
+ method?: string;
290
+ status?: number;
291
+ delayMs?: number;
292
+ hang?: boolean;
293
+ times?: number;
294
+ retryAfter?: number;
295
+ }
296
+ interface ActiveFailure {
297
+ id: string;
298
+ path: string;
299
+ method: string | null;
300
+ status: number | null;
301
+ delayMs: number;
302
+ hang: boolean;
303
+ remaining: number | null;
304
+ retryAfter: number;
305
+ hits: number;
306
+ }
307
+ declare class FailureInjector {
308
+ private rules;
309
+ private nextId;
310
+ add(rule: FailureRule): ActiveFailure;
311
+ remove(id: string): boolean;
312
+ clear(): void;
313
+ list(): ActiveFailure[];
314
+ take(method: string, path: string): ActiveFailure | null;
315
+ }
316
+
317
+ declare const WEBHOOK_EVENT_TYPES: readonly ["user.created", "user.updated", "user.deleted", "user.authenticated", "user.authentication_failed", "organization.created", "organization.updated", "organization.deleted", "role.created", "role.updated", "role.deleted", "permission.created", "permission.updated", "permission.deleted", "subscriber.created", "access_request.created"];
318
+ declare const BILLING_EVENT_TYPES: readonly ["customer.agreement_cancelled", "customer.agreement_created", "customer.invoice_overdue", "customer.meter_usage_updated", "customer.payment_failed", "customer.payment_succeeded", "customer.plan_assigned", "customer.plan_changed"];
319
+ type WebhookInvalidKind = "bad-signature" | "unknown-key" | "unsigned" | "stale";
320
+ type WebhookSource = "admin" | "api" | "user";
321
+ interface WebhookEndpointInput {
322
+ url: string;
323
+ events?: string[];
324
+ }
325
+ interface WebhookEndpoint {
326
+ id: string;
327
+ url: string;
328
+ events: string[] | null;
329
+ }
330
+ interface SendWebhookOptions {
331
+ type: string;
332
+ data?: Record<string, unknown>;
333
+ user?: string;
334
+ organization?: string;
335
+ role?: string;
336
+ permission?: string;
337
+ source?: WebhookSource;
338
+ ipAddress?: string;
339
+ to?: string;
340
+ duplicate?: number;
341
+ delayMs?: number;
342
+ invalid?: WebhookInvalidKind;
343
+ }
344
+ interface WebhookAttempt {
345
+ attempt: number;
346
+ status: number | null;
347
+ error: string | null;
348
+ durationMs: number;
349
+ }
350
+ interface WebhookDelivery {
351
+ webhookId: string;
352
+ eventId: string;
353
+ type: string;
354
+ url: string;
355
+ copy: number;
356
+ delivered: boolean;
357
+ attempts: WebhookAttempt[];
358
+ payload: Record<string, unknown>;
359
+ }
360
+ interface WebhookOptions {
361
+ retryDelaysMs?: number[];
362
+ timeoutMs?: number;
363
+ }
364
+ declare class WebhookDispatcher {
365
+ private readonly testkit;
366
+ private readonly seed;
367
+ private endpoints;
368
+ private seededEndpoints;
369
+ private log;
370
+ private nextEndpoint;
371
+ private readonly retryDelaysMs;
372
+ private readonly timeoutMs;
373
+ /** Set by the server to record coverage. */
374
+ observe: (id: string) => void;
375
+ constructor(testkit: KindeTestkit, seed: ResolvedSeed, endpoints?: WebhookEndpointInput[], options?: WebhookOptions);
376
+ addEndpoint(input: WebhookEndpointInput): WebhookEndpoint;
377
+ /** Replaces the endpoints that came from the seed, as when a new seed is loaded. */
378
+ replaceSeededEndpoints(endpoints: WebhookEndpointInput[]): void;
379
+ removeEndpoint(id: string): boolean;
380
+ listEndpoints(): WebhookEndpoint[];
381
+ deliveries(): WebhookDelivery[];
382
+ reset(): void;
383
+ buildEvent(options: SendWebhookOptions): Record<string, unknown>;
384
+ send(options: SendWebhookOptions): Promise<WebhookDelivery[]>;
385
+ private deliver;
386
+ private buildData;
387
+ emit(type: string, data: Record<string, unknown>, source?: WebhookSource): void;
388
+ userEventData(user: KindeUser): Record<string, unknown>;
389
+ emitForUser(type: "user.created" | "user.authenticated", user: KindeUser): void;
390
+ private userData;
391
+ private userPayload;
392
+ private organizationData;
393
+ private namedData;
394
+ private requireUser;
395
+ }
396
+
397
+ export { type AuthenticatedScenario as A, BILLING_EVENT_TYPES as B, type WebhookOptions as C, DEFAULT_AUTH_METHODS as D, type WebhookSource as E, FailureInjector as F, createKindeToken as G, getDefaultTestkit as H, INVALID_TOKEN_KINDS as I, principalFromClaims as J, type KindeOrganization as K, resolveSeed as L, type M2MTokenOptions as M, seedScenario as N, type SeedRole as O, type SeedPermission as P, type ResolvedSeed as R, type Scenario as S, type TestkitSeed as T, type UnauthenticatedScenario as U, WEBHOOK_EVENT_TYPES as W, type KindeUser as a, type KindeMembership as b, type KindeRole as c, type ActiveFailure as d, DEFAULT_CLIENT_ID as e, DEFAULT_ISSUER as f, DEFAULT_M2M_CLIENT_ID as g, DEFAULT_SCOPES as h, type Duration as i, type FailureRule as j, type IdTokenOptions as k, type InvalidTokenKind as l, type KindeApplication as m, type KindePrincipal as n, KindeTestkit as o, type KindeTestkitOptions as p, type KindeTokenOptions as q, type ScenarioTokenOverrides as r, type SendWebhookOptions as s, type TokenObserver as t, type WebhookAttempt as u, type WebhookDelivery as v, WebhookDispatcher as w, type WebhookEndpoint as x, type WebhookEndpointInput as y, type WebhookInvalidKind as z };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kinde-testkit",
3
- "version": "0.5.0",
3
+ "version": "0.6.1",
4
4
  "description": "Test Kinde-authenticated apps offline: a local issuer with a real sign-in flow, Kinde-shaped tokens, reusable auth scenarios, and Vitest and Playwright helpers.",
5
5
  "license": "MIT",
6
6
  "author": "Shola Jegede <jegedeshola@gmail.com>",
@@ -17,7 +17,10 @@
17
17
  "vitest",
18
18
  "auth",
19
19
  "playwright",
20
- "oauth"
20
+ "oauth",
21
+ "jest",
22
+ "cypress",
23
+ "emulator"
21
24
  ],
22
25
  "type": "module",
23
26
  "engines": {
@@ -52,12 +55,38 @@
52
55
  "default": "./dist/vitest.js"
53
56
  }
54
57
  },
58
+ "./jest": {
59
+ "import": {
60
+ "types": "./dist/jest.d.ts",
61
+ "default": "./dist/jest.js"
62
+ },
63
+ "require": {
64
+ "types": "./dist/jest.d.cts",
65
+ "default": "./dist/jest.cjs"
66
+ }
67
+ },
55
68
  "./playwright": {
56
69
  "import": {
57
70
  "types": "./dist/playwright.d.ts",
58
71
  "default": "./dist/playwright.js"
59
72
  }
60
73
  },
74
+ "./cypress": {
75
+ "import": {
76
+ "types": "./dist/cypress.d.ts",
77
+ "default": "./dist/cypress.js"
78
+ },
79
+ "require": {
80
+ "types": "./dist/cypress.d.cts",
81
+ "default": "./dist/cypress.cjs"
82
+ }
83
+ },
84
+ "./cypress/support": {
85
+ "import": {
86
+ "types": "./dist/cypress-support.d.ts",
87
+ "default": "./dist/cypress-support.js"
88
+ }
89
+ },
61
90
  "./package.json": "./package.json"
62
91
  },
63
92
  "scripts": {
@@ -65,10 +94,12 @@
65
94
  "typecheck": "tsc --noEmit",
66
95
  "test": "vitest run",
67
96
  "test:watch": "vitest",
68
- "prepublishOnly": "npm run typecheck && npm test && npm run build"
97
+ "prepublishOnly": "npm run typecheck && npm test && npm run build",
98
+ "test:contract": "vitest run test/contract"
69
99
  },
70
100
  "dependencies": {
71
- "jose": "^6.2.17"
101
+ "jose": "^6.2.17",
102
+ "yaml": "^2.9.1"
72
103
  },
73
104
  "peerDependencies": {
74
105
  "@playwright/test": ">=1.40",
@@ -89,6 +120,7 @@
89
120
  "@kinde/webhooks": "^1.3.3",
90
121
  "@playwright/test": "^1.65.1",
91
122
  "@types/node": "^22.10.0",
123
+ "jest": "^30.5.2",
92
124
  "tsup": "^8.3.5",
93
125
  "typescript": "^5.7.0",
94
126
  "vitest": "^5.1.0"