feat(clerk-js, types): Add clientTrustState and untrustedFirstFactors… (#7096)

Co-authored-by: Tom Milewski <me@tm.codes>

Author: chriscanin

.changeset/client-trust-state.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+---
+
+Adds `client_trust_state` field to Client and SignIn resources to support new fraud protection feature.

packages/clerk-js/src/core/resources/Client.ts

@@ -3,6 +3,7 @@ import type {
   ClientJSON,
   ClientJSONSnapshot,
   ClientResource,
+  ClientTrustState,
   LastAuthenticationStrategy,
   SignedInSessionResource,
   SignInResource,
@@ -26,6 +27,7 @@ export class Client extends BaseResource implements ClientResource {
   cookieExpiresAt: Date | null = null;
   /** Last authentication strategy used by this client; `null` when unknown/disabled. */
   lastAuthenticationStrategy: LastAuthenticationStrategy | null = null;
+  clientTrustState?: ClientTrustState = undefined;
   createdAt: Date | null = null;
   updatedAt: Date | null = null;
 
@@ -86,6 +88,7 @@ export class Client extends BaseResource implements ClientResource {
       this.signIn = new SignIn(null);
       this.lastActiveSessionId = null;
       this.lastAuthenticationStrategy = null;
+      this.clientTrustState = undefined;
       this.cookieExpiresAt = null;
       this.createdAt = null;
       this.updatedAt = null;
@@ -135,6 +138,7 @@ export class Client extends BaseResource implements ClientResource {
       this.captchaBypass = data.captcha_bypass || false;
       this.cookieExpiresAt = data.cookie_expires_at ? unixEpochToDate(data.cookie_expires_at) : null;
       this.lastAuthenticationStrategy = data.last_authentication_strategy || null;
+      this.clientTrustState = data.client_trust_state;
       this.createdAt = unixEpochToDate(data.created_at || undefined);
       this.updatedAt = unixEpochToDate(data.updated_at || undefined);
     }
@@ -153,6 +157,7 @@ export class Client extends BaseResource implements ClientResource {
       captcha_bypass: this.captchaBypass,
       cookie_expires_at: this.cookieExpiresAt ? this.cookieExpiresAt.getTime() : null,
       last_authentication_strategy: this.lastAuthenticationStrategy ?? null,
+      ...(this.clientTrustState && { client_trust_state: this.clientTrustState }),
       created_at: this.createdAt?.getTime() ?? null,
       updated_at: this.updatedAt?.getTime() ?? null,
     };

packages/shared/src/types/client.ts

@@ -1,4 +1,4 @@
-import type { LastAuthenticationStrategy } from './json';
+import type { ClientTrustState, LastAuthenticationStrategy } from './json';
 import type { ClerkResource } from './resource';
 import type { ActiveSessionResource, SessionResource, SignedInSessionResource } from './session';
 import type { SignInResource } from './signIn';
@@ -20,6 +20,7 @@ export interface ClientResource extends ClerkResource {
   lastActiveSessionId: string | null;
   /** Last authentication strategy used by this client; `null` when unknown or feature disabled. */
   lastAuthenticationStrategy: LastAuthenticationStrategy | null;
+  clientTrustState?: ClientTrustState;
   captchaBypass: boolean;
   cookieExpiresAt: Date | null;
   createdAt: Date | null;

packages/shared/src/types/json.ts

@@ -102,6 +102,8 @@ export type LastAuthenticationStrategy =
   | OAuthStrategy
   | Web3Strategy;
 
+export type ClientTrustState = 'new' | 'known' | 'pending';
+
 export interface ClientJSON extends ClerkResourceJSON {
   object: 'client';
   id: string;
@@ -111,6 +113,7 @@ export interface ClientJSON extends ClerkResourceJSON {
   captcha_bypass?: boolean; // this is used by the @clerk/testing package
   last_active_session_id: string | null;
   last_authentication_strategy: LastAuthenticationStrategy | null;
+  client_trust_state?: ClientTrustState;
   cookie_expires_at: number | null;
   created_at: number;
   updated_at: number;