kinde-testkit 0.4.0 → 0.6.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/dist/index.d.ts CHANGED
@@ -156,7 +156,17 @@ interface IdTokenOptions {
156
156
  clientId?: string;
157
157
  nonce?: string;
158
158
  }
159
+ /** Receives every token the testkit signs, for coverage and the dashboard. */
160
+ interface TokenObserver {
161
+ accessToken?(payload: Record<string, unknown>, invalid: InvalidTokenKind | undefined, token: string): void;
162
+ idToken?(payload: Record<string, unknown>, token: string): void;
163
+ anonymous?(): void;
164
+ }
159
165
  declare class KindeTestkit {
166
+ private observers;
167
+ /** Calls the observer for every token signed from now on. Returns a function that stops it. */
168
+ observe(observer: TokenObserver): () => void;
169
+ private signAccess;
160
170
  readonly issuer: string;
161
171
  readonly audience: string[];
162
172
  readonly clientId: string;
@@ -200,6 +210,7 @@ interface TestkitSeed {
200
210
  familyName?: string | null;
201
211
  picture?: string | null;
202
212
  claims?: Record<string, unknown>;
213
+ properties?: Record<string, string | number | boolean>;
203
214
  }>;
204
215
  organizations?: Array<{
205
216
  code: string;
@@ -216,6 +227,39 @@ interface TestkitSeed {
216
227
  url: string;
217
228
  events?: string[];
218
229
  }>;
230
+ roles?: Array<{
231
+ key: string;
232
+ name?: string;
233
+ description?: string;
234
+ permissions?: string[];
235
+ isDefault?: boolean;
236
+ }>;
237
+ featureFlags?: Array<{
238
+ key: string;
239
+ name?: string;
240
+ type?: "boolean" | "string" | "integer";
241
+ value: boolean | string | number;
242
+ organizations?: Record<string, boolean | string | number>;
243
+ }>;
244
+ plans?: Array<{
245
+ key: string;
246
+ name?: string;
247
+ subscribers?: string[];
248
+ entitlements?: Array<{
249
+ featureKey: string;
250
+ featureName?: string;
251
+ priceName?: string;
252
+ fixedCharge?: number | null;
253
+ unitAmount?: number | null;
254
+ limitMax?: number | null;
255
+ limitMin?: number | null;
256
+ }>;
257
+ }>;
258
+ permissions?: Array<{
259
+ key: string;
260
+ name?: string;
261
+ description?: string;
262
+ }>;
219
263
  applications?: Array<{
220
264
  clientId: string;
221
265
  clientSecret?: string;
@@ -235,6 +279,49 @@ interface ResolvedSeed {
235
279
  url: string;
236
280
  events?: string[];
237
281
  }>;
282
+ roles: SeedRole[];
283
+ permissions: SeedPermission[];
284
+ featureFlags: SeedFeatureFlag[];
285
+ plans: SeedPlan[];
286
+ userProperties: Record<string, Record<string, string | number | boolean>>;
287
+ }
288
+ interface SeedFeatureFlag {
289
+ id: string;
290
+ key: string;
291
+ name: string;
292
+ type: "boolean" | "string" | "integer";
293
+ value: boolean | string | number;
294
+ organizations: Record<string, boolean | string | number>;
295
+ }
296
+ interface SeedPlan {
297
+ key: string;
298
+ name: string;
299
+ subscribers: string[];
300
+ subscribedOn: string;
301
+ entitlements: Array<{
302
+ id: string;
303
+ featureKey: string;
304
+ featureName: string;
305
+ priceName: string;
306
+ fixedCharge: number | null;
307
+ unitAmount: number | null;
308
+ limitMax: number | null;
309
+ limitMin: number | null;
310
+ }>;
311
+ }
312
+ interface SeedRole {
313
+ id: string;
314
+ key: string;
315
+ name: string;
316
+ description: string | null;
317
+ isDefault: boolean;
318
+ permissions: string[];
319
+ }
320
+ interface SeedPermission {
321
+ id: string;
322
+ key: string;
323
+ name: string;
324
+ description: string | null;
238
325
  }
239
326
  declare function resolveSeed(input: unknown): ResolvedSeed;
240
327
  declare function seedScenario(seed: ResolvedSeed, ref: {
@@ -242,6 +329,60 @@ declare function seedScenario(seed: ResolvedSeed, ref: {
242
329
  organization?: string | null;
243
330
  }): AuthenticatedScenario;
244
331
 
332
+ interface UserMeta {
333
+ providedId: string | null;
334
+ isSuspended: boolean;
335
+ isPasswordResetRequested: boolean;
336
+ createdOn: string;
337
+ totalSignIns: number;
338
+ lastSignedIn: string | null;
339
+ }
340
+ interface OrganizationMeta {
341
+ externalId: string | null;
342
+ handle: string;
343
+ createdOn: string;
344
+ isAllowRegistrations: boolean;
345
+ }
346
+ declare class Directory {
347
+ readonly seed: ResolvedSeed;
348
+ private readonly userMeta;
349
+ private readonly orgMeta;
350
+ private snapshot;
351
+ constructor(seed: ResolvedSeed);
352
+ restore(): void;
353
+ /** Replaces the whole seed with another resolved seed, and makes it the state reset() returns to. */
354
+ load(next: ResolvedSeed): void;
355
+ user(id: string): KindeUser | undefined;
356
+ meta(user: KindeUser): UserMeta;
357
+ isSuspended(userId: string): boolean;
358
+ recordSignIn(user: KindeUser, organizationCode: string | null): void;
359
+ createUser(input: {
360
+ email?: string | null;
361
+ givenName?: string | null;
362
+ familyName?: string | null;
363
+ picture?: string | null;
364
+ providedId?: string | null;
365
+ }): KindeUser;
366
+ deleteUser(id: string): boolean;
367
+ organization(code: string): KindeOrganization | undefined;
368
+ orgInfo(org: KindeOrganization): OrganizationMeta;
369
+ createOrganization(input: {
370
+ name: string;
371
+ externalId?: string | null;
372
+ handle?: string | null;
373
+ }): KindeOrganization;
374
+ deleteOrganization(code: string): boolean;
375
+ membership(userId: string, organizationCode: string): KindeMembership | undefined;
376
+ addMembership(userId: string, organizationCode: string, roles?: string[], permissions?: string[]): KindeMembership;
377
+ removeMembership(userId: string, organizationCode: string): boolean;
378
+ role(idOrKey: string): SeedRole | undefined;
379
+ permission(idOrKey: string): SeedPermission | undefined;
380
+ ensureRole(key: string, extra?: Partial<Omit<SeedRole, "id" | "key">>): SeedRole;
381
+ ensurePermission(key: string, extra?: Partial<Omit<SeedPermission, "id" | "key">>): SeedPermission;
382
+ deleteRole(id: string): SeedRole | undefined;
383
+ deletePermission(id: string): SeedPermission | undefined;
384
+ }
385
+
245
386
  interface FailureRule {
246
387
  path: string;
247
388
  method?: string;
@@ -328,8 +469,12 @@ declare class WebhookDispatcher {
328
469
  private nextEndpoint;
329
470
  private readonly retryDelaysMs;
330
471
  private readonly timeoutMs;
472
+ /** Set by the server to record coverage. */
473
+ observe: (id: string) => void;
331
474
  constructor(testkit: KindeTestkit, seed: ResolvedSeed, endpoints?: WebhookEndpointInput[], options?: WebhookOptions);
332
475
  addEndpoint(input: WebhookEndpointInput): WebhookEndpoint;
476
+ /** Replaces the endpoints that came from the seed, as when a new seed is loaded. */
477
+ replaceSeededEndpoints(endpoints: WebhookEndpointInput[]): void;
333
478
  removeEndpoint(id: string): boolean;
334
479
  listEndpoints(): WebhookEndpoint[];
335
480
  deliveries(): WebhookDelivery[];
@@ -338,6 +483,8 @@ declare class WebhookDispatcher {
338
483
  send(options: SendWebhookOptions): Promise<WebhookDelivery[]>;
339
484
  private deliver;
340
485
  private buildData;
486
+ emit(type: string, data: Record<string, unknown>, source?: WebhookSource): void;
487
+ userEventData(user: KindeUser): Record<string, unknown>;
341
488
  emitForUser(type: "user.created" | "user.authenticated", user: KindeUser): void;
342
489
  private userData;
343
490
  private userPayload;
@@ -346,15 +493,113 @@ declare class WebhookDispatcher {
346
493
  private requireUser;
347
494
  }
348
495
 
496
+ interface RequestEntry {
497
+ at: string;
498
+ method: string;
499
+ path: string;
500
+ status: number;
501
+ durationMs: number;
502
+ injected: boolean;
503
+ }
504
+ interface TokenEntry {
505
+ at: string;
506
+ kind: "access" | "m2m" | "id";
507
+ subject: string | null;
508
+ organization: string | null;
509
+ permissions: string[];
510
+ roles: string[];
511
+ invalid: InvalidTokenKind | null;
512
+ expiresAt: string | null;
513
+ claims: Record<string, unknown>;
514
+ token: string;
515
+ }
516
+ /** Keeps the latest requests and tokens for the dashboard and `kinde-testkit inspect --requests`. */
517
+ declare class ActivityLog {
518
+ private requestLog;
519
+ private tokenLog;
520
+ request(entry: Omit<RequestEntry, "at" | "path"> & {
521
+ path: string;
522
+ query: URLSearchParams;
523
+ }): void;
524
+ token(kind: TokenEntry["kind"], claims: Record<string, unknown>, invalid: InvalidTokenKind | undefined, token: string): void;
525
+ requests(): RequestEntry[];
526
+ tokens(): TokenEntry[];
527
+ reset(): void;
528
+ }
529
+
530
+ interface CoverageItem {
531
+ id: string;
532
+ label: string;
533
+ hint: string;
534
+ }
535
+ interface CoverageGroup {
536
+ name: string;
537
+ items: CoverageItem[];
538
+ }
539
+ declare const COVERAGE_GROUPS: CoverageGroup[];
540
+ interface CoverageGroupResult {
541
+ name: string;
542
+ covered: number;
543
+ total: number;
544
+ items: Array<CoverageItem & {
545
+ covered: boolean;
546
+ count: number;
547
+ }>;
548
+ }
549
+ interface CoverageReport {
550
+ covered: number;
551
+ total: number;
552
+ groups: CoverageGroupResult[];
553
+ }
554
+ interface CoverageSnapshot {
555
+ version: 1;
556
+ hits: Record<string, number>;
557
+ }
558
+ /** Records which authentication scenarios the testkit produced during a test run. */
559
+ declare class CoverageRecorder {
560
+ private hits;
561
+ private userOrganizations;
562
+ private organizationUsers;
563
+ private organizationPermissionSets;
564
+ hit(id: string): void;
565
+ /** Called for every access token the testkit signs. */
566
+ observeAccessToken(payload: Record<string, unknown>, invalid: InvalidTokenKind | undefined): void;
567
+ report(): CoverageReport;
568
+ snapshot(): CoverageSnapshot;
569
+ reset(): void;
570
+ /** Writes this run's snapshot to the coverage folder, so separate test files can be merged. */
571
+ write(directory?: string): string;
572
+ }
573
+ declare const DEFAULT_COVERAGE_DIRECTORY: string;
574
+ declare function buildReport(hits: Record<string, number>): CoverageReport;
575
+ declare function mergeSnapshots(snapshots: CoverageSnapshot[]): Record<string, number>;
576
+ /** Reads and merges every snapshot in the coverage folder. */
577
+ declare function readCoverageDirectory(directory?: string): {
578
+ files: number;
579
+ report: CoverageReport;
580
+ };
581
+ declare function clearCoverageDirectory(directory?: string): void;
582
+ declare function formatCoverageReport(report: CoverageReport, options?: {
583
+ missing?: boolean;
584
+ }): string;
585
+
349
586
  interface StartKindeTestkitOptions {
350
587
  port?: number;
351
588
  host?: string;
352
589
  issuer?: string;
353
590
  audience?: string | string[];
354
591
  clientId?: string;
355
- seed?: TestkitSeed;
592
+ /** A seed object, or the path of a JSON, YAML, JavaScript or TypeScript seed file. */
593
+ seed?: TestkitSeed | string;
356
594
  allowPublic?: boolean;
595
+ /** Write this run's authentication coverage to a folder when the testkit closes. */
596
+ coverage?: boolean | {
597
+ directory?: string;
598
+ };
357
599
  webhooks?: WebhookOptions;
600
+ https?: boolean | {
601
+ certDirectory?: string;
602
+ };
358
603
  }
359
604
  interface RunningKindeTestkit {
360
605
  url: string;
@@ -365,6 +610,12 @@ interface RunningKindeTestkit {
365
610
  seed: ResolvedSeed;
366
611
  failures: FailureInjector;
367
612
  webhooks: WebhookDispatcher;
613
+ directory: Directory;
614
+ certificatePath: string | null;
615
+ coverage: CoverageRecorder;
616
+ activity: ActivityLog;
617
+ /** Replaces the seed while the issuer runs. reset() returns to the new seed. */
618
+ loadSeed(seed: TestkitSeed): void;
368
619
  reset(): void;
369
620
  close(): Promise<void>;
370
621
  }
@@ -378,6 +629,19 @@ declare class TestkitError extends Error {
378
629
  toString(): string;
379
630
  }
380
631
 
632
+ interface LocalCertificate {
633
+ cert: string;
634
+ key: string;
635
+ certPath: string;
636
+ keyPath: string;
637
+ created: boolean;
638
+ }
639
+ declare function ensureLocalCertificate(directory?: string): LocalCertificate;
640
+ declare function createLocalCertificate(): {
641
+ cert: string;
642
+ key: string;
643
+ };
644
+
381
645
  type CheckStatus = "pass" | "warn" | "fail";
382
646
  interface Check {
383
647
  name: string;
@@ -406,4 +670,64 @@ declare function runDoctor(options: {
406
670
  }): Promise<DoctorReport>;
407
671
  declare function parseEnvFile(text: string): Record<string, string>;
408
672
 
409
- export { type ActiveFailure, type AuthenticatedScenario, BILLING_EVENT_TYPES, type Check, type CheckStatus, type CreateKindeOrganizationOptions, type CreateKindeUserOptions, type CreateMembershipOptions, DEFAULT_AUTH_METHODS, DEFAULT_CLIENT_ID, DEFAULT_ISSUER, DEFAULT_M2M_CLIENT_ID, DEFAULT_SCOPES, type DoctorReport, type Duration, FailureInjector, type FailureRule, INVALID_TOKEN_KINDS, type IdTokenOptions, type InvalidTokenKind, type KindeApplication, type KindeMembership, type KindeOrganization, type KindePrincipal, type KindeRole, KindeTestkit, type KindeTestkitOptions, type KindeTokenOptions, type KindeUser, type M2MTokenOptions, type ResolvedSeed, type RunningKindeTestkit, type Scenario, ScenarioBuilder, type ScenarioTokenOverrides, type SendWebhookOptions, type StartKindeTestkitOptions, TestkitError, type TestkitErrorCode, type TestkitSeed, type TokenInspection, type UnauthenticatedScenario, WEBHOOK_EVENT_TYPES, type WebhookAttempt, type WebhookDelivery, WebhookDispatcher, type WebhookEndpoint, type WebhookEndpointInput, type WebhookInvalidKind, type WebhookOptions, type WebhookSource, createKindeOrganization, createKindeToken, createKindeUser, createMembership, getDefaultTestkit, inspectToken, isAuthenticated, parseEnvFile, principalFromClaims, resetFactories, resolveSeed, runDoctor, scenario, seedScenario, startKindeTestkit, toKindeRole };
673
+ interface KindeTestAuth {
674
+ token: string | null;
675
+ headers: Record<string, string>;
676
+ principal: KindePrincipal | null;
677
+ request: {
678
+ headers: Record<string, string>;
679
+ };
680
+ }
681
+ declare function kindeTest(options: {
682
+ scenario: Scenario;
683
+ testkit?: KindeTestkit;
684
+ token?: ScenarioTokenOverrides;
685
+ }): Promise<KindeTestAuth>;
686
+ interface KindeTestkitHandle {
687
+ readonly url: string;
688
+ readonly issuer: string;
689
+ readonly jwksUri: string;
690
+ readonly testkit: KindeTestkit;
691
+ readonly failures: FailureInjector;
692
+ readonly webhooks: WebhookDispatcher;
693
+ readonly directory: Directory;
694
+ readonly coverage: CoverageRecorder;
695
+ readonly activity: ActivityLog;
696
+ readonly certificatePath: string | null;
697
+ auth(scenario: Scenario, token?: ScenarioTokenOverrides): Promise<KindeTestAuth>;
698
+ loadSeed(seed: TestkitSeed): void;
699
+ reset(): void;
700
+ }
701
+
702
+ /** Files `kinde-testkit start` looks for, in this order, when no --seed is given. */
703
+ declare const DEFAULT_SEED_FILES: string[];
704
+ declare function findSeedFile(directory?: string): string | undefined;
705
+ /**
706
+ * Reads a seed from JSON, YAML, or a JavaScript or TypeScript module.
707
+ * A module exports the seed as its default export or as `seed`.
708
+ * TypeScript files need a Node version that runs TypeScript (22.18 or later).
709
+ */
710
+ declare function loadSeedFile(path: string): Promise<TestkitSeed>;
711
+
712
+ /**
713
+ * Steps for signing in through the testkit with plain HTTP requests instead of a browser page.
714
+ * The Cypress commands use these. No Node APIs here, because Cypress bundles this file for the browser.
715
+ */
716
+ interface RequestSignInOptions {
717
+ /** Email address or ID of the user. */
718
+ user: string;
719
+ /** Active organization, for users in more than one. */
720
+ org?: string;
721
+ }
722
+ /** The app's login route, with the hints the testkit sign-in page reads. */
723
+ declare function appLoginUrl(loginPath: string, options: RequestSignInOptions): string;
724
+ /** Reads the hidden request field from the testkit sign-in page. */
725
+ declare function readSignInRequest(html: string): string;
726
+ /** The form the sign-in page posts to /oauth2/auth/login. */
727
+ declare function signInForm(request: string, options: RequestSignInOptions): Record<string, string>;
728
+ /** Explains why the testkit did not redirect back to the app after the form was posted. */
729
+ declare function signInFailure(status: number, html: string, options: RequestSignInOptions): Error;
730
+ /** Resolves a Location header, which can be relative, against the URL that sent it. */
731
+ declare function resolveLocation(location: string, from: string): string;
732
+
733
+ export { type ActiveFailure, ActivityLog, type AuthenticatedScenario, BILLING_EVENT_TYPES, COVERAGE_GROUPS, type Check, type CheckStatus, type CoverageGroup, type CoverageGroupResult, type CoverageItem, CoverageRecorder, type CoverageReport, type CoverageSnapshot, type CreateKindeOrganizationOptions, type CreateKindeUserOptions, type CreateMembershipOptions, DEFAULT_AUTH_METHODS, DEFAULT_CLIENT_ID, DEFAULT_COVERAGE_DIRECTORY, DEFAULT_ISSUER, DEFAULT_M2M_CLIENT_ID, DEFAULT_SCOPES, DEFAULT_SEED_FILES, Directory, type DoctorReport, type Duration, FailureInjector, type FailureRule, INVALID_TOKEN_KINDS, type IdTokenOptions, type InvalidTokenKind, type KindeApplication, type KindeMembership, type KindeOrganization, type KindePrincipal, type KindeRole, type KindeTestAuth, KindeTestkit, type KindeTestkitHandle, type KindeTestkitOptions, type KindeTokenOptions, type KindeUser, type LocalCertificate, type M2MTokenOptions, type RequestEntry, type RequestSignInOptions, type ResolvedSeed, type RunningKindeTestkit, type Scenario, ScenarioBuilder, type ScenarioTokenOverrides, type SendWebhookOptions, type StartKindeTestkitOptions, TestkitError, type TestkitErrorCode, type TestkitSeed, type TokenEntry, type TokenInspection, type TokenObserver, type UnauthenticatedScenario, WEBHOOK_EVENT_TYPES, type WebhookAttempt, type WebhookDelivery, WebhookDispatcher, type WebhookEndpoint, type WebhookEndpointInput, type WebhookInvalidKind, type WebhookOptions, type WebhookSource, appLoginUrl, buildReport, clearCoverageDirectory, createKindeOrganization, createKindeToken, createKindeUser, createLocalCertificate, createMembership, ensureLocalCertificate, findSeedFile, formatCoverageReport, getDefaultTestkit, inspectToken, isAuthenticated, kindeTest, loadSeedFile, mergeSnapshots, parseEnvFile, principalFromClaims, readCoverageDirectory, readSignInRequest, resetFactories, resolveLocation, resolveSeed, runDoctor, scenario, seedScenario, signInFailure, signInForm, startKindeTestkit, toKindeRole };