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,579 @@
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 UserMeta {
288
+ providedId: string | null;
289
+ isSuspended: boolean;
290
+ isPasswordResetRequested: boolean;
291
+ createdOn: string;
292
+ totalSignIns: number;
293
+ lastSignedIn: string | null;
294
+ }
295
+ interface OrganizationMeta {
296
+ externalId: string | null;
297
+ handle: string;
298
+ createdOn: string;
299
+ isAllowRegistrations: boolean;
300
+ }
301
+ declare class Directory {
302
+ readonly seed: ResolvedSeed;
303
+ private readonly userMeta;
304
+ private readonly orgMeta;
305
+ private snapshot;
306
+ constructor(seed: ResolvedSeed);
307
+ restore(): void;
308
+ /** Replaces the whole seed with another resolved seed, and makes it the state reset() returns to. */
309
+ load(next: ResolvedSeed): void;
310
+ user(id: string): KindeUser | undefined;
311
+ meta(user: KindeUser): UserMeta;
312
+ isSuspended(userId: string): boolean;
313
+ recordSignIn(user: KindeUser, organizationCode: string | null): void;
314
+ createUser(input: {
315
+ email?: string | null;
316
+ givenName?: string | null;
317
+ familyName?: string | null;
318
+ picture?: string | null;
319
+ providedId?: string | null;
320
+ }): KindeUser;
321
+ deleteUser(id: string): boolean;
322
+ organization(code: string): KindeOrganization | undefined;
323
+ orgInfo(org: KindeOrganization): OrganizationMeta;
324
+ createOrganization(input: {
325
+ name: string;
326
+ externalId?: string | null;
327
+ handle?: string | null;
328
+ }): KindeOrganization;
329
+ deleteOrganization(code: string): boolean;
330
+ membership(userId: string, organizationCode: string): KindeMembership | undefined;
331
+ addMembership(userId: string, organizationCode: string, roles?: string[], permissions?: string[]): KindeMembership;
332
+ removeMembership(userId: string, organizationCode: string): boolean;
333
+ role(idOrKey: string): SeedRole | undefined;
334
+ permission(idOrKey: string): SeedPermission | undefined;
335
+ ensureRole(key: string, extra?: Partial<Omit<SeedRole, "id" | "key">>): SeedRole;
336
+ ensurePermission(key: string, extra?: Partial<Omit<SeedPermission, "id" | "key">>): SeedPermission;
337
+ deleteRole(id: string): SeedRole | undefined;
338
+ deletePermission(id: string): SeedPermission | undefined;
339
+ }
340
+
341
+ interface FailureRule {
342
+ path: string;
343
+ method?: string;
344
+ status?: number;
345
+ delayMs?: number;
346
+ hang?: boolean;
347
+ times?: number;
348
+ retryAfter?: number;
349
+ }
350
+ interface ActiveFailure {
351
+ id: string;
352
+ path: string;
353
+ method: string | null;
354
+ status: number | null;
355
+ delayMs: number;
356
+ hang: boolean;
357
+ remaining: number | null;
358
+ retryAfter: number;
359
+ hits: number;
360
+ }
361
+ declare class FailureInjector {
362
+ private rules;
363
+ private nextId;
364
+ add(rule: FailureRule): ActiveFailure;
365
+ remove(id: string): boolean;
366
+ clear(): void;
367
+ list(): ActiveFailure[];
368
+ take(method: string, path: string): ActiveFailure | null;
369
+ }
370
+
371
+ 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"];
372
+ 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"];
373
+ type WebhookInvalidKind = "bad-signature" | "unknown-key" | "unsigned" | "stale";
374
+ type WebhookSource = "admin" | "api" | "user";
375
+ interface WebhookEndpointInput {
376
+ url: string;
377
+ events?: string[];
378
+ }
379
+ interface WebhookEndpoint {
380
+ id: string;
381
+ url: string;
382
+ events: string[] | null;
383
+ }
384
+ interface SendWebhookOptions {
385
+ type: string;
386
+ data?: Record<string, unknown>;
387
+ user?: string;
388
+ organization?: string;
389
+ role?: string;
390
+ permission?: string;
391
+ source?: WebhookSource;
392
+ ipAddress?: string;
393
+ to?: string;
394
+ duplicate?: number;
395
+ delayMs?: number;
396
+ invalid?: WebhookInvalidKind;
397
+ }
398
+ interface WebhookAttempt {
399
+ attempt: number;
400
+ status: number | null;
401
+ error: string | null;
402
+ durationMs: number;
403
+ }
404
+ interface WebhookDelivery {
405
+ webhookId: string;
406
+ eventId: string;
407
+ type: string;
408
+ url: string;
409
+ copy: number;
410
+ delivered: boolean;
411
+ attempts: WebhookAttempt[];
412
+ payload: Record<string, unknown>;
413
+ }
414
+ interface WebhookOptions {
415
+ retryDelaysMs?: number[];
416
+ timeoutMs?: number;
417
+ }
418
+ declare class WebhookDispatcher {
419
+ private readonly testkit;
420
+ private readonly seed;
421
+ private endpoints;
422
+ private seededEndpoints;
423
+ private log;
424
+ private nextEndpoint;
425
+ private readonly retryDelaysMs;
426
+ private readonly timeoutMs;
427
+ /** Set by the server to record coverage. */
428
+ observe: (id: string) => void;
429
+ constructor(testkit: KindeTestkit, seed: ResolvedSeed, endpoints?: WebhookEndpointInput[], options?: WebhookOptions);
430
+ addEndpoint(input: WebhookEndpointInput): WebhookEndpoint;
431
+ /** Replaces the endpoints that came from the seed, as when a new seed is loaded. */
432
+ replaceSeededEndpoints(endpoints: WebhookEndpointInput[]): void;
433
+ removeEndpoint(id: string): boolean;
434
+ listEndpoints(): WebhookEndpoint[];
435
+ deliveries(): WebhookDelivery[];
436
+ reset(): void;
437
+ buildEvent(options: SendWebhookOptions): Record<string, unknown>;
438
+ send(options: SendWebhookOptions): Promise<WebhookDelivery[]>;
439
+ private deliver;
440
+ private buildData;
441
+ emit(type: string, data: Record<string, unknown>, source?: WebhookSource): void;
442
+ userEventData(user: KindeUser): Record<string, unknown>;
443
+ emitForUser(type: "user.created" | "user.authenticated", user: KindeUser): void;
444
+ private userData;
445
+ private userPayload;
446
+ private organizationData;
447
+ private namedData;
448
+ private requireUser;
449
+ }
450
+
451
+ interface RequestEntry {
452
+ at: string;
453
+ method: string;
454
+ path: string;
455
+ status: number;
456
+ durationMs: number;
457
+ injected: boolean;
458
+ }
459
+ interface TokenEntry {
460
+ at: string;
461
+ kind: "access" | "m2m" | "id";
462
+ subject: string | null;
463
+ organization: string | null;
464
+ permissions: string[];
465
+ roles: string[];
466
+ invalid: InvalidTokenKind | null;
467
+ expiresAt: string | null;
468
+ claims: Record<string, unknown>;
469
+ token: string;
470
+ }
471
+ /** Keeps the latest requests and tokens for the dashboard and `kinde-testkit inspect --requests`. */
472
+ declare class ActivityLog {
473
+ private requestLog;
474
+ private tokenLog;
475
+ request(entry: Omit<RequestEntry, "at" | "path"> & {
476
+ path: string;
477
+ query: URLSearchParams;
478
+ }): void;
479
+ token(kind: TokenEntry["kind"], claims: Record<string, unknown>, invalid: InvalidTokenKind | undefined, token: string): void;
480
+ requests(): RequestEntry[];
481
+ tokens(): TokenEntry[];
482
+ reset(): void;
483
+ }
484
+
485
+ interface CoverageItem {
486
+ id: string;
487
+ label: string;
488
+ hint: string;
489
+ }
490
+ interface CoverageGroup {
491
+ name: string;
492
+ items: CoverageItem[];
493
+ }
494
+ declare const COVERAGE_GROUPS: CoverageGroup[];
495
+ interface CoverageGroupResult {
496
+ name: string;
497
+ covered: number;
498
+ total: number;
499
+ items: Array<CoverageItem & {
500
+ covered: boolean;
501
+ count: number;
502
+ }>;
503
+ }
504
+ interface CoverageReport {
505
+ covered: number;
506
+ total: number;
507
+ groups: CoverageGroupResult[];
508
+ }
509
+ interface CoverageSnapshot {
510
+ version: 1;
511
+ hits: Record<string, number>;
512
+ }
513
+ /** Records which authentication scenarios the testkit produced during a test run. */
514
+ declare class CoverageRecorder {
515
+ private hits;
516
+ private userOrganizations;
517
+ private organizationUsers;
518
+ private organizationPermissionSets;
519
+ hit(id: string): void;
520
+ /** Called for every access token the testkit signs. */
521
+ observeAccessToken(payload: Record<string, unknown>, invalid: InvalidTokenKind | undefined): void;
522
+ report(): CoverageReport;
523
+ snapshot(): CoverageSnapshot;
524
+ reset(): void;
525
+ /** Writes this run's snapshot to the coverage folder, so separate test files can be merged. */
526
+ write(directory?: string): string;
527
+ }
528
+ declare const DEFAULT_COVERAGE_DIRECTORY: string;
529
+ declare function buildReport(hits: Record<string, number>): CoverageReport;
530
+ declare function mergeSnapshots(snapshots: CoverageSnapshot[]): Record<string, number>;
531
+ /** Reads and merges every snapshot in the coverage folder. */
532
+ declare function readCoverageDirectory(directory?: string): {
533
+ files: number;
534
+ report: CoverageReport;
535
+ };
536
+ declare function clearCoverageDirectory(directory?: string): void;
537
+ declare function formatCoverageReport(report: CoverageReport, options?: {
538
+ missing?: boolean;
539
+ }): string;
540
+
541
+ interface StartKindeTestkitOptions {
542
+ port?: number;
543
+ host?: string;
544
+ issuer?: string;
545
+ audience?: string | string[];
546
+ clientId?: string;
547
+ /** A seed object, or the path of a JSON, YAML, JavaScript or TypeScript seed file. */
548
+ seed?: TestkitSeed | string;
549
+ allowPublic?: boolean;
550
+ /** Write this run's authentication coverage to a folder when the testkit closes. */
551
+ coverage?: boolean | {
552
+ directory?: string;
553
+ };
554
+ webhooks?: WebhookOptions;
555
+ https?: boolean | {
556
+ certDirectory?: string;
557
+ };
558
+ }
559
+ interface RunningKindeTestkit {
560
+ url: string;
561
+ issuer: string;
562
+ discoveryUrl: string;
563
+ jwksUri: string;
564
+ testkit: KindeTestkit;
565
+ seed: ResolvedSeed;
566
+ failures: FailureInjector;
567
+ webhooks: WebhookDispatcher;
568
+ directory: Directory;
569
+ certificatePath: string | null;
570
+ coverage: CoverageRecorder;
571
+ activity: ActivityLog;
572
+ /** Replaces the seed while the issuer runs. reset() returns to the new seed. */
573
+ loadSeed(seed: TestkitSeed): void;
574
+ reset(): void;
575
+ close(): Promise<void>;
576
+ }
577
+ declare function startKindeTestkit(options?: StartKindeTestkitOptions): Promise<RunningKindeTestkit>;
578
+
579
+ export { type WebhookSource as $, type AuthenticatedScenario as A, BILLING_EVENT_TYPES as B, COVERAGE_GROUPS as C, DEFAULT_AUTH_METHODS as D, type KindeTokenOptions as E, FailureInjector as F, type ResolvedSeed as G, type RunningKindeTestkit as H, INVALID_TOKEN_KINDS as I, type ScenarioTokenOverrides as J, type KindeOrganization as K, type SendWebhookOptions as L, type M2MTokenOptions as M, type TokenEntry as N, type TokenObserver as O, type WebhookAttempt as P, type WebhookDelivery as Q, type RequestEntry as R, type StartKindeTestkitOptions as S, type TestkitSeed as T, type UnauthenticatedScenario as U, WebhookDispatcher as V, WEBHOOK_EVENT_TYPES as W, type WebhookEndpoint as X, type WebhookEndpointInput as Y, type WebhookInvalidKind as Z, type WebhookOptions as _, type KindeUser as a, buildReport as a0, clearCoverageDirectory as a1, createKindeToken as a2, formatCoverageReport as a3, getDefaultTestkit as a4, mergeSnapshots as a5, principalFromClaims as a6, readCoverageDirectory as a7, resolveSeed as a8, seedScenario as a9, startKindeTestkit as aa, type KindeMembership as b, type KindeRole as c, type Scenario as d, type ActiveFailure as e, ActivityLog as f, type CoverageGroup as g, type CoverageGroupResult as h, type CoverageItem as i, CoverageRecorder as j, type CoverageReport as k, type CoverageSnapshot as l, DEFAULT_CLIENT_ID as m, DEFAULT_COVERAGE_DIRECTORY as n, DEFAULT_ISSUER as o, DEFAULT_M2M_CLIENT_ID as p, DEFAULT_SCOPES as q, Directory as r, type Duration as s, type FailureRule as t, type IdTokenOptions as u, type InvalidTokenKind as v, type KindeApplication as w, type KindePrincipal as x, KindeTestkit as y, type KindeTestkitOptions as z };